minimal-agent 0.1.9 → 0.3.0

package/src/bootstrap/workingDir.js

@@ -0,0 +1,31 @@
+/**
+ * ============================================================
+ *  src/bootstrap/workingDir.ts —— 工作目录管理
+ * ------------------------------------------------------------
+ *  启动时一次性捕获 process.cwd()，后续所有"操作目录"统一通过
+ *  getWorkingDir() 读取，杜绝多处 process.cwd() 不一致的隐患。
+ *
+ *  设计选择：
+ *    - 模块级 state：单进程单 cwd，不需要 AsyncLocalStorage
+ *    - 锁定时机：main() 最开头，在加载 config / provider / history 之前
+ *    - 环境变量覆盖 MINIMAL_AGENT_CWD：测试 / docker / 显式 cd 场景
+ * ============================================================
+ */
+import { resolve } from 'node:path';
+let _workingDir = null;
+/** 首次调用锁定 cwd（解析 MINIMAL_AGENT_CWD），重复调用幂等。 */
+export function initWorkingDir() {
+    if (_workingDir !== null)
+        return _workingDir;
+    const override = process.env.MINIMAL_AGENT_CWD;
+    _workingDir = resolve(override ?? process.cwd());
+    return _workingDir;
+}
+/** 读取已锁定的工作目录；尚未 init 时退到 lazy init（主要给测试）。 */
+export function getWorkingDir() {
+    return _workingDir ?? initWorkingDir();
+}
+/** 仅供测试：重置 module-level state */
+export function _resetWorkingDir() {
+    _workingDir = null;
+}

package/src/cli/configWizard.js

