dsh-repeat-guard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yuqing
+
+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,193 @@
+# dsh-repeat-guard
+
+拦截思考段的"复读"退化：模型在思考里陷入反复输出"好。""执行。"这类碎片空话时，掐断本次生成，并让本轮继续往下跑，而不是停下来等用户输入。
+
+| 项 | 说明 |
+|---|---|
+| 类型 | dsh host 侧插件（函数式） |
+| 监听 | `llm/stream`、`agent/turn-stopping` |
+| 运行时依赖 | **无**，不产生任何运行时 import |
+| 构建期依赖 | 仅 TypeScript |
+| 入口 | `lib/index.js`（由 `src/index.ts` 编译得到） |
+| 分发 | npm 包 `dsh-repeat-guard` |
+
+---
+
+## 它解决什么问题
+
+模型退化时，思考段里会出现整行都是空话的情况，如"好。""执行。""OK." "Let me go."。
+
+这类思考本身不含信息，但会一直持续到 token 耗尽，把一次本可以正常完成的任务拖垮。
+
+## 检测范围
+
+**只看思考段（`reasoning-delta`），正文（`text-delta`）不参与判定，原样透传。**
+
+复读退化先出现在思考段，那时正文往往还没开始产出；等正文也碎掉再掐，思考段已经白烧了一遍。
+
+## 判据：查表
+
+判定不做任何"形状归纳"，只查一张表：**思考里有没有独占一行的表项**。
+
+最初试过两条归纳式判据，都被证伪：
+
+1. **数碎片重复了几次**（"好，好，好，好"）。它不看句子结构，只看重复次数，于是"然后，然后，然后，"（逗号被当作片段分隔符）这类正常句子会被判成复读。
+2. **按形状判断空话行**（中文去标点后 ≤2 字、英文 ≤3 词）。形状规则必然外溢："解。""豫。"这种被换行切开的半截词也满足形状，实测在大段正常思考里频繁误杀。
+
+表项是具体的、可增删的、可审计的，不会外溢。规则只有一条：
+
+```
+整行去掉首尾空白 → 转小写 → 查表
+```
+
+| 输入 | 结果 |
+|---|---|
+| `好。` `好的。` `执行。` `写。` `明白。` | 拦（表内） |
+| `OK.` `Sure.` `Let me go.` `Got it.` | 拦（表内） |
+| `查一下。` `这需要我。` | 不拦（表外） |
+| `A.` `1.` | 不拦（表外） |
+| `然后，` `注意：` `好的，` | 不拦（表外） |
+| `好？` `好！` `好` `OK` | 不拦（表外） |
+| `我需要检查实现。\n然后重新编译。` | 不拦（各行都在表外） |
+
+**表在 `src/detect.ts` 的 `FRAGMENTS` 数组里**，增删词条改它即可。表项**连标点一起写**（`'好的。'` 对应思考里的 `好的。`），英文条目一律写小写。
+
+已知边界：判据只看"有没有这样一行"，不看上下文。所以"用户想让我改代码。\n好的。"这种**前面有实质内容、结尾又跟一句空话**的思考也会被拦。这是"按行判定"的直接结果。
+
+## 工作原理
+
+1. 包一层 `llm/stream`（模型调用的流式 waterfall），逐 chunk 观察 `reasoning-delta`，累积本次响应已产出的思考文本。
+2. 命中退化时，把触发退化的那个 delta 照常放行，补一个 `block-end` 闭合思考块，再补一个 `finish(stop)`，然后结束流。agent-loop 的 `BlockAssembler` 会把这种"没有 finish 就结束"的流当作正常 `stop`，于是本次调用被当成正常完成：已生成的思考照常落盘。
+3. 提前结束流时显式向下游传播 `iterator.return()`，否则上游 HTTP 流会继续跑到结束，供应商照常计满 token，且连接悬挂。
+4. 光截断只会让本轮就此结束、停下来等用户输入。所以再挂一个 `agent/turn-stopping` 监听器，在本轮边界提交之前调 `agent.steer(...)` 推一条输入，本轮就会接着再跑一步。
+
+辅助调用（上下文压缩、会话标题等带 `purpose` 的调用）不参与检测。
+
+每次拦截都会把**命中的那一行原文**写进 journal，便于事后核对误杀：
+
+```
+[repeat-guard] 检出思考段复读，已掐断本次生成 | 命中行="好的。"
+```
+
+## 掐断之后怎么让本轮继续
+
+dsh 的 turn 循环（`dsh-agent-loop/lib/index.js:966-973`）：
+
+```js
+if (turnEnds && this.inbox.nextStep.length === 0) {
+  await this.dispatch.serial("agent/turn-stopping", { turn, signal });
+}
+if (turnEnds && this.inbox.nextStep.length === 0) break;   // 重读收件箱
+```
+
+`agent/turn-stopping` 在 `break` 之前被 `await`，之后收件箱会被**重新读一次**。所以只要监听器往 `inbox.nextStep` 里推入东西，本轮就不 break，而是再跑一步。官方对该事件的说明也写明了这个用法，先例见 `dsh-hooks-claude-code/lib/index.js:292`。
+
+注意：
+
+- **做不到"这一步当作没发生"。** 被截断的 assistant 消息在 `step()` 里已经 `session.append` 落盘，dsh 没有回滚一步的机制；`step()` 唯一返回 `null`（循环继续）的出口要求本步真的产生了 tool-call，插件够不着。所以这里的语义是"接着再跑一步"，会话里会留下被截断的思考记录。
+
+## 可调项
+
+判定本身没有阈值，只有 `src/detect.ts` 里的 `FRAGMENTS` 表。改完需要重新构建。
+
+| 项 | 位置 | 含义 |
+|---|---|---|
+| `FRAGMENTS` | `src/detect.ts` | 会被判为复读的空话短句表，增删词条改它 |
+
+## 续跑时推给模型的输入
+
+```
+[复读拦截]
+你上一段思考退化成了碎片复读（反复输出"好。"一类的空话），已被系统截断。
+请直接继续执行下一步，不要再输出任何确认语、寒暄或空话。
+```
+
+这条消息带 `source.kind = 'plugin'`，客户端会渲染成折叠的 context 行，不是用户气泡。
+
+## 构建
+
+```bash
+npm install
+npm run build        # 等价于 tsc，产出 lib/
+```
+
+`lib/` **不进版本库**：`npm publish` 前由 `prepack` 钩子现构建，随包发布（`files` 字段已含 `lib`）。这样"改了 `src/` 忘了 build"不会让旧产物静默跟着提交——代价是构建失败时发不出去，这是有意的。
+
+## 发布
+
+```bash
+npm login   --registry=https://registry.npmjs.org
+npm publish --registry=https://registry.npmjs.org
+```
+
+**两条命令都别省 `--registry`。** npm 的凭据是**按源绑定**的：`npm login` 登的是哪个源，`~/.npmrc` 里就只在那个源下记一条 `//registry.npmjs.org/:_authToken`。所以 `npm config get registry` 一旦被切到 npmmirror 这类只读镜像（它本身也发不上去），不带参数的 `npm publish` 会直接报 `need auth`。
+
+发布前不必手动构建，`prepack` 会跑一次 `npm run build`；tsc 报错则发布中止。
+
+## 安装到 dsh
+
+```bash
+dsh plugin --profile web add dsh-repeat-guard
+```
+
+本插件是一个 **dsh bundle**——包根带 `cordis.patch.yml`，由 `package.json` 的 `dsh.bundle.patch` 声明。装进 profile 时它会自动进入 `dsh.profile.bundles` 分层栈，**不需要改 profile 自己的 `cordis.patch.yml`**。
+
+装完**必须重启 dsh 进程**。`patchReload: live` 只重载已有的层，不会加载新增的层——实测编辑后运行中的进程既不加载也不报错。
+
+机制（dsh 源码）：`dsh plugin` 是 pnpm 转发器（`dsh/lib/plugin-*.js`），在 profile 目录跑 `pnpm add` 后按**安装后的真实包名**调和 `dsh.profile.bundles`，判定条件就是 `dsh.bundle.patch` 是否为 undefined（没有就印一句 "declares no dsh.bundle — installed as a plain dependency, not a profile layer"）。加载时 `dsh-app-boot` 的 `loadProfileDirectory` 对该字段做 `join(packageDir, declared)` 并当 overlay patch 读；声明缺失直接抛错。
+
+**只走 npm 分发。** git 安装（`add github:...`）会让 pnpm 拦下依赖的构建脚本，装出来的包没有 `lib/index.js`，除非安装者手工去 profile 的 `pnpm-workspace.yaml` 加 `allowBuilds` 白名单——那等于把本机的构建配置摊派给每个使用者。本地目录安装同理，只适合开发调试，不作为分发方式。
+
+验证是否加载：
+
+```bash
+journalctl --user -u dsh-web --no-pager | grep -a repeat-guard
+# [repeat-guard] 已加载，复读拦截生效
+```
+
+⚠️ 插件加载失败会让 **dsh 启动直接失败**，而 dsh-web 是本机 GUI 的唯一通道。改完先离线验证再重启：用假上下文 import 产物调一次入口，或喂一段真实 chunk 序列。
+
+## 开发约束：不得 import 外部包
+
+**不得 import 任何外部包，包括 `@deepseek-ai/cordis`；模块之间只用相对路径互相导入。**
+
+`cordis-plugin-loader` 的 `import()` 对**裸 specifier**（包名）直接 `import(name)`，锚点是 loader 自身的文件位置（dsh 安装目录内部），从 profile 或全局顶层加载时都可能解析不到插件的依赖。而**相对 specifier** 走 `new URL(name, baseUrl)`，由 Node 原生 ESM 按当前文件位置解析，不受影响——所以内部拆模块是安全的，新增模块时只连相对路径即可，源码里要带 `.js` 后缀。
+
+由这条约束派生的两点：
+
+- 类型一律在 `src/types.ts` 里声明，不 import dsh 的类型（那还要为 `tsc` 配 `paths` 指向 dsh 安装目录，路径里带 node 版本号，dsh 一升级就失效），也不引 `@types/node`（各模块按需 `declare` 用到的全局）；
+- 只用 TypeScript 写源码，由 `tsc` 产出 `lib/` 供 dsh 加载。dsh 的 loader 是原生 ESM import，**没有转译层**，运行时读到的永远是编译产物——改完 `src/` 必须重新构建才能生效。`lib/` 只随 npm 包发布，不进版本库。
+
+## 代码约定
+
+| 项 | 约定 |
+|---|---|
+| 缩进 / 引号 / 分号 | 2 空格、单引号、语句末分号 |
+| 行宽 | 目标 100 字符，上限 120（中英混排按字符数计） |
+| 控制语句 | **一律带花括号**，单行 `if`、`continue`、`break` 也不例外，不写 `if (x) return;` |
+| 文件 | 一个文件只干一件事：类型声明 / 判定 / 续跑 / 单个监听器 / 装配，各占一个文件 |
+| 函数 | 不超过 50 行；超了就先看能不能按职责拆开 |
+| 注释 | 一律中文；导出函数与判定函数配 `@param` / `@returns`，文件内小工具函数用单行注释即可 |
+
+排版细节已固化在 `.editorconfig`。花括号、文件职责、函数行数这三条没有配置项可表达，只能靠人工遵守。
+
+## 目录结构
+
+```
+.
+├── src/
+│   ├── index.ts                 插件入口：装配状态，注册两个监听器（只做装配）
+│   ├── types.ts                 与 dsh 交互的接口声明（纯类型，编译后为空模块）
+│   ├── detect.ts                复读判定：阈值常量 + 纯函数，不碰会话状态
+│   ├── resume.ts                续跑：注入文案、消息构造、推送
+│   ├── stream-guard.ts          llm/stream 监听器：思考段检测与掐断
+│   └── turn-stopping-guard.ts   agent/turn-stopping 监听器：让本轮继续
+├── lib/                         tsc 产物（已 gitignore），dsh 实际加载 lib/index.js
+├── package.json
+└── tsconfig.json
+```
+
+
+## 许可
+
+MIT，见 `LICENSE`。

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# dsh-repeat-guard 的 bundle 补丁：把本插件插进宿主配置。
+#
+# 本文件由 package.json 的 dsh.bundle.patch 字段声明，安装后由 dsh 自动加载，
+# 装在 profile 里的用户不需要改自己的 cordis.patch.yml。
+- insert:
+    - id: dsh-repeat-guard
+      name: dsh-repeat-guard

