专注于 Infra 层的 AI Agent 技能平台——龙蜥社区 SkillHub 已收到数百个技能，当前陆续上线中。我们每周也会收到一些技能的最佳实践分享，本期给大家推荐的是唐疑豪贡献的《Agent 工具契约漂移检查（tool-contract-drift-checker）》 Skill，他拥有多年软件开发经验，做过全栈开发、运维、RPA 和 AI 应用，也负责团队管理和项目交付，具备全栈开发和运维能力。目前主要从事 RPA 与 AI 应用落地，并作为项目经理负责团队管理和项目交付，希望通过龙蜥社区分享一线实践，帮助更多开发者高效解决实际问题。以下是他的实战分享：
这次参加龙蜥社区 Skill 最佳实践，我做了一个 tool-contract-drift-checker。它比较已发布契约、新版契约和旧调用样例，提前发现会让旧调用失效的变化。
tool-contract-drift-checker Skill 已在 3 套环境中完成 93 项次测试。面对故意做坏的候选契约，它找出 9 项破坏性变化，拦下 2 个旧调用，并用退出码 2 告诉 CI 是否放行。原因很直接：Agent 工具升级时，一个字段从可选变成必填，一个枚举值被删除。未传新字段或还在使用旧枚举值的调用会失败。
这种问题不能靠“运行一次没报错”来判断。为了把风险查清，我把两版契约、旧调用样例和单元测试放在一起比较。
2026 年 7 月，我在两套龙蜥环境完成参赛包验证。7 月底，我又在 Windows 上复跑了一次。两次验证让我确认：工具能启动，不代表升级后仍然兼容。
一行 JSON，也可能让旧调用失效
旧版本只要求调用方传 query：
{ "required": ["query"] }
新版本增加了一个必填字段 tenant：
{ "required": ["query","tenant"] }
新版只是多了一个必填字段 tenant，旧调用方却不会主动补上，原本成功的请求会直接变成非法请求。
这就是契约漂移：即使工具名称和调用入口不变，允许接收和返回的数据规则也会变化。
JSONSchema 可以理解成“工具参数和返回值的规则表”。MCP，也就是模型上下文协议，会用 inputSchema告诉大模型需要哪些参数；如果工具提供outputSchema，还能说明结构化返回值。
把检查做成发布门禁
按照龙蜥 SkillHub 指南，Skill 是让 Agent 解决特定问题的知识包。tool-contract-drift-checker Skill 包含 5 部分：
- SKILL.md 负责告诉 Agent 什么时候触发、按什么流程检查。
- Python 脚本负责做确定性比较，不让模型凭感觉判断。
- 示例文件提供兼容和不兼容的两组工具定义。
- Fixtures，也就是固定调用样例，用来回放旧请求。
- 单元测试负责验证规则、退出码和报告稳定性。
使用时，输入是两份文件：
1.基线契约：当前已经发布、旧调用方正在使用的版本。
2.候选契约：准备上线的新版本。
它支持两类常见结构：MCP tools[] 、OpenAI function tools，也就是函数工具定义。它只读取本地 JSON，不连接真实 MCP Server，也不执行工具调用。OpenAI function tools 只检查输入契约；MCP tools[] 只有提供 outputSchema 时才检查输出契约。
兼容性要看变化方向
工具契约不能只看“字段有没有变化”，还要看变化后旧调用能不能继续工作。我把判断规则压成了两句话：输入可以放宽，不能收窄；输出可以收紧，不能放宽。
输入像一扇门。旧版本允许进来的人，新版本也必须放行。所以，新增必填字段、删除枚举值、提高最小长度、禁止额外字段，都可能破坏旧调用。
输出像一份承诺。旧版本承诺一定返回的字段，新版本不能突然取消；对严格按旧 Schema 解析输出的调用方来说，旧版本只承诺返回字符串，新版本也不能突然多返回一种无法处理的类型。
这两个方向正好相反。如果只做普通文本差异对比，很容易把真正危险的变化漏掉。
报告要能直接定位问题
这部分是我认为对读者最有复用价值的 —— 怎么把散落的经验变成 Agent 能执行的指令。
报告按 3 个级别输出，并记录工具名、字段路径、规则编号、原因和修复动作：
级别 |
含义 |
发布动作 |
breaking |
已确认会破坏旧调用 |
阻止候选版本发布 |
warning |
无法可靠自动判断 |
人工复核 |
info |
兼容变化或普通提示 |
记录后继续 |
例如，发现新增必填字段时，报告不会只写“Schema 不兼容”，而是直接指向：
/tools/search-docs/inputSchema/required/tenant
随后给出处理建议：把字段改为可选，或者发布新版本并保留迁移窗口。
它还把结果映射成退出码，方便接入 CI，也就是代码提交后的自动检查流程：
退出码 |
含义 |
0 |
只有兼容变化或提示 |
1 |
存在人工复核项 |
2 |
存在破坏性变化 |
3 |
输入文件无效 |
4 |
命令用法错误 |
龙蜥环境实测结果
2026 年 7 月 28 日的参赛包验证记录覆盖了 Anolis OS 8.6 和 23.4。验证脚本只使用 Python 标准库。2026 年 7 月 31 日，我又从参赛提交版本在 Windows 上复跑了一次。
环境 |
Python |
测试结果 |
证据来源 |
Anolis OS 8.6 |
3.6.8 |
31 项全部通过 |
参赛包验证记录 |
Anolis OS 23.4 |
3.11.6 |
31 项全部通过 |
参赛包验证记录 |
Windows 本地复跑 |
3.13.5 |
31 项全部通过 |
本次复跑输出 |
进入已安装 Python 的 Anolis OS 环境后，在 Skill 包根目录执行：
python3 -m unittest discover -s tests -v
Windows 本地复跑使用：
py -3 -m unittest discover -s tests -v
我又回放了一组故意做坏的候选契约，结果如下：
状态：breaking 破坏性变化：9 人工复核项：0 兼容提示：1 Fixtures:0通过／ 2 失败／ 0 跳过 退出码：2
Fixtures：0 通过 / 2 失败是预期结果：两个旧版可用的样例都被新增必填字段、收窄枚举和删除工具拦下，并非测试框架失败。
这些情况仍要人工检查
这个 Skill 不覆盖完整 JSON Schema。
遇到 $ref 、oneOf 、anyOf 、allOf 、pattern 、format 这类复杂关键字时，它只给出 warning ，要求人工复核。
它也不会做下面这些事：
- 不连接真实 MCP Server。
- 不测试鉴权和账号权限。
- 不验证工具背后的业务逻辑。
- 不把静态报告当成线上联调结果。
所以，这份报告只能证明契约层面是否兼容。真实工具调用、鉴权、异常处理和业务结果，仍然要在集成测试里验证。
发布前如何检查？
如果大家要复用这套方法，请记得发布前做 5 步：
1. 保存当前已发布的工具契约，作为基线。
2. 每次升级都生成候选契约，不手工拼版本差异。
3. 先做确定性 Schema 比较，再让 Agent 解释报告。4. 保留一组真实但脱敏的调用样例，持续回放。
5. 把 breaking 接入 CI，阻止旧调用会失败的版本直接发布。
团队每次升级前，只要先回答一个问题：这次修改，会不会让昨天还能工作的调用今天突然失效？答案要来自基线、旧样例和自动检查，不能靠印象。
还想和社区一起补上哪些能力？
工具已经迈出了第一步，但要真正覆盖开发者日常面对的复杂问题，仅靠个人积累的样例还远远不够。当前最需要补充的，不是更多理想化的演示，而是来自真实业务、真实环境和真实调用链路的实践经验。我也希望和社区开发者一起，把以下几块关键拼图逐步补齐。
首先，是对复杂契约规则的支持。后续希望进一步覆盖 $ref、oneOf、anyOf、allOf 等常见但更复杂的定义方式，同时补充经过脱敏处理的历史调用样例，让验证不只停留在结构层面，也能更贴近实际接口的运行状态。
其次，是把验证能力更自然地接入研发流程。我们可以沉淀一批常见的 CI/CD 流水线模板，统一处理退出码识别、测试报告归档、异常提示和发布阻断等环节。开发者不必再为每个项目重复研究接入方式，只需结合自身流程进行少量配置，就能将契约验证纳入持续集成和发布检查。
真实调用中的问题，往往也不只来自契约本身。接口定义完全正确，并不代表请求一定能够成功执行。鉴权信息是否有效、账号权限是否完整、异常是否被正确处理、业务结果是否符合预期，都可能成为调用失败的原因。因此，后续还希望逐步接入鉴权、权限校验、异常处理和业务结果回放等能力，补上“契约正确，但调用仍然失败”的验证盲区。
兼容性同样需要更多真实记录来支撑。不同龙蜥操作系统版本、Python 版本以及硬件环境，都可能带来细微但关键的差异。我们希望持续收集这些环境下的验证结果，将它们整理为可复用的兼容性回归集，为后续版本迭代提供更可靠的参考，也帮助其他开发者更快判断工具能否在自己的环境中稳定运行。
参与共建并不复杂。按照龙蜥社区 SkillHub 官网用户指南，个人开发者可以直接在网站上传 ZIP 文件，也可以向 Gitee 官方仓库提交 PR，或者提交公开仓库地址。你不一定要从头开发一套完整工具：一条经过验证的兼容规则、一组脱敏后的 Fixtures、一份可复用的 CI 模板，甚至一次真实的龙蜥环境验证，都可以整理成 Skill，沉淀为社区可复用的经验。
一个人的场景和样例终究有限，但社区的真实实践可以不断拓宽工具的边界。欢迎大家把使用过程中遇到的问题、踩过的坑和验证过的解决方案留下来。每多沉淀一条经验，后来的人就能少走一段弯路；每多贡献一个 Skill，社区就多一份可以直接复用的能力。期待和大家一起，把这些分散的实践汇聚起来，让工具在更多真实场景中变得更完整、更可靠，也更好用。
相关链接：
Agent 工具契约漂移检查（tool-contract-drift-checker）：
https://skillhub.openanolis.cn/skill/tool-contract-drift-checker
Skillhub 官网链接：
https://skillhub.openanolis.cn
Model Context Protocol：Tools 规范
https://modelcontextprotocol.io/specification/2025-11-25/server/tools
JSON Schema：Object 规则：
https://json-schema.org/understanding-json-schema/reference/object
龙蜥社区 Skill 征集活动——「Skill 创造营」上线以来响应热烈。截至目前，龙蜥 SkillHub 已收到覆盖安全、系统运维、AI 推理、数据库等多个领域，一个面向 Infra 的 AI 技能生态正在加速成型。「Skill 创造营」持续征集中，诚挚欢迎每一位开发者提交你的 Skill 与最佳实践。如果你有感兴趣的方向或者关于 SkillHub 的问题，欢迎通过下方链接反馈给我们。
SkillHub 用户需求收集链接：
https://alidocs.dingtalk.com/notable/share/form/v014jKqm0b74KdjLnw1_f22ghuX_M7AJs3D
