minimal-agent 0.2.0 → 0.3.0

package/README.md

@@ -5,7 +5,7 @@
 
 一个用于**学习和教学**的 Agent 项目，从 [kakadeai](../) 主仓库的 Claude Code 源码中抽取并简化而来，把"一个能调工具、能自动压缩上下文、能跑插件、能可视化编排 workflow 的 agent"在合理规模的 TypeScript 里讲清楚。
 
-> 项目由**两个独立的 npm 包**组成：`minimal-agent`（主体 ReAct CLI）+ `workflow-ui`（可视化 workflow 编辑器）。两边只通过 `workflows/*.yaml` 文件耦合，零运行时依赖。
+> 项目由**两个独立的 npm 包**组成：`minimal-agent`（主体 ReAct CLI）+ `minimal-workflw`（可视化 workflow 编辑器）。两边只通过 `workflows/*.yaml` 文件耦合，零运行时依赖。
 
 ---
 
@@ -30,7 +30,7 @@
                                    ↓ 读写 workflows/*.yaml
                                    │
 ┌──────────────────────────────────┴───────────────────────────────┐
-│              workflow-ui (独立编辑器包, editor/)                 │
+│              minimal-workflw (独立编辑器包, editor/)                 │
 │                                                                  │
 │   Bun + Vite + React + React Flow                                │
 │   ┌────────┐  ┌────────┐  ┌────────┐                             │
@@ -54,13 +54,15 @@
 | 🧰 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） |
-| 🖼️ 可视化编辑器 | 独立 `workflow-ui` 包，拖拽组装 workflow，节点面板从 `src/tools/` + `skills/` 自动派生 |
+| 🖼️ 可视化编辑器 | 独立 `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 用户走 `npm i -g minimal-agent` 安装预构建版
+- **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 生成图片）
@@ -80,14 +82,16 @@
 npm install -g minimal-agent
 
 # 2. （可选）装可视化 workflow 编辑器
-npm install -g workflow-ui
+#    ⚠ 当前 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；首次会弹配置向导
-workflow-ui ~/my-agent-project      # 在指定项目目录里启编辑器
+minimal-workflw ~/my-agent-project  # 在指定项目目录里启编辑器
 ```
 
-两个包**独立发版、独立安装**。只想要 ReAct CLI 就装 `minimal-agent`；想拖拽编排 workflow 再加 `workflow-ui`。两者通过 `<project>/workflows/*.yaml` 文件耦合，没有进程间通信。
+两个包**独立发版、独立安装**。只想要 ReAct CLI 就装 `minimal-agent`；想拖拽编排 workflow 再加 `minimal-workflw`。两者通过 `<project>/workflows/*.yaml` 文件耦合，没有进程间通信。
 
 ### B. 从源码运行（贡献者 / 想读源码）
 
@@ -268,7 +272,7 @@ YAML DAG workflow 执行器，支持 7 种 step：
 
 ---
 
-## workflow-ui 可视化编辑器（editor/ 子项目）
+## minimal-workflw 可视化编辑器（editor/ 子项目）
 
 独立的 npm 包，运行时与 `minimal-agent` **零耦合**，仅通过 `workflows/*.yaml` + `.editor-cache/manifest.json` 两个文件交换数据。
 
@@ -276,9 +280,9 @@ YAML DAG workflow 执行器，支持 7 种 step：
 
 ```bash
 # 已全局安装时
-workflow-ui                         # 当前 cwd 当 minimal-agent 项目根
-workflow-ui ~/my-project            # 指定项目根
-workflow-ui --refresh-manifest      # 强制刷新工具/skill 清单
+minimal-workflw                         # 当前 cwd 当 minimal-agent 项目根
+minimal-workflw ~/my-project            # 指定项目根
+minimal-workflw --refresh-manifest      # 强制刷新工具/skill 清单
 
 # 从源码跑（在 editor/ 目录下）
 bun scripts/cli.ts --project ..     # 一键起后端 + Vite
@@ -289,7 +293,7 @@ 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 发布后用户执行的 `workflow-ui` 命令就是这个 cli.ts
+> - npm 发布后用户执行的 `minimal-workflw` 命令就是这个 cli.ts
 
 ### 启动序列（编辑器 CLI 内部）
 
@@ -335,7 +339,7 @@ export OPENROUTER_API_KEY=sk-or-...
 bun run src/main.tsx -p "/workflow youtube-shorts --input topic='猫咪赛博朋克城市探险'"
 ```
 
-整条流水线**零代码改动** —— 4 个 skill 都是 markdown，1 个 workflow 是 yaml。在 `workflow-ui` 里打开 `youtube-shorts.yaml`，可视化拖拽改 prompt、换 skill、加节点。
+整条流水线**零代码改动** —— 4 个 skill 都是 markdown，1 个 workflow 是 yaml。在 `minimal-workflw` 里打开 `youtube-shorts.yaml`，可视化拖拽改 prompt、换 skill、加节点。
 
 ---
 
@@ -364,8 +368,8 @@ minimal-agent/
 │   ├── book-review-short.yaml
 │   ├── e2e-write-greet.yaml
 │   └── youtube-shorts.yaml
-├── editor/                         # workflow-ui 独立子包
-│   ├── package.json                #   name: workflow-ui, bin: workflow-ui
+├── editor/                         # minimal-workflw 独立子包
+│   ├── package.json                #   name: minimal-workflw, bin: minimal-workflw
 │   ├── scripts/
 │   │   ├── cli.ts                  #   bin 入口（一键起后端+前端）
 │   │   └── server.ts               #   Bun.serve() 文件 IO + manifest 端点
@@ -387,9 +391,22 @@ minimal-agent/
 | 包 | 路径 | 命令 | 职责 |
 |---|---|---|---|
 | `minimal-agent` | 仓库根 | `minimal-agent` | ReAct CLI + 工具 + 插件 + skills |
-| `workflow-ui` | `editor/` | `workflow-ui` | 可视化 workflow 编辑器 |
+| `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**
 
-> **为什么不打成一个包**？因为 90% 的 ReAct CLI 用户不需要编辑器，编辑器的依赖（React / Vite / @xyflow/react / Monaco 等）有几十 MB，不应该污染主包。两边解耦后用户按需取用。
+这是 `execa` / `p-queue` / `ink` 等纯 ESM TypeScript 库的通用做法。
 
 ### 用户安装（终端）
 
@@ -399,23 +416,19 @@ npm install -g minimal-agent
 minimal-agent                       # 启 ReAct TUI
 
 # 加装编辑器
-npm install -g workflow-ui
-workflow-ui /path/to/your-project   # 启编辑器
+npm install -g minimal-workflw
+minimal-workflw /path/to/your-project   # 启编辑器
 ```
 
-> npm 的 `bin` 字段支持一个包注册多个命令；但本项目选择**两个独立包**而不是"一个包两个 bin"，是为了**依赖隔离**（编辑器的 React 依赖不该跟着 ReAct CLI 一起装到所有人的机器上）。
-
 ### 开发者发布流程
 
 #### 1. 发布主包
 
 ```bash
 cd minimal-agent
-# 改完代码后
-npm version patch                   # 0.1.6 → 0.1.7
-bun run build                       # tsup 把 src/main.tsx 打成 dist/main.js
-npm publish --dry-run               # 验证 tarball 内容（dist + vendor + skills + plugins）
-npm publish
+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` 关键字段：
@@ -423,67 +436,32 @@ npm publish
 ```json
 {
   "name": "minimal-agent",
-  "bin": { "minimal-agent": "dist/main.js" },
-  "files": ["dist", "vendor/ripgrep", "skills", "plugins", "README.md", "LICENSE"],
+  "bin": { "minimal-agent": "src/main.js" },
+  "files": ["src", "plugins", "skills", "workflows", "vendor/ripgrep", "README.md", "LICENSE"],
   "engines": { "node": ">=20" },
   "scripts": {
-    "build": "tsup",
-    "prepublishOnly": "npm run build"
+    "build": "tsc --build",
+    "clean": "bun scripts/clean-build.ts",
+    "prepublishOnly": "bun run clean && bun run build"
   }
 }
 ```
 
-`tsup` 把 `src/main.tsx` 单文件 bundle 成 ESM CJS 双格式输出到 `dist/`，首行加 `#!/usr/bin/env node` shebang。`prepublishOnly` 保证 `npm publish` 前自动跑构建。
+`prepublishOnly` 先清旧产物再跑 tsc 原地编译，`.npmignore` 排除源码 .ts/.tsx 让 tarball 里**只有 .js**。`src/main.tsx` 首行 `#!/usr/bin/env node` 由 tsc 编译产物保留，直接作为 bin。
 
 #### 2. 发布编辑器包
 
 ```bash
 cd minimal-agent/editor
-# 改完代码后
-# 先把 package.json 里的 "private": true 删掉
-npm version patch                   # 0.1.0 → 0.1.1
+npm version patch
 bun run build                       # Vite 把前端打到 editor/dist/
 npm publish --dry-run
 npm publish
 ```
 
-编辑器包需要在 publish 前完成：
-
-- 删 `"private": true`
-- 加 `"files": ["dist", "scripts", "public/manifest.fallback.json", "index.html", "vite.config.ts"]`（控制 tarball）
-- 加 `"engines": { "bun": ">=1.1" }`（因为 bin 是 .ts，需要 bun shebang）
-- `scripts/cli.ts` 首行确认有 `#!/usr/bin/env bun`
-
-#### 3. 一键发布脚本（可选）
-
-`scripts/publish-all.ts`（建议加上）：
-
-```ts
-#!/usr/bin/env bun
-import { $ } from 'bun';
-
-const bump = process.argv[2] ?? 'patch';   // patch | minor | major
-
-console.log('▶ 发布主包...');
-await $`npm version ${bump}`;
-await $`bun run build`;
-await $`npm publish`;
-
-console.log('▶ 发布编辑器...');
-await $`cd editor && npm version ${bump}`;
-await $`cd editor && bun run build`;
-await $`cd editor && npm publish`;
-
-console.log('✅ 完成。两个包都已发布到 npm。');
-```
-
-跑法：
-
-```bash
-bun scripts/publish-all.ts patch    # 两个包都升 patch 版并发布
-```
+编辑器是独立子项目，Bun 跑 `.ts` 源码作为 bin（`scripts/cli.ts` 首行有 `#!/usr/bin/env bun`），与主包发版策略不同但**目录耦合零依赖**——只通过文件系统读 `<project>/workflows/*.yaml`。
 
-#### 4. 版本独立
+#### 3. 版本独立
 
 两个包的 version 字段**互相独立**，不必同步。改主包内核 → 只升主包；改编辑器 UI → 只升编辑器。
 
@@ -564,8 +542,8 @@ minimal-agent 是 Claude Code 源码的**教学版**：
 | 改完 `~/.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 |
-| `workflow-ui` 命令找不到 | 没装编辑器包；`npm install -g workflow-ui` 即可 |
-| 编辑器空白 / 节点面板没工具 | `.editor-cache/manifest.json` 缺失；`workflow-ui --refresh-manifest` 强制刷新 |
+| `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` 是最后写入的一次 |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "minimal-agent",
-  "version": "0.2.0",
-  "description": "最小化 Agent 系统 —— 单对话 + 10 工具 + 插件系统 + workflow DSL + 自动压缩 + OpenAI 兼容 + Ink TUI（学习/教学用）",
+  "version": "0.3.0",
+  "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>",
   "repository": {
@@ -27,28 +27,34 @@
   ],
   "type": "module",
   "bin": {
-    "minimal-agent": "dist/main.js"
+    "minimal-agent": "src/main.js"
   },
-  "main": "dist/main.js",
   "engines": {
     "node": ">=20"
   },
   "files": [
-    "dist",
-    "vendor/ripgrep",
-    "skills",
-    "plugins",
-    "workflows",
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "plugins/**/*.js",
+    "plugins/**/*.d.ts",
+    "plugins/**/.claude-plugin/**",
+    "plugins/**/commands/**",
+    "plugins/**/hooks/**",
+    "plugins/HOW-TO-WRITE-A-PLUGIN.md",
+    "skills/**",
+    "workflows/**",
+    "vendor/ripgrep/**",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "start": "bun run src/main.tsx",
     "dev": "bun --watch src/main.tsx",
