dsh-loop-guard：DeepSeek Harness 死循环断路器

DeepSeek Harness (DSH) 插件生态强调一切皆插件。但在实际使用中，agent 往往会陷入某种形式的死循环，例如模型反复输出固定的文本片段，导致任务在后台无限空转却无实质性进展。本文介绍 dsh-loop-guard，用于检测并阻断这类单条消息内部的重复退化。

问题背景¶

DeepSeek 的 deepseek-v4.1-flash 模型在 “thinking” 模式下存在一个特定的故障场景：模型可能反复吐出极少量的固定文本（如 “好。写。执行。”），且不产生任何工具调用。这通常由以下因素叠加导致：

thinking 模式开启：思维链体量最大，重复轨迹最长。
tools 场景下的全量回传：当请求带 tools 时，历史所有轮次的 reasoning_content 必须完整传回，导致重复轨迹被不断强化。
KV Cache 压缩：该模型的核心卖点，它把低熵的重复内容压缩得几乎无损，却抹掉了能打破循环的边缘信号。
上下文压缩失效：循环中单条消息 token 极少，上下文不增长，导致针对总量触发的压缩机制全程旁观。

任何基于”比较前后两条消息是否相同”的传统守卫都够不着它。循环本质上发生在单条 assistant 消息内部。

核心功能¶

该插件通过”窗口重复密度”作为主判据，覆盖两种常见的循环形态：

单行刷屏：单行文本重复次数极高（如 </parameter> 重复 1729 次）。
多标记交替滚动：不同标记（输出、生成、工具调用、好。）交替出现，单行重复占比低，但整体密度高。

插件会在检测到退化时向下一步注入破环提醒，阻止 agent 循环。

安装与启用¶

安装前需确保环境满足 Node >= 20。

1. 通过命令安装插件¶

使用 DSH 插件命令将包加入 profile 依赖：

dsh plugin --profile <你的 profile> add github:GRUST303/dsh-loop-guard

2. 配置 Bundle（关键步骤）¶

执行上述命令只是将包写入 dependencies。DSH 依赖 dsh.profile.bundles 字段决定加载哪些插件。必须在 profile 的 package.json 中显式声明：

{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "dsh-loop-guard"  // 必须在此列出
      ]
    }
  }
}

3. 重启 Profile¶

Bundle 层在启动时被读取并合成 cordis.yml，必须完整重启 profile 才能生效，HMR 不够。

配置¶

配置通过 profile 插件行的 config 段提供。以下是典型的配置示例：

- id: loop-guard
  name: dsh-loop-guard
  config:
    preset: balanced
    repeatDensity: 0.35     # 主判据：窗口重复密度阈值
    window: 12              # 滑动窗口行数
    lineRepeatThreshold: 6  # 单行重复次数阈值（需同时满足占比 ≥ 50%）
    contextLineRepeatThreshold: 20   # 历史污染阈值
    minChars: 120           # 短于此长度的消息不参与判定
    crossStepThreshold: 3   # 跨步重复次数
    debug: false            # 写入调试日志

配置修改后，必须重启 profile 生效。

档位说明¶

插件提供三个档位供选择：

conservative（保守）：密度阈值 0.5。适合大量输出表格或代码的场景，误报率最低。
balanced（平衡）：密度阈值 0.35（默认）。实测误报率极低，覆盖已观察到的所有循环形态。
aggressive（激进）：密度阈值 0.25。最早介入，轻微重复也会提醒，适合无人值守的长任务。

注意事项¶

不重写 LLM 请求参数：插件不会修改 temperature、presence_penalty 等参数，因为 DeepSeek 的 thinking 模式下这些参数不支持或无效。
不阻断、不重置：插件只注入提醒，不 veto、不 block 或重置会话。上游若拒绝该步，原样透传。
设置页渲染问题：插件声明了设置页槽位 settings.plugins.tab，但在 DSH 0.1.7-rc.2 版本上未渲染出来。请直接通过 config 段配置，核心功能不受影响。
依赖要求：需要 Node.js >= 20。依赖 @deepseek-ai/schemastery 用于配置校验，若缺失设置页不可用，但核心防循环功能仍正常工作。

总结¶

dsh-loop-guard 针对的是 DSH 生态中一种隐蔽且难以察觉的故障模式。通过在单条消息内部进行滑动窗口的密度检测，它能有效识别并阻断模型在 thinking 模式下因 KV Cache 压缩导致的无限重复空转，保障 agent 的稳定运行。

项目地址：https://github.com/GRUST303/dsh-loop-guard