package/lib/detect.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 复读退化判定：查表。
+ *
+ * 表里是已知会被模型复读的空话短句，**连标点一起写**。判定就是"思考里有没有
+ * 独占一行的表项"，整行与表项全等，不拆解行的内部。
+ *
+ * 增删条目直接改下面的 FRAGMENTS 即可，改完重新构建。
+ */
+/**
+ * 找出退化的碎片行。
+ * @param text - 已生成的思考文本。
+ * @returns 命中返回该行的原文，未命中返回 null。
+ */
+export declare function findDegenerateLine(text: string): string | null;

package/lib/detect.js

@@ -0,0 +1,65 @@
+/**
+ * 复读退化判定：查表。
+ *
+ * 表里是已知会被模型复读的空话短句，**连标点一起写**。判定就是"思考里有没有
+ * 独占一行的表项"，整行与表项全等，不拆解行的内部。
+ *
+ * 增删条目直接改下面的 FRAGMENTS 即可，改完重新构建。
+ */
+/**
+ * 会被复读的空话短句表，标点照原样写。
+ *
+ * 英文条目一律写小写，判定时会把整行转成小写再比。
+ */
+const FRAGMENTS = [
+    // 中文
+    '好。',
+    '好的。',
+    '好嘞。',
+    '对。',
+    '对的。',
+    '是。',
+    '是的。',
+    '行。',
+    '嗯。',
+    '可以。',
+    '明白。',
+    '收到。',
+    '了解。',
+    '执行。',
+    '继续。',
+    '确认。',
+    '完成。',
+    '搞定。',
+    '写。',
+    '查。',
+    '看。',
+    // 英文
+    'ok.',
+    'okay.',
+    'sure.',
+    'alright.',
+    'right.',
+    'yes.',
+    'done.',
+    'got it.',
+    'let me go.',
+    'let me do it.',
+    'check it.',
+];
+/** 查表用的集合。 */
+const FRAGMENT_SET = new Set(FRAGMENTS);
+/**
+ * 找出退化的碎片行。
+ * @param text - 已生成的思考文本。
+ * @returns 命中返回该行的原文，未命中返回 null。
+ */
+export function findDegenerateLine(text) {
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (line !== '' && FRAGMENT_SET.has(line.toLowerCase())) {
+            return line;
+        }
+    }
+    return null;
+}

