minimal-agent 0.1.9 → 0.3.0

package/README.md

@@ -1,8 +1,43 @@
 # minimal-agent
 
-> 最小化的 AI 编程助手 —— 单对话 · 9 个内置工具 · 自动压缩 · OpenAI 兼容协议 · Ink TUI
+> 最小化的 AI 编程助手生态 —— ReAct CLI + 插件系统 + 可视化 workflow 编辑器
+> 10 个内置工具 · 23 个 Skills · 2 个内置插件 · OpenAI 兼容协议 · Ink TUI · Bun-first
 
-一个用于**学习和教学**的 Agent 项目，从 [kakadeai](../) 主仓库的 Claude Code 源码中抽取并简化而来，把"一个能调工具、能自动压缩上下文、能流式输出的 agent"在 ~3000 行 TypeScript 内讲清楚。
+一个用于**学习和教学**的 Agent 项目，从 [kakadeai](../) 主仓库的 Claude Code 源码中抽取并简化而来，把"一个能调工具、能自动压缩上下文、能跑插件、能可视化编排 workflow 的 agent"在合理规模的 TypeScript 里讲清楚。
+
+> 项目由**两个独立的 npm 包**组成：`minimal-agent`（主体 ReAct CLI）+ `minimal-workflw`（可视化 workflow 编辑器）。两边只通过 `workflows/*.yaml` 文件耦合，零运行时依赖。
+
+---
+
+## 一图看全
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                       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│                            │
+│   └────────┘  └────────┘  └────────┘                             │
+└──────────────────────────────────────────────────────────────────┘
+```
 
 ---
 
@@ -11,25 +46,71 @@
 | 模块 | 说明 |
 |---|---|
 | 🧠 主循环 | `runQuery` 用 AsyncGenerator 把"调 LLM → 跑工具 → 喂回去"串成一条流 |
-| 🔧 内置工具 | Read / Write / Edit / Glob / Grep / Bash / WebSearch / WebFetch / WebBrowser |
+| 🔧 内置工具 (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 系统 | 扫描 `skills/<name>/SKILL.md` frontmatter，按需懒加载完整 prompt |
+| 🧰 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 模式）共用一份目录布局。
+
 ## 系统要求
 
-- **Bun ≥ 1.1**（推荐，主运行时）；Node.js ≥ 20 需要走 build 流程，见末尾的[发布到 npm](#发布到-npm未来) 章节
+- **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）
 
 ---
 
+## 安装
+
+### 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/
+```
+
+---
+
 ## 快速开始
 
 支持两种配置方式，**任选其一**即可：
@@ -37,21 +118,14 @@
 ### 方式 A：手写 .env（适合开发者 / `-p` 非交互模式）
 
 ```bash
-# 1. 安装依赖
-bun install
-
-# 2. 配置 .env（参考 .env.example）
 cp .env.example .env
 # 编辑 .env 填入 BASE_URL / API_KEY / MODEL
-
-# 3. 启动 TUI
 bun run start
 ```
 
 ### 方式 B：首次启动配置向导（适合零配置上手）
 
 ```bash
-bun install
 bun run start    # 没检测到任何配置 → 自动弹 Ink 向导
 ```
 
@@ -59,20 +133,13 @@ bun run start    # 没检测到任何配置 → 自动弹 Ink 向导
 
 > 测试不通过或中途 ESC 退出 → **不写文件** → 下次启动继续走向导，直到成功为止。
 
-### 运行示例
-
-```bash
-bun run src/main.tsx -p "帮我写个 hello world"   # 一次性问答
-echo "解释这段代码" | bun run src/main.tsx -p     # 管道输入
-```
-
 ### 配置优先级
 
 ```
 process.env  >  ~/.minimal-agent/config.json  >  弹向导
 ```
 
-env 永远盖过 JSON，**逐字段**生效（可以只用 env 临时覆盖单个字段做调试）。`-p` 模式不会弹向导（没 TTY），缺配置直接 stderr 报错退出。
+env 永远盖过 JSON，**逐字段**生效。`-p` 模式不会弹向导（没 TTY），缺配置直接 stderr 报错退出。
 
 ### .env 字段
 
