工具预取加速 Liman-cmd/dsh-plugin-tool-prefetch

dsh-plugin-tool-prefetch

DeepSeek Harness（dsh）插件：把 agent-tool-acceleration 的工具调用预测网关作为 Python sidecar 拉起，将其工具（gw_predict_next / gw_observe / gw_stats / gw_reset + 代理的真实上游工具）原生注册到 ctx.tools——不是 MCP 服务器配置，是正经插件：在 Settings → Plugins 可见、可启用/禁用（禁用即杀掉 sidecar）。

零 npm 依赖（纯 JS + node:child_process），预测由论文的 CT-GNN 模型提供（CPU，~15 ms/次）。

四种模式（config.mode）

| mode | 注册工具吗 | 挂钩子吗 | 用途 |
| interceptor（随包默认）| ❌ | ✅ 自动采集+预测+预热 | 透明加速：零 token、零 agent 配合；预测发生在模型还在写 reasoning 时 |
| tools | ✅ 全部 24 个 | ❌ | v1 显式版：模型能主动调预测/遥测工具；采集需 agent 传参 |
| probe | ❌ | ✅ 只写日志 | 一次性验证：确认 dsh 会触发钩子、exec.agent 是什么形状 |
| both | 仅 gw_（7 个）| ✅ | 隐形加速 + 保留人工查询/切模型入口 |

代码内缺省值是 tools；随包的 cordis.patch.yml 显式设成 interceptor。
interceptor 若拉不起 sidecar（网关没装/路径错），钩子照常 next() 透传，只是不上报——不会挡住任何工具调用。

切换只改配置值，不用动代码：

- insert:
- id: tool-prefetch
name: dsh-plugin-tool-prefetch
config:
mode: 'interceptor' # ← 改这里 python: 'D:\...\.venv\Scripts\python.exe' repoRoot: 'D:\...\agent-tool-acceleration' gatewayConfig: 'mcp_prefetch_gateway/configs/tau_retail_gpt4o_real.yaml' sessionFrom: 'agent' # interceptor 用 exec.agent 分会话 catalogApply: true # 新增工具并入服务图（实测保序、已有预测逐位不变） catalogAllowRemovals: false # 删除会移位索引，需显式开 autoModelSwap: true # 飞轮晋升后自动应用（免重启 dsh） modelSwapPollMs: 300000 # 轮询间隔

工具目录上报（自动，无需配置）

插件在启动时取 ctx.tools.schemas()、并监听 tools/change（dsh 未过滤注册表通知，任何工具增删/权限变化都触发）增量上报实际工具集。网关据此与离线产物 diff——这是「命中率莫名下降」最常见的隐藏原因，现在会明确告警（cli health 或 gw_tool_catalog 可见）。

自动换模型（autoModelSwap）

飞轮过闸后会写网关配置，但运行中的网关是插件的子进程（不同进程），原先需重启 dsh 才生效。开着这个开关，插件定期调 gw_apply_pending，配置变了就地热切换。关掉即回到纯手动（只有显式 gw_switch_model / cli switch-model 才换）。

验证钩子 + 用户消息采集（mode: probe）

装好后重启 dsh、随便调一个工具，然后：

Get-Content D:\...\agent-tool-acceleration\mcp_prefetch_gateway\logs\probe.log -Tail 10

看到含 agentId + sessionUserFound: true 的 pre_execute 行 = 钩子可用且能从 agent.session.log 挖出用户原文。探针不改任何行为（next() 原样透传，实测 0ms）。

用户消息藏在 agent.session.log 的 user/message 事件里，而注入的 AGENTS.md / skill 列表 / 时间上下文同样是 type:user/message + role:'user'，只有 data.source.kind 不同（agent-instructions / skill-catalog / time-context …）。所以筛选用白名单 source.kind === 'user'，不能只看 role。详见 docs/interceptor-probe.md。

这个仓库包含什么 / 不包含什么

本仓只有「桥」（约 8 KB JS），不含预测、采集、训练的实现——它们在配套的网关项目 agent-tool-acceleration：