package/lib/index.d.ts

@@ -0,0 +1,6 @@
+import type { PluginContext } from './types.js';
+/**
+ * 函数式插件入口。ctx 为 cordis 上下文，注册的监听随插件卸载自动释放。
+ * @param ctx - 宿主 cordis 上下文。
+ */
+export default function repeatGuard(ctx: PluginContext): void;

package/lib/index.js

@@ -0,0 +1,38 @@
+// dsh-repeat-guard — host 侧插件入口：拦截"复读"型退化输出。
+//
+// 做法：包一层 `llm/stream`（模型调用的流式 waterfall），逐 chunk 观察思考段
+// （reasoning-delta）。命中退化时，把触发退化的那个 delta 照常放行，补一个 block-end
+// 闭合思考块，再补一个 finish(stop)，然后直接结束流。agent-loop 的 BlockAssembler 会把
+// 这种"没有 finish 就结束"的流当作正常 stop（assembler.js: `this._finish ?? {kind:'stop'}`），
+// 于是本次调用被当成正常完成：已生成的思考照常落盘，本轮该走什么流程就走什么流程。
+//
+// 只检测思考段：正文 text-delta 不参与判定。复读退化先出现在思考段，那时正文往往还没
+// 开始产出；等正文也碎掉再掐，思考段已经白烧了一遍。
+//
+// 判定做什么：思考段里出现单独成行的一句空话（中文一到两个汉字，如"好。""执行。"；
+// 英文不超过三个单词，如"OK." "Let me go."）就掐断。判据的取舍见 detect.ts 的注释——
+// 关键是不能把"同样的碎片出现了几次"当作复读信号，那样会误伤正常的短句。
+//
+// 掐断之后要让本轮继续，而不是停下来等用户输入：挂在 `agent/turn-stopping` 上，在本轮
+// 边界提交之前调 `agent.steer(...)` 推一条输入，机器就会再跑一步。详见 resume.ts。
+//
+// 依赖约束（重要）：不得 import 任何外部包，包括 @deepseek-ai/cordis。
+// cordis-plugin-loader 解析裸 specifier 时直接 `import(name)`，锚点是 loader 自身的
+// 文件位置（dsh 安装目录内部），从 profile 或全局顶层加载时都可能解析不到插件的依赖。
+// **相对路径 import 不受此限**：它由 Node 原生 ESM 按当前文件位置解析，所以本插件内部
+// 按职责拆出的这些模块可以正常互相导入。新增模块时照此办理：只连相对路径。
+//
+// 本文件只做装配，具体逻辑在各自的模块里。
+import { createStreamGuard } from './stream-guard.js';
+import { createTurnStoppingGuard } from './turn-stopping-guard.js';
+/**
+ * 函数式插件入口。ctx 为 cordis 上下文，注册的监听随插件卸载自动释放。
+ * @param ctx - 宿主 cordis 上下文。
+ */
+export default function repeatGuard(ctx) {
+    // 直接写 stdout：dsh 把插件的 stdout 收进 journal，便于确认插件确实被加载。
+    console.log('[repeat-guard] 已加载，复读拦截生效');
+    const state = { pending: new Set() };
+    ctx.on('llm/stream', createStreamGuard(state), { global: true });
+    ctx.on('agent/turn-stopping', createTurnStoppingGuard(state));
+}

