81 lines
3.6 KiB
Markdown
81 lines
3.6 KiB
Markdown
## 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 数组每轮请求完整重发。新工具进来时,先问"能不能装进已有工具",再问"要不要新建"。
|
||
|
||
### 九、回执形态
|
||
|
||
- **内容型**工具(`read_file` 的文本、`fetch` 的正文、`db` 的查询结果)回执就是内容本身,不要套 JSON 信封。
|
||
- **结果型**动作(读图、裁剪、转换)回执用**单个 JSON 对象**,把判定写进字段,不写自然语言:模型按字段分支,
|
||
不要再让它从句子里猜。字段名跨工具保持一致:`ok`(调用是否成功)/ `reason`(稳定枚举)/ `retryable` /
|
||
`width` `height` 之类的事实字段 / `hint`(仅解释,不承载判定)。
|
||
- 回执可能被多层改写(发送前裁剪、同回合去重、投递失败降级):改写**只动字段**,不得在 JSON 后追加句子——
|
||
追加会把回执变成不可解析的尾巴,等于把判定权又还给语义猜测。
|
||
- **回执是「那次调用」的历史事实,不是当前状态**:发送侧为了省 token 省略内容时,不要改写回执
|
||
(典型错例:把当时成功的图片投递改写成 `image_attached:false`)。模型会把历史读图当成失败,
|
||
于是反复重读同一条;省略、重放、缓存这类传输层细节不属于回执语义。
|
||
- `ok:true` 不等于「结果已送达」:另有字段(如 `image_attached`)描述投递状态,两者不要混成一个布尔。
|