minimal-agent 0.6.2 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "最小化 Agent 系统 —— 10 工具 + 插件系统 + workflow DSL + 自动压缩 + OpenAI 兼容 + Ink TUI；NodeNext + tsc 原地编译，dev 用 Bun .ts、install 用 Node .js（学习/教学用）",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Bill Wang <leiwang0359@gmail.com>",

package/plugins/workflow-runner/src/expressions.js

@@ -1,6 +1,6 @@
 /**
  * ============================================================
- *  src/workflows/expressions.ts —— workflow 表达式引擎（mini）
+ *  plugins/workflow-runner/src/expressions.ts —— workflow 表达式引擎（mini）
  * ------------------------------------------------------------
  *  WHY 不直接 eval / Function？
  *    Workflow 来源不可信（用户编辑器生成 / 别人贡献的 yaml），允许任意
@@ -310,7 +310,18 @@ function parsePrimary(c, vars) {
             const next = eat(c);
             if (next.kind !== 'ident')
                 throw new Error('点号后必须是标识符');
-            cur = cur != null && typeof cur === 'object' ? cur[next.value] : undefined;
+            // S1：禁止经点路径访问原型链（__proto__ / constructor / prototype），防原型污染 / 函数对象逃逸。
+            if (next.value === '__proto__' ||
+                next.value === 'constructor' ||
+                next.value === 'prototype') {
+                cur = undefined;
+            }
+            else {
+                cur =
+                    cur != null && typeof cur === 'object'
+                        ? cur[next.value]
+                        : undefined;
+            }
         }
         return cur;
     }

package/plugins/workflow-runner/src/loader.js

@@ -126,7 +126,9 @@ function validate(obj, file) {
 }
 // ADR-05: 控制流 type 集合——这些节点的"动作"由 type 自身定义，
 // 因此不能附带 tool/skill/llm 也不能配 output_schema / context_files / allowed_tools。
-const CONTROL_FLOW_TYPES = new Set([
+// 导出供「editor ↔ 后端」schema 一致性测试比对（test/editorSchemaSync.test.ts）。
+// editor 因 D2 红线禁止 import 后端、手抄了同一份；后端在此演进时该测试会红，提示同步 editor。
+export const CONTROL_FLOW_TYPES = new Set([
     'assert',
     'branch',
     'loop',
@@ -134,7 +136,7 @@ const CONTROL_FLOW_TYPES = new Set([
     'parallel',
     'vote',
 ]);
-const VALID_STEP_TYPES = new Set([
+export const VALID_STEP_TYPES = new Set([
     'assert',
     'branch',
     'loop',

package/src/cli/args.js

@@ -31,3 +31,30 @@ export function extractFlagValue(args, names) {
     }
     return undefined;
 }
+/**
+ * CLI 布尔标志（出现即生效、不带值）。集中定义一份，供 print.ts 的 extractPromptArgs
+ * 共用 —— 避免 flag 列表在多处各维护一份、新增 flag 时漏改导致「flag 值被当 prompt 污染」。
+ */
+export const BOOLEAN_FLAGS = new Set([
+    '-p',
+    '--print',
+    '--verbose',
+    '-v',
+    '-h',
+    '--help',
+    '-V',
+    '--version',
+    // stream-json 控制位（webchat broker / 网关用）；出现即生效、不带值。
+    '--clear',
+    '--compact',
+]);
+/**
+ * CLI 带值标志（标志本身 + 紧跟的下一个元素都不是位置参数）。
+ * 新增带值标志务必加到这里，否则它的值会被 extractPromptArgs 当成 prompt 文本。
+ */
+export const VALUE_FLAGS = new Set([
+    '-d',
+    '--cwd',
+    '--output-format',
+    '--max-turns',
+]);

package/src/cli/print.js

@@ -24,6 +24,7 @@
  */
 import { getContextPath, saveContext } from '../context/persistContext.js';
 import { runWithPlugins } from '../plugins/pluginRunner.js';
+import { BOOLEAN_FLAGS, VALUE_FLAGS } from './args.js';
 /** stderr 显示工具结果时的截断阈值；超过即末尾加 "..." */
 const TOOL_OUTPUT_PREVIEW_MAX = 200;
 /** stdin 读取超时（ms），防止非 TTY + 无管道时永久挂起 */
