@ethanwong-hk/dsh-thinking-guard 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ethan Wong
+
+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,130 @@
+# dsh-thinking-guard
+
+纯思考空转熔断器。挂在 `agent/assistant-stream` 事件上，对「只思考、零产出」的退化回合实施三重熔断。
+
+## 安装
+
+**方式一：从 npm 安装（推荐）**
+
+```sh
+dsh plugin add @ethanwong-hk/dsh-thinking-guard
+```
+
+**方式二：从 GitHub 安装**
+
+```sh
+dsh plugin add github:ethanwong-hk/dsh-thinking-guard
+```
+
+**方式三：手工挂载**
+
+把本仓库放到 `~/.dsh/plugins/dsh-thinking-guard/`，然后在 `~/.dsh/cordis.patch.yml` 中加入 `cordis.patch.yml` 里的 `insert` 片段（见下方「配置」）。
+
+安装后**重启 DSH** 生效。验证是否加载：
+
+```sh
+grep -n "thinking-guard" ~/.dsh/cordis.patch.yml
+```
+
+## 为什么需要它
+
+`dsh-agent-loop` 的 `step()` 只在**流结束后**才做终止判定（`lib/index.js:1115-1119`）。流不结束，`turn/end` 就永不写入。
+
+`dsh-llm-deepseek` 的 `idleWatchdog`（`lib/index.js:1627`）测的是**连接活性**而非任务进展 —— 它在每个 SSE 事件上 `pulse()` 重置 5 分钟计时器（`:1816` 经 `parseSse` 喂食）。模型持续吐 `reasoning-delta` 时，看门狗每 chunk 重置，**永不触发**。
+
+结果是：模型以比 5 分钟更密的节奏输出 thinking token 时，回合可以无限持续，只能由用户手动中止。默认 `max_tokens = 256000`（`DEFAULT_MAX_TOKENS`）量级过大，不构成实际兜底。
+
+## 三重熔断
+
+| 熔断 | 默认值 | 触发条件 |
+|---|---|---|
+| `thinking-only-timeout` | 45000 ms | 零 text、零 tool-call，且距**最后一次进展**已超时 |
+| `thinking-volume` | 80000 字符 | 单次尝试 reasoning 总量超限，**不依赖**是否有 text 产出 |
+| `degenerate-loop` | 3 次重复 | 尾部窗口命中：精确重复单元 / 句子级模板重复 / 稀疏复读 / N-gram 高密度 |
+
+命中即 `agent.cancel({ kind:'thinking-guard', reason, detail })`，并尽力用 `agent.followup()` 注入一条可见说明。
+
+「停滞时长」锚定**最后一次进展**（text 或 tool-call 到达的时刻），而非 attempt 起点 —— 避免慢启动的正常回合被误判。
+
+## 配置
+
+在 `~/.dsh/cordis.patch.yml` 的 `thinking-guard` 条目 `config` 下调整，重启 DSH 生效：
+
+```yaml
+- insert:
+    - id: thinking-guard
+      name: "dsh-thinking-guard"
+      config:
+        enabled: true
+        # 只思考、零 text/tool-call 的持续时长上限（毫秒）
+        thinkingOnlyMs: 45000
+        # 单次尝试 reasoning 字符总量上限
+        maxThinkingChars: 80000
+        # 退化循环：重复次数阈值
+        repeatThreshold: 3
+        # 熔断后自动注入「继续当前任务」指令
+        autoContinue: true
+        notify: true
+        verbose: false
+```
+
+环境变量可临时覆盖（无需改配置）：
+
+| 变量 | 作用 |
+|---|---|
+| `DSH_THINKING_GUARD_DISABLED=1` | 停用 |
+| `DSH_THINKING_ONLY_MS` | 纯思考停滞阈值 |
+| `DSH_MAX_THINKING_CHARS` | 思考容量阈值 |
+| `DSH_THINKING_REPEAT_THRESHOLD` | 重复次数阈值 |
+| `DSH_THINKING_GUARD_VERBOSE=1` | 打日志 |
+
+## 误报调优
+
+| 现象 | 调整 |
+|---|---|
+| 正常长文本被误熔断 | 调高 `sentenceRepeatRatio`（默认 0.6）、`gramDensity`（默认 0.22） |
+| 退化循环漏检 | 调低 `repeatThreshold`（默认 8） |
+| 慢模型被误判停滞 | 调高 `thinkingOnlyMs` |
+
+## 验证
+
+```bash
+node ~/.dsh/plugins/dsh-thinking-guard/test/guard.test.mjs
+```
+
+11 个场景覆盖：纯思考超时、退化复读、容量上限、有产出仍限容量、文本复读、稀疏复读（回归用例）、正常回合放行、工具调用放行、正常结束放行、长正常文本放行。
+
+## 已修缺陷：熔断器自身的静默失效
+
+`formatNotice` 是**模块级函数**，却在 `sparse-repeat` 分支引用了 `apply()` 内的局部 `cfg`（`cfg.sparseWindow`）。该分支一旦命中即抛 `ReferenceError: cfg is not defined`。
+
+危害不是「少一条提示」，而是**熔断完全失效**：
+
+1. `trip()` 中 `formatNotice(...)` 位于 `agent.cancel(...)` **之前**，异常直接中断 `trip()`，`cancel` 永不执行；
+2. `st.fired = true` 已在异常前置位，本 attempt 的后续检测被 `if (st.fired) return` 全部跳过。
+
+线上日志实证：`dsh-2026-09-26.log` 记录 472 次、`dsh-2026-09-27.log` 记录 39 次 `agent/assistant-stream listener threw: ReferenceError: cfg is not defined` —— 全部来自本插件唯一的事件监听器。修复前，该档熔断在所有命中回合上都是空转的。
+
+修复两处：
+
+```js
+// 1) 根因：显式传参，消除模块级作用域泄漏
+function formatNotice(reason, detail, st, cfg) { ... }
+
+// 2) 防御：cancel 前置，且通知文本生成失败时降级而非中断
+console.warn(...);
+try { agent.cancel({ ... }); } catch (error) { ... }
+let text;
+try { text = formatNotice(reason, detail, st, cfg); }
+catch (error) { text = `...（说明文本生成失败：${error?.message}）`; }
+```
+
+原则：**熔断这一关键动作不得依赖通知环节的成功**。回归用例见 `test/guard.test.mjs` 场景 11。
+
+## 语义边界
+
+`thinkingOnlyMs` **只在零 text、零 tool-call 时生效**。已产出文本的回合不会被它熔断 —— 那类回合至少有可见产出，不属于「纯思考空转」。`maxThinkingChars` 与退化检测对已产出文本的回合同样生效，用以兜住「先吐一小段文本再无限思考」。
+
+## 依赖
+
+无。仅用 harness 的 `agent/assistant-stream` / `agent/disposed` 事件与 `agent.cancel` / `agent.followup` 接口。消息工厂按候选路径显式解析 `@deepseek-ai/dsh-llm`，解析失败时降级为仅日志，不影响熔断本身。

