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 官方开源实现）。