minimal-agent 0.10.0 → 0.12.0

package/src/main.js

@@ -4,16 +4,18 @@ import { render } from 'ink';
 import { existsSync, mkdirSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { resolve } from 'node:path';
+import { installTerminalCapture } from './tools/terminal/terminalCapture.js';
 const require = createRequire(import.meta.url);
 const pkg = (() => {
+    if (typeof __GREEN_BUILD_VERSION__ === 'string') {
+        return { version: __GREEN_BUILD_VERSION__ };
+    }
     try {
         return require('../package.json');
     }
     catch {
         return {
-            version: typeof __GREEN_BUILD_VERSION__ === 'string'
-                ? __GREEN_BUILD_VERSION__
-                : '0.0.0',
+            version: '0.0.0',
         };
     }
 })();
@@ -25,19 +27,25 @@ import { clearContext, loadContext } from './context/persistContext.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 { buildBaseSystemPrompt } from './prompts/system.js';
+import { resolveMemoryAccess } from './cli/memoryAccess.js';
 import { ALL_TOOLS } from './tools/index.js';
+import { memoryToolAllowed } from './runtime/agentRuntimeContext.js';
 import { Root } from './ui/Root.js';
 import { runPrintMode } from './cli/print.js';
 import { runStreamJsonMode } from './cli/streamJson.js';
-import { extractFlagValue } from './cli/args.js';
+import { extractFlagValue, normalizeArgs } from './cli/args.js';
+import { resolveComputerUseMode, resolveComputerUseTraceDir } from './cli/computerUse.js';
 // re-export：对外保持「main.tsx 提供 extractFlagValue」的语义；实现住在 cli/args.ts，
 // 这样单测可零副作用 import（main.tsx 顶层 main() 自调用会启动整个 app，不可被测试 import）。
 export { extractFlagValue };
 async function main() {
     // ★ -d/--cwd：在锁定工作目录之前先建目录 + chdir，让后续逻辑全在 -d 下运行
     //   不存在则自动 mkdir -p；后续 initWorkingDir() 自然拿到新 cwd
-    const args = process.argv.slice(2);
+    //   normalizeArgs：先把 `--flag=value` 展开成空格式，之后所有解析（含下面的
+    //   extractCwdArg、-p 分支的 extractFlagValue、print/streamJson 的 extractPromptArgs）
+    //   都只需处理一种写法。这是全进程唯一的 argv 入口，规范化放这里即全链路生效。
+    const args = normalizeArgs(process.argv.slice(2));
     const dirArg = extractCwdArg(args);
     if (dirArg) {
         const abs = resolve(dirArg);
@@ -137,8 +145,30 @@ async function main() {
                 `  2. 先直接运行 \`minimal-agent\`（TUI）在首次配置菜单里配好基座模型；菜单会写出 ~/.minimal-agent/config.json，之后 -p 模式自动复用\n\n`);
             process.exit(1);
         }
-        const initialHistory = await buildInitialHistory(sessionFile);
+        // stream-json 的 stdin 是双工控制通道（宿主可回灌 ask_answer），所以它**能**交互提问；
+        // text/json 的 `-p` 不能——askBridge 会自动选推荐项兜底。提示词必须如实说明，
+        // 否则模型会以为可以停下来等用户选。
         const verbose = args.includes('--verbose') || args.includes('-v');
+        // 信任边界收敛在这一处：两个入口都不再自证「我是本机主人」（见 cli/memoryAccess.ts）。
+        let memoryAccess;
+        let computerUseMode;
+        let computerUseTraceDir;
+        try {
+            memoryAccess = resolveMemoryAccess(outputFormat, args);
+            computerUseMode = resolveComputerUseMode(args);
+            computerUseTraceDir = resolveComputerUseTraceDir(args);
+        }
+        catch (error) {
+            process.stderr.write(`参数错误：${error.message}\n`);
+            process.exitCode = 2;
+            return;
+        }
+        if (computerUseTraceDir) {
+            process.stderr.write(`Computer Use 诊断记录目录：${computerUseTraceDir}\n`);
+        }
+        const visibleTools = ALL_TOOLS.filter((tool) => memoryToolAllowed(tool.name, memoryAccess)
+            && (tool.name !== 'ComputerUse' || computerUseMode !== 'disabled'));
+        const initialHistory = await buildInitialHistory(sessionFile, visibleTools);
         // stream-json 走独立流式模式（webchat broker / 网关用）；text/json 仍走原 runPrintMode（契约不变）。
         if (outputFormat === 'stream-json') {
             await runStreamJsonMode(provider, args, initialHistory, {
@@ -146,20 +176,32 @@ async function main() {
                 compact: args.includes('--compact'),
                 sessionFile,
                 workspace: { cwd: getWorkingDir(), sessionId },
+                memoryAccess,
+                computerUseMode,
+                computerUseTraceDir,
             });
             return;
         }
         await runPrintMode(provider, args, initialHistory, {
             verbose, outputFormat, maxTurns, sessionFile,
             workspace: { cwd: getWorkingDir(), sessionId },
+            memoryAccess,
+            computerUseMode,
+            computerUseTraceDir,
         });
         return;
     }
     // TUI 交互模式：优先读 JSON 配置（home → exe 同级），没有再用 env 兜底；
     // 都没有则 Root 渲染首次配置菜单。
     const initialProvider = await loadProviderLayered();
+    const uninstallTerminalCapture = installTerminalCapture();
     const { waitUntilExit } = render(_jsx(Root, { initialProvider: initialProvider }));
-    await waitUntilExit();
+    try {
+        await waitUntilExit();
+    }
+    finally {
+        uninstallTerminalCapture();
+    }
 }
 /**
  * 启动时构造 history：用当前 cwd / 工具的最新 system prompt，
@@ -172,8 +214,10 @@ async function main() {
  * @param sessionFile 显式会话文件路径（`-p`/stream-json 模式下由 `--session` 解析而来）；
  *   缺省时走 `loadContext()` 的默认路径（= default session，向后兼容）。
  */
-async function buildInitialHistory(sessionFile) {
-    const content = await buildFullSystemPrompt(getWorkingDir(), ALL_TOOLS);
+async function buildInitialHistory(sessionFile, tools = ALL_TOOLS) {
+    // 只放稳定层：易变的运行时状态由每回合的 transientContext 注入消息尾部，
+    // 保证 history[0] 逐字节稳定 → provider 前缀缓存可命中（见 prompts/system.ts）。
+    const content = await buildBaseSystemPrompt(getWorkingDir(), tools);
     const fresh = { role: 'system', content };
     const persisted = await loadContext(sessionFile);
     if (!persisted || persisted.length === 0)
@@ -200,6 +244,17 @@ minimal-agent - 轻量级 AI 编程助手
                          （ok / result / stop_reason / num_turns / error）；
                          stream-json = 逐行 LoopEvent（webchat / 网关 broker 用）
   --max-turns <n>    最大工具循环轮数（防失控；缺省 50）
+  --memory-access <local-owner|read-write|read-only|denied>
+                     本机长期记忆权限。
+                     本机非交互 -p 模式缺省为 read-only；显式传
+                     --memory-access local-owner（或 read-write）才允许写入。
+                     值拼错不会静默降级，会直接报错退出
+  --computer-use <observe|interactive>
+                     非交互模式默认禁用。observe 仅允许观察；interactive 开放基础
+                     键鼠，但剪贴板、文件投放和最终提交仍须在本次指令中明确提出
+  --computer-use-trace <dir>
+                     显式保存本次 Computer Use 的顺序事件与动作后截图，供问题复盘；
+                     目录含屏幕隐私数据，默认不开启
   --image <path|url> 附加图片（可重复；JPEG/PNG/GIF/WEBP，本地单图≤10MB）
   --image-detail <d> 图片细节级别：low / default / high（默认 default）
   --image-max-long-side-pixel <n>
@@ -209,6 +264,8 @@ minimal-agent - 轻量级 AI 编程助手
   --workspace-doctor 只读诊断全局工作区索引、Session 数量和孤立历史
   -h, --help         显示帮助信息
 
+  所有带值标志两种写法等价："--output-format json" 与 "--output-format=json"。
+
 会话记忆:
   按当前工作目录隔离，同一工作目录下可以有多个会话（session），
   自动加载 / 保存到 ~/.minimal-agent/sessions/<目录哈希>--<sessionId>.json

package/src/main.tsx

@@ -0,0 +1,344 @@
+#!/usr/bin/env node
+/**
+ * ============================================================
+ *  src/main.tsx —— minimal-agent 入口
+ *  ------------------------------------------------------------
+ *  shebang `#!/usr/bin/env node` 由 tsc 编译后保留到 src/main.js
+ *  作为 npm 包 bin。dev 跑 `bun run src/main.tsx` 时 Bun 忽略 shebang，
+ *  互不冲突。
+ * ------------------------------------------------------------
+ *  支持两种运行模式：
+ *    - TUI 模式（默认）：启动 Ink 对话框
+ *    - CLI 模式（-p）：非交互，一问一答后退出
+ *
+ *  跑法：
+ *    bun run src/main.tsx
+ *    bun run src/main.tsx -p "提示"
+ *    echo "提示" | bun run src/main.tsx -p
+ *
+ *  快速排错：
+ *    - "缺少必需的环境变量"：检查 .env 文件是否配置正确
+ *    - "rg: command not found"：装 ripgrep（grep 工具用到）
+ * ============================================================
+ */
+
+import React from 'react';
+import { render } from 'ink';
+import { existsSync, mkdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+import { installTerminalCapture } from './tools/terminal/terminalCapture.js';
+
+const require = createRequire(import.meta.url);
+
+// 版本号读取：绿色版优先采用编译期 define；dev/npm 才读取 package.json。
+// Bun compile 的虚拟文件系统里 require('../package.json') 偶尔会“成功”解析到
+// 非本包清单，不能依赖 throw 才使用注入值。
+declare const __GREEN_BUILD_VERSION__: string | undefined;
+const pkg: { version: string } = (() => {
+  if (typeof __GREEN_BUILD_VERSION__ === 'string') {
+    return { version: __GREEN_BUILD_VERSION__ };
+  }
+  try {
+    return require('../package.json') as { version: string };
+  } catch {
+    return {
+      version: '0.0.0',
+    };
+  }
+})();
+
+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 { validateSessionId } from './context/sessionRegistry.js';
+import { workspaceIndexService } from './context/workspaceIndex.js';
+import { migrateLegacyContext, sessionFileFor } from './context/sessionPath.js';
+import { buildBaseSystemPrompt } from './prompts/system.js';
+import { resolveMemoryAccess } from './cli/memoryAccess.js';
+import { ALL_TOOLS } from './tools/index.js';
+import { memoryToolAllowed } from './runtime/agentRuntimeContext.js';
+import type { Message } from './types.js';
+import { Root } from './ui/Root.js';
+import { runPrintMode } from './cli/print.js';
+import { runStreamJsonMode } from './cli/streamJson.js';
+import { extractFlagValue, normalizeArgs } from './cli/args.js';
+import { resolveComputerUseMode, resolveComputerUseTraceDir } from './cli/computerUse.js';
+
+// re-export：对外保持「main.tsx 提供 extractFlagValue」的语义；实现住在 cli/args.ts，
+// 这样单测可零副作用 import（main.tsx 顶层 main() 自调用会启动整个 app，不可被测试 import）。
+export { extractFlagValue };
+
+async function main(): Promise<void> {
+  // ★ -d/--cwd：在锁定工作目录之前先建目录 + chdir，让后续逻辑全在 -d 下运行
+  //   不存在则自动 mkdir -p；后续 initWorkingDir() 自然拿到新 cwd
+  //   normalizeArgs：先把 `--flag=value` 展开成空格式，之后所有解析（含下面的
+  //   extractCwdArg、-p 分支的 extractFlagValue、print/streamJson 的 extractPromptArgs）
+  //   都只需处理一种写法。这是全进程唯一的 argv 入口，规范化放这里即全链路生效。
+  const args = normalizeArgs(process.argv.slice(2));
+  const dirArg = extractCwdArg(args);
+  if (dirArg) {
+    const abs = resolve(dirArg);
+    if (!existsSync(abs)) {
+      mkdirSync(abs, { recursive: true });
+    }
+    process.chdir(abs);
+  }
+
+  // ★ 必须在所有其他逻辑之前——锁定工作目录，并迁移旧版 last-context.json
+  initWorkingDir();
+  await migrateLegacyContext(getWorkingDir());
+
+  // ★ 把 saved config 里的工具 key（如 TAVILY_API_KEY）注入 process.env。
+  //   npm 全局安装跑 `node dist/main.js` 不会自动加载 .env，靠这一步把向导
+  //   收集到的 key 写回 env，否则 WebSearch 等工具 process.env.* 读不到。
+  await applyToolKeysToEnv();
+
+  // --help 优先显示
+  if (args.includes('-h') || args.includes('--help')) {
+    printHelp();
+    return;
+  }
+
+  // --version: 零依赖快速返回（对齐 kakadeai fast-path 设计）
+  if (args.includes('--version') || args.includes('-V')) {
+    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 契约给信号。
+    // 只接受 'text' | 'json'，其它值（含拼错）一律回落 'text'（向后兼容）。
+    const rawFormat = extractFlagValue(args, ['--output-format']);
+    // text（默认，逐字节向后兼容）/ json（一行结局契约）/ stream-json（逐行 LoopEvent，webchat broker 用）
+    const outputFormat: 'text' | 'json' | 'stream-json' =
+      rawFormat === 'json'
+        ? 'json'
+        : rawFormat === 'stream-json'
+          ? 'stream-json'
+          : 'text';
+    // --max-turns：parseInt，非法（NaN）→ undefined（走 loop 默认 50）
+    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: string;
+    try {
+      sessionId = validateSessionId(extractFlagValue(args, ['-s', '--session']) ?? 'default');
+    } catch (error) {
+      console.error(`无效的 --session：${(error as 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();
+    if (!provider) {
+      // json 模式：先给宿主一行结构化信号（stop_reason='config_error'），再退出。
+      // 人类可读的中文提示仍走 stderr（json 契约只占 stdout 那一行）。
+      if (outputFormat === 'json') {
+        console.log(
+          JSON.stringify({
+            ok: false,
+            result: '',
+            is_error: true,
+            stop_reason: 'config_error',
+            num_turns: 0,
+            error: 'provider config not found',
+          }),
+        );
+      } else if (outputFormat === 'stream-json') {
+        // stream-json：吐一行 error 事件（webchat 前端识别为致命错误）
+        console.log(
+          JSON.stringify({ type: 'error', error: 'provider config not found', code: 'llm_error' }),
+        );
+      }
+      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`,
+      );
+      process.exit(1);
+    }
+
+    // stream-json 的 stdin 是双工控制通道（宿主可回灌 ask_answer），所以它**能**交互提问；
+    // text/json 的 `-p` 不能——askBridge 会自动选推荐项兜底。提示词必须如实说明，
+    // 否则模型会以为可以停下来等用户选。
+    const verbose = args.includes('--verbose') || args.includes('-v');
+    // 信任边界收敛在这一处：两个入口都不再自证「我是本机主人」（见 cli/memoryAccess.ts）。
+    let memoryAccess: ReturnType<typeof resolveMemoryAccess>;
+    let computerUseMode: ReturnType<typeof resolveComputerUseMode>;
+    let computerUseTraceDir: ReturnType<typeof resolveComputerUseTraceDir>;
+    try {
+      memoryAccess = resolveMemoryAccess(outputFormat, args);
+      computerUseMode = resolveComputerUseMode(args);
+      computerUseTraceDir = resolveComputerUseTraceDir(args);
+    } catch (error) {
+      process.stderr.write(`参数错误：${(error as Error).message}\n`);
+      process.exitCode = 2;
+      return;
+    }
+    if (computerUseTraceDir) {
+      process.stderr.write(`Computer Use 诊断记录目录：${computerUseTraceDir}\n`);
+    }
+    const visibleTools = ALL_TOOLS.filter((tool) =>
+      memoryToolAllowed(tool.name, memoryAccess)
+      && (tool.name !== 'ComputerUse' || computerUseMode !== 'disabled'));
+    const initialHistory = await buildInitialHistory(sessionFile, visibleTools);
+    // 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 },
+        memoryAccess,
+        computerUseMode,
+        computerUseTraceDir,
+      });
+      return;
+    }
+    await runPrintMode(provider, args, initialHistory, {
+      verbose, outputFormat, maxTurns, sessionFile,
+      workspace: { cwd: getWorkingDir(), sessionId },
+      memoryAccess,
+      computerUseMode,
+      computerUseTraceDir,
+    });
+    return;
+  }
+
+  // TUI 交互模式：优先读 JSON 配置（home → exe 同级），没有再用 env 兜底；
+  // 都没有则 Root 渲染首次配置菜单。
+  const initialProvider = await loadProviderLayered();
+  const uninstallTerminalCapture = installTerminalCapture();
+  const { waitUntilExit } = render(<Root initialProvider={initialProvider} />);
+  try {
+    await waitUntilExit();
+  } finally {
+    uninstallTerminalCapture();
+  }
+}
+
+/**
+ * 启动时构造 history：用当前 cwd / 工具的最新 system prompt，
+ * 后面接上 last-context.json 里上次保存的对话（如果有）。
+ *
+ * 总是用 fresh system prompt（即便 last-context.json 里也存了一份），
+ * 这样换 cwd 或工具后也不会沿用错的环境上下文。
+ */
+/**
+ * @param sessionFile 显式会话文件路径（`-p`/stream-json 模式下由 `--session` 解析而来）；
+ *   缺省时走 `loadContext()` 的默认路径（= default session，向后兼容）。
+ */
+async function buildInitialHistory(
+  sessionFile?: string,
+  tools = ALL_TOOLS,
+): Promise<Message[]> {
+  // 只放稳定层：易变的运行时状态由每回合的 transientContext 注入消息尾部，
+  // 保证 history[0] 逐字节稳定 → provider 前缀缓存可命中（见 prompts/system.ts）。
+  const content = await buildBaseSystemPrompt(getWorkingDir(), tools);
+  const fresh: Message = { role: 'system', content };
+
+  const persisted = await loadContext(sessionFile);
+  if (!persisted || persisted.length === 0) return [fresh];
+  const rest = persisted[0]?.role === 'system' ? persisted.slice(1) : persisted;
+  return [fresh, ...rest];
+}
+
+function printHelp(): void {
+  console.log(`
+minimal-agent - 轻量级 AI 编程助手
+
+用法:
+  minimal-agent [选项] [提示...]
+  echo "提示" | minimal-agent [选项]
+
+选项:
+  -p, --print        非交互模式，直接执行单次问答
+  -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）
+  --memory-access <local-owner|read-write|read-only|denied>
+                     本机长期记忆权限。
+                     本机非交互 -p 模式缺省为 read-only；显式传
+                     --memory-access local-owner（或 read-write）才允许写入。
+                     值拼错不会静默降级，会直接报错退出
+  --computer-use <observe|interactive>
+                     非交互模式默认禁用。observe 仅允许观察；interactive 开放基础
+                     键鼠，但剪贴板、文件投放和最终提交仍须在本次指令中明确提出
+  --computer-use-trace <dir>
+                     显式保存本次 Computer Use 的顺序事件与动作后截图，供问题复盘；
+                     目录含屏幕隐私数据，默认不开启
+  --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         显示帮助信息
+
+  所有带值标志两种写法等价："--output-format json" 与 "--output-format=json"。
+
+会话记忆:
+  按当前工作目录隔离，同一工作目录下可以有多个会话（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 结局
+  `);
+}
+
+main().catch((e) => {
+  process.stderr.write(`\n未捕获异常：${(e as Error).message}\n${(e as Error).stack ?? ''}\n`);
+  process.exit(1);
+});