minimal-agent 0.9.0 → 0.10.0

package/src/loop.js

@@ -27,19 +27,31 @@
  * ============================================================
  */
 import crypto from 'node:crypto';
-import { autoCompactIfNeeded } from './context/compact.js';
+import { autoCompactIfNeeded, getCompactThreshold } from './context/compact.js';
 import { microCompact, incrementTurn, expireOldEntries } from './context/microCompactLite.js';
 import { isPromptTooLongError, reactiveCompactIfApplicable, } from './context/reactiveCompact.js';
 import { snipCompactIfNeeded } from './context/snipCompact.js';
 import { countMessagesTokens, estimateToolsTokens } from './context/tokenCounter.js';
 import { chat as defaultChat } from './llm/client.js';
+import { buildUserContent } from './multimodal.js';
 import { ALL_TOOLS, executeTool as defaultExecuteTool, getToolByName } from './tools/index.js';
+import { configService } from './config/configService.js';
 /**
- * 工具 schema 的估算 token 数（ALL_TOOLS 固定，模块加载时算一次即可）。
+ * 工具 schema 的估算 token 数（ALL_TOOLS 固定，首次使用时算一次并缓存）。
  * 每轮 LLM 请求都会带上整套工具 schema，但 countMessagesTokens 只数历史消息、
  * 漏了这部分 → 系统性低估。autoCompact 判定阈值时加上它才准。
+ *
+ * ⚠️ 必须懒求值而非模块顶层求值：Agent 工具引入了 tools/index → agent → loop →
+ * tools/index 的模块环，若从 tools/index 一侧先进入，顶层求值 ALL_TOOLS 时它还在
+ * TDZ（临时死区），启动即 ReferenceError。函数体内访问时模块图早已初始化完毕。
  */
