前言¶
在 DSH（DeepSeek Harness）的工程實踐中，工具調用通常通過 timeoutMs 或 job_output 的 timeout_ms 參數控制等待時間。這些參數由模型填寫，若模型未指定或填寫的值過大，部署側通常缺乏細粒度的兜底機制，可能導致長時間阻塞或資源佔用。
插件簡介¶
dsh-limit-timeout 是一個由 azazo1 維護的管理安全類插件，用於在 DSH agent 單次工具調用執行前攔截並檢查等待時長。
該插件在 tools/pre-execute 階段介入，覆蓋模型可控的等待參數。當調用請求超過配置的上限時，插件會拒絕該次調用，記錄日誌，並提供三條替代方案供模型參考（降低等待時間、改用後臺執行、申請提升）。
安裝與啓用¶
安裝前請確保 DSH 引擎版本滿足要求：@deepseek-ai/dsh-* 需要大於或等於 0.2.0-rc.1 且小於 0.3.0。
Web 端安裝需指定 web profile：
dsh plugin --profile web add azazo1/dsh-limit-timeout
安裝完成後，重啓 dsh web 以刷新頁面。
桌面端不支持通過命令行直接安裝（命令行會拒絕 --profile desktop 參數）。需在應用內的插件管理器中填寫包名 azazo1/dsh-limit-timeout 進行安裝，隨後重啓桌面端應用。
配置說明¶
設置入口位於 Settings > 等待上限。該頁面爲草稿式編輯，改動不會立即生效，需點擊“保存”或“放棄更改”。
保存操作爲原子寫入，若配置衝突（如默認上限高於硬天花板），保存會被拒絕。
設置包含以下字段：
| 字段 | 默認值 | 說明 |
|---|---|---|
全局默認等待上限 (defaultLimitMs) |
120000 | 單次調用可聲明的最大等待時間，覆蓋 timeoutMs 與 timeout_ms |
硬天花板 (hardLimitMs) |
1800000 | 即使批准了提升，實際等待也不會超過此值；調低它會收回已批准的提升 |
允許模型申請提升 (allowEscalation) |
開 | 開啓後模型可通過 request_wait_extension 申請提升，由部署側審批 |
要求顯式聲明等待時長 (requireExplicitJobWaitMs) |
關 | 開啓後 job_output 的 wait: true 必須同時給出 timeout_ms |
屏蔽重複調用提醒 (suppressRepeatToolReminders) |
關 | 開啓後 repeat-tool-reminder 注入的提醒不再進入模型請求 |
支持的時間格式包括：120000（毫秒）、500ms、90s、2m、1h。未編輯時，保存後與放棄更改後都會還原成合適的單位寫法。
運行時行爲¶
- 攔截與拒絕：插件在
tools/pre-execute階段攔截調用。放行時繼續進入下游策略（權限、沙箱）判斷；超限時直接短路成錯誤結果，調用不會真正執行。 - 拒絕日誌：每次拒絕都會以 info 級別記入 Host 日誌，包含工具名、調用 ID、當前上限與提升狀態。
- 提升機制：申請走 DSH 原生審批通道，批准後僅對當前進程內的會話生效。提升不寫入會話日誌，因此不可回放，也不能跨進程保留。
- 重複提醒：通過
agent/pre-step過濾repeat-tool-reminder注入的消息。此功能僅改變模型看到的內容，不影響會話日誌與歷史回放，被過濾的條數記入 debug 日誌。
適用場景與邊界¶
- 邊界檢查：該插件僅覆蓋模型可控的等待參數（
timeoutMs、timeout_ms）。工具自身的部署超時（如web_fetch的fetchTimeoutMs）不受本插件約束。 - job_output 行爲：當
job_output僅寫wait: true而不寫timeout_ms時，等待時長由dsh-tool-jobs的waitTimeoutMs決定，默認配置下不受本插件約束。需嚴格限制時可開啓“要求顯式聲明等待時長”。 - 安全提示：插件以當前 DSH 進程權限運行，安裝前建議檢查源碼與許可證（MIT）。
開發¶
插件基於 TypeScript 開發，源碼位於 src/ 目錄，構建產物位於 lib/ 目錄。
常用開發命令如下：
just install
just typecheck
just build
just test
just verify
結尾¶
該插件爲 DSH 生態提供了一種在部署側控制工具調用時延的手段。通過設置全局上限與硬天花板，結合模型申請提升機制，可以在保障系統穩定性的同時，給予模型靈活的執行空間。
