Yichen Jiang
5d2c943d38
The executor collapse landed without telling the model it exists. Every tool contributes its own guidance section naming its tool, none of them qualify how that tool is reached, and they all render before the SDK (orders 100-199 against SDK_SECTION_ORDER 150), so the prompt said "Use the read tool" eleven times and never said only run_code is callable. A real session shows the consequence: the model emitted a native call, read `unknown tool "read"` for a tool the same prompt declares, and concluded the deployment was inconsistent rather than routing through run_code. The registry now contributes `tools:code-only` at order 99 -- ahead of the guidance band -- stating the rule, registered wherever `tools:sdk` is and rendering empty outside an effective `code`. `both` renders it empty because its native calls do execute, which is also why both-mode-turn no longer shares code-mode-turn's expected prompt. The denial itself now names the route back, since a bare UNKNOWN_TOOL for a declared tool is what misled the model.
2.8 KiB
dsh-agent-tool-mode
English | 中文
agent preset 用来声明「模型看到的工具是哪一种形态」的那一行：native（全部 schema）、code（只有 run_code 加一份生成的 TypeScript SDK）或 both。
为什么是一行插件，而不是把注册表搬下来
工具注册表搬不进 preset。它的消费者全在宿主平面——dsh-agent-loop 读它的调度器，dsh-apiproxy 读它的 presenter 来渲染工具卡，每个工具插件都往里注册——而一个服务只有在所有消费者一起下沉时才能下沉。
preset 能拥有的是这份注册表的呈现方式。ctx.tools.presentAs() 只为正在挂载的那个 agent 声明，于是一个 Code Mode 会话可以和多个 native 会话同进程并存，各自看到各自的清单。dsh-tools 那一行上的 mode 仍然是默认值，供未作声明的 agent 使用。
它做什么
native 立即生效。code 类模式则等待 ctx.codeRuntime——这是一个宿主平面服务（dsh-code-runtime-worker）：若某个 preset 在未组装运行时的部署上选择 Code Mode，本行就停在 pending，dsh-agent-presets 会指名此 id 拒绝挂载。另一种做法——先乐观应用——会把失败推迟到该会话的第一次请求，那时操作者对 preset 和组装都已无从下手。
mode 是必填而非有默认值：不带这一行的 preset 本来就会拿到部署默认值，省略它等于这一行白组装了。
一个 agent 只声明一次呈现方式。同一份组装里的第二次声明会被拒绝而不是合并：对「模型看到哪种形态」给出两个答案是矛盾，不是覆盖。
Model Experience
间接生效，取决于它在 dsh-tools 中选择的投影：code 呈现 run_code、一份生成的 SDK 段，以及「只有 run_code 可被直接调用」这条规则，native 呈现每个工具的 schema。该选择同时决定了什么可以执行：在 code 下，注册表会把模型直呼其他任何工具名解析为 UNKNOWN_TOOL，因此这一行正是让「通告面」与「可调用面」对每个被它覆盖的 agent 保持一致的东西（执行器塌缩 note）。
KV Cache effect
没有直接的失效影响；呈现方式在 agent 组装时即固定，因此其请求前缀在该会话的整个生命周期内保持稳定。
Known Limitations and Deferred Work
- 运行时仍在宿主平面 —— preset 可以选择 Code Mode，却无法自带它所需的 TypeScript 运行时；未组装运行时的部署也就无法组装任何 code 模式的 preset。