前言¶
在 DeepSeek Harness（DSH）里跑 Agent，常见两类失败并不是「上下文太长」：一是同一目标反复改脚本、跑命令，工具调用堆到十几轮，界面只剩「一直在思考」；二是长回合里一路调工具却不对用户说半句进展。装上下文压缩类插件往往治不了前者——上下文再短，模型仍可能在同一个坑里换姿势继续试。下面介绍工作流插件 dsh-loop-guard（维护者 xfgil）：在单轮内记账工具调用，撞墙时拒绝继续同路试错并逼模型转向用户；长任务沉默时在合适节点注入进展提醒。
这是什么¶
dsh-loop-guard 是 DSH 上的通用工作流插件，npm 包名 @qzsecftb/dsh-loop-guard，当前版本 0.1.0，MIT 许可证。它挂在宿主通用钩子（agent/pre-step 与 ctx.tools.guard()）上，不修改 system prompt，不跨轮记仇，也不判断任务该不该做——只处理「原地打转」和「太久没对用户出声」两类现象。README 中给出的实测背景包括：362 秒、16 次工具调用的改写循环，以及 847 秒、59 次工具调用、中间零输出的长回合。
核心功能¶
撞墙叫停¶
每次工具调用前记账；命中任一条件则拒绝本次调用，并把一句带「别的出路」的说明当作工具结果喂回模型（默认行为下模型倾向于继续试，插件刻意要求直接回复用户：已试过什么、卡在哪、需要用户决定什么）。
判据与默认阈值如下（同一目标指文件路径或命令，不要求参数全等——改写循环里每版脚本内容不同，但目标未变仍会累计）：
| 条件 | 默认 |
|---|---|
| 同一目标被动次数 | 6（maxSameTarget） |
| 完全相同的调用重复 | 3（maxSameCall） |
| 连续失败（换工具也算） | 5（maxFailures） |
| 单轮工具调用总数硬顶 | 40（maxCallsPerTurn） |
叫停后同一轮可配置不再重复提示（muteAfterTrip，默认 true）。守卫自身出错时一律放行，避免把整个工具链卡死。
长任务播报¶
若本轮开始至今已过去默认 180 秒（narrateAfterMs，0 表示关闭），且尚未对用户说过正文，则在下一步注入一句提醒。判据是本轮起点至今的时长，不是「距上次播报多久」——避免一次超长工具调用把间隔逻辑整段跳过。若 Agent 已在同步进展，则不再催。两次提醒的最小间隔默认 240 秒（narrateEveryMs）。
观测¶
只读接口 GET /loop-guard 返回累计统计与当前轮账本；文档明确说明没有「停用/重启」类一键遥控——插件目的是减少用户被晾着，而不是远程开关。
安装与启用¶
官方安装命令：
dsh plugin add dsh-loop-guard --profile <你的 profile>
也可手动：将仓库放到本地目录，在 profile 的 package.json 中增加依赖并 link，例如：
"dependencies": { "dsh-loop-guard": "link:D:/Plugins/dsh-loop-guard" }
并把 dsh-loop-guard 加入 dsh.profile.bundles。插件零依赖，不碰 QQ / 人格 / 渠道相关代码，对所有会话一视同仁（网页、subagent 等）。
支持的 DSH 版本：>=0.2.1-rc.2。
配置¶
全部项有默认值，不配也能用。总开关 enabled 默认为 true。
| 键 | 默认 | 说明 |
|---|---|---|
enabled |
true |
总开关 |
maxSameTarget |
6 |
同一文件/命令被动几次算撞墙 |
maxSameCall |
3 |
完全相同调用几次算撞墙 |
maxFailures |
5 |
连续失败几次算路不通 |
maxCallsPerTurn |
40 |
单轮工具调用硬顶 |
muteAfterTrip |
true |
叫停后同一轮不再重复提示 |
narrateAfterMs |
180000 |
多久没出声就提醒（毫秒；0 = 不播报） |
narrateEveryMs |
240000 |
两次提醒最小间隔 |
典型用法与开发自测¶
日常用法是安装进 profile 后随 DSH 启动生效，无需额外命令。需要核对行为时，可请求 GET /loop-guard 查看账本与统计。
维护者在仓库内用纯函数自测（不依赖真实宿主）：
node test/selftest.mjs
其中一组断言复现了 2026-10-26 某次 turn 的调用序列，用于钉住「此类循环应在十几步内被叫停」的判据。
适用场景与注意¶
适合：长时间自主调工具的 DSH Agent 会话，尤其是容易出现「改脚本—运行—再改」或长回合零用户可见输出的场景。
边界（README 已写明）：不跨轮累计；不替 Agent 做任务价值判断；与 dsh-onebot-companion 等插件分属不同状态域——本插件只持有「本轮」指纹账本，轮末清账；单独安装应能完整工作，与其它插件配合时走可选注入，避免硬耦合读对方配置文件。
安全与信任：插件以当前 DSH 进程权限运行，安装前请自行审阅 GitHub 源码 与 MIT 许可证。Node 引擎要求 >=22。
结尾¶
dsh-loop-guard 用单轮内的上限、重复动作识别和长回合沉默播报，把两类真实出现过的「空转」和「闷头干」拦在工具层之前，并推动模型向用户交代进展或止损。社区目录页：skillhub.cn/plugins/xfgil/dsh-loop-guard；源码与完整说明：github.com/xfgil/dsh-loop-guard。
