minimal-agent 0.1.9 → 0.3.0

package/src/config.js

@@ -0,0 +1,118 @@
+/**
+ * ============================================================
+ *  config.ts —— 全局配置加载（从 .env 读取）
+ * ------------------------------------------------------------
+ *  只从环境变量读取，集中管理所有配置。
+ *
+ *  必需的环境变量：
+ *    MINIMAL_AGENT_BASE_URL   - API 地址，如 https://api.minimax.chat/v1
+ *    MINIMAL_AGENT_API_KEY    - API key
+ *    MINIMAL_AGENT_MODEL      - 模型名，如 MiniMax-M2.7
+ *
+ *  可选的环境变量：
+ *    MINIMAL_AGENT_PROVIDER   - 友好名称，默认 "env"
+ *    MINIMAL_AGENT_CONTEXT_WINDOW - 上下文窗口，默认 128000
+ * ============================================================
+ */
+import { readSavedConfig } from './config/configFile.js';
+const DEFAULT_CONTEXT_WINDOW = 128_000;
+/**
+ * 加载 Provider 配置（从环境变量）。
+ * 缺少必需变量时抛出明确错误。
+ */
+export async function loadProvider() {
+    const baseURL = process.env.MINIMAL_AGENT_BASE_URL;
+    const apiKey = process.env.MINIMAL_AGENT_API_KEY;
+    const model = process.env.MINIMAL_AGENT_MODEL;
+    if (!baseURL || !apiKey || !model) {
+        const missing = [];
+        if (!baseURL)
+            missing.push('MINIMAL_AGENT_BASE_URL');
+        if (!apiKey)
+            missing.push('MINIMAL_AGENT_API_KEY');
+        if (!model)
+            missing.push('MINIMAL_AGENT_MODEL');
+        throw new Error(`缺少必需的环境变量：${missing.join(', ')}\n\n` +
+            `请在 .env 中配置：\n` +
+            `  MINIMAL_AGENT_BASE_URL=https://api.example.com/v1\n` +
+            `  MINIMAL_AGENT_API_KEY=your-api-key\n` +
+            `  MINIMAL_AGENT_MODEL=your-model\n\n` +
+            `参考 .env.example`);
+    }
+    const contextWindowRaw = process.env.MINIMAL_AGENT_CONTEXT_WINDOW;
+    let contextWindow = DEFAULT_CONTEXT_WINDOW;
+    if (contextWindowRaw) {
+        const n = parseInt(contextWindowRaw, 10);
+        if (!Number.isNaN(n) && n > 0) {
+            contextWindow = n;
+        }
+    }
+    return {
+        name: process.env.MINIMAL_AGENT_PROVIDER ?? 'env',
+        baseURL,
+        apiKey,
+        model,
+        contextWindow,
+    };
+}
+/**
+ * 层级加载：env 优先（模式 A），不全则回退到 ~/.minimal-agent/config.json（模式 B）。
+ * 都没有时返回 null —— 调用方决定是触发向导还是直接退出。
+ *
+ * 与 loadProvider() 的区别：
+ *   - loadProvider() 只读 env，全缺则抛错（给 -p 模式用，明确告知"先做配置"）
+ *   - 本函数静默 fallback 到 JSON，全缺则返回 null（给 TUI 模式用，可触发向导）
+ *
+ * env 字段优先级是逐项的：只要 env 里有 BASE_URL 就用 env 的 BASE_URL，
+ * 其它字段从 JSON 补；这样用户可以临时用 env 覆盖单个字段做调试。
+ */
+export async function loadProviderLayered() {
+    const envBaseURL = process.env.MINIMAL_AGENT_BASE_URL;
+    const envApiKey = process.env.MINIMAL_AGENT_API_KEY;
+    const envModel = process.env.MINIMAL_AGENT_MODEL;
+    const envName = process.env.MINIMAL_AGENT_PROVIDER;
+    const envContextRaw = process.env.MINIMAL_AGENT_CONTEXT_WINDOW;
+    let saved = null;
+    if (!envBaseURL || !envApiKey || !envModel) {
+        saved = await readSavedConfig();
+    }
+    const baseURL = envBaseURL ?? saved?.baseURL;
+    const apiKey = envApiKey ?? saved?.apiKey;
+    const model = envModel ?? saved?.model;
+    if (!baseURL || !apiKey || !model)
+        return null;
+    let contextWindow = DEFAULT_CONTEXT_WINDOW;
+    if (envContextRaw) {
+        const n = parseInt(envContextRaw, 10);
+        if (!Number.isNaN(n) && n > 0)
+            contextWindow = n;
+    }
+    else if (saved?.contextWindow) {
+        contextWindow = saved.contextWindow;
+    }
+    return {
+        name: envName ?? saved?.provider ?? 'env',
+        baseURL,
+        apiKey,
+        model,
+        contextWindow,
+    };
+}
+/**
+ * 把 saved config 里的工具 key 注入 process.env（env 已设则不覆盖）。
+ *
+ * 解决 npm 全局安装场景：`node dist/main.js` 不会自动加载 .env，
+ * Tavily 之类的工具 key 只能从 ~/.minimal-agent/config.json 取出再写回 env，
+ * websearch.ts 才能在 call() 里读到。
+ *
+ * 应在 main() 最早期调用（initWorkingDir 之后即可），保证 ALL_TOOLS
+ * 任何 call() 触发前 env 已就位。
+ */
+export async function applyToolKeysToEnv() {
+    const saved = await readSavedConfig();
+    if (!saved)
+        return;
+    if (!process.env.TAVILY_API_KEY && saved.tavilyApiKey) {
+        process.env.TAVILY_API_KEY = saved.tavilyApiKey;
+    }
+}