| 能力 | 在哪 | 本仓有吗 |
| 插件壳（拉起 sidecar、原生注册工具、转发调用）| index.js（本仓）| ✅ |
| 预测（CT-GNN / markov 冷启动）| 网关 mcp_prefetch_gateway/ | ❌ 需配套项目 |
| 数据采集（step 事件 → 遥测）| 网关 server.py + telemetry.py | ❌ 需配套项目 |
| 训练 / 再训（飞轮）| scripts/retrain_gateway.py + src/train.py | ❌ 需配套项目 |

因此：只装本插件跑不起来。 完整依赖见下节。

安装

完整依赖（缺一不可）

| 依赖 | 说明 |
| 网关项目 | agent-tool-acceleration 检出（目前私有，需权限）|
| Python 环境 | .venv + pip install -r requirements.txt（torch 等，CPU 版即可）|
| 模型产物 | data/processed/model_.pt + graph_.pkl（被 gitignore，不在任何仓里）|
| 轨迹文件 | data/processed/trajectories_.jsonl——⚠️ 不只是训练用：网关启动时要拿它拟合 BM25 词表 |
| τ-bench 环境 | data/raw/tau-bench（真实零售数据库，git clone https://github.com/sierra-research/tau-bench）|

有权限的人 → 跑 scripts/setup_gateway.ps1 一条命令备齐环境。

装插件

从 GitHub（推荐）
npx @deepseek-ai/dsh plugin --profile web add github:Liman-cmd/dsh-plugin-tool-prefetch

或本地路径（开发）
npx @deepseek-ai/dsh plugin --profile web add ./dsh-plugin-tool-prefetch

重启 dsh web；Settings → Plugins 里应出现 tool-prefetch
npx @deepseek-ai/dsh web

⚠️ 本插件未附带预训练模型的可分发形态。换成你自己的工具场景时，retail 模型不适用——需要用你自己的数据重训（见"数据飞轮"），或先跑 markov 冷启动模式（predict.mode: markov，零训练即可用）。

配置

插件默认值写在 cordis.patch.yml（指向本仓库路径）。换机器/换配置：把该行拷进你的 profile patch（~/.dsh/profiles/web/cordis.patch.yml）改值：

- insert:
- id: tool-prefetch
name: dsh-plugin-tool-prefetch
config:
python: 'D:\path\to\.venv\Scripts\python.exe'
repoRoot: 'D:\path\to\agent-tool-acceleration'
gatewayConfig: 'mcp_prefetch_gateway/configs/tau_retail_gpt4o_real.yaml'
toolPrefix: '' # 注册名前缀，避免与其他插件重名 initTimeoutMs: 60000 # sidecar 冷启动预算（torch+模型 ~20s） callTimeoutMs: 120000

行为要点

- 冷启动异步：sidecar 启动 ~20 s，不阻塞 dsh；工具就绪后自动出现。
- 真实执行 + 自动对账：代理工具真调上游（默认 τ-bench retail 真实数据库），每次调用自动写入 session 状态并对账上一条预测（_gateway.session_id 可选携带）。
- 数据飞轮：所有真实调用自动落遥测 step 事件。查看采集进度： python -m mcp_prefetch_gateway.cli status --config <gateway yaml>（会告诉你距首次可训还差几条轨迹、按近期速率预计几天）；攒够后 python scripts/retrain_gateway.py ... 一键再训换模型。

要不要训 GNN？ 先看任务类型（论文结论）：短流程、无上下文依赖的任务， markov 计数通常就够了，GNN 未必更好；多轮、上下文相关的任务 GNN 才显著领先。
所以对很多场景，"自己的模型"这个目标本身是多余的——计数版已随使用变准。
- 与 MCP 配置互斥：若之前在 cordis.patch.yml 配过 mcp-prefetch （dsh-mcp-client 行），装本插件前删掉那行，避免 21 个工具注册两遍。

排障

| 症状 | 处置 |
| 工具一直不出现 | dsh 日志找 [tool-prefetch]；多半是 python 路径/产物路径错 |
| 验证 sidecar 本身 | node dsh-plugin-tool-prefetch/smoke.mjs（不起 dsh 全链自测）|
| 想换预测模型 | 改 gatewayConfig 指向别的 configs/*.yaml |

许可

MIT。预测器与数据来自本仓库论文项目（τ-bench 数据为 Sierra 官方开源实现）。