-const TOOLS_SCHEMA_TOKENS = estimateToolsTokens(ALL_TOOLS);
+let toolsSchemaTokensCache = null;
+function getToolsSchemaTokens() {
+    if (toolsSchemaTokensCache === null) {
+        toolsSchemaTokensCache = estimateToolsTokens(ALL_TOOLS);
+    }
+    return toolsSchemaTokensCache;
+}
 /**
  * 执行一次"用户输入 → 模型回答完成"的完整流程。
  *
@@ -51,11 +63,50 @@ export async function* runQuery(userInput, options) {
     // DI fallback：测试可传 stub，生产走真实模块单例
     const chatFn = options.chat ?? defaultChat;
     const executeToolFn = options.executeTool ?? defaultExecuteTool;
+    const subagents = await configService.subagents();
+    const toolCallContext = {
+        history,
+        advisorCalls: { used: 0, max: 1 },
+        advisorInvocation: 'agent',
+        // Agent 等派生工具起嵌套子查询所需的运行态：与主循环同一 provider、
+        // 同一审批闸门（子 agent 不绕过宿主策略）。agentCalls 与 advisorCalls 同构，
+        // 限同一回合内的子任务派生总数,防失控 fan-out。
+        provider,
+        toolGate: options.toolGate,
+        agentCalls: { used: 0, max: subagents.enabled ? subagents.maxCallsPerTurn : 0 },
+        subagentConfig: subagents,
+        browserRun: options.browserRun,
+    };
+    // 实际下发给模型的工具集：allowedTools 未传时给全量；
+    // 传入数组时严格按数组过滤，[] 表示本轮不下发任何工具。
+    // 仅影响呈现给 LLM 的工具清单，不影响 executeTool 的内部调度能力。
+    const activeTools = options.allowedTools !== undefined
+        ? ALL_TOOLS.filter((t) => options.allowedTools.includes(t.name))
+        : ALL_TOOLS.filter((tool) => tool.name !== 'Agent' || subagents.enabled);
+    let userContent;
+    try {
+        userContent = await buildUserContent({
+            text: userInput,
+            images: options.imageInputs,
+            parseInlineImages: options.parseInlineImages,
+            detail: options.imageDetail,
+            maxLongSidePixel: options.imageMaxLongSidePixel,
+        });
+    }
+    catch (e) {
+        yield {
+            type: 'error',
+            error: `图片输入处理失败：${e.message}`,
+            code: 'llm_error',
+        };
+        return;
+    }
     // 1. 用户消息入栈（v2：填 timestamp，让 MessageList 的 turn 边界横线
     //    能拿到首条 user 的真实时间，否则 fallback Date.now() 会丢失"提交时刻"语义）
     history.push({
         role: 'user',
-        content: userInput,
+        content: userContent,
+        ...(options.userAttachments?.length ? { attachments: options.userAttachments } : {}),
         timestamp: Date.now(),
         id: crypto.randomUUID(),
     });
@@ -70,15 +121,29 @@ export async function* runQuery(userInput, options) {
     // 作为 autoCompact 的权威判据，校正本地估算的系统性低估；压缩后清空（历史已变，旧值失真）。
     let lastPromptTokens;
     let turn = 0;
+    let workStarted = false;
     while (turn < maxTurns) {
         turn++;
         incrementTurn(sessionState?.microCompact);
         expireOldEntries(sessionState?.microCompact);
         if (signal?.aborted) {
-            // 中断标记帮助模型理解上下文
-            pushInterruptMarker(history);
-            // code='aborted'：让 `-p --output-format json` 把终结原因映射成 stop_reason='interrupted'
-            yield { type: 'error', error: '已被用户中断', code: 'aborted' };
+            pushManualInterruptMarker(history);
+            if (!workStarted) {
+                yield { type: 'error', error: '用户中断了任务', code: 'aborted' };
+            }
+            else {
+                yield { type: 'interrupted', reason: 'manual' };
+            }
+            return;
+        }
+        if (options.hasQueuedInput?.()) {
+            pushQueuedInputMarker(history);
+            if (!workStarted) {
+                yield { type: 'error', error: '收到新输入，取消当前任务', code: 'aborted' };
+            }
+            else {
+                yield { type: 'interrupted', reason: 'queued_input' };
+            }
             return;
         }
         // 2. 自动压缩（判据 = max(上一轮真实 usage, 历史估算 + 工具 schema)，
@@ -86,7 +151,8 @@ export async function* runQuery(userInput, options) {
         try {
             const compact = await autoCompactIfNeeded(history, provider, {
                 actualPromptTokens: lastPromptTokens,
-                toolsTokens: TOOLS_SCHEMA_TOKENS,
+                toolsTokens: getToolsSchemaTokens(),
+                signal,
             });
             if (compact.compacted) {
                 yield { type: 'compact_start' };
@@ -144,11 +210,18 @@ export async function* runQuery(userInput, options) {
         let lastFinishReason = 'unknown';
         // 进入 LLM 流前：等首 token / reasoning，本质是 thinking
         yield { type: 'stage_change', stage: 'thinking' };
+        workStarted = true;
         try {
+            const modelMessages = options.transientContext?.trim()
+                ? [
+                    { role: 'system', content: options.transientContext.trim() },
+                    ...history,
+                ]
+                : history;
             for await (const ev of chatFn({
                 provider,
-                messages: history,
-                tools: ALL_TOOLS,
+                messages: modelMessages,
+                tools: activeTools,
                 signal,
             })) {
                 if (ev.type === 'text_delta') {
@@ -187,9 +260,14 @@ export async function* runQuery(userInput, options) {
         }
         catch (e) {
             if (e.name === 'AbortError') {
-                // 用户主动中断：记录标记消息，不报红色错误
-                pushInterruptMarker(history);
-                yield { type: 'interrupted' };
+                if (options.hasQueuedInput?.()) {
+                    pushQueuedInputMarker(history);
+                    yield { type: 'interrupted', reason: 'queued_input' };
+                }
+                else {
+                    pushManualInterruptMarker(history);
+                    yield { type: 'interrupted', reason: 'manual' };
+                }
                 return;
             }
             // prompt_too_long 反应式自救：压缩历史 → 同 turn 重发 LLM
@@ -199,7 +277,7 @@ export async function* runQuery(userInput, options) {
                 reactiveCount++;
                 yield { type: 'compact_start' };
                 yield { type: 'stage_change', stage: 'compacting' };
-                const result = await reactiveCompactIfApplicable(history, provider, e, sessionState?.reactive);
+                const result = await reactiveCompactIfApplicable(history, provider, e, sessionState?.reactive, signal);
                 // 仅当确实压下去了（after < before）才重试；否则（没压动 / 未恢复）退回错误路径，杜绝死循环。
                 const shrank = (result.after ?? 0) < (result.before ?? 0);
                 if (result.recovered && shrank) {
@@ -226,6 +304,17 @@ export async function* runQuery(userInput, options) {
             };
             return;
         }
+        if (lastFinishReason === 'aborted' || signal?.aborted || options.hasQueuedInput?.()) {
+            if (options.hasQueuedInput?.() && !signal?.aborted) {
+                pushQueuedInputMarker(history);
+                yield { type: 'interrupted', reason: 'queued_input' };
+            }
+            else {
+                pushManualInterruptMarker(history);
+                yield { type: 'interrupted', reason: 'manual' };
+            }
+            return;
+        }
         // S2 防御：OpenAI 协议保证 tool_call 的 index 连续；万一某 provider 跳号产生稀疏数组，
         // 这里压实掉空洞，避免后续遍历 / 回填遇到 undefined（assistantMsg.tool_calls 与执行都用它）。
         {
@@ -259,6 +348,16 @@ export async function* runQuery(userInput, options) {
                         '可调大模型的 max_tokens 上限，或让模型分段输出。',
                 };
             }
+            const estimatedTokens = countMessagesTokens(history) + getToolsSchemaTokens();
+            const usedTokens = Math.min(provider.contextWindow, Math.max(lastPromptTokens ?? 0, estimatedTokens));
+            yield {
+                type: 'context_usage',
+                usedTokens,
+                contextWindow: provider.contextWindow,
+                remainingTokens: Math.max(0, provider.contextWindow - usedTokens),
+                compactThreshold: getCompactThreshold(provider),
+                source: lastPromptTokens === undefined ? 'estimated' : 'actual',
+            };
             yield { type: 'turn_done' };
             return;
         }
@@ -274,13 +373,34 @@ export async function* runQuery(userInput, options) {
         // （OpenAI 协议要求 tool 消息与上一条 assistant 的 tool_calls 一一对应）。
         yield { type: 'stage_change', stage: 'tool_executing' };
         // 执行单个 tool call → WorkerOutcome（内部吞掉 abort/异常，永不 reject）。
-        const runOne = async (tc) => {
+        const runOne = async (tc, reportProgress) => {
             try {
-                const result = await executeToolFn(tc.function.name, tc.function.arguments, signal);
+                // 工具执行闸门：宿主注入后覆盖所有工具，包括只读工具。deny → 把 reason 当
+                // tool_result 回填，模型据此改道/如实报告，不抛异常不中断整轮。宿主异常一律 deny。
+                const isReadOnly = getToolByName(tc.function.name)?.isReadOnly === true;
+                if (options.toolGate) {
+                    let decision;
+                    try {
+                        decision = await options.toolGate({ name: tc.function.name, argsJson: tc.function.arguments, isReadOnly, toolCallId: tc.id }, signal);
+                    }
+                    catch {
+                        decision = { allow: false, reason: '工具执行审批失败（宿主异常）' };
+                    }
+                    if (!decision.allow) {
+                        return { tc, result: { ok: false, error: decision.reason } };
+                    }
+                }
+                options.onToolStart?.(tc.function.name, tc.id);
+                // 浅拷贝填入本次调用的 toolCallId：进度按调用实例路由（并行同名工具不串扰）。
+                // advisorCalls/agentCalls 是共享对象引用，计数仍全轮共享，不受拷贝影响。
+                const result = await executeToolFn(tc.function.name, tc.function.arguments, signal, { ...toolCallContext, toolCallId: tc.id, reportProgress });
+                options.onToolEnd?.(tc.id, false);
                 return { tc, result };
             }
             catch (e) {
-                if (e.name === 'AbortError') {
+                const wasAborted = e.name === 'AbortError';
+                options.onToolEnd?.(tc.id, wasAborted);
+                if (wasAborted) {
                     return { tc, result: { ok: false, error: 'aborted' } };
                 }
                 return { tc, result: { ok: false, error: e.message } };
@@ -303,6 +423,7 @@ export async function* runQuery(userInput, options) {
                 : o.result.error === 'aborted'
                     ? '(已中断)'
                     : `Error: ${o.result.error}`,
+            metadata: o.result.metadata,
         });
         const allConcurrencySafe = toolCallsByIndex.every((tc) => {
             const tool = getToolByName(tc.function.name);
@@ -320,7 +441,13 @@ export async function* runQuery(userInput, options) {
             };
             const workers = toolCallsByIndex.map(async (tc) => {
                 enqueue(startEvent(tc));
-                const o = await runOne(tc);
+                const o = await runOne(tc, (message, detail) => enqueue({
+                    type: 'tool_progress',
+                    toolCallId: tc.id,
+                    toolName: tc.function.name,
+                    message,
+                    detail,
+                }));
                 enqueue(endEvent(o));
                 return o;
             });
@@ -347,7 +474,32 @@ export async function* runQuery(userInput, options) {
             settled = [];
             for (const tc of toolCallsByIndex) {
                 yield startEvent(tc);
-                const o = await runOne(tc);
+                const queue = [];
+                let wake = null;
+                let finished = false;
+                const worker = runOne(tc, (message, detail) => {
+                    queue.push({
+                        type: 'tool_progress',
+                        toolCallId: tc.id,
+                        toolName: tc.function.name,
+                        message,
+                        detail,
+                    });
+                    wake?.();
+                    wake = null;
+                }).finally(() => {
+                    finished = true;
+                    wake?.();
+                    wake = null;
+                });
+                while (!finished || queue.length > 0) {
+                    while (queue.length > 0)
+                        yield queue.shift();
+                    if (finished)
+                        break;
+                    await new Promise((resolve) => { wake = resolve; });
+                }
+                const o = await worker;
                 yield endEvent(o);
                 settled.push(o);
             }
@@ -366,13 +518,25 @@ export async function* runQuery(userInput, options) {
                 role: 'tool',
                 content,
                 tool_call_id: tc.id,
+                ...(result.metadata ? { display_metadata: result.metadata } : {}),
                 timestamp: Date.now(),
                 id: crypto.randomUUID(),
             });
         }
         if (anyAborted || signal?.aborted) {
-            // 工具被中断时，外层 yield interrupted 并 return
-            yield { type: 'interrupted' };
+            if (options.hasQueuedInput?.()) {
+                pushQueuedInputMarker(history);
+                yield { type: 'interrupted', reason: 'queued_input' };
+            }
+            else {
+                pushManualInterruptMarker(history);
+                yield { type: 'interrupted', reason: 'manual' };
+            }
+            return;
+        }
+        if (options.hasQueuedInput?.()) {
+            pushQueuedInputMarker(history);
+            yield { type: 'interrupted', reason: 'queued_input' };
             return;
         }
         // 6. 继续 while 让模型看到 tool_result 后继续推理
@@ -386,14 +550,30 @@ export async function* runQuery(userInput, options) {
 }
 // ---------------- 辅助函数 ----------------
 /**
- * 把"用户按下了 ESC/Ctrl+C 中断了任务"标记消息 push 到 history。
- * 两处使用：① loop 入口 signal 检查后 ② chat AbortError 捕获后。
- * 抽出来消除重复——同时保证两条路径写入的文案 + shape 完全一致。
+ * 用户按ESC手动中断
+ */
+function pushManualInterruptMarker(history) {
+    history.push({
+        role: 'user',
+        content: '(用户按下了 ESC/Ctrl+C 中断了任务。等待用户新指令。)',
+        timestamp: Date.now(),
+        id: crypto.randomUUID(),
+    });
+}
+/**
+ * 有新的用户输入在队列中，当前安全停靠
  */
