minimal-agent 0.6.1 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "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>",
@@ -54,6 +54,8 @@
     "clean": "bun scripts/clean-build.ts",
     "test": "bun test",
     "typecheck": "tsc --noEmit -p tsconfig.typecheck.json",
+    "compile:green": "bun scripts/build-green.ts",
+    "compile:green:host": "bun scripts/build-green.ts --host",
     "prepublishOnly": "bun run clean && bun run build"
   },
   "dependencies": {

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

@@ -20,18 +20,23 @@
 import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
-/** 配置文件路径（带环境变量覆盖，主要给测试用） */
+import { execSiblingDir } from '../utils/greenRoot.js';
+/**
+ * 配置文件的**写**路径（带环境变量覆盖，主要给测试用）。
+ * `saveConfig()` / 首次配置向导只写这里——env override 或 home，**绝不写 exe 同级**
+ * （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 默认配置路径（读分层的最后一档；也是 getConfigFilePath 的默认写入位置）。 */
+function homeConfigPath() {
+    return join(homedir(), '.minimal-agent', 'config.json');
 }
 /**
- * 读取向导保存的配置。
- *  - 文件不存在 / JSON 损坏 / 必填字段缺失 → 返回 null
- *  - 成功 → 返回 SavedConfig
+ * 解析单个 config.json：不存在 / JSON 损坏 / 必填字段缺失 → null；成功 → SavedConfig。
  */
-export async function readSavedConfig() {
-    const file = getConfigFilePath();
+async function parseConfigFile(file) {
     try {
         const raw = await readFile(file, 'utf8');
         const data = JSON.parse(raw);
@@ -51,6 +56,11 @@ export async function readSavedConfig() {
             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,
@@ -61,6 +71,30 @@ export async function readSavedConfig() {
         return null;
     }
 }
+/**
+ * 读取已保存的 provider 配置（**分层**，按优先级返回第一个有效的）：
+ *   1. `MINIMAL_AGENT_CONFIG_FILE` 显式覆盖 —— **只读这一个，不 fallthrough**
+ *      （保持既有语义 + 测试隔离）
+ *   2. exe 同级 `config.json` —— **绿色版 / U 盘的卖家预置配置**（compile 后
+ *      `execSiblingDir()` = 真实 exe 目录；dev/npm 下是 node/bun 二进制目录、无此文件 → 跳过）
+ *   3. `~/.minimal-agent/config.json` —— 首次配置向导写出的（原行为）
+ *
+ * 这层让卖家把配好的 config.json 放进绿色目录即完成预配置，客户端零配置开箱即用
+ * （loadProviderLayered 拿到 provider → 不进向导、`-p` 不报 config_error）。
+ *
+ * 加性保证：dev / npm 模式无 override 时，exe 同级无 config.json → 只命中 home → 行为不变。
+ */
+export async function readSavedConfig() {
+    const override = process.env.MINIMAL_AGENT_CONFIG_FILE;
+    if (override)
+        return parseConfigFile(override);
+    for (const file of [join(execSiblingDir(), 'config.json'), homeConfigPath()]) {
+        const cfg = await parseConfigFile(file);
+        if (cfg)
+            return cfg;
+    }
+    return null;
+}
 /**
  * 写入向导收集到的配置。
  * unix 上 chmod 600（仅本人可读写），Windows 上 chmod 是 no-op，靠 NTFS ACL。

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 };
     }
     // 真正要压缩了