[Design/BUG] 动态插件把工具注册进全局作用域：一个会话的工具增删打爆所有会话的提示词缓存

[Kitten-BLACK]

提交日期：2026-08-14　|　环境：@deepseek-ai/dsh 0.1.0-rc.6（web profile，Windows）　|　模型路由：deepseek-official / deepseek-v4-flash

摘要（Abstract）

Dynamic Cordis plugins mount under a process-root cordis-dynamic group, so every tool they register via ctx.tools.register() lands in the global tool layer of dsh-tools. That layer is merged into every session's visible tool set on every request (tools array of the chat-completions call). DeepSeek's automatic context cache is keyed on the exact input prefix, which includes the serialized tools definitions — so any add/remove of a global tool invalidates the full prompt prefix for every session sharing the API key. In one day of normal use (creating/stopping debug dynamic plugins), the affected session accumulated 8,094,273 cache-miss input tokens; each tool change cost a full ~470k-token re-processing, and the same registration was observed leaking into a second, unrelated session's request within 3 seconds.

现象（Symptoms）

1. 会话内 tools 数组在会话中途反复增删（request/header 事件 reason=change 频繁出现）。
2. 每次工具数变化后，紧接着的下一个 LLM 请求的缓存命中几乎归零，miss ≈ 当前上下文总量（最终约 47 万 token）。
3. 同一进程里另一个无关会话的请求中也出现了这个新工具（跨会话泄漏）。
4. 单日累计未命中 8,094,273 token。

根因（Root Cause）

代码路径

• 动态插件挂载组：dsh-cordis-host-runner/lib/index.js:2531

  requireGroup() { this.group ??= this.rootCtx.plugin({ name: 'cordis-dynamic', apply: () => { } }); }

  动态插件以子 fiber 挂在该组下（startHostHalf，index.js:919），ctx 是进程根作用域，没有 agent scope。
• 工具注册：sandboxRegisterTool → ctx.tools.register(tool)（dsh-cordis-host-runner/lib/index.js:541-543），最终插入 dsh-tools 的全局层（dsh-tools/lib/index.js:2755-2763）。
• 可见性合并：dsh-tools/lib/index.js:2836-2862 view(scope) 把 this.layers.global.tools 并入每个 agent 的可见集合。
• 每请求装配：dsh-system-prompt/lib/index.js:240 assemble() → 收集全局+作用域全部工具 schema → orderTools()（无 toolOrder 配置时按名称字典序稳定排序，index.js:46）。顺序稳定，但集合随注册增删变化。
• 请求构造：dsh-agent-loop/lib/index.js:670 buildRequest 把 tools 放进请求；变化时记录会话事件 request/header（reason=change）。
• 序列化：dsh-llm-deepseek/lib/index.js:107-135 把 tools 序列化为 chat-completions 顶层 tools 参数。
• usage 映射：dsh-llm-deepseek/lib/index.js:183-197，inputTokens = prompt_tokens - prompt_cache_hit_tokens（即纯未命中），cacheReadTokens = prompt_cache_hit_tokens。

失效机制

DeepSeek 自动上下文缓存按输入前缀精确匹配（官方文档 kv_cache），输入 token 流 = [system + tools 定义序列化] + 全部历史消息。tools 参数参与前缀编码（外部佐证：openclaw #107076 — Dynamic tool list before CACHE_BOUNDARY breaks prefix caching for exact-match providers (GLM-5.2, DeepSeek)）。因此任意全局工具注册/注销 → 所有会话的下一请求前缀分叉 → 全量缓存 miss。

控制对照：同一会话 11:42:13 有一次非工具类 header 变化（reasoningEffort 从 adapter 默认改为显式），紧随其后的请求 miss 仅 654 token（缓存未破）；而每次 tools 集合变化，miss 都等于上下文总量——证明破坏前缀的正是 tools 数组。

证据（Evidence）

数据来源：会话持久化日志 $DSH_HOME/sessions/<cwd>/<session>/session.jsonl.zstd（解压后为 JSONL，含 request/header 与 assistant/chunk 的 usage 事件）。

表 1：d39（框架推进会话）工具变动 vs 下一请求缓存 miss（节选，完整 30 条见附录）

时间	tools 数变化	新增/移除工具	下一请求 miss	下一请求 hit
12:03:12	36→37	+prompt_sections	248,421	7,936
12:05:22	37→32	-5 个调试工具	54,200	217,984
12:09:47	32→33	+agent_verify	314,504	0
12:14:21	39→40	+agent_prompt_verify2	335,656	3,968
12:41:10	32→33	+csharp_e2e	447,500	3,840
12:54:20	32→33	+prompt_dump	468,574	7,808
12:54:31	33→32	-prompt_dump	595	476,288

• 每次 miss ≈ 当前上下文总量；回到旧工具集合时（如 12:54:31 变回 32 个工具）能部分回命中原缓存——证明缓存键就是 tools 数组。
• 当日累计 inputTokens（未命中）= 8,094,273。

表 2：跨会话泄漏（同一时刻，两个无关会话）

时间	d39（推进框架的会话）	07d（CatHome 工作会话，另一上下文）
12:54:17	cordis_define 创建插件 prompt-dump 并 run → 工具注册进全局层	—（无操作）
12:54:20	自己下一请求：tools 32→33，miss=468,574	—
12:54:23	—	自己下一请求：tools 48→49，请求里出现 prompt_dump
12:54:26	—	该请求结束：miss=50,360，hit=7,936（当时 ~5.8 万上下文全量重算）
12:54:31	注销插件，tools 回到 32	—

07d 全程没有创建任何插件，纯粹因为共享全局工具层而损失整段缓存。

影响（Impact）

