前言¶

在 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