工具集成模式

Ai2 的 Shippy 有一条反直觉的做法：模型不直接拼裸 API 调用，而是通过一层专门构建的确定性 CLI 与后端交互。分页错误、畸形查询这类隐蔽 bug 在工具层就被消化掉，而且每一层可以独立测试。

这句话是这项技能的全部要义。工具层不是 API 的薄包装，它是一层要被设计的产品——它的职责是吸收混乱，而不是把混乱转发给模型。

工具层要吸收混乱

一个直接暴露给模型的原始接口，会把它所有的边角情况一起暴露出去：翻页、超时、部分成功、字段可空、错误码语义不一致。模型对这些的处理方式是即兴发挥，而且每次都不一样。

判断一个工具封装得够不够，有个实用的检查：把它的返回值单独拿出来看，能不能不依赖上下文就读懂发生了什么。 如果读不懂，模型也读不懂。

• 成功和失败要在结构上可区分，而不是靠文字措辞。
• 部分成功要显式表达，不能悄悄返回半截数据。
• 需要重试的错误和不该重试的错误要分开，否则模型只会一律重试。

边界要窄到可以被审计

MCP 在 2025 年一度被 Skills 盖过热度，原因很直白：一个能用终端和 curl 的智能体外壳，用更灵活的方式做到了大部分同样的事。而现在重新看 MCP 的理由不是协议变强了，是那条替代路线的代价看清楚了——给智能体一个能上网的 shell 风险很大，而且需要足够强的模型才驱动得动。

相比之下，一件职责明确的工具更容易审计和管控，简单到笔记本上跑的小模型也能驱动。所以工具的边界宽窄不只是工程整洁问题，它同时决定了两件事：出事之后你能不能查清楚，以及这套系统能不能用小模型跑。

无状态让工具目录可以被缓存和路由

MCP 2.0 把协议核心从有状态改成了无状态，几处改动直接影响工具怎么接：

1. 握手和会话 id 退休，每个请求自带协议版本与能力——任何请求都能落到负载均衡后的任意实例，不需要实例间共享存储。
2. 方法名与工具名走 HTTP 头（Mcp-Method、Mcp-Name），网关不必解请求体就能做路由和鉴权。
3. 列表响应可缓存且顺序确定，客户端可以缓存工具目录，重连之后上游的提示缓存也不会失效。
4. 弃用有了至少 12 个月的正式窗口，升级可以排期而不是被动响应。

第 4 条最容易被忽略，却最影响长期维护成本：一个没有弃用窗口的工具接口，意味着你的集成随时可能在某个周二早上失效。

接进来之后，谁负责失败

工具接入的最后一步是让失败可归因。任务失败时至少要分得出三类：模型选错了工具、工具自己执行失败、环境异常。三者的修复动作完全不同，混成一句「重试」就等于放弃了这条信息。

与相邻条目的分工

这一条管单个工具怎么接得可维护；整条链路怎么分层与交接，是「智能体工作流设计」。工具返回内容可能携带注入，那是「智能体安全与提示注入防御」。概念层面「为什么要把推理与行动分开」在「工具使用与函数调用」，而「稳定的输入输出约定为什么能提升可靠性」在「API 契约与接口边界」。