minimal-agent 0.8.2 → 0.9.0

package/README.md

@@ -25,7 +25,7 @@
 - **11 个内置工具**：Read / Write / Edit / MultiEdit / Glob / Grep / WebSearch / WebFetch / WebBrowser / Bash / AskUserQuestion（向用户提结构化选择题，动态工作流交互底座）
 - **OpenAI 兼容**：Message 形状对齐 Chat Completions，一套代码接 MiniMax / 火山 ARK / DeepSeek / OpenAI / Moonshot…
 - **Skills 系统**：放一个 `SKILL.md` 就能扩展能力，运行时实时扫描注入 prompt，改文件即生效
-- **插件系统**：`plugins/<id>/` drop-in，自带 `/ralph-loop`（复制任务循环）与 `/workflow`（YAML DAG 执行器）
+- **插件系统**：`plugins/<id>/` drop-in，自带 `/workflow`（YAML 工作流引擎，支持 while 循环 + 验证门 + fresh_context）
 - **自动上下文压缩**：接近上限时把旧对话压成摘要，保留系统提示 + 摘要 + 最近几条
 - **多 session + 归档**：同一工作目录多个并行会话，`/new` 归档、`/restore` 恢复
 - **可编程子进程**：`-p --output-format json` 输出一行结构化结局契约，方便被宿主程序 spawn 调度
@@ -98,7 +98,7 @@ bun run start        # 或全局安装后直接 minimal-agent
 | `/show <id>` | 展开某次工具调用的完整输出（列表默认折叠到 3 行） |
 | `/exit`（`/quit`） | 退出 |
 
-`/init`、`/config` 等是 **LLM 驱动的 skill**；`/workflow`、`/ralph-loop` 是**插件命令**（见下）。
+`/init`、`/config` 等是 **LLM 驱动的 skill**；`/workflow`、`/workflows` 是**插件激活入口**（见下）。
 
 ### 非交互模式（`-p`）—— 脚本 / CI / 被宿主程序调用
 
@@ -152,8 +152,7 @@ minimal-agent -p --output-format json "做点事"           # 一行结构化结
 - **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）
+  - **`/workflow` · `/workflows`**（workflow-runner）—— YAML 工作流引擎，10 种 step（tool/llm/skill/assert/agent/branch/loop/break/pause/parallel/vote），支持 while 循环 + fresh_context + 验证门。内置 `ralph-loop` 等工作流定义
 - **可视化编辑器**：`editor/` 子项目（Bun + Vite + React Flow）拖拽编排 workflow YAML（不属于 npm 发布物）。
 
 ---
@@ -215,7 +214,7 @@ dev 下 Bun 透明回退到 `.ts` 兄弟，发布前 `tsc --build` 原地产出
 minimal-agent/
 ├─ src/            # 主程序（loop / tools / llm / ui / plugins / config …）
 ├─ skills/         # 内置 skill（每个一个 SKILL.md）
-├─ plugins/        # 内置插件（ralph-wiggum / workflow-runner）
+├─ plugins/        # 内置插件（workflow-runner）
 ├─ workflows/      # 内置 workflow（YAML）
 ├─ vendor/ripgrep/ # Grep 自带的 6 平台 ripgrep 二进制
 ├─ scripts/        # 构建脚本（含绿色版 build-green.ts）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.8.2",
+  "version": "0.9.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>",

package/plugins/workflow-runner/plugin.js

@@ -25,6 +25,7 @@ const api = {
                 provider: ctx.provider,
                 history: ctx.history,
                 signal: ctx.signal,
+                sessionState: ctx.sessionState,
                 cwd: getWorkingDir(),
                 tools: ALL_TOOLS,
             });

package/plugins/workflow-runner/src/agentCommon.js