@@ -0,0 +1,272 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * ============================================================
+ *  src/cli/configWizard.tsx —— 首次启动配置向导（Ink TUI）
+ * ------------------------------------------------------------
+ *  当 loadProviderLayered() 返回 null（env 和 ~/.minimal-agent/config.json 都没有
+ *  完整 provider 配置）时，由 Root.tsx 渲染本组件。
+ *
+ *  流程：
+ *    Step 1: 选 provider 预设（minimax / openai / deepseek / kimi / custom）
+ *    Step 2: 输入 baseURL（预设有默认值，用户可改）
+ *    Step 3: 输入 apiKey（不回显，用 * 替代）
+ *    Step 4: 输入 model（预设有候选）
+ *    Step 5: 连接测试（POST /chat/completions max_tokens=5）
+ *      - 通过 → saveConfig + onSuccess(provider) → Root 切到 App
+ *      - 失败 → 显示错误 + 回到 Step 1（保留已输入的值方便修改）
+ *
+ *  设计取舍：
+ *    - 不引第三方 prompt 库（@inquirer/prompts 等），用 Ink + useInput 手写，
+ *      保持"零新增依赖"承诺。
+ *    - 不做 spinner 动画，loading 时显示一行文字够用。
+ *    - 不做"返回上一步"，要修改请按 ESC 退出向导重跑（简化键位逻辑）。
+ *      —— 用户中途退出 = 不写文件 = 下次启动继续向导，符合需求 "直到成功为止"。
+ * ============================================================
+ */
+import { useCallback, useMemo, useState } from 'react';
+import { Box, Text, useApp, useInput } from 'ink';
+import { saveConfig } from '../config/configFile.js';
+// 兜底值：custom 或表外 model 都退到这里。
+// 与 src/config.ts 的同名常量含义对齐（"既没 env、saved 也没填 contextWindow" 的最终兜底）。
+const FALLBACK_CONTEXT_WINDOW = 128_000;
+const PRESETS = [
+    {
+        name: 'minimax',
+        label: 'MiniMax (海螺)',
+        baseURL: 'https://api.minimax.chat/v1',
+        models: ['MiniMax-M2.7', 'MiniMax-M1', 'abab6.5s-chat'],
+        contextWindow: 204_800,
+    },
+    {
+        name: 'deepseek',
+        label: 'DeepSeek',
+        baseURL: 'https://api.deepseek.com/v1',
+        models: ['deepseek-chat', 'deepseek-reasoner'],
+        contextWindow: 128_000,
+    },
+    {
+        name: 'openai',
+        label: 'OpenAI',
+        baseURL: 'https://api.openai.com/v1',
+        models: ['gpt-4o', 'gpt-4o-mini'],
+        contextWindow: 128_000,
+    },
+    {
+        name: 'moonshot',
+        label: 'Moonshot (Kimi)',
+        baseURL: 'https://api.moonshot.cn/v1',
+        models: ['moonshot-v1-8k', 'moonshot-v1-32k', 'moonshot-v1-128k'],
+        contextWindow: 128_000,
+        modelContextWindows: {
+            'moonshot-v1-8k': 8_000,
+            'moonshot-v1-32k': 32_000,
+            'moonshot-v1-128k': 128_000,
+        },
+    },
+    {
+        name: 'custom',
+        label: '自定义（手动填 baseURL）',
+        baseURL: '',
+        models: [],
+        contextWindow: FALLBACK_CONTEXT_WINDOW,
+    },
+];
+function resolveContextWindow(preset, model) {
+    return (preset.modelContextWindows?.[model] ??
+        preset.contextWindow ??
+        FALLBACK_CONTEXT_WINDOW);
+}
+export function ConfigWizard({ onSuccess }) {
+    const { exit } = useApp();
+    const [step, setStep] = useState('preset');
+    const [presetIndex, setPresetIndex] = useState(0);
+    const [baseURL, setBaseURL] = useState('');
+    const [apiKey, setApiKey] = useState('');
+    const [model, setModel] = useState('');
+    const [modelIndex, setModelIndex] = useState(0);
+    const [draft, setDraft] = useState('');
+    const [errorMsg, setErrorMsg] = useState(null);
+    const preset = PRESETS[presetIndex];
+    const enterStep = useCallback((next) => {
+        setErrorMsg(null);
+        if (next === 'baseURL')
+            setDraft(baseURL || preset.baseURL);
+        if (next === 'apiKey')
+            setDraft('');
+        if (next === 'model') {
+            if (preset.models.length > 0) {
+                setDraft(model || preset.models[0]);
+                setModelIndex(0);
+            }
+            else {
+                setDraft(model);
+            }
+        }
+        setStep(next);
+    }, [baseURL, model, preset]);
+    // handleTest 接受 finalModel 作为参数：
+    // Step 4 里调用方 `setModel(...) + handleTest()` 时，setModel 是异步的，handleTest
+    // 的 closure 还引用着旧的 model state；直接传 finalModel 才能避免"首次必跑两轮"
+    // —— 第一次发请求时 model 还是空串，API 报错，回到 Step 1 再走一遍才能成功。
+    //
+    // 测试通过后 **不立即** saveConfig + onSuccess，而是转去 Step 5（tavily）
+    // 让用户决定是否一并填 Tavily key，最后在 finalize() 一次性落盘。
+    const handleTest = useCallback(async (finalModel) => {
+        setStep('testing');
+        setErrorMsg(null);
+        try {
+            const url = `${baseURL.replace(/\/$/, '')}/chat/completions`;
+            const resp = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify({
+                    model: finalModel,
+                    messages: [{ role: 'user', content: 'ping' }],
+                    max_tokens: 5,
+                    stream: false,
+                }),
+            });
+            if (!resp.ok) {
+                const body = await resp.text().catch(() => '');
+                throw new Error(`HTTP ${resp.status}: ${body.slice(0, 200) || resp.statusText}`);
+            }
+            const data = (await resp.json());
+            if (!Array.isArray(data.choices)) {
+                throw new Error('响应中没有 choices 字段，可能不是 OpenAI 兼容协议');
+            }
+            setDraft('');
+            setStep('tavily');
+        }
+        catch (e) {
+            setErrorMsg(e.message || '连接失败');
+            setStep('error');
+        }
+    }, [apiKey, baseURL]);
+    // 落盘 + 切到 App。tavily key 为空表示用户跳过 WebSearch 配置。
+    const finalize = useCallback(async (finalModel, tavilyApiKey) => {
+        const contextWindow = resolveContextWindow(preset, finalModel);
+        await saveConfig({
+            baseURL,
+            apiKey,
+            model: finalModel,
+            provider: preset.name,
+            contextWindow,
+            tavilyApiKey,
+        });
+        // 立刻注入当前进程 env，让本会话内的 WebSearch 不必重启就能用
+        if (tavilyApiKey) {
+            process.env.TAVILY_API_KEY = tavilyApiKey;
+        }
+        onSuccess({
+            name: preset.name,
+            baseURL,
+            apiKey,
+            model: finalModel,
+            contextWindow,
+        });
+    }, [apiKey, baseURL, onSuccess, preset]);
+    useInput((input, key) => {
+        if (key.escape || (key.ctrl && input === 'c')) {
+            exit();
+            return;
+        }
+        if (step === 'preset') {
+            if (key.upArrow) {
+                setPresetIndex((i) => (i - 1 + PRESETS.length) % PRESETS.length);
+            }
+            else if (key.downArrow) {
+                setPresetIndex((i) => (i + 1) % PRESETS.length);
+            }
+            else if (key.return) {
+                enterStep('baseURL');
+            }
+            return;
+        }
+        if (step === 'baseURL') {
+            if (key.return) {
+                if (draft.trim().length === 0)
+                    return;
+                setBaseURL(draft.trim());
+                enterStep('apiKey');
+            }
+            else if (key.backspace || key.delete) {
+                setDraft((s) => s.slice(0, -1));
+            }
+            else if (input && !key.meta && !key.ctrl) {
+                setDraft((s) => s + input);
+            }
+            return;
+        }
+        if (step === 'apiKey') {
+            if (key.return) {
+                if (draft.length === 0)
+                    return;
+                setApiKey(draft);
+                enterStep('model');
+            }
+            else if (key.backspace || key.delete) {
+                setDraft((s) => s.slice(0, -1));
+            }
+            else if (input && !key.meta && !key.ctrl) {
+                setDraft((s) => s + input);
+            }
+            return;
+        }
+        if (step === 'model') {
+            if (preset.models.length > 0) {
+                if (key.upArrow) {
+                    const ni = (modelIndex - 1 + preset.models.length) % preset.models.length;
+                    setModelIndex(ni);
+                    setDraft(preset.models[ni]);
+                }
+                else if (key.downArrow) {
+                    const ni = (modelIndex + 1) % preset.models.length;
+                    setModelIndex(ni);
+                    setDraft(preset.models[ni]);
+                }
+                else if (key.tab) {
+                    setDraft((s) => s + '');
+                }
+            }
+            if (key.return) {
+                const finalModel = draft.trim();
+                if (finalModel.length === 0)
+                    return;
+                setModel(finalModel);
+                void handleTest(finalModel);
+            }
+            else if (key.backspace || key.delete) {
+                setDraft((s) => s.slice(0, -1));
+            }
+            else if (input && !key.meta && !key.ctrl && !key.upArrow && !key.downArrow) {
+                setDraft((s) => s + input);
+            }
+            return;
+        }
+        if (step === 'tavily') {
+            if (key.return) {
+                // 空 draft 表示用户跳过 WebSearch 配置（合法路径，不报错）
+                const tavilyApiKey = draft.trim().length > 0 ? draft.trim() : undefined;
+                void finalize(model, tavilyApiKey);
+            }
+            else if (key.backspace || key.delete) {
+                setDraft((s) => s.slice(0, -1));
+            }
+            else if (input && !key.meta && !key.ctrl) {
+                setDraft((s) => s + input);
+            }
+            return;
+        }
+        if (step === 'error') {
+            if (key.return) {
+                enterStep('preset');
+            }
+            return;
+        }
+    });
+    const maskedApiKey = useMemo(() => '*'.repeat(Math.min(draft.length, 32)), [draft]);
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(Box, { marginBottom: 1, children: _jsx(Text, { color: "cyan", bold: true, children: "minimal-agent \u00B7 \u9996\u6B21\u914D\u7F6E\u5411\u5BFC" }) }), _jsx(Box, { marginBottom: 1, children: _jsx(Text, { color: "gray", children: "\u6309 ESC \u6216 Ctrl+C \u9000\u51FA\uFF08\u4E0D\u5199\u914D\u7F6E\uFF0C\u4E0B\u6B21\u542F\u52A8\u7EE7\u7EED\u5411\u5BFC\uFF09" }) }), step === 'preset' && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: "Step 1/5 \u00B7 \u9009\u62E9 provider \u9884\u8BBE\uFF08\u2191\u2193 \u79FB\u52A8\uFF0CEnter \u786E\u8BA4\uFF09" }), _jsx(Box, { flexDirection: "column", marginTop: 1, children: PRESETS.map((p, i) => (_jsxs(Text, { color: i === presetIndex ? 'cyan' : undefined, children: [i === presetIndex ? '> ' : '  ', p.label, p.baseURL ? `  (${p.baseURL})` : ''] }, p.name))) })] })), step === 'baseURL' && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: "Step 2/5 \u00B7 \u8F93\u5165 API base URL\uFF08\u9ED8\u8BA4\u4E3A\u9884\u8BBE\u503C\uFF0C\u53EF\u6539\uFF09" }), _jsx(Box, { marginTop: 1, borderStyle: "round", borderColor: "cyan", paddingX: 1, children: _jsx(Text, { children: draft || ' ' }) }), _jsx(Text, { color: "gray", children: "Enter \u786E\u8BA4 \u00B7 Backspace \u5220\u9664" })] })), step === 'apiKey' && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: "Step 3/5 \u00B7 \u8F93\u5165 API key\uFF08\u8F93\u5165\u5185\u5BB9\u4E0D\u4F1A\u663E\u793A\uFF09" }), _jsx(Box, { marginTop: 1, borderStyle: "round", borderColor: "cyan", paddingX: 1, children: _jsx(Text, { children: maskedApiKey || ' ' }) }), _jsxs(Text, { color: "gray", children: ["Enter \u786E\u8BA4 \u00B7 Backspace \u5220\u9664\uFF08\u5DF2\u8F93\u5165 ", draft.length, " \u5B57\u7B26\uFF09"] })] })), step === 'model' && (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: ["Step 4/5 \u00B7 \u8F93\u5165\u6216\u9009\u62E9 model", preset.models.length > 0 ? '（↑↓ 切换预设，或直接编辑）' : ''] }), preset.models.length > 0 && (_jsx(Box, { flexDirection: "column", marginTop: 1, children: preset.models.map((m, i) => (_jsxs(Text, { color: i === modelIndex ? 'cyan' : 'gray', children: [i === modelIndex ? '> ' : '  ', m] }, m))) })), _jsx(Box, { marginTop: 1, borderStyle: "round", borderColor: "cyan", paddingX: 1, children: _jsx(Text, { children: draft || ' ' }) }), _jsx(Text, { color: "gray", children: "Enter \u63D0\u4EA4\u5E76\u6D4B\u8BD5\u8FDE\u63A5" })] })), step === 'testing' && (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { color: "yellow", children: ["\u23F3 \u6B63\u5728\u6D4B\u8BD5\u8FDE\u63A5 ", baseURL, " ..."] }), _jsxs(Text, { color: "gray", children: ["model = ", model] })] })), step === 'tavily' && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: "green", children: "\u2713 LLM \u8FDE\u63A5\u6D4B\u8BD5\u901A\u8FC7" }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { children: "Step 5/5 \u00B7 \u53EF\u9009 - Tavily API key\uFF08\u7528\u4E8E WebSearch \u5DE5\u5177\uFF09" }) }), _jsx(Box, { marginTop: 1, borderStyle: "round", borderColor: "cyan", paddingX: 1, children: _jsx(Text, { children: maskedApiKey || ' ' }) }), _jsx(Text, { color: "gray", children: "\u76F4\u63A5 Enter \u8DF3\u8FC7\uFF08\u4E4B\u540E\u53EF\u5728\u5BF9\u8BDD\u91CC\u8F93\u5165 /config \u6DFB\u52A0\uFF0C\u6216\u8BBE env TAVILY_API_KEY\uFF09" }), _jsxs(Text, { color: "gray", children: ["\u514D\u8D39 key \u7533\u8BF7\uFF1Ahttps://tavily.com/  \u00B7  \u5DF2\u8F93\u5165 ", draft.length, " \u5B57\u7B26"] })] })), step === 'error' && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: "red", children: "\u2717 \u8FDE\u63A5\u6D4B\u8BD5\u5931\u8D25" }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "red", children: errorMsg ?? '未知错误' }) }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "gray", children: "\u5DF2\u8F93\u5165\uFF1A" }) }), _jsxs(Text, { color: "gray", children: ["  provider = ", preset.name] }), _jsxs(Text, { color: "gray", children: ["  baseURL  = ", baseURL] }), _jsxs(Text, { color: "gray", children: ["  model    = ", model] }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "yellow", children: "\u6309 Enter \u56DE\u5230 Step 1 \u91CD\u8BD5 \u00B7 ESC \u9000\u51FA" }) })] }))] }));
+}

