前言¶
在使用 DeepSeek Harness（DSH）构建智能体时，模型有时会陷入“推理退化”的状态：它不断产生 reasoning-delta，却没有任何工具调用，甚至只输出低熵的重复短句（如 好。执行。好。）。DSH 自带的 guard/ 家族（如 guard/timeout-policy 和 guard/repeat-tool-reminder）主要监控工具调用，无法捕捉这种“零工具、纯推理”的循环。结果就是回合永远无法 settle，界面显示“思考中”，但任务实际卡死，只能手动中止。
是什么¶
mrweicodes/dsh-loop-guard 是一个为 DSH 提供的思考循环守护插件。当检测到模型陷入这种不产出结果的退化循环时，它会自动从 llm/stream 瀑布流内部切断当前调用，并注入纠正提示，让任务继续向下执行，无需人工干预。
- 维护者: MrWeiCodes
- 许可: MIT
- 核心价值: 解决“只思考不做事”的死循环，且不中断会话流程。
核心功能¶
- 五层检测机制: 覆盖纯推理空转、复述上一步材料、可见输出周期循环、可见输出短语重排、推理内部短语重排。
- 流内切断: 不依赖“调用结束后”的判定，直接在流内部检测并截断，能处理“永不结束的回合”。
- 任务不中断: 切断只影响当前调用，回合以正常完成（
completed）收尾，会话存活，工具调用结果保留，可直接继续后续任务。 - 低误报率: 实测在 119 个有产出的调用中零误报；在 735 个会话扫描中误判 12 个（已被集中度护栏挡住）。
- 精确判据: 使用逐字周期和跨调用复述作为判定依据，而非时长或简单比率。
- 行为克制: 默认不自动重试，防止将退化模型再次喂入循环；注入提示仅要求“继续完成任务”，不引导其直接收尾。
- 离线分析器: 提供
tools/analyze-session.mjs，可复用运行时检测器对历史会话进行回放分析。 - 可观测: 切断时会写入 warn 日志，并在轨迹视图中显示注入的提示。
安装¶
本插件依赖 DSH 的 llm/stream 瀑布流特性，需 DSH 0.1.2-rc.1 及以上版本。
安装命令：
dsh plugin --profile web add @mrweicodes/dsh-loop-guard
注意：npm 上存在同名包 dsh-loop-guard（不带 scope），与本插件无关，请认准 @mrweicodes/dsh-loop-guard。
使用¶
插件开箱即用，无需额外配置即可拦截常见的推理退化循环。默认配置下，它会自动打断纯推理空转和可见输出的刷屏式重复。
如需在切断后自动继续执行，可在配置中启用 resumeAfterBreak：
- id: loop-guard
config:
resumeAfterBreak: true
注意事项¶
- 自动续跑慎用：默认配置下，切断后任务会停留在
idle状态，等待用户确认。开启resumeAfterBreak后会自动进入下一个回合。由于切断发生在模型尚未自主行动时，无人值守的长任务建议开启此选项，但需留意切断后的纠正提示内容。 - DSH 版本要求：必须使用支持
llm/stream的 DSH 版本。
结语¶
对于需要长时间运行、高 reasoning effort 的 DSH 工作流，dsh-loop-guard 是解决“思考死锁”的有效手段。它通过流内干预保证了任务的连续性，配合低误报率和离线分析工具，能够显著提升智能体运行的稳定性。
- 插件目录: https://www.skillhub.cn/plugins/MrWeiCodes/dsh-loop-guard
- GitHub 仓库: https://github.com/MrWeiCodes/dsh-loop-guard
