前言¶

在 DeepSeek Harness (DSH) 的开发过程中，自主智能体在遇到工具故障、指令歧义或幻觉时，容易陷入无限重试循环。例如，反复读取同一目录、编辑相同代码行，或在输出流中不断重复相同文本。这种情况会迅速消耗 token 预算和 API 信用，却无法推进用户目标。dsh-agent-loop-guard 是一个为 DSH 设计的原生主机运行时插件，旨在拦截并阻断此类失控循环，防止资源浪费。

核心功能¶

插件通过以下机制实现闭环防护：

1. 进度感知工具调用守卫
   使用基于 epoch 的状态跟踪，仅在未检测到有意义的状态变更或新证据时，才阻断重复调用。这允许合法的迭代（如 read ➔ edit ➔ read ➔ edit）正常执行，避免误杀有效操作。

2. 助手输出循环阻断器
   实时检测流式文本中的重复行或 markdown 块。当连续生成内容超过阈值时，会强制取消会话生成，避免输出失控。

3. 零核心修改
   插件完全基于 Cordis 生命周期钩子实现，无需对 DeepSeek Harness 核心代码进行任何修改。

4. 企业隐私与 Token 遮蔽
   日志系统会自动遮蔽敏感凭证，如 Bearer token、密码、cookie 及查询参数中的 secret，将它们替换为 [redacted]，防止敏感信息泄露。

5. 原生 WebUI 设置与遥测
   提供原生 WebUI 配置入口，支持插件设置与遥测数据上报。

安装与启用¶

插件以当前 DSH 进程的权限运行，安装前请确保环境满足依赖要求。

1. 环境检查
   确保系统已安装 Node.js 20 或更高版本。
   确保已安装 DeepSeek Harness 及其核心依赖。

2. 安装方法
   由于未提供直接的安装命令，请通过官方插件目录进行安装：
   访问目录地址：https://www.skillhub.cn/plugins/GooDAnDReaDY/dsh-agent-loop-guard
   在目录页面中完成插件的添加与启用操作。

3. 依赖校验
   安装过程中，DSH 会自动检查以下对等依赖是否已满足：

   • @deepseek-ai/cordis
   • @deepseek-ai/schemastery
   • @deepseek-ai/dsh-settings

典型用法¶

插件通过停止词和配置参数来控制循环行为。

1. 触发阻断的停止词
   在用户消息分析阶段，插件支持多种停止词来立即触发拒绝执行：

   • stop, halt, cancel
   • прекрати (俄语：停止)
   • ответь (俄语：回答)
   • петля (俄语：循环)

2. 默认配置参数
   插件内置了默认的循环限制策略，通常无需修改即可生效：

   • 最大重复调用次数：同一组调用中，默认限制为 5 次。
   • 最大工具尝试次数：单轮对话中，默认限制为 64 次非生产性工具尝试。

3. 配置方式
   所有设置均可通过 WebUI 进行可视化配置：
   进入 WebUI 设置页面 -> 选择 Plugins -> 点击 Plugin Settings。在此处调整循环阻断的具体阈值与行为。

适用场景与注意¶

该插件适用于任何需要防止智能体陷入死循环的场景，特别是长任务执行或自动化脚本开发中。

1. 运行权限
   插件以当前 DSH 进程的权限运行，这意味着它拥有与 DSH 相同的系统访问能力。在安装和启用前，请务必检查插件源码与许可证（MIT），确认其行为符合你的安全与合规要求。

2. 配置调整
   在生产环境中，建议根据具体任务的复杂度，适当调整 maxCallsPerRepeatGroup 和 maxToolAttemptsPerTurn 参数，以平衡安全性与任务灵活性。

结语¶

dsh-agent-loop-guard 提供了一种 Fail-Closed（失败-关闭）的运行时保护机制，帮助开发者构建更稳定、更可控的 DeepSeek Harness 智能体系统。

• 项目目录：https://www.skillhub.cn/plugins/GooDAnDReaDY/dsh-agent-loop-guard
• 源码仓库：https://github.com/GooDAnDReaDY/dsh-agent-loop-guard