@@ -1,55 +1,35 @@
 /**
  * ============================================================
- *  plugins/workflow-runner/src/agentCommon.ts —— workflow 内「有界 agent」的共享大脑
+ *  plugins/workflow-runner/src/agentCommon.ts —— workflow 内「有界 agent」的共享工具
  * ------------------------------------------------------------
- *  工作流里有两处会临时起一个 agent（都跑 miniReAct）：
+ *  工作流里有两处会临时起一个 agent（runQuery 执行后的验证闸门）：
  *    - onError:'recover'（recovery.ts）—— 节点失败后救火
  *    - agent: 节点（stepExecutors/agent.ts）—— 作者显式声明的开放任务
  *  二者本质同构：受工作流目标/上下文指导、用工具随机应变、产出经验证后回灌 capture。
  *  为避免「同一个脑子写两份提示词、行为漂移」，这里收敛它们的**共享件**：
- *    1. 统一系统提示词基础内核（来自 promptAssembly.ts）—— 含工具/skill/plugin 完整列表；
- *       两处只在前面各加一句**角色开场白**（recover=救火 / agent=自主完成一步），
- *       后面追加共享纪律块。
- *    2. 统一验证闸门（interpretMiniReActResult）—— miniReAct 跑完后，判定「真交付」还是
+ *    1. 统一验证闸门（interpretMiniReActResult）—— runQuery 执行完后，判定「真交付」还是
  *       「放弃/不可信」，**永不把没验证过的产出当成功**。这是 Phase 2 验证闸门的提取。
+ *
+ *  ⚠️ GIVEUP 标记设计原则（v0.9.3 修复 LLM 误触发问题）：
+ *     旧标记 __AGENT_GIVEUP__ 使用 __XXX__ 格式，MiniMax/GPT 等模型容易在输出中
+ *    幻觉出类似标记（如 "__AGENT_GIVEUP__: since I did the work..."），导致已完成的工作
+ *    被误判为"放弃"而 halt。新标记采用三重防误触发设计：
+ *       ① 非标准格式（非 __XXX__，LLM 训练数据中几乎不存在）
+ *       ② 含明确的 "DO-NOT-GENERATE" 警告文本
+ *       ③ 检测逻辑增加内容长度启发式（reason > 80 字符视为误报）
  * ============================================================
  */
-import { assembleBasePrompt } from '../../../src/prompts/promptAssembly.js';
-/** agent 显式放弃的唯一标记；与 DISCIPLINE 收尾约束严格对应。recover 与 agent 节点共用。 */
-export const GIVEUP_MARKER = '__AGENT_GIVEUP__';
-/** agent 步骤的角色开场白（与 recovery 的 RECOVER_OPENING 对称） */
-export const AGENT_OPENING = '你是一名资深工程师，被一个确定性工作流临时调来「自主完成一步开放任务」。';
-/** 共享纪律块：所有 workflow 内 agent 的通用行为约束（角色开场白由各调用方拼在前面）。 */
-const DISCIPLINE = `按这个纪律干活：
-1. 先想清楚「这一步要产出什么」，必要时用只读工具（Read / Grep / Glob）做最小探查，别凭空猜、别凭空编。
-2. 用工具**实际去做**（读文件、执行命令、写文件…），不要只描述计划。
-3. **收尾前必须自我验证**：用工具确认产出确实存在且满足意图（写了文件就 Read 回来核对、跑了命令就检查退出码与输出）。没验证过不算完成。
-
-安全护栏（你握有包括 Bash 在内的全部工具，务必克制）：
-- 只做达成意图所必需的最小动作，优先可逆操作。
-- 严禁破坏性行为：不 rm -rf、不删除/覆盖与本步无关的用户数据、不碰工作目录以外的东西。
-- **绝不靠伪造、占位、或编造一段「看起来对」的文本来假装成功**——你的产出会被工作流绑给后续步骤，假结果比诚实失败更糟。
-
-收尾（二选一，硬约束）：
-- 真的达成了 → 最终消息**只输出这一步要的结果本身**，不要寒暄、不要复述要求、不要解释推理过程。若要求结构化输出，严格按 JSON Schema、**不要**用 markdown 代码块包裹。
-- 确实做不成 → 最终消息**只输出一行**：\`${GIVEUP_MARKER}: <一句话说明为什么>\`，让工作流诚实地停下。绝不要为了「交差」而编一个假结果。`;
 /**
- * 拼一个 workflow agent 的完整 system prompt：
- *
- *   角色开场白 + 基础内核（含 skill/plugin/工具完整列表） + 共享纪律
+ * agent 显式放弃的唯一标记；recover 与 agent 节点共用。
  *
- * 基础内核来自 assembleBasePrompt()，确保 workflow agent 与 TUI 普通对话
- * 看到完全相同的 skill 列表和插件信息。
+ * 设计约束（纯 ASCII，避免 Unicode 编码匹配问题）：
+ *   - 不使用 __XXX__ 格式（LLM 容易幻觉模仿）
+ *   - 含 "wf-internal" 前缀 + "do-not-generate" 明确警告
+ *   - 使用 [bracket] 格式而非 ⟨angle⟩（避免 Unicode 字符在 Bun indexOf 中行为不一致）
  */