package/src/context/compact.js

@@ -0,0 +1,357 @@
+/**
+ * ============================================================
+ *  src/context/compact.ts —— 自动压缩逻辑（v0.2 修复版）
+ * ============================================================
+ *  做的事：
+ *    1. 估算当前历史的 token 数
+ *    2. 若超过阈值（contextWindow - AUTOCOMPACT_BUFFER_TOKENS），触发压缩
+ *    3. 压缩流程：
+ *         a. 把整段历史 + 9 段式压缩 prompt 发给 LLM（非流式）
+ *         b. 提取 <summary> 块
+ *         c. 用"会话延续"包装把摘要做成 user 消息，紧跟最后 N 条原消息
+ *
+ *  v0.2 修复说明（2026-05-08）：
+ *    - 🚨 修复致命 bug：/compact 后 tool_call / tool_result 配对关系破坏
+ *      导致 MiniMax API 返回 400 "tool id not found" 错误
+ *    - ✅ 新增 findTailWithCompleteToolChains() 函数
+ *      智能截取尾部消息，保证每条 tool 消息都有对应的 tool_call 父消息
+ *    - ✅ 不再使用固定的 KEEP_RECENT_MESSAGES = 4 简单切片
+ *    - 改为动态扫描算法：从末尾向前检查完整性，必要时自动扩展
+ *
+ *  为什么保留最后 N 条？
+ *    模型刚执行完工具的 tool_result 不能丢，否则后续推理失去依据。
+ *    但现在不是固定 N 条，而是动态保证 tool 消息完整性。
+ *
+ *  为什么用"延续"包装而不是直接塞摘要？
+ *    借鉴 kakadeai：在摘要前后加上"this session is continued from..."
+ *    + "Recent messages are preserved verbatim" + "Continue from where it
+ *    left off without asking" 三句话，可以让模型直接接着干活而不是把摘要
+ *    当成新任务"重新介绍一遍"。
+ *
+ *  ---- prompt 模板内联自 src/prompts/compact.ts ----
+ */
+import { chat } from '../llm/client.js';
+import { countMessagesTokens } from './tokenCounter.js';
+/** 压缩这一轮严禁调工具——前置警告 */
+const NO_TOOLS_PREAMBLE = `CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.
+
+- Do NOT use Read, Bash, Grep, Glob, Edit, Write, or ANY other tool.
+- You already have all the context you need in the conversation above.
+- Tool calls will be REJECTED and will waste your only turn — you will fail the task.
+- Your entire response must be plain text: an <analysis> block followed by a <summary> block.
+
+`;
+/** 同样的警告再放在 prompt 末尾——adaptive-thinking 模型在长 prompt 末尾容易"飘" */
+const NO_TOOLS_TRAILER = '\n\nREMINDER: Do NOT call any tools. Respond with plain text only — ' +
+    'an <analysis> block followed by a <summary> block. ' +
+    'Tool calls will be rejected and you will fail the task.';
+/**
+ * 9 段式压缩模板主体——UP_TO 变体。
+ */
+const COMPACT_PROMPT_BODY = `Your task is to create a detailed summary of this conversation. This summary will be placed at the start of a continuing session; newer messages that build on this context will follow after your summary. Summarize thoroughly so that someone reading only your summary and then the newer messages can fully understand what happened and continue the work.
+
+Before providing your final summary, wrap your analysis in <analysis> tags to organize your thoughts and ensure you've covered all necessary points. In your analysis process:
+
+1. Chronologically analyze each message and section of the conversation. For each section thoroughly identify:
+   - The user's explicit requests and intents
+   - Your approach to addressing the user's requests
+   - Key decisions, technical concepts and code patterns
+   - Specific details like file names, full code snippets, function signatures, file edits
+   - Errors that you ran into and how you fixed them
+   - Pay special attention to specific user feedback that you received, especially if the user told you to do something differently.
+2. Double-check for technical accuracy and completeness, addressing each required element thoroughly.
+
+Your summary should include the following sections:
+
+1. Primary Request and Intent: Capture all of the user's explicit requests and intents in detail
+2. Key Technical Concepts: List all important technical concepts, technologies, and frameworks discussed.
+3. Files and Code Sections: Enumerate specific files and code sections examined, modified, or created. Include FULL code snippets where applicable and include a summary of why this file read or edit is important. (Code snippets are NOT compressed — preserve them verbatim.)
+4. Errors and fixes: List all errors that you ran into, and how you fixed them. Pay special attention to specific user feedback that you received, especially if the user told you to do something differently.
+5. Problem Solving: Document problems solved and any ongoing troubleshooting efforts.
+6. All user messages: List ALL user messages that are not tool results. These are critical for understanding the users' feedback and changing intent. (User messages are NOT compressed — preserve them verbatim.)
+7. Pending Tasks: Outline any pending tasks that you have explicitly been asked to work on.
+8. Work Completed: Describe what was accomplished by the end of this portion.
+9. Context for Continuing Work: Summarize any context, decisions, or state that would be needed to understand and continue the work in subsequent messages. Include direct quotes from the most recent conversation showing exactly where work was left off — this should be verbatim to ensure there's no drift.
+
+Here's an example of how your output should be structured:
+
+<example>
+<analysis>
+[Your thought process, ensuring all points are covered thoroughly and accurately]
+</analysis>
+
+<summary>
+1. Primary Request and Intent:
+   [Detailed description]
+
+2. Key Technical Concepts:
+   - [Concept 1]
+   - [...]
+
+3. Files and Code Sections:
+   - [File Name 1]
+      - [Summary of why this file is important]
+      - [Important Code Snippet]
+   - [...]
+
+4. Errors and fixes:
+    - [Detailed description of error 1]:
+      - [How you fixed the error]
+      - [User feedback on the error if any]
+    - [...]
+
+5. Problem Solving:
+  [Description of solved problems and ongoing troubleshooting]
+
+6. All user messages:
+    - [Detailed non tool use user message]
+    - [...]
+
+7. Pending Tasks:
+   - [Task 1]
+   - [...]
+
+8. Work Completed:
+  [What was accomplished]
+
+9. Context for Continuing Work:
+  [Key context, decisions, or state needed to continue]
+
+</summary>
+</example>
+
+Please provide your summary following this structure, ensuring precision and thoroughness in your response.`;
+/**
+ * 完整的压缩 prompt：preamble + 9 段模板 + 可选的 customInstructions + trailer.
+ */
+export function buildCompactPrompt(customInstructions) {
+    let prompt = NO_TOOLS_PREAMBLE + COMPACT_PROMPT_BODY;
+    if (customInstructions && customInstructions.trim() !== '') {
+        prompt += `\n\nAdditional Instructions:\n${customInstructions.trim()}`;
+    }
+    prompt += NO_TOOLS_TRAILER;
+    return prompt;
+}
+/**
+ * 兼容旧名：现在等价于 buildCompactPrompt() 的默认调用。
+ */
+export const BASE_COMPACT_PROMPT = buildCompactPrompt();
+/**
+ * 把摘要包装成"会话延续"指令——这是让 LLM 接着干活而不是"重新介绍一遍"的关键。
+ */
+export function buildContinuationUserMessage(args) {
+    const { summary, recentMessagesPreserved } = args;
+    let msg = `This session is being continued from a previous conversation that ran out of context. The summary below covers the earlier portion of the conversation.
+
+${summary}`;
+    if (recentMessagesPreserved) {
+        msg += `\n\nRecent messages are preserved verbatim.`;
+    }
+    msg += `\n\nContinue the conversation from where it left off without asking the user any further questions. Resume directly — do not acknowledge the summary, do not recap what was happening, do not preface with "I'll continue" or similar. Pick up the last task as if the break never happened.`;
+    return msg;
+}
+/**
+ * 从 LLM 的压缩响应里提取 <summary>...</summary> 内的内容。
+ */
+export function formatCompactSummary(rawResponse) {
+    const match = rawResponse.match(/<summary>([\s\S]*?)<\/summary>/);
+    if (match)
+        return match[1].trim();
+    // 退化路径：去掉 <analysis> 块（如果有）
+    const stripped = rawResponse.replace(/<analysis>[\s\S]*?<\/analysis>/g, '').trim();
+    return stripped || rawResponse.trim();
+}
+/**
+ * autoCompact 触发阈值的安全 buffer。
+ *
+ * 设计意图：在 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 几乎不会被触发。
+ */
+export const AUTOCOMPACT_BUFFER_TOKENS = 25_000;
+/**
+ * 最少保留的消息数（即使没有 tool 调用也要保留这么多最近对话）
+ */
+export const MIN_KEEP_RECENT_MESSAGES = 4;
+/**
+ * 给定 provider 的压缩触发阈值
+ */
+export function getCompactThreshold(provider) {
+    return Math.max(1000, provider.contextWindow - AUTOCOMPACT_BUFFER_TOKENS);
+}
+/**
+ * ✅ 核心修复函数：智能截取尾部消息，保证 tool_call / tool_result 完整性。
+ *
+ * 问题背景：
+ *   OpenAI 协议要求 tool 消息的 tool_call_id 必须对应前面某条 assistant 消息
+ *   的 tool_calls[].id。如果压缩时只保留 tool 消息但丢掉了对应的 tool_call，
+ *   API 会返回 400 错误 "tool id not found"。
+ *
+ * 算法：
+ *   1. 从消息数组末尾开始，至少保留 minKeep 条消息
+ *   2. 维护一个 Set<tool_call_id> 记录已见过的 tool_call ID
+ *   3. 遇到 tool 消息时，检查其 tool_call_id 是否在 Set 中
+ *      - 如果不在 → 说明对应的 tool_call 消息被截断了 → 继续向前扩展
+ *      - 如果在 → 正常保留
+ *   4. 遇到 assistant 消息且有 tool_calls → 把所有 ID 加入 Set
+ *   5. 直到所有 tool 消息都有父级或到达数组开头
+ *
+ * @param messages 非系统消息数组
+ * @param minKeep 最少保留条数（默认 4）
+ * @returns 截取后的尾部子数组（保证 tool 消息完整性）
+ *
+ * 示例：
+ *   输入: [user, assistant(tool:A), tool(id:A), user, assistant]
+ *   minKeep: 3
+ *   输出: [assistant(tool:A), tool(id:A), user, assistant] (4条，自动扩展)
+ *
+ * 时间复杂度: O(N × M), N=消息数, M=平均扩展次数(通常<5)
+ * 空间复杂度: O(T), T=唯一 tool_call_id 数量(通常<20)
+ */
+export function findTailWithCompleteToolChains(messages, minKeep = MIN_KEEP_RECENT_MESSAGES) {
+    if (messages.length <= minKeep)
+        return [...messages];
+    // 至少保留 minKeep 条
+    const tailEnd = messages.length;
+    let tailStart = tailEnd - minKeep;
+    // 收集已经保留的 assistant 消息中的 tool_call IDs
+    const knownToolCallIds = new Set();
+    // 初始化已知 ID（从 minKeep 范围内）
+    for (let i = tailStart; i < tailEnd; i++) {
+        const msg = messages[i];
+        if (msg.role === 'assistant' && msg.tool_calls) {
+            for (const tc of msg.tool_calls) {
+                knownToolCallIds.add(tc.id);
+            }
+        }
+    }
+    // 检查是否有孤儿 tool 消息，如果有则向前扩展
+    let needsExpansion = true;
+    while (needsExpansion && tailStart > 0) {
+        needsExpansion = false;
+        for (let i = tailStart; i < tailEnd; i++) {
+            const msg = messages[i];
+            // 检查 tool 消息是否孤儿
+            if (msg.role === 'tool' && msg.tool_call_id) {
+                if (!knownToolCallIds.has(msg.tool_call_id)) {
+                    // ❌ 找到孤儿 tool 消息！需要向前扩展
+                    needsExpansion = true;
+                    tailStart--;
+                    // 把新加入的消息中的 tool_call ID 也加入集合
+                    const newMsg = messages[tailStart];
+                    if (newMsg.role === 'assistant' && newMsg.tool_calls) {
+                        for (const tc of newMsg.tool_calls) {
+                            knownToolCallIds.add(tc.id);
+                        }
+                    }
+                    // 重新开始检查（因为新加入的消息可能也是 tool 孤儿）
+                    break;
+                }
+            }
+        }
+    }
+    return messages.slice(tailStart);
+}
+/**
+ * 检查并按需压缩历史。
+ *
+ * @param messages 当前完整历史（必含一条 system）
+ * @param provider 当前 provider（取 contextWindow）
+ * @returns 可能更短的新 messages 数组（不修改原数组）
+ *
+ * 当 tokens 不超阈值时**直接返回原数组**（同引用），调用方可据此判断"是否压缩了"。
+ */
+export async function autoCompactIfNeeded(messages, provider) {
+    const before = countMessagesTokens(messages);
+    const threshold = getCompactThreshold(provider);
+    if (before < threshold) {
+        return { messages, compacted: false, before, after: before };
+    }
+    // 真正要压缩了
+    const compactedMessages = await runCompaction(messages, provider);
+    const after = countMessagesTokens(compactedMessages);
+    return { messages: compactedMessages, compacted: true, before, after };
+}
+/**
+ * 不看阈值，直接执行一次压缩。供 `/compact` 手动命令使用。
+ *
+ * 与 autoCompactIfNeeded 共用同一段 runCompaction 逻辑；区别仅在于此函数
+ * 永远跑压缩、不返回 `compacted` 字段（由调用方决定如何反馈）。
+ */
+export async function forceCompact(messages, provider) {
+    const before = countMessagesTokens(messages);
+    const compactedMessages = await runCompaction(messages, provider);
+    const after = countMessagesTokens(compactedMessages);
+    return { messages: compactedMessages, before, after };
+}
+/**
+ * 真正执行压缩（一轮非流式 LLM 调用）。
+ *
+ * 输入：原始历史
+ * 输出：[原 system, "会话延续指令 + 摘要" 的 user 消息, 最后 N 条原消息（保证完整性）]
+ *
+ * ✅ 关键修复：使用 findTailWithCompleteToolChains() 替代简单的 slice(-N)
+ * 保证压缩后的消息结构符合 OpenAI 协议要求（tool 消息必须有对应的 tool_call 父消息）。
+ */
+async function runCompaction(messages, provider) {
+    // 1. 找出原 system（保留它，避免 agent 失忆）
+    const systemMsg = messages.find((m) => m.role === 'system');
+    const nonSystem = messages.filter((m) => m.role !== 'system');
+    // 2. 构造给"压缩用"的请求：完整历史 + 9 段式压缩 prompt
+    //    （即使最后 N 条会被原样保留在新历史里，也送给 LLM 看 —— 让它写得出
+    //     高质量的 "Context for Continuing Work" 节，知道当前停在哪儿。）
+    const compactRequest = [
+        ...(systemMsg ? [systemMsg] : []),
+        ...nonSystem,
+        {
+            role: 'user',
+            content: buildCompactPrompt(),
+        },
+    ];
+    // 3. 调 LLM（用同一个 chat() 但不传工具，避免模型尝试调用工具）
+    let summary = '';
+    try {
+        for await (const ev of chat({
+            provider,
+            messages: compactRequest,
+            tools: [],
+        })) {
+            if (ev.type === 'text_delta')
+                summary += ev.delta;
+        }
+    }
+    catch (e) {
+        // 压缩失败时降级：保留原历史的最后 N 条 + 一条用 user 消息说明压缩失败
+        // ✅ 即使降级也要使用智能截取保证完整性
+        return [
+            ...(systemMsg ? [systemMsg] : []),
+            {
+                role: 'user',
+                content: `(自动压缩失败：${e.message}，已直接截断旧历史)`,
+            },
+            ...findTailWithCompleteToolChains(nonSystem),
+        ];
+    }
+    const cleanSummary = formatCompactSummary(summary);
+    // ✅ 核心修复：智能截取尾部，保证 tool 消息完整性
+    // 不再使用固定的 slice(-KEEP_RECENT_MESSAGES)
+    const recentTail = findTailWithCompleteToolChains(nonSystem);
+    // 4. 组装新历史：用"会话延续"包装把摘要做成 user 消息
+    return [
+        ...(systemMsg ? [systemMsg] : []),
+        {
+            role: 'user',
+            content: buildContinuationUserMessage({
+                summary: cleanSummary,
+                recentMessagesPreserved: recentTail.length > 0,
+            }),
+        },
+        ...recentTail,
+    ];
+}

