Files
agent/docs/tool-design.md
T
kicer 76a0e9ad86 refactor(skill): 参数改为动词作键,去掉 op/name/input_args
形状:{"list":"all"} / {"get":"<名>"} / {"run":"<名>","args":{...}},三者恰好给一个。
- 互斥无法用 required 表达,校验与报错回显放在 toolSkill
- list 取值是字符串范围而非布尔,为将来的技能分类留扩展位;今天只认 all
- list/get 带非空 args 一律报错,不静默丢弃
- 旧形状 {op,name,input_args} 仍由 toolSkill 兜底翻译,只为兼容存量技能文档,不再对外文档化
- README/AGENTS/skills 文档与内置技能调用示例同步为新形态
2026-10-21 09:25:25 +08:00

2.5 KiB
Raw Blame History

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