前言¶
DeepSeek Harness (DSH) 採用插件化架構，允許開發者擴展其功能。在管理多 agent 工作流時，精確跟蹤 root agent 與子 agent 的生命週期狀態是關鍵。lbryany/dsh-herdr 插件解決了這個問題，將 DSH 進程內部的 agent 狀態聚合爲 Herdr pane 的語義狀態。
插件介紹¶
插件名：lbryany/dsh-herdr
維護者：Lbryany
功能：DeepSeek Harness Herdr 狀態集成。
定位：該插件運行在 DSH TUI 進程內部，把該進程中的 root agent 與子 agent 聚合成當前 Herdr pane 的語義狀態。
核心功能¶
狀態映射¶
插件將 DSH 進程狀態映射爲 Herdr 狀態：
| DSH 進程狀態 | Herdr 狀態 |
|---|---|
| 任一 agent 有未處理審批 | blocked |
| 無待審批，任一 agent 正在運行 | working |
| 存在 agent，且全部空閒 | idle |
| 最後一個 agent 已銷燬或插件卸載 | release-agent |
狀態監聽與持久化¶
插件監聽以下事件：agent/created、agent/status、agent/disposed 和 session/event。通過持久 NDJSON 連接（HERDR_SOCKET_PATH）與 Herdr 通信，支持會話恢復時摺疊歷史審批狀態，避免重啓後丟失待審批信息。
狀態報告機制¶
狀態報告通過進程內隊列串行執行，並使用 epoch 微秒 seq 進行計數。同一 pane 重啓 DSH 後不會從 1 重新計數，確保 Herdr 能正確識別新報告。
安裝與啓用¶
在安裝前，請確保環境滿足以下要求：
- DeepSeek Harness 0.1.0-rc.6
- Node.js 22.19+ 或 24+
- Herdr 管理的 pane（進程環境包含 HERDR_ENV=1 與 HERDR_PANE_ID）
安裝命令如下：
dsh plugin --profile tui add github:Lbryany/dsh-herdr
安裝完成後，在 Herdr pane 內啓動 DSH TUI。
典型用法¶
- 在 Herdr pane 內啓動 DSH TUI。
- 通過另一個 pane 執行
herdr agent list查看狀態。 - 觀察 DSH 處理消息顯示
working，等待工具審批顯示blocked，完成後顯示idle或 Herdr 根據可見性派生的done。
設計細節¶
- 連接策略：插件優先通過
HERDR_SOCKET_PATH建立 Unix domain socket 或 Windows named pipe 連接。連接、超時或協議失敗時，自動回退到HERDR_BIN_PATH指定的 Herdr CLI。 - 進程複用：同一 DSH 進程複用一條 socket 連接，不爲每次狀態變化啓動 Herdr 子進程。
- 權限：插件以當前 dsh 進程權限運行，未運行在 Herdr pane 內時自動禁用。
適用場景與注意¶
適合需要將 DSH agent 狀態實時同步到 Herdr 儀表盤的開發者。安裝前建議檢查源碼與許可證（MIT）。