-function pushInterruptMarker(history) {
+function pushQueuedInputMarker(history) {
     history.push({
         role: 'user',
-        content: '(用户按下了 ESC/Ctrl+C 中断了任务)',
+        content: [
+            '(系统提示：用户在工作过程中发送了新的消息。',
+            '你现在看到的是上一轮工作在被打断前已完成的部分。',
+            '请阅读用户的新消息，判断：',
+            '1. 如果是不相关的新任务：简要确认已收到，转向新任务，可在新任务完成后询问是否回到之前工作',
+            '2. 如果是补充信息或前置依赖：把新信息纳入考虑，判断是否需要调整已做的工作，然后继续',
+            '3. 如果是改变方向或取消：评估已完成的部分，说明你对变更的理解，按新方向推进)',
+        ].join('\n'),
         timestamp: Date.now(),
         id: crypto.randomUUID(),
     });
@@ -466,6 +646,10 @@ function friendlyToolDescription(toolName, rawArgsJson) {
             }
         }
         case 'WebSearch': return `Searching \`${truncate(args.query, 50)}\``;
+        case 'Agent': {
+            const t = typeof args.agent_type === 'string' ? args.agent_type : 'explore';
+            return `子任务[${t}] ${truncate(args.description, 50)}`;
+        }
         default: return `${toolName}(...)`;
     }
 }