@@ -49,32 +50,14 @@ export function truncateForDisplay(content, max = TOOL_OUTPUT_PREVIEW_MAX) {
     return content.slice(0, max) + '...';
 }
 export function extractPromptArgs(args) {
-    // 布尔标志：直接过滤
-    const FLAG_BOOLEAN = new Set([
-        '-p',
-        '--print',
-        '--verbose',
-        '-v',
-        '-h',
-        '--help',
-        '-V',
-        '--version',
-    ]);
-    // 带值标志：本身 + 后面紧跟的值都要跳过
-    // （--output-format / --max-turns 必须在此，否则它们的值会被当成 prompt 文本污染）
-    const FLAG_WITH_VALUE = new Set([
-        '-d',
-        '--cwd',
-        '--output-format',
-        '--max-turns',
-    ]);
+    // flag 定义集中在 cli/args.ts（BOOLEAN_FLAGS / VALUE_FLAGS），这里只消费、不再各维护一份。
     const result = [];
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
-        if (FLAG_BOOLEAN.has(a))
+        if (BOOLEAN_FLAGS.has(a))
             continue;
-        if (FLAG_WITH_VALUE.has(a)) {
-            i++; // 跳过 flag 后面的值
+        if (VALUE_FLAGS.has(a)) {
+            i++; // 跳过带值标志紧跟的值（否则 --output-format 的值 json 会被当成 prompt 文本污染）
             continue;
         }
         result.push(a);
@@ -165,6 +148,23 @@ export async function runPrintMode(provider, args, initialHistory, options) {
         stopReason: undefined,
         error: null,
     };
+    // 收尾守卫：saveContext + (json) emit 只执行一次，所有退出路径 await 同一个
+    // promise 再 process.exit。
+    // 没有它的话：SIGINT 触发 abort 后，SIGINT handler 与 for-await 的 AbortError
+    // catch 会同时奔向收尾 → 双写 session 文件 + 往 stdout 打两行 JSON（破坏「一行契约」）。
+    // 用「缓存 promise」而非「布尔 once」是关键：后到的路径必须 await 到 emit 真正
+    // 完成再退出，否则可能抢先把进程杀掉、导致那一行 JSON 根本没发出。
+    let finalizePromise = null;
+    function finalizeOnce() {
+        if (!finalizePromise) {
+            finalizePromise = (async () => {
+                await saveContext(history);
+                if (isJson)
+                    emitJsonResult(result, trySessionFile());
+            })();
+        }
+        return finalizePromise;
+    }
     process.on('SIGINT', () => {
         if (interrupted)
             process.exit(130);
@@ -172,16 +172,9 @@ export async function runPrintMode(provider, args, initialHistory, options) {
         abortController.abort();
         console.error('\n已中断');
         // json 模式：SIGINT 也要给出结构化结局（stop_reason='interrupted'）
-        if (isJson) {
+        if (isJson)
             result.stopReason = 'interrupted';
-            void saveContext(history).finally(() => {
-                emitJsonResult(result, trySessionFile());
-                process.exit(130);
-            });
-        }
-        else {
-            void saveContext(history).finally(() => process.exit(130));
-        }
+        void finalizeOnce().finally(() => process.exit(130));
     });
     try {
         for await (const event of runWithPlugins(prompt, {
@@ -193,35 +186,28 @@ export async function runPrintMode(provider, args, initialHistory, options) {
             // event 是 LoopEvent | PluginEvent；handleEvent 只认 LoopEvent，未识别的插件私有事件走 default 静默忽略
             const handled = handleEvent(event, result, options.verbose, outputFormat);
             if (handled.exitCode !== undefined) {
-                await saveContext(history);
-                if (isJson)
-                    emitJsonResult(result, trySessionFile());
+                await finalizeOnce();
                 process.exit(handled.exitCode);
             }
         }
     }
     catch (e) {
         if (e.name === 'AbortError') {
-            await saveContext(history);
-            if (isJson) {
+            if (isJson)
                 result.stopReason = 'interrupted';
-                emitJsonResult(result, trySessionFile());
-            }
+            await finalizeOnce();
             process.exit(130);
         }
         console.error(`\n未捕获异常: ${e.message}`);
-        await saveContext(history);
         if (isJson) {
             // 未分类异常按 error 收尾（stopReason 仍为空 → emitJsonResult 兜底 'error'）
             result.error = result.error ?? e.message;
-            emitJsonResult(result, trySessionFile());
         }
+        await finalizeOnce();
         process.exit(1);
     }
-    await saveContext(history);
-    // json 模式：for-await 正常跑完（没有触发任何 exitCode 退出点）也要 emit 一行结局。
-    if (isJson)
-        emitJsonResult(result, trySessionFile());
+    // 正常跑完（没触发任何 exitCode 退出点）也走同一个收尾（json 模式 emit 一行结局）。
+    await finalizeOnce();
 }
 /**
  * 处理 runQuery yield 出来的 LoopEvent。

package/src/cli/streamJson.js

@@ -0,0 +1,117 @@
+/**
+ * ============================================================
+ *  src/cli/streamJson.ts —— `-p --output-format stream-json` 流式事件模式
+ * ------------------------------------------------------------
+ *  与 print.ts 的 text/json 一次性契约**并列、互不影响**（print.ts 一行未动）：
+ *    - text  : 纯文本答案（向后兼容）
+ *    - json  : 退出时一行结局契约
+ *    - stream-json（本文件）: 把 runQuery 的**每个 LoopEvent 作为一行 JSON**
+ *      实时写 stdout（jsonl）。给 webchat 本地服务 broker 用 —— 它 spawn 本模式、
+ *      逐行转发成 WebSocket event 帧。也是给网关预留的"流式子进程"契约。
+ *
+ *  约定：
+ *    - stdout 只允许 jsonl 事件流（一行一个 JSON.stringify(LoopEvent)）
+ *    - prompt 经 argv 或 stdin（与 print 一致）；--compact 走压缩动作（无需 prompt）
+ *    - 跑完 / 中断 / 出错都先 saveContext 再退出
+ * ============================================================
+ */
+import { getWorkingDir } from '../bootstrap/workingDir.js';
+import { forceCompact } from '../context/compact.js';
+import { recordRecentDir } from '../context/recentDirs.js';
+import { saveContext } from '../context/persistContext.js';
+import { runWithPlugins } from '../plugins/pluginRunner.js';
+import { extractPromptArgs, readFromStdin } from './print.js';
+/** 一行一个 JSON 事件写 stdout。EPIPE 时静默。 */
+function emitLine(ev) {
+    try {
+        process.stdout.write(`${JSON.stringify(ev)}\n`);
+    }
+    catch {
+        /* ignore */
+    }
+}
+function firstUserTitle(history) {
+    const u = history.find((m) => m.role === 'user');
+    return u && typeof u.content === 'string' ? u.content : undefined;
+}
+export async function runStreamJsonMode(provider, args, initialHistory, options) {
+    process.stdout.on('error', (err) => {
+        if (err.code === 'EPIPE')
+            process.stdout.destroy();
+    });
+    const history = initialHistory;
+    let finalized = false;
+    const finalize = async () => {
+        if (finalized)
+            return;
+        finalized = true;
+        await saveContext(history);
+    };
+    // --- 压缩动作（/compact）：不需要 prompt ---
+    if (options.compact) {
+        try {
+            emitLine({ type: 'compact_start' });
+            const r = await forceCompact(history, provider);
+            history.length = 0;
+            history.push(...r.messages);
+            emitLine({ type: 'compact_done', before: r.before, after: r.after });
+            emitLine({ type: 'turn_done' });
+        }
+        catch (e) {
+            emitLine({ type: 'error', error: `压缩失败：${e.message}`, code: 'compact_failed' });
+        }
+        await finalize();
+        return;
+    }
+    // --- 普通一轮 ---
+    const promptArgs = extractPromptArgs(args);
+    let prompt;
+    if (promptArgs.length > 0) {
+        prompt = promptArgs.join(' ');
+    }
+    else if (!process.stdin.isTTY) {
+        prompt = await readFromStdin();
+    }
+    else {
+        emitLine({ type: 'error', error: '未提供 prompt', code: 'llm_error' });
+        process.exit(1);
+    }
+    if (!prompt.trim()) {
+        emitLine({ type: 'error', error: 'prompt 为空', code: 'llm_error' });
+        process.exit(1);
+    }
+    // 记录最近目录（侧栏用）；title 优先用历史里第一条用户消息（稳定），否则用当前 prompt
+    await recordRecentDir(getWorkingDir(), firstUserTitle(history) ?? prompt);
+    const abortController = new AbortController();
+    let interrupted = false;
+    process.on('SIGINT', () => {
+        if (interrupted)
+            process.exit(130);
+        interrupted = true;
+        abortController.abort();
+        emitLine({ type: 'interrupted' });
+        void finalize().finally(() => process.exit(130));
+    });
+    try {
+        for await (const event of runWithPlugins(prompt, {
+            provider,
+            history,
+            signal: abortController.signal,
+            maxTurns: options.maxTurns,
+        })) {
+            // event 是 LoopEvent | PluginEvent，原样逐行 emit；前端不识别的插件私有事件会静默忽略
+            emitLine(event);
+        }
+    }
+    catch (e) {
+        if (e.name === 'AbortError') {
+            emitLine({ type: 'interrupted' });
+            await finalize();
+            process.exit(130);
+        }
+        emitLine({ type: 'error', error: e.message, code: 'llm_error' });
+        await finalize();
+        process.exit(1);
+    }
+    await finalize();
+}

package/src/config/configFile.js

@@ -27,10 +27,9 @@ import { execSiblingDir } from '../utils/greenRoot.js';
  * （U 盘可能只读，且不该污染产品目录）。读路径见 readSavedConfig 的分层。
  */
 export function getConfigFilePath() {
-    return (process.env.MINIMAL_AGENT_CONFIG_FILE ??
-        join(homedir(), '.minimal-agent', 'config.json'));
+    return process.env.MINIMAL_AGENT_CONFIG_FILE ?? homeConfigPath();
 }
-/** home 默认配置路径（读分层的最后一档）。 */
+/** home 默认配置路径（读分层的最后一档；也是 getConfigFilePath 的默认写入位置）。 */
 function homeConfigPath() {
     return join(homedir(), '.minimal-agent', 'config.json');
 }
@@ -57,6 +56,11 @@ async function parseConfigFile(file) {
             contextWindow: typeof data.contextWindow === 'number' && data.contextWindow > 0
                 ? data.contextWindow
                 : undefined,
+            compactRatio: typeof data.compactRatio === 'number' &&
+                data.compactRatio > 0 &&
+                data.compactRatio <= 1
+                ? data.compactRatio
+                : undefined,
             tavilyApiKey: typeof data.tavilyApiKey === 'string' && data.tavilyApiKey.length > 0
                 ? data.tavilyApiKey
                 : undefined,

package/src/config.js

@@ -16,6 +16,18 @@
  */
 import { readSavedConfig } from './config/configFile.js';
 const DEFAULT_CONTEXT_WINDOW = 128_000;
+/**
+ * 解析压缩阈值比例（0~1 小数）。
+ * 非法值（NaN、0、负数、>1）返回 undefined，由调用方决定是否用默认值 0.85。
+ */
+function parseCompactRatio(raw) {
+    if (!raw)
+        return undefined;
+    const n = parseFloat(raw);
+    if (Number.isNaN(n) || n <= 0 || n > 1)
+        return undefined;
+    return n;
+}
 /**
  * 加载 Provider 配置（从环境变量）。
  * 缺少必需变量时抛出明确错误。
@@ -47,12 +59,14 @@ export async function loadProvider() {
             contextWindow = n;
         }
     }
+    const compactRatio = parseCompactRatio(process.env.MINIMAL_AGENT_COMPACT_RATIO);
     return {
         name: process.env.MINIMAL_AGENT_PROVIDER ?? 'env',
         baseURL,
         apiKey,
         model,
         contextWindow,
+        ...(compactRatio !== undefined ? { compactRatio } : {}),
     };
 }
 /**
@@ -90,12 +104,17 @@ export async function loadProviderLayered() {
     else if (saved?.contextWindow) {
         contextWindow = saved.contextWindow;
     }
+    // compactRatio：env 优先（测试时临时 MINIMAL_AGENT_COMPACT_RATIO=0.2 即可），否则取 saved。
+    const envRatio = parseCompactRatio(process.env.MINIMAL_AGENT_COMPACT_RATIO);
+    const compactRatio = envRatio ??
+        (typeof saved?.compactRatio === 'number' ? saved.compactRatio : undefined);
     return {
         name: envName ?? saved?.provider ?? 'env',
         baseURL,
         apiKey,
         model,
         contextWindow,
+        ...(compactRatio !== undefined ? { compactRatio } : {}),
     };
 }
 /**

package/src/context/compact.js

@@ -4,7 +4,7 @@
  * ============================================================
  *  做的事：
  *    1. 估算当前历史的 token 数
- *    2. 若超过阈值（contextWindow - AUTOCOMPACT_BUFFER_TOKENS），触发压缩
+ *    2. 若超过阈值（contextWindow × compactRatio，默认 0.85），触发压缩
  *    3. 压缩流程：
  *         a. 把整段历史 + 9 段式压缩 prompt 发给 LLM（非流式）
  *         b. 提取 <summary> 块
@@ -161,29 +161,32 @@ export function formatCompactSummary(rawResponse) {
     const stripped = rawResponse.replace(/<analysis>[\s\S]*?<\/analysis>/g, '').trim();
     return stripped || rawResponse.trim();
 }
+/** 自动压缩触发阈值默认占 contextWindow 的比例（可被 provider.compactRatio 覆盖）。 */
+export const DEFAULT_COMPACT_RATIO = 0.85;
 /**
- * autoCompact 触发阈值的安全 buffer。
+ * 阈值的绝对安全下限：至少给下一轮 LLM 输出留这么多 token。
  *
- * 设计意图：在 contextWindow 被撑满之前留出"必须装得下"的两块空间：
- *   - 下一次 LLM 完整输出（assistant message + 多个 tool_calls）约 ~12K
- *   - 发起压缩调用时把 9 段模板 prompt 也算上的余量 ~13K
- *
- * 对比：kakadeai 主项目用 ~33K（output 20K + buffer 13K），但它有
- * prompt cache 收益所以可以更激进；我们没有 cache，25K 是稳健折中。
- *
- * 主动触发优先于 reactive 兜底——把 buffer 留宽一点，让 autoCompact
- * 在 LLM 真撑爆之前先把上下文摘要掉，reactive 几乎不会被触发。
+ * 设计意图：无论 ratio 设多大，contextWindow - 8000 都必须空出来给
+ * 下一轮 LLM 输出（assistant 回答 + tool_calls），防止撑爆。
  */
-export const AUTOCOMPACT_BUFFER_TOKENS = 25_000;
+export const COMPACT_OUTPUT_BUFFER_TOKENS = 8_000;
 /**
  * 最少保留的消息数（即使没有 tool 调用也要保留这么多最近对话）
  */
 export const MIN_KEEP_RECENT_MESSAGES = 4;
 /**
- * 给定 provider 的压缩触发阈值
+ * 给定 provider 的压缩触发阈值（按 contextWindow 比例缩放，provider 无关）。
+ *
+ * 公式：min(contextWindow × compactRatio, contextWindow − 8000)，且至少 1000。
+ *
+ * 为何改成比例而不是固定 buffer：
+ *   - 128K 窗口的 25K buffer = 81%，4K 窗口的 25K buffer = 负数（不合法）
+ *   - 比例自动适配所有模型，测试时把 ratio 调到 0.2 即可轻松触发压缩
+ *   - COMPACT_OUTPUT_BUFFER_TOKENS = 8000 是绝对安全下限，保证 LLM 有足够的输出空间
  */
 export function getCompactThreshold(provider) {
-    return Math.max(1000, provider.contextWindow - AUTOCOMPACT_BUFFER_TOKENS);
+    const ratio = provider.compactRatio ?? DEFAULT_COMPACT_RATIO;
+    return Math.max(1000, Math.min(Math.floor(provider.contextWindow * ratio), provider.contextWindow - COMPACT_OUTPUT_BUFFER_TOKENS));
 }
 /**
  * ✅ 核心修复函数：智能截取尾部消息，保证 tool_call / tool_result 完整性。
@@ -256,21 +259,43 @@ export function findTailWithCompleteToolChains(messages, minKeep = MIN_KEEP_RECE
             }
         }
     }
-    return messages.slice(tailStart);
+    // 不变量（Y3）：尾部不能以「未配对的 assistant.tool_calls」结尾 —— 它的 tool 响应不在
+    // 本切片内，直接发 OpenAI 会 400（assistant 的每个 tool_calls 必须有后续对应的 tool 消息）。
+    // 当前 autoCompact 在每轮轮首调用、输入末尾天然完整；这里仍主动裁剪，解除对「调用时机」的
+    // 隐式依赖，让算法自身健壮（被裁的是裸 assistant，其 tool 响应本就不存在，不会留下孤儿 tool）。
+    let tail = messages.slice(tailStart);
+    while (tail.length > 0 &&
+        tail[tail.length - 1].role === 'assistant' &&
+        (tail[tail.length - 1].tool_calls
+            ?.length ?? 0) > 0) {
+        tail = tail.slice(0, -1);
+    }
+    return tail;
 }
 /**
  * 检查并按需压缩历史。
  *
  * @param messages 当前完整历史（必含一条 system）
- * @param provider 当前 provider（取 contextWindow）
+ * @param provider 当前 provider（取 contextWindow / compactRatio）
+ * @param opts     可选的辅助数据，用于校正系统性低估：
+ *   - actualPromptTokens：本轮 LLM done 事件返回的真实 prompt token 数（如有）
+ *   - toolsTokens：工具 schema 占的估算 token 数（由 estimateToolsTokens 算出）
  * @returns 可能更短的新 messages 数组（不修改原数组）
  *
+ * 判据（取"真实 usage"与"估算+工具token"两者之大者）：
+ *   - countMessagesTokens 只数历史消息，漏了工具 schema token → 系统性低估
+ *   - LLM 返回的真实 usage 是最精确的，但不是每次都有（老 provider 或关了 include_usage）
+ *   - 取 max 确保：有真实值时用真实值；没有时用估算+工具补偿；二者都有时取最保守的
+ *
  * 当 tokens 不超阈值时**直接返回原数组**（同引用），调用方可据此判断"是否压缩了"。
  */
-export async function autoCompactIfNeeded(messages, provider) {
-    const before = countMessagesTokens(messages);
+export async function autoCompactIfNeeded(messages, provider, opts) {
+    const before = countMessagesTokens(messages); // 纯历史 token，保持语义不变（UI/snip/对比均依赖此值）
+    // 判据：真实 usage（若有）与「估算 + 工具 schema」取大者，校正系统性低估
+    const estimated = before + (opts?.toolsTokens ?? 0);
+    const judge = Math.max(opts?.actualPromptTokens ?? 0, estimated);
     const threshold = getCompactThreshold(provider);
-    if (before < threshold) {
+    if (judge < threshold) {
         return { messages, compacted: false, before, after: before };
     }
     // 真正要压缩了

package/src/context/reactiveCompact.js

@@ -3,7 +3,7 @@
  *  src/context/reactiveCompact.ts —— 反应式压缩（错误自救）
  * ------------------------------------------------------------
  *  对齐 kakadeai 主项目 services/compact/reactiveCompact.ts：
- *  当 API 返回 "prompt too long" 类错误时，自动触发一次压缩重试。
+ *  当 API 返回 "prompt too long" 类错误时，自动触发压缩重试。
  *
  *  典型场景：
  *    用户灌了一大段上下文 → 调 LLM → 返回 400 prompt_too_long
@@ -11,27 +11,39 @@
  *    → 摘要失败再用 snipCompact 砍头兜底
  *    → 把新上下文交还给调用方，调用方重试一次 chat()
  *
- *  防爆约束：
- *    每个 session 最多自救一次（attemptedThisSession 标志位）。
- *    用户 /new 重启会话后才能再次自救。这避免"压缩→还是太长→再压缩"
- *    的死循环。
+ *  防爆约束（circuit breaker）：
+ *    连续自救失败 MAX_CONSECUTIVE_REACTIVE_FAILURES 次才熔断。
+ *    任意一次自救成功（LLM 压缩或 snip 兜底）→ 计数清零，
+ *    允许后续再次触发。行为：压缩成功→继续→再溢出→再压→正常往复。
+ *    用户 /new 重启会话后 consecutiveFailures 也归零。
  * ============================================================
  */
 import { forceCompact } from './compact.js';
 import { snipCompactIfNeeded } from './snipCompact.js';
 import { countMessagesTokens } from './tokenCounter.js';
 export function createReactiveCompactState() {
-    return { attempted: false };
+    return { consecutiveFailures: 0 };
 }
+/** 连续失败几次触发熔断，拒绝继续自救 */
+export const MAX_CONSECUTIVE_REACTIVE_FAILURES = 3;
 const defaultState = createReactiveCompactState();
 /** /new 时调用，允许下一个 session 再次自救 */
 export function resetReactiveCompactState(state = defaultState) {
-    state.attempted = false;
+    state.consecutiveFailures = 0;
 }
-/** 测试 / 调试用：查询当前是否已尝试 */
+/**
+ * 测试 / 调试用：查询 circuit breaker 是否已熔断（连续失败达上限）。
+ *
+ * 原签名 hasAttemptedReactiveCompact 在新语义下映射为「电路是否已断开」：
+ * 单次成功就清零，只有连续失败 ≥ MAX_CONSECUTIVE_REACTIVE_FAILURES 才返回 true。
+ * 效果等价于原先的 attempted 旗标语义的"超集"（原先=1次，新=N次）。
+ * 别名 isReactiveCircuitOpen 供新代码使用，两者完全等价。
+ */
 export function hasAttemptedReactiveCompact(state = defaultState) {
-    return state.attempted;
+    return state.consecutiveFailures >= MAX_CONSECUTIVE_REACTIVE_FAILURES;
 }
+/** hasAttemptedReactiveCompact 的语义化别名 */
+export const isReactiveCircuitOpen = hasAttemptedReactiveCompact;
 // ==================== 错误识别 ====================
 /**
  * 判断一个错误是否是"提示词太长"类错误。
@@ -63,29 +75,37 @@ function errorMessage(error) {
     return String(error ?? '');
 }
 /**
- * 如果当前错误是 prompt_too_long 且本 session 未尝试过自救，
+ * 如果当前错误是 prompt_too_long 且 circuit breaker 未熔断，
  * 执行一次"先 LLM 压缩、失败兜底 snip"的恢复流程。
  *
+ * circuit breaker 规则：
+ *   - 任意成功（LLM 压缩 or snip 兜底）→ consecutiveFailures 清零
+ *   - 两个步骤都失败 → consecutiveFailures +1
+ *   - consecutiveFailures ≥ MAX_CONSECUTIVE_REACTIVE_FAILURES → 熔断拒绝
+ *
  * @param messages 当前历史（不修改）
  * @param provider 当前 provider（用于 LLM 压缩）
  * @param error    刚刚抛出的错误
+ * @param state    可选的独立状态（默认使用进程级单例）
  */
 export async function reactiveCompactIfApplicable(messages, provider, error, state = defaultState) {
+    // 非 prompt_too_long 错误：直接短路，不消耗计数
     if (!isPromptTooLongError(error)) {
         return { recovered: false, messages, reason: 'not a prompt-too-long error' };
     }
-    if (state.attempted) {
+    // 电路已熔断：连续失败达上限，拒绝继续
+    if (state.consecutiveFailures >= MAX_CONSECUTIVE_REACTIVE_FAILURES) {
         return {
             recovered: false,
             messages,
-            reason: 'already attempted this session — use /new or /compact manually',
+            reason: '反应式压缩已熔断（连续失败达上限）——请 /new 或手动 /compact',
         };
     }
-    // 占位：即使下面失败也算"用过一次"，防止反复触发
-    state.attempted = true;
     // Step 1: 先试 LLM 全量压缩
     try {
         const r = await forceCompact(messages, provider);
+        // 救活成功 → 清零计数，让后续继续可用
+        state.consecutiveFailures = 0;
         return {
             recovered: true,
             messages: r.messages,
@@ -94,16 +114,15 @@ export async function reactiveCompactIfApplicable(messages, provider, error, sta
             after: r.after,
         };
     }
-    catch (compactErr) {
+    catch {
         // 压缩失败 → 走 snip 兜底
     }
     // Step 2: snip 兜底（更激进 40%）
     const beforeSnip = countMessagesTokens(messages);
-    const snipped = snipCompactIfNeeded(messages, {
-        force: true,
-        snipPercent: 0.4,
-    });
+    const snipped = snipCompactIfNeeded(messages, { force: true, snipPercent: 0.4 });
     if (snipped.messagesRemoved > 0) {
+        // snip 也算救活 → 清零计数
+        state.consecutiveFailures = 0;
         const afterSnip = countMessagesTokens(snipped.messages);
         return {
             recovered: true,
@@ -113,6 +132,8 @@ export async function reactiveCompactIfApplicable(messages, provider, error, sta
             after: afterSnip,
         };
     }
+    // 两步都没救活 → 失败计数 +1
+    state.consecutiveFailures++;
     return {
         recovered: false,
         messages,