package/lib/resume.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 续跑：截断之后让本轮不要就此关闭，而是再跑一步。
+ *
+ * 机制在 dsh 侧：`agent/turn-stopping` 是 serial 事件，在本轮边界提交之前被 await，
+ * 之后收件箱会被重新读一次（dsh-agent-loop/lib/index.js:967-973）：
+ *
+ *     if (turnEnds && this.inbox.nextStep.length === 0) {
+ *       await this.dispatch.serial("agent/turn-stopping", { turn, signal });
+ *     }
+ *     if (turnEnds && this.inbox.nextStep.length === 0) break;   // 重读，读到东西就不 break
+ *
+ * 所以在监听器里调 `agent.steer(...)` 推入一条输入，本轮就会再跑一步，而不是停下来等
+ * 用户输入。dsh 自己在 dsh-hooks-claude-code/lib/index.js:292 有同样的用法。
+ */
+import type { GuardState, SteerableAgent } from './types.js';
+/**
+ * 本轮即将关闭时，若上一步刚被掐断过，就推一条输入让本轮继续。
+ * @param state - 跨监听保留的拦截状态。
+ * @param agent - 本轮所属的 agent 句柄。
+ */
+export declare function reviveTurn(state: GuardState, agent: SteerableAgent | undefined): void;

package/lib/resume.js

@@ -0,0 +1,64 @@
+/**
+ * 续跑：截断之后让本轮不要就此关闭，而是再跑一步。
+ *
+ * 机制在 dsh 侧：`agent/turn-stopping` 是 serial 事件，在本轮边界提交之前被 await，
+ * 之后收件箱会被重新读一次（dsh-agent-loop/lib/index.js:967-973）：
+ *
+ *     if (turnEnds && this.inbox.nextStep.length === 0) {
+ *       await this.dispatch.serial("agent/turn-stopping", { turn, signal });
+ *     }
+ *     if (turnEnds && this.inbox.nextStep.length === 0) break;   // 重读，读到东西就不 break
+ *
+ * 所以在监听器里调 `agent.steer(...)` 推入一条输入，本轮就会再跑一步，而不是停下来等
+ * 用户输入。dsh 自己在 dsh-hooks-claude-code/lib/index.js:292 有同样的用法。
+ */
+/** 续跑时推给模型的指令正文。 */
+const RESUME_TEXT = [
+    '[复读拦截]',
+    '你上一段思考退化成了碎片复读（反复输出"好。"一类的空话），已被系统截断。',
+    '请直接继续执行下一步，不要再输出任何确认语、寒暄或空话。',
+].join('\n');
+/** 折叠行显示的一行摘要；空字符串会让客户端回退成 opaque 渲染，故不可为空。 */
+const RESUME_SUMMARY = '复读已截断：请继续执行';
+/**
+ * 构造推给模型的一条输入，结构与 dsh 的 createUserMessage 对齐。
+ * @returns 一条插件来源的 user 消息，客户端会渲染成折叠的 context 行。
+ */
+function resumeMessage() {
+    return {
+        id: crypto.randomUUID(),
+        role: 'user',
+        content: [{ type: 'text', text: RESUME_TEXT }],
+        source: {
+            kind: 'plugin',
+            plugin: 'repeat-guard',
+            form: 'notice',
+            summary: RESUME_SUMMARY,
+        },
+    };
+}
+/**
+ * 本轮即将关闭时，若上一步刚被掐断过，就推一条输入让本轮继续。
+ * @param state - 跨监听保留的拦截状态。
+ * @param agent - 本轮所属的 agent 句柄。
+ */
+export function reviveTurn(state, agent) {
+    // 三个提前返回都要留痕：不打印就无法区分"没触发""id 对不上""没有标记"。
+    if (agent === undefined || typeof agent.steer !== 'function') {
+        console.log('[repeat-guard] turn-stopping：载荷里没有 agent 句柄，不续跑');
+        return;
+    }
+    const sessionId = agent.session?.id;
+    if (sessionId === undefined) {
+        console.log('[repeat-guard] turn-stopping：agent 上没有会话 id，不续跑');
+        return;
+    }
+    if (!state.pending.has(sessionId)) {
+        console.log(`[repeat-guard] turn-stopping：会话 ${sessionId} 没有待续跑标记，不续跑` +
+            `（当前有标记的会话：${[...state.pending].join(',') || '无'}）`);
+        return;
+    }
+    state.pending.delete(sessionId);
+    console.log(`[repeat-guard] turn-stopping：会话 ${sessionId} 续跑一步`);
+    agent.steer(resumeMessage());
+}

package/lib/stream-guard.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `llm/stream` 监听器：包一层上游流，思考段命中复读退化就补完流并提前结束。
+ *
+ * 只检测 reasoning-delta（思考段）。正文 text-delta 不参与判定，原样透传。
+ */
+import type { GenerateOptions, GuardState, StreamChunk } from './types.js';
+/** `llm/stream` 的监听器签名。 */
+export type StreamListener = (options: GenerateOptions, next: () => AsyncIterable<StreamChunk>) => AsyncIterable<StreamChunk>;
+/**
+ * 造一个 `llm/stream` 监听器。
+ * @param state - 跨监听保留的拦截状态。
+ * @returns 监听器；辅助调用直接透传，其余包一层复读检测。
+ */
+export declare function createStreamGuard(state: GuardState): StreamListener;

