阶段 5 讲义 — 工具契约、MCP 与 Skills

阶段 5 讲义 — 工具契约、MCP 与 Skills

本阶段的核心命题 工具面决定产品上限。 模型再强，也只能在你给它的能力集合里行动；能力集合的粒度、命名、返回值和错误语义，直接决定了它能不能把任务做对。

这一阶段的产出，是产品经理最容易展现独特价值的地方——工具契约是产品定义，不是研发实现细节。

一、工具契约的六个要素

一个工具不是"一个 API"，是一份给模型看的契约：

描述写不清楚 = 工具不存在 模型选工具靠的就是名称和描述。一个功能正确但描述含糊的工具，表现等同于没有这个工具——甚至更糟，因为它会在错误的场景被选中。Anthropic 在 Writing effective tools for AI agents 里给出的结论正是这一条：好工具是被刻意、清晰地定义出来的，且要节制地使用 Agent 的上下文。

关于"何时不用"

大多数工具描述只写"能做什么"，不写"不该用它做什么"。补上后一句，选错工具的概率会明显下降。例如：

get_published_fare：查询指定 OD + 日期的公布运价（航司对外发布的价目）。 不要用它查客户端在售价格——在售价格受渠道、库存、加价策略影响，与公布运价不同，请用 search_client_price。

二、工具粒度：三个层次与一条判据

判据：看这一步失败时，模型能不能自己修。

• 如果模型拿到错误后有能力自行调整参数重试 → 粒度合适
• 如果失败原因来自它看不见的内部编排 → 粒度太粗
• 如果模型要连调 5 次才能拿到一个业务上完整的结果 → 粒度太细

产品经理的默认起点 从业务动作级开始，只在实测发现"模型需要更细的控制"时才下沉，或"模型总是编排错"时才上浮。直接把内部微服务一比一暴露成工具，是最常见也最贵的错误——它把内部架构的复杂度全部转嫁给了模型。

三、返回值：给多少信息才对

这是最容易被忽略、但对成本和正确率影响最大的一项。

三条规则：

1. 只返回决策需要的字段。一个航班列表返回 60 个字段，模型只用 5 个，其余 55 个在每一步都占着上下文并稀释注意力。
2. 分页与摘要要显式。返回 200 条结果时，应当给"共 200 条，这里是前 20 条，可用 offset 继续"，而不是截断了不说。
3. 给出可继续的句柄。返回 ID/游标，让模型可以按需取详情——这就是阶段 3 的 Write + Select：把大块内容留在上下文之外，需要时再取。

反面案例的识别方法：统计每个工具单次返回的平均 token 数。超过一两千 token 的只读工具，基本都有精简空间。

四、并行、依赖、幂等、超时

超时是最阴险的一类错误 "占座请求超时"意味着可能占了也可能没占。如果 Agent 直接重试，用户可能被占两个座；如果直接放弃，可能白白占了一个座不释放。正确设计：超时后先查询状态再决定，且这条逻辑要写在工具契约里，不能指望模型自己想到。

五、从 Tool Use 到真正执行：Harness 中间还有一条治理链

模型产生 tool_use 后，不应直接调用业务函数。生产级执行链至少要区分：

Schema 校验
→ 业务输入校验
→ Hook / 策略检查与参数改写
→ 权限决策
→ 沙箱或执行环境
→ 工具执行
→ 结果转换
→ 后置 Hook
→ 上下文回填与轨迹打点

三个关键判断：

1. 先验证调用是否成立，再请求权限：不要为一个 Schema 都不合法的调用弹确认框。
2. 风险属性经常取决于本次输入：同一个 Shell 工具执行 ls 和删除命令，是否只读、破坏性、可并发完全不同。因此需要 is_read_only(input)、is_destructive(input)、is_concurrency_safe(input) 这类按调用判定。
3. 执行输入与观察输入要分开：真正执行和写入 Transcript 的输入可以保留模型原文；给 Hook、审计和 UI 的输入可补绝对路径、风险标签等派生字段，但必须明确哪个版本是权威值。

每一道关都要单独可观察 最终只记录“工具失败”不够。要能区分参数校验、权限拒绝、Hook 阻塞、Sandbox 失败、业务错误和结果转换失败，并挂回父 Agent / Subagent 的调用链。

完整案例见 Claude Code：工具执行链。教程中的精确关卡数量是特定快照事实，不是需要背诵的行业标准。

六、MCP：接线标准，不是价值本身

它解决什么

MCP（Model Context Protocol）定义了 Agent 客户端与外部能力服务端之间的通信协议：

价值在于多对多变成一对多：N 个 Agent 客户端 × M 个能力提供方，从 N×M 的适配工作量降到 N+M。

2026-07-28 版本：这是一次大改

