minimal-agent 0.2.0 → 0.3.1

package/src/loop.js

@@ -0,0 +1,230 @@
+/**
+ * ============================================================
+ *  src/loop.ts —— Agent 主循环（query loop）
+ * ------------------------------------------------------------
+ *  这是整个 agent 的"心脏"。一句话描述：
+ *
+ *    用户说话 → 调 LLM → LLM 想调工具就执行工具 → 把结果喂回去 → 继续调 LLM →
+ *    直到 LLM 不再调工具，输出最终回答。
+ *
+ *  和 kakadeai 主仓库 query.ts 用同样的 AsyncGenerator 模式：
+ *    - 函数是 async function*，可以 yield 各种事件给 UI
+ *    - UI 通过 for await 拿到事件，把它们映射到 React state
+ *
+ *  循环每轮（turn）做的事：
+ *    a. 自动压缩检查（防止 context 撑爆）
+ *    b. 调 LLM，把流式响应组装成完整的 assistant message
+ *    c. 如果 assistant 不调工具 → 结束，return
+ *    d. 否则按顺序执行每个工具调用，把 tool 消息追加到历史
+ *    e. 进入下一轮（让模型看到 tool_result 后继续推理）
+ *
+ *  失控保护：maxTurns（默认 50）。
+ *  中断支持：AbortSignal 透传到 chat() 和 tool.call()。
+ * ============================================================
+ */
+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';
+/**
+ * 执行一次"用户输入 → 模型回答完成"的完整流程。
+ *
+ * yield 出来的 LoopEvent 会被 UI 用来更新界面。
+ */
+export async function* runQuery(userInput, options) {
+    const { provider, history, signal, sessionState } = options;
+    const maxTurns = options.maxTurns ?? 50;
+    // 1. 用户消息入栈
+    history.push({ role: 'user', content: userInput });
+    // 反应式压缩自救：本 runQuery 只允许触发一次，避免压缩失败导致死循环。
+    // 配合 reactiveCompact.ts 的 attempted（session 级）双层防爆。
+    let reactiveAttempted = false;
+    let turn = 0;
+    while (turn < maxTurns) {
+        turn++;
+        incrementTurn(sessionState?.microCompact);
+        expireOldEntries(sessionState?.microCompact);
+        if (signal?.aborted) {
+            // 中断标记帮助模型理解上下文
+            history.push({
+                role: 'user',
+                content: '(用户按下了 ESC/Ctrl+C 中断了任务)',
+            });
+            yield { type: 'error', error: '已被用户中断' };
+            return;
+        }
+        // 2. 自动压缩
+        try {
+            const compact = await autoCompactIfNeeded(history, provider);
+            if (compact.compacted) {
+                yield { type: 'compact_start' };
+                // in-place 替换 history（保持调用方持有的引用有效）
+                history.length = 0;
+                history.push(...compact.messages);
+                yield { type: 'compact_done', before: compact.before, after: compact.after };
+            }
+        }
+        catch (e) {
+            // 压缩失败不要让整个对话挂掉
+            yield {
+                type: 'error',
+                error: `自动压缩失败（继续不压缩）：${e.message}`,
+            };
+        }
+        // 3. 调 LLM 并组装 assistant 消息
+        let assistantText = '';
+        /** 按 index 累积 tool_calls（OpenAI 协议下 tool_calls 是分片返回的） */
+        const toolCallsByIndex = [];
+        /**
+         * 思维链累积器。三个 provider 字段名各管一份；最后哪个非空就挂哪个，
+         * 多个非空就都挂上（不会冲突，下一轮请求时整个 message 透传给 API）。
+         */
+        let reasoningContent = '';
+        let reasoningString = '';
+        const reasoningDetails = [];
+        try {
+            for await (const ev of chat({
+                provider,
+                messages: history,
+                tools: ALL_TOOLS,
+                signal,
+            })) {
+                if (ev.type === 'text_delta') {
+                    assistantText += ev.delta;
+                    yield { type: 'text', delta: ev.delta };
+                }
+                else if (ev.type === 'tool_call_delta') {
+                    mergeToolCallDelta(toolCallsByIndex, ev);
+                }
+                else if (ev.type === 'reasoning_delta') {
+                    if (ev.field === 'reasoning_content' && ev.delta) {
+                        reasoningContent += ev.delta;
+                    }
+                    else if (ev.field === 'reasoning' && ev.delta) {
+                        reasoningString += ev.delta;
+                    }
+                    else if (ev.field === 'reasoning_details' && ev.items) {
+                        reasoningDetails.push(...ev.items);
+                    }
+                }
+                // ev.type === 'done' 时无需处理：循环自然结束
+            }
+        }
+        catch (e) {
+            if (e.name === 'AbortError') {
+                // 用户主动中断：记录标记消息，不报红色错误
+                history.push({
+                    role: 'user',
+                    content: '(用户按下了 ESC/Ctrl+C 中断了任务)',
+                });
+                yield { type: 'interrupted' };
+                return;
+            }
+            // prompt_too_long 反应式自救：压缩历史 → 同 turn 重发 LLM
+            // LLM 看到压缩后的 9 段摘要 + 近期 verbatim 消息，能接着干活，
+            // 不会丢失中途的工具调用上下文。
+            if (isPromptTooLongError(e) && !reactiveAttempted) {
+                reactiveAttempted = true;
+                yield { type: 'compact_start' };
+                const result = await reactiveCompactIfApplicable(history, provider, e, sessionState?.reactive);
+                if (result.recovered) {
+                    history.length = 0;
+                    history.push(...result.messages);
+                    yield {
+                        type: 'compact_done',
+                        before: result.before ?? 0,
+                        after: result.after ?? 0,
+                    };
+                    turn--; // 不消耗 turn 配额，本轮重新走
+                    continue;
+                }
+                // reactive 也失败 → 退回正常错误路径
+            }
+            yield { type: 'error', error: `LLM 调用失败：${e.message}` };
+            return;
+        }
+        const assistantMsg = {
+            role: 'assistant',
+            content: assistantText.length > 0 ? assistantText : null,
+            ...(toolCallsByIndex.length > 0 ? { tool_calls: toolCallsByIndex } : {}),
+            ...(reasoningContent ? { reasoning_content: reasoningContent } : {}),
+            ...(reasoningString ? { reasoning: reasoningString } : {}),
+            ...(reasoningDetails.length > 0 ? { reasoning_details: reasoningDetails } : {}),
+        };
+        history.push(assistantMsg);
+        yield { type: 'assistant_message', message: assistantMsg };
+        // 4. 没有工具调用 → 整轮交互结束
+        if (toolCallsByIndex.length === 0) {
+            yield { type: 'turn_done' };
+            return;
+        }
+        // 5. 顺序执行每个工具
+        for (const tc of toolCallsByIndex) {
+            if (signal?.aborted) {
+                // 中断标记帮助模型理解上下文：为什么输出被截断，用户可以重新输入
+                history.push({
+                    role: 'user',
+                    content: '(用户按下了 ESC/Ctrl+C 中断了任务)',
+                });
+                yield { type: 'error', error: '已被用户中断' };
+                return;
+            }
+            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 rawContent = result.ok ? result.content : `Error: ${result.error}`;
+            const content = microCompact(tc.function.name, rawContent, sessionState?.microCompact);
+            // 工具结果作为 tool 消息回填
+            history.push({
+                role: 'tool',
+                content,
+                tool_call_id: tc.id,
+            });
+            yield {
+                type: 'tool_end',
+                toolName: tc.function.name,
+                toolCallId: tc.id,
+                ok: result.ok,
+                content,
+            };
+        }
+        // 6. 继续 while 让模型看到 tool_result 后继续推理
+    }
+    yield {
+        type: 'error',
+        error: `达到最大轮数 ${maxTurns}，提前结束（防止失控）。如果合理可以提高 maxTurns。`,
+    };
+}
+// ---------------- 辅助函数 ----------------
+/** 把一条 tool_call_delta 合并到累积数组上 */
+function mergeToolCallDelta(acc, ev) {
+    let slot = acc[ev.index];
+    if (!slot) {
+        slot = {
+            id: '',
+            type: 'function',
+            function: { name: '', arguments: '' },
+        };
+        acc[ev.index] = slot;
+    }
+    if (ev.id)
+        slot.id = ev.id;
+    if (ev.name)
+        slot.function.name += ev.name;
+    if (ev.argumentsDelta)
+        slot.function.arguments += ev.argumentsDelta;
+}
+/** 给 UI 展示用的参数预览（只取前 60 字符） */
+function previewArgs(rawJson) {
+    const oneLine = rawJson.replace(/\s+/g, ' ').trim();
+    if (oneLine.length <= 60)
+        return oneLine;
+    return oneLine.slice(0, 60) + '...';
+}

