minimal-agent 0.6.0 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "最小化 Agent 系统 —— 10 工具 + 插件系统 + workflow DSL + 自动压缩 + OpenAI 兼容 + Ink TUI；NodeNext + tsc 原地编译，dev 用 Bun .ts、install 用 Node .js（学习/教学用）",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Bill Wang <leiwang0359@gmail.com>",
@@ -54,6 +54,8 @@
     "clean": "bun scripts/clean-build.ts",
     "test": "bun test",
     "typecheck": "tsc --noEmit -p tsconfig.typecheck.json",
+    "compile:green": "bun scripts/build-green.ts",
+    "compile:green:host": "bun scripts/build-green.ts --host",
     "prepublishOnly": "bun run clean && bun run build"
   },
   "dependencies": {

package/src/cli/args.js

@@ -0,0 +1,33 @@
+/**
+ * ============================================================
+ *  src/cli/args.ts —— CLI 参数解析纯函数
+ * ------------------------------------------------------------
+ *  零依赖、零副作用的命令行参数提取工具，供 main.tsx 的 -p 分支使用。
+ *
+ *  为什么单独成文件（而非塞进 main.tsx）：
+ *    main.tsx 顶层有 `main().catch(...)` 自调用，一旦被 import 就会启动整个
+ *    应用。把纯函数抽出来，单测可零副作用地 import 断言。main.tsx re-export
+ *    同名符号，对外仍是「main.tsx 提供 extractFlagValue」的语义。
+ *
+ *  不引 commander：手撸即可，逻辑足够简单且教学清晰。
+ * ============================================================
+ */
+/**
+ * 从 args 里提取「带值标志」的值：找到 names 中任一标志，取其后**紧跟的下一个元素**当 value。
+ *
+ *   - 命中多次：取**第一次**出现的值
+ *   - 标志在末尾（后面没有元素）：返回 undefined（args[i+1] 天然是 undefined）
+ *   - 没命中任何 name：返回 undefined
+ *
+ * 例：extractFlagValue(['-p','--output-format','json','x'], ['--output-format']) === 'json'
+ *
+ * 用于 -p 模式提取 --output-format / --max-turns 的值。
+ */
+export function extractFlagValue(args, names) {
+    for (let i = 0; i < args.length; i++) {
+        if (names.includes(args[i])) {
+            return args[i + 1]; // 末尾标志时 args[i+1] 为 undefined，符合语义
+        }
+    }
+    return undefined;
+}

package/src/cli/print.js

@@ -2,8 +2,12 @@
  * ============================================================
  *  src/cli/print.ts —— CLI 非交互模式（-p / --print）
  * ------------------------------------------------------------
- *  不启动 Ink TUI，直接执行单次问答，流式输出到 stdout。
- *  适合脚本集成、CI/CD、快速单次查询。
+ *  不启动 Ink TUI，直接执行单次问答，最后落盘 history。
+ *  适合脚本集成、CI/CD、宿主程序（hermes/openclaw）spawn 调用。
+ *
+ *  两种输出格式（--output-format，默认 text）：
+ *    text —— 把最终回答原样打到 stdout（向后兼容，逐字节不变）
+ *    json —— stdout 只输出**一行** JSON 结局契约，其它诊断全走 stderr
  *
  *  v2 改进（对齐 kakadeai CLI 工程实践）：
  *    1. SIGINT 先保存 context 再退出（防丢失）
@@ -15,9 +19,10 @@
  *    minimal-agent -p "提示"
  *    echo "提示" | minimal-agent -p
  *    minimal-agent -p --verbose "提示"
+ *    minimal-agent -p --output-format json "提示"        # 结构化结局
  * ============================================================
  */
-import { saveContext } from '../context/persistContext.js';
+import { getContextPath, saveContext } from '../context/persistContext.js';
 import { runWithPlugins } from '../plugins/pluginRunner.js';
 /** stderr 显示工具结果时的截断阈值；超过即末尾加 "..." */
 const TOOL_OUTPUT_PREVIEW_MAX = 200;
@@ -56,7 +61,13 @@ export function extractPromptArgs(args) {
         '--version',
     ]);
     // 带值标志：本身 + 后面紧跟的值都要跳过
