前言¶
在 DeepSeek Harness（dsh）裏跑一條複雜對話時，主 agent 會派出多個 subagent，工具調用和模型回覆交錯進行。事後若要判斷「卡在哪一步、是誰先出問題、subagent 交回了什麼」，往往只能翻日誌或會話記錄，難以把主從關係和時間順序放在一張圖上對照。
dsh-stuck-monitor 是社區維護者 jwang513 提供的被動記錄插件：它不干預 agent 行爲，只訂閱 dsh 事件流，按時間彙總主 agent 與各 subagent 的動作，在 Web 界面的「會話復盤」標籤裏回放，並對可規則化的失敗與卡住點做標記；需要時再按需生成 AI 前因後果復盤。
這是什麼¶
一句話來說：被動 dsh 記錄器——在同一時間線上重放主 agent 與全部 subagent，標出卡住位置，並可按需寫入 AI 因果復盤。
- 維護者：jwang513
- 倉庫：github.com/jwang513/dsh-stuck-monitor
- 社區目錄：skillhub.cn/plugins/jwang513/dsh-stuck-monitor
- 許可證：MIT（見倉庫 README）
- package.json 版本：0.5.0
插件只記錄，不提醒、不糾正、不攔截 agent。
在哪裏查看復盤¶
打開任意會話，在標題下方視圖欄選擇 對話 / 軌跡 / 會話復盤，點 會話復盤。顯示的是當前會話；會話進行中大約每 5 秒刷新一次。
會話總覽頁¶
- 整體復盤（AI）：發生了什麼、最終結果、問題從哪一步開始、前因後果、各 subagent 的作用。
- 時間線：主 agent 與每個 subagent 各一條泳道；色塊表示一段工作，紅點爲問題、黃點爲外部阻攔、灰色斜紋爲探查區段，虛線表示派出 subagent；可點 subagent 名字或色塊進入其頁面。
- 參與者：按「在主 agent 哪一段被派出」分組；含運行狀態、問題數、是否已復盤。
- 主 agent 的經過：分段列表，展開可見各時間點事件；「派出 / 收到結果」旁可跳轉到對應 subagent。
subagent 頁¶
從參與者列表進入；若在 subagent 自己的會話裏打開該標籤，會直接顯示此頁。
- 來龍去脈：派出時刻與主 agent 段、完整任務、結束方式與時間、交回內容及對應主 agent 段（可點擊跳轉）。
- 它自己的復盤（AI）
- 它自己的時間線：豎線爲時間點（模型回覆或工具調用），紅色表示出錯或有問題；空白處拖動可框選時間段，下方「經過」僅顯示該區間。
- 經過：各事件的時間、內容、參數、結果或報錯原文。
導出 Markdown：總覽頁導出整個會話（含全部 subagent）；subagent 頁只導出該 subagent；已生成的 AI 復盤會一併導出。文件名形如 replay_2026-11-05_140200_session.md。
自動標出的問題類型¶
標記只針對「確實失敗或卡住」，不評價工作方式是否像偷懶。分三類。
紅點：問題（agent 自身失敗或卡住）¶
| 問題 | 判斷方式 |
|---|---|
| 原地重複 | 同一調用連續 3 次以上，參數相同且返回結果也相同（結果在變如輪詢狀態，不算） |
| 來回打轉 | 2–4 個調用組成循環重複 3 輪以上，每輪結果相同（如改代碼→跑測試且結果在變，不算） |
| 同一錯誤反覆出現 | 同一工具同類錯誤 3 次以上（行號、路徑不同仍算同類） |
| 輸出撞上限 | 模型回覆寫到一半因 max-tokens 截斷 |
| 沒有正常結束 | subagent 以出錯或拒絕執行結束 |
黃點：外部阻攔¶
| 情況 | 判斷方式 |
|---|---|
| 操作被拒絕 | 報錯含 approval / rejected / denied / permission 等 |
| 模型請求失敗 | 網絡、限流或服務端錯誤 |
| 被取消 | 用戶手動停止或上級 agent 取消 |
灰色斜紋：工作方式記錄（非問題）¶
| 記錄 | 判斷方式 |
|---|---|
| 探查 | 連續 15 次以上只讀調用（read、grep、glob、search、ls、web_* 等） |
| 長思考 | 單次回覆推理超過 8000 tokens（真正撐爆由「輸出撞上限」標出） |
是否合理需結合任務判斷；AI 復盤會結合任務上下文說明。
AI 復盤¶
- 每個 subagent 可單獨生成復盤；整體復盤會複用已生成的 subagent 復盤，未生成的用壓縮後的經過，避免長會話超出模型輸入上限，且只爲選定部分付費。
- 僅點擊按鈕時生成，不會自動調用模型。
- 默認使用當前對話所用模型；可在配置中指定其他模型。調用走 dsh 自有模型服務（與會話標題自動生成同路徑）。
- 結果保存在本地；會話有新進展時，復盤卡片會提示「可重新生成」。
環境與安裝¶
要求 Node.js 24 或以上；README 註明在 dsh 0.2.1-rc.5 上開發與測試。
先停止正在運行的 dsh，在 dsh 項目目錄執行：
npx dsh plugin --profile web add https://github.com/jwang513/dsh-stuck-monitor
npx dsh web
將 --profile web 換成你實際使用的 profile 名。若已安裝，重啓 npx dsh web 即可。
配置¶
在 ~/.dsh/profiles/<profile>/cordis.patch.yml 末尾追加（Windows 上 ~ 爲 C:\Users\<用戶名>）：
- id: stuck-monitor
name: 'dsh-stuck-monitor'
config:
outputDir: '' # 記錄目錄，留空表示 ~/.dsh/stuck-monitor
aiProvider: '' # AI 復盤用的模型；留空表示用對話本身的模型
aiModel: ''
aiMaxTokens: 6000
repeatThreshold: 3 # 下面這些是問題判斷的閾值
cycleMinRepeats: 2
repeatedErrorThreshold: 3
readOnlyStretch: 15
reasoningWarnTokens: 8000
記錄文件位置¶
默認在 ~/.dsh/stuck-monitor/sessions/（可通過 outputDir 修改）。每次對話約三個文件：
<id>.session.json：完整事件流、分段與問題<id>.meta.json：列表摘要<id>.ai.json：AI 復盤（生成後纔有；整體與各 subagent 復盤均在此）
安全與原理簡述¶
面板數據接口 /stuck-monitor/session、/stuck-monitor/analyze 使用 dsh 登錄與來源校驗：無 dsh 鏈接 token 返回 401，跨站請求返回 403。
插件主要監聽 agent/pre-step、agent/request、agent/assistant-stream、tools/pre-execute / tools/post-execute、agent/request-error、subagent/start / subagent/end、agent/turn-stopping 等事件；lib/index.js 彙總並約每 5 秒寫盤，lib/detect.js 實現問題規則，lib/analyze.js 負責 AI 復盤，client/client.js 提供「會話復盤」標籤與 Markdown 導出。
適用場景與注意¶
適合需要事後對照主從 agent 時間線、定位重複調用或權限類卡點的 dsh 用戶與智能體開發者。問題檢測基於行爲模式，語義上「偏離任務」需依賴 AI 復盤；思考內容每輪僅保留首尾各約 400 字，正文最多約 1500 字；寫盤間隔約 5 秒，崩潰前最後幾秒可能丟失；插件安裝前已結束的會話無記錄；用戶以 /skill名 直接調用的 skill 不計入工具調用，但用戶原話會出現在時間線。
插件以當前 dsh 進程權限運行，安裝前請自行審閱源碼與 MIT 許可證。
結尾¶
dsh-stuck-monitor 把一次對話裏主 agent 與全部 subagent 的動作收到同一時間線，用規則標出可識別的卡住點，並在需要時用 AI 寫清前因後果，適合作爲 DSH 生態中的被動觀測與復盤工具。
- 目錄頁：https://www.skillhub.cn/plugins/jwang513/dsh-stuck-monitor
- GitHub：https://github.com/jwang513/dsh-stuck-monitor