package/src/main.js

@@ -19,9 +19,12 @@ const pkg = (() => {
 })();
 import { extractCwdArg } from './bootstrap/cwdArg.js';
 import { initWorkingDir, getWorkingDir } from './bootstrap/workingDir.js';
+import { ensureAgentBrowserOnPath } from './tools/webbrowser/agentBrowserPath.js';
 import { applyToolKeysToEnv, loadProviderLayered } from './config.js';
 import { clearContext, loadContext } from './context/persistContext.js';
-import { migrateLegacyContext } from './context/sessionPath.js';
+import { validateSessionId } from './context/sessionRegistry.js';
+import { workspaceIndexService } from './context/workspaceIndex.js';
+import { migrateLegacyContext, sessionFileFor } from './context/sessionPath.js';
 import { buildFullSystemPrompt } from './prompts/system.js';
 import { ALL_TOOLS } from './tools/index.js';
 import { Root } from './ui/Root.js';
@@ -60,12 +63,25 @@ async function main() {
         console.log(`minimal-agent v${pkg.version}`);
         return;
     }
+    if (args.includes('--workspace-doctor')) {
+        const snapshot = await workspaceIndexService.snapshot();
+        console.log(`Workspace Index v${snapshot.version} · revision ${snapshot.revision}`);
+        for (const workspace of snapshot.workspaces) {
+            console.log(`${workspace.available ? '✓' : '○'} ${workspace.displayPath} · ${workspace.sessions.length} sessions`);
+        }
+        console.log(`可恢复/已过滤历史：${snapshot.recoverable.length}`);
+        return;
+    }
     // --clear：清空当前工作目录的会话（归档 + 清空）后退出。供 webchat 的 /new 调用。
     //   无需 provider；上面 -d/--cwd 已 chdir + initWorkingDir，clearContext() 作用于该目录。
     if (args.includes('--clear')) {
         await clearContext();
         return;
     }