package/src/main.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+import { render } from 'ink';
+import { existsSync, mkdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+import { extractCwdArg } from './bootstrap/cwdArg.js';
+import { initWorkingDir, getWorkingDir } from './bootstrap/workingDir.js';
+import { applyToolKeysToEnv, loadProviderLayered } from './config.js';
+import { loadContext } from './context/persistContext.js';
+import { migrateLegacyContext } from './context/sessionPath.js';
+import { buildFullSystemPrompt } from './prompts/system.js';
+import { ALL_TOOLS } from './tools/index.js';
+import { Root } from './ui/Root.js';
+import { runPrintMode } from './cli/print.js';
+async function main() {
+    // ★ -d/--cwd：在锁定工作目录之前先建目录 + chdir，让后续逻辑全在 -d 下运行
+    //   不存在则自动 mkdir -p；后续 initWorkingDir() 自然拿到新 cwd
+    const args = 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;
+    }
+    const isPrintMode = args.includes('-p') || args.includes('--print');
+    if (isPrintMode) {
+        // CLI 非交互模式：先 env，再 ~/.minimal-agent/config.json fallback；都没就退出
+        // （宿主 spawn 子进程时通常没 export env，靠 TUI 向导写出的 config.json 持久化）
+        const provider = await loadProviderLayered();
+        if (!provider) {
+            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);
+        }
+        const initialHistory = await buildInitialHistory();
+        const verbose = args.includes('--verbose') || args.includes('-v');
+        await runPrintMode(provider, args, initialHistory, { verbose });
+        return;
+    }
+    // TUI 交互模式：env 不全则 fallback 到 ~/.minimal-agent/config.json；
+    // 都没有则 Root 渲染配置向导。
+    const initialProvider = await loadProviderLayered();
+    const { waitUntilExit } = render(_jsx(Root, { initialProvider: initialProvider }));
+    await waitUntilExit();
+}
+/**
+ * 启动时构造 history：用当前 cwd / 工具的最新 system prompt，
+ * 后面接上 last-context.json 里上次保存的对话（如果有）。
+ *
+ * 总是用 fresh system prompt（即便 last-context.json 里也存了一份），
+ * 这样换 cwd 或工具后也不会沿用错的环境上下文。
+ */
+async function buildInitialHistory() {
+    const content = await buildFullSystemPrompt(getWorkingDir(), ALL_TOOLS);
+    const fresh = { role: 'system', content };
+    const persisted = await loadContext();
+    if (!persisted || persisted.length === 0)
+        return [fresh];
+    const rest = persisted[0]?.role === 'system' ? persisted.slice(1) : persisted;
+    return [fresh, ...rest];
+}
+function printHelp() {
+    console.log(`
+minimal-agent - 轻量级 AI 编程助手
+
+用法:
+  minimal-agent [选项] [提示...]
+  echo "提示" | minimal-agent [选项]
+
+选项:
+  -p, --print        非交互模式，直接执行单次问答
+  -v, --verbose      显示详细输出（工具调用、压缩信息）
+  -d, --cwd <dir>    指定工作目录（不存在自动创建）；启动时 chdir 到这里，
+                     上下文文件、工具相对路径、.env 加载都以此为基准
+  -h, --help         显示帮助信息
+
+会话记忆:
+  按当前工作目录隔离，自动加载 / 保存到
+  ~/.minimal-agent/sessions/<目录哈希>.json
+  TUI 与 -p 共享同一目录的上下文；TUI 中输入 /new 仅清当前目录的会话
+
+示例:
+  minimal-agent -p "帮我写一个 hello world"
+  echo "解释代码" | minimal-agent -p
+  minimal-agent -p --verbose "运行测试并报告结果"
+  minimal-agent -p "处理资料" -d /tmp/job-123        # 工作目录隔离
+  `);
+}
+main().catch((e) => {
+    process.stderr.write(`\n未捕获异常：${e.message}\n${e.stack ?? ''}\n`);
+    process.exit(1);
+});

