前言¶
在 DeepSeek Harness（DSH）裏跑長任務時，模型和腳本常會「等滿超時再查一遍」：wait_agent(timeout=30min) 在隊友卡死時仍要等滿上限且只返回布爾值；job_output(wait:true) 在作業無進展時同樣燒時間；更常見的是 sleep 90 再查文件，一輪往返就要一分半。超時返回後往往還要二次查詢才能區分成功、失敗還是單純超時。下面介紹的插件 dsh-tool-wait-until 由社區維護者 tongsh6 發佈，分類爲工作流，用事件驅動的 wait_until 工具替代上述空等路徑，並在工具層硬攔截過長的 sleep 與超長 job_output / wait_agent 等待。
這是什麼¶
dsh-tool-wait-until 是 DSH 的 Host 插件：給模型註冊 wait_until 等待原語，在後臺作業結束、隊友空閒、文件出現或日誌命中等條件滿足時立即返回結構化結果；在目標失敗、連續無進展或調用方取消時提前結束，而不是把 timeout_sec 當作主要判定手段。插件零依賴，手寫 JSON Schema，要求 Node 20+ 與 dsh 0.2.1 及以上（engines.dsh 聲明爲 >=0.2.1-rc.1 <0.3.0，README 寫明在 0.2.1-rc.5 上驗證過）。許可證 MIT，當前 npm 包版本 1.0.5。
維護者設計上的關鍵判斷是：只提供新工具不夠，模型仍可能在思考裏決定「先 sleep 再查」。因此插件分三層——系統提示詞注入等待紀律、tools.guard 拒絕典型空等調用、以及 wait_until 本身的事件驅動實現。
核心功能¶
wait_until：一次調用、五種狀態¶
調用一次即可決策，無需再查 list_agents 或重複 job_output。返回字段包括 status、elapsed / elapsed_ms、failure_reason、output_tail 等。
status 爲五態：completed、failed、stalled、timeout、cancelled。README 明確：超時不是失敗，單獨一態。
多個 conditions 爲 wait_all 語義：全部滿足才 completed；fail_fast 命中時任一條件失敗即 failed。若需要「任一完成就返回」，應拆成多次 wait_until。
條件類型¶
| kind | 必填 | until | 說明 |
|---|---|---|---|
job |
id |
settled（默認）/ failed |
作業結束（含失敗）或僅失敗 |
agent |
— | inactive（默認）/ failed / status_changed |
成員空閒 / 失敗 / 狀態變化 |
file |
path |
exists（默認）/ changed |
文件出現 / 版本變化 |
log |
path, matches |
matches |
日誌尾部或新增內容命中正則 |
平臺可能把「進程退出但退出碼非零」記爲 completed；插件會結合退出碼與輸出裏的 EXIT=N 自行判定爲 failed，避免把腳本報錯當成功。
fail_fast 與卡住檢測¶
fail_fast: true（默認）：覆蓋job_failed、job_killed、agent_failed。- 也可設爲
false或數組，支持exit_code_nonzero、stderr_matches:/re/、output_matches:/re/等。 stall_after_sec：連續 N 秒無任何進展返回stalled，而不是等到timeout_sec。
事件驅動與輪詢邊界¶
作業類條件訂閱 jobs.events，在 settle、輸出增長或 progress 時喚醒主循環，不受 poll_interval_sec 限制。文件、日誌、隊友條件按 poll_interval_sec 採樣（默認 2s）。全程響應 exec.signal，打斷時返回 cancelled。
行爲攔截（tools.guard）¶
| 攔截對象 | 條件 | 行爲 |
|---|---|---|
前臺 bash |
含 sleep ≥ 20s（非後臺、非 run_in_background） |
拒絕，並在原因中給出 wait_until 替代示例 |
job_output |
wait:true 且 timeout_ms > 120000 |
拒絕，要求改用 wait_until |
wait_agent |
timeout_ms > 120000 |
拒絕，要求改用 agent 條件 |
短 sleep、後臺 sleep 與其餘調用不受影響。攔截爲硬拒絕，模型需重試一步；拒絕信息裏附帶可複製的替代調用。
安裝與啓用¶
CLI 從 npm 安裝（命令以 README 爲準）：
dsh plugin --profile web add dsh-tool-wait-until
桌面應用可在插件管理器中搜索同名包安裝。本地開發可鏈接源碼目錄：
dsh plugin --profile web add link:/path/to/dsh-tool-wait-until
安裝後 Plugin Manager 會寫入 profile 的 package.json 與 bundle，cordis.patch.yml 插入 tool-wait-until 條目；卸載從插件管理器移除即可。
注意：DSH 會緩存已加載的插件模塊；僅改 link 包 JS 再重裝時，運行中進程可能仍跑舊代碼，需重啓 Desktop。插件在宿主進程內以當前 dsh 進程權限運行，安裝前宜查看 GitHub 倉庫 源碼與 MIT 許可證。
典型用法¶
下面示例來自 README，展示多條件等待與常用參數：
wait_until({
conditions: [
{ kind: 'job', id: '<job_id>' },
{ kind: 'agent', target: 'worker' },
{ kind: 'file', path: '/tmp/out.zip', until: 'exists' },
{ kind: 'log', path: '/tmp/build.log', matches: '/EXIT=0/' },
],
fail_fast: true,
stall_after_sec: 120,
timeout_sec: 900,
poll_interval_sec: 2,
})
失敗時返回示例結構（節選）：
{
"status": "failed",
"elapsed_ms": 1250,
"elapsed": "1.2s",
"failure_reason": "後臺作業 bash-xxxx 失敗：退出碼 3",
"output_tail": "BOOM: intentional failure\n",
"hint": "目標已失敗，不必再等：按 output_tail / failure_reason 決策……"
}
倉庫內單測入口：
node test/unit.mjs
適用場景與限制¶
適合：需要在 DSH 工作流中等待後臺 job、Agent Teams 成員、文件或日誌條件，且希望失敗、卡住時快速得到可解釋結果的多步自動化任務。
限制（README 已知項）：
- 思考階段是否「想 sleep 180 秒」無法直接干預；僅當落成工具調用時纔會被 guard 改道。
agent條件依賴 Agent Teams；非 Team 會話會立即failed並說明原因，不會空等。- 多條件爲 wait_all，非「任一滿足」。
- 日誌按字節窗口讀取，多字節字符在邊界可能出現替換符，一般不影響 ASCII 正則匹配。
DSH 生態理念是「一切皆插件」；SkillHub 目錄頁 爲社區站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-tool-wait-until 把 DSH 裏常見的「睡滿超時再查」改成事件驅動的一次性裁決，並用 guard 堵住 sleep 輪詢與超長內置等待。進一步瞭解可閱讀 GitHub README 與 目錄頁。