package/cordis.patch.yml

@@ -0,0 +1,23 @@
+# dsh-thinking-guard bundle patch
+#
+# 以本插件包为单位挂载时使用（插入 profile 的 layer stack）。
+# 若你已手工在 ~/.dsh/cordis.patch.yml 的 DSH_THINKING_GUARD 段里配置过，
+# 二者等价，保留其一即可。
+#
+# 注意：这里的 config 会覆盖插件内 DEFAULTS，请与 lib/index.js 的
+# DEFAULTS 保持同步，否则会出现「配置文件写的值 ≠ 实际生效值」。
+- insert:
+    - id: thinking-guard
+      name: 'dsh-thinking-guard'
+      config:
+        enabled: true
+        # 只思考、零 text/tool-call 的持续时长上限（毫秒）
+        thinkingOnlyMs: 45000
+        # 单次尝试 reasoning 字符总量上限
+        maxThinkingChars: 80000
+        # 退化循环：短语连续重复次数阈值
+        repeatThreshold: 3
+        # 熔断后自动注入「继续当前任务」指令
+        autoContinue: true
+        notify: true
+        verbose: false

package/lib/index.js

@@ -0,0 +1,435 @@
+// dsh-thinking-guard —— 纯思考空转熔断器
+//
+// 机理（已实证）：
+//   dsh-agent-loop/lib/index.js 的 step() 只在流结束后才做终止判定
+//   （1115-1119 行：max-tokens / 零工具调用 / concludesTurn）。
+//   dsh-llm-deepseek 的 idleWatchdog 只测「连接是否还有数据到达」
+//   （1627 行 idleWatchdog + 1659 行 onActivity 经 parseSse 喂食），
+//   模型持续吐 reasoning-delta 时它每 chunk 重置，5 分钟阈值永不触发。
+//   结果是「只思考、零 text、零 tool-call」的退化回合没有任何熔断点，
+//   只能由用户手动中止。
+//
+// 本插件挂 agent/assistant-stream 事件，做的是进展型检测（而非活性检测），
+// 三重熔断：
+//   1. 纯思考时长  thinkingOnlyMs  — 持续仅 reasoning 且零 text/tool-call
+//   2. 思考容量    maxThinkingChars — 单次尝试 reasoning 字符总量
+//   3. 退化循环    detectDegenerate — 尾部文本出现高密度重复短语
+// 命中即调用 agent.cancel({ kind:'thinking-guard', ... }) 中止当前活动，
+// 并尽力向会话注入一条可见说明。
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const name = 'dsh-thinking-guard';
+
+// 只需事件总线，不注入其它服务。
+export const inject = [];
+
+const DEFAULTS = {
+    enabled: true,
+    // 只思考、无任何 text/tool-call 产出的持续时长上限（毫秒）
+    thinkingOnlyMs: 45000,
+    // 单次尝试 reasoning 字符总量上限
+    maxThinkingChars: 80000,
+    // 熔断后是否自动注入「继续当前任务」指令
+    autoContinue: true,
+    // 退化循环：尾部窗口内同一短语连续重复次数阈值
+    repeatThreshold: 3,
+    // 退化循环：重复单元最大长度
+    repeatUnitMax: 40,
+    // 退化循环：N-gram 密度检测
+    gramWindow: 600,
+    gramSize: 6,
+    gramDensity: 0.16,
+    gramMinDistinct: 40,
+    // 退化循环：句子级模板重复（对「固定模板 + 小变化」的自我催促有效）
+    sentenceRepeatRatio: 0.6,
+    sentenceMinPeak: 8,
+    sentenceMinParts: 10,
+    // 退化循环：稀疏复读（跨大窗口的短句高次重复，不要求连续）
+    // 命中场景：thinking 里每隔几百字插一句「好。执行。」这类自我催促
+    sparseWindow: 4000,
+    sparseMaxUnit: 12,
+    sparseMinCount: 5,
+    sparseMinRatio: 0.15,
+    sparseMinTotal: 6,
+    // 每累积多少字符做一次退化检查
+    checkEveryChars: 1024,
+    // 是否向会话注入说明
+    notify: true,
+    verbose: false,
+};
+
+let createUserMessage = null;
+
+// harness 包不在用户插件的解析路径上，按候选顺序显式解析。
+// 路径由 homedir() / DSH_HOME 推导，不硬编码具体用户名——
+// 否则安装路径会随包分发，泄露维护者的本机目录结构。
+const LLM_CANDIDATES = [
+    process.env.DSH_HOME
+        ? join(process.env.DSH_HOME, 'profiles/node_modules/@deepseek-ai/dsh-llm/lib/index.js')
+        : null,
+    join(homedir(), '.dsh/profiles/node_modules/@deepseek-ai/dsh-llm/lib/index.js'),
+    '/Applications/DSH Desktop.app/Contents/Resources/app/node_modules/@deepseek-ai/dsh-llm/lib/index.js',
+].filter(Boolean);
+
+async function resolveMessageFactory() {
+    for (const candidate of LLM_CANDIDATES) {
+        try {
+            const mod = await import(candidate);
+            if (typeof mod.createUserMessage === 'function') return mod.createUserMessage;
+        } catch {
+            // 试下一个候选
+        }
+    }
+    return null;
+}
+
+function mergeConfig(raw) {
+    const cfg = { ...DEFAULTS, ...(raw ?? {}) };
+    // 环境变量可覆盖，便于不改配置文件调参
+    const env = (k) => process.env[k];
+    if (env('DSH_THINKING_GUARD_DISABLED') === '1') cfg.enabled = false;
+    const numeric = [
+        ['DSH_THINKING_ONLY_MS', 'thinkingOnlyMs'],
+        ['DSH_MAX_THINKING_CHARS', 'maxThinkingChars'],
+        ['DSH_THINKING_REPEAT_THRESHOLD', 'repeatThreshold'],
+    ];
+    for (const [envKey, cfgKey] of numeric) {
+        const value = Number(env(envKey));
+        if (Number.isFinite(value) && value > 0) cfg[cfgKey] = value;
+    }
+    if (env('DSH_THINKING_GUARD_VERBOSE') === '1') cfg.verbose = true;
+    return cfg;
+}
+
+/**
+ * 退化循环检测：三档互补指标，任一命中即判定退化。
+ *   1) 尾部精确重复单元 —— 抓严格复读
+ *   2) 句子级模板重复   —— 抓「固定模板 + 小变化」的自我催促
+ *   3) N-gram 密度       —— 抓低信息密度的原地打转
+ */
+export function detectDegenerate(text, cfg) {
+    const window = (text ?? '').slice(-cfg.gramWindow);
+    if (window.trim().length < 120) return null;
+
+    // 1) 尾部精确重复单元：从短到长找第一个满足阈值的最小单元
+    for (let unit = 4; unit <= cfg.repeatUnitMax; unit += 1) {
+        let count = 1;
+        let cursor = window.length - unit;
+        while (cursor - unit >= 0 && window.slice(cursor - unit, cursor) === window.slice(cursor, cursor + unit)) {
+            count += 1;
+            cursor -= unit;
+        }
+        if (count >= cfg.repeatThreshold) {
+            return { kind: 'repeat-unit', unit: window.slice(window.length - unit), count };
+        }
+    }
+
+    // 2) 句子级模板重复：数字归一化后统计句模占比
+    const normalized = window.replace(/\d+/g, '#').replace(/[ \t]+/g, '');
+    const parts = normalized
+        .split(/(?<=[。！？!?.\n])/)
+        .map((part) => part.trim())
+        .filter((part) => part.length >= 4);
+    if (parts.length >= cfg.sentenceMinParts) {
+        const freq = new Map();
+        for (const part of parts) freq.set(part, (freq.get(part) ?? 0) + 1);
+        let peak = 0;
+        let peakPart = '';
+        for (const [part, count] of freq) {
+            if (count > peak) {
+                peak = count;
+                peakPart = part;
+            }
+        }
+        const ratio = peak / parts.length;
+        if (peak >= cfg.sentenceMinPeak && ratio >= cfg.sentenceRepeatRatio) {
+            return {
+                kind: 'sentence-repeat',
+                sample: peakPart.slice(0, 40),
+                count: peak,
+                ratio: Number(ratio.toFixed(3)),
+            };
+        }
+    }
+
+    // 3) 稀疏复读：大窗口内短句高次重复（不要求连续）
+    //    覆盖「实质分析与自我催促交替出现」的形态——这类复读在 600 字窗口里
+    //    密度不够，前三档全部漏检。
+    const bigWindow = (text ?? '').slice(-cfg.sparseWindow);
+    const shortParts = bigWindow
+        .split(/(?<=[。！？!?.\n])/)
+        .map((part) => part.trim())
+        .filter((part) => part.length >= 2 && part.length <= cfg.sparseMaxUnit);
+    if (shortParts.length >= cfg.sparseMinTotal) {
+        const shortFreq = new Map();
+        for (const part of shortParts) shortFreq.set(part, (shortFreq.get(part) ?? 0) + 1);
+        let peak = 0;
+        let peakPart = '';
+        for (const [part, count] of shortFreq) {
+            if (count > peak) {
+                peak = count;
+                peakPart = part;
+            }
+        }
+        const share = peak / shortParts.length;
+        if (peak >= cfg.sparseMinCount && share >= cfg.sparseMinRatio) {
+            return {
+                kind: 'sparse-repeat',
+                sample: peakPart.slice(0, 24),
+                count: peak,
+                share: Number(share.toFixed(4)),
+            };
+        }
+    }
+
+    // 4) N-gram 密度：最高频 gram 占比过高说明文本在原地打转
+    const grams = new Map();
+    for (let i = 0; i + cfg.gramSize <= window.length; i += 1) {
+        const gram = window.slice(i, i + cfg.gramSize);
+        grams.set(gram, (grams.get(gram) ?? 0) + 1);
+    }
+    if (grams.size >= cfg.gramMinDistinct) {
+        let peak = 0;
+        for (const count of grams.values()) if (count > peak) peak = count;
+        const density = peak / grams.size;
+        if (density >= cfg.gramDensity) return { kind: 'gram-density', density: Number(density.toFixed(3)), peak };
+    }
+
+    return null;
+}
+
+function formatNotice(reason, detail, st, cfg) {
+    const head = '[thinking-guard] 已中止当前活动：检测到纯思考空转。';
+    const tail = '请停止自我催促式思考，直接输出结论或调用工具推进任务。';
+    const stats = `（本回合 reasoning ${st.reasoningChars} 字符，text ${st.textChars} 字符，工具调用 ${st.toolCalls} 次）`;
+    switch (reason) {
+        case 'thinking-only-timeout':
+            return `${head}\n原因：连续 ${Math.round(detail.heldMs / 1000)} 秒只产出思考内容，没有任何回复文本或工具调用。${stats}\n${tail}`;
+        case 'thinking-volume':
+            return `${head}\n原因：单次尝试思考内容已达 ${detail.chars} 字符，仍无回复文本或工具调用。${stats}\n${tail}`;
+        case 'degenerate-loop': {
+            let why;
+            if (detail.kind === 'repeat-unit') why = `短语「${detail.unit}」连续重复 ${detail.count} 次`;
+            else if (detail.kind === 'sentence-repeat') why = `句模「${detail.sample}」重复 ${detail.count} 次（占比 ${detail.ratio}）`;
+            else if (detail.kind === 'sparse-repeat') why = `短句「${detail.sample}」在最近 ${cfg.sparseWindow} 字内出现 ${detail.count} 次（稀疏复读）`;
+            else why = `6-gram 密度 ${detail.density}`;
+            return `${head}\n原因：思考内容陷入重复循环（${why}）。${stats}\n${tail}`;
+        }
+        default:
+            return `${head}${stats}\n${tail}`;
+    }
+}
+
+export function apply(ctx, config) {
+    const cfg = mergeConfig(config);
+    const states = new Map();
+
+    // 异步准备消息工厂；失败只是失去可见提示，不影响熔断本身。
+    resolveMessageFactory().then((factory) => {
+        createUserMessage = factory;
+        if (cfg.verbose) {
+            console.log(`[thinking-guard] 消息工厂 ${factory ? '已就绪' : '不可用（降级为仅日志）'}`);
+        }
+    });
+
+    const log = (...args) => {
+        if (cfg.verbose) console.log('[thinking-guard]', ...args);
+    };
+
+    function notify(agent, text) {
+        if (!cfg.notify) return;
+        try {
+            if (createUserMessage === null) return;
+            const message = createUserMessage({
+                content: [{ type: 'text', text }],
+                source: {
+                    kind: 'plugin',
+                    plugin: 'thinking-guard',
+                    form: 'notice',
+                    summary: '纯思考空转熔断',
+                },
+            });
+            agent.followup(message);
+            log('已注入熔断说明');
+        } catch (error) {
+            log('注入说明失败：', error?.message ?? error);
+        }
+    }
+
+    // 熔断后自动继续当前任务：注入一条"继续"指令，要求立即以工具调用恢复。
+    function notifyContinue(agent, reason) {
+        try {
+            if (createUserMessage === null) return;
+            const message = createUserMessage({
+                content: [{
+                    type: 'text',
+                    text: '继续。上一回合因思考空转被熔断中止（' + reason + '）。'
+                        + '现在立即恢复原有任务，不要重述背景、不要写长篇思考：'
+                        + '本回合第一个动作必须是工具调用；先做一件可验证的小事（读文件、跑命令、查状态），再根据结果继续。',
+                }],
+                source: {
+                    kind: 'plugin',
+                    plugin: 'thinking-guard',
+                    form: 'notice',
+                    summary: '自动继续当前任务',
+                },
+            });
+            agent.followup(message);
+            log('已注入自动继续指令');
+        } catch (error) {
+            log('注入自动继续指令失败：', error?.message ?? error);
+        }
+    }
+
+    function trip(agent, st, reason, detail) {
+        if (st.fired) return;
+        st.fired = true;
+        console.warn(`[thinking-guard] 熔断 ${reason} session=${st.sessionId} turn=${st.turn} step=${st.step} detail=${JSON.stringify(detail)}`);
+        // 关键动作优先：cancel 必须先于通知文本生成。
+        // 曾出现过的故障：formatNotice 抛 ReferenceError 后 cancel 永不执行，
+        // 熔断静默失效（且 st.fired 已置位，本 attempt 后续检测全部跳过）。
+        try {
+            // keepInbox 默认 false：清掉待处理输入后中止当前活动，避免残留
+            agent.cancel({ kind: 'thinking-guard', reason, detail, sessionId: st.sessionId });
+        } catch (error) {
+            console.warn('[thinking-guard] cancel 失败：', error?.message ?? error);
+        }
+        // 通知属尽力而为：生成失败也要降级为一条最小说明，不能影响已完成的熔断。
+        let text;
+        try {
+            text = formatNotice(reason, detail, st, cfg);
+        } catch (error) {
+            text = `[thinking-guard] 已中止当前活动：检测到纯思考空转。\n原因：${reason}`
+                + `（说明文本生成失败：${error?.message ?? error}）`;
+            console.warn('[thinking-guard] 通知文本生成失败，已降级：', error?.message ?? error);
+        }
+        notify(agent, text);
+        if (cfg.autoContinue !== false) notifyContinue(agent, reason);
+    }
+
+    function evaluate(agent, st) {
+        if (st.fired) return;
+        const noProgress = st.textChars === 0 && st.toolCalls === 0;
+
+        // 绝对容量上限：不依赖是否已有产出。模型先吐一小段文本再无限思考，
+        // 同样会耗尽资源，因此这条必须独立生效。
+        if (st.reasoningChars >= cfg.maxThinkingChars) {
+            trip(agent, st, 'thinking-volume', { chars: st.reasoningChars });
+            return;
+        }
+
+        if (noProgress && st.reasoningChars > 0) {
+            // 停滞时长锚定「最后一次进展」，而非 attempt 起点：
+            // 已产出 text/tool-call 的回合不会因早期延迟被误判。
+            const heldMs = Date.now() - st.lastProgressAt;
+            if (heldMs >= cfg.thinkingOnlyMs) {
+                trip(agent, st, 'thinking-only-timeout', { heldMs });
+                return;
+            }
+        }
+
+        // 有进展的回合同样要防退化循环：空转既可以是纯思考，也可以是
+        // 反复输出同段落而不推进任务。
+        if (st.sinceCheck >= cfg.checkEveryChars) {
+            st.sinceCheck = 0;
+            const hit = detectDegenerate(st.tail, cfg);
+            if (hit !== null) trip(agent, st, 'degenerate-loop', hit);
+        }
+    }
+
+    function onStream(payload) {
+        if (!cfg.enabled) return;
+        const agent = payload?.agent;
+        const frame = payload?.frame;
+        if (agent === undefined || frame === undefined) return;
+
+        const sessionId = agent.session?.id;
+        if (typeof sessionId !== 'string') return;
+
+        if (frame.type === 'start') {
+            states.set(sessionId, {
+                sessionId,
+                attemptId: frame.attemptId,
+                turn: frame.turn,
+                step: frame.step,
+                startedAt: Date.now(),
+                lastProgressAt: Date.now(),
+                reasoningChars: 0,
+                textChars: 0,
+                toolCalls: 0,
+                tail: '',
+                sinceCheck: 0,
+                fired: false,
+            });
+            return;
+        }
+
+        if (frame.type === 'end') {
+            states.delete(sessionId);
+            return;
+        }
+
+        if (frame.type !== 'chunk') return;
+
+        const st = states.get(sessionId);
+        if (st === undefined || st.fired) return;
+
+        const chunk = frame.chunk;
+        if (chunk === undefined || typeof chunk.type !== 'string') return;
+
+        switch (chunk.type) {
+            case 'reasoning-delta': {
+                const text = typeof chunk.text === 'string' ? chunk.text : '';
+                if (text === '') return;
+                st.reasoningChars += text.length;
+                st.sinceCheck += text.length;
+                // 尾部缓冲按窗口两倍截断，避免无限增长
+                st.tail = (st.tail + text).slice(-cfg.gramWindow * 2);
+                break;
+            }
+            case 'text-delta': {
+                const text = typeof chunk.text === 'string' ? chunk.text : '';
+                if (text.trim() !== '') {
+                    st.textChars += text.length;
+                    st.lastProgressAt = Date.now();
+                    // 文本同样进入退化窗口：反复输出同段文本也是空转
+                    st.sinceCheck += text.length;
+                    st.tail = (st.tail + text).slice(-cfg.gramWindow * 2);
+                    break;   // 落到 evaluate：文本退化同样要检查
+                }
+                return;
+            }
+            case 'tool-call-delta':
+                st.toolCalls += 1;
+                st.lastProgressAt = Date.now();
+                return;
+            case 'block-start':
+                // 出现 text / tool-call 块即视为已产生进展
+                if (chunk.blockType === 'tool-call') {
+                    st.toolCalls += 1;
+                    st.lastProgressAt = Date.now();
+                } else if (chunk.blockType === 'text') {
+                    st.lastProgressAt = Date.now();
+                }
+                return;
+            default:
+                return;
+        }
+
+        evaluate(agent, st);
+    }
+
+    // global：会话以编程方式创建的 agent 同样纳入熔断
+    ctx.on('agent/assistant-stream', onStream, { global: true });
+
+    ctx.on('agent/disposed', ({ agent }) => {
+        const sessionId = agent?.session?.id;
+        if (typeof sessionId === 'string') states.delete(sessionId);
+    }, { global: true });
+
+    ctx.effect(() => () => states.clear(), 'thinking-guard.state');
+
+    log(`已启用：thinkingOnlyMs=${cfg.thinkingOnlyMs} maxThinkingChars=${cfg.maxThinkingChars} repeatThreshold=${cfg.repeatThreshold}`);
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@ethanwong-hk/dsh-thinking-guard",
+  "version": "1.0.2",
+  "description": "Circuit breaker for pure-thinking idle loops in DSH agent turns: triple fusing on timeout, reasoning volume, and degenerate repetition.",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "test",
+    "README.md",
+    "cordis.patch.yml"
+  ],
+  "scripts": {
+    "test": "node test/guard.test.mjs"
+  },
+  "author": "Ethan Wong <202729672+ethanwong-hk@users.noreply.github.com>",
+  "license": "MIT",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "thinking-guard",
+    "circuit-breaker",
+    "idle-loop",
+    "reasoning-stall",
+    "agent-reliability"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ethanwong-hk/dsh-thinking-guard.git"
+  },
+  "homepage": "https://github.com/ethanwong-hk/dsh-thinking-guard#readme",
+  "bugs": {
+    "url": "https://github.com/ethanwong-hk/dsh-thinking-guard/issues"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "engines": {
+    "node": ">=18",
+    "dsh": ">=0.1.0"
+  }
+}