package/src/context/microCompactLite.js

@@ -0,0 +1,151 @@
+/**
+ * ============================================================
+ *  src/context/microCompactLite.ts —— 工具结果微压缩（v2）
+ * ------------------------------------------------------------
+ *  对齐 kakadeai 的 microCompact 设计，纯规则实现，零 LLM 调用。
+ *
+ *  核心思路：
+ *    工具执行结果在写入 history 前经过一道"单向检查门"，
+ *    用规则压缩冗余内容，减少 token 消耗但不丢失关键信息。
+ *
+ *  对齐 kakadeai 的两条有效路径：
+ *    Path A: Cached MC → 本方案用 SHA-1 进程缓存 + 计数淘汰实现
+ *    Path B: Time-based MC → 本方案用轮次衰减实现
+ *
+ *  kakadeai 已删除 Legacy LLM path → 本方案不实现 LLM 压缩
+ * ============================================================
+ */
+import { createHash } from 'node:crypto';
+// ==================== 配置常量 ====================
+/** 同一内容最多原样保留多少次，之后用压缩引用替代 */
+const MAX_REPEAT_COUNT = 3;
+/** 触发截断的字符数阈值（仅白名单内的工具） */
+const MAX_RESULT_SIZE = 4000;
+/** 截断时保留的头部字符数 */
+const HEAD_KEEP_CHARS = 2000;
+/** 截断时保留的尾部字符数 */
+const TAIL_KEEP_CHARS = 1000;
+/** 时间衰减：条目首次出现后超过多少轮自动清理 */
+const MAX_KEEP_ROUNDS = 10;
+/** 短内容阈值：不超过此长度的内容直接放行（不做任何处理） */
+const SHORT_CONTENT_THRESHOLD = 200;
+export function createMicroCompactState() {
+    return { turn: 0, cache: new Map() };
+}
+const defaultState = createMicroCompactState();
+export function incrementTurn(state = defaultState) {
+    state.turn++;
+}
+export function resetTurn(state = defaultState) {
+    state.turn = 0;
+}
+/** 获取当前缓存统计 */
+export function getCacheStats(state = defaultState) {
+    let compressedCount = 0;
+    let expiredCount = 0;
+    let truncatedCount = 0;
+    let totalCharsSaved = 0;
+    let repeatedCount = 0;
+    for (const entry of state.cache.values()) {
+        if (entry.count > 1)
+            repeatedCount++;
+        if (entry.count > MAX_REPEAT_COUNT) {
+            compressedCount++;
+            totalCharsSaved += (entry.count - MAX_REPEAT_COUNT) * 500;
+        }
+        if (state.turn - entry.firstSeenTurn > MAX_KEEP_ROUNDS) {
+            expiredCount++;
+        }
+    }
+    return { totalEntries: state.cache.size, repeatedCount, compressedCount, expiredCount, truncatedCount, totalCharsSaved };
+}
+/** 清空缓存（供 /new 命令或测试使用） */
+export function clearCache(state = defaultState) {
+    state.cache.clear();
+    state.turn = 0;
+}
+// ==================== 工具白名单 ====================
+/**
+ * 只有这些工具的返回值参与微压缩（长度截断 + SHA-1 去重）。
+ *
+ * 排除 Read/Edit/Write 的原因：输出本身就短，有独立的大小限制。
+ * 排除 WebSearch 的原因：搜索结果是"一次性知识注入"，首次必须完整展示给模型；
+ *   后续重复时由 SHA-1 去重处理，但不做长度截断（避免丢失关键信息）。
+ */
+const COMPRESSIBLE_TOOLS = new Set([
+    'Grep',
+    'Bash',
+    'WebFetch',
+    'Glob',
+]);
+// ==================== 核心函数 ====================
+/**
+ * 对一条工具执行结果进行微压缩处理。
+ *
+ * 这是整个模块唯一的对外接口。loop.ts 在把 tool_result 塞入 history 之前调用它。
+ *
+ * 处理流水线（按优先级）：
+ *   Rule 0: 错误/短内容 → 原样放行
+ *   Rule 1: SHA-1 去重 → 相同内容第 4 次起压缩为引用标记
+ *   Rule 2: 时间衰减 → 超过 N 轮未再出现的内容清理掉
+ *   Rule 3: 长度截断 → 白名单工具超长内容保留头尾 + 省略标记
+ *
+ * @param toolName 工具名
+ * @param content 工具返回的原始内容
+ * @returns 处理后的内容（可能被压缩、截断、或原样返回）
+ */
+export function microCompact(toolName, content, state = defaultState) {
+    if (!content)
+        return content;
+    // Rule 0: 错误信息原样保留
+    if (content.startsWith('Error:') || content.startsWith('错误')) {
+        return content;
+    }
+    // Rule 0b: 短内容直接放行
+    if (content.length <= SHORT_CONTENT_THRESHOLD) {
+        return content;
+    }
+    // Rule 1: SHA-1 去重
+    const hash = sha1(content);
+    const existing = state.cache.get(hash);
+    if (existing) {
+        existing.count++;
+        if (existing.count > MAX_REPEAT_COUNT) {
+            return `[↑ ${existing.firstToolName} 结果已重复出现 ${existing.count} 次（相同内容已省略）]`;
+        }
+        return content;
+    }
+    // 首次看到此内容
+    state.cache.set(hash, { count: 1, firstToolName: toolName, firstSeenTurn: state.turn });
+    // Rule 2: 不需要——首次出现不存在时间衰减问题
+    // Rule 3: 长度截断（仅白名单工具）
+    if (content.length > MAX_RESULT_SIZE && COMPRESSIBLE_TOOLS.has(toolName)) {
+        return truncateContent(content);
+    }
+    return content;
+}
+/**
+ * 清理过期条目（每轮开始前调用）。
+ * 将超过 MAX_KEEP_ROUNDS 未被再次访问的条目标记为过期，
+ * 后续如果这些条目的 hash 再次命中，会作为"新内容"重新计数。
+ */
+export function expireOldEntries(state = defaultState) {
+    let expired = 0;
+    for (const [hash, entry] of state.cache) {
+        if (state.turn - entry.firstSeenTurn > MAX_KEEP_ROUNDS) {
+            state.cache.delete(hash);
+            expired++;
+        }
+    }
+    return expired;
+}
+// ==================== 内部函数 ====================
+function sha1(str) {
+    return createHash('sha1').update(str).digest('hex');
+}
+function truncateContent(content) {
+    const omitted = content.length - HEAD_KEEP_CHARS - TAIL_KEEP_CHARS;
+    return (content.slice(0, HEAD_KEEP_CHARS) +
+        `\n\n[... 省略了 ${omitted.toLocaleString()} 字符 ...]\n\n` +
+        content.slice(-TAIL_KEEP_CHARS));
+}