malganiswu/red-bean-nian-gao/make-agent-system-tools

制作 Agent 系统工具

本 Skill 提供系统工具专项工作流，不保存项目契约副本。项目规则以任务路径适用的 AGENTS.md 为准；接口、注册方式和命令以当前源码、权威设计文档与 Makefile 为准。

建立当前上下文

1. 确认仓库根目录，完整读取根 AGENTS.md 和 backend/AGENTS.md，再读取它们按任务范围直接要求的文档。
2. 读取 `docs/design/tool/tool-system.md`，并检查当前 Registry、composition root、默认工具配置和同类工具实现。不要依赖 Skill 中固化的接口签名或文件行号。
3. 如果改动的是 Runtime 内置工具，同时读取同级 Runtime 仓库适用的 AGENTS.md、公开文档和真实接口；遵守产品仓的 Runtime revision 锁定流程。
4. 若规范、设计文档和实现不一致，先明确漂移：AGENTS.md 决定项目规则，当前源码决定可编译接口，权威设计文档应在本次授权范围内同步，而不是由 Skill 覆盖差异。

先判定改动边界

开始实现前区分以下变化，因为它们的接线、风险和验证不同：

• 新增产品工具或修改现有产品工具。
• 新增或修改 Runtime 可选内置工具。
• 仅修改名称、描述或 JSON Schema。
• 改变注册、默认启用范围或 Agent 权限。
• 引入文件、网络、凭证、数据库写入或其他外部副作用。
• 返回普通内容，还是返回中断等结构化控制信号。

默认启用和“工具可被注册”是两个独立决策。权限或安全边界变化按 AGENTS.md 的决策权限处理，不因完成工具实现而自动获得授权。

没有产品依赖不等于应自动放入 Runtime。只有明确需要多宿主复用、符合 Runtime 中性边界且已获得跨仓修改授权时， 才优先考虑 Runtime builtin；否则默认留在产品仓。两种归属都合理且会影响交付边界时，先请用户确认。

设计模型可用的契约

先写工具的调用契约和验收场景，再进入实现。

工具描述

描述应让模型无需阅读实现就能回答四个问题：

1. 工具做什么。
2. 什么情况下应该调用。
3. 成功后返回什么，尤其是可直接消费的字段。
4. 与相似工具相比，什么情况下不应调用。

对有副作用、成本或权限要求的工具，还要明确调用前提。避免只写“执行某操作”之类无法帮助模型选工具的描述。

JSON Schema

• 为每个参数说明使用时机、约束和省略后的行为，而不是重复字段名。
• 明确 required、枚举、长度或数值边界；对象和集合按真实接受范围限制。
• Schema、参数解析和错误文案必须表达同一契约。
• 只修改 Schema 时也要检查已有会话、模型调用与兼容性影响。

测试与实现

按 backend/AGENTS.md 的测试先行规则执行。针对工具行为，至少从以下维度选择与风险相称的场景：

• 成功路径与模型实际会提交的参数形状。
• 缺失、非法、边界和超大输入。
• 下游错误、超时、取消和输出截断。
• 外部副作用的权限、幂等性与敏感信息处理。
• 结构化控制信号及其经真实 dispatcher / pipeline 的传播。
• 注册、未注册和默认启用状态。

对任何外部副作用工具，编码前必须明确目标/出站策略、凭证来源、幂等键、重试语义、审计与脱敏、默认授权范围。 自动测试使用 fake 或本地测试服务；未获用户明确授权时，禁止对真实端点产生副作用。

实现时从当前源码定位 Tool 接口、同类实现和接线点；依赖通过现有 composition root 注入，输出和资源消耗设置与风险相称的边界。不要从旧计划或 Skill 示例复制已经变化的注册方式。

文档影响与验证

完成实现后查看完整 diff，并按 AGENTS.md 执行文档影响审查：

• 工具清单、行为、注册或默认启用状态变化时，更新 docs/design/tool/tool-system.md。
• Runtime 公共行为变化时，更新 Runtime 的 README、API 文档、示例或兼容性说明中实际受影响的部分。
• 只有真实 HTTP、SSE 或其他公开契约发生变化时才更新相应契约；不能预设“系统工具永远与契约无关”。
• 架构、命令或开发流程发生变化时，检查相应 AGENTS.md、标准文档和 README。

从当前 Makefile 选择存在的定向测试和最终门禁，不在 Skill 中固化可能改名的命令。交付前至少完成相关包测试、文档机械检查以及适用 AGENTS.md 指定的统一门禁；需要真实基础设施时再运行当前仓库定义的集成入口。

最终说明测试先行证据、权限与副作用判断、注册和默认启用状态、文档影响结论及实际执行的验证命令。