桌面Agent选型:Skills与部署验收清单

作者:热心市民鹿先生2026.11.16 10:32浏览量:0

简介:很多开发者选桌面Agent时,最先困惑的是两类方案的架构差异、Skills的作用和部署位置。本文给出可核验的判断标准,讲清Skills的职责边界和SKILL.md的编写要点,对比本地与云端部署的适用场景,并附上十项迁移前验收清单,帮助你在上线前发现权限、密钥和数据外发等风险。

一、选型前要回答的三个问题

开发者选桌面Agent时,通常会问三件事:两类方案的底层结构有什么不同,Skills机制承担什么职责,本地部署还是云端部署更合适。这三个问题彼此相关。结构决定扩展方式,Skills决定任务流程怎么走,部署位置则决定数据和权限的边界。

本文的判断基于公开文档的描述,并给出可以逐项核验的标准。文中的两款工具分别称为方案A和方案B。它们的版本迭代较快,插件生态、配置项和依赖关系都可能变化。因此本文的结论只能作为选型起点。正式决策前,请以官方仓库、官方文档和自己的实测结果为准,并记录所用的版本号和查阅日期。

二、先统一三层结构

两类方案的分层基本一致。理解这三层,才能看清后续的差异。

层级 组成 职责 主要风险
第一层 基础模型加提示词 理解问题,给出回答 只能回答,不能操作外部环境
第二层 基础模型加Tools 读写文件、执行代码、调用外部组件 文件读写范围过大,命令执行无白名单,密钥或环境变量泄露
第三层 Agent加Skills 规定任务步骤:先调用什么工具,先读哪个文件,先做什么后做什么 步骤写得过简,模型容易跳步或误判

第三层位于第二层之上。Skill负责编排流程,它调用的仍是第二层的工具能力。Skill本身不提供新的执行权限。

三、Skills是什么,它管什么

Agent Skill是一份指导Agent完成某类任务的说明文件,通常包括用途描述、执行步骤,以及必要的脚本和参考资料。社区常见的写法是目录式结构,核心文件是SKILL.md。规范的名称、版本和维护方,需要到对应项目的文档中核对。

Skill的职责是把任务拆成可执行的步骤。它可以告诉模型:遇到哪类请求时启用该Skill,先读取哪份配置,再运行哪个脚本,最后输出什么格式的结果。

Skill不是权限沙箱。Skill中的脚本运行时,仍受宿主工具的权限约束。文件读写范围、命令执行白名单和环境变量访问,都要在工具层设置。即使Skill的文字说明写着“只读取数据”,工具层也必须真正限制读取范围,否则脚本仍可能访问其他路径。

四、SKILL.md怎么写

典型的目录结构如下:

  1. my-skill/
  2. ├── SKILL.md # 必需:用途说明与执行步骤
  3. ├── scripts/ # 可选:可执行脚本
  4. ├── references/ # 可选:参考文档
  5. └── assets/ # 可选:模板与资源

写SKILL.md时,建议包含以下内容。

  1. 触发条件:说明什么样的请求应启用该Skill。
  2. 输入与输出:列出需要的输入字段,以及输出的文件路径或格式。
  3. 可检查的步骤:每一步都写成可以验证的动作,例如“读取data目录下的文件第一行,确认表头包含date与amount两列”。避免“处理一下数据”这类模糊描述。
  4. 依赖环境:写明运行时版本、依赖包及版本号,以及需要的外部工具。
  5. 权限范围:写明允许读写的目录、允许执行的命令,以及禁止访问的路径。
  6. 失败处理:说明某一步失败时如何回滚,哪些中间文件需要清理。
  7. 测试样例:至少给出一组输入和期望输出,用于验证Skill是否按预期运行。