-export async function buildWorkflowAgentSystem(cwd, opening, tools) {
-    const baseKernel = await assembleBasePrompt({
-        cwd,
-        tools,
-        includeProjectInstructions: false, // workflow 子步骤不需要项目指令
-        includePlugins: true, // 插件列表对 agent 也有参考价值
-    });
-    return `${opening}\n\n${baseKernel}\n\n${DISCIPLINE}`;
-}
+export const GIVEUP_MARKER = '[wf-internal-abort-do-not-generate]';
+/** agent 步骤的角色开场白（与 recovery 的 RECOVER_OPENING 对称） */
+export const AGENT_OPENING = '你是一名资深工程师，被一个确定性工作流临时调来「自主完成一步开放任务」。';
 /** 把 step.capture 翻成「下游会把你的结果存成哪些变量」，让 agent 产出对得上形状。 */
 export function describeCaptureContract(step) {
     if (!step.capture)
@@ -64,26 +44,60 @@ export function truncate(s, n) {
 }
 /**
  * 解析非 schema 模式下 agent 最终文本里的放弃标记。
- *   - 命中 `__AGENT_GIVEUP__: <原因>` → 返回原因字符串（可能为空串）
+ *   - 命中 GIVEUP_MARKER → 返回原因字符串（可能为空串）
  *   - 未命中 → null（视为给出了真实结果）
+ *
+ * 注意：旧标记 __AGENT_GIVEUP__ 也兼容检测（向后兼容已存在的 checkpoint/状态数据），
+ * 但新代码只使用新标记格式。
  */
+const LEGACY_GIVEUP_MARKER = '__AGENT_GIVEUP__';
 export function parseGiveup(text) {
-    const idx = text.indexOf(GIVEUP_MARKER);
+    // 优先检测新标记
+    const newIdx = text.indexOf(GIVEUP_MARKER);
+    const legacyIdx = text.indexOf(LEGACY_GIVEUP_MARKER);
+    // 取先出现的那一个
+    let idx = -1;
+    let markerLen = 0;
+    if (newIdx !== -1 && (legacyIdx === -1 || newIdx < legacyIdx)) {
+        idx = newIdx;
+        markerLen = GIVEUP_MARKER.length;
+    }
+    else if (legacyIdx !== -1) {
+        idx = legacyIdx;
+        markerLen = LEGACY_GIVEUP_MARKER.length;
+    }
     if (idx === -1)
         return null;
     return text
-        .slice(idx + GIVEUP_MARKER.length)
-        .replace(/^[:：\s]+/, '')
+        .slice(idx + markerLen)
+        .replace(/^[:：\s\]]+/, '') // 兼容新旧标记后的分隔符（: / : / ]）
         .trim();
 }
