前言¶
用 DeepSeek Harness（dsh）跑 Agent 時，工具調用和模型輪次往往在後臺連續進行。不點開會話、不翻事件流，很難回答四個具體問題：現在在幹什麼、這一輪第幾步、已經跑了多久、待辦清單推到哪一項。社區插件 dsh-agent-status（維護者 mdktelmdktel，分類：客戶端）把上述信息摺疊成標題欄裏的「膠囊」狀態條，並在 0.2.0 起可選屏幕右下角置頂 HUD，數據來自本機 HTTP API，零配置即可使用。
下面按定位、能力、安裝與原理說明用法與注意點。插件以當前 dsh 進程權限運行；安裝前請自行查看 GitHub 倉庫 源碼與 MIT 許可證。社區目錄頁見 skillhub.cn，與 DeepSeek / 幻方無官方從屬關係。
這是什麼¶
dsh-agent-status 是 DSH 客戶端插件：在會話標題欄實時顯示 Agent 進度，並可選獨立桌面窗口常駐顯示同一套狀態。
它要解決的是「進度可見性」——不用切換面板，一眼看到當前動作、步數、本輪耗時和待辦進度。npm 上另有同名包 dsh-agent-status（作者 r2s，2026-10-20 發佈，功能類似），不是本插件；請認準 github:mdktelmdktel/dsh-agent-status。
核心功能¶
標題欄膠囊¶
膠囊單行示例（來自 README）：
● 執行命令：pnpm test · 第 12 步 · 1:38 · 待辦 3/7
● 修改文件：client.js · 第 8 步 · 0:42
✓ 上一輪完成 · 6 步 · 1:12 ← 空閒 9 秒後自動消失
含義約定：
- ● 藍點脈衝：正在執行
- ✓ 綠點：剛結束的一輪
- ✗ 紅點：最近一次工具調用失敗
- 鼠標懸停：當前待辦原文 + 最近 4 個動作（工具 / 目標 / 耗時 / 成敗）
屏幕右下角 HUD（0.2.0）¶
除標題欄外，插件可拉起獨立桌面窗口，釘在屏幕右下角、始終置頂；DSH 最小化或被其他窗口遮擋時仍可看到。窗口爲無邊框、圓角、半透明卡片，不在任務欄佔位；可拖動，右鍵關閉本次窗口。數據與膠囊相同，輪詢本機 /agent-status/api/state，端口自動發現。DSH 退出時窗口一併退出；重複啓動會做單例檢測。
腳本爲 desktop-hud.ps1（Windows PowerShell 5.1 + WPF，零依賴），由插件宿主在啓動時拉起。若不需要 HUD，設置環境變量：
DSH_AGENT_STATUS_HUD=0
顯示字段¶
| 字段 | 含義 |
|---|---|
| 當前動作 | 工具名映射爲可讀文案（如 ops_bash → 執行命令，edit → 修改文件），並附參數摘要 |
| 第 N 步 | 本輪中第幾次模型請求（每批工具調用算一步） |
| 本輪耗時 | 從 turn/start 到當前的實際時間 |
| 待辦 x/y | Agent 調用 todo_write 時的清單進度與當前項 |
前兩項回答「現在」，後兩項回答「做到哪裏」。
安裝與啓用¶
在 Plugin Manager 中安裝下列 bundle，或在 profile 目錄 ~/.dsh/profiles/<name> 手工等價配置：
github:mdktelmdktel/dsh-agent-status
手工步驟：
- 在
package.json的dependencies中加入"dsh-agent-status": "github:mdktelmdktel/dsh-agent-status" - 在
package.json的dsh.profile.bundles中加入"dsh-agent-status" - 執行
pnpm install，HMR 會激活新 bundle
裝完後刷新頁面（Ctrl+R）即可看到膠囊。若要關閉插件，在插件配置行設置 disabled: true。
運行要求（來自 package.json）：Node >=18，DSH >=0.1.0。
典型用法¶
安裝並刷新後，打開任意 Agent 會話即可在標題欄看到膠囊隨工具調用更新。Windows 用戶默認還會看到右下角 HUD；關閉 HUD 見上文 DSH_AGENT_STATUS_HUD=0。
懸停膠囊可覈對待辦與最近動作，適合長時間跑測試、批量改文件時確認 Agent 是否卡在某一工具上。子 Agent 作爲獨立 session，同一套摺疊邏輯會自動爲其記賬，無需額外配置。
原理與數據流¶
架構可以概括爲：宿主摺疊會話事件 → 暴露 JSON API → 客戶端輪詢渲染。
Host Client
session/event ──摺疊──> per-session state 1.2s 輪詢
turn/start { phase, tool, detail, │
tool/call step, turnMs, todo, ▼
tool/result recent } conversation.session.header.utilities
assistant/message │ → 膠囊組件
turn/end ▼
GET /agent-status/api/state
要點：
- 僅消費持久事件：
turn/start、tool/call、tool/result、assistant/message、turn/end，狀態可重建，不依賴 per-agent 訂閱 - 內存態、無落盤：會話 15 分鐘無事件即回收，最多保留 48 個會話
- 默認零配置；若要改輪詢間隔，修改
client.js中的POLL_MS
倉庫主要文件：index.js（宿主：事件摺疊 + API）、client.js（瀏覽器：膠囊組件）、cordis.patch.yml、desktop-hud.ps1、locale/{zh,en}.json。
適用場景與已知限制¶
適合：本地長時間跑 Agent、需要不點開會話就確認當前工具與步數；Windows 上需要置頂 HUD 盯進度。
注意：
- 膠囊顯示的是宿主內存中的當前狀態；若在某一 round 中途纔打開頁面，「第 N 步」從插件開始觀察的位置計數，不會回溯該 round 更早的事件
- 修改宿主側
index.js不會熱更，需重啓應用；修改client.js會經 client-hmr 下發 /agent-status/api/state僅監聽迴環地址、無鑑權，內容爲工具名與參數摘要，請勿在不可信網絡環境暴露
結尾¶
dsh-agent-status 把 Agent 的「現在在幹什麼、第幾步、跑了多久、待辦幾項」收進標題欄膠囊，並在 Windows 上可選右下角置頂 HUD，安裝 bundle 後刷新即可使用。
