minimal-agent 0.5.4 → 0.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "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/src/context/archive.js

@@ -0,0 +1,117 @@
+/**
+ * ============================================================
+ *  src/context/archive.ts —— /new 自动归档历史对话
+ * ------------------------------------------------------------
+ *  做的事：
+ *    `/new` 清空上下文前，先把当前对话历史落盘到 archive 目录，
+ *    供后续 `/list-archive`、`/restore <id>` 查看 / 找回。
+ *
+ *  文件路径：
+ *    <MINIMAL_AGENT_HOME ?? ~>/.minimal-agent/archive/<cwd-hash>/<ISO-timestamp>.json
+ *    - cwd-hash：当前工作目录 sha1 前 12 位（避免不同项目 archive 串台）
+ *    - timestamp：new Date().toISOString().replace(/:/g, '-')（Windows 不允许冒号）
+ *
+ *  存储格式：
+ *    { updatedAt: number; messages: Message[] }
+ *
+ *  抉择：
+ *    - 仅含 system 消息（空对话）跳过写入，返回空字符串
+ *    - 失败由调用方 try/catch 吞掉，本模块不做 stderr（保持纯函数语义）
+ *    - 损坏文件在 listArchives 中静默 skip
+ *    - 通过 MINIMAL_AGENT_HOME 环境变量让测试切到临时目录，避免污染真实 ~/.minimal-agent
+ * ============================================================
+ */
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { getWorkingDir } from '../bootstrap/workingDir.js';
+/** 解析 archive 根目录，支持 MINIMAL_AGENT_HOME 测试覆盖 */
+function agentHome() {
+    return process.env.MINIMAL_AGENT_HOME ?? homedir();
+}
+function archiveDir(cwd) {
+    const hash = createHash('sha1').update(cwd).digest('hex').slice(0, 12);
+    return join(agentHome(), '.minimal-agent', 'archive', hash);
+}
+/**
+ * 归档当前 messages 到 archive 目录。
+ *
+ * @returns archive id（成功）或空字符串（无内容跳过）
+ *
+ * 行为：
+ *  - messages 为空 / 仅含 system role → 跳过，返回 ''
+ *  - 写入失败抛错（调用方负责吞）
+ */
+export async function archiveCurrent(messages) {
+    const nonSystem = messages.filter((m) => m.role !== 'system');
+    if (nonSystem.length === 0)
+        return '';
+    const dir = archiveDir(getWorkingDir());
+    await mkdir(dir, { recursive: true });
+    const id = new Date().toISOString().replace(/:/g, '-');
+    const path = join(dir, `${id}.json`);
+    await writeFile(path, JSON.stringify({ updatedAt: Date.now(), messages }), 'utf8');
+    return id;
+}
+/**
+ * 列出当前 cwd 下所有归档，最新优先（按文件 mtime 倒序）。
+ *
+ * 损坏 / 无法解析的文件会被静默跳过——不影响其它条目展示。
+ * 目录不存在视作空列表。
+ */
+export async function listArchives() {
+    const dir = archiveDir(getWorkingDir());
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        const id = name.slice(0, -'.json'.length);
+        const fpath = join(dir, name);
+        try {
+            const st = await stat(fpath);
+            const raw = await readFile(fpath, 'utf8');
+            const data = JSON.parse(raw);
+            if (!Array.isArray(data.messages))
+                continue;
+            const firstUser = data.messages.find((m) => m.role === 'user');
+            const preview = firstUser && typeof firstUser.content === 'string'
+                ? firstUser.content.replace(/\s+/g, ' ').slice(0, 80)
+                : '';
+            entries.push({
+                id,
+                updatedAt: st.mtimeMs,
+                msgCount: data.messages.length,
+                firstUserPreview: preview,
+            });
+        }
+        catch {
+            // 损坏文件静默 skip
+        }
+    }
+    return entries.sort((a, b) => b.updatedAt - a.updatedAt);
+}
+/**
+ * 按 id 恢复归档。
+ *
+ * @returns messages 数组（成功）；找不到 / 损坏 / messages 非数组 → null
+ */
+export async function restoreArchive(id) {
+    const dir = archiveDir(getWorkingDir());
+    const path = join(dir, `${id}.json`);
+    try {
+        const raw = await readFile(path, 'utf8');
+        const data = JSON.parse(raw);
+        return Array.isArray(data.messages) ? data.messages : null;
+    }
+    catch {
+        return null;
+    }
+}

package/src/context/persistContext.js