package/src/cli/print.js

@@ -0,0 +1,192 @@
+/**
+ * ============================================================
+ *  src/cli/print.ts —— CLI 非交互模式（-p / --print）
+ * ------------------------------------------------------------
+ *  不启动 Ink TUI，直接执行单次问答，流式输出到 stdout。
+ *  适合脚本集成、CI/CD、快速单次查询。
+ *
+ *  v2 改进（对齐 kakadeai CLI 工程实践）：
+ *    1. SIGINT 先保存 context 再退出（防丢失）
+ *    2. handleEvent 返回退出码，不直接 process.exit（单一职责）
+ *    3. EPIPE 保护：管道断开时静默退出不崩溃
+ *    4. stdin peek 超时：防止非 TTY 无管道时永久挂起
+ *
+ *  使用方式：
+ *    minimal-agent -p "提示"
+ *    echo "提示" | minimal-agent -p
+ *    minimal-agent -p --verbose "提示"
+ * ============================================================
+ */
+import { saveContext } from '../context/persistContext.js';
+import { runWithPlugins } from '../plugins/pluginRunner.js';
+/** stderr 显示工具结果时的截断阈值；超过即末尾加 "..." */
+const TOOL_OUTPUT_PREVIEW_MAX = 200;
+/** stdin 读取超时（ms），防止非 TTY + 无管道时永久挂起 */
+const STDIN_TIMEOUT_MS = 3000;
+function handleEPIPE(stream) {
+    return (err) => {
+        if (err.code === 'EPIPE')
+            stream.destroy();
+    };
+}
+export function truncateForDisplay(content, max = TOOL_OUTPUT_PREVIEW_MAX) {
+    if (content.length <= max)
+        return content;
+    return content.slice(0, max) + '...';
+}
+export function extractPromptArgs(args) {
+    // 布尔标志：直接过滤
+    const FLAG_BOOLEAN = new Set([
+        '-p',
+        '--print',
+        '--verbose',
+        '-v',
+        '-h',
+        '--help',
+        '-V',
+        '--version',
+    ]);
+    // 带值标志：本身 + 后面紧跟的值都要跳过
+    const FLAG_WITH_VALUE = new Set(['-d', '--cwd']);
+    const result = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (FLAG_BOOLEAN.has(a))
+            continue;
+        if (FLAG_WITH_VALUE.has(a)) {
+            i++; // 跳过 flag 后面的值
+            continue;
+        }
+        result.push(a);
+    }
+    return result;
+}
+/**
+ * CLI 非交互模式：读取 prompt，执行 runQuery，流式输出到 stdout，最后落盘 history。
+ */
+export async function runPrintMode(provider, args, initialHistory, options) {
+    // EPIPE 保护：管道断开时不崩溃（如 `bun -p "..." | head -1`）
+    process.stdout.on('error', handleEPIPE(process.stdout));
+    process.stderr.on('error', handleEPIPE(process.stderr));
+    const promptArgs = extractPromptArgs(args);
+    let prompt;
+    if (promptArgs.length > 0) {
+        prompt = promptArgs.join(' ');
+    }
+    else if (!process.stdin.isTTY) {
+        prompt = await readFromStdin();
+    }
+    else {
+        console.error('错误: 请提供提示文本或使用管道输入');
+        process.exit(1);
+    }
+    if (!prompt.trim()) {
+        console.error('错误: 提示不能为空');
+        process.exit(1);
+    }
+    const abortController = new AbortController();
+    let interrupted = false;
+    process.on('SIGINT', () => {
+        if (interrupted)
+            process.exit(130);
+        interrupted = true;
+        abortController.abort();
+        console.error('\n已中断');
+        void saveContext(initialHistory).finally(() => process.exit(130));
+    });
+    const history = initialHistory;
+    const output = { buffer: '' };
+    try {
+        for await (const event of runWithPlugins(prompt, {
+            provider,
+            history,
+            signal: abortController.signal,
+        })) {
+            // event 是 LoopEvent | PluginEvent；插件私有事件 handleEvent 走 default 静默忽略
+            const result = handleEvent(event, output, options.verbose);
+            if (result.exitCode !== undefined) {
+                await saveContext(history);
+                process.exit(result.exitCode);
+            }
+        }
+    }
+    catch (e) {
+        if (e.name === 'AbortError') {
+            await saveContext(history);
+            process.exit(130);
+        }
+        console.error(`\n未捕获异常: ${e.message}`);
+        await saveContext(history);
+        process.exit(1);
+    }
+    await saveContext(history);
+}
+/**
+ * 处理 runQuery yield 出来的 LoopEvent。
+ * 纯事件分发函数，返回 { exitCode? } 由调用方决定是否退出。
+ */
+export function handleEvent(event, output, verbose) {
+    switch (event.type) {
+        case 'text':
+            if (verbose)
+                process.stdout.write(event.delta);
+            output.buffer += event.delta;
+            return {};
+        case 'assistant_message':
+            return {};
+        case 'tool_start':
+            if (verbose) {
+                process.stderr.write(`\n🔧 工具: ${event.toolName}(${event.argsPreview})\n`);
+            }
+            return {};
+        case 'tool_end':
+            if (verbose) {
+                process.stderr.write(`${event.ok ? '✅' : '❌'} ${event.toolName}: ${truncateForDisplay(event.content)}\n`);
+            }
+            return {};
+        case 'compact_start':
+            if (verbose)
+                process.stderr.write('\n📝 正在压缩上下文...\n');
+            return {};
+        case 'compact_done':
+            if (verbose) {
+                process.stderr.write(`📝 压缩完成: ${event.before} → ${event.after} tokens\n`);
+            }
+            return {};
+        case 'turn_done':
+            if (!verbose)
+                console.log(output.buffer);
+            return {};
+        case 'error':
+            console.error(`\n错误: ${event.error}`);
+            return { exitCode: 1 };
+        default:
+            return {};
+    }
+}
+function readFromStdin() {
+    return new Promise((resolve) => {
+        let data = '';
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                resolve('');
+            }
+        }, STDIN_TIMEOUT_MS);
+        process.stdin.setEncoding('utf8');
+        function onData(chunk) {
+            data += chunk;
+        }
+        function onEnd() {
+            if (!settled) {
+                clearTimeout(timer);
+                settled = true;
+                resolve(data.trim());
+            }
+        }
+        process.stdin.on('data', onData);
+        process.stdin.on('end', onEnd);
+    });
+}
+export { readFromStdin };

