前言¶

在 DeepSeek Harness（DSH）裏跑 agent 時，常見問題不是模型不會寫代碼，而是行爲上「原地打轉」：同一個文件改到第三遍、同一種報錯喫第二遍、改完代碼卻不跑任何驗證就進入下一步。AGENTS.md 裏的五條閘門、以及 stuck-gate 技能，本質上是提示詞層約束——模型得先想起「我卡住了」，條款才生效；而卡住時恰恰是想不起來的時候。

dsh-better-debug 由 Leonlee114514 維護，分類爲工作流。它不看模型說了什麼，只看工具調用軌跡；一旦行爲符合「打轉」，就在下一步工具調用之前往 messages 尾部追加一條 user 提醒（不用 reject，避免整 turn 變成 no-op）。社區目錄頁：skillhub 插件頁。

這是什麼¶

一句話：把卡住檢測寫成 DSH 插件裏的監聽器與閾值，用可觀測的編輯、報錯、驗證行爲觸發提醒，並可選附帶 bundled stuck-gate 技能與只讀統計面板。

當前包版本 0.1.1（見倉庫 package.json），許可證 MIT，要求 Node >=20、DSH >=0.2.1-rc.5。

三個行爲信號¶

插件用三條信號刻畫「打轉」，默認值可在配置裏調整（調小更容易觸發，調大更寬鬆）。

錯誤指紋會做歸一化（例如十六進制、C:\Users\... 路徑、純數字），因此「行號變了但異常類不變」仍算同一錯。

搜索類工具（命中即視爲拿到外部先驗，B 與 C 同時解除）：web_search、research、advanced_search、multi_search、platform_search、domain_search、cache_search、video_search。

驗證類工具（A 與 C 解除）：ops_bash、lsp_diagnostics。

每條信號每個 turn 最多觸發一次；且上一次提醒之後必須出現新事實（再多寫一次文件、再喫一個錯）纔會再次開口。A 或 B 觸發時會把 C 標成已觸發，避免重複囉嗦。

刻意不做的事¶

• 不做「我猜是」類措辭檢測（留給 stuck-gate 技能自檢）。
• 不做收尾探針清零（歸 dsh-turn-cleanup）。
• 不對子會話生效：header.origin === 'subagent' 或 delegationDepth > 0 時跳過。

D 段例外（用戶明確要快試）¶

對齊 AGENTS.md D 條：本 turn 用戶原話命中 /別搜|不要搜|不用搜|先別搜|直接改|快速試|別折騰|先試試/ 時，整 turn 不注入。只認 source.kind === 'user' 的消息，插件自己注入的不算。

自帶 stuck-gate 技能¶

包內 assets/stuck-gate/SKILL.md 通過 inject: ["skills"] 註冊爲 bundled 技能（source: "bundled"，rank: 600）。裝完即在模型可見技能目錄中，無需手動拷貝。

想改閘門文案而不改插件代碼：在 ~/.dsh/skills/stuck-gate/SKILL.md 放一份即可覆蓋（rank 400 的用戶全局技能優先於本插件默認）。宿主若無 skills 服務，註冊會跳過並記日誌，閘門邏輯仍運行。

增益面板（只讀）¶

設置頁 → better-debug，或訪問 http://<web-origin>/better-debug。iframe 每 5 秒刷新，只展示日誌聚合，不改變閘門行爲。

• 閘門觸發次數：按 A / B / C 及組合從 inject 行統計。
• 覆蓋會話：session= 去重，看影響多少會話與注入字符量。
• 注入後換動作：依賴 outcome 行，看提醒後第一條 tool/call 是否轉向驗證 / 搜索（class=verify|search|edit|other）。

關閉面板：config: { panel: false }，路由不掛，/better-debug 返回 404，閘門不受影響。面板通過 ctx.inject(['webServer'], …) 動態掛載，未寫進 export const inject，以免無 webServer 的宿主連閘門都裝不上。

安裝與啓用¶

