minimal-agent 0.2.0 → 0.3.1

package/src/context/reactiveCompact.js

@@ -0,0 +1,121 @@
+/**
+ * ============================================================
+ *  src/context/reactiveCompact.ts —— 反应式压缩（错误自救）
+ * ------------------------------------------------------------
+ *  对齐 kakadeai 主项目 services/compact/reactiveCompact.ts：
+ *  当 API 返回 "prompt too long" 类错误时，自动触发一次压缩重试。
+ *
+ *  典型场景：
+ *    用户灌了一大段上下文 → 调 LLM → 返回 400 prompt_too_long
+ *    → 系统不直接报错，而是先调 forceCompact 把上下文摘要一遍
+ *    → 摘要失败再用 snipCompact 砍头兜底
+ *    → 把新上下文交还给调用方，调用方重试一次 chat()
+ *
+ *  防爆约束：
+ *    每个 session 最多自救一次（attemptedThisSession 标志位）。
+ *    用户 /new 重启会话后才能再次自救。这避免"压缩→还是太长→再压缩"
+ *    的死循环。
+ * ============================================================
+ */
+import { forceCompact } from './compact.js';
+import { snipCompactIfNeeded } from './snipCompact.js';
+import { countMessagesTokens } from './tokenCounter.js';
+export function createReactiveCompactState() {
+    return { attempted: false };
+}
+const defaultState = createReactiveCompactState();
+/** /new 时调用，允许下一个 session 再次自救 */
+export function resetReactiveCompactState(state = defaultState) {
+    state.attempted = false;
+}
+/** 测试 / 调试用：查询当前是否已尝试 */
+export function hasAttemptedReactiveCompact(state = defaultState) {
+    return state.attempted;
+}
+// ==================== 错误识别 ====================
+/**
+ * 判断一个错误是否是"提示词太长"类错误。
+ *
+ * 兼容多家 provider 的错误消息格式：
+ *   - OpenAI:   "This model's maximum context length is X tokens..."
+ *   - Anthropic: "prompt is too long"
+ *   - MiniMax:  "input length exceeds the context window"
+ *   - DeepSeek: "context_length_exceeded"
+ *   - 通用:     含 "prompt" / "context" / "token" 且含 "long"/"exceed"/"limit"
+ */
+export function isPromptTooLongError(error) {
+    const msg = errorMessage(error).toLowerCase();
+    if (!msg)
+        return false;
+    // 宽松匹配：提及 prompt/context/token 且提及 long/exceed/limit/max
+    const hasSubject = /prompt|context|token|input length/.test(msg);
+    const hasIssue = /too long|exceed|limit|maximum|over/.test(msg);
+    return hasSubject && hasIssue;
+}
+function errorMessage(error) {
+    if (typeof error === 'string')
+        return error;
+    if (error instanceof Error)
+        return error.message;
+    if (error && typeof error === 'object' && 'message' in error) {
+        return String(error.message ?? '');
+    }
+    return String(error ?? '');
+}
+/**
+ * 如果当前错误是 prompt_too_long 且本 session 未尝试过自救，
+ * 执行一次"先 LLM 压缩、失败兜底 snip"的恢复流程。
+ *
+ * @param messages 当前历史（不修改）
+ * @param provider 当前 provider（用于 LLM 压缩）
+ * @param error    刚刚抛出的错误
+ */
+export async function reactiveCompactIfApplicable(messages, provider, error, state = defaultState) {
+    if (!isPromptTooLongError(error)) {
+        return { recovered: false, messages, reason: 'not a prompt-too-long error' };
+    }
+    if (state.attempted) {
+        return {
+            recovered: false,
+            messages,
+            reason: 'already attempted this session — use /new or /compact manually',
+        };
+    }
+    // 占位：即使下面失败也算"用过一次"，防止反复触发
+    state.attempted = true;
+    // Step 1: 先试 LLM 全量压缩
+    try {
+        const r = await forceCompact(messages, provider);
+        return {
+            recovered: true,
+            messages: r.messages,
+            reason: `LLM 压缩成功（${r.before} → ${r.after} tokens）`,
+            before: r.before,
+            after: r.after,
+        };
+    }
+    catch (compactErr) {
+        // 压缩失败 → 走 snip 兜底
+    }
+    // Step 2: snip 兜底（更激进 40%）
+    const beforeSnip = countMessagesTokens(messages);
+    const snipped = snipCompactIfNeeded(messages, {
+        force: true,
+        snipPercent: 0.4,
+    });
+    if (snipped.messagesRemoved > 0) {
+        const afterSnip = countMessagesTokens(snipped.messages);
+        return {
+            recovered: true,
+            messages: snipped.messages,
+            reason: `snip 兜底成功（删除 ${snipped.messagesRemoved} 条最老消息，释放 ~${snipped.tokensFreed} tokens）`,
+            before: beforeSnip,
+            after: afterSnip,
+        };
+    }
+    return {
+        recovered: false,
+        messages,
+        reason: '反应式压缩失败：LLM 压缩抛错且 snip 也没东西可砍',
+    };
+}

