dsh-loop-guard：结果感知循环检测器

在 DeepSeek Harness 工作流中，智能体常陷入重复调用相同工具且持续返回相同结果的死循环，导致步数与令牌的浪费。dsh-loop-guard 插件通过结果感知机制，在连续调用运行长度达到阈值时介入，提供提示性通知或直接拒绝后续相同调用。

核心功能¶

该插件为 DeepSeek Harness 提供结果感知的循环检测功能，核心包含以下三点：

1. 结果感知跟踪
   插件跟踪具有相同工具名、排序参数和结果内容的连续工具调用的运行长度。只有完全相同的“工具名 + 参数 + 结果”才会计入循环计数，因此合法的状态轮询或文件重读不会误触发。

2. 软硬阶段阻断
   * 软阶段（Advisory）：当运行长度达到 softThreshold（默认 4）时，插件会注入提示性通知，告知模型当前调用已重复，并提示在硬阈值触发时将被拒绝。
   * 硬阶段（Hard Stop）：当运行长度达到 hardThreshold（默认 8）时，插件会单调拒绝下一个相同的工具调用，并附带修正反馈。模型需改变行动才能解除阻断。

3. 用户干预重置
   当 source.kind === 'user' 时，链条会被重置。这意味着跨用户消息的重复调用不会被视为循环，确保用户手动干预后能继续操作。

安装与启用¶

使用官方安装命令将插件添加到指定配置文件：

dsh plugin --profile <name> add github:erdholion/dsh-loop-guard

也可以从本地检出目录安装：

dsh plugin --profile <name> add ./dsh-loop-guard

配置¶

在 DSH 配置文件中添加插件定义，需注意无效配置会在插件加载时抛出错误：

- id: loop-guard
  name: dsh-loop-guard
  config:
    softThreshold: 4     # 0 禁用提示，默认 4
    hardThreshold: 8     # 0 禁用拒绝，必须大于软阈值，默认 8
    resultHashChars: 4000 # 参与哈希的结果序列前缀长度

典型用法与场景¶

该插件特别适用于需要处理不确定返回值或状态变更的场景：

• 合法轮询：允许具有不同结果的轮询（例如作业状态检查）。只要结果发生变化，循环计数不会增加，不会误判为死循环。
• 状态恢复：允许具有不同结果的重新读取（例如编辑后重新读取文件）。
• 组合使用：可与官方的 @deepseek-ai/dsh-repeat-tool-reminder 一起使用。前者负责在参数相同时提供早期提醒，后者负责在结果相同时进行硬性拒绝。

注意事项¶

• 配置约束：硬阈值必须严格大于软阈值，否则插件加载会报错。
• 阻断机制：硬阶段触发的拒绝是一个正常的错误结果，会返回给模型修正反馈。这对于前端将提供者 4xx 错误视为致命的情况尤为重要。
• 通知来源：插件注入的通知来源为插件本身，不会触发链条重置。

该插件通过结果感知机制，有效避免了智能体陷入无信息产出的重复调用循环，提升资源利用效率。