Files
agent/docs/tool-design.md
T
kicer b0a8283406 占位裁剪新增 turns(真人回合)条件:回合内不裁,跨回合才裁
rounds 数的是 assistant 行,长回合里会把模型还要用的回执裁掉——实测有回合把同一文件
分段重读了 24 次(每次都在 rounds:2 生效的那一轮回来重读)。

- 规则新增 turns 字段:其后又来了几条真人消息(role=user 且 type 为空,注入行不算)
- rounds 与 turns 同时满足才裁(AND);两者都写 0 才算规则关闭
- 默认:fetch / read_file / web_search 用 rounds:2 + turns:1(回合内绝不裁),
  write_file 参数侧保持 rounds:1 + turns:0(只是写盘快照,照旧早裁)
- config.example.yml 补了带时间线的例子与「rounds=后面 AI 又说了几句话 /
  turns=后面又来了几条真人消息」的注释;AGENTS.md 与 tool-design.md 同步
- 启动日志改为打印 轮≥N,回合≥M,便于核对生效规则
2026-11-03 08:06:43 +08:00

88 lines
4.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## 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 数组每轮请求完整重发。新工具进来时,先问"能不能装进已有工具",再问"要不要新建"。
回执/参数里可能很大的内容,若**可再生**(文件在盘上可重读、页面可重抓)或只是当时快照,
可在 `agent.trim.rules` 登记历史重放占位裁剪:同时满足「其后 ≥rounds 条 assistant 行」与
「其后 ≥turns 条真人消息」后换成单行占位(`app/server/llm.js` 的 `setPayloadTrim`;
`side: args` 点名参数、`side: result` 裁整段回执)。`turns: 1` = 回合内不裁、跨回合才裁;
长回合里会被反复回看的内容(如 `read_file` 的分段)应配它,否则模型会把同一段重读一遍。
一次性输出(`terminal`、外部服务扣额度的生成结果等)不要登记——裁掉后模型无法恢复。
### 九、回执形态
- **内容型**工具(`read_file` 的文本、`fetch` 的正文、`db` 的查询结果)回执就是内容本身,不要套 JSON 信封。
- **结果型**动作(读图、裁剪、转换)回执用**单个 JSON 对象**,把判定写进字段,不写自然语言:模型按字段分支,
不要再让它从句子里猜。字段名跨工具保持一致:`ok`(调用是否成功)/ `reason`(稳定枚举)/ `retryable` /
`width` `height` 之类的事实字段 / `hint`(仅解释,不承载判定)。
- 回执可能被多层改写(发送前裁剪、同回合去重、投递失败降级):改写**只动字段**,不得在 JSON 后追加句子——
追加会把回执变成不可解析的尾巴,等于把判定权又还给语义猜测。
- **回执是「那次调用」的历史事实,不是当前状态**:发送侧为了省 token 省略内容时,不要改写回执
(典型错例:把当时成功的图片投递改写成 `image_attached:false`)。模型会把历史读图当成失败,
于是反复重读同一条;省略、重放、缓存这类传输层细节不属于回执语义。
- `ok:true` 不等于「结果已送达」:另有字段(如 `image_attached`)描述投递状态,两者不要混成一个布尔。