形状:{"list":"all"} / {"get":"<名>"} / {"run":"<名>","args":{...}},三者恰好给一个。
- 互斥无法用 required 表达,校验与报错回显放在 toolSkill
- list 取值是字符串范围而非布尔,为将来的技能分类留扩展位;今天只认 all
- list/get 带非空 args 一律报错,不静默丢弃
- 旧形状 {op,name,input_args} 仍由 toolSkill 兜底翻译,只为兼容存量技能文档,不再对外文档化
- README/AGENTS/skills 文档与内置技能调用示例同步为新形态
2.5 KiB
2.5 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" }。 - 动词 + 单 token 标识可以折叠成「动词作键、标识作值」(技能的
{"get":"<名>"}即此形)。 多个动词互斥时required表达不了,必须在代码里校验,并在报错里回显全部合法形态; 取值范围暂只有一个时(如{"list":"all"})仍用字符串而非布尔,便于后续扩成分类等子集。
四、条件必填
- 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 数组每轮请求完整重发。新工具进来时,先问"能不能装进已有工具",再问"要不要新建"。