截至 2026-08，MCP 的当前规范版本是 2026-07-28，官方称之为发布以来最大的一次修订。产品经理需要知道的几条：

落地前请核对官方规范原文 上表来自 2026-07-28 规范发布公告与随后的路线图公告。部分特性的弃用状态（如 Roots / Sampling / Logging）在二手报道中说法不一，涉及改造决策时请以 modelcontextprotocol.io 的规范页 与官方博客为准。本讲义写作时间 2026-08-25。

MCP Instructions 也是上下文与供应链风险面

MCP Server 不只提供 Tools，也可能提供会改变模型行为的 Instructions。产品设计要把它当作外部输入处理：

• 标注来源与信任等级；
• 明确项目级、用户级和管理端配置的边界；
• Server 断线或能力列表变化时做增量公告；
• 不让不可信 Instructions 绕过权限、Sandbox 和系统策略；
• 规范支持的能力与某个 Host 已实现的能力分开核对。

Claude Code 的实现案例见 Claude Code：扩展面。

MCP 与 API / Plugin / Skill 的关系

产品判断：MCP 不是壁垒 接得上 20 个 MCP Server 不等于产品变强。协议是降低接入成本的公共品——一旦成为公共品，它就不再是差异化来源。真正的壁垒在：工具背后的独家数据与业务闭环、工具契约的质量、以及围绕它的评测与治理。

这一判断在 2026 年更明确了：A2A 于 2026-08-17 转入 Linux Foundation 旗下的 Agentic AI Foundation，与 MCP 一起走向中立治理。协议正在变成基础设施，而基础设施不给任何人护城河。

七、Skills：渐进式披露

Skill 解决的问题和 Tool 不同：Tool 提供"能做什么"，Skill 提供"该怎么做"。

Anthropic 的 Agent Skills 用三级渐进式披露组织内容：

这套结构的产品意义：让"知识很多"和"上下文很贵"这两件事同时成立。

写好一个 Skill 的四条

1. description 是触发器。它决定 Skill 会不会在该用的时候被用上、会不会在不该用的时候被误用。写清楚触发词与场景。
2. 从评测出发，而不是从整理出发。官方建议很直接：先跑代表性任务，观察 Agent 在哪里卡住，再针对性地补 Skill；不要一上来就把手册全搬进去。
3. 拆分而不是堆砌。正文变长就拆到附件；互斥或很少同时用到的路径要分开放，能显著省 token。
4. 验证正确触发与错误触发。只测"该用时用了"是不够的，还要测"不该用时没用"。

本仓自己就是这套方法的实践场：.claude/skills/ 有 35+ 个 Skill，其 name / description 强制保持英文，是本仓为索引与触发匹配制定的约定，不是 Claude Code 官方要求所有 Skill 元数据必须使用英文。

Skill 元数据也可以承载运行语义 Claude Code 的案例表明，Skill 元数据不只用于触发，还可能决定模型、推理强度、执行 Agent、上下文隔离、工具白名单、路径触发和自带 Hook。基础教程不要求记具体字段，但产品方案必须回答：这个 Skill 在什么上下文、以什么权限、由谁执行、过程是否回流主会话。

完整案例见 Claude Code：Skills / Plugins / MCP / Commands。

第五条：技能规模化之后是治理问题，不是写作问题 OWASP 为技能生态单列了一份 Agentic Skills Top 10（AST01–AST10），其中 AST09「无治理」 描述的场景很具体：技能被个人随手安装，组织既没有清单、没有审批流程，也没有审计轨迹，安全团队完全没有可见性。

这条对本仓直接适用——35+ 个 Skill 已经越过了"随手写几个"的规模。阶段 5 实践里创建 Skill 时，顺手回答三个问题：谁能装、装了谁知道、能不能查到它做过什么。注意 AST 与 ASI（阶段 11 的 Agentic 应用十大风险）是两份独立清单，编号别混。

八、工具太多怎么办：Tool Search 与动态加载

当工具数量增长到几十个，工具定义本身就成了上下文负担——这是"工具面也要做上下文工程"的直接体现。

三种解法：

本仓已有资料 Tool Search 与 Codex：注册、路由与延迟加载 讲的是同一个问题的两种实现。

九、常见误区清单

十、外部一手资料（阶段 5 精读，约 6 小时）

本仓已有资料：

• Pi：工具系统
• dsh：五段流水线与两种呈现
• Codex：注册、路由与延迟加载
• dsh：技能与扩展点
• Claude Code 如何使用 Skills
• Tool Search
• Claude Code：工具能力与延迟加载
• Claude Code：工具执行链
• Claude Code：扩展面

Related Documents

• 阶段 5 实践：15 个 MCP 工具的粒度重审
• 阶段 4 讲义
• 阶段 11 讲义：安全
• 学习路线