@@ -25,6 +25,7 @@
 import { mkdir, readFile, readdir, rmdir, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { getWorkingDir } from '../bootstrap/workingDir.js';
+import { archiveCurrent } from './archive.js';
 import { sessionFileFor } from './sessionPath.js';
 /** 上下文文件路径（按工作目录隔离，可用环境变量覆盖） */
 export function getContextPath() {
@@ -76,6 +77,21 @@ export async function saveContext(messages, file) {
  */
 export async function clearContext(file) {
     const target = file ?? getContextPath();
+    // 归档当前历史（仅含 system 的空对话会跳过）；失败不阻塞 clear
+    // 显式传 file（HTTP 模式 / 测试覆盖路径）或 MINIMAL_AGENT_CONTEXT_FILE 激活时
+    // 跳过 archive：这两种语义下 caller 自管路径，不应污染默认 archive 目录
+    const skipArchive = file !== undefined || !!process.env.MINIMAL_AGENT_CONTEXT_FILE;
+    if (!skipArchive) {
+        try {
+            const current = await loadContext(target);
+            if (current && current.length > 0) {
+                await archiveCurrent(current);
+            }
+        }
+        catch (e) {
+            process.stderr.write(`[minimal-agent] archive 失败（继续 clear）：${e.message}\n`);
+        }
+    }
     try {
         await unlink(target);
     }

package/src/context/sessionPath.js

@@ -6,10 +6,16 @@
  *    把当前工作目录编码为 ~/.minimal-agent/sessions/<encoded>.json
  *    的文件名，让不同项目目录的对话历史互不覆盖。
  *
- *  命名规则：
- *    <sanitized-path>-<6-hex-hash>.json
+ *  命名规则（v2 加 sessionId 后）：
+ *    <sanitized-path>-<6-hex-hash>--<sessionId>.json
  *      sanitized：路径归一化后只保留 [a-z0-9-]，最长 80 字符
  *      hash    ：原始路径 sha1 前 6 位，防 sanitize 后碰撞
+ *      sessionId：v2 多 session 支持；默认 'default'
+ *
+ *    向后兼容：sessionId='default' 时，新文件名 `<sanitized>-<hash>--default.json`
+ *    与旧文件名 `<sanitized>-<hash>.json` 都可能存在。resolveSessionFile()
+ *    优先返新路径，新路径不存在但旧路径存在时回退到旧路径，保证老用户的
+ *    last-context 无缝继承。
  *
  *  迁移：
  *    旧版 ~/.minimal-agent/last-context.json 启动时一次性 rename 到
@@ -20,8 +26,29 @@ 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 DEFAULT_SESSION_ID = 'default';
+/**
+ * 把 cwd + sessionId 编码成会话文件绝对路径。
+ *
+ * @param cwd 工作目录
+ * @param sessionId 多 session 支持的 id；缺省 'default'
+ *
+ * 注意：'default' 调用走新格式 `<base>--default.json`。如果磁盘上只有
+ * 旧格式 `<base>.json`（v1 历史文件），需要用 resolveSessionFile()
+ * 拿到实际存在的路径用于 load。
+ */
+export function sessionFileFor(cwd, sessionId = DEFAULT_SESSION_ID) {
+    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}--${sessionId}.json`);
+}
+/** 旧格式（v1，不带 `--<id>` 后缀）—— 仅 'default' session 可能存在 */
+function legacySessionFileFor(cwd) {
     const normalized = resolve(cwd).replace(/\\/g, '/').toLowerCase();
     const sanitized = normalized
         .replace(/:/g, '')
@@ -31,6 +58,34 @@ export function sessionFileFor(cwd) {
     const hash = createHash('sha1').update(normalized).digest('hex').slice(0, 6);
     return join(homedir(), '.minimal-agent', 'sessions', `${sanitized}-${hash}.json`);
 }
+/**
+ * 解析 cwd + sessionId 对应的实际存在的会话文件路径。
+ *
+ *  - 新格式（带 `--<id>`）存在 → 返回新路径
+ *  - 仅 sessionId='default' 且新路径不存在但旧路径（不带 `--`）存在 → 返回旧路径
+ *  - 都不存在 → 返回新路径（让调用方按新格式 create）
+ */
+export async function resolveSessionFile(cwd, sessionId = DEFAULT_SESSION_ID) {
+    const fresh = sessionFileFor(cwd, sessionId);
+    try {
+        await stat(fresh);
+        return fresh;
+    }
+    catch {
+        // 新路径不存在
+    }
+    if (sessionId === DEFAULT_SESSION_ID) {
+        const legacy = legacySessionFileFor(cwd);
+        try {
+            await stat(legacy);
+            return legacy;
+        }
+        catch {
+            // 旧路径也不存在
+        }
+    }
+    return fresh;
+}
 /**
  * 一次性把旧版 ~/.minimal-agent/last-context.json 迁到当前 cwd 对应的
  * 会话文件。

package/src/context/sessionRegistry.js

@@ -0,0 +1,104 @@
+/**
+ * ============================================================
+ *  src/context/sessionRegistry.ts —— 同 cwd 多 session 注册表
+ * ------------------------------------------------------------
+ *  做的事：
+ *    一个工作目录下可以有多个并行 session（id = 任意字符串），
+ *    每次只激活一个。active 信息存 ~/.minimal-agent/active-sessions.json，
+ *    键是 cwd 的 sha1[:12]，值是当前激活的 session id 字符串。
+ *
+ *  文件路径：
+ *    <MINIMAL_AGENT_HOME ?? ~>/.minimal-agent/active-sessions.json
+ *    <MINIMAL_AGENT_HOME ?? ~>/.minimal-agent/sessions/<cwd-hash>--<id>.json
+ *      （新格式；旧格式 <cwd-hash>.json 视作 id='default' 兼容）
+ *
+ *  抉择：
+ *    - active 文件 atomic write（写 .tmp + rename）—— 防止跨进程并发写时部分写入
+ *    - sessionId 为字符串，'default' 是约定的默认值（无 active 时返回它）
+ *    - listSessions 同时扫新旧格式，保证迁移期不丢
+ * ============================================================
+ */
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, readdir, rename, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** 解析根目录，支持 MINIMAL_AGENT_HOME 测试覆盖 */
+function agentHome() {
+    return process.env.MINIMAL_AGENT_HOME ?? homedir();
+}
+function agentDir() {
+    return join(agentHome(), '.minimal-agent');
+}
+function activeFilePath() {
+    return join(agentDir(), 'active-sessions.json');
+}
+function sessionsDirPath() {
+    return join(agentDir(), 'sessions');
+}
+function cwdHash(cwd) {
+    return createHash('sha1').update(cwd).digest('hex').slice(0, 12);
+}
+async function loadActiveMap() {
+    try {
+        const raw = await readFile(activeFilePath(), 'utf8');
+        const data = JSON.parse(raw);
+        if (data && typeof data === 'object' && !Array.isArray(data)) {
+            return data;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * 获取当前 cwd 的激活 session id。
+ * 无记录 → 返回 'default'。
+ */
+export async function getActiveSession(cwd) {
+    const map = await loadActiveMap();
+    return map[cwdHash(cwd)] ?? 'default';
+}
+/**
+ * 设置当前 cwd 的激活 session id。
+ *
+ * 写入策略：先写 <target>.tmp，再原子 rename 到 target；
+ * 即使被中断也只会留临时文件，不破坏 target。
+ */
+export async function setActiveSession(cwd, sessionId) {
+    const map = await loadActiveMap();
+    map[cwdHash(cwd)] = sessionId;
+    await mkdir(agentDir(), { recursive: true });
+    const target = activeFilePath();
+    const tmp = `${target}.tmp`;
+    await writeFile(tmp, JSON.stringify(map), 'utf8');
+    await rename(tmp, target);
+}
+/**
+ * 列出当前 cwd 下所有 session id（含 'default'）。
+ *
+ * 扫描规则：
+ *  - 新格式 `<hash>--<id>.json` → 提取 id
+ *  - 旧格式 `<hash>.json` → 视作 'default'
+ *  - 都没有 → 返回 ['default']（让 UI 默认能 list 出至少一项）
+ */
+export async function listSessions(cwd) {
+    const dir = sessionsDirPath();
+    const hash = cwdHash(cwd);
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return ['default'];
+    }
+    const prefix = `${hash}--`;
+    const ids = names
+        .filter((n) => n.startsWith(prefix) && n.endsWith('.json'))
+        .map((n) => n.slice(prefix.length, -'.json'.length));
+    const legacy = `${hash}.json`;
+    if (names.includes(legacy) && !ids.includes('default')) {
+        ids.unshift('default');
+    }
+    return ids.length > 0 ? ids : ['default'];
+}

package/src/loop.js

@@ -15,18 +15,23 @@
  *    a. 自动压缩检查（防止 context 撑爆）
  *    b. 调 LLM，把流式响应组装成完整的 assistant message
  *    c. 如果 assistant 不调工具 → 结束，return
- *    d. 否则按顺序执行每个工具调用，把 tool 消息追加到历史
+ *    d. 否则并行执行所有工具调用（OpenAI 协议要求 tool 消息按 tool_calls 顺序回填）
  *    e. 进入下一轮（让模型看到 tool_result 后继续推理）
  *
  *  失控保护：maxTurns（默认 50）。
  *  中断支持：AbortSignal 透传到 chat() 和 tool.call()。
+ *
+ *  v0.5.3 新增"工作过程显示"事件：
+ *    - stage_change：thinking / streaming / tool_executing / compacting
+ *    - reasoning：思维链流式增量（仅字符串型 field）
+ *    - token_tick：200ms 节流，UI 用来显示 token / 耗时心跳
  * ============================================================
  */
 import { autoCompactIfNeeded } from './context/compact.js';
 import { microCompact, incrementTurn, expireOldEntries } from './context/microCompactLite.js';
 import { isPromptTooLongError, reactiveCompactIfApplicable, } from './context/reactiveCompact.js';
-import { chat } from './llm/client.js';
-import { ALL_TOOLS, executeTool } from './tools/index.js';
+import { chat as defaultChat } from './llm/client.js';
+import { ALL_TOOLS, executeTool as defaultExecuteTool } from './tools/index.js';
 /**
  * 执行一次"用户输入 → 模型回答完成"的完整流程。
  *
@@ -35,11 +40,20 @@ import { ALL_TOOLS, executeTool } from './tools/index.js';
 export async function* runQuery(userInput, options) {
     const { provider, history, signal, sessionState } = options;
     const maxTurns = options.maxTurns ?? 50;
-    // 1. 用户消息入栈
-    history.push({ role: 'user', content: userInput });
+    // DI fallback：测试可传 stub，生产走真实模块单例
+    const chatFn = options.chat ?? defaultChat;
+    const executeToolFn = options.executeTool ?? defaultExecuteTool;
+    // 1. 用户消息入栈（v2：填 timestamp，让 MessageList 的 turn 边界横线
+    //    能拿到首条 user 的真实时间，否则 fallback Date.now() 会丢失"提交时刻"语义）
+    history.push({ role: 'user', content: userInput, timestamp: Date.now() });
     // 反应式压缩自救：本 runQuery 只允许触发一次，避免压缩失败导致死循环。
     // 配合 reactiveCompact.ts 的 attempted（session 级）双层防爆。
     let reactiveAttempted = false;
+    // token_tick 心跳起点：跨多轮累计估算 token 与耗时
+    const turnStart = Date.now();
+    // v2 工具 step 计数器：跨整次 runQuery 累计每个工具 worker 的派发序号
+    // （每个 worker 启动时 ++）。token_tick yield 时携带 stepN 给 UI 显示 "step N"。
+    let stepN = 0;
     let turn = 0;
     while (turn < maxTurns) {
         turn++;
@@ -50,6 +64,7 @@ export async function* runQuery(userInput, options) {
             history.push({
                 role: 'user',
                 content: '(用户按下了 ESC/Ctrl+C 中断了任务)',
+                timestamp: Date.now(),
             });
             yield { type: 'error', error: '已被用户中断' };
             return;
@@ -59,10 +74,13 @@ export async function* runQuery(userInput, options) {
             const compact = await autoCompactIfNeeded(history, provider);
             if (compact.compacted) {
                 yield { type: 'compact_start' };
+                yield { type: 'stage_change', stage: 'compacting' };
                 // in-place 替换 history（保持调用方持有的引用有效）
                 history.length = 0;
                 history.push(...compact.messages);
                 yield { type: 'compact_done', before: compact.before, after: compact.after };
+                // 压缩完会回到 LLM 调用，stage 退回 thinking
+                yield { type: 'stage_change', stage: 'thinking' };
             }
         }
         catch (e) {
@@ -83,14 +101,24 @@ export async function* runQuery(userInput, options) {
         let reasoningContent = '';
         let reasoningString = '';
         const reasoningDetails = [];
+        /** 首个 text_delta 时切到 streaming，再来不重复 yield */
+        let stageStreamingYielded = false;
+        /** 200ms token_tick 节流游标 */
+        let lastTick = Date.now();
+        // 进入 LLM 流前：等首 token / reasoning，本质是 thinking
+        yield { type: 'stage_change', stage: 'thinking' };
         try {
-            for await (const ev of chat({
+            for await (const ev of chatFn({
                 provider,
                 messages: history,
                 tools: ALL_TOOLS,
                 signal,
             })) {
                 if (ev.type === 'text_delta') {
+                    if (!stageStreamingYielded) {
+                        stageStreamingYielded = true;
+                        yield { type: 'stage_change', stage: 'streaming' };
+                    }
                     assistantText += ev.delta;
                     yield { type: 'text', delta: ev.delta };
                 }
@@ -100,11 +128,14 @@ export async function* runQuery(userInput, options) {
                 else if (ev.type === 'reasoning_delta') {
                     if (ev.field === 'reasoning_content' && ev.delta) {
                         reasoningContent += ev.delta;
+                        yield { type: 'reasoning', delta: ev.delta };
                     }
                     else if (ev.field === 'reasoning' && ev.delta) {
                         reasoningString += ev.delta;
+                        yield { type: 'reasoning', delta: ev.delta };
                     }
                     else if (ev.field === 'reasoning_details' && ev.items) {
+                        // reasoning_details 是结构化数组，没有 delta 字符串，跳过 yield
                         reasoningDetails.push(...ev.items);
                     }
                     if (ev.delta) {
@@ -112,6 +143,20 @@ export async function* runQuery(userInput, options) {
                     }
                 }
                 // ev.type === 'done' 时无需处理：循环自然结束
+                // 每 chunk 同步检查 200ms 节流，避免起 setInterval 与 generator yield 时机冲突
+                const now = Date.now();
+                if (now - lastTick >= 200) {
+                    lastTick = now;
+                    const usedThisTurn = Math.ceil(assistantText.length / 4) +
+                        Math.ceil(reasoningContent.length / 4) +
+                        Math.ceil(reasoningString.length / 4);
+                    yield {
+                        type: 'token_tick',
+                        usedThisTurn,
+                        elapsedMs: now - turnStart,
+                        stepN,
+                    };
+                }
             }
         }
         catch (e) {
@@ -120,6 +165,7 @@ export async function* runQuery(userInput, options) {
                 history.push({
                     role: 'user',
                     content: '(用户按下了 ESC/Ctrl+C 中断了任务)',
+                    timestamp: Date.now(),
                 });
                 yield { type: 'interrupted' };
                 return;
@@ -130,6 +176,7 @@ export async function* runQuery(userInput, options) {
             if (isPromptTooLongError(e) && !reactiveAttempted) {
                 reactiveAttempted = true;
                 yield { type: 'compact_start' };
+                yield { type: 'stage_change', stage: 'compacting' };
                 const result = await reactiveCompactIfApplicable(history, provider, e, sessionState?.reactive);
                 if (result.recovered) {
                     history.length = 0;
@@ -139,6 +186,8 @@ export async function* runQuery(userInput, options) {
                         before: result.before ?? 0,
                         after: result.after ?? 0,
                     };
+                    // 压缩完回到 LLM 调用
+                    yield { type: 'stage_change', stage: 'thinking' };
                     turn--; // 不消耗 turn 配额，本轮重新走
                     continue;
                 }
@@ -154,6 +203,7 @@ export async function* runQuery(userInput, options) {
             ...(reasoningContent ? { reasoning_content: reasoningContent } : {}),
             ...(reasoningString ? { reasoning: reasoningString } : {}),
             ...(reasoningDetails.length > 0 ? { reasoning_details: reasoningDetails } : {}),
+            timestamp: Date.now(),
         };
         history.push(assistantMsg);
         yield { type: 'assistant_message', message: assistantMsg };
@@ -162,41 +212,116 @@ export async function* runQuery(userInput, options) {
             yield { type: 'turn_done' };
             return;
         }
-        // 5. 顺序执行每个工具
-        for (const tc of toolCallsByIndex) {
-            if (signal?.aborted) {
-                // 中断标记帮助模型理解上下文：为什么输出被截断，用户可以重新输入
+        // 5. 并行执行所有工具
+        //
+        // 设计：用 Promise.allSettled 启动 N 个 worker，配合一个简易事件队列
+        // （queue + signalNew）把多个 worker 的 tool_start / tool_end 事件按
+        // 真实完成顺序交错 yield 给 UI；但 history 里的 tool 消息严格按
+        // toolCallsByIndex 索引顺序 push（OpenAI 协议要求 tool 消息和上一条
+        // assistant 的 tool_calls 一一对应）。
+        yield { type: 'stage_change', stage: 'tool_executing' };
+        const queue = [];
+        let signalNew = null;
+        const enqueue = (ev) => {
+            queue.push(ev);
+            signalNew?.();
+            signalNew = null;
+        };
+        const workers = toolCallsByIndex.map(async (tc) => {
+            // 每个 worker 启动时累加 step 序号；token_tick 携带它给 UI 显示进度感
+            stepN++;
+            enqueue({
+                type: 'tool_start',
+                toolCallId: tc.id,
+                toolName: tc.function.name,
+                argsPreview: previewArgs(tc.function.arguments),
+                argsFriendly: friendlyToolDescription(tc.function.name, tc.function.arguments),
+            });
+            try {
+                const result = await executeToolFn(tc.function.name, tc.function.arguments, signal);
+                enqueue({
+                    type: 'tool_end',
+                    toolCallId: tc.id,
+                    toolName: tc.function.name,
+                    ok: result.ok,
+                    content: result.ok ? result.content : `Error: ${result.error}`,
+                });
+                return { tc, result };
+            }
+            catch (e) {
+                if (e.name === 'AbortError') {
+                    enqueue({
+                        type: 'tool_end',
+                        toolCallId: tc.id,
+                        toolName: tc.function.name,
+                        ok: false,
+                        content: '(已中断)',
+                    });
+                    return { tc, result: { ok: false, error: 'aborted' } };
+                }
+                const msg = e.message;
+                enqueue({
+                    type: 'tool_end',
+                    toolCallId: tc.id,
+                    toolName: tc.function.name,
+                    ok: false,
+                    content: msg,
+                });
+                return { tc, result: { ok: false, error: msg } };
+            }
+        });
+        const allDone = Promise.allSettled(workers);
+        let finished = false;
+        allDone.then(() => {
+            finished = true;
+            signalNew?.();
+            signalNew = null;
+        });
+        while (!finished || queue.length > 0) {
+            while (queue.length > 0)
+                yield queue.shift();
+            if (finished)
+                break;
+            await new Promise((r) => {
+                signalNew = r;
+            });
+        }
+        // 严格按 toolCallsByIndex 顺序 push tool 消息进 history（OpenAI 协议要求）
+        const settled = await allDone;
+        let anyAborted = false;
+        for (let i = 0; i < toolCallsByIndex.length; i++) {
+            const tc = toolCallsByIndex[i];
+            const r = settled[i];
+            if (r.status === 'rejected') {
+                // 理论上 worker 已经 catch 了所有异常，这里只是防御
+                const errMsg = r.reason?.message ?? 'unknown';
                 history.push({
-                    role: 'user',
-                    content: '(用户按下了 ESC/Ctrl+C 中断了任务)',
+                    role: 'tool',
+                    tool_call_id: tc.id,
+                    content: `Error: ${errMsg}`,
+                    timestamp: Date.now(),
                 });
-                yield { type: 'error', error: '已被用户中断' };
-                return;
+                continue;
             }
-            const argsPreview = previewArgs(tc.function.arguments);
-            yield {
-                type: 'tool_start',
-                toolName: tc.function.name,
-                toolCallId: tc.id,
-                argsPreview,
-            };
-            const result = await executeTool(tc.function.name, tc.function.arguments, signal);
-            // 工具结果：失败保留错误信息，成功经微压缩后保留
+            const { result } = r.value;
+            if (!result.ok && result.error === 'aborted')
+                anyAborted = true;
             const rawContent = result.ok ? result.content : `Error: ${result.error}`;
-            const content = microCompact(tc.function.name, rawContent, sessionState?.microCompact);
-            // 工具结果作为 tool 消息回填
+            // 微压缩仅对成功结果走（失败结果通常很短，不需要压缩）
+            const content = result.ok
+                ? microCompact(tc.function.name, rawContent, sessionState?.microCompact)
+                : rawContent;
             history.push({
                 role: 'tool',
                 content,
                 tool_call_id: tc.id,
+                timestamp: Date.now(),
             });
-            yield {
-                type: 'tool_end',
-                toolName: tc.function.name,
-                toolCallId: tc.id,
-                ok: result.ok,
-                content,
-            };
+        }
+        if (anyAborted || signal?.aborted) {
+            // 任一工具抛 AbortError 时，外层 yield interrupted 并 return
+            yield { type: 'interrupted' };
+            return;
         }
         // 6. 继续 while 让模型看到 tool_result 后继续推理
     }
@@ -231,3 +356,47 @@ function previewArgs(rawJson) {
         return oneLine;
     return oneLine.slice(0, 60) + '...';
 }
+/**
+ * 把工具名 + raw arguments JSON 转换成人话描述。
+ * UI 优先用这个显示在 spinner 行（如 "Reading src/foo.ts"）。
+ * 已知工具走 switch；未知工具或 JSON parse 失败 fallback 到 `${toolName}(...)`。
+ */
+function friendlyToolDescription(toolName, rawArgsJson) {
+    let args = {};
+    try {
+        args = JSON.parse(rawArgsJson) ?? {};
+    }
+    catch {
+        return `${toolName}(...)`;
+    }
+    const truncate = (s, n) => {
+        if (typeof s !== 'string')
+            return '';
+        return s.length > n ? s.slice(0, n) + '…' : s;
+    };
+    switch (toolName) {
+        case 'Read': return `Reading ${truncate(args.file_path, 60)}`;
+        case 'Edit': return `Editing ${truncate(args.file_path, 60)}`;
+        case 'Write': return `Writing ${truncate(args.file_path, 60)}`;
+        case 'Bash': return `Running \`${truncate(args.command, 40)}\``;
+        case 'Grep': {
+            const p = truncate(args.pattern, 30);
+            const g = typeof args.glob === 'string' && args.glob.length > 0 ? ` in ${truncate(args.glob, 25)}` : '';
+            return `Searching \`${p}\`${g}`;
+        }
+        case 'Glob': return `Globbing \`${truncate(args.pattern, 50)}\``;
+        case 'WebFetch':
+        case 'WebBrowser': {
+            try {
+                return `Fetching ${new URL(String(args.url)).host}`;
+            }
+            catch {
+                return `Fetching ...`;
+            }
+        }
+        case 'WebSearch': return `Searching \`${truncate(args.query, 50)}\``;
+        default: return `${toolName}(...)`;
+    }
+}
+// 导出供测试用（friendlyToolDescription 是 module-private 纯函数）
+export { friendlyToolDescription };

package/src/ui/InputBox.js

@@ -20,19 +20,38 @@ import { useRef, useState, useCallback } from 'react';
 import { Box, Text, useApp, useInput } from 'ink';
 import { useTextBuffer } from './hooks/useTextBuffer.js';
 import { usePasteHandler } from './hooks/usePasteHandler.js';
+import { useInputHistory } from './hooks/useInputHistory.js';
 export function InputBox({ onSubmit, disabled, onAbort, onClear, onCompact }) {
     const buf = useTextBuffer();
+    const hist = useInputHistory();
     const ctrlCCountRef = useRef(0);
     const ctrlCTimerRef = useRef(null);
     const { exit } = useApp();
     // ✅ 精准刷新计数器：只在必要时触发重渲染
     const [refreshCounter, setRefreshCounter] = useState(0);
-    // ✅ Delete 专用去重：只防止 Windows 双事件，不影响其他键
-    const lastDeleteTime = useRef(0);
-    const DELETE_DEBOUNCE_MS = 20; // 仅 Delete 键用极短防抖
+    // ✅ 精准刷新函数
     const forceRefresh = useCallback(() => {
         setRefreshCounter((c) => c + 1);
     }, []);
+    // ✅ IME 输入缓冲：非 ASCII 字符（CJK/emoji）累积后批量刷新，减少 rerender 频率
+    const imeBufRef = useRef('');
+    const imeTimerRef = useRef(null);
+    const flushImeBuffer = useCallback(() => {
+        if (imeTimerRef.current) {
+            clearTimeout(imeTimerRef.current);
+            imeTimerRef.current = null;
+        }
+        if (imeBufRef.current.length > 0) {
+            buf.insert(imeBufRef.current);
+            imeBufRef.current = '';
+            forceRefresh();
+        }
+    }, [buf, forceRefresh]);
+    // ✅ Ctrl+R 反向搜索模式（null 表示不在搜索）
+    const [searchMode, setSearchMode] = useState(null);
+    // ✅ Delete 专用去重：只防止 Windows 双事件，不影响其他键
+    const lastDeleteTime = useRef(0);
+    const DELETE_DEBOUNCE_MS = 20; // 仅 Delete 键用极短防抖
     // ✅ 粘贴处理 Hook：支持多行粘贴
     // v0.3 设计：Enter 始终发送, Alt+Enter（Mac: Option+Enter）换行, 粘贴期间拦截 Enter
     const { handleInput: handlePasteInput } = usePasteHandler({
@@ -61,15 +80,72 @@ export function InputBox({ onSubmit, disabled, onAbort, onClear, onCompact }) {
             return;
         }
         // pasteResult === 'continue'，继续普通处理
+        // ---- ✅ Ctrl+R 反向搜索模式（独占按键流）----
+        if (searchMode !== null) {
+            // ESC 退出搜索
+            if (key.escape) {
+                setSearchMode(null);
+                return;
+            }
+            // Enter 选中并提交
+            if (key.return) {
+                if (searchMode.hit !== null) {
+                    const text = searchMode.hit;
+                    setSearchMode(null);
+                    buf.clear();
+                    forceRefresh();
+                    hist.push(text);
+                    hist.resetCursor();
+                    onSubmit(text);
+                }
+                else {
+                    setSearchMode(null);
+                }
+                return;
+            }
+            // Backspace 削 query；query 削空了退出
+            if (key.backspace || key.delete) {
+                const nextQuery = searchMode.query.slice(0, -1);
+                if (nextQuery.length === 0) {
+                    setSearchMode(null);
+                    return;
+                }
+                const nextHit = hist.search(nextQuery)[0] ?? null;
+                setSearchMode({ query: nextQuery, hit: nextHit });
+                return;
+            }
+            // Ctrl+C 退出搜索（不退出程序）
+            if (key.ctrl && input === 'c') {
+                setSearchMode(null);
+                return;
+            }
+            // 字面字符（排除控制键）追加到 query
+            if (input && !key.ctrl && !key.meta && !key.return && !key.escape) {
+                const nextQuery = searchMode.query + input;
+                const nextHit = hist.search(nextQuery)[0] ?? null;
+                setSearchMode({ query: nextQuery, hit: nextHit });
+                return;
+            }
+            // 其他按键在搜索模式下静默吞掉
+            return;
+        }
         // ---- ESC ----
         if (key.escape) {
             if (disabled)
                 onAbort();
             return;
         }
+        // ---- ✅ Ctrl+R 进入反向搜索（仅在空 buf + 非 disabled）----
+        if (key.ctrl && input === 'r') {
+            if (!disabled && buf.state.text.length === 0) {
+                setSearchMode({ query: '', hit: null });
+            }
+            return;
+        }
         // ---- Ctrl+C ----
         if (key.ctrl && input === 'c') {
             if (buf.state.text.length > 0) {
+                flushImeBuffer();
                 buf.clear();
                 forceRefresh();
                 return;
@@ -93,9 +169,13 @@ export function InputBox({ onSubmit, disabled, onAbort, onClear, onCompact }) {
         //   - Ctrl+Enter：返回 'continue' → 这里也执行**强制发送**
         //   - 粘贴期间 + Enter：返回 'enter-in-paste' → **忽略**（防误发）
         if (key.return) {
+            flushImeBuffer(); // 先提交残留 CJK 输入
             const text = buf.state.text.trim();
             if (text.length === 0)
                 return;
+            // 入历史（所有非空提交都记，包括 slash 命令；连续重复 hist 内部去重）
+            hist.push(text);
+            hist.resetCursor();
             if (text === '/exit' || text === '/quit')
                 exit();
             else if (text === '/new' || text === '/clear') {
@@ -133,11 +213,29 @@ export function InputBox({ onSubmit, disabled, onAbort, onClear, onCompact }) {
             return;
         }
         if (key.upArrow) {
+            // 首行按 ↑ → 翻历史；中间行 → 正常移动光标
+            if (buf.layout.cursorRow === 0) {
+                const prev = hist.prev();
+                if (prev !== null) {
+                    buf.setText(prev);
+                    forceRefresh();
+                }
+                return;
+            }
             buf.moveUp();
             forceRefresh();
             return;
         }
         if (key.downArrow) {
+            // 末行按 ↓ → 翻历史；中间行 → 正常移动光标
+            const lastRow = buf.layout.lines.length - 1;
+            if (buf.layout.cursorRow >= lastRow) {
+                const nxt = hist.next();
+                // next 返 null 表示走到 "新输入" 位 → 清空缓冲
+                buf.setText(nxt ?? '');
+                forceRefresh();
+                return;
+            }
             buf.moveDown();
             forceRefresh();
             return;
@@ -207,15 +305,54 @@ export function InputBox({ onSubmit, disabled, onAbort, onClear, onCompact }) {
         // Alt+Enter 在多数终端发 \x1b\r：Ink 把 \x1b 剥掉后 input='\r'、key.return=false、
         // key.meta=false，从这里落地。把 \r/\r\n 统一成 \n，textBuffer 才能真切分逻辑行
         // （否则 layout 永远 1 行 → ↑/↓ 失效、输入框不长高，光标只能左右）。
+        //
+        // IME 兼容优化（方案C：启发式过滤 + 延迟刷新）：
+        //   - ASCII 可打印字符 → 立即插入+刷新（英文打字无延迟）
+        //   - 非 ASCII 字符（CJK/emoji）→ 累积到 imeBuf，50ms 后批量刷新
+        //     （合并连续 CJK 输入，减少 Ink 整树 rerender 次数）
         if (input && !key.meta) {
             const normalized = input.replace(/\r\n?/g, '\n');
-            buf.insert(normalized);
-            forceRefresh();
+            if (normalized.length === 0)
+                return;
+            // ASCII 可打印 + 换行：立即处理
+            if (/^[\x20-\x7E\n]+$/.test(normalized)) {
+                flushImeBuffer(); // 先提交残留 CJK
+                buf.insert(normalized);
+                forceRefresh();
+                return;
+            }
+            // 非 ASCII（CJK / emoji / 特殊字符）：累积后延迟刷新
+            imeBufRef.current += normalized;
+            if (!imeTimerRef.current) {
+                imeTimerRef.current = setTimeout(() => {
+                    if (imeBufRef.current.length > 0) {
+                        buf.insert(imeBufRef.current);
+                        imeBufRef.current = '';
+                        forceRefresh();
+                    }
+                    imeTimerRef.current = null;
+                }, 50);
+            }
         }
     });
+    // ✅ 搜索模式下覆盖整个 BufferView，显示 (reverse-i-search)`<query>': <hit>
+    if (searchMode !== null) {
+        return _jsx(ReverseSearchView, { query: searchMode.query, hit: searchMode.hit });
+    }
     // ✅ 传递 refreshCounter 作为 prop（不放入 key）
     return (_jsx(BufferView, { buf: buf, disabled: disabled, refreshCounter: refreshCounter }));
 }
+// ---------- 反向搜索视图 ----------
+function ReverseSearchView({ query, hit, }) {
+    // hit 可能含换行；仅展示首行避免撑爆 InputBox
+    const hitFirstLine = hit !== null ? hit.split('\n', 1)[0] : null;
+    const hitDisplay = hitFirstLine === null
+        ? '<no match>'
+        : hit !== null && hit.includes('\n')
+            ? `${hitFirstLine} …`
+            : hitFirstLine;
+    return (_jsxs(Box, { borderStyle: "round", borderColor: "magenta", paddingX: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { color: "magenta", bold: true, children: '(reverse-i-search)`' }), _jsx(Text, { color: "yellow", children: query }), _jsx(Text, { color: "magenta", bold: true, children: "': " }), _jsx(Text, { color: hitFirstLine === null ? 'gray' : 'white', children: hitDisplay })] }), _jsx(Box, { children: _jsx(Text, { color: "gray", dimColor: true, children: "Enter \u63D0\u4EA4 \u00B7 ESC \u53D6\u6D88 \u00B7 Backspace \u5220\u5B57\u7B26" }) })] }));
+}
 function BufferView({ buf, disabled, refreshCounter }) {
     // ✅ 关键：用 useMemo 依赖 refreshCounter，而非改变 key
     // 这样不会重建组件，只是强制重新计算 layout

package/src/ui/MessageList.js

@@ -1,10 +1,18 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { Box, Text } from 'ink';
 const MAX_TOOL_PREVIEW_LINES = 3;
 export function MessageList({ history, streamingText, streamingReasoning }) {
-    return (_jsxs(Box, { flexDirection: "column", children: [history.map((m, i) => (_jsx(MessageRow, { message: m }, i))), streamingReasoning.length > 0 && (_jsx(Box, { marginBottom: 1, children: _jsxs(Text, { color: "gray", dimColor: true, children: ["\uD83D\uDCA1 ", streamingReasoning.length > 300
-                            ? `...(${Math.round(streamingReasoning.length / 1000)}K字)${streamingReasoning.slice(-200)}`
-                            : streamingReasoning] }) })), streamingText.length > 0 && (_jsx(Box, { marginBottom: 1, children: _jsx(Text, { children: streamingText }) }))] }));
+    return (_jsxs(Box, { flexDirection: "column", children: [history.map((m, i) => (_jsx(MessageRow, { message: m }, i))), streamingReasoning.length > 0 && (_jsx(Box, { marginBottom: 1, flexDirection: "column", children: (() => {
+                    const MAX_LINES = 5;
+                    const THRESHOLD = 300;
+                    if (streamingReasoning.length <= THRESHOLD) {
+                        return (_jsxs(Text, { color: "gray", dimColor: true, children: ["\uD83D\uDCA1 ", streamingReasoning] }));
+                    }
+                    const allLines = streamingReasoning.split('\n');
+                    const tailLines = allLines.slice(-MAX_LINES);
+                    const omitted = allLines.length - MAX_LINES;
+                    return (_jsxs(_Fragment, { children: [_jsxs(Text, { color: "gray", dimColor: true, children: ["\uD83D\uDCA1 ... (", Math.round(streamingReasoning.length / 1000), "K\u5B57, \u7701\u7565 ", omitted, " \u884C)"] }), tailLines.slice(0, -1).map((line, i) => (_jsxs(Text, { color: "gray", dimColor: true, children: ['  ', line || ' '] }, i))), _jsxs(Text, { color: "gray", dimColor: true, children: ['  ', tailLines[tailLines.length - 1] || ' '] })] }));
+                })() })), streamingText.length > 0 && (_jsx(Box, { marginBottom: 1, children: _jsx(Text, { children: streamingText }) }))] }));
 }
 function MessageRow({ message }) {
     switch (message.role) {

package/src/ui/ProgressPanel.js

@@ -0,0 +1,98 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+/**
+ * ============================================================
+ *  src/ui/ProgressPanel.tsx —— 工作过程显示面板（v2 瘦身版）
+ * ------------------------------------------------------------
+ *  贴在 InputBox 上方的一块"过程区"。
+ *  仅当 progressStage !== 'idle' 时渲染，turn 结束后整块消失。
+ *
+ *  v2 变化：
+ *    - 删除 streamingText 块（搬去 StreamingBlock 独立组件）
+ *    - 删除 reasoning preview 块（reasoning 留在 history 由 MessageList 渲染）
+ *    - spinner 行融合 friendly 工具描述：
+ *        `⠋ Reading src/foo.ts +2 more · 2.3s · ~890 tokens · step 6`
+ *    - 不再单独列每个 tool 一行（多个工具用 +N more 在 spinner 行末尾）
+ *
+ *  样式：
+ *    ⠋ Reading src/foo.ts +2 more · 2.3s · ~890 tokens · step 6
+ *    [plugin:ralph-wiggum] 3/10 验证中...
+ *
+ *  设计要点：
+ *  - braille spinner 用 useEffect + setInterval(120ms) 自驱动；unmount 时 clearInterval
+ *  - 最终高度：1 行 spinner / 0~1 行 plugin progress
+ * ============================================================
+ */
+import React from 'react';
+import { Box, Text } from 'ink';
+/** braille spinner 帧序列 */
+const SPINNER_FRAMES = [
+    '⠋',
+    '⠙',
+    '⠹',
+    '⠸',
+    '⠼',
+    '⠴',
+    '⠦',
+    '⠧',
+    '⠇',
+    '⠏',
+];
+const SPINNER_INTERVAL_MS = 120;
+/** 阶段标签中文映射 */
+const STAGE_LABELS = {
+    thinking: '思考中',
+    streaming: '回答中',
+    tool_executing: '调用工具',
+    compacting: '压缩历史',
+};
+/** 工具参数预览单行最大宽度（fallback 时用） */
+const TOOL_ARGS_MAX = 60;
+/** 按字符宽度截断，超长尾部加 …（按字符而非 byte，够用） */
+function truncateTail(s, max) {
+    if (s.length <= max)
+        return s;
+    return `${s.slice(0, max - 1)}…`;
+}
+/**
+ * 自驱动的 braille spinner hook。
+ * 组件 unmount 时自动 clearInterval，避免悬挂定时器。
+ */
+function useSpinnerFrame() {
+    const [frame, setFrame] = React.useState(0);
+    React.useEffect(() => {
+        const t = setInterval(() => {
+            setFrame((f) => (f + 1) % SPINNER_FRAMES.length);
+        }, SPINNER_INTERVAL_MS);
+        return () => clearInterval(t);
+    }, []);
+    return SPINNER_FRAMES[frame];
+}
+export function ProgressPanel({ progressStage, runningTools, turnTokens, turnElapsedMs, turnStep, pluginProgress, }) {
+    // spinner hook 必须无条件调用（React Hooks 规则），早 return 放在 hook 之后
+    const spinner = useSpinnerFrame();
+    // idle 时整个面板不渲染
+    if (progressStage === 'idle') {
+        return null;
+    }
+    const stageLabel = STAGE_LABELS[progressStage];
+    const elapsedSec = (turnElapsedMs / 1000).toFixed(1);
+    const tokensStr = turnTokens.toLocaleString();
+    // 头行的"主描述"：有工具用 friendly，无工具用 stage label
+    let mainDescription;
+    if (runningTools.length > 0) {
+        const first = runningTools[0];
+        mainDescription =
+            first.argsFriendly && first.argsFriendly.length > 0
+                ? first.argsFriendly
+                : `${first.toolName}(${truncateTail(first.argsPreview, TOOL_ARGS_MAX)})`;
+        if (runningTools.length > 1) {
+            mainDescription += ` +${runningTools.length - 1} more`;
+        }
+    }
+    else {
+        mainDescription = stageLabel;
+    }
+    // 头行尾部的附加信息：耗时 / token / step
+    const stepHint = typeof turnStep === 'number' && turnStep > 0 ? ` · step ${turnStep}` : '';
+    return (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsxs(Box, { children: [_jsxs(Text, { color: "cyan", children: [spinner, " "] }), _jsx(Text, { bold: true, children: mainDescription }), _jsx(Text, { color: "gray", children: ` · ${elapsedSec}s · ~${tokensStr} tokens${stepHint}` })] }), pluginProgress && (_jsx(Box, { children: _jsx(Text, { color: "magenta", children: `[plugin:${pluginProgress.pluginId}] ${pluginProgress.current}/${pluginProgress.max ?? '?'}${pluginProgress.message ? ` ${pluginProgress.message}` : ''}` }) }))] }));
+}

package/src/ui/StreamingBlock.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+/** streaming text 显示尾部行数上限（超出截尾，老内容滚出窗口） */
+const STREAMING_TAIL_LINES = 20;
+export function StreamingBlock({ progressStage, streamingText, }) {
+    if (progressStage !== 'streaming' || streamingText.length === 0) {
+        return null;
+    }
+    const lines = streamingText.split('\n').slice(-STREAMING_TAIL_LINES);
+    return (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [lines.map((line, i) => (_jsx(Text, { children: line }, i))), _jsx(Text, { color: "gray", dimColor: true, children: "\u258D" })] }));
+}

package/src/ui/ToolStatus.js

@@ -2,10 +2,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Box, Text } from 'ink';
 export function ToolStatus({ status, compacting }) {
     if (compacting) {
-        return (_jsx(Box, { children: _jsx(Text, { color: "magenta", bold: true, children: "\uD83D\uDDDC  \u6B63\u5728\u538B\u7F29\u5BF9\u8BDD\u5386\u53F2..." }) }));
+        return (_jsx(Box, { children: _jsx(Text, { color: "magenta", bold: true, children: "\uD83D\uDF18 \u6B63\u5728\u538B\u7F29\u5BF9\u8BDD\u5386\u53F2..." }) }));
     }
     if (status) {
-        return (_jsx(Box, { children: _jsxs(Text, { color: "yellow", children: ['⏳ ', _jsx(Text, { bold: true, children: status.toolName }), `(${status.argsPreview})`] }) }));
+        return (_jsx(Box, { children: _jsxs(Text, { color: "yellow", children: ["\u23F3 ", _jsx(Text, { bold: true, children: status.toolName }), "(", status.argsPreview, ")"] }) }));
     }
     return null;
 }

package/src/ui/hooks/useInputHistory.js

@@ -0,0 +1,186 @@
+/**
+ * ============================================================
+ *  src/ui/hooks/useInputHistory.ts —— 输入历史 ring buffer + 持久化
+ * ------------------------------------------------------------
+ *  - ring buffer 上限 50 条
+ *  - 持久化 ~/.minimal-agent/input-history.txt（一行一条 UTF-8）
+ *    转义 `\\` → `\\\\`，`\n` → `\\n`，避免多行输入被换行符撕碎
+ *  - API：push / prev / next / search / resetCursor
+ *  - 核心逻辑抽到 createInputHistoryStore，方便测试 DI 注入 fs
+ *    hook 自身只是 useRef + useEffect 包一下，渲染零依赖
+ * ============================================================
+ */
+import { useEffect, useMemo, useRef } from 'react';
+import { mkdir as fsMkdir, readFile as fsReadFile, writeFile as fsWriteFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+const MAX_ITEMS = 50;
+const WRITE_DEBOUNCE_MS = 500;
+/* ------------------------------------------------------------ *
+ *  转义：换行 + 反斜杠
+ * ------------------------------------------------------------ */
+export function encodeHistoryLine(text) {
+    return text.replace(/\\/g, '\\\\').replace(/\n/g, '\\n');
+}
+export function decodeHistoryLine(line) {
+    // 状态机：遇到 \ 看下一个字符决定 \\ → \  或  \n → 真换行
+    let out = '';
+    let i = 0;
+    while (i < line.length) {
+        const ch = line[i];
+        if (ch === '\\' && i + 1 < line.length) {
+            const nxt = line[i + 1];
+            if (nxt === '\\') {
+                out += '\\';
+                i += 2;
+                continue;
+            }
+            if (nxt === 'n') {
+                out += '\n';
+                i += 2;
+                continue;
+            }
+        }
+        out += ch;
+        i += 1;
+    }
+    return out;
+}
+export function createInputHistoryStore(opts = {}) {
+    const fs = opts.fs ?? {
+        readFile: (p) => fsReadFile(p, 'utf8'),
+        writeFile: (p, d) => fsWriteFile(p, d, 'utf8'),
+        mkdir: (p, o) => fsMkdir(p, o).then(() => undefined),
+    };
+    const historyPath = opts.historyPath ?? join(homedir(), '.minimal-agent', 'input-history.txt');
+    const debounceMs = opts.writeDebounceMs ?? WRITE_DEBOUNCE_MS;
+    let buffer = [];
+    let cursor = 0;
+    let writeTimer = null;
+    let pendingWrite = null;
+    async function doWrite() {
+        try {
+            await fs.mkdir(dirname(historyPath), { recursive: true });
+            const data = buffer.map(encodeHistoryLine).join('\n');
+            await fs.writeFile(historyPath, data);
+        }
+        catch {
+            // 持久化失败不影响 UI；下次 push 还会再试
+        }
+    }
+    function scheduleWrite() {
+        if (debounceMs <= 0) {
+            pendingWrite = doWrite();
+            return;
+        }
+        if (writeTimer)
+            clearTimeout(writeTimer);
+        writeTimer = setTimeout(() => {
+            writeTimer = null;
+            pendingWrite = doWrite();
+        }, debounceMs);
+    }
+    return {
+        async load() {
+            try {
+                const raw = await fs.readFile(historyPath);
+                if (!raw)
+                    return;
+                const lines = raw.split('\n').filter((l) => l.length > 0);
+                buffer = lines.slice(-MAX_ITEMS).map(decodeHistoryLine);
+                cursor = buffer.length;
+            }
+            catch {
+                // 文件不存在 / 读不出 → 用空 buffer 起步
+            }
+        },
+        push(text) {
+            if (!text)
+                return;
+            // 连续重复去重：跟最后一条相同就忽略
+            if (buffer.length > 0 && buffer[buffer.length - 1] === text) {
+                cursor = buffer.length;
+                return;
+            }
+            buffer.push(text);
+            while (buffer.length > MAX_ITEMS)
+                buffer.shift();
+            cursor = buffer.length;
+            scheduleWrite();
+        },
+        prev() {
+            if (buffer.length === 0)
+                return null;
+            if (cursor <= 0)
+                return null;
+            cursor -= 1;
+            return buffer[cursor] ?? null;
+        },
+        next() {
+            if (buffer.length === 0)
+                return null;
+            if (cursor >= buffer.length)
+                return null;
+            cursor += 1;
+            if (cursor >= buffer.length) {
+                // 已走到 "新输入" 位（buffer 之后），返 null 让 UI 清空
+                return null;
+            }
+            return buffer[cursor] ?? null;
+        },
+        search(query) {
+            if (!query)
+                return [];
+            const hits = [];
+            // 反向遍历，最近优先；同字符串只收一次
+            const seen = new Set();
+            for (let i = buffer.length - 1; i >= 0; i -= 1) {
+                const item = buffer[i];
+                if (item.includes(query) && !seen.has(item)) {
+                    hits.push(item);
+                    seen.add(item);
+                }
+            }
+            return hits;
+        },
+        resetCursor() {
+            cursor = buffer.length;
+        },
+        async flush() {
+            if (writeTimer) {
+                clearTimeout(writeTimer);
+                writeTimer = null;
+                pendingWrite = doWrite();
+            }
+            if (pendingWrite)
+                await pendingWrite;
+        },
+        _snapshot() {
+            return { buffer: [...buffer], cursor };
+        },
+    };
+}
+/* ------------------------------------------------------------ *
+ *  React hook 门面：store 用 useRef 持有，启动时 useEffect 拉盘
+ * ------------------------------------------------------------ */
+export function useInputHistory(opts) {
+    // 同一组件实例共享同一 store；options 变化不重建（输入历史 hook 不需要重建语义）
+    const storeRef = useRef(null);
+    if (storeRef.current === null) {
+        storeRef.current = createInputHistoryStore(opts);
+    }
+    useEffect(() => {
+        // 异步拉盘，不 await；UI 在拉盘前按 ↑ 只是空操作
+        storeRef.current?.load();
+    }, []);
+    // 暴露稳定门面，绑定到内部 store
+    return useMemo(() => {
+        return {
+            push: (t) => storeRef.current.push(t),
+            prev: () => storeRef.current.prev(),
+            next: () => storeRef.current.next(),
+            search: (q) => storeRef.current.search(q),
+            resetCursor: () => storeRef.current.resetCursor(),
+        };
+    }, []);
+}

package/src/ui/hooks/useTerminalSize.js

@@ -0,0 +1,31 @@
+/**
+ * ============================================================
+ *  src/ui/hooks/useTerminalSize.ts —— 终端尺寸感知
+ * ------------------------------------------------------------
+ *  返回当前终端的 rows / cols；监听 process.stdout 'resize' 事件，
+ *  resize 时刷新 state，触发依赖此 hook 的组件 re-render（如 MessageList
+ *  根据 rows < 28 决定是否折叠 reasoning）。
+ *
+ *  fallback 值：rows=24, cols=80（POSIX 终端历史默认）。
+ *  非 TTY 场景（pipe / 测试环境）下 process.stdout.rows 可能 undefined，
+ *  fallback 兜底保证 UI 不崩。
+ * ============================================================
+ */
+import { useEffect, useState } from 'react';
+function readSize() {
+    return {
+        rows: process.stdout.rows ?? 24,
+        cols: process.stdout.columns ?? 80,
+    };
+}
+export function useTerminalSize() {
+    const [size, setSize] = useState(readSize);
+    useEffect(() => {
+        const update = () => setSize(readSize());
+        process.stdout.on('resize', update);
+        return () => {
+            process.stdout.off('resize', update);
+        };
+    }, []);
+    return size;
+}