# @goodandready/dsh-agent-loop-guard 中文文档

规范地址：https://npmcn.com/package/%40goodandready/dsh-agent-loop-guard/

版本：0\.3\.1
npm 元数据更新时间：2026-11-16T14:36:14.787Z
中文译文更新时间：2026-11-16T19:24:03.742Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40goodandready/dsh-agent-loop-guard
原文对照：https://npmcn.com/package/%40goodandready/dsh-agent-loop-guard/?lang=original
项目主页：https://github.com/GooDAnDReaDY/dsh-agent-loop-guard
源码仓库：https://github.com/GooDAnDReaDY/dsh-agent-loop-guard

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：215 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：@deepseek-ai/cordis ^4\.0\.1，@deepseek-ai/schemastery ^3\.18\.4，@deepseek-ai/dsh-settings ^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1
- 首次发布：2026-09-02T15:32:48.586Z
- 最新版本发布：2026-11-16T14:36:14.227Z
- 近 30 天下载量：2835（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 24 个）

## 中文简介

DeepSeek Harness的失败的运行时间工具调用循环守护.

## 安装

```sh
npm install @goodandready/dsh-agent-loop-guard
```

也可以使用：`pnpm add @goodandready/dsh-agent-loop-guard`、`yarn add @goodandready/dsh-agent-loop-guard`、`bun add @goodandready/dsh-agent-loop-guard`

## README

# 📦 @goodandready/dsh-agent-loop-guard

### 面向 DeepSeek Harness 的工具调用与智能体流式输出死循环熔断引擎