README 給出的方式是 local-pkgs + profile link，不是 dsh plugin add 一類命令，請按原文操作：

# 1. 放進 local-pkgs（可與 dsh-turn-cleanup 並列）
cp -r dsh-better-debug ~/.dsh/local-pkgs/

# 2. profile 里加 link 依賴
cd ~/.dsh/profiles/desktop
# package.json → dependencies 加一行：
#   "dsh-better-debug": "link:../../local-pkgs/dsh-better-debug"
# package.json → dsh.profile.bundles 數組末尾加：
#   "dsh-better-debug"

# 3. 讓 bundle patch 掛上（bundles 已含它時 dsh 會自動 apply 包內 cordis.patch.yml）
#    或在 profile 的 cordis.patch.yml 手寫：
#      - id: better-debug
#        name: dsh-better-debug
#        inject: [skills]
#        config: { enabled: true }

# 4. 重啓 DSH（inject 含 skills 屬結構性變更，HMR 未必生效）

插件以當前 DSH 進程權限運行；安裝前請閱讀倉庫源碼與 MIT 許可證，自行確認可信。

配置示例¶

在 cordis.patch.yml 或 profile 合併結果中：

- id: better-debug
  name: dsh-better-debug
  inject: [skills]
  config:
    enabled: true
    repeatEditThreshold: 3      # A：同一文件改幾次算打轉
    repeatErrorThreshold: 2     # B：同一類報錯幾次算打轉
    noVerifySteps: 2            # C：改完幾步沒驗證算打轉
    logFile: ""                 # 絕對路徑；空 = 不落盤（ctx.logger 僅 stdout）
    panel: true                 # false 則不掛 /better-debug

enabled: false 時不註冊 listener。

典型用法：確認插件已加載並在幹活¶

1. 將 logFile 設爲絕對路徑，例如 ~/.dsh/logs/better-debug.log（Windows 可用 C:/Users/<you>/.dsh/logs/better-debug.log）。
2. 加載後應出現一行 apply pid=… logFile=… A=3 B=2 C=2——這是證明插件掛上的關鍵證據（僅 ctx.logger 時事後 grep Electron stdout 往往找不到）。
3. 打轉時應出現類似：

   inject session=… turn=32 step=98 signals=A chars=254 files=1 worstEdits=3 worstErrors=0 searched=false

files=1 worstEdits=3 才表示「盯着一個文件改三遍」；隨後通常還有 outcome 行記錄注入後第一步工具類別。
4. 面板上的「換動作」只看有 outcome 的樣本；持續很低時應考慮改文案或閾值，而不是盲目加信號。

倉庫內本地自測（不依賴 DSH 運行時）：

npm run verify

含語法檢查、test/sim.mjs（15 個閘門用例）、test/panel.mjs（17 個日誌與面板用例）。

適用場景與注意¶

適合誰：長期用 DSH desktop profile、希望 agent 在「反覆改同一處 / 重複同一錯 / 改完不驗證」時自動被提醒拉回反饋迴路的主會話開發者。

邊界（README 已寫明）：

• 「同一文件」按絕對路徑；刪了重建同名路徑仍可能累計。
• ops_bash 只看工具名，不區分裏面是 npm test 還是 ls——寧可漏判驗證，也不誤判。
• 子 agent 各自打轉不會在本插件層攔截；lead 主會話計數仍有效。
• logFile 爲空時面板統計爲 0，不能當監控後端。

DSH 生態是「一切皆插件」；skillhub.cn 上的目錄爲社區站點，與 DeepSeek / 幻方無官方從屬關係。

結尾¶

若你已經在用提示詞版的卡住條款，卻經常看到模型嘴上答應、手上繼續第三次 write 或第四次相同報錯，dsh-better-debug 提供的是行爲側的補充：閾值可配、提醒可冪等、可選面板用 outcome 觀察是否真的換動作。

• 目錄頁：https://www.skillhub.cn/plugins/Leonlee114514/dsh-better-debug
• 源碼與文檔：https://github.com/Leonlee114514/dsh-better-debug