minimal-agent 0.6.1 → 0.6.2

package/README.md

@@ -1,573 +1,231 @@
 # minimal-agent
 
-> 最小化的 AI 编程助手生态 —— ReAct CLI + 插件系统 + 可视化 workflow 编辑器
-> 10 个内置工具 · 23 个 Skills · 2 个内置插件 · OpenAI 兼容协议 · Ink TUI · Bun-first
+> 一个**最小化但功能完整**的 AI 编程助手 —— Bun + React + TypeScript + Ink TUI 构建，
+> OpenAI 兼容、多 provider，10 个内置工具 + Skills + 插件 + Workflow DSL + 自动上下文压缩。
+> 为**学习与教学**而生：代码量克制、注释充分，把一个 agent「从输入到工具循环到落盘」讲透。
 
-一个用于**学习和教学**的 Agent 项目，从 [kakadeai](../) 主仓库的 Claude Code 源码中抽取并简化而来，把"一个能调工具、能自动压缩上下文、能跑插件、能可视化编排 workflow 的 agent"在合理规模的 TypeScript 里讲清楚。
-
-> 项目由**两个独立的 npm 包**组成：`minimal-agent`（主体 ReAct CLI）+ `minimal-workflw`（可视化 workflow 编辑器）。两边只通过 `workflows/*.yaml` 文件耦合，零运行时依赖。
+`v0.5.1` · Runtime: **Bun**（主）/ Node ≥ 20 · License: **PolyForm Noncommercial 1.0.0**
 
 ---
 
-## 一图看全
+## 这是什么
+
+一个能在终端里跟你对话、并真正动手改代码的 AI agent。核心是一个 **AsyncGenerator 主循环**
+（`src/loop.ts`）：
 
 ```
-┌──────────────────────────────────────────────────────────────────┐
-│                       minimal-agent (主包)                       │
-│                                                                  │
-│   ┌─────────┐    ┌─────────┐    ┌─────────────┐                  │
-│   │ ReAct   │ ─→ │  Tools  │    │  Plugins/   │                  │
-│   │ runQuery│    │  10 个  │    │  ralph-loop │                  │
-│   └─────────┘    └─────────┘    │  workflow-* │                  │
-│        ↑                        └─────────────┘                  │
-│        │ 调用                          ↑                         │
-│        ↓                               │ 读                      │
-│   ┌─────────┐                          │                         │
-│   │ Skills/ │ ─── 23 个 SKILL.md ──────┘                         │
-│   └─────────┘                                                    │
-└──────────────────────────────────┬───────────────────────────────┘
-                                   │
-                                   ↓ 读写 workflows/*.yaml
-                                   │
-┌──────────────────────────────────┴───────────────────────────────┐
-│              minimal-workflw (独立编辑器包, editor/)                 │
-│                                                                  │
-│   Bun + Vite + React + React Flow                                │
-│   ┌────────┐  ┌────────┐  ┌────────┐                             │
-│   │ Palette│  │ Canvas │  │Inspector│                            │
-│   └────────┘  └────────┘  └────────┘                             │
-└──────────────────────────────────────────────────────────────────┘
+用户输入 → 调 LLM → LLM 要调工具就执行 → 结果喂回去 → 继续调 LLM → … → 不再调工具 → 输出最终回答
 ```
 
----
+每轮 `yield` 一个事件给 UI 实时刷新。上下文快撑爆时自动压缩成结构化摘要。麻雀虽小，
+工具系统、Skills、插件、Workflow、多 session、自动压缩、可编程子进程契约一应俱全。
 
 ## 特性
 