[![npm version](https://img.shields.io/npm/v/@goodandready/dsh-agent-loop-guard.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b)](https://www.npmjs.com/package/@goodandready/dsh-agent-loop-guard) [![license](https://img.shields.io/github/license/GooDAnDReaDY/dsh-agent-loop-guard.svg?style=for-the-badge&color=10b981&labelColor=064e3b)](https://npmcn.com/package/%40goodandready/dsh-agent-loop-guard/LICENSE) [![DSH Plugin](https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065)](https://github.com/topics/dsh-plugin) [![Node version](https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03)](https://nodejs.org/)

[![作者全部项目](https://img.shields.io/badge/%E4%BD%9C%E8%80%85%E5%85%A8%E9%83%A8%E9%A1%B9%E7%9B%AE-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e)](https://goodandready.app/)

[**🇬🇧 English**](https://npmcn.com/package/%40goodandready/dsh-agent-loop-guard/README.md) • [**🇷🇺 Русский**](https://npmcn.com/package/%40goodandready/dsh-agent-loop-guard/README.ru.md) • [**🇨🇳 中文说明**](https://npmcn.com/package/%40goodandready/dsh-agent-loop-guard/README.zh.md)

<table><tbody><tr><td align="center">⭐ <strong>如果您喜欢这个插件，请在 GitHub 上为它点亮 Star</strong> — 这能让我知道插件对您有用，并鼓励我继续开发和维护它。<br><br>🐛 <strong>如果您发现 Bug 或希望增加功能</strong>，请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议，并在后续版本中实现有价值的改进。</td></tr></tbody></table>

* * *

## ⚡ 核心定位与解决痛点

在自主 AI 智能体执行复杂多阶段研发任务时，遇到工具调用异常、指令模糊或模型幻觉时，极易陷入无限重试死循环：反复读取同一文件、以完全相同的参数反复调用工具却无实际产出，或在流式输出中无限重复相同的文本。此类死循环不仅迅速耗尽上下文 Token 预算，还会导致 UI 卡死与 API 额度浪费。

**`@goodandready/dsh-agent-loop-guard`** 是专为 DeepSeek Harness 打造的原生宿主运行时防死循环熔断插件，无需修改 DSH 核心代码即可提供全面防护：

1.  **进度感知型工具防循环（Progress-Aware Epochs）**：仅在工具调用未产生任何状态变化或新证据时判定为死循环。合法的有效迭代（如 `读` ➔ `写` ➔ `读` ➔ `写`）完全不受限制。
2.  **文本输出流防死循环（Assistant Output Guard）**：实时监测智能体流式输出，精准识别跨回合或跨步骤的单行及多行 Markdown 段落重复，安全中断生成而不破坏历史对话。
3.  **平滑降级至仅回答模式（Answer-Only Mode）**：触发死循环拦截时，向模型返回结构化 DSH 拒绝信息，强制要求模型输出文本向用户说明当前遇到的瓶颈。
4.  **目标配额守卫与无变化重复读取保护（Target Quota Guard）**：防止智能体针对单个文件无限空转消耗 Token（如重复读取未变动文件 20+ 次）。自动规范化跨平台路径（`extractTargetKey`），检测无变化内容哈希（`LOOP_GUARD_UNREFRESHED_READ`），施加单目标调用配额（`LOOP_GUARD_TARGET_QUOTA`），并提供非全局锁定的点对点拒绝机制。
5.  **工具重复报错拦截（Error Thrashing Guard）**：即使调用参数不同，也能归一化识别相同错误类型（`FS_ENOENT`、`EXIT_*`、`HTTP_*` 等）并阻断无效重试。
6.  **智能自纠正引导（Smart Steering）**：两阶段保护机制，在硬熔断前提供纠偏提示（`[LOOP_GUARD_STEER]`），引导模型自主改变策略。
7.  **拦截日志与一键诊断包**：环形遥测缓冲区记录最近事件及其调用链，并在设置面板提供一键复制诊断数据功能。
8.  **灵敏度预设（Presets）**：设置卡片提供 Strict / Balanced / Autonomous 一键预设切换。
9.  **日志隐私脱敏**：所有安全警告日志自动对 Token、密码、API Key 等敏感数据进行 `[redacted]` 掩码处理。

* * *

## 🏗️ 架构设计

```mermaid
graph TD
    subgraph DSH ["DeepSeek Harness 核心运行时"]
        Turn["智能体回合执行<br/>(LLM 推理与工具调用)"]
        Stream["助手流式输出<br/>(text-delta 与 block-end)"]
        UserStop["用户指令分析<br/>(停止词识别: stop, halt, 停止)"]
    end

    subgraph LoopGuard ["@goodandready/dsh-agent-loop-guard"]
        ToolInterceptor["ctx.tools.guard 拦截器<br/>(执行前校验 denyReason)"]
        ProgressEpoch["进度纪元追踪器<br/>(参数与结果哈希签名)"]
        OutputState["AssistantOutputGuardState<br/>(重复单行与段落判定)"]
        SafeLogger["脱敏事件日志器<br/>(敏感凭证掩码)"]
    end

    subgraph Actions ["防护动作"]
        Allow["放行工具执行<br/>(产生新结果或有效进展)"]
        Deny["拦截并强制文本回答<br/>(要求智能体总结原因)"]
        Cancel["平滑取消当前会话<br/>(keepInbox: false 中止失控输出)"]
    end

    Turn -->|agent/pre-step & 工具调用| ToolInterceptor
    ToolInterceptor --> ProgressEpoch
    ProgressEpoch -->|确认产生新状态| Allow
    ProgressEpoch -->|重复无进展或超额| Deny
    Stream --> OutputState
    OutputState -->|超出文本重复阈值| Cancel
    UserStop -->|即刻锁定停止| Deny
    Deny -.-> SafeLogger
    Cancel -.-> SafeLogger
```

* * *

## ✨ 核心特性深度解析

### 1\. 进度感知型工具调用判定

与盲目统计调用次数的简单计数器不同，本插件精准区分**有效迭代**与**停滞循环**：

-   **确定性指纹签名**：为调用参数（`callFingerprint`）与返回结果（`resultFingerprint`）生成确定性 JSON 指纹。
-   **进度纪元追踪（Progress Epochs）**：一旦操作产生新证据（如文件修改成功、返回新差异或进度 Token），无进展计数器立即重置。
-   **网络与 VCS 细粒度隔离**：不同的 HTTP 端点或请求方法（如 Gitea API 的不同资源操作）绝不会因基础域名相同而发生误判。
-   **进度工具独立白名单**：专用于维护任务清单的工具（如 `todo_write`）拥有独立的无进展预算，避免更新进度时误触拦截。

### 2\. 拦截代码速查与触发策略

| 拦截代码 | 触发场景 | 默认阈值 | 防护动作 |
| :-- | :-- | :-- | :-- |
| `LOOP_GUARD_STOP` | 用户发送了终止或要求回答的指令（`stop`, `halt`, `cancel`, `停止`, `等等`, `回答`） | 立即触发 | 拦截后续工具调用，强制智能体立即返回文本答复 |
| `LOOP_GUARD_DUPLICATE` | 连续以完全相同参数调用工具且返回结果毫无变化 | 1 次重复 | 阻止原地踏步，强制更换执行策略 |
| `LOOP_GUARD_REPEAT` | 同一工具组在未产生新状态的情况下连续重复调用 | `maxCallsPerRepeatGroup` (5) | 防止单一工具过度空转 |
| `LOOP_GUARD_LIMIT` | 当前回合自上次产出有效进展以来的总无效调用次数超标 | `maxToolAttemptsPerTurn` (64) | 限制单回合探索预算上限 |
| `LOOP_GUARD_PROGRESS_LIMIT` | 连续调用进度工具而未产生任何任务变更 | `maxProgressToolCallsPerTurn` (16) | 防止陷入无限修改清单死循环 |
| `LOOP_GUARD_OUTPUT` | 智能体在流式输出中重复输出相同单行或完整段落 | `maxRepeatedAssistantLines` (5) | 通过 `agent.cancel()` 安全中断当前输出 |
| `LOOP_GUARD_PSEUDO_TOOL_CALL` | 连续 completed 回合输出伪工具调用语法（如 `<invoke>`）且 0 次真实工具调用 | `pseudoToolCallThreshold` (3) | 通过 `agent.cancel()` 安全中断当前会话 |
| `LOOP_GUARD_OSCILLATION` | 多工具交替震荡循环（例如 A ➔ B ➔ A ➔ B 乒乓死循环）且无状态进展 | `maxOscillationRepeats` (3) | 拦截交替空转循环；提示智能体切换策略或直接回答 |
| `LOOP_GUARD_PAYLOAD_TRUNCATED` | 工具返回结果字符数超出安全阈值 | `maxToolResultChars` (65536) | 安全截断过大输出（保留首尾）并注入引导提示；记录遥测且不中断工具执行 |

### 3\. 流式文本防死循环机制

-   **行规范化**：自动剔除多余空格与不可见回车符，精准捕获带格式的文本重复。
-   **段落哈希**：支持最长 `maxAssistantBlockChars` (16,384 字节) 的多行 Markdown 块哈希比对。
-   **长耗时工具豁免**：在工具实际执行期间，文本中断检测自动保持静默，避免长任务被误杀。
-   **用户输入无损重置**：用户发起新对话轮次时，检测状态自动全量清理重置。

### 4\. 凭证脱敏与日志隐私防护

所有防护告警日志均会自动针对敏感凭证执行脱敏处理：

-   Bearer 令牌、密码、Cookie 与查询参数凭据（`token=`, `api-key=`, `secret=`）在写入日志前一律替换为 `[redacted]`。
-   对深度嵌套的参数对象执行深度与宽度截断，杜绝超大 JSON 解析引发的内存泄漏。

### 5\. 原生 WebUI 设置卡片、实时防护遥测与一键平滑更新

-   **原生设置面板集成**：直接内嵌于 DSH Web 控制台「设置 ➔ 插件 ➔ 插件设置」卡片列表中（`settings.plugin.item`, order 95）。
-   **对齐 DSH 设计规范**：完全基于 DSH 标准设计令牌变量（`--dsw-alias-*`）与无障碍标签绑定（`htmlFor`/`id`），搭配轻量级平滑展开 Chevron 图标，零外部重型 UI 库依赖。
-   **实时防护遥测看板**：在设置卡片中直观呈现当前运行时拦截的死循环总数（`LOOP_GUARD_DUPLICATE`, `LOOP_GUARD_REPEAT`, `LOOP_GUARD_LIMIT`, `LOOP_GUARD_OUTPUT`），支持通过 `/api/@goodandready/dsh-agent-loop-guard/telemetry` 安全端点一键重置计数。
-   **一键无缝在线更新**：卡片自动联动 npm 官方源检查最新版本，支持通过经过鉴权的本地环回 API（`/api/@goodandready/dsh-agent-loop-guard/update`）在后台安全完成版本升级。

* * *

## 📦 快速安装

通过 DeepSeek Harness CLI 一键安装：

```bash
dsh plugin --profile web add @goodandready/dsh-agent-loop-guard
```

重启 DSH 并刷新浏览器工作区。

* * *

## ⚙️ 配置指南

在 `config.yaml` 或 Web UI 设置面板中配置：

```yaml
# config.yaml
dsh-agent-loop-guard:
  maxToolAttemptsPerTurn: 64
  maxProgressToolCallsPerTurn: 16
  progressToolNames:
    - todo_write
  maxCallsPerRepeatGroup: 5
  blockExactDuplicates: true
  assistantOutputGuard: true
  maxRepeatedAssistantLines: 5
  maxRepeatedAssistantBlocks: 5
  maxAssistantBlockChars: 16384
```

### 配置参数参考表

| 参数名 | 类型 | 默认值 | 功能说明 |
| :-- | :-- | :-- | :-- |
| `maxToolAttemptsPerTurn` | `number` | `64` | 单回合最大无进展工具调用预算。设为 `0` 可禁用此聚合上限。 |
| `maxProgressToolCallsPerTurn` | `number` | `16` | 进度标记工具（`todo_write`）连续无进展调用的上限。 |
| `progressToolNames` | `array` | `["todo_write"]` | 标记任务进度的工具名称数组。 |
| `maxCallsPerRepeatGroup` | `number` | `5` | 同一组工具未产生新结果时允许调用的最大次数。 |
| `maxCallsPerToolPerTurn` | `number` | `5` | _(已废弃)_ `maxCallsPerRepeatGroup` 的向后兼容别名。两者同时存在时优先使用 `maxCallsPerRepeatGroup`。UI 卡片中有意隐藏以避免混淆。 |
| `strictTools` | `array` | `[]` | 受到更严格重复调用限制的敏感/修改类工具名称列表。 |
| `strictToolLimit` | `number` | `3` | `strictTools` 列表中工具的最大允许重复次数。 |
| `blockExactDuplicates` | `boolean` | `true` | 是否立即拦截结果毫无变化的连续相同调用。 |
| `dryRunMode` | `boolean` | `false` | 审计模式：记录告警与遥测指标，但不实际拦截工具调用。 |
| `assistantOutputGuard` | `boolean` | `true` | 是否开启助手流式文本输出防死循环监测。 |
| `maxRepeatedAssistantLines` | `number` | `5` | 触发输出中断的连续相同单行阈值。 |
| `maxRepeatedAssistantBlocks` | `number` | `5` | 触发输出中断的连续重复段落阈值。 |
| `maxAssistantBlockChars` | `number` | `16384` | 捕获用于段落指纹比对的最大字符数。 |
| `pseudoToolCallThreshold` | `number` | `3` | 伪工具调用空转拦截阈值（连续回合数，0 表示禁用）。 |
| `pseudoToolCallPatterns` | `array` | `[]` | 自定义伪工具调用文本检测正则表达式或关键词列表。 |

* * *

## 🧪 测试与校验

运行全部 51 个自动化单元与集成测试及静态代码检查：

```bash
npm test
npm run check
```

* * *

## 📄 开源许可证

-   **开源许可证**: MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)
-   **更新历史**: 完整版本演进历史与特性发布记录详见 [CHANGELOG.md](https://npmcn.com/package/%40goodandready/dsh-agent-loop-guard/CHANGELOG.md)。

## 常见问题

### @goodandready/dsh-agent-loop-guard 是什么？

DeepSeek Harness的失败的运行时间工具调用循环守护\.

### 如何安装 @goodandready/dsh-agent-loop-guard？

在项目目录运行 npm install @goodandready/dsh-agent-loop-guard，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（^4\.0\.1）、@deepseek-ai/schemastery（^3\.18\.4）、@deepseek-ai/dsh-settings（^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @goodandready/dsh-agent-loop-guard 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/goodandready\_\_dsh-agent-loop-guard 是否存在。

### @goodandready/dsh-agent-loop-guard 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @goodandready/dsh-agent-loop-guard 可以商用吗？

@goodandready/dsh-agent-loop-guard 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @goodandready/dsh-agent-loop-guard 的下载量有多少？

根据 npm 官方下载统计，@goodandready/dsh-agent-loop-guard 在 2026/10/17 – 2026/11/15 这 30 天内被下载 2,835 次，日均约 95 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @goodandready/dsh-agent-loop-guard 还在维护吗？

最新版本 0\.3\.1 发布于 2026/11/16（今天）；至今共发布 24 个版本，其中过去 12 个月发布了 24 个；首次发布于 2026/09/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