package/lib/stream-guard.js

@@ -0,0 +1,71 @@
+/**
+ * `llm/stream` 监听器：包一层上游流，思考段命中复读退化就补完流并提前结束。
+ *
+ * 只检测 reasoning-delta（思考段）。正文 text-delta 不参与判定，原样透传。
+ */
+import { findDegenerateLine } from './detect.js';
+/**
+ * 逐 chunk 检查上游流的思考段，命中复读退化时补完这段流。
+ *
+ * 适配器只开一个 reasoning 块（dsh-llm-deepseek: `reasoningBlock` 是单个变量），
+ * 所以累积文本用一个字符串即可，不需要按 index 分开存。
+ *
+ * @param downstream - 上游模型的流。
+ * @param sessionId - 当前会话 id；有值才登记待续跑标记。
+ * @param state - 跨监听保留的拦截状态。
+ * @returns 包好的流。
+ */
+async function* guardStream(downstream, sessionId, state) {
+    const iterator = downstream[Symbol.asyncIterator]();
+    let accumulated = '';
+    try {
+        for (;;) {
+            const step = await iterator.next();
+            if (step.done) {
+                return;
+            }
+            const chunk = step.value;
+            if (chunk?.type === 'reasoning-delta' && typeof chunk.text === 'string') {
+                accumulated += chunk.text;
+                const hit = findDegenerateLine(accumulated);
+                if (hit !== null) {
+                    if (sessionId !== undefined) {
+                        state.pending.add(sessionId);
+                    }
+                    console.log(`[repeat-guard] 检出思考段复读，已掐断本次生成 | 会话=${sessionId ?? '无'} | 命中行=${JSON.stringify(hit)}`);
+                    // 触发点本身已经产生了，照常放行；要掐掉的是它之后的思考。
+                    const index = chunk.index ?? 0;
+                    yield chunk;
+                    yield { type: 'block-end', index, block: { type: 'reasoning', text: accumulated } };
+                    yield { type: 'finish', reason: { kind: 'stop' } };
+                    return;
+                }
+            }
+            yield chunk;
+        }
+    }
+    finally {
+        // 提前 return 时必须显式向下游传播：不补这一步上游 HTTP 流会继续跑到结束，
+        // 供应商照常计满 token，且连接悬挂。上游可能已经结束/关闭，其异常忽略。
+        try {
+            await iterator.return?.();
+        }
+        catch {
+            /* 上游已经结束或关闭，无需处理 */
+        }
+    }
+}
+/**
+ * 造一个 `llm/stream` 监听器。
+ * @param state - 跨监听保留的拦截状态。
+ * @returns 监听器；辅助调用直接透传，其余包一层复读检测。
+ */
+export function createStreamGuard(state) {
+    return (options, next) => {
+        // 辅助调用（上下文压缩、会话标题）不参与检测。
+        if (options.purpose !== undefined) {
+            return next();
+        }
+        return guardStream(next(), options.sessionId, state);
+    };
+}

package/lib/turn-stopping-guard.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `agent/turn-stopping` 监听器：把上一步掐断欠下的续跑补上。
+ *
+ * 监听器的返回值不被使用（该事件是 serial 的副作用钩子），实现方式是调
+ * `agent.steer(...)`，见 resume.ts 的说明。
+ */
+import type { GuardState } from './types.js';
+/** `agent/turn-stopping` 的监听器签名。 */
+export type TurnStoppingListener = (payload: unknown) => void;
+/**
+ * 造一个 `agent/turn-stopping` 监听器。
+ * @param state - 跨监听保留的拦截状态。
+ * @returns 监听器；只在有待续跑标记时推一条输入。
+ */
+export declare function createTurnStoppingGuard(state: GuardState): TurnStoppingListener;

package/lib/turn-stopping-guard.js

@@ -0,0 +1,18 @@
+/**
+ * `agent/turn-stopping` 监听器：把上一步掐断欠下的续跑补上。
+ *
+ * 监听器的返回值不被使用（该事件是 serial 的副作用钩子），实现方式是调
+ * `agent.steer(...)`，见 resume.ts 的说明。
+ */
+import { reviveTurn } from './resume.js';
+/**
+ * 造一个 `agent/turn-stopping` 监听器。
+ * @param state - 跨监听保留的拦截状态。
+ * @returns 监听器；只在有待续跑标记时推一条输入。
+ */
+export function createTurnStoppingGuard(state) {
+    return (rawPayload) => {
+        const payload = rawPayload;
+        reviveTurn(state, payload?.agent);
+    };
+}

