2.3 KiB
2.3 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 数组每轮请求完整重发。新工具进来时,先问"能不能装进已有工具",再问"要不要新建"。