前言¶
在 DSH 裏讓 agent 跑長任務時，一個常見問題是看不清它此刻在做什麼：目標進行到第幾輪、哪些 subagent 在跑、workflow 到了哪個階段、後臺任務有沒有失敗。這些信息分散在會話的不同位置，不開日誌就得來回切換查看。
dsh-agent-pill 解決的是這個可見性問題：把當前會話的關鍵活動濃縮成右上角一顆狀態膠囊，需要細節時再用快捷鍵展開懸浮面板。下面按功能、架構、安裝與用法的順序介紹。
這是什麼¶
dsh-agent-pill 是 mozhuanzuojing 維護的 DSH web 插件，MIT 許可證，當前版本 0.14.8。一句話定位：ZCode 風格的 agent 活動膠囊（右上角狀態膠囊）+ 懸浮摘要面板，Ctrl+Alt+P 切換。
插件分兩半：
- host 半：聚合當前會話的 Goal / Subagents / Agent 狀態 / workflow 運行 / 後臺任務，經
/pill/api暴露帶完整控制動詞的 JSON API。 - client 半：右上角浮動膠囊 + 錨定膠囊的 tooltip 式懸浮面板，內含 goal 卡片、workflow 歷史（步驟與觀察文件）、subagent 樹、任務列表（輸出 / kill）。
核心功能¶
膠囊與懸浮面板¶
1、Ctrl+Alt+P 切換面板，點擊膠囊同樣有效。
2、面板是錨定膠囊的輕量 popover，不是固定右側抽屜：會在四個視口邊緣間翻轉以保持完整可見，高約 70vh 內部滾動，點擊外部、Esc 或再按快捷鍵關閉。
3、寬度自適應（v0.9.0）：ResizeObserver 驅動，在 320–520px 內夾緊並以視口爲上限；diff 行保持 white-space: pre 不換行。
4、膠囊可拖拽到任意屏幕邊緣，位置持久化到 localStorage，窗口縮放時仍夾緊在視口內。
5、主題跟隨 DSH：配色由 CSS 變量驅動，響應 <body data-ds-dark-theme> 信號，白色 / 暗色（moon night）即時切換，含跟隨操作系統的 system 模式。
6、分區摺疊：Goal / Agent / Subagents / Jobs 分區頭可點擊摺疊，狀態存 localStorage；v0.13.0 起默認展開。
7、空狀態隱藏（v0.6.0）：沒有目標的 Goal、沒有子節點的 Subagents、沒有條目的 Jobs、沒有事件的 Activity 整體隱藏——只顯示存在的內容。
8、詳情層（v0.7.0）：點擊 workflow 運行或 subagent 行，在彈層內推入新的詳情層（頭部有返回按鈕）；目標消失時自動返回，會話切換時重置。subagent 詳情含身份、模式、計時、終止狀態和停止控制。
Goal 卡片與 workflow 歷史¶
- Goal 卡片顯示目標、階段、輪數、經過時間與激活狀態，帶輪數進度條（
roundsStarted / maxGoalRounds）。 - workflow 歷史（v0.4.0）：最近 5 次運行的有界環。每次運行可展開看步驟（每次
agent()調用的 seq / label / phase / outcome）與運行期間觀察的文件（來自 host 的fs/observed流，去重後按運行歸因）。已結束的運行保留詳情，直到被新運行替換。 - 步驟與 subagent 關聯（v0.6.0）：步驟行通過 childId 關聯 subagent 行，顯示子代理時長與終止顏色。
- 文件 diff（v0.8.0 / v0.9.0）：workflow 文件 chips 打開文件詳情層，展示結果時行級 diff（來自
dsh-tool-fs的 tool/result meta，區分新文件 / 編輯 / 覆蓋）加複製路徑按鈕；v0.9.0 起文件列表內聯展開 diff，每文件帶 +N/-N 徽標，默認僅變更行，可切換含上下文。 - 活動時間線（v0.9.0）：Activity 分區流式顯示最近主機事件——工具調用與完成、文件活動（按路徑合併計數）、workflow 階段變化、subagent 起止、goal 變化，40 條有界環。
Subagent 樹與後臺任務¶
- Subagent 樹按深度縮進，每行顯示運行時長與終止 stop reason，失敗爲紅色。時間戳來自 host 的
subagent/start/subagent/end事件。 - 後臺任務渲染爲單條步驟條目（狀態、輸出摘要、計時）；jobs 沒有結構化步驟，因此不做文件提取。任務列表支持查看輸出與 kill 終止。
即時狀態與通知¶
- 膠囊摘要（v0.3.0）：目標經過時間加即時徽標——運行中 subagent、運行中任務、活動 workflow（
wf徽標，tooltip 裏帶當前階段）、失敗任務（紅色）。 - 即時工具名（v0.5.0）：運行中會話的 in-flight 工具名顯示在膠囊條與 tooltip，
tool/result後清除。 - 工具時長（v0.6.0）：
tool/call與tool/result配對顯示，如⛭ write · 0s、✓ edit done · 12s。DSH 串行執行工具，單個 in-flight 槽位即可完成配對。 - 即時膠囊標籤（v0.8.0）：膠囊文本優先顯示運行中 workflow 的 name·phase，回退到當前工具名，再回退到
AGENT。 - 排隊消息（v0.5.0）：
agent/inbox事件維護每會話排隊數，膠囊顯示q徽標。 - 完成通知（v0.5.0）：workflow 結束、後臺任務失敗、目標完成時各觸發一次瀏覽器通知。權限爲惰性請求；頁面刷新時登記已結束 id，但不重放通知。
- 空閒長輪詢（v0.8.0）：全部空閒時客戶端停在 host 長輪詢
POST /pill/api/poll（30s 上限），而不是每 1.5s 輪詢；有活動即喚醒並恢復節奏。
會話內的文件記錄（v0.14.x）¶
- turn-tail 文件行（
conversation.chat.turnTail）：會話裏每條用戶指令下方顯示該指令處理的文件，帶 +N/-N 徽標、內聯 diff（僅變更行 / 含上下文可切換）和複製路徑按鈕。 - 忙碌時膠囊顯示「第N輪 · 動作」。
歷史說明：早期的 Usage 區塊（token 壓力 / 成本估算）與 Sessions fleet 視圖已在 v0.12.0 移除，插件現在只顯示當前會話存在的內容。
架構：契約單源與領域模塊¶
v0.14.8 的架構調整圍繞可測性與 AI 可導航性，把 host 半的編排模塊按領域拆開：
1、契約單源：src/contract.ts 是 /pill JSON API 的 wire 契約單一事實源，host 與 client 都從它 import。此前 host 內聯視圖（GoalWireView / SubagentWireView）與 client 的 api.ts（PillGoal / PillState 等）是兩份手寫鏡像，host 改字段會靜默讓 client 類型失效；現在 host 契約一改，client 編譯期即報錯。
2、領域深模塊：src/goal-tracker.ts（goal 投影）、src/git-status.ts（純解析與 TTL 緩存分離）、src/usage-snapshot.ts（token-meter + context-window）、src/subagents.ts（subagent 後代樹）、src/jobs.ts（後臺任務列表）各自帶注入 seam，可單測；src/index.ts 迴歸薄 seam 接線加方法分發。
安裝與啓用¶
本文寫作時抓取到的 README 與 package.json 中沒有給出安裝命令原文，這裏不做拼接，請以倉庫 README 爲準：https://github.com/mozhuanzuojing/dsh-agent-pill
依賴方面可對照 package.json 覈實：
- peerDependencies：
@deepseek-ai/cordis^4.0.2；@deepseek-ai/dsh-agent、@deepseek-ai/dsh-client-store、@deepseek-ai/dsh-goal、@deepseek-ai/dsh-jobs、@deepseek-ai/dsh-session、@deepseek-ai/dsh-subagent、@deepseek-ai/dsh-web-app均 ^0.1.2-rc.1；react/react-dom^18.2.0。 - package.json 的
dsh字段聲明這是 web 平臺插件，客戶端注入@deepseek-ai/dsh-client-store。
日常用法¶
1、Ctrl+Alt+P 或點擊膠囊切換摘要面板。
2、拖拽膠囊到屏幕任意邊緣，位置跨刷新保留於 localStorage。
3、點擊 Goal / Agent / Subagents / Jobs 分區頭摺疊或展開。
4、點擊 workflow 運行或 subagent 行推入詳情層，用頭部返回按鈕返回。
5、workflow 文件 chips 展開行級 diff，默認僅變更行，可切換帶上下文，附複製路徑按鈕。
6、後臺任務行內查看輸出摘要，需要時 kill 終止。
適用場景與注意¶
適合長期跑 goal / workflow / 後臺任務、想在不離開當前界面的情況下掌握 agent 進度的 DSH web 用戶。如果你此前靠翻日誌判斷 agent 行爲，Activity 時間線和 turn-tail 文件行會把“改了什麼、走到哪”直接呈現在界面上。
注意：
1、插件以當前 dsh 進程的權限運行，host 半會聚合會話狀態並暴露 /pill/api。安裝前請檢查源碼與許可證（MIT），確認可接受再啓用。
2、瀏覽器通知權限是首次觸發時惰性請求的；刷新頁面後已結束的事件不會重放通知。
3、Usage / Sessions 相關展示已在 v0.12.0 移除，按舊版本介紹找入口會落空。
小結¶
dsh-agent-pill 把 DSH 會話的活動狀態壓縮成一顆常駐膠囊和一個懸浮面板：不打開任何東西也能看到 agent 在做什麼，展開後 goal、workflow、subagent、後臺任務與文件 diff 都在手邊。MIT 許可證，當前版本 0.14.8。
- 目錄頁：https://www.skillhub.cn/plugins/mozhuanzuojing/dsh-agent-pill
- GitHub：https://github.com/mozhuanzuojing/dsh-agent-pill
補充一句生態背景：DSH 的理念是「一切皆插件」，這類可見性工具適合按需加裝；skillhub.cn 是社區維護的獨立插件目錄，與 DeepSeek / 幻方沒有官方從屬關係。