+/** 判断一个 giveup reason 是否看起来像"误报"（实际是 LLM 在正常输出中碰巧触发了标记）。
+ *
+ * 启发式规则：
+ *   - reason 长度 > 80 字符 → 几乎可以确定是误报（真正的放弃原因通常简短）
+ *   - reason 包含结构化内容（如 ## 标题、### 章节、列表项等）→ 误报
+ */
+function isLikelyFalsePositive(reason) {
+    if (reason.length > 80)
+        return true;
+    // 如果 reason 看起来像 markdown 正文（标题/章节），也是误报
+    if (/^#{1,6}\s/m.test(reason) || /^[-*+]\s/m.test(reason) || /^\d+\.\s/m.test(reason)) {
+        return true;
+    }
+    return false;
+}
 /**
- * 验证闸门：把 miniReAct 的 StepResult 判定为「真交付」或「放弃/不可信」。
- *   - schema 模式：miniReAct 已 strict 解析（解析失败会抛、落不到这里），能拿到结果即 ok；
+ * 验证闸门：把 StepResult 判定为「真交付」或「放弃/不可信」。
+ *   - schema 模式：extractJsonPayload 已严格解析（解析失败会抛、落不到这里），能拿到结果即 ok；
  *     补 content 别名不覆盖具名字段。
  *   - 非 schema 模式：空产出 / 命中 GIVEUP 标记 → ok:false；否则 ok:true，raw 补 text/result/content
  *     三键别名，兼容 capture:{content:x}/{result:x}/{text:x}。
- * 注意：preview 这里给「干净版」（不加任何前缀），需要前缀的调用方（如 recover 的 "recovered: "）
- * 自行包装。
+ *
+ * v0.9.3 增强：GIVEUP 检测增加误报过滤（isLikelyFalsePositive）。
+ * 当标记后的内容看起来像是实质性的工作产出而非简短放弃理由时，
+ * 视为 LLM 误触发标记 → 仍然当作成功交付处理。
  */
 export function interpretMiniReActResult(result, hasSchema) {
     if (hasSchema) {
@@ -100,6 +114,27 @@ export function interpretMiniReActResult(result, hasSchema) {
     }
     const giveup = parseGiveup(trimmed);
     if (giveup !== null) {
+        // v0.9.3: 误报过滤 —— 如果 "放弃原因" 太长或太结构化，
+        // 说明 LLM 是在正常输出中碰巧触发了标记，不应判为放弃
+        if (isLikelyFalsePositive(giveup)) {
+            // 降级为成功交付：去掉误触发的标记部分，保留实质内容
+            const cleanText = trimmed
+                .replace(GIVEUP_MARKER, '')
+                .replace(LEGACY_GIVEUP_MARKER, '')
+                .trim();
+            const raw = {
+                text: cleanText,
+                result: cleanText,
+                content: cleanText,
+            };
+            return {
+                ok: true,
+                value: {
+                    raw,
+                    preview: cleanText.length > 200 ? `${cleanText.slice(0, 200)}…` : cleanText,
+                },
+            };
+        }
         return { ok: false, reason: giveup || '显式放弃（未给原因）' };
     }
     const raw = {

package/plugins/workflow-runner/src/expressions.js

@@ -40,7 +40,7 @@ import { existsSync } from 'node:fs';
 import { join, isAbsolute } from 'node:path';
 import { getWorkingDir } from '../../../src/plugin-sdk.js';
 const PUNCT2 = new Set(['==', '!=', '>=', '<=', '&&', '||']);
-const PUNCT1 = new Set(['(', ')', '[', ']', ',', '.', '!', '>', '<', '+']);
+const PUNCT1 = new Set(['(', ')', '[', ']', ',', '.', '!', '>', '<', '+', '?', ':']);
 function tokenize(src) {
     const out = [];
     let i = 0;
@@ -164,6 +164,37 @@ const BUILTINS = {
     upper(args) {
         return String(args[0] ?? '').toUpperCase();
     },
+    includes(args) {
+        const haystack = String(args[0] ?? '');
+        const needle = String(args[1] ?? '');
+        return haystack.includes(needle);
+    },
+    startsWith(args) {
+        const s = String(args[0] ?? '');
+        const prefix = String(args[1] ?? '');
+        return s.startsWith(prefix);
+    },
+    endsWith(args) {
+        const s = String(args[0] ?? '');
+        const suffix = String(args[1] ?? '');
+        return s.endsWith(suffix);
+    },
+    match(args) {
+        const s = String(args[0] ?? '');
+        const pattern = String(args[1] ?? '');
+        try {
+            const re = new RegExp(pattern);
+            return re.test(s);
+        }
+        catch {
+            return false; // 非法正则 → 不匹配
+        }
+    },
+    split(args) {
+        const s = String(args[0] ?? '');
+        const delim = args[1] !== undefined ? String(args[1]) : ',';
+        return s.split(delim);
+    },
 };
 function parseOr(c, vars) {
     let left = parseAnd(c, vars);
@@ -174,6 +205,21 @@ function parseOr(c, vars) {
     }
     return left;
 }
+// 三元表达式：cond ? true_expr : false_expr
+// 优先级低于 ||（即先算完 || 再判断 ? :）
+// 右结合：a ? b ? c : d : e 等价于 a ? (b ? c : d) : e
+function parseTernary(c, vars) {
+    const cond = parseOr(c, vars);
+    if (!isPunct(c, '?'))
+        return cond;
+    eat(c); // 吃掉 '?'
+    const consequent = parseTernary(c, vars); // 右结合：true 分支可以是嵌套三元
+    if (!isPunct(c, ':'))
+        throw new Error("三元表达式缺少 ':'");
+    eat(c); // 吃掉 ':'
+    const alternate = parseTernary(c, vars); // 右结合：false 分支也可以是嵌套三元
+    return truthy(cond) ? consequent : alternate;
+}
 function parseAnd(c, vars) {
     let left = parseNot(c, vars);
     while (isPunct(c, '&&')) {
@@ -349,7 +395,7 @@ export function evalExpr(expr, vars) {
     if (toks.length === 0)
         return undefined;
     const cursor = { toks, pos: 0 };
-    const v = parseOr(cursor, vars);
+    const v = parseTernary(cursor, vars);
     if (cursor.pos !== toks.length) {
         throw new Error(`表达式多余 token: "${expr}"`);
     }

package/plugins/workflow-runner/src/index.js

@@ -188,6 +188,7 @@ export async function* runWorkflowFromCommand(rawArgs, opts) {
         provider: opts.provider,
         signal: opts.signal,
         history: opts.history,
+        sessionState: opts.sessionState,
         cwd: opts.cwd ?? process.cwd(),
         tools: opts.tools ?? [],
     };

package/plugins/workflow-runner/src/jsonPayload.js

@@ -10,7 +10,7 @@
  *    破坏主循环。剥离必须发生在「契约要求纯 JSON」的边界，也就是 workflow 的
  *    output_schema 解析处。本模块就是那个边界的唯一实现，被两个解析点共享：
  *      - stepExecutors/llm.ts（llm + output_schema 单轮）
- *      - miniReAct.ts（agent 节点 / llm+context_files / onError:recover 三处子循环）
+ *      - stepExecutors/llm.ts（output_schema 解析处）
  *    放一处、两边 import，杜绝"只修一个解析点、另一个继续炸"的漂移。
  *
  *  处理顺序（保守、纯函数、可单测）：

package/plugins/workflow-runner/src/loader.js

@@ -103,6 +103,29 @@ function validate(obj, file) {
         throw new WorkflowLoadError("缺少必填字段 'steps' 或为空数组", file);
     }
     validateSteps(obj.steps, file, '');
+    // self_heal 校验（可选）
+    if (obj.self_heal !== undefined) {
+        const sh = obj.self_heal;
+        if (typeof sh !== 'object' || sh === null || Array.isArray(sh)) {
+            throw new WorkflowLoadError("'self_heal' 必须是对象", file);
+        }
+        if (sh.backoff !== undefined) {
+            if (typeof sh.backoff !== 'number' || !Number.isInteger(sh.backoff) || sh.backoff < 0) {
+                throw new WorkflowLoadError("self_heal.backoff 必须是 >= 0 的整数", file);
+            }
+        }
+        if (sh.max_retries !== undefined) {
+            if (typeof sh.max_retries !== 'number' || !Number.isInteger(sh.max_retries) || sh.max_retries < 1) {
+                throw new WorkflowLoadError("self_heal.max_retries 必须是 >= 1 的整数", file);
+            }
+        }
+    }
+    // artifacts 校验（WorkflowDef 级别，可选）
+    if (obj.artifacts !== undefined) {
+        if (!Array.isArray(obj.artifacts) || !obj.artifacts.every((x) => typeof x === 'string' && x.length > 0)) {
+            throw new WorkflowLoadError("'artifacts' 必须是非空字符串数组", file);
+        }
+    }
     if (obj.inputs !== undefined) {
         if (!Array.isArray(obj.inputs)) {
             throw new WorkflowLoadError("'inputs' 必须是数组", file);
@@ -133,6 +156,7 @@ export const CONTROL_FLOW_TYPES = new Set([
     'verify',
     'branch',
     'loop',
+    'break',
     'pause',
     'parallel',
     'vote',
@@ -142,6 +166,7 @@ export const VALID_STEP_TYPES = new Set([
     'verify',
     'branch',
     'loop',
+    'break',
     'pause',
     'parallel',
     'vote',
@@ -196,24 +221,47 @@ function validateSteps(steps, file, pathPrefix) {
             throw new WorkflowLoadError(`${p} type=branch 必须带 'condition'`, file);
         }
         if (s.type === 'loop') {
-            if (s.over === undefined)
-                throw new WorkflowLoadError(`${p} type=loop 必须带 'over'`, file);
-            if (typeof s.as !== 'string' || s.as.length === 0) {
-                throw new WorkflowLoadError(`${p} type=loop 必须带 'as'`, file);
+            const hasOver = s.over !== undefined;
+            const hasMaxIter = s.max_iterations !== undefined;
+            // 两种模式互斥：for-each（over 必填）或 while（max_iterations 必填）
+            if (!hasOver && !hasMaxIter) {
+                throw new WorkflowLoadError(`${p} type=loop: for-each 模式需 'over'，while 模式需 'max_iterations'，二者必选其一`, file);
+            }
+            if (hasOver) {
+                // for-each 模式
+                if (typeof s.as !== 'string' || s.as.length === 0) {
+                    throw new WorkflowLoadError(`${p} type=loop for-each 模式必须带 'as'`, file);
+                }
+            }
+            else {
+                // while 模式：as 可选（不设则不注入迭代变量）
+                if (s.as !== undefined && (typeof s.as !== 'string' || s.as.length === 0)) {
+                    throw new WorkflowLoadError(`${p} type=loop while 模式的 'as' 必须是非空字符串`, file);
+                }
             }
             if (!Array.isArray(s.do)) {
                 throw new WorkflowLoadError(`${p} type=loop 必须带 'do' 数组`, file);
             }
             validateSteps(s.do, file, `${p}.do`);
         }
+        if (s.type === 'break') {
+            // break 是循环退出信号，通常配合 when 条件使用
+            // 无额外必填字段；when 缺失时等价于无条件跳出（极少用）
+        }
         if (s.type === 'assert' && s.condition === undefined) {
             throw new WorkflowLoadError(`${p} type=assert 必须带 'condition'`, file);
         }
         if (s.type === 'verify') {
-            if (!Array.isArray(s.checks) || s.checks.length === 0) {
-                throw new WorkflowLoadError(`${p} type=verify 必须带非空 'checks' 数组`, file);
+            // 兼容两种格式：YAML 数组 或逗号分隔字符串
+            const rawChecks = Array.isArray(s.checks)
+                ? s.checks
+                : typeof s.checks === 'string'
+                    ? s.checks.split(',').map((x) => x.trim()).filter(Boolean)
+                    : [];
+            if (rawChecks.length === 0) {
+                throw new WorkflowLoadError(`${p} type=verify 必须带 checks（数组或逗号分隔字符串）`, file);
             }
-            for (const [ci, c] of s.checks.entries()) {
+            for (const [ci, c] of rawChecks.entries()) {
                 if (typeof c !== 'string' || !c.includes(':')) {
                     throw new WorkflowLoadError(`${p}.checks[${ci}] 格式错误，应为 "type:value"（如 "file_exists:./x"）`, file);
                 }
@@ -313,7 +361,7 @@ function validateSteps(steps, file, pathPrefix) {
                 throw new WorkflowLoadError(`${p}.context_files 不能用在 type=${s.type} 控制流节点上`, file);
             }
             // P3：context_files 同样是 skill 节点的静默 no-op（execSkillStep 无视它），
-            // 仅 llm 节点经 miniReAct 生效——loader 直接拒绝，避免悄悄丢弃。
+            // 仅 llm 节点经 runQuery 生效——loader 直接拒绝，避免悄悄丢弃。
             if (s.skill !== undefined) {
                 throw new WorkflowLoadError(`${p}.context_files 暂不支持 skill 节点（仅 llm 节点生效）`, file);
             }
@@ -332,5 +380,19 @@ function validateSteps(steps, file, pathPrefix) {
                 throw new WorkflowLoadError(`${p}.allowed_tools 暂不支持 skill 节点（仅 llm 节点生效）`, file);
             }
         }
+        // ---------------- Phase 1: 断点续执行 / 自愈字段校验 ----------------
+        // step.artifacts: string[]（可选）
+        if (s.artifacts !== undefined) {
+            if (!Array.isArray(s.artifacts) || !s.artifacts.every((x) => typeof x === 'string' && x.length > 0)) {
+                throw new WorkflowLoadError(`${p}.artifacts 必须是非空字符串数组`, file);
+            }
+        }
+        // step.max_retries: number（可选，>= 0 的整数）
+        if (s.max_retries !== undefined) {
+            const mr = s.max_retries;
+            if (typeof mr !== 'number' || !Number.isInteger(mr) || mr < 0) {
+                throw new WorkflowLoadError(`${p}.max_retries 必须是 >= 0 的整数`, file);
+            }
+        }
     }
 }

package/plugins/workflow-runner/src/recovery.js

@@ -6,30 +6,26 @@
  *
  *  传统 DAG 的脆点：某节点抛错 → 整条 halt（或 onError:'continue' 盲跳，下游
  *  capture 拿 undefined 静默级联错）。当节点声明 onError:'recover' 时，runner
- *  不立刻 halt，而是调本模块起一个**有界恢复 agent**（复用 miniReAct），喂给它
- *  「工作流总目标 + 失败节点的意图 + 错误信息 + 当前已知变量 + 下游 capture 契约」，
+ *  不立刻 halt，而是调本模块起一个**有界恢复 agent**（委托 runQuery/TAOR），
+ *  喂给它「工作流总目标 + 失败节点的意图 + 错误信息 + 当前已知变量 + 下游 capture 契约」，
  *  让它**随机应变去达成该节点本来要的结果**（换路径 / 换命令 / 先读后写…）。
  *
+ *  v0.9 重构：不再使用独立 miniReAct 子循环，而是委托主 TAOR 引擎（runQuery）
+ *  在共享 ctx.history 上执行。恢复过程也写入共享上下文——后续对话能看到"某步失败后
+ *  如何被自动修复"，增强可解释性。
+ *
  *  —— 共享大脑 ——
- *  恢复 agent 与 agent: 节点（stepExecutors/agent.ts）本质同构，故系统提示词纪律与
- *  验证闸门都收敛在 agentCommon.ts：本模块只贴一句「救火」角色开场白（RECOVER_OPENING），
- *  跑完后交给 interpretMiniReActResult 判定「真救回 / 放弃」——绝不把没验证过的产出当成功
- *  绑给下游。返回 AgentOutcome：
+ *  恢复 agent 与正常 agent/llm/skill 步本质同构：都通过 runQuery(TAOR) 执行。
+ *  本模块只构造「救火」角色提示词，跑完后交给 interpretMiniReActResult 判定
+ *  「真救回 / 放弃」。返回 AgentOutcome：
  *    - { ok:true, value }  —— runner 用同一个 step.capture 绑定后继续 happy path
  *    - { ok:false, reason } —— runner 带原因 honest halt
- *
- *  设计取舍：复用 miniReAct 而非 runQuery —— 恢复要的正是「有界、白名单、不污染主
- *  history、直接返回 StepResult」；默认全量 ALL_TOOLS（与 skill/agent 节点同等授权、
- *  同一信任边界），step.allowed_tools 可收窄。本函数是 AsyncGenerator，yield*
- *  runMiniReAct 把恢复 agent 的内层思考透传给 UI；warning/plugin_progress/halt 仍由
- *  runner 在调用前后发（事件卫生集中在 runner）。
  * ============================================================
  */
-import { ALL_TOOLS } from '../../../src/plugin-sdk.js';
-import { buildWorkflowAgentSystem, describeCaptureContract, interpretMiniReActResult, truncate, } from './agentCommon.js';
+import { runQuery } from '../../../src/loop.js';
+import { describeCaptureContract, interpretMiniReActResult, truncate, } from './agentCommon.js';
 import { interpolate, interpolateDeep } from './expressions.js';
-import { runMiniReAct } from './miniReAct.js';
-// RECOVERY_SYSTEM 现在是 async（需要扫描 skill/plugin），在 runRecovery 内部构建
+// RECOVER_OPENING 作为用户消息的一部分（系统提示词已在 history[0] 中）
 const RECOVER_OPENING = `你是一名资深的自动化工程师 / SRE，被一个确定性工作流临时调来「救火」。
 工作流里一个原本写死的步骤刚刚执行失败了，现在交给你随机应变——先看错误信息诊断根因，再想办法真正达成这个步骤**本来要的结果**（关注它要的结果，别拘泥它原先怎么写）。`;
 /** 描述失败节点「本来要干什么」，喂给恢复 agent 作为意图说明。 */
@@ -57,7 +53,6 @@ function describeStepIntent(step, vars) {
  * 尝试自适应恢复一个失败的动作 step。
  *   - 救回 → { ok:true, value }（value.raw 已 normalize，可被原 step.capture 绑定）
  *   - 放弃 / 不可信 / 子循环抛错（含用户中断）→ { ok:false, reason }
- *     （中断的最终语义由调用方在拿到结果后另行检测 ctx.signal 决定）
  */
 export async function* runRecovery(step, vars, ctx, errorMsg) {
     const intent = describeStepIntent(step, vars);
@@ -67,33 +62,46 @@ export async function* runRecovery(step, vars, ctx, errorMsg) {
     const hintLine = step.recover_hint
         ? `\n\n作者给恢复的提示：${interpolate(step.recover_hint, vars)}`
         : '';
-    const userMsg = `${goalLine}` +
+    // 构造恢复 prompt（作为 user message push 进共享 history）
+    const recoverPrompt = `${RECOVER_OPENING}\n\n` +
+        `${goalLine}` +
         `失败的步骤（id=${step.id}）本来要做的事：\n${intent}\n\n` +
         `它失败时的错误：\n${truncate(errorMsg, 800)}\n\n` +
         `当前已知的变量（JSON）：\n${knownVars}` +
         `${captureLine}${hintLine}\n\n` +
         `请随机应变，把这一步要的结果做出来；做不成就按约定输出放弃标记。`;
-    // 工具集：默认全量（与 skill/agent 节点同等 agency）；step.allowed_tools 收窄。
-    const allowed = step.allowed_tools;
-    const tools = allowed && allowed.length > 0
-        ? ALL_TOOLS.filter((t) => allowed.includes(t.name))
-        : ALL_TOOLS;
-    // ✅ Phase 2: 异步构建完整 system prompt（含 skill/plugin 列表）
-    const systemContent = await buildWorkflowAgentSystem(ctx.cwd, RECOVER_OPENING, tools);
-    const messages = [
-        { role: 'system', content: systemContent },
-        { role: 'user', content: userMsg },
-    ];
+    // output_schema 约束嵌入 prompt
+    const schemaHint = step.output_schema
+        ? `\n\n【结构化输出约束】请严格按照以下 JSON Schema 输出结果：\n${JSON.stringify(step.output_schema, null, 2)}`
+        : '';
+    const fullPrompt = recoverPrompt + schemaHint;
+    // 记录 history 长度用于提取本步输出
+    const historyLenBefore = ctx.history.length;
     try {
-        const result = yield* runMiniReAct({
-            messages,
-            tools,
-            output_schema: step.output_schema,
+        // 委托 TAOR 引擎执行——事件透传给 UI（显示恢复进度）
+        yield* runQuery(fullPrompt, {
             provider: ctx.provider,
+            history: ctx.history,
             signal: ctx.signal,
             maxTurns: step.maxTurns ?? 12,
+            chat: ctx.chat,
+            executeTool: ctx.executeTool,
+            sessionState: ctx.sessionState,
         });
-        const outcome = interpretMiniReActResult(result, step.output_schema !== undefined);
+        // 从 history 提取本步最后一条 assistant 消息
+        let rawText = '';
+        for (let i = ctx.history.length - 1; i >= historyLenBefore; i--) {
+            const msg = ctx.history[i];
+            if (msg.role === 'assistant' && typeof msg.content === 'string' && msg.content.trim()) {
+                rawText = msg.content;
+                break;
+            }
+        }
+        const stepResult = {
+            raw: { text: rawText, result: rawText },
+            preview: rawText.length > 200 ? `${rawText.slice(0, 200)}...` : rawText,
+        };
+        const outcome = interpretMiniReActResult(stepResult, !!step.output_schema);
         if (!outcome.ok)
             return outcome;
         // 救回：preview 加 recovered: 前缀（runner 的 step_end output 用），raw 原样。
@@ -103,7 +111,7 @@ export async function* runRecovery(step, vars, ctx, errorMsg) {
         };
     }
     catch (e) {
-        // miniReAct 抛错（用尽轮数 / 重复工具调用 / schema 解析失败 / 中断）→ 恢复失败。
+        // runQuery 抛错（用尽轮数 / 中断）→ 恢复失败。
         return { ok: false, reason: e.message ?? String(e) };
     }
 }