+    // 内置 agent 浏览器：把已 vendored/绿色版同级的 agent-browser 目录前置进 PATH，
+    // 让 Bash 工具 / skill 脚本 / 工作流 bash 步也能直接调（tools/skills/工作流共用底座）。
+    // dev/npm 无 vendored 二进制时 no-op；不污染 stdout，-p json 契约安全。
+    await ensureAgentBrowserOnPath();
     const isPrintMode = args.includes('-p') || args.includes('--print');
     if (isPrintMode) {
         // 先把输出格式解析出来——provider 缺失分支也要按 json 契约给信号。
@@ -81,6 +97,20 @@ async function main() {
         const rawMaxTurns = extractFlagValue(args, ['--max-turns']);
         const parsedMaxTurns = rawMaxTurns !== undefined ? Number.parseInt(rawMaxTurns, 10) : Number.NaN;
         const maxTurns = Number.isNaN(parsedMaxTurns) ? undefined : parsedMaxTurns;
+        // -s/--session <id>：选定同 cwd 下的哪个 session；缺省 'default'（向后兼容，
+        // 逐字节保持旧行为）。读、写必须用同一份解析结果——不能只让加载感知这个 flag，
+        // 落盘时各自重新计算，否则出现"从 session A 读、写回 default"的读写分裂。
+        let sessionId;
+        try {
+            sessionId = validateSessionId(extractFlagValue(args, ['-s', '--session']) ?? 'default');
+        }
+        catch (error) {
+            console.error(`无效的 --session：${error.message}`);
+            process.exitCode = 2;
+            return;
+        }
+        await workspaceIndexService.register(getWorkingDir()).catch(() => { });
+        const sessionFile = sessionFileFor(getWorkingDir(), sessionId);
         // CLI 非交互模式：先 env，再 ~/.minimal-agent/config.json fallback；都没就退出
         // （宿主 spawn 子进程时通常没 export env，靠 TUI 向导写出的 config.json 持久化）
         const provider = await loadProviderLayered();
@@ -104,24 +134,29 @@ async function main() {
             process.stderr.write(`\n未找到 provider 配置。\n\n` +
                 `请二选一：\n` +
                 `  1. 设置环境变量 MINIMAL_AGENT_BASE_URL / MINIMAL_AGENT_API_KEY / MINIMAL_AGENT_MODEL\n` +
-                `  2. 先直接运行 \`minimal-agent\`（TUI）完成首次配置向导；向导会写出 ~/.minimal-agent/config.json，之后 -p 模式自动复用\n\n`);
+                `  2. 先直接运行 \`minimal-agent\`（TUI）在首次配置菜单里配好基座模型；菜单会写出 ~/.minimal-agent/config.json，之后 -p 模式自动复用\n\n`);
             process.exit(1);
         }
-        const initialHistory = await buildInitialHistory();
+        const initialHistory = await buildInitialHistory(sessionFile);
         const verbose = args.includes('--verbose') || args.includes('-v');
         // stream-json 走独立流式模式（webchat broker / 网关用）；text/json 仍走原 runPrintMode（契约不变）。
         if (outputFormat === 'stream-json') {
             await runStreamJsonMode(provider, args, initialHistory, {
                 maxTurns,
                 compact: args.includes('--compact'),
+                sessionFile,
+                workspace: { cwd: getWorkingDir(), sessionId },
             });
             return;
         }
-        await runPrintMode(provider, args, initialHistory, { verbose, outputFormat, maxTurns });
+        await runPrintMode(provider, args, initialHistory, {
+            verbose, outputFormat, maxTurns, sessionFile,
+            workspace: { cwd: getWorkingDir(), sessionId },
+        });
         return;
     }
