minimal-agent 0.1.9 → 0.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "minimal-agent",
-  "version": "0.1.9",
-  "description": "最小化 Agent 系统 —— 单对话 + 9 工具 + 自动压缩 + 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,33 +27,41 @@
   ],
   "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",
+    "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",
     "ink": "^5.0.1",
     "react": "^18.3.1",
     "turndown": "^7.2.4",
+    "yaml": "^2.9.0",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.25.2"
   },
@@ -61,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/HOW-TO-WRITE-A-PLUGIN.md

@@ -0,0 +1,186 @@
+# How to Write a minimal-agent Plugin
+
+minimal-agent 的插件系统遵循 **drop-in** 原则：把目录扔进 `plugins/`，命令立即可用，**`src/` 一行不改**。
+
+## 两种契约
+
+### 1. 纯声明式（Anthropic 兼容，零 TS）
+
+最小可用插件 = 一个 frontmatter 模板。框架替你拼 prompt 喂给 LLM。
+
+```
+plugins/hello-bot/
+├── .claude-plugin/
+│   └── plugin.json
+└── commands/
+    └── hi.md
+```
+
+**`.claude-plugin/plugin.json`**
+
+```json
+{
+  "name": "hello-bot",
+  "version": "0.1.0",
+  "description": "Greets the user"
+}
+```
+
+**`commands/hi.md`**
+
+```markdown
+---
+description: "Greet the user"
+argument-hint: "<name>"
+---
+
+你好 $ARGUMENTS！欢迎使用 minimal-agent。
+```
+
+**效果**：用户输入 `/hi 世界` → LLM 收到 `你好 世界！欢迎使用 minimal-agent。\n\n用户参数: 世界`。
+
+支持的占位符：
+- `$ARGUMENTS` / `${ARGUMENTS}` —— 用户在命令名后的全部文本
+- `${CLAUDE_PLUGIN_ROOT}` —— 该插件目录的绝对路径（用于引用插件资源）
+
+### 2. 声明式 + `plugin.ts`（富插件）
+
+当模板不够（要跑循环 / 做 TS 校验 / 启动子进程 / 状态机），加一个 `plugin.ts`：
+
+```
+plugins/echo-bot/
+├── .claude-plugin/plugin.json
+├── commands/echo.md         # 仍要存在！frontmatter 用于 listAvailableCommands
+└── plugin.ts                # PluginApi default export
+```
+
+**`plugin.ts`**
+
+```typescript
+import {
+  runQuery,
+  type PluginApi,
+  type LoopEvent,
+} from '../../src/plugin-sdk.ts';
+
+const api: PluginApi = {
+  async *runCommand(commandName, args, ctx): AsyncGenerator<LoopEvent> {
+    if (commandName === 'echo') {
+      // 直接 yield 自定义事件
+      yield { type: 'text', delta: `你输入了：${args}` };
+      yield { type: 'turn_done' };
+      return;
+    }
+
+    // 或者改写 prompt 后丢给 LLM
+    yield* runQuery(`请把以下内容重复 3 遍：${args}`, {
+      provider: ctx.provider,
+      history: ctx.history,
+      signal: ctx.signal,
+    });
+  },
+};
+
+export default api;
+```
+
+**框架行为**：命中 `/echo abc` 时，`pluginRunner` 优先调用 `runCommand('echo', 'abc', ctx)`，不再走声明式 fallback。你完全接管事件流。
+
+## `plugin-sdk.ts` 暴露的全部 API
+
+**唯一稳定 import 路径**：`from '../../src/plugin-sdk.ts'`（相对你的 `plugin.ts`）。
+
+| 名称 | 类型 | 用途 |
+|------|------|------|
+| `runQuery(input, opts)` | function | 标准 T-A-O-R 循环，AsyncGenerator |
+| `chat(messages, provider, opts)` | function | 单次非流式 LLM 调用 |
+| `executeTool(name, argsJson, ctx)` | function | 框架级工具调用入口 |
+| `getToolByName(name)` | function | 取 Tool 定义 |
+| `ALL_TOOLS` | const | 所有内置工具数组 |
+| `getWorkingDir()` | function | 当前锁定的工作目录 |
+| `getResourceSearchPaths(name, importMetaUrl)` | function | 双源资源路径（cwd + packageRoot） |
+| `triggerHook(event, payload)` | function | 触发框架级 hook |
+| `createSessionState()` | function | 新建 SessionState |
+| `Message` / `Provider` / `LoopEvent` / `LlmStreamEvent` | type | 协议类型 |
+| `Tool` / `ToolCall` / `ToolResult` | type | 工具协议类型 |
+| `PluginApi` / `PluginContext` | type | 你的 plugin.ts 契约 |
+| `ResourceName` / `HookEventName` / `HookDecision` / `SessionState` | type | 杂项 |
+
+**不要**绕开 `plugin-sdk.ts` 直接 import `src/loop.ts` / `src/llm/client.ts` 等内部路径 —— 那些路径不是稳定 API，框架重构时会破坏你的插件。
+
+## `PluginContext`
+
+`runCommand` 收到的 ctx：
+
+```typescript
+interface PluginContext {
+  provider: Provider;          // 当前 LLM provider 配置
+  history: Message[];          // 对话历史（你可以读 / 修改 / 替换）
+  signal?: AbortSignal;        // 用户 ESC / Ctrl+C 时触发
+  sessionState?: SessionState; // 可选共享 session 状态
+  maxTurns?: number;           // 工具循环最大轮数（runQuery 透传用）
+}
+```
+
+## 事件 (`LoopEvent`)
+
+你的 `runCommand` 必须 yield `LoopEvent`，UI 据此渲染。常用的有：
+
+| type | 字段 | 用途 |
+|------|------|------|
+| `text` | `delta: string` | 流式文本片段 |
+| `assistant_message` | (无) | 一次完整 assistant 消息已 push 进 history |
+| `tool_start` | `toolName`, `argsPreview` | 工具开始执行 |
+| `tool_end` | (无) | 工具结束 |
+| `turn_done` | (无) | 整轮交互结束 |
+| `interrupted` | (无) | 用户中断 |
+| `error` | `error: string` | 红色错误提示 |
+| `plugin_progress` | `pluginId`, `current`, `max?`, `message?` | 循环进度条（替代旧的 plugin_start / plugin_iteration） |
+
+通常做法：复杂插件直接 `yield* runQuery(...)` 透传所有事件，自己额外 yield `plugin_progress` 做进度展示。
+
+## 工作目录与持久化
+
+- 状态写到 `getWorkingDir()/.minimal-agent-<your-plugin-id>/` 下，避免污染主 context 目录
+- `/new` 命令会自动清这些 `.minimal-agent*` 目录，你不用管 cleanup
+- 跨平台：Windows 没 bash，hooks/*.sh 静默跳过；其它 .ts 代码完全平台无关
+
+## 命令默认值
+
+框架**不再**注入命令默认参数（旧版 `COMMAND_DEFAULTS` 已删除）。如果你的命令需要默认值（如 `--max-iterations 50`），自己在 `plugin.ts` 里解析 args 时兜底。这样默认值的语义属于插件契约，不属于框架。
+
+## 测试
+
+- 把测试放在 `plugins/<id>/test/*.test.ts`
+- `bunfig.toml` 的 `[test].root = ["./test", "./plugins"]` 让 `bun test` 自动发现
+- 测试里 mock LLM / 工具时，用 `mock.module('../../../src/loop.ts', ...)` 等绝对到 src 的相对路径
+
+## 参考实现
+
+- **声明式 + plugin.ts 简单例**：`plugins/workflow-runner/plugin.ts`（~25 行接管 `/workflow` 与 `/workflows`）
+- **重型循环例**：`plugins/ralph-wiggum/plugin.ts`（~270 行 do-while loop + FSM + sentinel + verification + stop-hook）
+
+## Transcript 与 Hook：当前状态
+
+框架提供了两套基础设施 —— 都**就绪、有测试、可独立调用**，但**主循环 `src/loop.ts` 不自动触发**：
+
+| 模块 | 暴露 | 当前主循环触发？ |
+|------|------|------|
+| `src/plugins/transcript.ts` | `initTranscript / appendUserMessage / appendAssistantMessage / appendToolResult` | 否 |
+| `src/plugins/hookEngine.ts` | `loadHooks / triggerHook('UserPromptSubmit' \| 'PreToolUse' \| 'PostToolUse' \| 'SessionStart' \| 'SessionEnd', payload)` | 否 |
+
+**插件如何使用**：
+- 想写自己的 JSONL transcript → 在 `runCommand` 内 `import { initTranscript, appendUserMessage } from '../../src/plugin-sdk.ts'` 自己调
+- 想响应 hook 事件 → 在 `runCommand` 内 `triggerHook('PreToolUse', { tool_name, ... })` 自己调；ralph-wiggum 走的就是这条路（vendored stop-hook 执行器在 `plugins/ralph-wiggum/src/stopHookRunner.ts`）
+
+**为什么不在主循环自动触发**：当前没有 Anthropic 风格 `hooks/*.sh` 的真实用例驱动；自动触发会改主循环热路径但不解决实际问题。等真有跨插件的全局 hook 需求时再接也不迟。届时只需在 `src/loop.ts` 的 user/assistant/tool 三处 push 点加 `appendXxx` 与 `triggerHook` 调用即可，**不影响插件契约**。
+
+## 不支持的 Anthropic 字段
+
+minimal-agent 的插件契约是 Anthropic 上游的**子集**。当前未实现的字段：
+
+- `mcp-servers/` —— MCP 服务器配置
+- `agents/` —— 子 agent 定义
+- `skills/` 在插件目录下 —— minimal-agent 的 skill 系统是独立顶层目录
+
+未实现字段在 plugin.json 中存在不会报错，但被忽略。

package/plugins/ralph-wiggum/commands/ralph-loop.md

@@ -10,7 +10,7 @@ hide-from-slash-command-tool: "true"
 <!--
   minimal-agent 注意：以下 ```! ``` 块是 Claude Code 专有的 shell-on-command
   语法，minimal-agent **不会执行**它。GoalState 的初始化（goal.md / phase.md
-  / completion.md 等）由 src/plugins/pluginRunner.ts 在进循环前自动完成，
+  / completion.md 等）由本插件的 plugin.ts 在进循环前自动完成，
   不需要 setup 脚本。该块保留在这里只是为了与原版 Claude Code 兼容。
 -->
 
@@ -26,22 +26,12 @@ CRITICAL RULE: If a completion promise is set, you may ONLY output it when the s
 
 ---
 
-## Goal State 初始化（首次迭代必做）
+## 本插件管理的状态文件
 
-在开始工作之前，请先执行以下步骤：
-
-1. **确认目标文件**：检查 `.minimal-agent/goal.md` 是否已包含用户的原始目标。如未包含，将用户目标写入。
-2. **生成完成判据**：在 `.minimal-agent/completion.md` 中写入 JSON 格式的客观验证条件（如果尚未存在或内容不完整）：
-   ```json
-   [
-     { "type": "shell", "command": "你的验证命令" },
-     { "type": "file_exists", "file": "期望存在的文件路径" },
-     { "type": "file_contains", "file": "文件路径", "pattern": "正则表达式" }
-   ]
-   ```
-3. **设置阶段**：确认 `.minimal-agent/phase.md` 内容为 `plan`。
-
-> 以上文件由 GoalState 系统自动管理，每轮迭代开始时会自动注入到你的上下文头部。你只需要在第一轮确保它们的内容正确。
+`.minimal-agent-ralph-wiggum/` 目录下的所有文件（goal.md / phase.md / completion.md /
+progress.md / learnings.md / decisions.md）**由本插件自动创建并维护**，你不需要主动
+读写它们。每轮迭代开始时，插件会把当前目标、阶段、最近进度、关键决策、教训自动拼接到
+你的 prompt 头部（freshContext），你**专注按头部信息行动**即可。
 
 ## 阶段工作流
 

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;