前言¶
在 DeepSeek Harness（DSH）裏用子代理拆任務時，主會話側欄能看到子代理入口，但運行中的子代理數量、狀態、token 用量往往要切進各子會話才能確認。主會話派生出多個並行子代理時，缺少一塊集中、即時、可逐層下鑽的監視界面。
下面介紹社區插件 dsh-subagent-monitor（維護者 Mombrane，MIT 許可）。它在 DSH Web 側欄底部增加「子代理」入口，並在屏幕右上角常駐一塊可拖動的卡片面板，展示當前會話直接派生的子代理運行狀態；進入子代理會話後，面板隨之顯示該層直接派生的下一層子代理。
這是什麼¶
dsh-subagent-monitor 是面向 DSH Web 的客戶端擴展插件，npm 包名爲 @leetoners/dsh-ui-subagent-monitor，當前版本 0.3.0，要求 DSH 0.1.x 平臺。倉庫同時提供 dsh.client 插件與 dsh.bundle 組合 bundle（含 cordis.patch.yml 與預構建 lib/）。
插件通過輪詢 /api/subagent-monitor/snapshot 獲取快照；該路由面向迴環地址、無鑑權，僅建議本地或內網使用。
核心功能¶
即時狀態與卡片列表¶
每個子代理對應一張圓角卡片，展示名稱、spawn 方式、短 ID、狀態與耗時。「打開對話」在卡片右側，可跳轉到對應子會話。
支持的狀態包括：
| 狀態 | 含義 |
|---|---|
| 運行中 | 藍色像素追逐動畫（與 DSH 側欄進行態同款）+ 即時秒錶 |
| 完成 | 面板即時觀測到成功結束，綠點 + 光暈，顯示耗時 |
| 已結束 | 服務重啓前的歷史回填，結局未觀測 |
| 失敗 | 錯誤結束，紅點 + 光暈 |
| 已打斷 / 令牌上限 / 已拒絕 | 被中止、達到 token 上限或請求被拒絕，琥珀點 + 光暈 |
總體監控看板¶
面板頂部爲彙總條：左側三枚環形圖分別展示主會話上下文窗口當前佔用、主會話與子代理聚合的緩存命中率；右側一根狀態柱狀圖展示當前層子代理的運行 / 完成 / 異常計數（按最大值等比縮放）。每張卡片下方另附一行用量明細：該 run 的輸入 / 輸出 token、緩存命中、上下文大小。
主會話「上下文」環顯示當前窗口占用（projectedTokens：最新 prompt 樣本 + 表層啓發式增減），隨內容新增而上升，壓縮後立即回落，而非隨會話只增不減的累計量。用量數據來自各子代理會話日誌中 provider 上報的 TokenUsage（assistant/message 事件）；適配器未上報時顯示「—」。
逐層查看與導航¶
面板只顯示當前會話直接派生的子代理，不跨層平鋪。進入某個子代理會話後，可繼續查看其直接派生的下一層；面板出現「← 上一層」按鈕，可跳回直接父會話。
面板交互¶
- 標題左側四角箭頭拖動柄：移動面板位置，跨會話保留，雙擊復位。
- 底部拖動柄：調整面板高度，按會話分別記憶，雙擊復位。
- 兩段式收起：第一次「收起」只隱藏下方子代理卡片，頂部總覽看板保留，按鈕變爲「全部收起」；再點一次收起到只剩標題欄；「展開」一步恢復完整面板。
- 底部提供「清空已完成」；每個直接父會話最多保留 200 條記錄，超出時淘汰最舊的已結束行。
- 頁面刷新或服務重啓後面板自動恢復（常駐組合）。
- 視口寬度 ≤768px 時默認不彈出面板，側欄按鈕仍可手動打開。
安裝與啓用¶
推薦通過 npm 一行安裝（已發佈 v0.3.0，GitHub Actions 構建並簽名，SLSA provenance 可驗）：
dsh plugin --profile <your-profile> add @leetoners/dsh-ui-subagent-monitor
也可從 GitHub 直裝：
dsh plugin --profile <your-profile> add github:Mombrane/dsh-subagent-monitor
首次從 GitHub 安裝若提示允許構建腳本，按提示在 profile 的 pnpm-workspace.yaml 中確認即可。
安裝完成後重啓 dsh web 生效。側欄底部出現「子代理」入口，點擊即可打開右上角監視面板。
典型用法¶
1、在主會話中派生子代理（如 spawn 或 one-shot），保持當前頁面不切換。右上角面板會列出當前會話直接派生的子代理，運行中項顯示秒錶與 token 明細。
2、點擊某張卡片的「打開對話」進入子代理會話。面板切換爲該子會話直接派生的下一層子代理；需要返回時點擊「← 上一層」。
3、並行派生多個子代理時，通過頂部狀態柱狀圖與底部「運行 · 完成 · 異常」計數快速掌握整體進度；任務結束後用「清空已完成」整理列表。
4、關注上下文與緩存時，查看頂部三枚環形圖：主會話當前窗口占用、緩存命中率，以及各卡片的輸入 / 輸出與上下文利用率。
適用場景與注意¶
適合誰： 經常在 DSH Web 中用子代理並行探索代碼庫、拆分子任務，且需要在主界面一眼掌握各子代理狀態與 token 用量的開發者。
使用前注意：
- 插件以當前
dsh進程權限運行，安裝前應檢查源碼與 MIT 許可證。 - 監視路由
/api/subagent-monitor/snapshot無鑑權，勿暴露到公網。 - 用量與緩存數據依賴 provider 適配器上報，未適配時相關字段顯示「—」。
- 「完成」（即時觀測成功）與「已結束」（重啓前歷史、結局未知）含義不同，見上文狀態表。
如需二次開發，可將倉庫 src/ 內聯到 DSH 源碼樹，詳見 GitHub README 中的方式 C；設計決策與數據流見倉庫內 ARCHITECTURE.md。
鏈接¶
- SkillHub 目錄頁：https://www.skillhub.cn/plugins/Mombrane/dsh-subagent-monitor
- GitHub 倉庫：https://github.com/Mombrane/dsh-subagent-monitor（約 18 stars，已收錄 awesome-dsh-plugin）
dsh-subagent-monitor 把子代理運行態從「逐個點進會話查看」收斂到一塊可拖動、可逐層下鑽的即時面板，適合作爲 DSH Web 多子代理工作流的日常監視工具。