1. 跨会话缓存污染：任何一个会话注册/注销带工具的动态插件（或 HMR、MCP 工具集变化），都会使同进程所有会话（共享同一 API key）的下一次请求全量 miss，代价与各会话上下文大小成正比。
2. 重复付费：长上下文会话（~47 万 token）每次被波及都相当于把整段上下文按未命中重新计费。
3. 工具幽灵：会话 A 注册→注销的窗口内，会话 B 的模型可能看到该工具并调用，随后工具消失 → UNKNOWN_TOOL 错误。
4. 命名冲突：两个会话同时注册同名工具会触发 tool "x" is already registered in this scope。

修复建议（Suggested Fix）

1. 核心修复（推荐）：把 cordis-dynamic 组从进程根 rootCtx 改为发起会话的 agent 作用域（dsh-cordis-host-runner 的 requireGroup()/startHostHalf 需要拿到发起 agent 的 ctx，或为每个会话建独立 group）。动态插件工具从此只出现在发起会话的请求里，跨会话污染消除；会话内频繁 run/stop 的代价也仅由该会话自己承担。
2. 可选增强：工具注册变更时（tools/change 事件已存在）在 Web UI 提示"工具集已变化，将导致前缀缓存失效"。
3. 可选增强：会话级 toolOrder 已可固定顺序（仅影响顺序，不影响集合）；可进一步提供"冻结工具集"开关供长会话使用。

附录：d39 完整工具变动时间线（30 次）

#	时间	变化	miss(下一请求)	hit
1	11:58:25	32→33 +preset_check	216,100	2,048
2	11:59:14	33→34 +preset_verify	224,056	7,808
3	12:00:21	34→35 +preset_debug	233,111	7,808
4	12:01:44	35→36 +preset_diag	241,636	7,808
5	12:03:12	36→37 +prompt_sections	248,421	7,936
6	12:05:22	37→32 批量移除	54,200	217,984
7	12:05:37	32→33 +roster_check	271,250	7,808
8	12:05:43	33→32 -roster_check	532	278,912
9	12:09:47	32→33 +agent_verify	314,504	0
10	12:10:49	33→34 +agent_verify2	318,501	3,840
11	12:11:15	34→35 +agent_diag2	321,072	3,840
12	12:12:01	35→36 +registry_diag	324,446	3,840
13	12:12:34	36→37 +registry_diag2	321,248	9,344
14	12:13:18	37→38 +agent_verify3	331,372	3,840
15	12:13:43	38→39 +agent_prompt_verify	332,582	3,840
16	12:14:21	39→40 +agent_prompt_verify2	335,656	3,968
17	12:14:52	40→32 批量移除	26,872	314,368
18	12:22:07	32→33 +js_eval_probe	353,583	3,840
19	12:22:28	33→34 +skills_verify	351,758	7,424
20	12:25:52	34→35 +probe_read	371,624	7,424
21	12:27:13	35→36 +final_verify	379,978	3,840
22	12:27:46	36→37 +final_verify2	378,784	6,528
23	12:27:55	37→32 批量移除	28,545	357,248
24	12:41:10	32→33 +csharp_e2e	447,500	3,840
25	12:41:52	33→34 +csharp_e2e2	447,332	6,144
26	12:43:30	34→32 批量移除	6,317	451,200
27	12:51:38	32→33 +schema_check	464,921	9,216
28	12:52:15	33→32 -schema_check	146	474,496
29	12:54:20	32→33 +prompt_dump	468,574	7,808
30	12:54:31	33→32 -prompt_dump	595	476,288

合计未命中 inputTokens = 8,094,273（含工具变动之外的新消息增量）。

复现步骤（Repro）

1. 在 web profile 下开两个会话，共用同一 API key。
2. 会话 B（长上下文）正常对话至上下文 ~10 万+ token。
3. 会话 A：cordis_define 定义一个 inject: ['tools']、在 apply 里 ctx.tools.register({ name: 'probe_x', ... }) 的插件，cordis_run。
4. 观察：会话 B 的下一请求 request/header 记录 tools 变化（reason=change），usage 中 cacheReadTokens 归零、inputTokens ≈ 会话 B 全量上下文。
5. 会话 A cordis_stop/cordis_undefine：会话 B 再次全量 miss。

[Kitten-BLACK]

并非单日，是2分钟连续几轮工具调用就直接泄露了8M的未命中，直接把一个500k前文300步的会话命中率整体拉低到80%
我的Token如雪花般消失：XD

[Yan-Zero]

你补的跨会话时间线很有价值，prompt_dump 在另一个会话里出现后立刻带来 50k miss，这比单会话工具抖动更容易定位问题。

我最近做了一个呈现层的缓解方案：dsh-progressive-tools。插件挂在 profile 的 host plane，对已有和后续 preset 生效；模型侧长期看到的是一组固定 discovery 入口，动态 registry 里的普通工具只以 name + description 出现在 search_tools(*) 结果里，调用前再通过 describe_tools 取 schema。这样全局层新增、注销工具时，下一次请求的顶层工具表不跟着整批变化。

cordis-dynamic 把注册落到 global layer 的归属问题仍值得在上游处理。这个插件覆盖的是请求呈现和调用路径：目录与执行都实时读取当前 scoped ToolRuntime，工具消失、受限或被 shadow 后会按当前状态失败；policy、approval 和 guard 也继续走原来的执行管线。

v0.2.3 已经发布：

dsh plugin --profile web add dsh-progressive-tools

你这个 500k 前文、连续动态工具启停的样本很适合测呈现层方案能挡住多少 cache miss。如果复测时 request/header.tools 仍随全局注册变化，欢迎把那段 header 发到插件仓库，我可以继续追具体的 assembly 组合。