@@ -83,17 +150,14 @@ MINIMAL_AGENT_API_KEY=your-api-key
 MINIMAL_AGENT_MODEL=MiniMax-M2.7
 
 # 可选
-MINIMAL_AGENT_PROVIDER=minimax           # 仅作显示用，默认 "env"
-MINIMAL_AGENT_CONTEXT_WINDOW=204800      # 模型上下文窗口，默认 128000
+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=                        # 同上
 ```
 
-### 重新配置
-
-在 TUI 内直接输入 `/config`（不带任何其他内容），LLM 会按 `skills/config/SKILL.md` 流程逐项询问后用 Write 工具更新 `~/.minimal-agent/config.json`，提示重启生效。
-
-> `/config` 是 **LLM 驱动的 skill**（同 `/init`），不是硬编码命令（不同于 `/new` / `/compact`）—— 必须**单独输入 `/config`**，带其他内容（如 `/config 帮我看看`）不会触发。
-
 ---
 
 ## 命令行参数
@@ -103,60 +167,179 @@ minimal-agent [选项] [提示...]
 echo "提示" | minimal-agent [选项]
 
 选项:
-  -p, --print        非交互模式，问答一次后退出
-  -v, --verbose      显示工具调用 / 压缩详情
-  -h, --help         帮助
-  -V, --version      版本号
+  -p, --print            非交互模式，问答一次后退出
+  -v, --verbose          显示工具调用 / 压缩详情
+  -d, --cwd <dir>        指定工作目录（不存在自动创建）
+  -h, --help             帮助
+  -V, --version          版本号
 ```
 
 TUI 内部支持：
 
 | 输入 | 效果 |
 |---|---|
-| `/new` | 清空历史，重建 system prompt（带最新 skills + 项目指令）；同时清掉当前工作目录下所有 `.minimal-agent*/` 状态目录 |
+| `/new` | 清空历史，重建 system prompt；同时清掉当前工作目录下所有 `.minimal-agent*/` 状态目录 |
 | `/compact` | 手动压缩当前对话 |
-| `/config` | 重新配置 LLM provider（LLM 驱动 skill，单独输入才触发） |
-| `/ralph-loop "<目标>" [--max-iterations N] [--verify ...]` | 复制任务循环（PLAN→BUILD→VERIFY→HEAL→DONE 五阶段 FSM）；按当前 cwd 隔离，不同工作目录可并行 |
-| `Alt+Enter` | 输入框换行（教学/多行 prompt 友好） |
+| `/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` | 中断当前任务 |
 
-### `/ralph-loop` 速查
-
-最小用法：
-
-```bash
-/ralph-loop "在当前目录创建 hello.txt 内容为 hi" --max-iterations 5 --verify "file_exists:hello.txt"
-```
-
-参数：
-- `--max-iterations N` — 用户上限，默认 50，硬天花板 200
-- `--verify <type>:<args>` — 完成判据，支持四种 type：
-  - `shell:<cmd>` —— 命令退出码 0 即通过（跨平台 spawn）
-  - `file_exists:<path>` —— 文件存在即通过（相对路径以当前 cwd 为锚）
-  - `file_contains:<file>:<regex>` —— 文件内容匹配正则即通过
-  - `test_count:<N>` —— 跑 `bun test` 并解析 "X pass"，X≥N 即通过
-
-agent 通过输出 `<promise>DONE</promise>` 哨兵声明完成，验证通过才真正退出；声明完成但验证不过会回 BUILD 阶段继续干，连续 3 次失败强转 HEAL 阶段。若 agent 判断方案不可行，可输出 `<PROMISE>NEED_REPLAN</PROMISE>` 强制回 PLAN 重新规划。
-
-FSM 状态文件落在 `<cwd>/.minimal-agent-ralph-wiggum/`（`goal.md` / `phase.md` / `progress.md` / `learnings.md` / `decisions.md` / `completion.md`），循环结束或 `/new` 时自动清理。Windows / macOS / Linux 都能跑。
-
 ---
 
-## 内置工具
+## 内置工具（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（**可选依赖**） |
+| `WebBrowser` | 浏览器交互（点击 / 填表单 / 截图 / JS 渲染） | playwright-core（**可选依赖**） |
 