package/test/guard.test.mjs

@@ -0,0 +1,90 @@
+// 相对本文件解析，避免写死安装位置（否则随包分发会泄露维护者的本机目录）
+const mod = await import(new URL('../lib/index.js', import.meta.url).href);
+function h(config) {
+  const handlers = new Map();
+  mod.apply({ on: (e, f) => handlers.set(e, f), effect: (f) => f() }, config);
+  const events = []; let rev = 0, idx = 0;
+  const agent = { session: { id: 's' }, cancel: (c) => events.push({ type: 'cancel', cause: c }), followup: () => {} };
+  return {
+    start: () => handlers.get('agent/assistant-stream')({ agent, frame: { type:'start', attemptId:'a', revision:++rev, turn:1, step:1 } }),
+    chunk: (c) => handlers.get('agent/assistant-stream')({ agent, frame: { type:'chunk', attemptId:'a', revision:++rev, index:idx++, time:Date.now(), chunk:c } }),
+    tripped: () => events.find((e) => e.type === 'cancel'),
+  };
+}
+let pass=0, fail=0;
+const check=(l,g,w)=>{const ok=g===w; ok?pass++:fail++; console.log(`[${ok?'PASS':'FAIL'}] ${l}  熔断=${g} 期望=${w}`);};
+
+// 1 纯思考超时
+{ const t=h({thinkingOnlyMs:60,checkEveryChars:1e9,notify:false}); t.start();
+  await new Promise(r=>setTimeout(r,80));
+  for(let i=0;i<5;i++) t.chunk({type:'reasoning-delta',index:0,text:`思考片段 ${i}，仍未形成结论。`});
+  check('场景1 纯思考超时',!!t.tripped(),true); }
+
+// 2 YG 样本复读
+{ const t=h({thinkingOnlyMs:1e9,checkEveryChars:1,notify:false}); t.start();
+  const s='好。执行。好。（输出工具调用）'.repeat(12);
+  for(let i=0;i<s.length;i+=20) t.chunk({type:'reasoning-delta',index:0,text:s.slice(i,i+20)});
+  check('场景2 退化循环复读',!!t.tripped(),true); }
+
+// 3 容量上限
+{ const t=h({thinkingOnlyMs:1e9,maxThinkingChars:300,checkEveryChars:1e9,notify:false}); t.start();
+  for(let i=0;i<20;i++) t.chunk({type:'reasoning-delta',index:0,text:'一段没有结论的思考内容，持续消耗资源而无任何产出。'});
+  check('场景3 思考容量上限',!!t.tripped(),true); }
+
+// 4 正常回合（每轮内容不同，逼近真实）
+{ const t=h({thinkingOnlyMs:60,maxThinkingChars:300,checkEveryChars:1,notify:false}); t.start();
+  for(let i=0;i<12;i++){
+    t.chunk({type:'reasoning-delta',index:0,text:`第 ${i} 步需要先确认目标服务的版本信息。`});
+    t.chunk({type:'text-delta',index:1,text:`正在处理第 ${i} 项检查，结果已记录到证据文件。`});
+  }
+  check('场景4 正常回合放行',!!t.tripped(),false); }
+
+// 5 工具调用
+{ const t=h({thinkingOnlyMs:60,maxThinkingChars:300,checkEveryChars:1,notify:false}); t.start();
+  for(let i=0;i<12;i++){ t.chunk({type:'reasoning-delta',index:0,text:'准备调用工具。'}); t.chunk({type:'tool-call-delta',index:1,id:'c',name:'bash',argumentsDelta:'{"command":' }); }
+  check('场景5 工具调用放行',!!t.tripped(),false); }
+
+// 6 有产出后短思考
+{ const t=h({thinkingOnlyMs:1e9,maxThinkingChars:1e9,checkEveryChars:1,notify:false}); t.start();
+  t.chunk({type:'text-delta',index:1,text:'已输出一段正式回复。'});
+  await new Promise(r=>setTimeout(r,80));
+  for(let i=0;i<5;i++) t.chunk({type:'reasoning-delta',index:0,text:'继续思考但没有新产出。'});
+  check('场景6 有产出后短思考放行',!!t.tripped(),false); }
+
+// 7 正常结束（各句实质不同）
+{ const t=h({thinkingOnlyMs:1e9,maxThinkingChars:1e9,checkEveryChars:1,notify:false}); t.start();
+  const lines=['先确认服务端口与协议。','检查证书链的颁发者字段。','比对中国件响应头顺序。','核对错误页模板哈希。','记录归属判定依据。','标注仍需复核的条目。','换一条路径扩展侦察。','汇总证据链后收束。','整理未完成事项清单。','输出最终结论与建议。'];
+  for(const line of lines) t.chunk({type:'text-delta',index:1,text:line});
+  t.chunk({type:'finish',reason:{kind:'stop'}});
+  check('场景7 正常结束放行',!!t.tripped(),false); }
+
+// 8 有产出仍限容量
+{ const t=h({thinkingOnlyMs:1e9,maxThinkingChars:400,checkEveryChars:1e9,notify:false}); t.start();
+  t.chunk({type:'text-delta',index:1,text:'先输出一小段文本。'});
+  for(let i=0;i<20;i++) t.chunk({type:'reasoning-delta',index:0,text:'随后陷入无限思考，继续消耗而不产出结论。'});
+  check('场景8 有产出仍限容量',!!t.tripped(),true); }
+
+// 9 文本复读
+{ const t=h({thinkingOnlyMs:1e9,maxThinkingChars:1e9,checkEveryChars:1,notify:false}); t.start();
+  const s='正在重新整理思路，稍后输出。'.repeat(20);
+  for(let i=0;i<s.length;i+=25) t.chunk({type:'text-delta',index:1,text:s.slice(i,i+25)});
+  check('场景9 文本复读熔断',!!t.tripped(),true); }
+
+// 10 长正常技术文本
+{ const t=h({thinkingOnlyMs:1e9,maxThinkingChars:1e9,checkEveryChars:1,notify:false}); t.start();
+  const para=['先确认目标服务的监听端口与证书链。','再比对中国件指纹，包括响应头顺序与错误页哈希。','随后核对静态资源路径的命名习惯，判断归属。','综合以上证据后记录确认方法，并标注待复核项。','如果证据不足则扩展侦察角度，换一条路径重新验证。'];
+  for(let r=0;r<4;r++) for(const p of para) t.chunk({type:'text-delta',index:1,text:p});
+  check('场景10 长正常文本放行',!!t.tripped(),false); }
+
+// 11 稀疏复读（跨大窗口短句高次重复，前三档在 600 字窗口内密度不足会漏检）
+// 回归用例：此档曾因 formatNotice 引用模块级 cfg 抛 ReferenceError，
+// 导致 cancel 永不执行、熔断静默失效（线上日志累计 500+ 次）。
+{ const t=h({thinkingOnlyMs:1e9,maxThinkingChars:1e9,checkEveryChars:1,notify:false}); t.start();
+  const parts=[]; for(let i=0;i<12;i++) parts.push('好。执行。', `第 ${i} 段实质不同的分析内容，用于拉开窗口距离。`);
+  const s=parts.join('');
+  let threw=null;
+  for(let i=0;i<s.length;i+=40){ try{ t.chunk({type:'reasoning-delta',index:0,text:s.slice(i,i+40)}); }catch(e){ threw=e; break; } }
+  check('场景11 稀疏复读熔断且不抛异常', threw===null && !!t.tripped(), true); }
+
+console.log(`\n合计：${pass} 通过 / ${fail} 失败`);
+process.exit(fail===0?0:1);