简介:很多开发者选桌面Agent时,最先困惑的是两类方案的架构差异、Skills的作用和部署位置。本文给出可核验的判断标准,讲清Skills的职责边界和SKILL.md的编写要点,对比本地与云端部署的适用场景,并附上十项迁移前验收清单,帮助你在上线前发现权限、密钥和数据外发等风险。
开发者选桌面Agent时,通常会问三件事:两类方案的底层结构有什么不同,Skills机制承担什么职责,本地部署还是云端部署更合适。这三个问题彼此相关。结构决定扩展方式,Skills决定任务流程怎么走,部署位置则决定数据和权限的边界。
本文的判断基于公开文档的描述,并给出可以逐项核验的标准。文中的两款工具分别称为方案A和方案B。它们的版本迭代较快,插件生态、配置项和依赖关系都可能变化。因此本文的结论只能作为选型起点。正式决策前,请以官方仓库、官方文档和自己的实测结果为准,并记录所用的版本号和查阅日期。
两类方案的分层基本一致。理解这三层,才能看清后续的差异。
| 层级 | 组成 | 职责 | 主要风险 |
|---|---|---|---|
| 第一层 | 基础模型加提示词 | 理解问题,给出回答 | 只能回答,不能操作外部环境 |
| 第二层 | 基础模型加Tools | 读写文件、执行代码、调用外部组件 | 文件读写范围过大,命令执行无白名单,密钥或环境变量泄露 |
| 第三层 | Agent加Skills | 规定任务步骤:先调用什么工具,先读哪个文件,先做什么后做什么 | 步骤写得过简,模型容易跳步或误判 |
第三层位于第二层之上。Skill负责编排流程,它调用的仍是第二层的工具能力。Skill本身不提供新的执行权限。
Agent Skill是一份指导Agent完成某类任务的说明文件,通常包括用途描述、执行步骤,以及必要的脚本和参考资料。社区常见的写法是目录式结构,核心文件是SKILL.md。规范的名称、版本和维护方,需要到对应项目的文档中核对。
Skill的职责是把任务拆成可执行的步骤。它可以告诉模型:遇到哪类请求时启用该Skill,先读取哪份配置,再运行哪个脚本,最后输出什么格式的结果。
Skill不是权限沙箱。Skill中的脚本运行时,仍受宿主工具的权限约束。文件读写范围、命令执行白名单和环境变量访问,都要在工具层设置。即使Skill的文字说明写着“只读取数据”,工具层也必须真正限制读取范围,否则脚本仍可能访问其他路径。
典型的目录结构如下:
my-skill/├── SKILL.md # 必需:用途说明与执行步骤├── scripts/ # 可选:可执行脚本├── references/ # 可选:参考文档└── assets/ # 可选:模板与资源
写SKILL.md时,建议包含以下内容。
下面是一个简化示例:
# 用途将 data/sales.csv 中的销售记录汇总为按月统计表。# 触发条件用户请求“月度汇总”或“按月统计销售”时启用。# 输入- data/sales.csv,必须包含 date(YYYY-MM-DD)与 amount(数字)两列。# 步骤1. 读取 data/sales.csv 第一行,确认包含 date 与 amount 两列,否则停止并报告缺失的列。2. 运行 scripts/summarize.py,参数为输入文件路径。3. 检查 output/monthly.csv 是否生成,且行数大于0。# 依赖- Python 3.11 或以上版本- pandas 2.x# 权限- 允许读取 data/,允许写入 output/。- 禁止访问 data/ 和 output/ 以外的路径,禁止联网。# 失败处理若第3步失败,删除 output/ 中本次生成的文件,并保留日志 logs/summarize.log。# 测试样例输入:包含三条记录的测试文件。期望输出:两行月度汇总。
目录结构和文档格式相同,并不代表迁移成本低。只有当scripts没有专有依赖,且运行时版本一致时,迁移成本才相对较低。
下表列出选型时需要核对的维度。表中内容多为待核验项,请在自己的环境中填写实际结果。
| 维度 | 需要核对的问题 | 核验来源 |
|---|---|---|
| 决策模型 | 支持哪些模型服务,能否切换为本地模型 | 官方配置文档 |
| 工具调用 | 内置哪些工具,工具权限如何设置 | 工具定义与配置项 |
| Skills目录规范 | 是否采用SKILL.md目录结构,是否支持自定义Skill | 官方仓库示例 |
| 扩展粒度 | 能否单独替换记忆、提示词或消息通道模块 | 模块划分文档 |
| 消息通道 | 支持哪些接入渠道,鉴权方式是什么 | 通道配置文档 |
| 部署方式 | 支持本地部署、云端部署,还是两者都支持 | 部署指南 |
| 权限模型 | 文件、网络和命令执行的默认权限是什么 | 安全说明与源码 |
| 生态 | 社区Skill数量,维护活跃度,版本发布频率 | 仓库提交记录与发布说明 |
两款工具的核心概念相似,都以大模型做决策,以工具调用执行动作,以Skills规定流程。但它们是否基于同一底层框架,需要检查两边的依赖清单。在确认之前,不应把底层框架的同源关系当作结论。
选型时可以先看结论,再看原因。若团队有能力维护自定义模块,并且需要深度定制,可以优先考虑模块化程度更高的方案。若团队人力有限,希望尽快投入使用,可以优先考虑生态成熟、Skill资源丰富的方案。判断时应同时考虑团队的开发能力、维护成本和生态成熟度,不宜只看单一因素。
部署位置决定了数据、网络和权限的边界。
本地部署适合以下场景:处理内部文档或源代码,数据不能离开内网;需要直接访问本机文件或本地数据库;对延迟敏感,希望减少网络往返。它的主要成本在于硬件、模型推理资源和日常运维。升级、补丁和密钥轮换都要由团队自己完成。
云端部署适合以下场景:团队成员分布在多个地点,需要统一入口;希望由服务商承担基础设施运维;对本机资源占用敏感。它的主要风险是数据外发。需要确认哪些内容会被上传,保存多久,是否用于模型训练,以及跨境传输是否符合所在地的合规要求。
无论选哪种方式,都要检查三项。第一,Agent能访问的文件目录是否已经最小化。第二,API密钥和令牌是否存放在环境变量或密钥管理服务中,而不是写入Skill或配置文件。第三,日志是否会记录敏感内容,日志的保存期限是否符合要求。
在把Skill迁移到新工具或新环境之前,建议逐项完成以下检查。每一项都应有明确的通过标准。