-工具入口：`src/tools/index.ts` 的 `ALL_TOOLS` 数组和 `executeTool()` 函数。
+工具入口：`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。
+
+---
+
+## 插件系统
+
+**硬约束**：`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 反馈。
+
+```bash
+/ralph-loop "在当前目录创建 hello.txt 内容为 hi" --max-iterations 5 --verify "file_exists:hello.txt"
+```
+
+`--verify` 支持四种判据：`shell:<cmd>` / `file_exists:<path>` / `file_contains:<file>:<regex>` / `test_count:<N>`。FSM 状态文件落在 `<cwd>/.minimal-agent-ralph-wiggum/`，按当前 cwd 隔离，不同工作目录可并行。
+
+#### `plugins/workflow-runner/` — `/workflow` `/workflows`
+
+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="猫咪赛博朋克城市探险"
+/workflows                          # 列出所有 workflow
+```
+
+### 写自己的插件
+
+参考 `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/ 子项目）
+
+独立的 npm 包，运行时与 `minimal-agent` **零耦合**，仅通过 `workflows/*.yaml` + `.editor-cache/manifest.json` 两个文件交换数据。
+
+### 启动方式
+
+```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() 后端
+```
+
+> **为什么是 `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
+```
+
+跑起来：
+
+```bash
+export OPENROUTER_API_KEY=sk-or-...
+bun run src/main.tsx -p "/workflow youtube-shorts --input topic='猫咪赛博朋克城市探险'"
+```
+
+整条流水线**零代码改动** —— 4 个 skill 都是 markdown，1 个 workflow 是 yaml。在 `minimal-workflw` 里打开 `youtube-shorts.yaml`，可视化拖拽改 prompt、换 skill、加节点。
 
 ---
 
@@ -164,31 +347,124 @@ FSM 状态文件落在 `<cwd>/.minimal-agent-ralph-wiggum/`（`goal.md` / `phase
 
 ```
 minimal-agent/
-├── src/
-│   ├── main.tsx                    # 入口：CLI 参数解析 + 模式分发
-│   ├── loop.ts                     # Agent 主循环（runQuery）
-│   ├── config.ts                   # .env 加载
-│   ├── types.ts                    # 核心类型（Message / Tool / LoopEvent）
-│   ├── cli/print.ts                # -p 非交互模式
-│   ├── llm/client.ts               # OpenAI 兼容流式客户端
-│   ├── context/                    # 压缩 / 持久化 / token 计数
-│   │   ├── compact.ts              # auto + force 压缩
-│   │   ├── reactiveCompact.ts      # 上下文撑爆时的自救
-│   │   ├── microCompactLite.ts     # 工具回填 inline 压缩
-│   │   └── persistContext.ts       # ~/.minimal-agent/last-context.json
-│   ├── prompts/                    # system prompt 拼装
-│   │   ├── system.ts               # 主 prompt + 项目指令注入
-│   │   ├── projectInstructions.ts  # 项目根 minimal-agent.md 加载
-│   │   └── skillList.ts            # 扫描 skills/ 生成 skill 列表
-│   ├── tools/                      # 9 个内置工具（见上表）
-│   └── ui/                         # Ink TUI 组件
-├── skills/                         # Skill 库（每个子目录一个 SKILL.md）
-├── vendor/ripgrep/                 # 自带的 ripgrep 二进制（6 个平台）
+├── 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 用例
-├── examples/                       # Ink 教学示例
-└── minimal-agent.md                # 项目指令（类似 CLAUDE.md，会被自动注入 system prompt）
+└── 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"的通用目录差异问题：
+
+- 源码（仓库 / 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**
+
+这是 `execa` / `p-queue` / `ink` 等纯 ESM TypeScript 库的通用做法。
+
+### 用户安装（终端）
+
+```bash
+# 只装主包
+npm install -g minimal-agent
+minimal-agent                       # 启 ReAct TUI
+
+# 加装编辑器
+npm install -g minimal-workflw
+minimal-workflw /path/to/your-project   # 启编辑器
+```
+
+### 开发者发布流程
+
+#### 1. 发布主包
+
+```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
+```
+
+主包 `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 跑 `.ts` 源码作为 bin（`scripts/cli.ts` 首行有 `#!/usr/bin/env bun`），与主包发版策略不同但**目录耦合零依赖**——只通过文件系统读 `<project>/workflows/*.yaml`。
+
+#### 3. 版本独立
+
+两个包的 version 字段**互相独立**，不必同步。改主包内核 → 只升主包；改编辑器 UI → 只升编辑器。
+
 ---
 
 ## 工作原理（一句话版）