package/lib/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 与本插件交互的 dsh 接口声明。
+ *
+ * 这些类型一律在本插件内声明，不 import dsh 的类型：那样还要为 tsc 配 paths 指向
+ * dsh 安装目录，路径里带 node 版本号，dsh 一升级就失效。
+ */
+/** 一个流式 chunk。本插件只读 reasoning-delta 的 index/text，其余字段原样透传。 */
+export interface StreamChunk {
+    readonly type: string;
+    readonly index?: number;
+    readonly text?: string;
+    readonly [key: string]: unknown;
+}
+/** 一次模型调用的参数；只声明本插件读到的两个字段。 */
+export interface GenerateOptions {
+    readonly purpose?: string;
+    readonly sessionId?: string;
+}
+/**
+ * `agent/turn-stopping` 的载荷。
+ *
+ * dsh 的注释写明：本轮即将关闭（模型不再欠响应）时、在边界提交之前 await 这个事件；
+ * 监听器若不同意关闭，就调 `agent.steer(...)` 推入新的输入，机器会重读收件箱——
+ * 有新的 steering 就再跑一步，没有才真正关闭本轮。
+ */
+export interface TurnStoppingPayload {
+    readonly agent?: SteerableAgent;
+}
+/** 能往本轮收件箱推输入、从而让本轮继续的 agent 句柄。 */
+export interface SteerableAgent {
+    readonly session?: {
+        readonly id?: string;
+    };
+    /** 推入 `next-step` 并唤醒驱动器：本轮再跑一步。 */
+    steer(input: unknown): void;
+}
+/** 注入给 dsh 的 cordis 上下文；只声明本插件用到的能力。 */
+export interface PluginContext {
+    /**
+     * 监听器的形参随所监听的事件而异，只能声明成 any[]：换成 unknown[] 会因函数
+     * 参数逆变，导致各监听器的具体签名无法赋值。
+     */
+    on(name: string, listener: (...args: any[]) => unknown, options?: {
+        global?: boolean;
+    }): void;
+}
+/** 跨两次监听保留的拦截状态。 */
+export interface GuardState {
+    /** 发生过截断、等待下一步续跑的会话 id。 */
+    readonly pending: Set<string>;
+}

package/lib/types.js

@@ -0,0 +1,7 @@
+/**
+ * 与本插件交互的 dsh 接口声明。
+ *
+ * 这些类型一律在本插件内声明，不 import dsh 的类型：那样还要为 tsc 配 paths 指向
+ * dsh 安装目录，路径里带 node 版本号，dsh 一升级就失效。
+ */
+export {};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "dsh-repeat-guard",
+  "version": "0.1.0",
+  "description": "流式输出退化拦截：检测碎片复读，掐断本次生成并提醒模型直接执行工具调用",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepack": "npm run build"
+  },
+  "license": "MIT",
+  "author": "yuqing",
+  "devDependencies": {
+    "typescript": "^7.0.2"
+  }
+}

package/src/detect.ts

@@ -0,0 +1,68 @@
+/**
+ * 复读退化判定：查表。
+ *
+ * 表里是已知会被模型复读的空话短句，**连标点一起写**。判定就是"思考里有没有
+ * 独占一行的表项"，整行与表项全等，不拆解行的内部。
+ *
+ * 增删条目直接改下面的 FRAGMENTS 即可，改完重新构建。
+ */
+
+/**
+ * 会被复读的空话短句表，标点照原样写。
+ *
+ * 英文条目一律写小写，判定时会把整行转成小写再比。
+ */
+const FRAGMENTS: readonly string[] = [
+  // 中文
+  '好。',
+  '好的。',
+  '好嘞。',
+  '对。',
+  '对的。',
+  '是。',
+  '是的。',
+  '行。',
+  '嗯。',
+  '可以。',
+  '明白。',
+  '收到。',
+  '了解。',
+  '执行。',
+  '继续。',
+  '确认。',
+  '完成。',
+  '搞定。',
+  '写。',
+  '查。',
+  '看。',
+  // 英文
+  'ok.',
+  'okay.',
+  'sure.',
+  'alright.',
+  'right.',
+  'yes.',
+  'done.',
+  'got it.',
+  'let me go.',
+  'let me do it.',
+  'check it.',
+];
+
+/** 查表用的集合。 */
+const FRAGMENT_SET = new Set(FRAGMENTS);
+
+/**
+ * 找出退化的碎片行。
+ * @param text - 已生成的思考文本。
+ * @returns 命中返回该行的原文，未命中返回 null。
+ */
+export function findDegenerateLine(text: string): string | null {
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    if (line !== '' && FRAGMENT_SET.has(line.toLowerCase())) {
+      return line;
+    }
+  }
+  return null;
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+// dsh-repeat-guard — host 侧插件入口：拦截"复读"型退化输出。
+//
+// 做法：包一层 `llm/stream`（模型调用的流式 waterfall），逐 chunk 观察思考段
+// （reasoning-delta）。命中退化时，把触发退化的那个 delta 照常放行，补一个 block-end
+// 闭合思考块，再补一个 finish(stop)，然后直接结束流。agent-loop 的 BlockAssembler 会把
+// 这种"没有 finish 就结束"的流当作正常 stop（assembler.js: `this._finish ?? {kind:'stop'}`），
+// 于是本次调用被当成正常完成：已生成的思考照常落盘，本轮该走什么流程就走什么流程。
+//
+// 只检测思考段：正文 text-delta 不参与判定。复读退化先出现在思考段，那时正文往往还没
+// 开始产出；等正文也碎掉再掐，思考段已经白烧了一遍。
+//
+// 判定做什么：思考段里出现单独成行的一句空话（中文一到两个汉字，如"好。""执行。"；
+// 英文不超过三个单词，如"OK." "Let me go."）就掐断。判据的取舍见 detect.ts 的注释——
+// 关键是不能把"同样的碎片出现了几次"当作复读信号，那样会误伤正常的短句。
+//
+// 掐断之后要让本轮继续，而不是停下来等用户输入：挂在 `agent/turn-stopping` 上，在本轮
+// 边界提交之前调 `agent.steer(...)` 推一条输入，机器就会再跑一步。详见 resume.ts。
+//
+// 依赖约束（重要）：不得 import 任何外部包，包括 @deepseek-ai/cordis。
+// cordis-plugin-loader 解析裸 specifier 时直接 `import(name)`，锚点是 loader 自身的
+// 文件位置（dsh 安装目录内部），从 profile 或全局顶层加载时都可能解析不到插件的依赖。
+// **相对路径 import 不受此限**：它由 Node 原生 ESM 按当前文件位置解析，所以本插件内部
+// 按职责拆出的这些模块可以正常互相导入。新增模块时照此办理：只连相对路径。
+//
+// 本文件只做装配，具体逻辑在各自的模块里。
+
+import { createStreamGuard } from './stream-guard.js';
+import { createTurnStoppingGuard } from './turn-stopping-guard.js';
+import type { GuardState, PluginContext } from './types.js';
+
+/** dsh 跑在 Node 上；只声明本插件用到的全局，避免为此引入 @types/node。 */
+declare const console: { log(...args: unknown[]): void };
+
+/**
+ * 函数式插件入口。ctx 为 cordis 上下文，注册的监听随插件卸载自动释放。
+ * @param ctx - 宿主 cordis 上下文。
+ */
+export default function repeatGuard(ctx: PluginContext): void {
+  // 直接写 stdout：dsh 把插件的 stdout 收进 journal，便于确认插件确实被加载。
+  console.log('[repeat-guard] 已加载，复读拦截生效');
+  const state: GuardState = { pending: new Set() };
+  ctx.on('llm/stream', createStreamGuard(state), { global: true });
+  ctx.on('agent/turn-stopping', createTurnStoppingGuard(state));
+}

