## 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 专属参数一律设为**可选**; - 工具 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 数组每轮请求完整重发。新工具进来时,先问"能不能装进已有工具",再问"要不要新建"。