package/src/config/configFile.js

@@ -0,0 +1,78 @@
+/**
+ * ============================================================
+ *  src/config/configFile.ts —— 模式 B 向导写的 provider 配置
+ * ------------------------------------------------------------
+ *  与 src/config.ts 的关系：
+ *    - config.ts 负责"读取 process.env 拼装 Provider"（模式 A）
+ *    - 本文件负责"读写 ~/.minimal-agent/config.json"（模式 B）
+ *    - 上层（loadProviderLayered）先看 env、再看本文件
+ *
+ *  与 src/context/persistContext.ts 的关系：
+ *    - 复用同一个目录 ~/.minimal-agent/
+ *    - 同样"解析失败返回 null、写失败静默"模式
+ *
+ *  为什么用 JSON 而非 .env 格式：
+ *    - 解析无歧义（dotenv 各家行为略有差异）
+ *    - 显式区分"向导写的" vs "用户写的 .env"，避免互相覆盖
+ *    - JSON 还可以放结构化扩展（如 savedAt 用于排查）
+ * ============================================================
+ */
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** 配置文件路径（带环境变量覆盖，主要给测试用） */
+export function getConfigFilePath() {
+    return (process.env.MINIMAL_AGENT_CONFIG_FILE ??
+        join(homedir(), '.minimal-agent', 'config.json'));
+}
+/**
+ * 读取向导保存的配置。
+ *  - 文件不存在 / JSON 损坏 / 必填字段缺失 → 返回 null
+ *  - 成功 → 返回 SavedConfig
+ */
+export async function readSavedConfig() {
+    const file = getConfigFilePath();
+    try {
+        const raw = await readFile(file, 'utf8');
+        const data = JSON.parse(raw);
+        if (typeof data.baseURL !== 'string' ||
+            typeof data.apiKey !== 'string' ||
+            typeof data.model !== 'string' ||
+            data.baseURL.length === 0 ||
+            data.apiKey.length === 0 ||
+            data.model.length === 0) {
+            return null;
+        }
+        return {
+            baseURL: data.baseURL,
+            apiKey: data.apiKey,
+            model: data.model,
+            provider: typeof data.provider === 'string' ? data.provider : undefined,
+            contextWindow: typeof data.contextWindow === 'number' && data.contextWindow > 0
+                ? data.contextWindow
+                : undefined,
+            tavilyApiKey: typeof data.tavilyApiKey === 'string' && data.tavilyApiKey.length > 0
+                ? data.tavilyApiKey
+                : undefined,
+            savedAt: typeof data.savedAt === 'number' ? data.savedAt : 0,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 写入向导收集到的配置。
+ * unix 上 chmod 600（仅本人可读写），Windows 上 chmod 是 no-op，靠 NTFS ACL。
+ */
+export async function saveConfig(cfg) {
+    const file = getConfigFilePath();
+    await mkdir(dirname(file), { recursive: true });
+    const data = { ...cfg, savedAt: Date.now() };
+    await writeFile(file, JSON.stringify(data, null, 2), 'utf8');
+    try {
+        await chmod(file, 0o600);
+    }
+    catch {
+    }
+}