dsh-dupguard 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+本文件遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
+
+## [1.0.0] - 2026-08-16
+
+### Added
+
+- 首次发布：实时检测流式输出中的连续重复（默认同一字符串 ≥10 次）并立即停止生成。
+- 双入口交付：`plugin/host.js`（动态插件）与 `lib/index.js`（npm/组合常驻），行为一致、同一测试套件防漂移。
+- 端到端测试（15 项 × 2 入口）与 GitHub Actions CI（Node 18/20/22）。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zqh260619
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+# dupguard · DSH 大模型重复输出守卫
+
+> **dupguard** — a real-time repetition guard for [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness): stops model generation as soon as the same string repeats **≥ 10 times** (configurable) in the streamed output.
+>
+> **dupguard** 是 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) 的实时重复输出守卫插件：当最新输出中同一字符串连续重复 **10 次及以上**（可配置）时，立即停止本次生成。
+
+[![npm version](https://img.shields.io/npm/v/dsh-dupguard)](https://www.npmjs.com/package/dsh-dupguard)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/zqh260619/dsh-dupguard/actions/workflows/ci.yml/badge.svg)](https://github.com/zqh260619/dsh-dupguard/actions/workflows/ci.yml)
+[![dsh-plugin](https://img.shields.io/badge/topic-dsh--plugin-0969da)](https://github.com/topics/dsh-plugin)
+
+触发后，已生成的内容会**正常提交为助手消息**，本轮对话干净结束——不会报错、不会丢弃输出、不会污染会话日志。
+
+When triggered, the already-generated text is committed as a normal assistant message and the turn ends cleanly — no errors, no lost output, no session-log pollution.
+
+---
+
+## 特性 / Features
+
+- **实时检测**：逐 token（`text-delta`）检测，复读出现即停，延迟为单个增量。
+- **多种复读形态**：单字符循环、词语循环、带空格/换行分隔的复读均能识别（默认去空白后检测）。
+- **真正的服务端停止**：提前关闭流迭代 → 适配器 `consumer.abort()` → 中断 HTTP 连接，模型在服务端停止生成。
+- **安全停止**：绝不 `abort()` agent 步骤信号；补发协议合规的 `block-end` + `finish(stop)`，消息正常提交。
+- **零依赖 / 零配置**：纯 JavaScript，无运行时依赖；默认配置开箱即用。
+- **双入口交付**：动态插件（`plugin/host.js`）+ npm 组合挂载（`lib/index.js`），行为一致、CI 防漂移。
+
+---
+
+## 快速开始 / Quick Start
+
+### 方式一：动态插件（无需安装，进程内生效）/ Dynamic plugin (no install)
+
+把 [`plugin/host.js`](plugin/host.js) 的全部内容作为 `code.host` 提交给 `cordis_define`，再 `cordis_run` 激活即可：
+
+1. `cordis_define`：kind 选 `new`，idPrefix 例如 `dupguard`，`code.host` 填入 `plugin/host.js` 内容；
+2. `cordis_run`：激活返回的 `packageId`（首次使用 mode `run`）。
+
+动态插件随 DSH 进程存在；重启后需重新 define + run。
+
+Paste the entire content of [`plugin/host.js`](plugin/host.js) as `code.host` in `cordis_define`, then activate the returned `packageId` with `cordis_run`.
+
+### 方式二：npm 安装 + 组合挂载（常驻）/ npm + composition (persistent)
+
+```bash
+npm install dsh-dupguard
+```
+
+然后在你的 preset 组合文件（cordis.yml）中加入本插件的行并重启 DSH。具体挂载写法以官方发布指南为准：
+[deepseek-ai/deepseek-harness · docs/user/develop/basic/publish.zh.md](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.zh.md)（npm 生态与发布流程）。
+
+Then add the plugin row to your preset composition (cordis.yml) and restart DSH; follow the official [publish guide](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md) for the exact mounting syntax.
+
+---
+
+## 配置 / Configuration
+
+修改 `plugin/host.js` 或 `lib/index.js` 顶部 `CONFIG` 常量（两个入口需保持同步，CI 会校验一致性）：
+
+Edit the `CONFIG` block at the top of `plugin/host.js` / `lib/index.js` (both entries must stay in sync; CI verifies behavioral parity).
+
+| 配置项 / Option | 默认 / Default | 说明 / Description |
+| --- | --- | --- |
+| `threshold` | `10` | 触发阈值：同一字符串连续重复 ≥ 该值时停止 / stop when the same string repeats ≥ this many times |
+| `minUnitLength` | `1` | 最小重复单元长度 / minimum repeating-unit length (`1` also catches single-char loops like `aaaaaaaaaa`) |
+| `maxUnitLength` | `80` | 最大重复单元长度 / maximum repeating-unit length |
+| `detectionWindow` | `8192` | 检测滚动窗口（字符，去空白后）/ rolling detection window in chars (after whitespace removal) |
+| `stripWhitespace` | `true` | 检测前移除空白/换行，识别带分隔符的复读 / strip whitespace so `"x x x"` and `"x\nx\nx"` are caught |
+| `monitorReasoning` | `false` | 是否检测思考文本 / also guard reasoning (thinking) text — off by default, high false-positive risk |
+| `monitorToolArguments` | `false` | 是否检测工具调用参数 / also guard tool-call JSON args — off by default (base64/JSON repeats are common) |
+
+---
+
+## 工作原理 / How it works
+
+### 1. 拦截流式输出 / Intercept the stream
+
+监听 `llm/stream` 瀑布事件（包裹每次流式模型调用），返回包装后的 `AsyncIterable`。与 DSH 自带
+`@deepseek-ai/dsh-llm` invariant 插件、`dsh-session-checkpoint-policy` 同款接入方式。
+
+Listens to the `llm/stream` waterfall (wraps every streaming model call) and returns a wrapped `AsyncIterable`.
+
+### 2. 检测算法 / Detection
+
+- 按块索引（`chunk.index`）分别累积文本，多块交替输出互不干扰；
+- 去空白后做**尾部连续重复检测**：文本以某个单元（长度 1..80）连续重复 ≥ 阈值结尾即触发。
+  模型一旦复读，重复必然在尾部，因此尾部检测即可实时捕获所有循环，同时避免全窗口词频的误报
+  （如正常中文里高频的"的"）。
+
+Tails-only consecutive-run detection on the whitespace-stripped buffer: catches every loop in real time
+without the false positives of whole-window frequency counting.
+
+### 3. 停止机制 / Stopping
+
+守卫生成器提前结束 → `for await` 调用上游 `iterator.return()` → 适配器 `finally` 中
+`consumer.abort()` 中断 HTTP 连接 → 服务端真正停止生成。**绝不直接 `abort()`
+`options.signal`**（对 loop 请求它就是 agent 步骤信号，直接中止会以 `aborted` 结束并丢弃消息）。
+
+Graceful early end: `iterator.return()` propagates to the adapter, whose `finally` aborts the HTTP
+connection server-side. We never abort `options.signal` directly (for loop requests it *is* the agent
+step signal).
+
+### 4. 协议合规收尾 / Protocol-compliant closure
+
+停止时补发所有打开块的 `block-end`（携带完整已生成文本）与 `finish{kind:'stop'}`，满足
+`llm-invariant` 校验器要求；agent-loop 将已生成内容正常提交为助手消息。
+
+Emits synthetic `block-end`s plus `finish(stop)` to satisfy the `llm-invariant` validator, so the
+agent-loop commits the partial text as a normal assistant message.
+
+---
+
+## 触发示例 / What gets stopped
+
+| 形态 / Pattern | 示例 / Example |
+| --- | --- |
+| 单字符循环 / single-char loop | `aaaaaaaaaa` |
+| 词语循环 / word loop | `哈哈` ×10 |
+| 带空格复读 / space-separated | `hello hello hello ...` ×10 |
+| 逐行复读 / line repeats | `抱歉，我无法完成。` ×10 行 |
+| 前缀后循环 / loop after prefix | `好的，下面开始回答：` + `循环` ×10 |
+
+**不会触发 / Won't trigger**：正常文本中的高频词（检测只针对**连续**重复）、重复 9 次及以下、
+reasoning 与工具参数（默认关闭）。/ high-frequency words in normal prose (consecutive runs only),
+≤9 repeats, reasoning and tool args (off by default).
+
+---
+
+## 项目结构 / Project layout
+
+```
+.
+├── plugin/
+│   └── host.js                 # 动态插件形式（cordis_define 的 code.host）
+├── lib/
+│   └── index.js                # npm/组合常驻形式（package.json main 入口）
+├── tests/
+│   └── detector.test.js        # 端到端测试：15 项 × 2 入口（防漂移）
+├── .github/workflows/ci.yml    # GitHub Actions：Node 18/20/22
+├── package.json
+├── CHANGELOG.md
+├── LICENSE                     # MIT
+└── README.md
+```
+
+## 测试 / Tests
+
+```bash
+node tests/detector.test.js   # 或 npm test
+```
+
+同一套 15 项用例分别驱动两个入口（`plugin/host.js` 经 `new Function` 求值、`lib/index.js` 经
+`require` 加载），覆盖：透传完整性、各类复读形态、阈值边界、协议闭合、上游 `return()` 调用、
+默认不检测 reasoning/工具参数、未闭合工具调用块的闭合、多次调用状态隔离等。CI 在 Node 18/20/22
+上运行。
+
+The same 15-test suite drives both entries, guarding against drift between the two forms. CI runs on
+Node 18/20/22.
+
+---
+
+## 已知限制 / Limitations
+
+- 停止时若恰有未闭合的工具调用块（顺序输出块的适配器几乎不可能），该块会按已累积参数闭合并可能被执行。
+- 服务端停止依赖适配器在流关闭时中止底层请求的语义（已验证 `dsh-llm-deepseek`；自定义适配器需自查）。
+- 阈值语义为 `>= threshold`：第 10 次重复出现时即停止。
+
+## License
+
+[MIT](LICENSE)

package/lib/index.js

@@ -0,0 +1,215 @@
+'use strict'
+
+// ============================================================================
+// dupguard —— DSH (DeepSeek Harness) 插件（npm / 组合常驻形式，CJS 入口）
+//
+// 实时检测大模型流式输出中的重复内容：当最新的输出中同一字符串连续重复
+// CONFIG.threshold 次及以上时，立即停止本次生成。
+//
+// 本文件是 package.json 的 main 入口，导出 Cordis 插件对象
+// { name, apply }，供 DSH 组合（cordis.yml / preset）挂载；
+// 与 plugin/host.js（动态 cordis_define 形式）行为完全一致，
+// tests/detector.test.js 会对两者同时跑同一套用例，防止两份代码漂移。
+// ============================================================================
+
+const name = 'dupguard'
+
+const CONFIG = {
+  // 触发阈值：同一字符串连续重复次数达到该值时停止输出（用户需求：重复十次以上）。
+  // 语义为「>= threshold」，即第 10 次重复出现时就触发。
+  threshold: 10,
+  // 参与检测的重复单元的最小/最大长度（字符数）。
+  // minUnitLength=1 意味着 "aaaaaaaaaa" 这类单字符循环也会触发。
+  minUnitLength: 1,
+  maxUnitLength: 80,
+  // 检测用滚动窗口（字符数，去除空白后）。
+  // 只需要容纳 threshold * maxUnitLength（默认 10 * 80 = 800），留足余量即可。
+  detectionWindow: 8192,
+  // 检测前先移除所有空白字符（含换行）：
+  // 让 "重复 重复 重复"、"重复\n重复\n重复" 这类带分隔符的复读也能被识别。
+  stripWhitespace: true,
+  // 是否同时检测思考（reasoning）文本。默认关闭：思考内容不可见，且正常思考文本
+  // 更可能出现连续重复片段，误伤风险高。
+  monitorReasoning: false,
+  // 是否同时检测工具调用参数（JSON 片段）。默认关闭：JSON / base64 中重复字符很常见。
+  monitorToolArguments: false,
+}
+
+/**
+ * 尾部连续重复检测：text 是否以某个 unit（长度 minUnitLength..maxUnitLength）
+ * 连续重复 >= threshold 次结尾。是则返回 { unit, count, span }，否则返回 null。
+ *
+ * 说明：由于本插件对每个增量实时调用本函数，模型一旦陷入复读循环，
+ * 循环必然发生在文本尾部，因此尾部检测即可覆盖所有循环场景；
+ * 不做全窗口词频统计，是为了避免正常文本（例如中文里高频出现的"的"）
+ * 被误判为重复。
+ */
+function findRepeatedTail(text, threshold, minUnitLength, maxUnitLength) {
+  const n = text.length
+  if (n < threshold * minUnitLength) return null
+  const maxP = Math.min(maxUnitLength, Math.floor(n / threshold))
+  for (let p = minUnitLength; p <= maxP; p++) {
+    const unit = text.slice(n - p) // 最后一个候选单元
+    let ok = true
+    for (let k = 1; k < threshold; k++) {
+      // 向前逐段比较前 threshold-1 个副本
+      if (text.slice(n - p * (k + 1), n - p * k) !== unit) {
+        ok = false
+        break
+      }
+    }
+    if (ok) return { unit, count: threshold, span: p * threshold }
+  }
+  return null
+}
+
+/** 移除所有空白字符（与 CONFIG.stripWhitespace 配合）。 */
+function stripWhitespace(text) {
+  return text.replace(/\s+/g, '')
+}
+
+/**
+ * 为一次 llm/stream 调用创建守卫。
+ * 每次模型调用都会新建一份状态，互不干扰。
+ */
+function createStreamGuard(options) {
+  // index -> 块状态。用 Map 按块索引累积，避免多个文本块交替输出时互相打断检测。
+  const blocks = new Map()
+  let stopped = null
+
+  const provider = typeof options === 'object' && options !== null ? String(options.provider ?? '?') : '?'
+  const model = typeof options === 'object' && options !== null ? String(options.model ?? '?') : '?'
+
+  function ensure(index, blockType) {
+    let b = blocks.get(index)
+    if (b === undefined) {
+      b = {
+        blockType,
+        text: '',            // 完整文本：停止时需要用它闭合块，不能只保留窗口
+        stripped: '',        // 去空白后的滚动窗口：仅用于检测
+        toolCallId: undefined,
+        toolCallName: undefined,
+        toolCallArguments: '',
+      }
+      blocks.set(index, b)
+    }
+    return b
+  }
+
+  /** 把一段文本增量喂给检测缓冲，返回命中结果（null 表示未命中）。 */
+  function feedText(b, delta) {
+    b.text += delta
+    const piece = CONFIG.stripWhitespace ? stripWhitespace(delta) : delta
+    b.stripped = (b.stripped + piece).slice(-CONFIG.detectionWindow)
+    return findRepeatedTail(b.stripped, CONFIG.threshold, CONFIG.minUnitLength, CONFIG.maxUnitLength)
+  }
+
+  /** 依据 StreamChunk 协议累积状态；命中时置 stopped。 */
+  function feed(chunk) {
+    switch (chunk.type) {
+      case 'block-start': {
+        ensure(chunk.index, chunk.blockType)
+        return
+      }
+      case 'text-delta': {
+        const b = ensure(chunk.index, 'text')
+        const hit = feedText(b, chunk.text)
+        if (hit !== null) stopped = hit
+        return
+      }
+      case 'reasoning-delta': {
+        const b = ensure(chunk.index, 'reasoning')
+        b.text += chunk.text // 始终累积：停止时需要完整内容闭合块
+        if (CONFIG.monitorReasoning) {
+          const hit = feedText(b, chunk.text)
+          if (hit !== null) stopped = hit
+        }
+        return
+      }
+      case 'tool-call-delta': {
+        const b = ensure(chunk.index, 'tool-call')
+        if (chunk.id !== undefined) b.toolCallId = chunk.id
+        if (chunk.name !== undefined) b.toolCallName = chunk.name
+        b.toolCallArguments += chunk.argumentsDelta
+        if (CONFIG.monitorToolArguments) {
+          b.stripped = b.toolCallArguments.slice(-CONFIG.detectionWindow)
+          const hit = findRepeatedTail(b.stripped, CONFIG.threshold, CONFIG.minUnitLength, CONFIG.maxUnitLength)
+          if (hit !== null) stopped = hit
+        }
+        return
+      }
+      case 'block-end': {
+        blocks.delete(chunk.index)
+        return
+      }
+      case 'usage':
+      case 'finish':
+      default:
+        return
+    }
+  }
+
+  /** 把块状态装配为 ContentBlock（与 BlockAssembler 的 open-block 装配规则一致）。 */
+  function closeBlock(b, index) {
+    let block
+    if (b.blockType === 'text') {
+      block = { type: 'text', text: b.text }
+    } else if (b.blockType === 'reasoning') {
+      block = { type: 'reasoning', text: b.text }
+    } else {
+      block = {
+        type: 'tool-call',
+        id: b.toolCallId !== undefined ? b.toolCallId : 'call-' + index,
+        name: b.toolCallName !== undefined ? b.toolCallName : '',
+        arguments: b.toolCallArguments,
+      }
+    }
+    return { type: 'block-end', index, block }
+  }
+
+  /**
+   * 满足 llm/stream 协议地收尾：
+   * 1) 闭合所有仍打开的块（否则 llm-invariant 校验器会报
+   *    "LLM stream finished with N open block(s)"）；
+   * 2) 以 finish(stop) 结尾（否则报 "LLM stream ended without a terminal finish chunk"）。
+   * agent-loop 因此把已生成内容正常提交为助手消息，本轮干净结束。
+   */
+  function* closingChunks() {
+    for (const [index, b] of blocks) yield closeBlock(b, index)
+    yield { type: 'finish', reason: { kind: 'stop' } }
+  }
+
+  /** 包装上游流：逐块透传 + 检测；命中后补发闭合块并提前结束。 */
+  async function* guarded(source) {
+    for await (const chunk of source) {
+      yield chunk
+      feed(chunk)
+      if (stopped !== null) {
+        console.log(
+          '[dupguard] 检测到重复输出，已停止生成：provider=' + provider + ' model=' + model +
+          ' unit=' + JSON.stringify(stopped.unit) +
+          ' repeat>=' + String(stopped.count) +
+          ' span=' + String(stopped.span) + 'chars'
+        )
+        yield* closingChunks()
+        // 提前 return：for-await 会调用上游 iterator.return()，
+        // 适配器的 finally 随即 consumer.abort() 中断 HTTP 连接，
+        // 从而在服务端真正停止生成。这里绝不调用 options.signal.abort()，
+        // 因为 loop 请求的 options.signal 就是整个 agent 步骤的信号，
+        // 直接中止会让本轮以 aborted 结束并丢弃已生成的消息。
+        return
+      }
+    }
+  }
+
+  return guarded
+}
+
+function apply(ctx) {
+  // llm/stream：包裹每次流式模型调用的瀑布事件。
+  // 监听器返回包装后的 AsyncIterable，即成为本次调用对消费方可见的流。
+  // （与 @deepseek-ai/dsh-llm 的 invariant、dsh-session-checkpoint-policy 同款接入方式）
+  ctx.on('llm/stream', (options, next) => createStreamGuard(options)(next()))
+}
+
+module.exports = { name, apply }

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "dsh-dupguard",
+  "version": "1.0.0",
+  "description": "Real-time repetition guard for DeepSeek Harness (DSH): stops model generation when the same string repeats >=10 times in the streamed output. 实时检测 DSH 大模型流式输出中的重复内容，同一字符串重复十次以上立即停止生成。",
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "dsh",
+    "repetition-detection",
+    "loop-detection",
+    "anti-repetition",
+    "output-guard",
+    "llm",
+    "防复读",
+    "重复检测"
+  ],
+  "license": "MIT",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib",
+    "plugin",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node tests/detector.test.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zqh260619/dsh-dupguard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zqh260619/dsh-dupguard/issues"
+  },
+  "homepage": "https://github.com/zqh260619/dsh-dupguard#readme"
+}

package/plugin/host.js

@@ -0,0 +1,212 @@
+// ============================================================================
+// dupguard —— DSH 动态 Cordis 插件（Host 端）
+//
+// 实时检测大模型流式输出中的重复内容：当最新的输出中同一字符串连续重复
+// CONFIG.threshold 次及以上时，立即停止本次生成。
+//
+// 用法：把整个文件内容作为 cordis_define 的 code.host 传入即可，
+//       不需要修改任何 DSH 组合（composition）文件。
+// 需要随 DSH 常驻时，请改用 npm/组合形式 lib/index.js（与本文件行为一致，
+// tests/detector.test.js 会对两个入口跑同一套用例防止漂移）。
+// 安装/运行步骤与配置说明见仓库根目录的 README.md。
+// ============================================================================
+
+const CONFIG = {
+  // 触发阈值：同一字符串连续重复次数达到该值时停止输出（用户需求：重复十次以上）。
+  // 语义为「>= threshold」，即第 10 次重复出现时就触发。
+  threshold: 10,
+  // 参与检测的重复单元的最小/最大长度（字符数）。
+  // minUnitLength=1 意味着 "aaaaaaaaaa" 这类单字符循环也会触发。
+  minUnitLength: 1,
+  maxUnitLength: 80,
+  // 检测用滚动窗口（字符数，去除空白后）。
+  // 只需要容纳 threshold * maxUnitLength（默认 10 * 80 = 800），留足余量即可。
+  detectionWindow: 8192,
+  // 检测前先移除所有空白字符（含换行）：
+  // 让 "重复 重复 重复"、"重复\n重复\n重复" 这类带分隔符的复读也能被识别。
+  stripWhitespace: true,
+  // 是否同时检测思考（reasoning）文本。默认关闭：思考内容不可见，且正常思考文本
+  // 更可能出现连续重复片段，误伤风险高。
+  monitorReasoning: false,
+  // 是否同时检测工具调用参数（JSON 片段）。默认关闭：JSON / base64 中重复字符很常见。
+  monitorToolArguments: false,
+}
+
+/**
+ * 尾部连续重复检测：text 是否以某个 unit（长度 minUnitLength..maxUnitLength）
+ * 连续重复 >= threshold 次结尾。是则返回 { unit, count, span }，否则返回 null。
+ *
+ * 说明：由于本插件对每个增量实时调用本函数，模型一旦陷入复读循环，
+ * 循环必然发生在文本尾部，因此尾部检测即可覆盖所有循环场景；
+ * 不做全窗口词频统计，是为了避免正常文本（例如中文里高频出现的"的"）
+ * 被误判为重复。
+ */
+function findRepeatedTail(text, threshold, minUnitLength, maxUnitLength) {
+  const n = text.length
+  if (n < threshold * minUnitLength) return null
+  const maxP = Math.min(maxUnitLength, Math.floor(n / threshold))
+  for (let p = minUnitLength; p <= maxP; p++) {
+    const unit = text.slice(n - p) // 最后一个候选单元
+    let ok = true
+    for (let k = 1; k < threshold; k++) {
+      // 向前逐段比较前 threshold-1 个副本
+      if (text.slice(n - p * (k + 1), n - p * k) !== unit) {
+        ok = false
+        break
+      }
+    }
+    if (ok) return { unit, count: threshold, span: p * threshold }
+  }
+  return null
+}
+
+/** 移除所有空白字符（与 CONFIG.stripWhitespace 配合）。 */
+function stripWhitespace(text) {
+  return text.replace(/\s+/g, '')
+}
+
+/**
+ * 为一次 llm/stream 调用创建守卫。
+ * 每次模型调用都会新建一份状态，互不干扰。
+ */
+function createStreamGuard(options) {
+  // index -> 块状态。用 Map 按块索引累积，避免多个文本块交替输出时互相打断检测。
+  const blocks = new Map()
+  let stopped = null
+
+  const provider = typeof options === 'object' && options !== null ? String(options.provider ?? '?') : '?'
+  const model = typeof options === 'object' && options !== null ? String(options.model ?? '?') : '?'
+
+  function ensure(index, blockType) {
+    let b = blocks.get(index)
+    if (b === undefined) {
+      b = {
+        blockType,
+        text: '',            // 完整文本：停止时需要用它闭合块，不能只保留窗口
+        stripped: '',        // 去空白后的滚动窗口：仅用于检测
+        toolCallId: undefined,
+        toolCallName: undefined,
+        toolCallArguments: '',
+      }
+      blocks.set(index, b)
+    }
+    return b
+  }
+
+  /** 把一段文本增量喂给检测缓冲，返回命中结果（null 表示未命中）。 */
+  function feedText(b, delta) {
+    b.text += delta
+    const piece = CONFIG.stripWhitespace ? stripWhitespace(delta) : delta
+    b.stripped = (b.stripped + piece).slice(-CONFIG.detectionWindow)
+    return findRepeatedTail(b.stripped, CONFIG.threshold, CONFIG.minUnitLength, CONFIG.maxUnitLength)
+  }
+
+  /** 依据 StreamChunk 协议累积状态；命中时置 stopped。 */
+  function feed(chunk) {
+    switch (chunk.type) {
+      case 'block-start': {
+        ensure(chunk.index, chunk.blockType)
+        return
+      }
+      case 'text-delta': {
+        const b = ensure(chunk.index, 'text')
+        const hit = feedText(b, chunk.text)
+        if (hit !== null) stopped = hit
+        return
+      }
+      case 'reasoning-delta': {
+        const b = ensure(chunk.index, 'reasoning')
+        b.text += chunk.text // 始终累积：停止时需要完整内容闭合块
+        if (CONFIG.monitorReasoning) {
+          const hit = feedText(b, chunk.text)
+          if (hit !== null) stopped = hit
+        }
+        return
+      }
+      case 'tool-call-delta': {
+        const b = ensure(chunk.index, 'tool-call')
+        if (chunk.id !== undefined) b.toolCallId = chunk.id
+        if (chunk.name !== undefined) b.toolCallName = chunk.name
+        b.toolCallArguments += chunk.argumentsDelta
+        if (CONFIG.monitorToolArguments) {
+          b.stripped = b.toolCallArguments.slice(-CONFIG.detectionWindow)
+          const hit = findRepeatedTail(b.stripped, CONFIG.threshold, CONFIG.minUnitLength, CONFIG.maxUnitLength)
+          if (hit !== null) stopped = hit
+        }
+        return
+      }
+      case 'block-end': {
+        blocks.delete(chunk.index)
+        return
+      }
+      case 'usage':
+      case 'finish':
+      default:
+        return
+    }
+  }
+
+  /** 把块状态装配为 ContentBlock（与 BlockAssembler 的 open-block 装配规则一致）。 */
+  function closeBlock(b, index) {
+    let block
+    if (b.blockType === 'text') {
+      block = { type: 'text', text: b.text }
+    } else if (b.blockType === 'reasoning') {
+      block = { type: 'reasoning', text: b.text }
+    } else {
+      block = {
+        type: 'tool-call',
+        id: b.toolCallId !== undefined ? b.toolCallId : 'call-' + index,
+        name: b.toolCallName !== undefined ? b.toolCallName : '',
+        arguments: b.toolCallArguments,
+      }
+    }
+    return { type: 'block-end', index, block }
+  }
+
+  /**
+   * 满足 llm/stream 协议地收尾：
+   * 1) 闭合所有仍打开的块（否则 llm-invariant 校验器会报
+   *    "LLM stream finished with N open block(s)"）；
+   * 2) 以 finish(stop) 结尾（否则报 "LLM stream ended without a terminal finish chunk"）。
+   * agent-loop 因此把已生成内容正常提交为助手消息，本轮干净结束。
+   */
+  function* closingChunks() {
+    for (const [index, b] of blocks) yield closeBlock(b, index)
+    yield { type: 'finish', reason: { kind: 'stop' } }
+  }
+
+  /** 包装上游流：逐块透传 + 检测；命中后补发闭合块并提前结束。 */
+  async function* guarded(source) {
+    for await (const chunk of source) {
+      yield chunk
+      feed(chunk)
+      if (stopped !== null) {
+        console.log(
+          '[dupguard] 检测到重复输出，已停止生成：provider=' + provider + ' model=' + model +
+          ' unit=' + JSON.stringify(stopped.unit) +
+          ' repeat>=' + String(stopped.count) +
+          ' span=' + String(stopped.span) + 'chars'
+        )
+        yield* closingChunks()
+        // 提前 return：for-await 会调用上游 iterator.return()，
+        // 适配器的 finally 随即 consumer.abort() 中断 HTTP 连接，
+        // 从而在服务端真正停止生成。这里绝不调用 options.signal.abort()，
+        // 因为 loop 请求的 options.signal 就是整个 agent 步骤的信号，
+        // 直接中止会让本轮以 aborted 结束并丢弃已生成的消息。
+        return
+      }
+    }
+  }
+
+  return guarded
+}
+
+return {
+  apply(ctx) {
+    // llm/stream：包裹每次流式模型调用的瀑布事件。
+    // 监听器返回包装后的 AsyncIterable，即成为本次调用对消费方可见的流。
+    // （与 @deepseek-ai/dsh-llm 的 invariant、dsh-session-checkpoint-policy 同款接入方式）
+    ctx.on('llm/stream', (options, next) => createStreamGuard(options)(next()))
+  },
+}