@@ -212,18 +488,27 @@ runQuery (loop.ts)
   └── continue              # 下一轮
 ```
 
-详见 `src/loop.ts` 的注释。
+`/workflow` / `/ralph-loop` 这类插件命令在主循环**之前**被路由器拦截，由 `pluginRunner` 分发到对应插件的 `runCommand` 接管。详见 `src/loop.ts` + `src/plugins/pluginRunner.ts`。
 
 ---
 
 ## 开发命令
 
 ```bash
-bun run start         # 跑 TUI
-bun run dev           # 热重载
-bun test              # 跑全部测试（test/*）
-bun test test/llm.live.test.ts  # 跑单个测试文件
-tsc --noEmit          # 类型检查
+# 主包
+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
 ```
 
 ---
@@ -234,14 +519,16 @@ minimal-agent 是 Claude Code 源码的**教学版**：
 
 | 维度 | kakadeai/Claude Code | minimal-agent |
 |---|---|---|
-| 代码量 | 数十万行 | ~3000 行 |
+| 代码量 | 数十万行 | 数千行 |
 | 主循环 | QueryEngine + 状态机 | 单层 while + AsyncGenerator |
-| Tool 数 | 60+（含 MCP / Agent / Notebook 等） | 9 个内置 |
+| 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 是什么"暴露在你眼前。
+设计目标是**砍掉一切非必要的抽象**，把"AI agent 是什么 / 怎么扩展"暴露在你眼前。
 
 ---
 
@@ -253,39 +540,13 @@ minimal-agent 是 Claude Code 源码的**教学版**：
 | 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 目录未随项目复制 |
-| `WebBrowser 报"无法启动浏览器"` | 需要 `npm install playwright-core && npx playwright install chromium`；或改用 WebFetch |
+| `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` 是最后写入的一次 |
-| 模型回复说"我没法访问外部 API" | 检查 `MINIMAL_AGENT_BASE_URL` 是否拼了 `/v1`，model id 是否对 |
-
----
-
-## 发布到 npm（未来）
-
-**当前状态：不能直接 `npm install -g minimal-agent`** —— `package.json` 里 `"private": true`，也没有 `bin` 字段和构建产物。
-
-如果要发布到 npm 让 Node.js 用户也能用，至少要做：
-
-1. **改 `package.json`**
-   - 去掉 `"private": true`
-   - 加 `"bin": { "minimal-agent": "dist/main.js" }`
-   - 加 `"files": ["dist", "vendor", "skills"]`（控制 npm tarball 内容）
-   - 加 `"engines": { "node": ">=20" }`
-2. **加构建步骤**：用 tsup / esbuild 把 `src/main.tsx` bundle 成单文件 CJS+ESM，输出到 `dist/main.js`
-3. **shebang**：构建产物首行加 `#!/usr/bin/env node`，发布前 `chmod +x`
-4. **`.env` 不打包**：在 `.npmignore` 里排除 `.env*`、`vendor/ripgrep/test/`，依赖**配置向导**让用户首次跑 `npx minimal-agent` 时填配置（这正是本项目 Mode B 的设计目的）
-5. **vendor ripgrep**：6 个平台二进制（~30MB）会进 tarball；如想瘦身可拆成 `optionalDependencies` 按平台下载
-6. **首发流程**：`npm whoami` → `npm publish --dry-run` 验证 tarball → `npm publish`
-
-发布后用户体验：
-
-```bash
-npm install -g minimal-agent
-minimal-agent              # 没配置 → 弹向导 → 测试通过 → 直接进 TUI
-minimal-agent -p "..."     # 配置完成后可直接 -p
-```
-
-**本项目尚未做这步**，本仓库定位为学习/教学版，主要面向 `bun run start` / `bun run dev` 本地运行的用户。
 
 ---