dsh-loop-rescue 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 citydirector
+
+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

@@ -1,3 +1,150 @@
-# Temporary Holding Version
+# dsh-loop-rescue
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[English](README.md) · [简体中文](README.zh-CN.md)
+
+[![Release](https://img.shields.io/github/v/tag/citydirector/dsh-loop-rescue?sort=semver&label=release)](https://github.com/citydirector/dsh-loop-rescue/releases) [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![DSH plugin](https://img.shields.io/badge/DSH%20plugin-%E2%89%A50.2.2--alpha.2-blue)](https://github.com/topics/dsh-plugin)
+
+A loop-rescue plugin for DSH (DeepSeek Harness). When the model falls into repetition (`Now. / OK. / Emit. / Producing.` rotations, the same paragraph over and over), it cuts the stream from the inside, **prunes the loop out of what gets written to the session log**, and resumes automatically.
+
+The difference from a plain cut-off: the interrupted message that goes into the next turn's context **contains no loop**, so the model never re-reads its own repetition and carries on repeating.
+
+Requires **DSH 0.2.2-alpha.2 or newer 0.2.x**. Pure JS, no build step.
+
+## npm installation and updates
+
+Requires DSH 0.2.2-alpha.2 or a newer 0.2.x and Node.js 24.9+. Enter `dsh-loop-rescue` in **Plugins → Add plugin**, or run:
+
+```sh
+dsh plugin --profile web add dsh-loop-rescue
+```
+
+For an existing GitHub installation, back up the profile's `cordis.patch.yml`, remove the old package in Plugins, and add the npm package above in the same profile. Keep the configuration row IDs and verify the saved settings after reinstalling. Subsequent updates use DSH's version list and update operation. Updates are handled entirely by DSH.
+
+## Quick start
+
+Use this **or** `@mrweicodes/dsh-loop-guard`, not both: with both on, loops get cut twice.
+
+1. **Install**: sidebar **Plugins** → Add plugin, and give it
+   ```
+   dsh-loop-rescue
+   ```
+   Switch it on.
+2. The defaults work as they are. To watch before it acts, set `mode` to `observe` (see Configuration).
+
+From the command line:
+
+```powershell
+dsh plugin --profile web remove @mrweicodes/dsh-loop-guard
+dsh plugin --profile web add dsh-loop-rescue
+```
+
+Restart `dsh web` after a command-line install. No pnpm build scripts need approving.
+
+## Configuration
+
+The defaults work as they are. To change them, write to the profile's `cordis.patch.yml`:
+
+```yaml
+- set:
+    - id: loop-rescue
+      config:
+        mode: rescue              # rescue: cut + prune + resume | cut: cut + prune | observe: log only
+        watch: both               # both | reasoning | text
+        marker: true              # leave a "〔N chars of repeated reasoning removed〕" line where it pruned
+        maxConsecutiveRescues: 3  # cap on back-to-back rescues; one normal call resets it
+        stallCalls: 3             # nudge after this many reasoning-only calls with no output; 0 = off
+        stallMinReasoningChars: 1024
+        retryTemperature: 1.0     # temperature for the resume request; unset = unchanged
+        retryReasoningEffort: low # reasoning effort for the resume request; unset = unchanged
+        retryRequests: 1          # how many requests after a resume use the two settings above
+        language: auto            # auto | zh | en
+        detector:                 # detection thresholds; rarely need changing
+          poolWindow: 30
+          poolMinCoverage: 0.75
+          cycleMinChars: 600
+```
+
+Consider running `mode: observe` for a day or two first, check that every `loop-rescue: ... loop detected` line in the log is a real loop, then switch to `rescue`.
+
+## How it works
+
+When the agent loop assembles an `assistant/message`, each block's final content comes from the `block-end` payload, not from the deltas streamed before it. The plugin wraps the model call in the `llm/stream` waterfall:
+
+1. It runs a streaming detector on every reasoning and text block.
+2. On a hit it closes every open block: the looping block is replaced by its content **pruned back to where the loop started** (optionally with a one-line marker), and the stream ends with `stop`.
+3. The message written to the log holds only the useful content before the loop. The raw stream is still kept in full in the event's `stream` record, where the trajectory view can show it.
+4. Once the turn has really ended (`whenIdle()`), it sends a resume message with a correction via `followup()`.
+5. The first N requests after a resume can use a different set of sampling parameters.
+6. After the cap on back-to-back rescues it stops resuming and leaves a note.
+
+Why not edit the session afterwards: an `assistant/message` cannot carry `sourceEventSeqs`, so the session surface's replace operation cannot swap one assistant message for another. Pruning at `block-end` is the only way that keeps message roles and tool-call pairing intact.
+
+### Detection rules
+
+| Rule | Catches | Prunes from |
+|---|---|---|
+| Phrase pool `pool` | ≥75% of the last 30 sentences are a handful of recurring short phrases (in any order) | Back to where that batch of phrases first appeared |
+| Verbatim cycle `cycle` | The tail is the same text repeated verbatim, period 16–4000 chars, ≥3 repeats, ≥600 chars in total | Keeps the first copy, prunes from the second |
+
+Guarding against false positives:
+
+- A Chinese full stop always ends a sentence; an English period only when followed by whitespace.
+- Symbol-only lines (`|---|`, `}`) are not counted.
+- List items, table rows and quote lines in the text are not counted.
+- The inside of ``` code blocks in the text is skipped entirely.
+- The phrase pool needs at least two different phrases rotating.
+- It never cuts while an open block holds a tool call: closing a half-written tool call would make the host run it with incomplete arguments.
+
+## Offline scan
+
+Replay past sessions through the same detector the plugin uses, to see where it would cut:
+
+```powershell
+node tools/scan-session.mjs <session file or directory>          # hits only
+node tools/scan-session.mjs <session file or directory> --all    # hits and misses
+node tools/scan-session.mjs <session file> --json
+```
+
+Reads plain jsonl and zstd-compressed session files (zstd needs Node 22.15+). The script only depends on `src/detector.js` and runs on plain node.
+
+## Cleaning loops already in the history
+
+The plugin only stops new loops; loops already committed to the history keep being imitated by the model. What DSH sends the model is a frozen projection of the session log, which a plugin cannot change, so the session files have to be cleaned offline **with DSH fully closed**. This works for old sessions that never had the plugin too.
+
+The recommended tool is [dsh-session-manager](https://github.com/citydirector/dsh-session-manager) (`dsm loops`, a single-file exe on Windows): the same detection rules, plus upgrading, archiving and repairing broken sessions.
+
+This repository also ships a lightweight script (Node 22.15+, v4 sessions only):
+
+```powershell
+node tools/clean-session.mjs            # list sessions with loops, pick by number; Enter = newest
+node tools/clean-session.mjs --dry-run  # show what would change
+node tools/clean-session.mjs --undo     # restore from the backup
+```
+
+- On Windows you can also double-click `tools\clean-session.cmd`, or drop a session folder onto it; if it cannot find the data directory, pass `--data <data directory>`.
+- Only matching `assistant/message` events change: text and reasoning are cut back to where the loop started, `data.stream` is cut to match, and the message's `source.replayState` is removed. Every other line stays byte-for-byte the same.
+- It backs up to `<data directory>\sessions-loop-rescue-backup\` first, and refuses while DSH is running (`--force` skips that check; not recommended).
+- Versions before 2026-10-17 read only the first frame of a compressed log and wrote the result as a single frame, which DSH treats as corrupt and hides. That is fixed; `dsm repair` brings hidden sessions back.
+
+## Known limitations
+
+- Loop text already streamed into the chat is replaced by the pruned version once the message is committed, but exactly how it redraws depends on the DSH front-end version.
+- Loops that span steps (every step is "say a line → call the same tool") are out of scope; that is the job of the built-in `guard/repeat-tool-reminder`.
+- `retryTemperature` needs an adapter that supports temperature. DSH has no generic field for Ollama's repetition penalty and similar parameters, so they cannot be set from here.
+
+## Development
+
+```bash
+npm install
+npm test
+```
+
+## Related projects
+
+- [dsh-remote-access-proxy](https://github.com/citydirector/dsh-remote-access-proxy): Use DSH from your phone, tablet, or another computer
+- [deepinfra-fusion-proxy](https://github.com/citydirector/deepinfra-fusion-proxy): DeepInfra Standard / Flex switching with automatic fallback, per session
+- [dsh-session-manager](https://github.com/citydirector/dsh-session-manager): Offline session manager: upgrade, archive, trash, loop cleanup, broken-tail repair
+
+## License
+
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,150 @@
+# dsh-loop-rescue
+
+[English](README.md) · [简体中文](README.zh-CN.md)
+
+[![Release](https://img.shields.io/github/v/tag/citydirector/dsh-loop-rescue?sort=semver&label=release)](https://github.com/citydirector/dsh-loop-rescue/releases) [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![DSH plugin](https://img.shields.io/badge/DSH%20plugin-%E2%89%A50.2.2--alpha.2-blue)](https://github.com/topics/dsh-plugin)
+
+DSH 循环救援插件：模型陷入重复（`Now. / OK. / Emit. / Producing.` 轮转、段落刷屏）时，从流内部切断，**把循环部分从落盘内容里剪掉**，再自动续跑。
+
+和单纯截断相比，关键区别是：被切断的那条消息在下一轮上下文里**不含循环**，模型不会再读一遍自己的复读，然后接着复读。
+
+需要 **DSH 0.2.2-alpha.2 或更新的 0.2.x**。纯 JS，没有构建步骤。
+
+## npm 安装与更新
+
+需要 DSH 0.2.2-alpha.2 或更新的 0.2.x，以及 Node.js 24.9+。在 DSH「插件 → 添加插件」输入 `dsh-loop-rescue`，或运行：
+
+```sh
+dsh plugin --profile web add dsh-loop-rescue
+```
+
+旧版从 GitHub 安装的用户：先备份 profile 的 `cordis.patch.yml`，在插件页移除旧包并用上述 npm 包名重新添加，保持原 profile 与配置行 ID。配置仍由 profile 保存；重新添加后检查已保存的值。此后统一使用 DSH 插件页的版本列表与更新功能。更新完全由 DSH 管理。
+
+## 快速开始
+
+和 `@mrweicodes/dsh-loop-guard` **二选一**，两者同时开会重复切断。
+
+1. **安装**：侧边栏 **插件** → 添加插件，填入
+   ```
+   dsh-loop-rescue
+   ```
+   装完打开开关。
+2. 默认配置即可使用。想先观察，把 `mode` 设成 `observe`（见「配置」）。
+
+命令行安装：
+
+```powershell
+dsh plugin --profile web remove @mrweicodes/dsh-loop-guard
+dsh plugin --profile web add dsh-loop-rescue
+```
+
+命令行装完重启 `dsh web`。不需要放行 pnpm 构建脚本。
+
+## 配置
+
+默认配置即可使用。需要调整时写进 profile 的 `cordis.patch.yml`：
+
+```yaml
+- set:
+    - id: loop-rescue
+      config:
+        mode: rescue              # rescue：切+剪+续跑 | cut：切+剪 | observe：只记日志
+        watch: both               # both | reasoning | text
+        marker: true              # 剪除处留「〔已删除 N 字重复思考〕」
+        maxConsecutiveRescues: 3  # 连续救援上限，出现一次正常调用就清零
+        stallCalls: 3             # 连续几次只思考无产出就提示继续；0 关闭
+        stallMinReasoningChars: 1024
+        retryTemperature: 1.0     # 续跑请求改用的温度；不填不改
+        retryReasoningEffort: low # 续跑请求改用的推理强度；不填不改
+        retryRequests: 1          # 续跑后几次请求使用上面两项
+        language: auto            # auto | zh | en
+        detector:                 # 检测阈值，一般不用动
+          poolWindow: 30
+          poolMinCoverage: 0.75
+          cycleMinChars: 600
+```
+
+建议先用 `mode: observe` 跑一两天，看日志里的 `loop-rescue: ... loop detected` 是不是都是真循环，再切到 `rescue`。
+
+## 工作原理
+
+agent-loop 组装 `assistant/message` 时，每个 block 的最终内容取自 `block-end` 的载荷，而不是之前流出的 delta。插件在 `llm/stream` 瀑布里包装模型调用：
+
+1. 对每个推理/正文 block 跑流式检测器；
+2. 命中后闭合所有打开的 block：循环所在的 block 换成**剪到循环起点**的内容（可留一行标记），以 `stop` 结束流；
+3. 落盘的消息里只剩循环之前的有效内容。原始流仍完整保存在事件的 `stream` 记录里，轨迹视图可以查看；
+4. 等回合真正结束（`whenIdle()`）后，用 `followup()` 发一条带纠正语的续跑消息；
+5. 续跑的前 N 次请求可选地改用另一组采样参数；
+6. 连续救援达到上限就不再续跑，留一条提示。
+
+为什么不事后改会话：`assistant/message` 不能携带 `sourceEventSeqs`，会话面的 replace 操作没法用 assistant 消息替换 assistant 消息。在 `block-end` 处剪，是唯一不破坏消息角色和工具调用配对的做法。
+
+### 检测规则
+
+| 规则 | 抓什么 | 剪在哪 |
+|---|---|---|
+| 短句池 `pool` | 最近 30 句里 ≥75% 是几种反复出现的短句（顺序可以变） | 回溯到这批短句第一次出现的位置 |
+| 逐字周期 `cycle` | 尾部是同一段文字的逐字重复，周期 16–4000 字符，重复 ≥3 遍，总长 ≥600 | 保留第一份，从第二份开始剪 |
+
+防误伤：
+
+- 中文句号直接断句，英文句号后面要跟空白才断；
+- 纯符号行（`|---|`、`}`）不计入统计；
+- 正文中的列表项、表格行、引用行不计入统计；
+- 正文中的 ``` 代码块内部完全跳过；
+- 短句池至少要有两种句子在轮转；
+- 打开的 block 里有工具调用时不切，因为闭合半截工具调用会让宿主执行参数不完整的调用。
+
+## 离线扫描
+
+用插件同一份检测器复跑历史会话，看会在哪里剪：
+
+```powershell
+node tools/scan-session.mjs <会话文件或目录>          # 只列命中
+node tools/scan-session.mjs <会话文件或目录> --all    # 连未命中一起列
+node tools/scan-session.mjs <会话文件> --json
+```
+
+支持纯 jsonl 和 zstd 压缩的会话文件（zstd 需要 Node 22.15+）。脚本只依赖 `src/detector.js`，普通 node 就能运行。
+
+## 清洗历史里已经提交的循环
+
+插件只能拦住新的循环；历史里已经提交的循环会被模型继续模仿。DSH 发给模型的请求是会话日志的冻结投影，插件改不了，只能在 **DSH 完全退出后** 离线清洗会话文件。没装过插件的老会话同样适用。
+
+推荐用 [dsh-session-manager](https://github.com/citydirector/dsh-session-manager)（`dsm loops`，Windows 有单文件 exe），检测规则和本插件同一套，另外还能升级、归档、修复烂尾会话。
+
+本仓库也带一个轻量脚本（需要 Node 22.15+，只支持 v4 会话）：
+
+```powershell
+node tools/clean-session.mjs            # 列出有循环的会话，按序号选，回车=最新
+node tools/clean-session.mjs --dry-run  # 只看会改哪里
+node tools/clean-session.mjs --undo     # 从备份恢复
+```
+
+- Windows 下也可以双击 `tools\clean-session.cmd`，或把会话文件夹拖到它上面；找不到数据目录时用 `--data <数据目录>` 指定。
+- 只改命中的 `assistant/message`：正文 / 推理截到循环起点，`data.stream` 同步截断，移除该消息的 `source.replayState`。其余行逐字节不变。
+- 改之前备份到 `<数据目录>\sessions-loop-rescue-backup\`；DSH 在运行时拒绝执行（`--force` 可跳过，不推荐）。
+- 2026-10-17 之前的版本只读得到压缩日志的第一帧，并会把结果写成单帧（DSH 会把这种会话当损坏隐藏）。已修复；被隐藏的会话可以用 `dsm repair` 找回。
+
+## 已知限制
+
+- 聊天区已经流出的循环文字在消息提交后会被替换成剪过的版本，但具体怎么重绘取决于 DSH 前端版本；
+- 跨步骤的循环（每一步都是「说一句 → 调同一个工具」）不在本插件范围内，那是内置 `guard/repeat-tool-reminder` 的职责；
+- `retryTemperature` 需要适配器支持 temperature；Ollama 的重复惩罚等参数 DSH 目前没有通用字段，无法从这里设置。
+
+## 开发与测试
+
+```bash
+npm install
+npm test
+```
+
+## 相关项目
+
+- [dsh-remote-access-proxy](https://github.com/citydirector/dsh-remote-access-proxy)：在手机、平板或另一台电脑上使用 DSH
+- [deepinfra-fusion-proxy](https://github.com/citydirector/deepinfra-fusion-proxy)：DeepInfra Standard / Flex 按会话切换与自动回退
+- [dsh-session-manager](https://github.com/citydirector/dsh-session-manager)：离线会话管理器，可升级、归档、清洗循环、修复烂尾会话
+
+## 许可证
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,15 @@
+# dsh-loop-rescue 的 bundle 补丁：默认配置即可挂载。
+# 与 @mrweicodes/dsh-loop-guard 二选一：两者都包装 llm/stream，同时开会重复切断。
+#
+# 按需在 profile 里覆盖，例如：
+#
+#   - set:
+#       - id: loop-rescue
+#         config:
+#           mode: rescue            # rescue | cut | observe
+#           retryTemperature: 1.0   # 续跑那一次请求换个温度
+#           maxConsecutiveRescues: 3
+
+- insert:
+    - id: loop-rescue
+      name: 'dsh-loop-rescue'

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "dsh-loop-rescue",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "DSH plugin that cuts model repetition loops mid-stream, prunes the loop out of the committed message, and resumes automatically.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./detector": "./src/detector.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "tools",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.spec.mjs",
+    "scan": "node tools/scan-session.mjs"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "loop",
+    "repetition",
+    "guard"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/citydirector/dsh-loop-rescue.git"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.6-alpha.1",
+    "@deepseek-ai/dsh-llm": ">=0.2.2-alpha.2 <0.3.0"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.6-alpha.1",
+    "@deepseek-ai/dsh-llm": "0.2.2-alpha.2"
+  },
+  "engines": {
+    "node": ">=24.9.0",
+    "dsh": ">=0.2.2-alpha.2 <0.3.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/detector.js

@@ -0,0 +1,255 @@
+/**
+ * 纯函数检测器：不依赖任何 @deepseek-ai/* 包，插件和离线扫描脚本共用同一份判定。
+ *
+ * 两条规则，都在流内逐段运行，并且都能给出「循环从哪里开始」的精确位置，
+ * 这是本插件能把循环从落盘内容里剪掉的前提：
+ *
+ * - **短句池轮转（pool）**：最近 N 个句子几乎全由少数几个反复出现的短句组成，
+ *   例如 `Now. / OK. / Enough. / Let me write. / Emit. / Producing.`。
+ *   这是 DeepSeek 退化时最常见的形态，逐字周期检测抓不到，因为轮转顺序会变。
+ * - **逐字周期（cycle）**：尾部是一段文字的逐字重复（段落、长句、代码块被原样
+ *   刷屏）。用尾部指纹的历史出现位置当候选周期，代价与流长度无关。
+ *
+ * 句子切分：句末标点（. ! ? 。！？…）后接空白，或换行。纯符号句子（表格分隔线、
+ * `}`、`---`）不计入统计，也不打断循环段，避免把表格、日志、代码误判成循环。
+ * 正文模式下 ``` 代码块内部完全跳过。
+ *
+ * @module dsh-loop-rescue/detector
+ */
+
+/** 默认阈值。按「宁可晚切一点，也不误伤正常输出」标定。 */
+export const DEFAULTS = Object.freeze({
+  /** 短句池：参与判定的最近句子数。 */
+  poolWindow: 30,
+  /** 短句池：窗口内句子的平均长度上限（字符）。 */
+  poolMaxMeanChars: 60,
+  /** 短句池：窗口内总长度下限（汉字按 3 计），太短不判。 */
+  poolMinChars: 120,
+  /** 短句池：一个句子在窗口内出现几次才算「反复出现」。 */
+  poolMinRepeats: 3,
+  /** 短句池：反复出现的句子占窗口的比例下限。 */
+  poolMinCoverage: 0.75,
+  /** 回溯循环起点时，允许夹杂的连续新句子数。 */
+  poolGapAllowance: 2,
+  /** 逐字周期：最短周期（字符）。 */
+  cycleMinPeriod: 16,
+  /** 逐字周期：最长周期（字符）。 */
+  cycleMaxPeriod: 4000,
+  /** 逐字周期：重复部分总长下限（字符）。 */
+  cycleMinChars: 600,
+  /** 逐字周期：至少重复几遍。 */
+  cycleMinReps: 3,
+  /** 逐字周期：每新增多少字符检查一次。 */
+  cycleCheckEvery: 128,
+})
+
+const ASCII_TERMINATOR = /[.!?]/
+const CJK_TERMINATOR = /[。！？…]/
+const HAS_WORD = /[\p{L}\p{N}]/u
+/** 正文里的列表项、表格行、引用行：结构化内容，天然重复，不计入短句池。 */
+const STRUCTURED_LINE = /^(?:[-*+|>]|\d+[.)])\s?/
+
+/**
+ * 把句子规范成比较用的键：小写、合并空白、去掉首尾标点。
+ * 数字保留原样：编号不同的行（表格、清单）本来就不是同一句话。
+ * @param {string} s
+ * @returns {string}
+ */
+export function normalizeUnit(s) {
+  return s
+    .toLowerCase()
+    .replace(/\s+/g, ' ')
+    .replace(/^[\s\p{P}\p{S}]+|[\s\p{P}\p{S}]+$/gu, '')
+}
+
+/**
+ * 长度估算：CJK 字符信息密度高，按 3 个字符计，使中英文阈值大致可比。
+ * @param {string} s
+ * @returns {number}
+ */
+export function weightedLength(s) {
+  let n = 0
+  for (const ch of s) n += /[\u3400-\u9fff\uf900-\ufaff\u3040-\u30ff\uac00-\ud7af]/.test(ch) ? 3 : 1
+  return n
+}
+
+/**
+ * @typedef {object} Detection
+ * @property {'pool' | 'cycle'} rule 命中的规则
+ * @property {number} cut 循环起点（在累计文本里的 UTF-16 下标），保留 `text.slice(0, cut)`
+ * @property {number} repeatedChars 被判为循环的字符数（`text.length - cut`）
+ * @property {number} [period] 逐字周期的周期长度
+ * @property {string[]} [pool] 短句池里的句子（规范化后）
+ */
+
+/**
+ * 单个 block（一段推理或一段正文）的流式循环检测器。
+ */
+export class StreamLoopDetector {
+  /**
+   * @param {'reasoning' | 'text'} kind 推理还是正文；正文会跳过代码块
+   * @param {Partial<typeof DEFAULTS>} [options]
+   */
+  constructor(kind, options = {}) {
+    this.kind = kind
+    this.o = { ...DEFAULTS, ...options }
+    /** 累计文本。 */
+    this.text = ''
+    /** @type {{start: number, end: number, key: string}[]} 已切出的计数句子 */
+    this.units = []
+    this.unitStart = 0
+    this.inFence = false
+    this.lastCycleCheck = 0
+    /** @type {Detection | undefined} */
+    this.detection = undefined
+  }
+
+  /**
+   * 追加一段增量。返回第一次命中的检测结果；命中后不再变化。
+   * @param {string} delta
+   * @returns {Detection | undefined}
+   */
+  push(delta) {
+    if (this.detection !== undefined || delta.length === 0) return this.detection
+    const from = this.text.length
+    this.text += delta
+    for (let i = from; i < this.text.length; i++) {
+      const ch = this.text[i]
+      const next = this.text[i + 1]
+      const atLineEnd = ch === '\n'
+      // 中文句末标点直接切；英文标点后面跟空白才切（避免切开 1.5、a.b），
+      // 流尾的英文标点等下一段增量再说。
+      const atSentenceEnd = CJK_TERMINATOR.test(ch)
+        || (ASCII_TERMINATOR.test(ch) && next !== undefined && /\s/.test(next))
+      if (atLineEnd || atSentenceEnd) {
+        this.closeUnit(i + 1)
+        if (this.detection !== undefined) return this.detection
+      }
+    }
+    if (this.text.length - this.lastCycleCheck >= this.o.cycleCheckEvery) {
+      this.lastCycleCheck = this.text.length
+      const hit = this.checkCycle()
+      if (hit !== undefined) this.detection = hit
+    }
+    return this.detection
+  }
+
+  /** @param {number} end */
+  closeUnit(end) {
+    const raw = this.text.slice(this.unitStart, end)
+    const start = this.unitStart
+    this.unitStart = end
+    const trimmed = raw.trim()
+    if (this.kind === 'text' && trimmed.startsWith('```')) {
+      this.inFence = !this.inFence
+      this.units = []
+      return
+    }
+    if (this.inFence) return
+    if (!HAS_WORD.test(trimmed)) return // 纯符号：中性，不计也不断
+    if (this.kind === 'text' && STRUCTURED_LINE.test(trimmed)) return // 列表/表格：中性
+    this.units.push({ start: start + raw.indexOf(trimmed), end, key: normalizeUnit(trimmed) })
+    if (this.units.length > this.o.poolWindow * 4) this.units.splice(0, this.units.length - this.o.poolWindow * 4)
+    const hit = this.checkPool()
+    if (hit !== undefined) this.detection = hit
+  }
+
+  /** @returns {Detection | undefined} */
+  checkPool() {
+    const o = this.o
+    if (this.units.length < o.poolWindow) return undefined
+    const win = this.units.slice(-o.poolWindow)
+    let chars = 0
+    const counts = new Map()
+    for (const u of win) {
+      chars += weightedLength(u.key)
+      counts.set(u.key, (counts.get(u.key) ?? 0) + 1)
+    }
+    if (chars < o.poolMinChars) return undefined
+    if (chars / win.length > o.poolMaxMeanChars) return undefined
+    const pool = new Set([...counts].filter(([, n]) => n >= o.poolMinRepeats).map(([k]) => k))
+    // 只有一个句子在刷屏属于逐字周期的范畴，这里要求至少两种句子在轮转。
+    if (pool.size < 2) return undefined
+    let covered = 0
+    for (const u of win) if (pool.has(u.key)) covered++
+    if (covered / win.length < o.poolMinCoverage) return undefined
+
+    // 回溯：从尾部往前走，经过池内句子，允许夹杂少量新句子。
+    let first = this.units.length - 1
+    let gap = 0
+    for (let i = this.units.length - 1; i >= 0; i--) {
+      if (pool.has(this.units[i].key)) {
+        first = i
+        gap = 0
+      } else if (++gap > o.poolGapAllowance) break
+    }
+    const cut = this.units[first].start
+    return { rule: 'pool', cut, repeatedChars: this.text.length - cut, pool: [...pool] }
+  }
+
+  /** @returns {Detection | undefined} */
+  checkCycle() {
+    const o = this.o
+    const s = this.text
+    const n = s.length
+    if (n < o.cycleMinChars) return undefined
+    // 正文里代码块内部的重复（生成数据、样例）不归本规则管。
+    if (this.kind === 'text' && this.inFence) return undefined
+    const probe = Math.min(32, o.cycleMinPeriod)
+    const tail = s.slice(n - probe)
+    const windowStart = Math.max(0, n - o.cycleMaxPeriod - probe)
+    // 尾部指纹在之前出现的位置 → 候选周期。取最近的几个。
+    const candidates = []
+    let at = n - probe - 1
+    while (candidates.length < 6) {
+      const idx = s.lastIndexOf(tail, at)
+      if (idx < windowStart || idx < 0) break
+      const period = n - probe - idx
+      if (period >= o.cycleMinPeriod) candidates.push(period)
+      at = idx - 1
+    }
+    for (const p of candidates) {
+      // 从尾部往前数，s[i] === s[i + p] 连续成立的长度。
+      let i = n - 1 - p
+      while (i >= 0 && s[i] === s[i + p]) i--
+      const runStart = i + 1 // [runStart, n) 以周期 p 自重复
+      const span = n - runStart
+      const reps = span / p + 1
+      if (span + p < o.cycleMinChars || reps < o.cycleMinReps) continue
+      // 第一份拷贝本身可能是正常内容，保留它，从第二份起剪。
+      // 周期回溯会多吃掉前文里恰好相同的几个字符（如 ".\n"），把切点吸附到下一个换行之后。
+      let cut = Math.min(n, runStart + p)
+      const nl = s.indexOf('\n', cut - 1)
+      if (nl !== -1 && nl - cut < Math.min(p, 120)) cut = nl + 1
+      return { rule: 'cycle', cut, repeatedChars: n - cut, period: p }
+    }
+    return undefined
+  }
+
+  /**
+   * 流结束后的最终检查（尾部不足 cycleCheckEvery 的部分也查一遍，并把未闭合的最后一句计入）。
+   * @returns {Detection | undefined}
+   */
+  finish() {
+    if (this.detection !== undefined) return this.detection
+    if (this.unitStart < this.text.length) this.closeUnit(this.text.length)
+    if (this.detection === undefined) this.detection = this.checkCycle()
+    return this.detection
+  }
+}
+
+/**
+ * 对一段完整文本跑一遍检测（离线扫描与测试用）。
+ * @param {'reasoning' | 'text'} kind
+ * @param {string} text
+ * @param {Partial<typeof DEFAULTS>} [options]
+ * @param {number} [chunk] 模拟流的切片大小
+ * @returns {Detection | undefined}
+ */
+export function detectInText(kind, text, options, chunk = 24) {
+  const d = new StreamLoopDetector(kind, options)
+  for (let i = 0; i < text.length; i += chunk) {
+    if (d.push(text.slice(i, i + chunk)) !== undefined) return d.detection
+  }
+  return d.finish()
+}