前言¶
在 DeepSeek Harness（DSH）里跑本地小模型做 Agent 时，常见一类故障：模型反复发起「工具名 + 参数」完全相同的调用，且每次返回的结果也一样，主循环却停不下来。这类问题不一定出在模型能力本身，而是缺少对「同一调用、同一结果」的计数与熔断。
dshx-loop-guard 是社区维护者 callaumyan-design 发布的 DSH 工作流类插件。它只订阅 DSH 公开的 agent/request、tools/pre-execute、tools/post-execute 事件，不改动 Agent 主循环，在工具执行前后做指纹比对与阈值控制，从而在达到配置上限时提醒或拒绝继续调用。
这是什么¶
插件仓库：callaumyan-design/dshx-loop-guard。目录页：SkillHub 插件条目。
一句话定位：检测并停止「相同工具调用反复得到完全相同结果」的 Agent 循环，主要面向本地小模型场景。实现为纯 JavaScript（index.js + cordis.patch.yml），无构建步骤。
判定规则¶
计数按 Agent、按「轮」进行。README 中的规则如下。
- 调用指纹：工具名 + 参数（键顺序无关）。
- 相同结果重复：同一指纹连续得到完全相同的结果时，第
warnAt次在结果后附加提醒，第stopAt次直接拒绝该调用。 - 单指纹硬上限：同一指纹在一轮内执行满
hardLimit次（不论结果是否相同）后拒绝。 - 单轮总调用数：一轮内工具调用总数超过
maxCallsPerTurn时拒绝；0表示不限制。 - 拒绝次数上限：一轮内被拒绝达到
maxDenials次后中止本轮。
改完文件再跑同一条测试命令不算循环：结果变了，相关计数会清零。
配置¶
在插件自带的 cordis.patch.yml 中可改下列字段（安装后随插件 bundle 生效，具体合并方式以你当前 DSH / Cordis 配置为准）。
| 字段 | 默认 | 说明 |
|---|---|---|
providers |
['local'] |
只对这些 provider 生效；空数组表示对所有模型生效 |
warnAt |
3 |
相同结果重复达到此次数时附加提醒 |
stopAt |
5 |
相同结果重复达到此次数时拒绝 |
hardLimit |
12 |
同一指纹一轮内最大执行次数 |
maxCallsPerTurn |
0 |
一轮最大工具调用总数，0 为不限 |
maxDenials |
3 |
一轮内最大拒绝次数，达到后中止本轮 |
默认仅对 local provider 生效；若你在 Web 或 Desktop 里用其他 provider 跑 Agent，需要按 README 调整 providers。
安装与启用¶
安装命令须使用 README 原文（按 profile 二选一）。安装后需重启 DSH；package.json 中 requiresRestart 为 true。
# Web profile
dsh plugin --profile web add github:callaumyan-design/dshx-loop-guard
# Desktop（使用 DSH Desktop 自带的 dsh 命令；先从托盘完全退出 Desktop）
dsh plugin --profile desktop add github:callaumyan-design/dshx-loop-guard
卸载：
dsh plugin --profile <profile> remove dshx-loop-guard
package.json 声明 marketplace 支持 headless、web、desktop 三种 profile；README 的安装示例仅给出 web 与 desktop，headless 可按同一 add github:... 形式对照你的环境文档选用对应 profile。
典型用法¶
插件无单独 CLI 示例：安装并重启后，在已配置的 provider（默认 local）上正常跑 Agent 即可。当模型陷入「同工具、同参数、同结果」的循环时，你会先看到 warnAt 之后的提醒，再在 stopAt 或 hardLimit / maxCallsPerTurn / maxDenials 触发时收到拒绝或本轮中止。
若你依赖「同一命令多次执行直到输出变化」（例如改代码后重跑测试），只要工具返回结果与上一轮不同，计数会清零，不会被误判为死循环。
适用场景与注意¶
适合谁：主要在 DSH 上用本地小模型做工具型 Agent，且遇到过重复 read_file、grep 等同参调用、同结果返回的情况。
兼容性：README 写明在 DeepSeek Harness 0.2.0-rc.2（desktop / web profile）上开发和使用；插件版本 1.0.0，许可证 MIT。
安全与权限：插件以当前 DSH 进程权限运行，可拦截或修改工具执行路径上的行为。安装前建议阅读 仓库源码 与许可证，确认与你的工作流一致。社区目录站点 SkillHub 与 DeepSeek / 幻方无官方从属关系，插件来源以 GitHub 仓库为准。
结尾¶
dshx-loop-guard 用事件钩子做「同参同结果」与单轮调用上限的熔断，不改 Agent 主循环，适合给本地小模型加一层可配置的循环防护。需要安装命令与字段默认值时，以 README 为准。
- 目录页：https://www.skillhub.cn/plugins/callaumyan-design/dshx-loop-guard
- GitHub：https://github.com/callaumyan-design/dshx-loop-guard