下面是一个简化示例:

  1. # 用途
  2. 将 data/sales.csv 中的销售记录汇总为按月统计表。
  3. # 触发条件
  4. 用户请求“月度汇总”或“按月统计销售”时启用。
  5. # 输入
  6. - data/sales.csv,必须包含 date(YYYY-MM-DD)与 amount(数字)两列。
  7. # 步骤
  8. 1. 读取 data/sales.csv 第一行,确认包含 date 与 amount 两列,否则停止并报告缺失的列。
  9. 2. 运行 scripts/summarize.py,参数为输入文件路径。
  10. 3. 检查 output/monthly.csv 是否生成,且行数大于0。
  11. # 依赖
  12. - Python 3.11 或以上版本
  13. - pandas 2.x
  14. # 权限
  15. - 允许读取 data/,允许写入 output/。
  16. - 禁止访问 data/ 和 output/ 以外的路径,禁止联网。
  17. # 失败处理
  18. 若第3步失败,删除 output/ 中本次生成的文件,并保留日志 logs/summarize.log。
  19. # 测试样例
  20. 输入:包含三条记录的测试文件。期望输出:两行月度汇总。

目录结构和文档格式相同,并不代表迁移成本低。只有当scripts没有专有依赖,且运行时版本一致时,迁移成本才相对较低。

五、两类方案怎么对比

下表列出选型时需要核对的维度。表中内容多为待核验项,请在自己的环境中填写实际结果。

维度 需要核对的问题 核验来源
决策模型 支持哪些模型服务,能否切换为本地模型 官方配置文档
工具调用 内置哪些工具,工具权限如何设置 工具定义与配置项
Skills目录规范 是否采用SKILL.md目录结构,是否支持自定义Skill 官方仓库示例
扩展粒度 能否单独替换记忆、提示词或消息通道模块 模块划分文档
消息通道 支持哪些接入渠道,鉴权方式是什么 通道配置文档
部署方式 支持本地部署、云端部署,还是两者都支持 部署指南
权限模型 文件、网络和命令执行的默认权限是什么 安全说明与源码
生态 社区Skill数量,维护活跃度,版本发布频率 仓库提交记录与发布说明

两款工具的核心概念相似,都以大模型做决策,以工具调用执行动作,以Skills规定流程。但它们是否基于同一底层框架,需要检查两边的依赖清单。在确认之前,不应把底层框架的同源关系当作结论。

选型时可以先看结论,再看原因。若团队有能力维护自定义模块,并且需要深度定制,可以优先考虑模块化程度更高的方案。若团队人力有限,希望尽快投入使用,可以优先考虑生态成熟、Skill资源丰富的方案。判断时应同时考虑团队的开发能力、维护成本和生态成熟度,不宜只看单一因素。

六、本地部署还是云端部署

部署位置决定了数据、网络和权限的边界。

本地部署适合以下场景:处理内部文档或源代码,数据不能离开内网;需要直接访问本机文件或本地数据库;对延迟敏感,希望减少网络往返。它的主要成本在于硬件、模型推理资源和日常运维。升级、补丁和密钥轮换都要由团队自己完成。

云端部署适合以下场景:团队成员分布在多个地点,需要统一入口;希望由服务商承担基础设施运维;对本机资源占用敏感。它的主要风险是数据外发。需要确认哪些内容会被上传,保存多久,是否用于模型训练,以及跨境传输是否符合所在地的合规要求。

无论选哪种方式,都要检查三项。第一,Agent能访问的文件目录是否已经最小化。第二,API密钥和令牌是否存放在环境变量或密钥管理服务中,而不是写入Skill或配置文件。第三,日志是否会记录敏感内容,日志的保存期限是否符合要求。

七、迁移前的验收清单

在把Skill迁移到新工具或新环境之前,建议逐项完成以下检查。每一项都应有明确的通过标准。

  1. 版本记录:记录方案A和方案B的版本号、仓库地址和查阅日期。
  2. 依赖扫描:列出Skill所需的运行时版本与依赖包,在目标环境中逐项安装并验证。
  3. 脚本隔离:在隔离环境中运行scripts,确认其不会访问环境之外的文件或网络。
  4. 权限最小化:工具权限只开放Skill必需的目录与命令。
  5. 密钥检查:扫描Skill目录,确认没有硬编码的密钥、令牌或个