前言¶
在 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