package/src/context/sessionPath.js

@@ -0,0 +1,58 @@
+/**
+ * ============================================================
+ *  src/context/sessionPath.ts —— 按目录隔离的会话文件路径
+ * ------------------------------------------------------------
+ *  做的事：
+ *    把当前工作目录编码为 ~/.minimal-agent/sessions/<encoded>.json
+ *    的文件名，让不同项目目录的对话历史互不覆盖。
+ *
+ *  命名规则：
+ *    <sanitized-path>-<6-hex-hash>.json
+ *      sanitized：路径归一化后只保留 [a-z0-9-]，最长 80 字符
+ *      hash    ：原始路径 sha1 前 6 位，防 sanitize 后碰撞
+ *
+ *  迁移：
+ *    旧版 ~/.minimal-agent/last-context.json 启动时一次性 rename 到
+ *    当前 cwd 对应的会话文件。失败静默——丢迁移好过崩进程。
+ * ============================================================
+ */
+import { createHash } from 'node:crypto';
+import { mkdir, rename, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+/** 把 cwd 编码成会话文件绝对路径 */
+export function sessionFileFor(cwd) {
+    const normalized = resolve(cwd).replace(/\\/g, '/').toLowerCase();
+    const sanitized = normalized
+        .replace(/:/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 80);
+    const hash = createHash('sha1').update(normalized).digest('hex').slice(0, 6);
+    return join(homedir(), '.minimal-agent', 'sessions', `${sanitized}-${hash}.json`);
+}
+/**
+ * 一次性把旧版 ~/.minimal-agent/last-context.json 迁到当前 cwd 对应的
+ * 会话文件。
+ *
+ * 静默策略：
+ *  - 旧文件不存在 → 直接返回
+ *  - rename 失败（目标已存在 / 权限等）→ 忽略，旧文件原位等下次启动
+ */
+export async function migrateLegacyContext(cwd) {
+    const legacy = join(homedir(), '.minimal-agent', 'last-context.json');
+    try {
+        await stat(legacy);
+    }
+    catch {
+        return;
+    }
+    const target = sessionFileFor(cwd);
+    try {
+        await mkdir(dirname(target), { recursive: true });
+        await rename(legacy, target);
+    }
+    catch {
+        // 静默
+    }
+}

package/src/context/snipCompact.js

@@ -0,0 +1,112 @@
+/**
+ * ============================================================
+ *  src/context/snipCompact.ts —— 轻量"砍头"压缩（Path 3）
+ * ------------------------------------------------------------
+ *  对齐 kakadeai 主项目 services/compact/snipCompact.ts 的设计：
+ *  纯规则、零 LLM 调用，直接砍掉最老的 N% 消息，用作 LLM 压缩失败时
+ *  的兜底（"穷人的压缩"）。
+ *
+ *  压缩强度光谱：
+ *    micro  —— 工具结果级别（SHA-1 + 长度截断，每条消息内部）
+ *    snip   —— 对话级别（按比例砍最老消息，无 LLM）   ← 本文件
+ *    auto   —— LLM 全量重写摘要（9 段式模板）
+ *
+ *  设计要点：
+ *    1. system 消息（messages[0]）永远不动
+ *    2. 默认 < 10 条历史不动（除非 force=true）
+ *    3. 砍头时严格保护 tool_call / tool_result 配对：切口落在 tool
+ *       消息上会自动向后微调，避免造成"孤儿 tool"导致 API 400
+ *    4. 替换为一条 user marker 消息，告诉模型"前面有 N 条被自动删除"
+ * ============================================================
+ */
+import { countMessagesTokens } from './tokenCounter.js';
+// ==================== 配置常量 ====================
+const DEFAULT_SNIP_PERCENT = 0.2;
+const DEFAULT_MIN_KEEP = 5;
+const DEFAULT_MAX_SNIP = 50;
+/** 小于这个总长度时除非 force 不动 */
+const DEFAULT_THRESHOLD = 10;
+// ==================== 核心函数 ====================
+/**
+ * 砍掉最老的 N% 消息，用一条 user marker 消息替代。
+ *
+ * 切口保护：如果按比例算出的切点落在 tool 消息上，会自动向后微调
+ * 直到切点不在 tool 上——避免造成孤儿 tool（其父 assistant.tool_calls
+ * 被砍掉而它自己被保留，OpenAI 协议下 API 会 400 "tool id not found"）。
+ */
+export function snipCompactIfNeeded(messages, options = {}) {
+    const force = options.force ?? false;
+    const snipPercent = options.snipPercent ?? DEFAULT_SNIP_PERCENT;
+    const minKeep = options.minMessagesToKeep ?? DEFAULT_MIN_KEEP;
+    const maxSnip = options.maxMessagesToSnip ?? DEFAULT_MAX_SNIP;
+    if (messages.length === 0) {
+        return { messages: [], messagesRemoved: 0, tokensFreed: 0 };
+    }
+    // 拆出 system 消息（只可能在 index 0；最多一条）
+    const systemMsg = messages[0].role === 'system' ? messages[0] : null;
+    const rest = systemMsg ? messages.slice(1) : messages.slice();
+    // 阈值检查（< 10 条且非 force → 不动）
+    if (!force && rest.length < DEFAULT_THRESHOLD) {
+        return { messages: messages.slice(), messagesRemoved: 0, tokensFreed: 0 };
+    }
+    // 算应该砍多少条
+    const byPercent = Math.floor(rest.length * snipPercent);
+    const proposedSnipCount = Math.min(byPercent, maxSnip, Math.max(0, rest.length - minKeep));
+    if (proposedSnipCount <= 0) {
+        return { messages: messages.slice(), messagesRemoved: 0, tokensFreed: 0 };
+    }
+    // 切点保护：避免落在 tool 消息上造成孤儿
+    const actualCut = findHeadCutpoint(rest, proposedSnipCount);
+    if (actualCut === 0 || actualCut >= rest.length) {
+        return { messages: messages.slice(), messagesRemoved: 0, tokensFreed: 0 };
+    }
+    const snipped = rest.slice(0, actualCut);
+    const remaining = rest.slice(actualCut);
+    const tokensFreed = countMessagesTokens(snipped);
+    const marker = {
+        role: 'user',
+        content: `[已自动删除最早的 ${actualCut} 条对话以节省 token（约释放 ${tokensFreed.toLocaleString()} tokens）。` +
+            `如需完整历史请用 /new 重启会话或 /compact 触发 LLM 摘要压缩。]`,
+    };
+    return {
+        messages: [...(systemMsg ? [systemMsg] : []), marker, ...remaining],
+        messagesRemoved: actualCut,
+        tokensFreed,
+    };
+}
+/**
+ * 找到一个安全的"砍头切点"：从 proposedCut 开始向后扫描，
+ * 跳过所有会留下孤儿 tool 的位置。
+ *
+ * 算法（与 compact.ts 的 findTailWithCompleteToolChains 互补）：
+ *   1. 扫描 messages[cut:]（即"保留区"），收集 assistant.tool_calls.id
+ *      到 knownIds Set 中（向前扫描，每遇到 assistant 就累加）
+ *   2. 遇到 tool 消息且其 tool_call_id 不在 knownIds → 这是孤儿
+ *      → 把切点向后推一位（即 cut++）并重新扫描
+ *   3. 直到保留区中所有 tool 消息都有父级，或 cut 越界
+ *
+ * 复杂度：O(N²) 最坏（N 个消息），实际 N 通常 < 100、扩展次数 < 5 → 极快
+ */
+export function findHeadCutpoint(messages, proposedCut) {
+    let cut = Math.max(0, Math.min(proposedCut, messages.length));
+    // 反复扫描直到切点稳定
+    while (cut < messages.length) {
+        const knownIds = new Set();
+        let foundOrphan = false;
+        for (let i = cut; i < messages.length; i++) {
+            const msg = messages[i];
+            if (msg.role === 'assistant' && msg.tool_calls) {
+                for (const tc of msg.tool_calls)
+                    knownIds.add(tc.id);
+            }
+            else if (msg.role === 'tool' && !knownIds.has(msg.tool_call_id)) {
+                foundOrphan = true;
+                break;
+            }
+        }
+        if (!foundOrphan)
+            return cut;
+        cut++;
+    }
+    return cut;
+}

package/src/context/tokenCounter.js

@@ -0,0 +1,66 @@
+/**
+ * ============================================================
+ *  src/context/tokenCounter.ts —— Token 估算
+ * ------------------------------------------------------------
+ *  我们用一个**粗略估算**（chars / 4）作为 token 数。
+ *
+ *  为何不用 tiktoken / @anthropic-ai/tokenizer？
+ *    - 真实 tokenizer 对每个模型都不同，且会增加几 MB 的依赖
+ *    - 我们只用估算来决定"要不要触发压缩"，误差 ±20% 完全可以接受
+ *    - chars/4 对英文很准；对中文偏低（中文 1 char ≈ 1 token）
+ *
+ *  如何换成精确版？
+ *    1. npm i tiktoken
+ *    2. 把 countTokens() 实现替换为 tiktoken 调用
+ *    3. 不改外部签名即可
+ * ============================================================
+ */
+/**
+ * 粗略估算一段文本的 token 数。
+ *
+ * 经验值：
+ *   - GPT 系列英文: 1 token ≈ 4 chars
+ *   - 中文：1 char ≈ 1~1.5 tokens（因此本函数对中文低估）
+ *
+ * 我们选保守的 chars/4 + 中文加权：
+ *   ASCII 部分按 /4，非 ASCII（主要是中文）按 *1.0。
+ */
+export function countTextTokens(text) {
+    if (!text)
+        return 0;
+    let asciiChars = 0;
+    let nonAsciiChars = 0;
+    for (let i = 0; i < text.length; i++) {
+        const code = text.charCodeAt(i);
+        if (code < 128)
+            asciiChars++;
+        else
+            nonAsciiChars++;
+    }
+    return Math.ceil(asciiChars / 4) + nonAsciiChars;
+}
+/** 估算整段历史的 token 数（包含 role / 工具调用结构的开销） */
+export function countMessagesTokens(messages) {
+    let total = 0;
+    for (const m of messages) {
+        // 每条消息至少有 ~4 token 的固定开销（role + 边界标记）
+        total += 4;
+        if (typeof m.content === 'string') {
+            total += countTextTokens(m.content);
+        }
+        else if (m.content === null) {
+            // assistant 的 content 可以是 null（只有 tool_calls 时）
+        }
+        if (m.role === 'assistant' && m.tool_calls) {
+            for (const tc of m.tool_calls) {
+                total += 8; // tool_call 结构开销
+                total += countTextTokens(tc.function.name);
+                total += countTextTokens(tc.function.arguments);
+            }
+        }
+        if (m.role === 'tool') {
+            total += countTextTokens(m.tool_call_id);
+        }
+    }
+    return total;
+}

package/src/llm/client.js

@@ -0,0 +1,182 @@
+/**
+ * ============================================================
+ *  src/llm/client.ts —— OpenAI 兼容 LLM 客户端（流式）
+ * ------------------------------------------------------------
+ *  这个文件做一件事：把"消息历史 + 可用工具"发给 LLM，把"流式响应"逐 chunk
+ *  yield 回上层。它是整个 agent 系统里唯一会 fetch() 远端 API 的地方。
+ *
+ *  我们用 OpenAI 的 Chat Completions 协议，因为：
+ *    - DeepSeek、月之暗面、智谱、火山、OpenRouter 都按它兼容
+ *    - 协议简单：POST 一个 JSON，回 SSE
+ *
+ *  SSE（Server-Sent Events）是什么？
+ *    一种很简单的流式协议：服务器逐行返回 "data: <json>\n\n"，
+ *    最后用 "data: [DONE]\n\n" 表示结束。
+ *
+ *  本文件不依赖任何 npm 包（fetch 是 Bun/Node 20+ 内置）。
+ * ============================================================
+ */
+/**
+ * 调用 LLM 并以流的形式 yield 事件。
+ *
+ * @param provider 选好的 provider（含 baseURL / apiKey / model）
+ * @param messages 完整的对话历史
+ * @param tools    工具列表（每个工具需要带 jsonSchema 才能给 LLM）
+ * @param signal   AbortSignal，UI 按 Ctrl+C 时中断
+ *
+ * @yield LlmStreamEvent: text_delta / tool_call_delta / done
+ *
+ * 用法示例：
+ * ```
+ * for await (const ev of chat({ provider, messages, tools })) {
+ *   if (ev.type === 'text_delta') process.stdout.write(ev.delta);
+ * }
+ * ```
+ */
+export async function* chat(args) {
+    const { provider, messages, tools, signal } = args;
+    // 1. 把 Tool 数组转成 OpenAI 协议的 tools 字段
+    const openaiTools = tools.map((t) => ({
+        type: 'function',
+        function: {
+            name: t.name,
+            description: typeof t.description === 'function' ? t.description() : t.description,
+            parameters: t.parameters,
+        },
+    }));
+    // 2. 构造请求体
+    const body = {
+        model: provider.model,
+        messages,
+        tools: openaiTools.length > 0 ? openaiTools : undefined,
+        stream: true,
+        // tool_choice: 'auto' 是默认值，可不写；某些 provider 必须显式
+        tool_choice: openaiTools.length > 0 ? 'auto' : undefined,
+    };
+    // 3. 发请求（fetch 在 Bun/Node 20+ 内置）
+    const url = `${provider.baseURL.replace(/\/$/, '')}/chat/completions`;
+    const resp = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${provider.apiKey}`,
+        },
+        body: JSON.stringify(body),
+        signal,
+    });
+    // 4. 错误处理：把 HTTP 错误尽量翻译成可读消息
+    if (!resp.ok) {
+        const errText = await resp.text().catch(() => '');
+        throw new Error(`LLM 请求失败 [${resp.status} ${resp.statusText}]：${errText.slice(0, 500)}`);
+    }
+    if (!resp.body) {
+        throw new Error('LLM 响应没有 body（provider 可能不支持流式？）');
+    }
+    // 5. SSE 解析：把 ReadableStream 切成一行行 "data: ..." 然后 JSON.parse
+    const reader = resp.body.getReader();
+    const decoder = new TextDecoder();
+    /** 临时缓冲：HTTP chunk 不一定按行切，要自己拼 */
+    let buffer = '';
+    /** 累积的 stop_reason，最后 yield done 时用 */
+    let stopReason = 'unknown';
+    try {
+        while (true) {
+            // 每次 read 前检查 abort：用户按 ESC/Ctrl+C 时 signal.aborted 为 true。
+            // 这样即使 fetch 还没完成，loop 也能及时退出而不是一直等到网络超时。
+            if (signal?.aborted) {
+                yield { type: 'done', stopReason: 'aborted' };
+                return;
+            }
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            // 每个 chunk 处理完后也检查 abort，让快速连按能及时退出。
+            if (signal?.aborted) {
+                yield { type: 'done', stopReason: 'aborted' };
+                return;
+            }
+            buffer += decoder.decode(value, { stream: true });
+            // SSE 用 "\n\n" 分事件，按行拆 buffer
+            let lineEnd;
+            while ((lineEnd = buffer.indexOf('\n')) !== -1) {
+                const line = buffer.slice(0, lineEnd).trim();
+                buffer = buffer.slice(lineEnd + 1);
+                if (!line || !line.startsWith('data:'))
+                    continue;
+                const dataStr = line.slice(5).trim(); // 去掉 "data:" 前缀
+                if (dataStr === '[DONE]') {
+                    // 流结束标记
+                    yield { type: 'done', stopReason };
+                    return;
+                }
+                // 解析一个 chunk JSON
+                let chunk;
+                try {
+                    chunk = JSON.parse(dataStr);
+                }
+                catch {
+                    // 罕见：某些 provider 会发空行或心跳，忽略
+                    continue;
+                }
+                const delta = chunk.choices?.[0]?.delta;
+                const finish = chunk.choices?.[0]?.finish_reason;
+                if (finish) {
+                    stopReason =
+                        finish === 'stop' || finish === 'tool_calls' || finish === 'length'
+                            ? finish
+                            : 'unknown';
+                }
+                if (!delta)
+                    continue;
+                // 5a. 文本增量
+                //   注意：MiniMax 等模型默认会把 <think>...</think> 标签直接放在
+                //   content 字段里 —— 我们原样累积，不剥离，确保下一轮工具调用时
+                //   思维链完整回传。
+                if (typeof delta.content === 'string' && delta.content.length > 0) {
+                    yield { type: 'text_delta', delta: delta.content };
+                }
+                // 5b. tool_calls 增量（OpenAI 协议下 tool_calls 也是分片的）
+                if (Array.isArray(delta.tool_calls)) {
+                    for (const tc of delta.tool_calls) {
+                        yield {
+                            type: 'tool_call_delta',
+                            index: tc.index ?? 0,
+                            id: tc.id,
+                            name: tc.function?.name,
+                            argumentsDelta: tc.function?.arguments,
+                        };
+                    }
+                }
+                // 5c. 思维链增量（DeepSeek-R1 / MiniMax reasoning_split / OpenRouter）
+                //   三种字段名都见过：reasoning_content / reasoning / reasoning_details
+                //   reasoning_details 是数组，每片是个对象；其它两个是字符串增量。
+                if (typeof delta.reasoning_content === 'string' && delta.reasoning_content.length > 0) {
+                    yield {
+                        type: 'reasoning_delta',
+                        field: 'reasoning_content',
+                        delta: delta.reasoning_content,
+                    };
+                }
+                if (typeof delta.reasoning === 'string' && delta.reasoning.length > 0) {
+                    yield {
+                        type: 'reasoning_delta',
+                        field: 'reasoning',
+                        delta: delta.reasoning,
+                    };
+                }
+                if (Array.isArray(delta.reasoning_details) && delta.reasoning_details.length > 0) {
+                    yield {
+                        type: 'reasoning_delta',
+                        field: 'reasoning_details',
+                        items: delta.reasoning_details,
+                    };
+                }
+            }
+        }
+        // 如果流没显式发 [DONE]，也补一个 done
+        yield { type: 'done', stopReason };
+    }
+    finally {
+        reader.releaseLock?.();
+    }
+}