前言¶
DeepSeek Harness (DSH) 負責編排智能體的運行與工具調用，而 UniPet 是一個運行在桌面上的寵物進程。二者之間缺乏直接的交互接口。unipet-dsh 插件填補了這個空白，它監聽 DSH 的 agent/session 生命週期事件，將思考、工具執行、等待審批或失敗等狀態，通過 HTTP API 推送給本地 UniPet 寵物，使其狀態與 AI 的實際運行情況保持同步。
插件概覽¶
- 名稱：unipet-dsh
- 維護者：ztyhehe
- 許可：MIT
- 定位：工作流插件，負責 DSH 與 UniPet 的狀態橋接。
核心功能¶
- 監聽 DSH agent/session 的生命週期事件。
- 實時將狀態推送到本地 UniPet 寵物。
- 支持狀態映射（thinking, waiting, failed, review 等）。
- 寵物不在線時自動執行
unipet start拉起。 - 定期進行健康探測，斷線期間停止推送，恢復後自動回 idle。
- 對高頻事件進行去抖動處理，並支持失敗語義識別。
安裝與啓用¶
在 DSH 的 web profile 環境下執行以下命令進行安裝：
cd ~/.dsh && dsh plugin --profile web add git+https://github.com/ztyhehe/unipet-dsh.git
安裝完成後，重啓 dsh web 服務即可生效。
狀態映射¶
插件會將 DSH 的特定事件映射爲 UniPet 的狀態，具體對應關係如下：
| DSH 事件 | UniPet 狀態 | 氣泡文案 |
|---|---|---|
turn/start |
running | Thinking… |
tool/call |
running | Editing code / Running command / Searching / Delegating |
approval/asked |
waiting | Waiting for your approval |
ask/question |
waiting | Waiting for your answer |
tool/result 失敗 / agent/error |
failed | Task failed |
agent/status idle |
review | Done - ready for review（8s 後自動復位） |
配置說明¶
默認配置即可滿足基本使用。如需調整，可在 profile 的 cordis.patch.yml 中覆蓋插件的 config 字段。
- host / port：UniPet 的 HTTP 地址與端口，默認
127.0.0.1:8768。 - source：事件來源標識，默認
dsh。 - autoStart：寵物不在線時嘗試拉起，默認
true。 - debounceMs：同類狀態的最小發送間隔（去抖窗口），默認
400ms。 - healthIntervalMs：寵物健康探測週期，默認
30000ms。 - aggregate：多 agent 聚合策略，默認
true。 - softFail：擴展語義失敗識別，默認
true。
注意事項與限制¶
- 本插件爲純 host 側插件，不包含客戶端代碼，僅訪問本機迴環地址，不外發任何數據。
- 卸載前需手動清理定時器與未發出的去抖狀態。
- 若
cordis.patch.yml中存在舊的手工掛載行（name: './plugins/unipet-dsh/index.js'），請務必刪除該條 insert，否則可能導致雙實例重複推送。
驗證與故障排除¶
若日誌中出現 push failed: request timeout，但 UniPet 明顯在運行，這可能是舊版本誤報。v0.2.0 已修復此問題（通過消費 HTTP 響應避免 socket 空閒超時）。確保完全重啓 dsh web 後再觀察。
可通過以下命令手動驗證推送鏈路，確認 UniPet 正常接收：
curl -sS -m 5 -w "\nHTTP=%{http_code} total=%{time_total}s\n" \
-X POST http://127.0.0.1:8768/api/pet/events \
-H 'Content-Type: application/json' \
--data '{"source":"dsh","state":"idle","message":"DSH ready","action":"update"}'
短結尾¶
通過上述配置，DSH 的運行狀態將實時反饋在桌面寵物上。更多細節可查閱項目目錄頁或源碼。