package/src/resume.ts

@@ -0,0 +1,76 @@
+/**
+ * 续跑：截断之后让本轮不要就此关闭，而是再跑一步。
+ *
+ * 机制在 dsh 侧：`agent/turn-stopping` 是 serial 事件，在本轮边界提交之前被 await，
+ * 之后收件箱会被重新读一次（dsh-agent-loop/lib/index.js:967-973）：
+ *
+ *     if (turnEnds && this.inbox.nextStep.length === 0) {
+ *       await this.dispatch.serial("agent/turn-stopping", { turn, signal });
+ *     }
+ *     if (turnEnds && this.inbox.nextStep.length === 0) break;   // 重读，读到东西就不 break
+ *
+ * 所以在监听器里调 `agent.steer(...)` 推入一条输入，本轮就会再跑一步，而不是停下来等
+ * 用户输入。dsh 自己在 dsh-hooks-claude-code/lib/index.js:292 有同样的用法。
+ */
+
+import type { GuardState, SteerableAgent } from './types.js';
+
+/** dsh 跑在 Node 上；只声明本插件用到的全局，避免为此引入 @types/node。 */
+declare const crypto: { randomUUID(): string };
+declare const console: { log(...args: unknown[]): void };
+
+/** 续跑时推给模型的指令正文。 */
+const RESUME_TEXT = [
+  '[复读拦截]',
+  '你上一段思考退化成了碎片复读（反复输出"好。"一类的空话），已被系统截断。',
+  '请直接继续执行下一步，不要再输出任何确认语、寒暄或空话。',
+].join('\n');
+
+/** 折叠行显示的一行摘要；空字符串会让客户端回退成 opaque 渲染，故不可为空。 */
+const RESUME_SUMMARY = '复读已截断：请继续执行';
+
+/**
+ * 构造推给模型的一条输入，结构与 dsh 的 createUserMessage 对齐。
+ * @returns 一条插件来源的 user 消息，客户端会渲染成折叠的 context 行。
+ */
+function resumeMessage(): Record<string, unknown> {
+  return {
+    id: crypto.randomUUID(),
+    role: 'user',
+    content: [{ type: 'text', text: RESUME_TEXT }],
+    source: {
+      kind: 'plugin',
+      plugin: 'repeat-guard',
+      form: 'notice',
+      summary: RESUME_SUMMARY,
+    },
+  };
+}
+
+/**
+ * 本轮即将关闭时，若上一步刚被掐断过，就推一条输入让本轮继续。
+ * @param state - 跨监听保留的拦截状态。
+ * @param agent - 本轮所属的 agent 句柄。
+ */
+export function reviveTurn(state: GuardState, agent: SteerableAgent | undefined): void {
+  // 三个提前返回都要留痕：不打印就无法区分"没触发""id 对不上""没有标记"。
+  if (agent === undefined || typeof agent.steer !== 'function') {
+    console.log('[repeat-guard] turn-stopping：载荷里没有 agent 句柄，不续跑');
+    return;
+  }
+  const sessionId = agent.session?.id;
+  if (sessionId === undefined) {
+    console.log('[repeat-guard] turn-stopping：agent 上没有会话 id，不续跑');
+    return;
+  }
+  if (!state.pending.has(sessionId)) {
+    console.log(
+      `[repeat-guard] turn-stopping：会话 ${sessionId} 没有待续跑标记，不续跑` +
+        `（当前有标记的会话：${[...state.pending].join(',') || '无'}）`,
+    );
+    return;
+  }
+  state.pending.delete(sessionId);
+  console.log(`[repeat-guard] turn-stopping：会话 ${sessionId} 续跑一步`);
+  agent.steer(resumeMessage());
+}

package/src/stream-guard.ts

