前言¶

DSH 的 agent 常遇到一類任務：等構建產物落地、等下載完成、等日誌追加某一行、等子進程退出。這些任務本身不難，難的是必須等外部事件。常見的做法是讓 agent 反覆 sleep 加輪詢，代價是上下文被輪詢喫掉，或者把當前回合卡死，用戶插不上話；DSH 一旦重啓，未完成的等待就直接丟了。

下面介紹的 dsh-durable-wait（中文名「守候」）解決的就是這個問題：agent 登記一次等待就結束當前輪次，插件在後臺按固定間隔檢查條件，條件成立時自動叫醒原會話繼續幹活。

這是什麼¶

dsh-durable-wait 是一個 DSH 插件，由 Yyhy110421 維護，許可證 MIT，在社區目錄裏歸在工作流分類下。它不改變原有用法，只是補上一個持久等待的輪子：等待狀態落盤，DSH 重啓後繼續檢查。

它不做的事也很明確：不監聽文件系統事件（靠輪詢）、不殺進程、不讀文件內容。

核心功能¶

1、三個宿主工具：wait_create 登記等待，wait_list 查看當前等待，wait_cancel 取消等待。
2、三類等待條件：文件出現（file-exists）、文件修改（file-changed）、進程退出（process-exit）。
3、當前輪次立即結束：wait_create 返回後 agent 可以把這一輪正常收尾，不阻塞用戶。
4、喚醒原會話：條件成立後按會話狀態決定是立即 followup，還是排隊等會話空閒，或離線時嘗試 agents.resume。
5、狀態落盤：等待狀態寫在 DSH_HOME/data/durable-wait.json，設置寫在 DSH_HOME/data/durable-wait-settings.json，DSH 重啓後繼續檢查；終態條目默認保留 7 天。

等待的判斷全部在本地完成，沒有額外依賴。

安裝與啓用¶

在 DSH 裏打開 設置 → 插件管理器，安裝下面任一來源：

github:Yyhy110421/dsh-durable-wait

或者安裝本地目錄：

file:E:\DSH\projects\dsh-durable-wait

裝完重啓 DSH。兩點注意：

1、file: 安裝是實體拷貝，改了源碼要卸載再裝，不是熱更新。
2、插件管理器裏的「更新」只適用於 npm 註冊表插件，本插件不發佈 npm。

安裝後菜單裏出現 設置 → 守候，用於配置參數和查看等待列表。源碼和許可證建議在安裝前先過一遍，插件是以當前 DSH 進程權限運行的。

典型用法¶

等文件出現¶

{
  "kind": "file-exists",
  "path": "E:\\build\\release\\app.exe",
  "note": "等構建產物",
  "timeoutMinutes": 30
}

file-exists 只判斷路徑是否存在，不做內容檢查。

等文件修改¶

{
  "kind": "file-changed",
  "path": "E:\\logs\\build.log",
  "note": "等日誌追加",
  "timeoutMinutes": 20
}

file-changed 的基線是創建等待那一刻的 mtime 和文件大小：

• 創建時文件已存在：mtime 或大小變化纔算成立；
• 創建時文件不存在：文件出現就算成立。

所以「日誌追加了內容」如果恰好沒改變 mtime 和大小，不會被判定爲成立。

等進程退出¶

{
  "kind": "process-exit",
  "pid": 12345,
  "note": "等渲染進程結束",
  "timeoutMinutes": 60
}

只檢查進程是否還存在，不會殺進程。PID 可能被系統複用：進程退出後 PID 立刻被別的進程佔用，這個等待可能不會觸發。需要強關聯時，優先等產物文件或日誌。

查看和取消¶

wait_list
wait_cancel { "id": "wait-..." }

wait_create 返回的等待對象裏帶 id、status、expiresAt。

叫醒規則¶

條件成立後的行爲，按會話狀態分四種：

1、會話在線且空閒：直接 followup，下一輪繼續。
2、會話在線但正在跑：保持「待叫醒」，等它空閒再叫，不插隊。
3、會話不在線：嘗試 agents.resume 一次，失敗就標 undelivered，不循環重試。
4、自動叫醒關閉：條件成立只改狀態，不叫醒。

被叫醒時消息以 【守候】 開頭，包含等待 ID、條件類型和目標、備註、成立時間。agent 被叫醒後應先 wait_list 確認，再繼續原任務，不要重複創建同一個等待。

狀態字段¶

等待狀態 status：

投遞狀態 delivery：

設置頁¶

設置 → 守候：

• 默認超時（分鐘）：新建等待不傳 timeoutMinutes 時使用；
• 輪詢間隔（秒）：2–60，默認 2；
• 最多同時等待：1–200，默認 50；
• 條件成立時自動叫醒會話：關掉後只記錄狀態；
• 等待列表：目標、狀態、剩餘時間、叫醒狀態；
• 取消進行中的等待。

設置保存在 DSH_HOME/data/durable-wait-settings.json。

安全邊界¶

插件只做了很窄的一件事：

• 文件類只做 stat，進程類只做 process.kill(pid, 0) 存在性檢查；
• 不殺進程、不改目標文件、不讀文件內容；
• 只接受絕對路徑，避免相對路徑隨工作目錄漂移；
• 備註限 500 字，不要寫驗證碼、密碼、API Key；
• 最多同時 200 條等待，防止狀態文件無限增長；
• 叫醒消息只包含等待目標和備註，不含文件內容或進程輸出。

適用場景與注意¶

適合這類場景：agent 需要等一個外部事件（產物文件、日誌變化、子進程結束），且這一步可以異步化，之後還有活兒要幹。不適合的場景：需要秒級響應的等待（默認 2 秒輪詢）、需要精確感知文件內容變化的等待、以及依賴 PID 強關聯的進程等待。

幾個務必留意的點：

1、插件以當前 DSH 進程權限運行，能訪問該進程能訪問的文件和 PID，安裝前先檢查源碼與許可證（MIT）。
2、file: 安裝是拷貝，改源碼後不會自動生效。
3、本插件不發佈 npm，插件管理器的「更新」對它無效。
4、等待狀態依賴 DSH_HOME/data/ 落盤，換 DSH_HOME 會丟等待。
5、叫醒是「下一輪用戶消息」，不會打斷正在執行的回合。

結尾¶

dsh-durable-wait 把「等外部事件」從 agent 反覆輪詢的笨辦法，換成一次登記加一次叫醒。它覆蓋文件出現/修改和進程退出三類常見條件，狀態落盤可跨重啓，權限面也控制得很窄。

目錄頁：https://www.skillhub.cn/plugins/Yyhy110421/dsh-durable-wait
GitHub：https://github.com/Yyhy110421/dsh-durable-wait