-| 模块 | 说明 |
-|---|---|
-| 🧠 主循环 | `runQuery` 用 AsyncGenerator 把"调 LLM → 跑工具 → 喂回去"串成一条流 |
-| 🔧 内置工具 (10) | Read / Edit / MultiEdit / Write / Glob / Grep / Bash / WebSearch / WebFetch / WebBrowser |
-| 📦 自动压缩 | 接近 context window 时自动摘要历史（auto / micro / reactive 三层） |
-| 💾 单上下文 | `~/.minimal-agent/last-context.json` 自动保存/恢复，无 session 概念 |
-| 🎨 双模式 | Ink TUI 交互模式 + `-p` 非交互 CLI 模式（管道友好） |
-| 🌐 多 provider | 走 OpenAI Chat Completions 协议，配 .env 即可切换 MiniMax / DeepSeek / Kimi / OpenAI |
-| 🧰 Skills 系统 (23) | 扫描 `skills/<name>/SKILL.md` frontmatter，按需懒加载完整 prompt |
-| 🔌 插件系统 | `plugins/<id>/` drop-in 目录，声明式命令 / 富插件双契约；自带 ralph-loop + workflow-runner |
-| 🎬 Workflow 引擎 | YAML DAG，7 种 step 类型（tool / llm / skill / assert / pause / branch / loop） |
-| 🖼️ 可视化编辑器 | 独立 `minimal-workflw` 包，拖拽组装 workflow，节点面板从 `src/tools/` + `skills/` 自动派生 |
-
----
-
-> ⚠️ **0.2.0 已发布到 npm 但插件系统不可用**（dynamic import .ts 在 node_modules 下被 Node 拒绝）。请使用 **0.3.0+**：源码 import 统一 `.js` 后缀 + tsc 原地编译，Bun（dev 模式）和 Node（install 模式）共用一份目录布局。
-
-## 系统要求
-
-- **Node.js ≥ 20**（npm install 后跑 bin 的运行时）或 **Bun ≥ 1.1**（推荐，dev 模式必需）
-- 一个 OpenAI 兼容的 LLM API（MiniMax / OpenAI / DeepSeek / Kimi / 自建 vLLM 均可）
-- *可选*：[Tavily](https://tavily.com) API key（开启 WebSearch）
-- *可选*：[OpenRouter](https://openrouter.ai) API key（用 `image-gen-openrouter` skill 生成图片）
-- *可选*：[MiniMax T2A](https://www.minimaxi.com/) 或 `pip install edge-tts`（用 `tts-zh` skill 做中文配音）
-- *可选*：`ffmpeg` + `ffprobe`（跑视频合成类 workflow）
-- *可选*：`playwright-core` + chromium（开启 WebBrowser；不装会自动降级到 WebFetch）
-- *无需安装 ripgrep* —— 项目自带 `vendor/ripgrep/` 6 个平台二进制（arm64/x64 × win32/darwin/linux）
+- **10 个内置工具**：Read / Write / Edit / MultiEdit / Glob / Grep / WebSearch / WebFetch / WebBrowser / Bash
+- **OpenAI 兼容**：Message 形状对齐 Chat Completions，一套代码接 MiniMax / 火山 ARK / DeepSeek / OpenAI / Moonshot…
+- **Skills 系统**：放一个 `SKILL.md` 就能扩展能力，运行时实时扫描注入 prompt，改文件即生效
+- **插件系统**：`plugins/<id>/` drop-in，自带 `/ralph-loop`（复制任务循环）与 `/workflow`（YAML DAG 执行器）
+- **自动上下文压缩**：接近上限时把旧对话压成摘要，保留系统提示 + 摘要 + 最近几条
+- **多 session + 归档**：同一工作目录多个并行会话，`/new` 归档、`/restore` 恢复
+- **可编程子进程**：`-p --output-format json` 输出一行结构化结局契约，方便被宿主程序 spawn 调度
+- **三种运行形态**：源码跑（dev）/ npm 全局安装 / **bun --compile 绿色单文件夹**（免安装，可装 U 盘）
 
 ---
 
-## 安装
-
-### A. 从 npm 安装（终端用户）
-
-```bash
-# 1. 装主包（ReAct CLI + 内置工具/插件/skills）
-npm install -g minimal-agent
-
-# 2. （可选）装可视化 workflow 编辑器
-#    ⚠ 当前 0.1 版编辑器 bin 直接吃 .ts，运行需要 Bun ≥1.1 在 PATH 上
-#    （主包 minimal-agent 在纯 Node 下完全可用，不依赖 Bun）
-npm install -g minimal-workflw      # 或：bun install -g minimal-workflw
-
-# 3. 跑起来
-minimal-agent                       # 启 TUI；首次会弹配置向导
-minimal-workflw ~/my-agent-project  # 在指定项目目录里启编辑器
-```
-
-两个包**独立发版、独立安装**。只想要 ReAct CLI 就装 `minimal-agent`；想拖拽编排 workflow 再加 `minimal-workflw`。两者通过 `<project>/workflows/*.yaml` 文件耦合，没有进程间通信。
+## 快速开始
 
-### B. 从源码运行（贡献者 / 想读源码）
+### 方式一：源码运行（推荐学习用）
 
 ```bash
 git clone https://github.com/billsoft/kakadeai.git
 cd kakadeai/minimal-agent
 bun install
-
-# 主体 ReAct CLI
-bun run start                       # TUI
-bun run src/main.tsx -p "hi"        # 非交互
-
-# Workflow 编辑器（另开终端）
-cd editor && bun install
-bun scripts/cli.ts --project ..     # 启编辑器并加载父项目的 workflows/
+cp .env.example .env        # 填入你的 API key（见下）
+bun run start               # 启动 TUI
 ```
 
----
+> 没装 Bun？见 https://bun.sh 。也可在缺 Bun 时用 Node 跑发布产物（见「三种运行形态」）。
 
-## 快速开始
-
-支持两种配置方式，**任选其一**即可：
-
-### 方式 A：手写 .env（适合开发者 / `-p` 非交互模式）
+### 方式二：全局安装后随处可用
 
 ```bash
-cp .env.example .env
-# 编辑 .env 填入 BASE_URL / API_KEY / MODEL
-bun run start
-```
-
-### 方式 B：首次启动配置向导（适合零配置上手）
-
-```bash
-bun run start    # 没检测到任何配置 → 自动弹 Ink 向导
+npm install -g minimal-agent
+minimal-agent                # 首次运行进入配置向导
 ```
 
-向导步骤：选 provider 预设（MiniMax / DeepSeek / OpenAI / Kimi / 自定义）→ 填 baseURL → 填 API key（掩码显示）→ 选 model → 自动做一次连通性测试 → 通过后写入 `~/.minimal-agent/config.json` 并直接进入对话界面。
-
-> 测试不通过或中途 ESC 退出 → **不写文件** → 下次启动继续走向导，直到成功为止。
+## 配置
 
-### 配置优先级
+两种方式任选其一（**环境变量优先级高于配置文件**）：
 
-```
-process.env  >  ~/.minimal-agent/config.json  >  弹向导
-```
+1. **`.env` 文件**（源码模式，Bun 自动加载）—— 复制 `.env.example` 改值。
+2. **配置向导** —— 首次运行 `minimal-agent`（TUI）会引导你填，写到 `~/.minimal-agent/config.json`。
 
-env 永远盖过 JSON，**逐字段**生效。`-p` 模式不会弹向导（没 TTY），缺配置直接 stderr 报错退出。
-
-### .env 字段
+必需三项 + 可选项：
 
 ```env
-# 必需
-MINIMAL_AGENT_BASE_URL=https://api.minimax.chat/v1
-MINIMAL_AGENT_API_KEY=your-api-key
-MINIMAL_AGENT_MODEL=MiniMax-M2.7
-
-# 可选
-MINIMAL_AGENT_PROVIDER=minimax           # 仅显示用，默认 "env"
-MINIMAL_AGENT_CONTEXT_WINDOW=204800      # 上下文窗口，默认 128000
-TAVILY_API_KEY=                          # 启用 WebSearch
-OPENROUTER_API_KEY=                      # 启用 image-gen-openrouter skill
-MINIMAX_API_KEY=                         # 启用 tts-zh skill（minimax 通道）
-MINIMAX_GROUP_ID=                        # 同上
-```
-
----
-
-## 命令行参数
-
-```
-minimal-agent [选项] [提示...]
-echo "提示" | minimal-agent [选项]
-
-选项:
-  -p, --print            非交互模式，问答一次后退出
-  -v, --verbose          显示工具调用 / 压缩详情
-  -d, --cwd <dir>        指定工作目录（不存在自动创建）
-  -h, --help             帮助
-  -V, --version          版本号
+MINIMAL_AGENT_BASE_URL=https://api.minimax.chat/v1   # 必需：API 地址
+MINIMAL_AGENT_API_KEY=your-api-key                   # 必需：API key
+MINIMAL_AGENT_MODEL=MiniMax-M2.7                     # 必需：模型名
+MINIMAL_AGENT_PROVIDER=minimax                       # 可选：友好名，默认 "env"
+MINIMAL_AGENT_CONTEXT_WINDOW=204800                  # 可选：上下文窗口，默认 128000
+TAVILY_API_KEY=                                      # 可选：WebSearch 工具用（https://tavily.com）
 ```
 
-TUI 内部支持：
-
-| 输入 | 效果 |
-|---|---|
-| `/new` | 清空历史，重建 system prompt；同时清掉当前工作目录下所有 `.minimal-agent*/` 状态目录 |
-| `/compact` | 手动压缩当前对话 |
-| `/config` | 重新配置 LLM provider（LLM 驱动 skill，必须单独输入） |
-| `/init` | 让 LLM 扫一遍项目目录，生成或更新 `minimal-agent.md` |
-| `/ralph-loop "<目标>" [...]` | 复制任务循环（plugin: ralph-wiggum） |
-| `/workflow <name> [--input k=v]` | 执行 workflow yaml（plugin: workflow-runner） |
-| `/workflows` | 列出可用 workflow |
-| `Alt+Enter` | 输入框换行 |
-| `ESC` / `Ctrl+C` | 中断当前任务 |
-
----
-
-## 内置工具（10 个）
-
-| 名称 | 用途 | 实现 |
-|---|---|---|
-| `Read` | 读文件（支持 offset / limit / 二进制嗅探） | `node:fs/promises` |
-| `Write` | 整体写文件（覆盖前要先 Read） | `node:fs/promises` |
-| `Edit` | 字符串精确替换（old_string 必须唯一） | `node:fs/promises` |
-| `MultiEdit` | 一次性多处替换（原子操作） | `node:fs/promises` |
-| `Glob` | 文件名模式匹配 | `fast-glob` |
-| `Grep` | 文件内容搜索 | spawn vendor 内置 ripgrep |
-| `Bash` | 终端命令执行（黑名单 + 超时双保险） | `node:child_process` |
-| `WebSearch` | Web 搜索（自动注入当前日期） | Tavily API |
-| `WebFetch` | 抓网页 → HTML→Markdown（LRU 缓存） | `fetch` + `turndown` |
-| `WebBrowser` | 浏览器交互（点击 / 填表单 / 截图 / JS 渲染） | playwright-core（**可选依赖**） |
-
-工具入口：`src/tools/index.ts` 的 `ALL_TOOLS`。
-
----
-
-## Skills 系统（23 个）
-
-每个 `skills/<name>/SKILL.md` 都是一段 LLM 子系统提示词 + frontmatter 元数据。框架在每轮组装 system prompt 时**实时扫描**目录注入 `name + description`，完整 body 按需懒加载（用户输入命中 description 触发词时才载入）。**新增 skill 改文件即可，不用改代码。**
-
-当前内置 skills：
-
-| 类别 | Skill |
-|---|---|
-| **配置 / 元** | `config` `init` `compact` `simplify` `batch` `skill-creator` `mcp-builder` |
-| **创作** | `algorithmic-art` `canvas-design` `frontend-design` `theme-factory` `web-artifacts-builder` `webapp-testing` |
-| **文档** | `docx` `pdf` `pptx` `xlsx` `diff` `commit` |
-| **多媒体流水线** | `image-gen-openrouter`（OpenRouter Nano Banana 文生图） `tts-zh`（MiniMax + edge-tts 中文配音） `subtitle-srt`（通用 SRT 字幕） `video-compose`（ffmpeg 视频合成） |
-
-**双源加载**：cwd 优先，packageRoot fallback。同名（frontmatter::name）时 cwd 覆盖。用户在自己项目里放 `skills/<name>/SKILL.md` 即可扩展或覆盖 npm 包自带的 skill。
+`.env.example` 里附了 **MiniMax / 火山 ARK / DeepSeek / OpenAI / Moonshot** 五套现成模板，注释切换即可。
 
 ---
 
-## 插件系统
-
-**硬约束**：`src/plugins/` 只放**框架**（discovery / 命令解析 / plugin.ts 加载 / hook 引擎 / transcript）；任何具体插件功能都住在各自的 `plugins/<id>/` 目录内。**新增插件 = 把目录 drop 进 `plugins/`，`src/` 一行不动。**
+## 使用
 
-### 内置插件
-
-#### `plugins/ralph-wiggum/` — `/ralph-loop`
-
-Karpathy 风格的复制任务循环：PLAN → BUILD → VERIFY → HEAL → DONE 五阶段 FSM，配合 verification gate 和 stop-hook 反馈。
+### 交互式 TUI
 
 ```bash
-/ralph-loop "在当前目录创建 hello.txt 内容为 hi" --max-iterations 5 --verify "file_exists:hello.txt"
+bun run start        # 或全局安装后直接 minimal-agent
 ```
 
-`--verify` 支持四种判据：`shell:<cmd>` / `file_exists:<path>` / `file_contains:<file>:<regex>` / `test_count:<N>`。FSM 状态文件落在 `<cwd>/.minimal-agent-ralph-wiggum/`，按当前 cwd 隔离，不同工作目录可并行。
+布局自上而下：消息列表（scrollback）→ 本轮过程区（流式思维链/工具进度）→ 输入框 → 状态栏。
+`ESC` / `Ctrl+C` 中断当前任务，`Alt+Enter` 输入框换行。
 
-#### `plugins/workflow-runner/` — `/workflow` `/workflows`
+**内置 slash 命令**（不走 LLM，UI 层直接拦截）：
 
-YAML DAG workflow 执行器，支持 7 种 step：
-
-| step 类型 | 用途 |
+| 命令 | 作用 |
 |---|---|
-| `tool` | 直接调内置工具（Read / Bash / Write …） |
-| `llm` | 单轮 LLM 调用（可 `capture` 输出到变量） |
-| `skill` | LLM 驱动子循环，body 当子 system prompt |
-| `assert` | 表达式断言（`fileExists(...)` / `length(...)` / 比较运算） |
-| `branch` | 条件分支 |
-| `loop` | 循环（`over:` + `as:` + 自动 `${as}_idx`） |
-| `pause` | 等待用户输入 |
-
-```bash
-/workflow youtube-shorts --input topic="猫咪赛博朋克城市探险"
-/workflow youtube-shorts "猫咪赛博朋克城市探险"   # 位置参数：按 inputs 声明顺序映射，.yaml 后缀可省
-/workflows                          # 列出所有 workflow
-```
-
-> ⚠ **位置参数依赖 yaml 文件 `inputs:` 数组的声明顺序**。重排 inputs 顺序会破坏所有现有 CLI 位置参数调用（位置参数会映射到错误的 input）。
-> 多 input workflow 推荐使用 `--input key=value` 显式 KV 形式，更稳。
-
-### 写自己的插件
-
-参考 `plugins/HOW-TO-WRITE-A-PLUGIN.md`。两种契约任选其一即可生效：
-
-- **声明式**（纯 markdown）：`plugins/<id>/commands/<cmd>.md` 用 frontmatter + prompt 模板，框架自动注册命令，零 TS 代码。
-- **富插件**：根目录写 `plugin.ts` 导出 `default { runCommand }`，由插件自己 yield `LoopEvent` 流（可调 `runQuery` / 跑循环 / 起子进程）。
-
-插件作者唯一稳定 import 路径：`from '../../src/plugin-sdk.ts'`。
-
----
-
-## minimal-workflw 可视化编辑器（editor/ 子项目）
+| `/new`（`/clear`） | 归档当前对话 → 清空 → 用最新 skills 重建 system prompt |
+| `/compact` | 手动压缩当前对话 |
+| `/session <name>` · `/sessions` | 切换 / 列出同目录下的并行会话 |
+| `/list-archive` · `/restore <id>` | 列出 / 恢复归档对话 |
+| `/show <id>` | 展开某次工具调用的完整输出（列表默认折叠到 3 行） |
+| `/exit`（`/quit`） | 退出 |
 
-独立的 npm 包，运行时与 `minimal-agent` **零耦合**，仅通过 `workflows/*.yaml` + `.editor-cache/manifest.json` 两个文件交换数据。
+`/init`、`/config` 等是 **LLM 驱动的 skill**；`/workflow`、`/ralph-loop` 是**插件命令**（见下）。
 
-### 启动方式
+### 非交互模式（`-p`）—— 脚本 / CI / 被宿主程序调用
 
 ```bash
-# 已全局安装时
-minimal-workflw                         # 当前 cwd 当 minimal-agent 项目根
-minimal-workflw ~/my-project            # 指定项目根
-minimal-workflw --refresh-manifest      # 强制刷新工具/skill 清单
-
-# 从源码跑（在 editor/ 目录下）
-bun scripts/cli.ts --project ..     # 一键起后端 + Vite
-bun run dev                         # 只起 Vite 前端（不带后端文件 IO）
-bun run server                      # 只起 Bun.serve() 后端
+minimal-agent -p "帮我写一个 hello world"
+echo "解释这段代码" | minimal-agent -p
+minimal-agent -p "处理资料" -d /tmp/job-123              # -d 隔离工作目录
+minimal-agent -p --output-format json "做点事"           # 一行结构化结局契约
 ```
 
-> **为什么是 `bun scripts/cli.ts` 而不是 `bun run dev`？**
-> - `bun run dev` 只起 Vite 前端，UI 能渲染但**没有后端**，文件列表 / 读写 / manifest 端点全是 404
-> - `bun scripts/cli.ts` 是 bin 入口，**同时**起 `Bun.serve()` 文件 IO 后端 + Vite 前端，完整可用
-> - npm 发布后用户执行的 `minimal-workflw` 命令就是这个 cli.ts
-
-### 启动序列（编辑器 CLI 内部）
-
-1. 解析 `--project`（默认 cwd）→ 验证目录存在 + `workflows/` 子目录存在
-2. 检查 `<project>/.editor-cache/manifest.json` 新鲜度，过期则 spawn `<project>/scripts/export-manifest.ts` 重新生成（脚本缺失时 fallback 到 `editor/public/manifest.fallback.json`）
-3. 启动 `Bun.serve()` 在 127.0.0.1:5174（文件 IO + manifest 端点）
-4. 启动 `bunx --bun vite` 在 127.0.0.1:5173
-
-### 解耦红线（D2 红线）
-
-- ❌ 编辑器**绝不** import `minimal-agent/src/*` 任何模块
-- ❌ minimal-agent 主程序**绝不**在启动路径里 spawn 编辑器
-- ✅ 接触面只有：`workflows/*.yaml`（双向）+ `.editor-cache/manifest.json`（单向，主项目→编辑器）
-
----
-
-## 示例：YouTube Shorts 生产流水线
-
-`workflows/youtube-shorts.yaml` 是一条端到端示例，演示如何在编辑器里拖出非编程用户场景：
-
-```
-输入主题
-  ↓
-LLM 写 5 幕剧本 (JSON)
-  ↓
-parse_script (jq 拆出 prompts.txt / narrations.txt)
-  ↓
-loop 5×: image-gen-openrouter   ──→ assets/img_0..4.png
-  ↓
-loop 5×: tts-zh                 ──→ assets/audio_0..4.mp3
-  ↓
-probe_durations + merge_audio   ──→ assets/audio.mp3
-  ↓
-subtitle-srt                    ──→ assets/subs.srt
-  ↓
-video-compose (ffmpeg)          ──→ out/shorts.mp4
-```
+| 选项 | 说明 |
+|---|---|
+| `-p` / `--print` | 非交互单次问答，输出后退出 |
+| `-v` / `--verbose` | stderr 显示工具调用、压缩等过程 |
+| `-d <dir>` / `--cwd <dir>` | 指定工作目录（不存在自动创建），隔离文件视图与会话 |
+| `--output-format <text\|json>` | `text`（默认，纯文本答案）/ `json`（一行结局契约） |
+| `--max-turns <n>` | 最大工具循环轮数（防失控，默认 50） |
+| `-V` / `--version` · `-h` / `--help` | 版本 / 帮助 |
 
-跑起来：
+**`--output-format json` 结局契约**（供宿主程序可靠 spawn）：
 
-```bash
-export OPENROUTER_API_KEY=sk-or-...
-bun run src/main.tsx -p "/workflow youtube-shorts --input topic='猫咪赛博朋克城市探险'"
+```json
+{ "ok": true, "result": "...", "is_error": false,
+  "stop_reason": "end_turn", "num_turns": 3, "error": null }
 ```
 
-整条流水线**零代码改动** —— 4 个 skill 都是 markdown，1 个 workflow 是 yaml。在 `minimal-workflw` 里打开 `youtube-shorts.yaml`，可视化拖拽改 prompt、换 skill、加节点。
+`ok = (stop_reason === 'end_turn')`；`stop_reason ∈ end_turn | max_turns | error | interrupted | config_error`。
+> ⚠️ `ok=true` 只代表「正常跑完未报错」，**不代表任务目标达成**——宿主应额外校验 `result` / 产物文件。
 
 ---
 
-## 项目结构
+## 工具
 
-```
-minimal-agent/
-├── src/                            # 主体内核
-│   ├── main.tsx                    #   入口：CLI 参数 + 模式分发
-│   ├── loop.ts                     #   Agent 主循环 (runQuery)
-│   ├── config.ts                   #   .env + ~/.minimal-agent/config.json
-│   ├── types.ts                    #   核心类型 (Message / Tool / LoopEvent)
-│   ├── plugin-sdk.ts               #   插件作者唯一稳定 import 路径
-│   ├── plugins/                    #   插件框架（discovery / loader / router / hooks）
-│   ├── llm/client.ts               #   OpenAI 兼容流式客户端
-│   ├── context/                    #   压缩 / 持久化 / token 计数
-│   ├── prompts/                    #   system prompt 拼装
-│   ├── tools/                      #   10 个内置工具
-│   └── ui/                         #   Ink TUI 组件
-├── plugins/                        # 实际插件（drop-in）
-│   ├── HOW-TO-WRITE-A-PLUGIN.md
-│   ├── ralph-wiggum/               #   /ralph-loop
-│   └── workflow-runner/            #   /workflow + /workflows
-├── skills/                         # 23 个 SKILL.md
-├── workflows/                      # YAML DAG 工作流定义
-│   ├── book-review-short.yaml
-│   ├── e2e-write-greet.yaml
-│   └── youtube-shorts.yaml
-├── editor/                         # minimal-workflw 独立子包
-│   ├── package.json                #   name: minimal-workflw, bin: minimal-workflw
-│   ├── scripts/
-│   │   ├── cli.ts                  #   bin 入口（一键起后端+前端）
-│   │   └── server.ts               #   Bun.serve() 文件 IO + manifest 端点
-│   ├── public/manifest.fallback.json
-│   └── src/                        #   React + React Flow + Monaco UI
-├── scripts/
-│   └── export-manifest.ts          # 主项目 → editor 的工具/skill 元数据导出
-├── vendor/ripgrep/                 # 自带 ripgrep 二进制（6 个平台）
-├── test/                           # bun test 用例
-└── minimal-agent.md                # 项目指令（类似 CLAUDE.md，自动注入 system prompt）
-```
-
----
-
-## 发布与安装（npm 工作流）
-
-项目作为**两个独立 npm 包**发布：
-
-| 包 | 路径 | 命令 | 职责 |
-|---|---|---|---|
-| `minimal-agent` | 仓库根 | `minimal-agent` | ReAct CLI + 工具 + 插件 + skills |
-| `minimal-workflw` | `editor/` | `minimal-workflw` | 可视化 workflow 编辑器 |
-
-> **为什么不打成一个包**？90% 的 ReAct CLI 用户不需要编辑器，编辑器的依赖（React / Vite / @xyflow/react / Monaco 等）有几十 MB，不应该污染主包。两边解耦后用户按需取用，通过 `<project>/workflows/*.yaml` 文件交流，无进程间通信。
-
-### 模块解析模式（dev vs install 通用范式）
-
-主包采用**标准 NodeNext + tsc 原地编译**模式，解决了 npm 包"dev 跑 .ts，install 跑 .js"的通用目录差异问题：
+| 工具 | 底层 | 说明 |
+|---|---|---|
+| **Read** | `node:fs` | 支持 offset/limit、二进制嗅探 |
+| **Write** | `node:fs` | 整体写入；覆盖前需先 Read |
+| **Edit** | `node:fs` | `old_string` 必须唯一 |
+| **MultiEdit** | `node:fs` | 单文件一次多处替换 |
+| **Glob** | `fast-glob` | 文件名 pattern |
+| **Grep** | 自带 `ripgrep` | 内容搜索，**自带 6 平台二进制**，开箱即用 |
+| **WebSearch** | Tavily API | 需 `TAVILY_API_KEY` |
+| **WebFetch** | `fetch` + `turndown` | HTML → Markdown，LRU 缓存 |
+| **WebBrowser** | `playwright-core`（可选） | 缺依赖时自动降级 WebFetch |
+| **Bash** | `child_process` | 黑名单 + 超时双保险 |
 
-- 源码（仓库 / dev）里 import 统一写 `.js` 后缀：`import { x } from './foo.js'`
-- dev 模式跑 `bun run dev`：Bun 把 `'./foo.js'` 透明解析到 `./foo.ts` 源文件，**无需任何构建**
-- publish 前 `tsc --build`：原地输出 `./foo.js`（与 .ts 兄弟位置，路径布局完全一致）
-- `.npmignore` 排除 `*.ts/*.tsx`，tarball 里**只发 .js**
-- install 后 Node 直接吃 .js，Bun 也吃 .js（行为统一）
-- 源码 `plugin.ts` 里 `import '../../src/plugin-sdk.js'` 在 dev / install 两种模式下都指向同一份模块（dev=plugin-sdk.ts，install=plugin-sdk.js），**模块身份天然 singleton**
+工具失败**不抛异常**——把 error 写进结果喂回 LLM 让它自己重试。
 
-这是 `execa` / `p-queue` / `ink` 等纯 ESM TypeScript 库的通用做法。
+## Skills · 插件 · Workflow
 
-### 用户安装（终端）
+- **Skills**：每个 `skills/<name>/SKILL.md`（带 frontmatter）。运行时实时扫描注入 prompt，prompt 体按需懒加载。
+  cwd 优先、包内 fallback，用户可在自己项目里覆盖或新增。内置 20+ 个（`/init`、`/config`、文档生成、设计等）。
+- **插件**（`plugins/<id>/`，drop-in，`src/` 一行不改）：
+  - **`/ralph-loop`**（ralph-wiggum）—— Karpathy 式复制任务循环，自带 PLAN/BUILD/VERIFY/HEAL 状态机 + 验证门
+  - **`/workflow` · `/workflows`**（workflow-runner）—— YAML DAG 执行器，9 种 step（tool/llm/skill/assert/branch/loop/pause/parallel/vote）
+- **可视化编辑器**：`editor/` 子项目（Bun + Vite + React Flow）拖拽编排 workflow YAML（不属于 npm 发布物）。
 
-```bash
-# 只装主包
-npm install -g minimal-agent
-minimal-agent                       # 启 ReAct TUI
+---
 
-# 加装编辑器
-npm install -g minimal-workflw
-minimal-workflw /path/to/your-project   # 启编辑器
-```
+## 三种运行形态
 
-### 开发者发布流程
+| 形态 | 怎么跑 | 适合 |
+|---|---|---|
+| **源码 dev** | `bun run dev`（Bun 直接吃 `.ts`，watch 热重载） | 学习、改源码 |
+| **npm 安装** | `npm i -g minimal-agent` → `minimal-agent`（Node 吃 tsc 编译的 `.js`） | 日常使用 |
+| **绿色版** | `bun run compile:green` → 单文件夹（内嵌运行时，**免装 Node/Bun**） | 免安装分发 / 装 U 盘 |
 
-#### 1. 发布主包
+**绿色版**把运行时 + 全部依赖 + 工具执行器编译进**单个可执行文件**，连同 `vendor/ripgrep`、`skills`、
+`workflows`、插件一起组装成「拷到任意机器即插即用」的文件夹；支持把 `config.json` 预置在目录里做到
+**零配置开箱即用**。三平台（Windows / macOS / Linux）各一份。详见 **[GREEN-BUILD.md](./GREEN-BUILD.md)**。
 
 ```bash
-cd minimal-agent
-npm version patch                   # 0.3.0 → 0.3.1
-npm publish --dry-run               # 验证 tarball（src/*.js + plugins/*.js + skills + workflows + vendor）
-npm publish                         # prepublishOnly 自动跑 clean + tsc --build
+bun run compile:green                 # 三主平台：win-x64 / mac-arm64 / linux-x64
+bun run compile:green:host            # 仅当前平台
+bun run compile:green -- --config 你的config.json   # 编译时烧录预配置
 ```
 
-主包 `package.json` 关键字段：
-
-```json
-{
-  "name": "minimal-agent",
-  "bin": { "minimal-agent": "src/main.js" },
-  "files": ["src", "plugins", "skills", "workflows", "vendor/ripgrep", "README.md", "LICENSE"],
-  "engines": { "node": ">=20" },
-  "scripts": {
-    "build": "tsc --build",
-    "clean": "bun scripts/clean-build.ts",
-    "prepublishOnly": "bun run clean && bun run build"
-  }
-}
-```
-
-`prepublishOnly` 先清旧产物再跑 tsc 原地编译，`.npmignore` 排除源码 .ts/.tsx 让 tarball 里**只有 .js**。`src/main.tsx` 首行 `#!/usr/bin/env node` 由 tsc 编译产物保留，直接作为 bin。
+---
 
-#### 2. 发布编辑器包
+## 开发
 
 ```bash
-cd minimal-agent/editor
-npm version patch
-bun run build                       # Vite 把前端打到 editor/dist/
-npm publish --dry-run
-npm publish
+bun install            # 安装依赖
+bun run start          # 运行（= bun run src/main.tsx）
+bun run dev            # watch 热重载
+bun test               # 跑所有测试
+bun run typecheck      # tsc --noEmit
+bun run build          # tsc --build → src/*.js + plugins/*.js（npm 发布用）
+bun run clean          # 删除原地编译产物
 ```
 
-编辑器是独立子项目，Bun 跑 `.ts` 源码作为 bin（`scripts/cli.ts` 首行有 `#!/usr/bin/env bun`），与主包发版策略不同但**目录耦合零依赖**——只通过文件系统读 `<project>/workflows/*.yaml`。
+格式/检查用 **Biome**（2 空格缩进、单引号、80 列）。模块解析 NodeNext：源码 import 统一写 `.js` 后缀，
+dev 下 Bun 透明回退到 `.ts` 兄弟，发布前 `tsc --build` 原地产出 `.js`。
 
-#### 3. 版本独立
+## 架构速览
 
-两个包的 version 字段**互相独立**，不必同步。改主包内核 → 只升主包；改编辑器 UI → 只升编辑器。
+| 模块 | 职责 |
+|---|---|
+| `src/loop.ts` | `runQuery()` 主循环（AsyncGenerator）—— 系统的「心脏」 |
+| `src/llm/client.ts` | OpenAI 兼容流式客户端（text / tool_call / reasoning 三路） |
+| `src/types.ts` | 对齐 Chat Completions 的 Message / ToolCall / 事件类型 |
+| `src/tools/` | 10 个工具 + `executeTool()` 参数防线（JSON.parse → Zod → call） |
+| `src/context/compact.ts` | 自动上下文压缩 |
+| `src/prompts/` | system prompt 组装 + Skills 实时扫描注入 |
+| `src/plugins/` | 插件框架（discovery / 命令路由 / hook 引擎 / transcript） |
+| `src/ui/` | Ink TUI（MessageList / LiveArea / InputBox / StatusLine） |
+| `src/config.ts` · `src/config/` | 分层 provider 配置（env → 配置文件） |
 
----
+> 给 Claude Code / 维护者的深入说明见 **[CLAUDE.md](./CLAUDE.md)**。
 
-## 工作原理（一句话版）
+## 目录结构
 
 ```
-用户输入
-  │
-  ▼
-runQuery (loop.ts)
-  │
-  ├── autoCompactIfNeeded   # 接近上限就压缩
-  ├── chat(LLM)             # 流式 token + tool_calls
-  ├── yield {text, ...}     # → UI 显示
-  │
-  ├── if 没工具 → return    # 任务完成
-  │
-  ├── for each tool_call:
-  │     executeTool         # zod 校验 → tool.call(args)
-  │     append tool result  # 写回 history
-  │
-  └── continue              # 下一轮
-```
-
-`/workflow` / `/ralph-loop` 这类插件命令在主循环**之前**被路由器拦截，由 `pluginRunner` 分发到对应插件的 `runCommand` 接管。详见 `src/loop.ts` + `src/plugins/pluginRunner.ts`。
-
----
-
-## 开发命令
-
-```bash
-# 主包
-bun run start                       # TUI
-bun run dev                         # 热重载
-bun test                            # 跑全部测试
-bun test test/llm.live.test.ts      # 单个测试文件
-bun run typecheck                   # tsc --noEmit
-bun run build                       # tsup 打包
-
-# 编辑器
-cd editor
-bun scripts/cli.ts --project ..     # 一键起后端 + 前端
-bun run dev                         # 只起前端
-bun run server                      # 只起后端
-bun test
+minimal-agent/
+├─ src/            # 主程序（loop / tools / llm / ui / plugins / config …）
+├─ skills/         # 内置 skill（每个一个 SKILL.md）
+├─ plugins/        # 内置插件（ralph-wiggum / workflow-runner）
+├─ workflows/      # 内置 workflow（YAML）
+├─ vendor/ripgrep/ # Grep 自带的 6 平台 ripgrep 二进制
+├─ scripts/        # 构建脚本（含绿色版 build-green.ts）
+├─ editor/         # workflow 可视化编辑器（独立子项目）
+├─ test/           # 测试
+├─ GREEN-BUILD.md  # 绿色版/U 盘分发指南
+└─ CLAUDE.md       # 架构与开发指南
 ```
 
----
-
-## 与 [kakadeai](../) 主项目的关系
-
-minimal-agent 是 Claude Code 源码的**教学版**：
-
-| 维度 | kakadeai/Claude Code | minimal-agent |
-|---|---|---|
-| 代码量 | 数十万行 | 数千行 |
-| 主循环 | QueryEngine + 状态机 | 单层 while + AsyncGenerator |
-| Tool 数 | 60+（含 MCP / Agent / Notebook 等） | 10 个内置 |
-| Skill 加载 | `registerBundledSkill()` 注册 | 扫描目录 + frontmatter 解析 |
-| Plugin | builtin / bundled plugin registry | drop-in `plugins/<id>/` 目录 |
-| Workflow | / | YAML DAG + 可视化编辑器 |
-| Provider | Anthropic SDK | OpenAI Chat Completions（多家兼容） |
-| UI | 完整 Ink 框架 + 主题系统 | 基础 Ink 组件 |
-
-设计目标是**砍掉一切非必要的抽象**，把"AI agent 是什么 / 怎么扩展"暴露在你眼前。
-
----
-
-## 故障排查
-
-| 现象 | 原因 / 处理 |
-|---|---|
-| `-p` 模式报 `缺少必需的环境变量` | `-p` 不弹向导。先用 `bun run start` 走向导，或手动写 `.env` |
-| TUI 启动就弹向导，但我已经写了 .env | 检查 .env 是否在项目根（`bun run` 当前目录），三项变量名拼写无误 |
-| 向导测试卡 `HTTP 401` / `HTTP 404` | 401 = API key 错；404 = baseURL 没拼 `/v1` 或 model id 不对 |
-| 改完 `~/.minimal-agent/config.json` 没生效 | 当前进程仍持有旧配置；Ctrl+C 退出后重新 `bun run start` |
-| `rg: command not found` | 不该出现——项目自带 ripgrep；若出现说明 vendor 目录未随 npm tarball 复制 |
-| `WebBrowser 报"无法启动浏览器"` | 需 `npm install playwright-core && npx playwright install chromium`；或改用 WebFetch |
-| `minimal-workflw` 命令找不到 | 没装编辑器包；`npm install -g minimal-workflw` 即可 |
-| 编辑器空白 / 节点面板没工具 | `.editor-cache/manifest.json` 缺失；`minimal-workflw --refresh-manifest` 强制刷新 |
-| 编辑器看不到自定义 skill | 检查 `<project>/skills/<name>/SKILL.md` frontmatter 是否有 `name` 和 `description` 两个必填字段 |
-| ffmpeg / ffprobe 未找到 | `winget install Gyan.FFmpeg` / `brew install ffmpeg` / `apt install ffmpeg` |
-| 历史"被吃掉"了 | 上次进程崩溃前未保存；`~/.minimal-agent/last-context.json` 是最后写入的一次 |
-
----
-
 ## License
 
-本项目使用 **PolyForm Noncommercial License 1.0.0**（详见根目录 `LICENSE` 文件）。
-
-**允许**：
-- 个人学习、教学、研究、非商业实验用途
-- 修改源代码、本地构建、自托管运行
-- 在非商业项目中引用 / fork
-- 慈善机构、教育机构、公共研究组织等非营利组织使用
-
-**禁止**：
-- 任何形式的商业使用（包括但不限于：销售本软件、用于公司内部生产环境、作为商业产品的组件、提供付费服务）
-- 未经授权的再分发（必须保留 LICENSE 与版权声明）
-
-如需商业授权，请联系作者另行洽谈。
-
-`vendor/ripgrep/` 内的二进制为上游 ripgrep 项目的 MIT / Unlicense 双重许可，**不受**本项目 PolyForm Noncommercial License 约束。
+[PolyForm Noncommercial License 1.0.0](./LICENSE) © 2026 billsoft。
+允许非商业用途的使用、修改与分发；商业用途请联系作者。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.6.1",
+  "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/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/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';

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;