-    const FLAG_WITH_VALUE = new Set(['-d', '--cwd']);
+    // （--output-format / --max-turns 必须在此，否则它们的值会被当成 prompt 文本污染）
+    const FLAG_WITH_VALUE = new Set([
+        '-d',
+        '--cwd',
+        '--output-format',
+        '--max-turns',
+    ]);
     const result = [];
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
@@ -71,12 +82,62 @@ export function extractPromptArgs(args) {
     return result;
 }
 /**
- * CLI 非交互模式：读取 prompt，执行 runQuery，流式输出到 stdout，最后落盘 history。
+ * 输出 `-p --output-format json` 的结局契约（**一行** JSON 到 stdout）。
+ *
+ * ⚠️ 诚实声明：`ok=true` 只代表「Agent 正常跑完（stop_reason==='end_turn'）——
+ * 未报错、未被中断、未撞最大轮数」，**不代表任务目标真的达成**。工具失败会被
+ * 吞回 LLM 让它自行重试，LLM 完全可能在没产出有效结果的情况下正常收尾、给出
+ * end_turn。调用方（宿主程序）若要判断「任务是否真做成」，必须额外校验 `result`
+ * 文本内容 / 产物文件，不能只看 ok。
+ *
+ * 字段语义：
+ *   ok          = (stop_reason === 'end_turn')
+ *   result      = 累积的 assistant 文本
+ *   is_error    = !ok
+ *   stop_reason = end_turn | max_turns | error | interrupted | config_error
+ *   num_turns   = assistant_message 事件计数
+ *   error       = 失败文案（成功时 null）
+ *   session_file（可选）= 当前对话落盘路径；拿得到才填，拿不到省略该键
+ *
+ * 导出供单测断言。
+ */
+export function emitJsonResult(result, sessionFile) {
+    const stopReason = result.stopReason ?? 'error';
+    const ok = stopReason === 'end_turn';
+    console.log(JSON.stringify({
+        ok,
+        result: result.buffer,
+        is_error: !ok,
+        stop_reason: stopReason,
+        num_turns: result.numTurns,
+        error: result.error,
+        ...(sessionFile ? { session_file: sessionFile } : {}),
+    }));
+}
+/**
+ * 尝试拿当前会话落盘路径（给 json 契约的 session_file 字段）。
+ * 取不到（异常等）返回 undefined，emitJsonResult 据此省略该键（契约允许）。
+ */
+function trySessionFile() {
+    try {
+        return getContextPath();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * CLI 非交互模式：读取 prompt，执行 runQuery，最后落盘 history。
+ *
+ *  - text 模式：流式 / 收尾把答案打到 stdout（逐字节兼容旧行为）
+ *  - json 模式：stdout 只在退出时输出一行 JSON 结局契约（emitJsonResult）
  */
 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 outputFormat = options.outputFormat ?? 'text';
+    const isJson = outputFormat === 'json';
     const promptArgs = extractPromptArgs(args);
     let prompt;
     if (promptArgs.length > 0) {
@@ -95,53 +156,97 @@ export async function runPrintMode(provider, args, initialHistory, options) {
     }
     const abortController = new AbortController();
     let interrupted = false;
+    const history = initialHistory;
+    // text 模式只关心 buffer；json 模式还要 numTurns / stopReason / error。
+    // 用同一个对象承载，handleEvent 按 outputFormat 决定写哪些字段。
+    const result = {
+        buffer: '',
+        numTurns: 0,
+        stopReason: undefined,
+        error: null,
+    };
     process.on('SIGINT', () => {
         if (interrupted)
             process.exit(130);
         interrupted = true;
         abortController.abort();
         console.error('\n已中断');
-        void saveContext(initialHistory).finally(() => process.exit(130));
+        // json 模式：SIGINT 也要给出结构化结局（stop_reason='interrupted'）
+        if (isJson) {
+            result.stopReason = 'interrupted';
+            void saveContext(history).finally(() => {
+                emitJsonResult(result, trySessionFile());
+                process.exit(130);
+            });
+        }
+        else {
+            void saveContext(history).finally(() => process.exit(130));
+        }
     });
-    const history = initialHistory;
-    const output = { buffer: '' };
     try {
         for await (const event of runWithPlugins(prompt, {
             provider,
             history,
             signal: abortController.signal,
+            maxTurns: options.maxTurns,
         })) {
             // event 是 LoopEvent | PluginEvent；handleEvent 只认 LoopEvent，未识别的插件私有事件走 default 静默忽略
-            const result = handleEvent(event, output, options.verbose);
-            if (result.exitCode !== undefined) {
+            const handled = handleEvent(event, result, options.verbose, outputFormat);
+            if (handled.exitCode !== undefined) {
                 await saveContext(history);
-                process.exit(result.exitCode);
+                if (isJson)
+                    emitJsonResult(result, trySessionFile());
+                process.exit(handled.exitCode);
             }
         }
     }
     catch (e) {
         if (e.name === 'AbortError') {
             await saveContext(history);
+            if (isJson) {
+                result.stopReason = 'interrupted';
+                emitJsonResult(result, trySessionFile());
+            }
             process.exit(130);
         }
         console.error(`\n未捕获异常: ${e.message}`);
         await saveContext(history);
+        if (isJson) {
+            // 未分类异常按 error 收尾（stopReason 仍为空 → emitJsonResult 兜底 'error'）
+            result.error = result.error ?? e.message;
+            emitJsonResult(result, trySessionFile());
+        }
         process.exit(1);
     }
     await saveContext(history);
+    // json 模式：for-await 正常跑完（没有触发任何 exitCode 退出点）也要 emit 一行结局。
+    if (isJson)
+        emitJsonResult(result, trySessionFile());
 }
 /**
  * 处理 runQuery yield 出来的 LoopEvent。
  * 纯事件分发函数，返回 { exitCode? } 由调用方决定是否退出。
+ *
+ * @param result      累积态（buffer 始终累积；json 模式还会写 numTurns/stopReason/error）
+ * @param verbose     是否把工具/压缩诊断打到 stderr
+ * @param outputFormat 'text'（默认）逐字节兼容旧行为；'json' 时 stdout 静默（只在退出时由 emitJsonResult 输出）
+ *
+ * ⚠️ 向后兼容：旧调用方 `handleEvent(ev, output, verbose)` 三参不传 outputFormat，
+ *    默认 'text'，行为与改前逐字节一致。
  */
-export function handleEvent(event, output, verbose) {
+export function handleEvent(event, result, verbose, outputFormat = 'text') {
+    const isJson = outputFormat === 'json';
     switch (event.type) {
         case 'text':
-            if (verbose)
+            // text 模式：verbose 才流式写 stdout（与旧行为逐字节一致）。
+            // json 模式：绝不往 stdout 写任何东西（stdout 只允许最后那一行 JSON），仅累积 buffer。
+            if (verbose && !isJson)
                 process.stdout.write(event.delta);
-            output.buffer += event.delta;
+            result.buffer += event.delta;
             return {};
         case 'assistant_message':
+            // 一轮 assistant 消息完整组装 → 回合计数 +1（json 契约的 num_turns）
+            result.numTurns++;
             return {};
         case 'tool_start':
             if (verbose) {
@@ -168,16 +273,39 @@ export function handleEvent(event, output, verbose) {
             process.stderr.write(`${event.message}\n`);
             return {};
         case 'turn_done':
-            if (!verbose)
-                console.log(output.buffer);
+            // text 模式：非 verbose 时这里一次性把累积答案打到 stdout（旧行为，逐字节不变）。
+            // json 模式：只记 stopReason='end_turn'，stdout 保持静默。
+            result.stopReason = 'end_turn';
+            if (!isJson && !verbose)
+                console.log(result.buffer);
             return {};
         case 'error':
+            // compact_failed 是「非致命」信号：loop 压缩失败后会继续硬上（不 return），
+            // 这里**不退出**，只 stderr 警告 —— 对齐 loop 语义。
+            // （这同时修了一个旧瑕疵：之前 -p 收到该 error 会被误当致命退出。）
+            if (event.code === 'compact_failed') {
+                process.stderr.write(`${event.error}\n`);
+                return {};
+            }
+            // 其余 error 都是终结性的。
+            if (isJson) {
+                result.stopReason = event.code === 'max_turns' ? 'max_turns' : 'error';
+                result.error = event.error;
+                // json 模式不在这里打 stdout/stderr；由外层 emitJsonResult 统一输出
+                return { exitCode: 1 };
+            }
+            // text 模式：保持旧行为（红字 stderr + exitCode 1）
             console.error(`\n错误: ${event.error}`);
             return { exitCode: 1 };
+        case 'interrupted':
+            // 用户中断：json 模式记 stop_reason；外层退出点（catch / for-await 收尾 / SIGINT）emit。
+            // text 模式无需特殊处理（与旧行为一致：静默忽略，靠 SIGINT handler 退出）。
+            if (isJson)
+                result.stopReason = 'interrupted';
+            return {};
         // 已知但 -p 模式无需呈现的框架事件：显式忽略，好让 default 只剩"真正未知"的插件私有事件。
         case 'user_message_committed':
         case 'tool_messages_committed':
-        case 'interrupted':
         case 'plugin_progress':
         case 'reasoning':
         case 'stage_change':

package/src/config/configFile.js

@@ -20,18 +20,24 @@
 import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
-/** 配置文件路径（带环境变量覆盖，主要给测试用） */
+import { execSiblingDir } from '../utils/greenRoot.js';
+/**
+ * 配置文件的**写**路径（带环境变量覆盖，主要给测试用）。
+ * `saveConfig()` / 首次配置向导只写这里——env override 或 home，**绝不写 exe 同级**
+ * （U 盘可能只读，且不该污染产品目录）。读路径见 readSavedConfig 的分层。
+ */
 export function getConfigFilePath() {
     return (process.env.MINIMAL_AGENT_CONFIG_FILE ??
         join(homedir(), '.minimal-agent', 'config.json'));
 }
+/** home 默认配置路径（读分层的最后一档）。 */
+function homeConfigPath() {
+    return join(homedir(), '.minimal-agent', 'config.json');
+}
 /**
- * 读取向导保存的配置。
- *  - 文件不存在 / JSON 损坏 / 必填字段缺失 → 返回 null
- *  - 成功 → 返回 SavedConfig
+ * 解析单个 config.json：不存在 / JSON 损坏 / 必填字段缺失 → null；成功 → SavedConfig。
  */
-export async function readSavedConfig() {
-    const file = getConfigFilePath();
+async function parseConfigFile(file) {
     try {
         const raw = await readFile(file, 'utf8');
         const data = JSON.parse(raw);
@@ -61,6 +67,30 @@ export async function readSavedConfig() {
         return null;
     }
 }
+/**
+ * 读取已保存的 provider 配置（**分层**，按优先级返回第一个有效的）：
+ *   1. `MINIMAL_AGENT_CONFIG_FILE` 显式覆盖 —— **只读这一个，不 fallthrough**
+ *      （保持既有语义 + 测试隔离）
+ *   2. exe 同级 `config.json` —— **绿色版 / U 盘的卖家预置配置**（compile 后
+ *      `execSiblingDir()` = 真实 exe 目录；dev/npm 下是 node/bun 二进制目录、无此文件 → 跳过）
+ *   3. `~/.minimal-agent/config.json` —— 首次配置向导写出的（原行为）
+ *
+ * 这层让卖家把配好的 config.json 放进绿色目录即完成预配置，客户端零配置开箱即用
+ * （loadProviderLayered 拿到 provider → 不进向导、`-p` 不报 config_error）。
+ *
+ * 加性保证：dev / npm 模式无 override 时，exe 同级无 config.json → 只命中 home → 行为不变。
+ */
+export async function readSavedConfig() {
+    const override = process.env.MINIMAL_AGENT_CONFIG_FILE;
+    if (override)
+        return parseConfigFile(override);
+    for (const file of [join(execSiblingDir(), 'config.json'), homeConfigPath()]) {
+        const cfg = await parseConfigFile(file);
+        if (cfg)
+            return cfg;
+    }
+    return null;
+}
 /**
  * 写入向导收集到的配置。
  * unix 上 chmod 600（仅本人可读写），Windows 上 chmod 是 no-op，靠 NTFS ACL。

package/src/loop.js

@@ -70,7 +70,8 @@ export async function* runQuery(userInput, options) {
                 timestamp: Date.now(),
                 id: crypto.randomUUID(),
             });
-            yield { type: 'error', error: '已被用户中断' };
+            // code='aborted'：让 `-p --output-format json` 把终结原因映射成 stop_reason='interrupted'
+            yield { type: 'error', error: '已被用户中断', code: 'aborted' };
             return;
         }
         // 2. 自动压缩
@@ -88,10 +89,13 @@ export async function* runQuery(userInput, options) {
             }
         }
         catch (e) {
-            // 压缩失败不要让整个对话挂掉
+            // 压缩失败不要让整个对话挂掉。
+            // code='compact_failed'：标记为「非致命」——注意此处 yield error 后**不 return**，
+            // loop 继续往下跑（不压缩硬上）。`-p --output-format json` 据此只 stderr 警告、不退出。
             yield {
                 type: 'error',
                 error: `自动压缩失败（继续不压缩）：${e.message}`,
+                code: 'compact_failed',
             };
         }
         // 3. 调 LLM 并组装 assistant 消息
@@ -179,7 +183,12 @@ export async function* runQuery(userInput, options) {
                 }
                 // reactive 也失败 → 退回正常错误路径
             }
-            yield { type: 'error', error: `LLM 调用失败：${e.message}` };
+            // code='llm_error'：终结性错误，stop_reason='error'
+            yield {
+                type: 'error',
+                error: `LLM 调用失败：${e.message}`,
+                code: 'llm_error',
+            };
             return;
         }
         const assistantMsg = {
@@ -312,9 +321,11 @@ export async function* runQuery(userInput, options) {
         }
         // 6. 继续 while 让模型看到 tool_result 后继续推理
     }
+    // code='max_turns'：撞最大轮数上限而终结，stop_reason='max_turns'
     yield {
         type: 'error',
         error: `达到最大轮数 ${maxTurns}，提前结束（防止失控）。如果合理可以提高 maxTurns。`,
+        code: 'max_turns',
     };
 }
 // ---------------- 辅助函数 ----------------

package/src/main.js

@@ -5,7 +5,18 @@ 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');
+const pkg = (() => {
+    try {
+        return require('../package.json');
+    }
+    catch {
+        return {
+            version: typeof __GREEN_BUILD_VERSION__ === 'string'
+                ? __GREEN_BUILD_VERSION__
+                : '0.0.0',
+        };
+    }
+})();
 import { extractCwdArg } from './bootstrap/cwdArg.js';
 import { initWorkingDir, getWorkingDir } from './bootstrap/workingDir.js';
 import { applyToolKeysToEnv, loadProviderLayered } from './config.js';
@@ -15,6 +26,10 @@ 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';
+import { extractFlagValue } from './cli/args.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
@@ -46,10 +61,30 @@ async function main() {
     }
     const isPrintMode = args.includes('-p') || args.includes('--print');
     if (isPrintMode) {
+        // 先把输出格式解析出来——provider 缺失分支也要按 json 契约给信号。
+        // 只接受 'text' | 'json'，其它值（含拼错）一律回落 'text'（向后兼容）。
+        const rawFormat = extractFlagValue(args, ['--output-format']);
+        const outputFormat = rawFormat === 'json' ? '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;
         // 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',
+                }));
+            }
             process.stderr.write(`\n未找到 provider 配置。\n\n` +
                 `请二选一：\n` +
                 `  1. 设置环境变量 MINIMAL_AGENT_BASE_URL / MINIMAL_AGENT_API_KEY / MINIMAL_AGENT_MODEL\n` +
@@ -58,7 +93,7 @@ async function main() {
         }
         const initialHistory = await buildInitialHistory();
         const verbose = args.includes('--verbose') || args.includes('-v');
-        await runPrintMode(provider, args, initialHistory, { verbose });
+        await runPrintMode(provider, args, initialHistory, { verbose, outputFormat, maxTurns });
         return;
     }
     // TUI 交互模式：env 不全则 fallback 到 ~/.minimal-agent/config.json；
@@ -96,6 +131,9 @@ minimal-agent - 轻量级 AI 编程助手
   -v, --verbose      显示详细输出（工具调用、压缩信息）
   -d, --cwd <dir>    指定工作目录（不存在自动创建）；启动时 chdir 到这里，
                      上下文文件、工具相对路径、.env 加载都以此为基准
+  --output-format <fmt>  text（默认）= 纯文本答案；json = stdout 输出一行结构化
+                         结局契约（ok / result / stop_reason / num_turns / error）
+  --max-turns <n>    最大工具循环轮数（防失控；缺省 50）
   -h, --help         显示帮助信息
 
 会话记忆:
@@ -108,6 +146,7 @@ minimal-agent - 轻量级 AI 编程助手
   echo "解释代码" | minimal-agent -p
   minimal-agent -p --verbose "运行测试并报告结果"
   minimal-agent -p "处理资料" -d /tmp/job-123        # 工作目录隔离
+  minimal-agent -p --output-format json "做点事"     # 宿主程序 spawn：一行 JSON 结局
   `);
 }
 main().catch((e) => {

package/src/plugins/pluginLoader.js

@@ -24,9 +24,28 @@
  * ============================================================
  */
 import { existsSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 const loaderCache = new Map();
+/**
+ * 内置插件静态注册表（仅绿色版 compile 入口 entry.compiled.tsx 会填充）。
+ *
+ * 背景：`bun --compile` 后，rich 插件的 plugin.ts 顺链 import 的框架 SDK
+ * （`../../../src/plugin-sdk.js`）已被焊进 exe、磁盘上不存在 → 动态 import
+ * 外部 plugin.ts 必抛错。绿色版改为在 compile 入口**静态 import** 内置插件
+ * （`src/plugins/builtinRegistry.ts`），让 bun 把执行器整树打进 exe，再经
+ * setBuiltinPluginApi 注册到这里；loadPluginApi 在磁盘加载缺失/失败时回退到此表。
+ *
+ * dev / npm 模式：entry.compiled 永不被 import → 此表恒为空 → 回退分支不触发
+ * → loadPluginApi 行为与改动前逐字节一致。
+ *
+ * key = 插件目录名（`plugins/<id>/` 的 `<id>`，等于 `basename(pluginRoot)`）。
+ */
+const builtinApis = new Map();
+/** 由绿色版 compile 入口调用，注册内置插件执行器。dev/npm 不会调用。 */
+export function setBuiltinPluginApi(key, api) {
+    builtinApis.set(key, api);
+}
 function isPluginApi(value) {
     if (!value || typeof value !== 'object')
         return false;
@@ -62,8 +81,24 @@ export async function loadPluginApi(pluginRoot) {
             // stat 失败静默，不影响加载
         }
     }
+    // 绿色版回退：磁盘加载缺失/失败时，按目录名查 exe 内静态注册表。
+    // dev/npm 注册表恒空 → 永远返回 null → 不改变下方任何分支的最终结果。
+    const builtinKey = basename(pluginRoot);
+    const builtinFallback = () => {
+        const api = builtinApis.get(builtinKey);
+        if (api) {
+            loaderCache.set(pluginRoot, api);
+            return api;
+        }
+        return null;
+    };
     const pluginEntry = jsExists ? jsPath : tsExists ? tsPath : undefined;
     if (!pluginEntry) {
+        // 磁盘无 plugin.js/.ts：绿色目录只铺声明式部分（plugin.json + commands/），
+        // 执行器在 exe 内注册表 → 这里命中。dev/npm 注册表空 → 维持原 null。
+        const fb = builtinFallback();
+        if (fb)
+            return fb;
         loaderCache.set(pluginRoot, null);
         return null;
     }
@@ -79,6 +114,11 @@ export async function loadPluginApi(pluginRoot) {
         return candidate;
     }
     catch (err) {
+        // 绿色版：磁盘铺了 plugin.js 但它顺链 import 的框架 SDK 在 exe 内、磁盘没有
+        // → import 抛错 → 回退到 exe 内注册表。dev/npm 注册表空 → 维持原 warn + null。
+        const fb = builtinFallback();
+        if (fb)
+            return fb;
         console.warn(`[minimal-agent] failed to load plugin entry at ${pluginRoot}: ${err instanceof Error ? err.message : String(err)}`);
         loaderCache.set(pluginRoot, null);
         return null;

package/src/tools/grep/rgPath.js

@@ -26,6 +26,7 @@
 import { spawn } from 'node:child_process';
 import { chmodSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { execSiblingDir } from '../../utils/greenRoot.js';
 import { findPackageRoot } from '../../utils/packageRoot.js';
 let cached;
 /**
@@ -53,6 +54,15 @@ async function detect() {
         ensureExecutable(vendored);
         return vendored;
     }
+    // ②.5 绿色版（bun --compile 单文件）：exe 同级 vendor/ripgrep/<arch>-<platform>/rg
+    //   compile 后 import.meta.url 是虚拟路径，findPackageRoot 失效（② 命不中），
+    //   绿色目录把 vendor/ 摆在可执行文件旁边，从这里捞回来。dev/npm 下 exe 同级
+    //   没有 vendor/ → existsSync 过滤掉 → 不影响 ②/③/④ 原有优先级。
+    const sibling = resolve(execSiblingDir(), 'vendor', 'ripgrep', subdir(), exeName());
+    if (existsSync(sibling)) {
+        ensureExecutable(sibling);
+        return sibling;
+    }
     // ③ PATH 上的 rg —— 直接试 spawn rg --version
     if (await trySpawn('rg'))
         return 'rg';

package/src/utils/greenRoot.js

@@ -0,0 +1,33 @@
+/**
+ * ============================================================
+ *  src/utils/greenRoot.ts —— 绿色版(bun --compile 单文件)资源探测锚点
+ * ------------------------------------------------------------
+ *  问题：`bun build --compile` 把运行时 + 全部 JS 焊进单个可执行文件，
+ *  此时 `import.meta.url` 指向嵌入式虚拟路径（`/$bunfs/...`），磁盘上
+ *  既没有 package.json 也没有源码树 —— `findPackageRoot` 会抛错，靠它
+ *  定位的 `vendor/ripgrep/`、`skills/`、`plugins/`、`workflows/` 全失效。
+ *
+ *  方案：绿色版把这些外部资产与可执行文件**放在同一目录**，运行时用
+ *  `dirname(process.execPath)` 找回来（exe 同级）。
+ *
+ *  为什么 dev / npm 模式零影响：
+ *    - dev（`bun run src/main.tsx`）：execPath = bun 二进制，其同级目录
+ *      （如 `~/.bun/bin/`）没有 vendor/skills/plugins。
+ *    - npm 全局安装（`node dist/main.js`）：execPath = node 二进制，其
+ *      同级目录同样没有这些资源目录。
+ *    - 故调用方一律对返回值做 `existsSync` 过滤：dev/npm 下命不中 → 被
+ *      丢弃 → 行为与现状逐字节一致。只有真·绿色版（资产摆在 exe 旁边）
+ *      才会命中。因此这里**无条件返回** execPath 目录即可，无需判别
+ *      "是否 compiled"。
+ * ============================================================
+ */
+import { dirname } from 'node:path';
+/**
+ * 返回可执行文件所在目录（绿色版资产的同级锚点）。
+ *
+ * 调用方必须用 existsSync 过滤返回路径下的目标子目录 —— dev/npm 模式
+ * execPath 指向 node/bun 二进制，其同级没有资源目录，过滤后无副作用。
+ */
+export function execSiblingDir() {
+    return dirname(process.execPath);
+}

package/src/utils/resourcePaths.js

@@ -21,6 +21,7 @@
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { getWorkingDir } from '../bootstrap/workingDir.js';
+import { execSiblingDir } from './greenRoot.js';
 import { findPackageRoot } from './packageRoot.js';
 /**
  * 返回资源目录的搜索顺序数组（cwd 优先 + packageRoot fallback）。
@@ -35,6 +36,13 @@ export function getResourceSearchPaths(name, metaUrl) {
     if (existsSync(cwdPath)) {
         paths.push(cwdPath);
     }
+    // 绿色版（bun --compile 单文件）：exe 同级 <name>/ —— compile 后 findPackageRoot
+    // 失效，资源目录摆在可执行文件旁边从这里命中。dev/npm 下 exe 同级（node/bun
+    // 二进制所在目录）没有资源目录 → existsSync 过滤 → 数组与现状一致。
+    const sibPath = resolve(join(execSiblingDir(), name));
+    if (!paths.includes(sibPath) && existsSync(sibPath)) {
+        paths.push(sibPath);
+    }
     let pkgPath;
     try {
         pkgPath = resolve(join(findPackageRoot(metaUrl), name));
@@ -42,7 +50,7 @@ export function getResourceSearchPaths(name, metaUrl) {
     catch {
         return paths;
     }
-    if (pkgPath !== cwdPath && existsSync(pkgPath)) {
+    if (!paths.includes(pkgPath) && existsSync(pkgPath)) {
         paths.push(pkgPath);
     }
     return paths;