@@ -0,0 +1,88 @@
+/**
+ * `llm/stream` 监听器：包一层上游流，思考段命中复读退化就补完流并提前结束。
+ *
+ * 只检测 reasoning-delta（思考段）。正文 text-delta 不参与判定，原样透传。
+ */
+
+import { findDegenerateLine } from './detect.js';
+import type { GenerateOptions, GuardState, StreamChunk } from './types.js';
+
+/** dsh 跑在 Node 上；只声明本插件用到的全局，避免为此引入 @types/node。 */
+declare const console: { log(...args: unknown[]): void };
+
+/** `llm/stream` 的监听器签名。 */
+export type StreamListener = (
+  options: GenerateOptions,
+  next: () => AsyncIterable<StreamChunk>,
+) => AsyncIterable<StreamChunk>;
+
+/**
+ * 逐 chunk 检查上游流的思考段，命中复读退化时补完这段流。
+ *
+ * 适配器只开一个 reasoning 块（dsh-llm-deepseek: `reasoningBlock` 是单个变量），
+ * 所以累积文本用一个字符串即可，不需要按 index 分开存。
+ *
+ * @param downstream - 上游模型的流。
+ * @param sessionId - 当前会话 id；有值才登记待续跑标记。
+ * @param state - 跨监听保留的拦截状态。
+ * @returns 包好的流。
+ */
+async function* guardStream(
+  downstream: AsyncIterable<StreamChunk>,
+  sessionId: string | undefined,
+  state: GuardState,
+): AsyncGenerator<StreamChunk> {
+  const iterator = downstream[Symbol.asyncIterator]();
+  let accumulated = '';
+  try {
+    for (;;) {
+      const step = await iterator.next();
+      if (step.done) {
+        return;
+      }
+      const chunk = step.value;
+      if (chunk?.type === 'reasoning-delta' && typeof chunk.text === 'string') {
+        accumulated += chunk.text;
+        const hit = findDegenerateLine(accumulated);
+        if (hit !== null) {
+          if (sessionId !== undefined) {
+            state.pending.add(sessionId);
+          }
+          console.log(
+            `[repeat-guard] 检出思考段复读，已掐断本次生成 | 会话=${sessionId ?? '无'} | 命中行=${JSON.stringify(hit)}`,
+          );
+          // 触发点本身已经产生了，照常放行；要掐掉的是它之后的思考。
+          const index = chunk.index ?? 0;
+          yield chunk;
+          yield { type: 'block-end', index, block: { type: 'reasoning', text: accumulated } };
+          yield { type: 'finish', reason: { kind: 'stop' } };
+          return;
+        }
+      }
+      yield chunk;
+    }
+  } finally {
+    // 提前 return 时必须显式向下游传播：不补这一步上游 HTTP 流会继续跑到结束，
+    // 供应商照常计满 token，且连接悬挂。上游可能已经结束/关闭，其异常忽略。
+    try {
+      await iterator.return?.();
+    } catch {
+      /* 上游已经结束或关闭，无需处理 */
+    }
+  }
+}
+
+/**
+ * 造一个 `llm/stream` 监听器。
+ * @param state - 跨监听保留的拦截状态。
+ * @returns 监听器；辅助调用直接透传，其余包一层复读检测。
+ */
+export function createStreamGuard(state: GuardState): StreamListener {
+  return (options, next) => {
+    // 辅助调用（上下文压缩、会话标题）不参与检测。
+    if (options.purpose !== undefined) {
+      return next();
+    }
+    return guardStream(next(), options.sessionId, state);
+  };
+}

package/src/turn-stopping-guard.ts

@@ -0,0 +1,24 @@
+/**
+ * `agent/turn-stopping` 监听器：把上一步掐断欠下的续跑补上。
+ *
+ * 监听器的返回值不被使用（该事件是 serial 的副作用钩子），实现方式是调
+ * `agent.steer(...)`，见 resume.ts 的说明。
+ */
+
+import { reviveTurn } from './resume.js';
+import type { GuardState, TurnStoppingPayload } from './types.js';
+
+/** `agent/turn-stopping` 的监听器签名。 */
+export type TurnStoppingListener = (payload: unknown) => void;
+
+/**
+ * 造一个 `agent/turn-stopping` 监听器。
+ * @param state - 跨监听保留的拦截状态。
+ * @returns 监听器；只在有待续跑标记时推一条输入。
+ */
+export function createTurnStoppingGuard(state: GuardState): TurnStoppingListener {
+  return (rawPayload) => {
+    const payload = rawPayload as TurnStoppingPayload;
+    reviveTurn(state, payload?.agent);
+  };
+}

package/src/types.ts

@@ -0,0 +1,57 @@
+/**
+ * 与本插件交互的 dsh 接口声明。
+ *
+ * 这些类型一律在本插件内声明，不 import dsh 的类型：那样还要为 tsc 配 paths 指向
+ * dsh 安装目录，路径里带 node 版本号，dsh 一升级就失效。
+ */
+
+/** 一个流式 chunk。本插件只读 reasoning-delta 的 index/text，其余字段原样透传。 */
+export interface StreamChunk {
+  readonly type: string;
+  readonly index?: number;
+  readonly text?: string;
+  readonly [key: string]: unknown;
+}
+
+/** 一次模型调用的参数；只声明本插件读到的两个字段。 */
+export interface GenerateOptions {
+  readonly purpose?: string;
+  readonly sessionId?: string;
+}
+
+/**
+ * `agent/turn-stopping` 的载荷。
+ *
+ * dsh 的注释写明：本轮即将关闭（模型不再欠响应）时、在边界提交之前 await 这个事件；
+ * 监听器若不同意关闭，就调 `agent.steer(...)` 推入新的输入，机器会重读收件箱——
+ * 有新的 steering 就再跑一步，没有才真正关闭本轮。
+ */
+export interface TurnStoppingPayload {
+  readonly agent?: SteerableAgent;
+}
+
+/** 能往本轮收件箱推输入、从而让本轮继续的 agent 句柄。 */
+export interface SteerableAgent {
+  readonly session?: { readonly id?: string };
+  /** 推入 `next-step` 并唤醒驱动器：本轮再跑一步。 */
+  steer(input: unknown): void;
+}
+
+/** 注入给 dsh 的 cordis 上下文；只声明本插件用到的能力。 */
+export interface PluginContext {
+  /**
+   * 监听器的形参随所监听的事件而异，只能声明成 any[]：换成 unknown[] 会因函数
+   * 参数逆变，导致各监听器的具体签名无法赋值。
+   */
+  on(
+    name: string,
+    listener: (...args: any[]) => unknown,
+    options?: { global?: boolean },
+  ): void;
+}
+
+/** 跨两次监听保留的拦截状态。 */
+export interface GuardState {
+  /** 发生过截断、等待下一步续跑的会话 id。 */
+  readonly pending: Set<string>;
+}