4.1 KiB
4.1 KiB
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 登记历史重放占位裁剪:距尾 ≥N 个 assistant 轮后换成单行占位
(app/server/llm.js 的 setPayloadTrim;side: args 点名参数、side: result 裁整段回执)。
一次性输出(terminal、外部服务扣额度的生成结果等)不要登记——裁掉后模型无法恢复。
九、回执形态
- 内容型工具(
read_file的文本、fetch的正文、db的查询结果)回执就是内容本身,不要套 JSON 信封。 - 结果型动作(读图、裁剪、转换)回执用单个 JSON 对象,把判定写进字段,不写自然语言:模型按字段分支,
不要再让它从句子里猜。字段名跨工具保持一致:
ok(调用是否成功)/reason(稳定枚举)/retryable/widthheight之类的事实字段 /hint(仅解释,不承载判定)。 - 回执可能被多层改写(发送前裁剪、同回合去重、投递失败降级):改写只动字段,不得在 JSON 后追加句子—— 追加会把回执变成不可解析的尾巴,等于把判定权又还给语义猜测。
- 回执是「那次调用」的历史事实,不是当前状态:发送侧为了省 token 省略内容时,不要改写回执
(典型错例:把当时成功的图片投递改写成
image_attached:false)。模型会把历史读图当成失败, 于是反复重读同一条;省略、重放、缓存这类传输层细节不属于回执语义。 ok:true不等于「结果已送达」:另有字段(如image_attached)描述投递状态,两者不要混成一个布尔。