## LLM 工具接口设计规范 ### 一、合并还是分开 共享同一**标识空间** + 同一**生命周期** → 合并为一个工具,用 `op` 分派。否则分开。 ### 二、动词表 按资源性质选: | 资源性质 | 动词 | |---|---| | 持久化资源(存在/不存在两态) | `list` / `get` / `create` / `update` / `delete` | | 可开关资源 | 上面 + `enable` / `disable` | | 瞬时动作(无持久状态) | `run`,单独成工具 | 表按**资源**选动词:动作作用于持久资源时(如技能的 `run`)并入该资源工具的 op 集;「`run` 单独成工具」只针对资源本身无持久状态、只剩动作的情形(`terminal`、`fetch` 类)。 跨工具统一用词:枚举 `list`、读单个 `get`、新建 `create`、删除 `delete`。 ### 三、参数的放置 默认全部展开为顶层 `properties`。 - 跨 op 共享的参数放顶层,description 说明哪些 op 用它; - op 专属参数也放顶层,description 说明 `op=X 时必填`; - 仅当参数结构在工具定义时无法确定时,才用自由对象 `{ "type": "object" }`。 - 互斥的多动作一律用枚举开关 `op` + 各自顶层参数,不要把动作编码进键名:键名方案无法用 `required` 约束(漏键只能到运行时才发现),弱模型也更容易漏写。 ### 四、条件必填 - op 专属参数一律设为**可选**; - 工具 description 用紧凑格式列依赖: ``` op=list 无参数。 op=create 需要 A 和 B。 op=delete 需要 id。 ``` - 参数 description 补一句"op=X 时使用"。 ### 五、错误处理 - 分派的 default 分支**列出可用 op**; - 报错**回显**:哪个 op、缺哪个字段; - 代码里做校验,不只依赖 schema。 ### 六、内容分工 | 内容 | 位置 | |---|---| | 有哪些 op、每个 op 要什么参数 | tool schema | | op 之间的依赖 | tool description | | 跨工具的动作指令 | system prompt | | 动词表、命名约定 | 开发文档 | system prompt 不重复 schema 已表达的内容。 ### 七、配套工具 成对出现的工具("执行动态能力" + "查询其 schema")相互依赖。删一个前先确认另一个的定位是否随之改变。 ### 八、上下文成本 tools 数组每轮请求完整重发。新工具进来时,先问"能不能装进已有工具",再问"要不要新建"。 回执/参数里可能很大的内容,若**可再生**(文件在盘上可重读、页面可重抓)或只是当时快照, 可在 `agent.trim.rules` 登记历史重放占位裁剪:同时满足「其后 ≥rounds 条 assistant 行」与 「其后 ≥turns 条真人消息」后换成单行占位(`app/server/llm.js` 的 `setPayloadTrim`; `side: args` 点名参数、`side: result` 裁整段回执)。`turns: 1` = 回合内不裁、跨回合才裁; 长回合里会被反复回看的内容(如 `read_file` 的分段)应配它,否则模型会把同一段重读一遍。 一次性输出(`terminal`、外部服务扣额度的生成结果等)不要登记——裁掉后模型无法恢复。 ### 九、回执形态 - **内容型**工具(`read_file` 的文本、`fetch` 的正文、`db` 的查询结果)回执就是内容本身,不要套 JSON 信封。 - **结果型**动作(读图、裁剪、转换)回执用**单个 JSON 对象**,把判定写进字段,不写自然语言:模型按字段分支, 不要再让它从句子里猜。字段名跨工具保持一致:`ok`(调用是否成功)/ `reason`(稳定枚举)/ `retryable` / `width` `height` 之类的事实字段 / `hint`(仅解释,不承载判定)。 - 回执可能被多层改写(发送前裁剪、同回合去重、投递失败降级):改写**只动字段**,不得在 JSON 后追加句子—— 追加会把回执变成不可解析的尾巴,等于把判定权又还给语义猜测。 - **回执是「那次调用」的历史事实,不是当前状态**:发送侧为了省 token 省略内容时,不要改写回执 (典型错例:把当时成功的图片投递改写成 `image_attached:false`)。模型会把历史读图当成失败, 于是反复重读同一条;省略、重放、缓存这类传输层细节不属于回执语义。 - `ok:true` 不等于「结果已送达」:另有字段(如 `image_attached`)描述投递状态,两者不要混成一个布尔。