-    "build": "tsup",
+    "build": "tsc --build",
+    "clean": "bun scripts/clean-build.ts",
     "test": "bun test",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
+    "typecheck": "tsc --noEmit -p tsconfig.typecheck.json",
+    "prepublishOnly": "bun run clean && bun run build"
   },
   "dependencies": {
     "fast-glob": "^3.3.2",
@@ -63,7 +69,6 @@
     "@types/node": "^20.14.0",
     "@types/react": "^18.3.0",
     "bun-types": "^1.3.13",
-    "tsup": "^8.5.1",
     "typescript": "^5.5.0"
   }
 }

package/plugins/ralph-wiggum/plugin.js

@@ -0,0 +1,205 @@
+/**
+ * ============================================================
+ *  plugins/ralph-wiggum/plugin.ts —— ralph-wiggum 真·插件入口
+ * ------------------------------------------------------------
+ *  把原 src/plugins/pluginRunner.ts 的 do-while 循环驱动整段搬来。
+ *  对外通过 PluginApi.runCommand 暴露 /ralph-loop。
+ *
+ *  循环契约：
+ *    - 每轮把 history 重置成进入循环前的快照（fresh context）
+ *    - 用 GoalState.composeContext() 拼 PLAN/BUILD/VERIFY/HEAL 阶段信息
+ *    - 跑 runQuery
+ *    - 检测 <promise>DONE</promise> → runVerification → 通过则退出
+ *    - 检测 <PROMISE>NEED_REPLAN</PROMISE> → forceSetPhase(PLAN)
+ *    - executeStopHook 是咨询式：block 才把 reason 注入下一轮，pass 不退出
+ *
+ *  终止（独占）：sentinel + verify 通过 / 达 max-iterations / abort / 安全天花板
+ *
+ *  Windows 上 hooks/stop-hook.sh 不可用，但循环不依赖 hook，功能完整，
+ *  只是 hook 的咨询通道失效。
+ * ============================================================
+ */
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+import { runQuery, getWorkingDir, } from '../../src/plugin-sdk.js';
+import { GoalState, Phase } from './src/goalState.js';
+import { parseVerifyArgs, runVerification } from './src/verificationGate.js';
+import { hasCompleteSentinel, hasNeedReplanSentinel, } from './src/sentinels.js';
+import { executeStopHook } from './src/stopHookRunner.js';
+const PLUGIN_NAME = 'ralph-wiggum';
+const DEFAULT_MAX_ITERATIONS = 50;
+const SAFETY_CEILING = 200;
+const PLUGIN_ROOT = dirname(fileURLToPath(import.meta.url));
+function extractMaxIterations(args) {
+    const match = args.match(/--max-iterations\s+(\d+)/i);
+    return match ? parseInt(match[1], 10) : undefined;
+}
+async function* runRalphLoop(args, ctx) {
+    const { provider, history, signal } = ctx;
+    const maxIter = Math.min(extractMaxIterations(args) ?? DEFAULT_MAX_ITERATIONS, SAFETY_CEILING);
+    // 没有 args（用户只敲 /ralph-loop）→ 留个最小 goal placeholder，避免 GoalState.init 拒空串
+    const userGoal = args.trim() || '(未提供目标)';
+    yield {
+        type: 'plugin_progress',
+        pluginId: PLUGIN_NAME,
+        current: 0,
+        max: maxIter,
+        message: 'Ralph Wiggum copy-task loop 启动',
+    };
+    const checks = parseVerifyArgs(args);
+    // sessionTag = 插件名 → 多插件可并发不打架，/new 也能扫到清掉
+    const goalState = new GoalState(getWorkingDir(), PLUGIN_NAME);
+    await goalState.reset();
+    await goalState.init(userGoal, checks);
+    await goalState.appendProgress(`=== Loop 启动 === 目标: ${userGoal.slice(0, 120)}...`);
+    // 进循环前快照 history —— 每轮 runQuery 前用它重置，保证 fresh context
+    const baseHistory = history.slice();
+    let iterationCount = 0;
+    let consecutiveFailures = 0;
+    let currentInput = userGoal;
+    let finalAssistantMsg = null;
+    try {
+        do {
+            iterationCount++;
+            if (iterationCount > maxIter) {
+                await goalState.forceSetPhase(Phase.DONE, `达到迭代上限 ${maxIter}`);
+                await goalState.appendLearning(`[迭代上限] 循环在 ${iterationCount - 1} 轮后强制终止，可能目标过大或陷入死循环`);
+                yield {
+                    type: 'error',
+                    error: `Loop 已达迭代上限 ${maxIter}，自动停止`,
+                };
+                return;
+            }
+            if (signal?.aborted) {
+                yield { type: 'interrupted' };
+                return;
+            }
+            yield {
+                type: 'plugin_progress',
+                pluginId: PLUGIN_NAME,
+                current: iterationCount,
+                max: maxIter,
+            };
+            // fresh context：清空 history，重置为入循环前的快照
+            history.length = 0;
+            history.push(...baseHistory);
+            const freshContext = goalState.composeContext(iterationCount);
+            const enhancedInput = `${freshContext}\n\n${currentInput}`;
+            yield* runQuery(enhancedInput, {
+                provider,
+                history,
+                signal,
+                maxTurns: ctx.maxTurns,
+                sessionState: ctx.sessionState,
+            });
+            if (signal?.aborted) {
+                yield { type: 'interrupted' };
+                return;
+            }
+            // 从本轮 history 抓最后一个 assistant 消息（runQuery 已 push 进去）
+            const lastAssistantIdx = (() => {
+                for (let i = history.length - 1; i >= 0; i--) {
+                    if (history[i].role === 'assistant')
+                        return i;
+                }
+                return -1;
+            })();
+            finalAssistantMsg =
+                lastAssistantIdx >= 0 ? history[lastAssistantIdx] : null;
+            const lastAssistantText = finalAssistantMsg
+                ? typeof finalAssistantMsg.content === 'string'
+                    ? finalAssistantMsg.content
+                    : JSON.stringify(finalAssistantMsg.content)
+                : '';
+            if (hasCompleteSentinel(lastAssistantText)) {
+                // 哨兵：可能来自任意阶段（包括 iter 1 的 PLAN），用 force 跳到 VERIFY
+                await goalState.forceSetPhase(Phase.VERIFY, '检测到完成哨兵，进入验证');
+                await goalState.appendProgress(`迭代 ${iterationCount}: 检测到完成哨兵，运行验证门...`);
+                if (checks.length > 0) {
+                    const vResult = await runVerification(checks);
+                    if (!vResult.passed) {
+                        consecutiveFailures++;
+                        await goalState.appendLearning(`[迭代 ${iterationCount}] 声称完成但验证未通过: ${vResult.summary}`);
+                        yield {
+                            type: 'error',
+                            error: `⚠️ 验证未通过: ${vResult.summary}。继续尝试...`,
+                        };
+                        if (consecutiveFailures >= 3) {
+                            await goalState.forceSetPhase(Phase.HEAL, `连续 ${consecutiveFailures} 次验证失败`);
+                        }
+                        else {
+                            await goalState.setPhase(Phase.BUILD, '验证未通过，返回构建');
+                        }
+                        continue;
+                    }
+                    await goalState.appendProgress(`✅ 验证通过: ${vResult.summary}`);
+                }
+                await goalState.setPhase(Phase.DONE, 'goal complete & verified');
+                yield {
+                    type: 'plugin_iteration',
+                    pluginName: PLUGIN_NAME,
+                    current: iterationCount,
+                    max: maxIter,
+                };
+                return;
+            }
+            if (hasNeedReplanSentinel(lastAssistantText)) {
+                await goalState.forceSetPhase(Phase.PLAN, 'agent 请求重新规划');
+                await goalState.appendLearning('[NEED_REPLAN] Agent 认为当前方案不可行，需要重新规划');
+                await goalState.appendProgress('Agent 请求 NEED_REPLAN，回 PLAN 阶段');
+                consecutiveFailures = 0;
+                continue;
+            }
+            // PLAN 阶段跑过一轮还没哨兵，认为规划已完成，自动推进 BUILD
+            if (goalState.currentPhase === Phase.PLAN && iterationCount >= 2) {
+                await goalState.setPhase(Phase.BUILD, '规划阶段已完成，进入构建');
+            }
+            // Stop-hook 咨询式调用：block 才把 reason 注入下一轮 prompt
+            // pass / 报错都不再终止循环；终止由 sentinel/maxIter/abort/NEED_REPLAN 独占
+            const hookResult = await executeStopHook(PLUGIN_ROOT, lastAssistantText);
+            if (hookResult.decision === 'block' && hookResult.reason) {
+                currentInput = hookResult.reason;
+                consecutiveFailures = 0;
+                await goalState.recordDecision({
+                    iteration: iterationCount,
+                    phase: goalState.currentPhase,
+                    summary: 'stop-hook 反馈',
+                }, ['继续循环', '终止'], '继续循环', hookResult.reason.slice(0, 200));
+                if (hookResult.systemMessage) {
+                    baseHistory.push({
+                        role: 'user',
+                        content: `[Plugin Stop Hook] ${hookResult.systemMessage}`,
+                    });
+                }
+                await goalState.appendProgress(`迭代 ${iterationCount}: Stop hook block，注入反馈继续`);
+            }
+            else {
+                await goalState.appendProgress(`迭代 ${iterationCount}: 无哨兵 / hook pass，继续下一轮`);
+            }
+        } while (true);
+    }
+    finally {
+        // 收尾：把循环里临时累积的 history 还原成 baseHistory + 最后一轮 assistant
+        // 这样 TUI 上看到的就是"一次问答"，而不是 N 轮重复
+        history.length = 0;
+        history.push(...baseHistory);
+        if (finalAssistantMsg) {
+            history.push(finalAssistantMsg);
+        }
+        await goalState.cleanup();
+    }
+}
+const api = {
+    async *runCommand(commandName, args, ctx) {
+        if (commandName === 'ralph-loop') {
+            yield* runRalphLoop(args, ctx);
+            return;
+        }
+        // 其它命令（help / cancel-ralph）→ 不接管，让框架走声明式 fallback
+        yield {
+            type: 'error',
+            error: `ralph-wiggum: 命令 /${commandName} 未由 plugin.ts 接管`,
+        };
+    },
+};
+export default api;