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