Agent 的文档与 API 规范如何设计？

标准回答

API 文档要说明输入输出、权限、错误、副作用和兼容规则，让调用者知道成功究竟意味着什么。

接口返回 accepted 只代表进入队列，就应告诉调用方如何查询完成状态；不能把“请求接收”与“业务完成”都写成成功。

**文档要让调用者能独立接入：**说明请求字段、必填条件、返回结构、错误和权限，并提供成功与失败样例。工具名称最好表达实际动作，减少含糊的万能接口。

**版本变化怎样交代：**新增字段通常比改变旧字段含义更容易兼容。对单位、状态或权限变化明确标版本与迁移方式，使旧客户端能继续工作或得到可识别的拒绝。