package/src/plugin-sdk.js

@@ -0,0 +1,24 @@
+/**
+ * ============================================================
+ *  src/plugin-sdk.ts —— 插件作者的稳定 import 门面
+ * ------------------------------------------------------------
+ *  Drop-in 插件契约的"窄门"：插件根目录下的 plugin.ts 只允许从
+ *  '../../src/plugin-sdk.js' 取运行时（NodeNext 标准，Bun 自动回退到 .ts
+ *  源文件，Node 跑 install 后编译产物），不直接访问 src/ 内部路径。
+ *
+ *  好处：
+ *   - 框架内部重构（loop.ts / llm/client.ts / tools/* 移动）不破坏插件
+ *   - 插件作者只需记一个 import 源
+ *   - 暴露面收口（这里没的 API 不开放给插件）
+ *
+ *  零运行时开销：纯 re-export，TS 编译后等价于直接 import。
+ * ============================================================
+ */
+// --- 运行时入口 ---
+export { runQuery } from './loop.js';
+export { chat } from './llm/client.js';
+export { ALL_TOOLS, executeTool, getToolByName } from './tools/index.js';
+export { getWorkingDir } from './bootstrap/workingDir.js';
+export { getResourceSearchPaths } from './utils/resourcePaths.js';
+export { triggerHook } from './plugins/hookEngine.js';
+export { createSessionState } from './session/sessionState.js';

