minimal-agent 0.2.0 → 0.3.1

package/src/cli/print.js

@@ -0,0 +1,197 @@
+/**
+ * ============================================================
+ *  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 识别 LoopEvent + workflow_warning，其它走 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 'workflow_warning':
+            // workflow 引擎警告（如多余位置参数、--input 覆盖位置参数等）始终走 stderr，
+            // 不受 verbose 控制 —— 这是用户必须看到的信号，避免静默丢弃语义被忽略。
+            process.stderr.write(`${event.message}\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 {
+    }
+}

package/src/config.js

@@ -0,0 +1,118 @@
+/**
+ * ============================================================
+ *  config.ts —— 全局配置加载（从 .env 读取）
+ * ------------------------------------------------------------
+ *  只从环境变量读取，集中管理所有配置。
+ *
+ *  必需的环境变量：
+ *    MINIMAL_AGENT_BASE_URL   - API 地址，如 https://api.minimax.chat/v1
+ *    MINIMAL_AGENT_API_KEY    - API key
+ *    MINIMAL_AGENT_MODEL      - 模型名，如 MiniMax-M2.7
+ *
+ *  可选的环境变量：
+ *    MINIMAL_AGENT_PROVIDER   - 友好名称，默认 "env"
+ *    MINIMAL_AGENT_CONTEXT_WINDOW - 上下文窗口，默认 128000
+ * ============================================================
+ */
+import { readSavedConfig } from './config/configFile.js';
+const DEFAULT_CONTEXT_WINDOW = 128_000;
+/**
+ * 加载 Provider 配置（从环境变量）。
+ * 缺少必需变量时抛出明确错误。
+ */
+export async function loadProvider() {
+    const baseURL = process.env.MINIMAL_AGENT_BASE_URL;
+    const apiKey = process.env.MINIMAL_AGENT_API_KEY;
+    const model = process.env.MINIMAL_AGENT_MODEL;
+    if (!baseURL || !apiKey || !model) {
+        const missing = [];
+        if (!baseURL)
+            missing.push('MINIMAL_AGENT_BASE_URL');
+        if (!apiKey)
+            missing.push('MINIMAL_AGENT_API_KEY');
+        if (!model)
+            missing.push('MINIMAL_AGENT_MODEL');
+        throw new Error(`缺少必需的环境变量：${missing.join(', ')}\n\n` +
+            `请在 .env 中配置：\n` +
+            `  MINIMAL_AGENT_BASE_URL=https://api.example.com/v1\n` +
+            `  MINIMAL_AGENT_API_KEY=your-api-key\n` +
+            `  MINIMAL_AGENT_MODEL=your-model\n\n` +
+            `参考 .env.example`);
+    }
+    const contextWindowRaw = process.env.MINIMAL_AGENT_CONTEXT_WINDOW;
+    let contextWindow = DEFAULT_CONTEXT_WINDOW;
+    if (contextWindowRaw) {
+        const n = parseInt(contextWindowRaw, 10);
+        if (!Number.isNaN(n) && n > 0) {
+            contextWindow = n;
+        }
+    }
+    return {
+        name: process.env.MINIMAL_AGENT_PROVIDER ?? 'env',
+        baseURL,
+        apiKey,
+        model,
+        contextWindow,
+    };
+}
+/**
+ * 层级加载：env 优先（模式 A），不全则回退到 ~/.minimal-agent/config.json（模式 B）。
+ * 都没有时返回 null —— 调用方决定是触发向导还是直接退出。
+ *
+ * 与 loadProvider() 的区别：
+ *   - loadProvider() 只读 env，全缺则抛错（给 -p 模式用，明确告知"先做配置"）
+ *   - 本函数静默 fallback 到 JSON，全缺则返回 null（给 TUI 模式用，可触发向导）
+ *
+ * env 字段优先级是逐项的：只要 env 里有 BASE_URL 就用 env 的 BASE_URL，
+ * 其它字段从 JSON 补；这样用户可以临时用 env 覆盖单个字段做调试。
+ */
+export async function loadProviderLayered() {
+    const envBaseURL = process.env.MINIMAL_AGENT_BASE_URL;
+    const envApiKey = process.env.MINIMAL_AGENT_API_KEY;
+    const envModel = process.env.MINIMAL_AGENT_MODEL;
+    const envName = process.env.MINIMAL_AGENT_PROVIDER;
+    const envContextRaw = process.env.MINIMAL_AGENT_CONTEXT_WINDOW;
+    let saved = null;
+    if (!envBaseURL || !envApiKey || !envModel) {
+        saved = await readSavedConfig();
+    }
+    const baseURL = envBaseURL ?? saved?.baseURL;
+    const apiKey = envApiKey ?? saved?.apiKey;
+    const model = envModel ?? saved?.model;
+    if (!baseURL || !apiKey || !model)
+        return null;
+    let contextWindow = DEFAULT_CONTEXT_WINDOW;
+    if (envContextRaw) {
+        const n = parseInt(envContextRaw, 10);
+        if (!Number.isNaN(n) && n > 0)
+            contextWindow = n;
+    }
+    else if (saved?.contextWindow) {
+        contextWindow = saved.contextWindow;
+    }
+    return {
+        name: envName ?? saved?.provider ?? 'env',
+        baseURL,
+        apiKey,
+        model,
+        contextWindow,
+    };
+}
+/**
+ * 把 saved config 里的工具 key 注入 process.env（env 已设则不覆盖）。
+ *
+ * 解决 npm 全局安装场景：`node dist/main.js` 不会自动加载 .env，
+ * Tavily 之类的工具 key 只能从 ~/.minimal-agent/config.json 取出再写回 env，
+ * websearch.ts 才能在 call() 里读到。
+ *
+ * 应在 main() 最早期调用（initWorkingDir 之后即可），保证 ALL_TOOLS
+ * 任何 call() 触发前 env 已就位。
+ */
+export async function applyToolKeysToEnv() {
+    const saved = await readSavedConfig();
+    if (!saved)
+        return;
+    if (!process.env.TAVILY_API_KEY && saved.tavilyApiKey) {
+        process.env.TAVILY_API_KEY = saved.tavilyApiKey;
+    }
+}