-    // TUI 交互模式：env 不全则 fallback 到 ~/.minimal-agent/config.json；
-    // 都没有则 Root 渲染配置向导。
+    // TUI 交互模式：优先读 JSON 配置（home → exe 同级），没有再用 env 兜底；
+    // 都没有则 Root 渲染首次配置菜单。
     const initialProvider = await loadProviderLayered();
     const { waitUntilExit } = render(_jsx(Root, { initialProvider: initialProvider }));
     await waitUntilExit();
@@ -133,10 +168,14 @@ async function main() {
  * 总是用 fresh system prompt（即便 last-context.json 里也存了一份），
  * 这样换 cwd 或工具后也不会沿用错的环境上下文。
  */
-async function buildInitialHistory() {
+/**
+ * @param sessionFile 显式会话文件路径（`-p`/stream-json 模式下由 `--session` 解析而来）；
+ *   缺省时走 `loadContext()` 的默认路径（= default session，向后兼容）。
+ */
+async function buildInitialHistory(sessionFile) {
     const content = await buildFullSystemPrompt(getWorkingDir(), ALL_TOOLS);
     const fresh = { role: 'system', content };
-    const persisted = await loadContext();
+    const persisted = await loadContext(sessionFile);
     if (!persisted || persisted.length === 0)
         return [fresh];
     const rest = persisted[0]?.role === 'system' ? persisted.slice(1) : persisted;
@@ -155,24 +194,35 @@ minimal-agent - 轻量级 AI 编程助手
   -v, --verbose      显示详细输出（工具调用、压缩信息）
   -d, --cwd <dir>    指定工作目录（不存在自动创建）；启动时 chdir 到这里，
                      上下文文件、工具相对路径、.env 加载都以此为基准
+  -s, --session <id> 选定同一工作目录下的哪个会话（缺省 'default'）；配合 TUI 的
+                     /session /sessions /resume 是同一套内核会话，互不冲突
   --output-format <fmt>  text（默认）= 纯文本答案；json = 一行结局契约
                          （ok / result / stop_reason / num_turns / error）；
                          stream-json = 逐行 LoopEvent（webchat / 网关 broker 用）
   --max-turns <n>    最大工具循环轮数（防失控；缺省 50）
+  --image <path|url> 附加图片（可重复；JPEG/PNG/GIF/WEBP，本地单图≤10MB）
+  --image-detail <d> 图片细节级别：low / default / high（默认 default）
+  --image-max-long-side-pixel <n>
+                     OpenAI 兼容图片参数：限制最长边像素
   --clear            清空当前工作目录的会话（归档 + 清空）后退出
   --compact          与 -p --output-format stream-json 连用：压缩当前会话
+  --workspace-doctor 只读诊断全局工作区索引、Session 数量和孤立历史
   -h, --help         显示帮助信息
 
 会话记忆:
-  按当前工作目录隔离，自动加载 / 保存到
-  ~/.minimal-agent/sessions/<目录哈希>.json
-  TUI 与 -p 共享同一目录的上下文；TUI 中输入 /new 仅清当前目录的会话
+  按当前工作目录隔离，同一工作目录下可以有多个会话（session），
+  自动加载 / 保存到 ~/.minimal-agent/sessions/<目录哈希>--<sessionId>.json
+  （不传 --session 时用 'default'）。TUI 与 -p 共享同一套会话；
+  TUI 里用 /session /sessions /resume 列出并切换会话、/session new [标题] 新建；
+  -p 用 -s/--session <id> 选定；TUI 中输入 /new 仅清当前会话（不影响其它会话）
 
 示例:
   minimal-agent -p "帮我写一个 hello world"
   echo "解释代码" | minimal-agent -p
   minimal-agent -p --verbose "运行测试并报告结果"
   minimal-agent -p "处理资料" -d /tmp/job-123        # 工作目录隔离
+  minimal-agent -p --image ./ui.png "评价这个界面"
+  minimal-agent -p "@/tmp/a.png 请识别图片内容"       # TUI / -p 均支持 @图片路径
   minimal-agent -p --output-format json "做点事"     # 宿主程序 spawn：一行 JSON 结局
   `);
 }

package/src/messageQueue.js

@@ -0,0 +1,97 @@
+/**
+ * ============================================================
+ *  src/messageQueue.ts —— 用户输入队列（支持优先级）
+ * ------------------------------------------------------------
+ *  实现对话进行中用户插话的排队管理。
+ *
+ *  设计原则：
+ *    - 极简：只保留 minimal-agent 需要的核心功能
+ *    - 发布订阅：subscribe() 订阅队列变化，用于UI更新
+ *    - 工厂函数：createInputQueue() 创建独立实例，支持多session/测试
+ *    - 两级优先级：'now'（立即处理）> 'next'（排队等待）
+ * ============================================================
+ */
+function randomUUID() {
+    if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
+        return crypto.randomUUID();
+    }
+    return `q_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+export function createInputQueue() {
+    const queue = [];
+    const subscribers = new Set();
+    function notify() {
+        for (const cb of subscribers) {
+            cb();
+        }
+    }
+    function findBestIndex() {
+        let bestIdx = 0;
+        let bestPrio = 99;
+        for (let i = 0; i < queue.length; i++) {
+            const p = queue[i].priority === 'now' ? 0 : 1;
+            if (p < bestPrio) {
+                bestPrio = p;
+                bestIdx = i;
+            }
+        }
+        return bestIdx;
+    }
+    return {
+        enqueue(value, priority = 'next') {
+            queue.push({
+                id: randomUUID(),
+                value,
+                priority,
+                timestamp: Date.now(),
+            });
+            notify();
+        },
+        dequeue() {
+            if (queue.length === 0)
+                return undefined;
+            const bestIdx = findBestIndex();
+            const item = queue.splice(bestIdx, 1)[0];
+            if (item)
+                notify();
+            return item;
+        },
+        dequeueAll() {
+            if (queue.length === 0)
+                return [];
+            const sorted = [...queue].sort((a, b) => {
+                const pa = a.priority === 'now' ? 0 : 1;
+                const pb = b.priority === 'now' ? 0 : 1;
+                if (pa !== pb)
+                    return pa - pb;
+                return a.timestamp - b.timestamp;
+            });
+            queue.length = 0;
+            notify();
+            return sorted;
+        },
+        peek() {
+            if (queue.length === 0)
+                return undefined;
+            return queue[findBestIndex()];
+        },
+        clear() {
+            if (queue.length === 0)
+                return;
+            queue.length = 0;
+            notify();
+        },
+        size() {
+            return queue.length;
+        },
+        subscribe(callback) {
+            subscribers.add(callback);
+            return () => {
+                subscribers.delete(callback);
+            };
+        },
+        getSnapshot() {
+            return Object.freeze([...queue]);
+        },
+    };
+}