package/src/plugins/commandRouter.js

@@ -0,0 +1,169 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getResourceSearchPaths } from '../utils/resourcePaths.js';
+const pluginCache = new Map();
+let discoveryDone = false;
+function stripQuotes(s) {
+    const trimmed = s.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+function parseMarkdownFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return {};
+    const frontmatter = {};
+    for (const line of match[1].split('\n')) {
+        const colon = line.indexOf(':');
+        if (colon < 0)
+            continue;
+        const key = line.slice(0, colon).trim();
+        const value = line.slice(colon + 1).trim();
+        if (key)
+            frontmatter[key] = stripQuotes(value);
+    }
+    return frontmatter;
+}
+async function loadPlugin(pluginDirPath) {
+    const dirName = pluginDirPath.split('/').pop() ?? pluginDirPath;
+    const manifestPath = join(pluginDirPath, '.claude-plugin', 'plugin.json');
+    let manifestName = dirName;
+    let manifestVersion;
+    let manifestDesc;
+    try {
+        const raw = await readFile(manifestPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        manifestName = parsed.name ?? dirName;
+        manifestVersion = parsed.version;
+        manifestDesc = parsed.description;
+    }
+    catch {
+    }
+    const commandsDir = join(pluginDirPath, 'commands');
+    const commands = [];
+    try {
+        const entries = await readdir(commandsDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.name.endsWith('.md'))
+                continue;
+            const cmdPath = join(commandsDir, entry.name);
+            try {
+                const content = await readFile(cmdPath, 'utf8');
+                const fm = parseMarkdownFrontmatter(content);
+                const sep = content.indexOf('\n---', 4);
+                const body = sep >= 0 ? content.slice(sep + 4).trim() : content.trim();
+                commands.push({
+                    name: entry.name.replace(/\.md$/, ''),
+                    description: fm.description ?? '(no description)',
+                    argumentHint: fm['argument-hint'],
+                    pluginName: manifestName,
+                    pluginRoot: pluginDirPath,
+                    promptBody: body,
+                });
+            }
+            catch {
+            }
+        }
+    }
+    catch {
+    }
+    const hooksJsonPath = join(pluginDirPath, 'hooks', 'hooks.json');
+    let hasStopHook = false;
+    try {
+        const hooksRaw = await readFile(hooksJsonPath, 'utf8');
+        const hooksParsed = JSON.parse(hooksRaw);
+        const stopHooks = hooksParsed?.hooks?.Stop;
+        if (Array.isArray(stopHooks) && stopHooks.length > 0) {
+            hasStopHook = true;
+        }
+    }
+    catch {
+    }
+    if (commands.length === 0 && !hasStopHook)
+        return null;
+    return {
+        name: manifestName,
+        version: manifestVersion,
+        description: manifestDesc,
+        root: pluginDirPath,
+        commands,
+        hasStopHook,
+    };
+}
+export async function discoverPlugins() {
+    if (discoveryDone && pluginCache.size > 0) {
+        return Array.from(pluginCache.values());
+    }
+    pluginCache.clear();
+    discoveryDone = true;
+    // 双源扫描：cwd 优先 + packageRoot fallback；按数组顺序处理，已有 manifestName 跳过
+    const searchPaths = getResourceSearchPaths('plugins', import.meta.url);
+    for (const root of searchPaths) {
+        try {
+            const entries = await readdir(root, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                if (entry.name.startsWith('.'))
+                    continue;
+                const plugin = await loadPlugin(join(root, entry.name));
+                if (!plugin)
+                    continue;
+                if (pluginCache.has(plugin.name))
+                    continue; // cwd 已注册的 manifestName，packageRoot 同名跳过
+                pluginCache.set(plugin.name, plugin);
+            }
+        }
+        catch {
+        }
+    }
+    return Array.from(pluginCache.values());
+}
+/** 仅供测试：重置 discovery cache。 */
+export function _resetPluginCache() {
+    pluginCache.clear();
+    discoveryDone = false;
+}
+export function resolveCommand(input) {
+    const trimmed = input.trimStart();
+    if (!trimmed.startsWith('/'))
+        return null;
+    const spaceIdx = trimmed.indexOf(' ', 1);
+    const cmdName = spaceIdx >= 0 ? trimmed.slice(1, spaceIdx) : trimmed.slice(1);
+    const args = spaceIdx >= 0 ? trimmed.slice(spaceIdx + 1) : '';
+    for (const plugin of pluginCache.values()) {
+        for (const cmd of plugin.commands) {
+            if (cmd.name === cmdName) {
+                return { cmd, arguments: args };
+            }
+        }
+    }
+    return null;
+}
+export function buildCommandInput(resolved) {
+    const { cmd, arguments: args } = resolved;
+    let input = cmd.promptBody;
+    input = input.replaceAll('${CLAUDE_PLUGIN_ROOT}', cmd.pluginRoot);
+    input = input.replaceAll('$ARGUMENTS', args);
+    input = input.replaceAll('${ARGUMENTS}', args);
+    if (args.trim()) {
+        input += `\n\n用户参数: ${args.trim()}`;
+    }
+    return input;
+}
+export function listAvailableCommands() {
+    const result = [];
+    for (const plugin of pluginCache.values()) {
+        for (const cmd of plugin.commands) {
+            result.push({
+                command: `/${cmd.name}`,
+                plugin: plugin.name,
+                description: cmd.description,
+            });
+        }
+    }
+    return result;
+}