前言¶
在 DeepSeek Harness（DSH）里跑智能体时，一轮对话往往要经历多次模型推理和大量工具调用。README 中基于 6 次真实会话（2,517 次工具调用）的测量表明：关键路径上模型延迟（首 token、思考、生成）约占 87.2%，工具执行约占 22.1%。本插件只作用于后者，不能减少模型往返次数。
若你的瓶颈是重复的 read/glob/grep、glob 之后紧跟着的一串读文件，或只读 shell 被串行排队，可以在不改模型侧逻辑的前提下，用缓存、预取和可选的 shell 并发缩短工具窗口。若工具本身已是毫秒级，或 Harness 已把并发安全工具并行发出，增益会很小——作者也在文档里明确写了这些边界。
这是什么¶
dsh-agent-speedup 是维护者 HJ1H 发布在 npm 上的 DSH 工作流类插件（GitHub：HJ1H/dsh-agent-speedup）。定位是「工具执行效率套件」：在有限、可测量的范围内提供只读结果缓存（含进行中去重）、基于 glob 的投机预取，以及可选的只读 shell 并发调度。
与同样面向 DSH 的 HarnessMM 不同：HarnessMM 通过回放受 guard 的决策减少模型推理调用；本插件只减少或合并工具执行，不碰推理层。两者可叠加使用。
核心功能¶
只读缓存（Cache）¶
对 read、glob、grep、read_image 等只读工具，按工具名与规范化参数缓存结果；命中时不再调用真实 dispatch。
- 条目带
size+mtimeMs指纹，每次命中校验；文件被任意方式修改即失效（含 bash/pwsh 写入，无 fs 事件时亦然）。 fs/write-intent、fs/edit-intent会对编辑路径立即失效。- 相对路径相对 agent 会话工作目录解析，与 dsh 自带
read一致。 - LRU，默认
maxEntries: 512；读过程中文件发生变化的结果不写入缓存。 - 自定义或 MCP 只读工具需在
readonlyTools中显式列出，否则不会假定安全。
作者给出的串行重复读示例：约 2023 ms → 7 ms。
进行中去重（In-flight merge）¶
同一轮并行批次里若出现两次相同只读调用，在都未完成前缓存无法命中。插件让相同进行中的调用共享一次执行。测量示例：3 次同时读总耗时约 2027 ms，而非串行 6 s 量级。
投机预取（Prefetch）¶
glob 返回后，在后台对前 N 个路径预执行同族 read，结果进入同一缓存；模型随后真正请求时可直接命中。预取走与普通工具相同的 pipeline（上下文、工作目录、guard）。作者测量：工具时间约 10.08 s → 2.07 s（−79.4%），单次 read 中位数约 2016 ms → 11 ms。在 deepseek-v4.1-flash 上方向与量级类似（文档称 prefetch/cache 约 −79.0% 工具时间、70% 命中率）。
触发 glob 的工具名默认在 speculateOn: [glob]；预取数量由 prefetchN 控制（ bundled 默认 3）。
Shell 并发（默认关闭）¶
dsh 的 bash/pwsh 未声明 isConcurrencySafe 时，shell 会互斥执行。启用后，对通过保守分类器的只读命令允许并行。作者在一组 4 条只读命令上测得窗口约 13.81 s → 4.65 s（−66.3%）；且在该次对比中关闭 cache 与 speculate，仅改调度。
分类器故意严格：npm test、cargo build、未知命令、命令替换、${VAR}、NAME=value cmd、PowerShell 脚本块等一律拒绝或视为有副作用。误分类可能导致带副作用的命令并行——因此 默认 shellConcurrency: false，需自行在 patch 中开启并接受风险。
安装与启用¶
环境要求（README）：Node 22+、dsh 0.2.x、PATH 上有 pnpm（Windows 上文档建议 pnpm 10；pnpm 12 在部分环境 store lock 会失败）。
官方安装命令：
dsh plugin --profile web add dsh-agent-speedup
插件随附 cordis.patch.yml，安装后默认开启缓存与预取；shell 并发需手动配置。
覆盖配置时注意：dsh 里相同 id 的 patch 整对象替换，不 merge。改一个键时要写全你关心的字段，默认值见仓库内 cordis.patch.yml。npm 包当前版本为 0.3.1（以 package.json 为准）。
启用 shell 并发时，README 示例（须重复全部相关键）：
- id: agent-speedup
config:
cache: true
readonlyTools: []
validateStat: true
maxEntries: 512
speculate: true
prefetchN: 3
speculateOn: [glob]
speculateRootPrefix: ""
shellConcurrency: true
shellTools: [bash, pwsh]
主要配置项默认值（README 表格，截断处已省略的扩展字段以仓库为准）：
| Key | Default | 含义 |
|---|---|---|
cache |
true |
只读结果缓存 |
readonlyTools |
[] |
额外视为只读、可缓存的工具名 |
validateStat |
true |
命中时校验文件 stat |
maxEntries |
512 |
LRU 容量 |
speculate |
true |
是否预取 |
prefetchN |
3 |
glob 后预读路径数 |
speculateOn |
[glob] |
触发预取的工具 |
shellConcurrency |
false |
只读 shell 并行 |
peer 依赖：@deepseek-ai/cordis >= 4.0.0、@deepseek-ai/dsh-tools >= 0.2.0-rc.0（optional）。
典型用法¶
- 在 web profile 下执行上述
dsh plugin --profile web add dsh-agent-speedup，保持 bundled patch 即可体验缓存 + glob 预取。 - 智能体反复读同一文件、或在同一 turn 里并行重复 grep/read 时，依赖缓存与 in-flight merge，无需改 prompt。
- 工作流常为「glob 找文件 → 连续 read」时，预取会在 glob 结果返回后后台读前几条路径。
- 若大量只读 PowerShell/
git branch/find -print类命令被 shell 串行拖慢，在理解分类器风险后，将shellConcurrency设为true并保留完整 config 块。
更完整的基准方法、置信区间与「不适合安装」的情形见仓库 docs/BENCHMARK.md。
适用场景与注意¶
适合：远程或慢磁盘上的 read/glob/grep 较多、调用重复或 glob 后紧跟批量读、只读 shell 被互斥锁拉长窗口的 DSH 会话。
不适合或增益有限：本地毫秒级工具（作者测得工具仅占墙钟 0.1–9.4% 的会话）；baseline 中 Harness 已在约 19 ms 内并行发出 7 个工具且无本插件时，相邻结果常在 100 ms 内返回——插件无法替代模型侧优化。
安全与信任：插件在 dsh 进程权限下拦截/调度工具。安装前应阅读源码与许可证，自行评估 shell 分类器与缓存失效策略是否匹配你的仓库与工作流。社区目录 SkillHub 插件页 与 GitHub 无 DeepSeek / 幻方官方从属关系，属社区生态。
结尾¶
dsh-agent-speedup 把优化范围 honest 地限定在工具执行约占的那部分路径：缓存与去重、glob 预取、可选只读 shell 并发，并有公开基准说明边界与与 HarnessMM 的分工。若你的 agent 会话工具耗时可测且重复明显，可按官方命令安装并在 patch 中按需打开 shell 并发。
- 目录页：https://www.skillhub.cn/plugins/HJ1H/dsh-agent-speedup
- 仓库：https://github.com/HJ1H/dsh-agent-speedup
