minimal-agent 0.8.2 → 0.10.0

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

@@ -1,22 +1,23 @@
 /**
  * ============================================================
- *  src/workflows/loader.ts —— workflow yaml 双源加载 + 最小校验
+ *  plugins/workflow-runner/src/loader.ts —— workflow yaml 双源加载 + 校验
  * ------------------------------------------------------------
  *  - 扫描 cwd/workflows/ 与 packageRoot/workflows/（cwd 优先，复用
  *    getResourceSearchPaths 契约）
  *  - 一个坏 yaml 不应拖累其它工作流（catch 单文件错误，继续扫描）
  *  - 目录不存在 / 为空 → 静默返回 []（默认 T-A-O-R 不受影响）
  *
- *  P0 不引 AJV；下面手写 ≤80 行的最小校验器，只挡死硬性错误：
- *    - name / description / steps 必填且类型正确
- *    - steps 非空
- *    - 每个 step 必须有且只有一个动作字段（tool / skill / llm / type）
- *
- *  P1 切 AJV 做完整 schema。
+ *  不引 AJV：下面手写校验器（validate/validateSteps），覆盖结构性硬错误并对
+ *  每条 step 字段做类型/一致性校验——
+ *    - name / description / steps 必填且类型正确；steps 非空
+ *    - 每个 step 必须有且只有一个动作字段（tool / skill / llm / agent / type）
+ *    - 控制流字段一致性 + ADR-05 的 llm-only 字段（output_schema/context_files/
+ *      allowed_tools）准入 + 断点续跑字段（artifacts/max_retries）类型
+ *  手写而非 schema 库：依赖少、错误信息可中文化、按减法不为「完整 schema」引依赖。
  * ============================================================
  */
 import { readFile, readdir } from 'node:fs/promises';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { parse as parseYamlLib } from 'yaml';
 import { getResourceSearchPaths } from '../../../src/plugin-sdk.js';
 export class WorkflowLoadError extends Error {
@@ -31,10 +32,10 @@ export class WorkflowLoadError extends Error {
  * 扫描双源目录，返回所有 *.yaml / *.yml 解析后的 workflow。
  * 永远不抛；坏文件 console.warn 并跳过。
  */
-export async function listWorkflows() {
+export async function listWorkflows(workingDir) {
     const out = [];
     const seen = new Set();
-    const roots = getResourceSearchPaths('workflows', import.meta.url);
+    const roots = getResourceSearchPaths('workflows', import.meta.url, workingDir);
     for (const root of roots) {
         let entries;
         try {
@@ -63,9 +64,21 @@ export async function listWorkflows() {
     return out;
 }
 /** 按 name 查找。找不到返回 null —— 调用方决定如何提示用户。 */
-export async function findWorkflowByName(name) {
-    const all = await listWorkflows();
-    return all.find((w) => w.name === name) ?? null;
+export async function findWorkflowByName(name, workingDir) {
+    const all = await listWorkflows(workingDir);
+    const normalized = normalizeWorkflowLookupName(name);
+    return all.find((w) => w.name === normalized || workflowFileBaseName(w) === normalized) ?? null;
+}
+function stripYamlExt(name) {
+    return name.replace(/\.ya?ml$/i, '');
+}
+function normalizeWorkflowLookupName(name) {
+    return stripYamlExt(basename(name));
+}
+function workflowFileBaseName(workflow) {
+    if (!workflow.__source)
+        return null;
+    return stripYamlExt(basename(workflow.__source));
 }
 /** 读单个 yaml 文件 → 解析 → 校验。失败抛 WorkflowLoadError。 */
 export async function parseWorkflowFile(file) {
@@ -103,6 +116,39 @@ 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);
+            }
+        }
+        if (sh.retry_delay_ms !== undefined) {
+            if (typeof sh.retry_delay_ms !== 'number' || !Number.isFinite(sh.retry_delay_ms) || sh.retry_delay_ms < 0) {
+                throw new WorkflowLoadError("self_heal.retry_delay_ms 必须是 >= 0 的数字（毫秒）", file);
+            }
+        }
+        if (sh.max_turns_retry_delay_ms !== undefined) {
+            if (typeof sh.max_turns_retry_delay_ms !== 'number' || !Number.isFinite(sh.max_turns_retry_delay_ms) || sh.max_turns_retry_delay_ms < 0) {
+                throw new WorkflowLoadError("self_heal.max_turns_retry_delay_ms 必须是 >= 0 的数字（毫秒）", 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);
@@ -121,37 +167,71 @@ function validate(obj, file) {
             if (r.type === 'enum' && (!Array.isArray(r.values) || r.values.length === 0)) {
                 throw new WorkflowLoadError(`inputs[${i}].values 必填（type=enum 时）`, file);
             }
+            // greedy 首参：只许 boolean，且只能标在第一个 input（语义=吸收全部位置参数，
+            // 标在非首位无意义且会误导，响亮拒绝）。
+            if (r.greedy !== undefined && typeof r.greedy !== 'boolean') {
+                throw new WorkflowLoadError(`inputs[${i}].greedy 必须是 boolean`, file);
+            }
+            if (r.greedy === true && i !== 0) {
+                throw new WorkflowLoadError(`inputs[${i}].greedy 只能标在第一个 input 上`, file);
+            }
         }
     }
 }
 // ADR-05: 控制流 type 集合——这些节点的"动作"由 type 自身定义，
 // 因此不能附带 tool/skill/llm 也不能配 output_schema / context_files / allowed_tools。
-// 导出供「editor ↔ 后端」schema 一致性测试比对（test/editorSchemaSync.test.ts）。
+// 导出供「editor ↔ 后端」schema 一致性测试比对（test/workflowEditorSchemaSync.test.ts）。
 // editor 因 D2 红线禁止 import 后端、手抄了同一份；后端在此演进时该测试会红，提示同步 editor。
 export const CONTROL_FLOW_TYPES = new Set([
     'assert',
     'verify',
+    'set',
     'branch',
     'loop',
+    'break',
+    'continue',
+    'echo',
     'pause',
-    'parallel',
-    'vote',
 ]);
 export const VALID_STEP_TYPES = new Set([
     'assert',
     'verify',
+    'set',
     'branch',
     'loop',
+    'break',
+    'continue',
+    'echo',
     'pause',
-    'parallel',
-    'vote',
 ]);
 // 动作字段里「自带 kind 含义」的那几个（不含 type —— type 的 kind 由其值决定）。
-// 单一来源：validateSteps 的 actionFields + test/editorSchemaSync.test.ts 都从这里取，
+// 单一来源：validateSteps 的 actionFields + test/workflowEditorSchemaSync.test.ts 都从这里取，
 // 新增动作 kind 只改这一处（并同步 editor 手抄镜像 + 该测试快照）。
 export const ACTION_KINDS = ['tool', 'skill', 'agent', 'llm'];
 // onError 合法值（单一来源：onError 校验 + editor schema 同步测试）。
 export const ON_ERROR_VALUES = ['halt', 'continue', 'recover'];
+function isValidMaxIterations(value) {
+    return ((typeof value === 'number' && Number.isInteger(value) && value > 0) ||
+        (typeof value === 'string' && (value.includes('${') || /^\d+$/.test(value.trim()))));
+}
+function isValidImageDetail(value) {
+    return value === 'low' || value === 'default' || value === 'high';
+}
+function assertLlmOrAgentMultimodalField(s, key, p, file) {
+    if (s.llm === undefined && s.agent === undefined) {
+        throw new WorkflowLoadError(`${p}.${key} 仅支持 llm / agent 节点`, file);
+    }
+}
+function assertHistoryModeField(s, p, file) {
+    if (s.llm === undefined && s.agent === undefined && s.skill === undefined) {
+        throw new WorkflowLoadError(`${p}.history_mode 只能用在 llm / agent / skill 节点上`, file);
+    }
+}
+function requireNonEmptyString(s, key, p, file, typeName) {
+    if (typeof s[key] !== 'string' || String(s[key]).length === 0) {
+        throw new WorkflowLoadError(`${p} type=${typeName} requires non-empty '${key}'`, file);
+    }
+}
 function validateSteps(steps, file, pathPrefix) {
     const seenIds = new Set();
     for (const [i, item] of steps.entries()) {
@@ -191,30 +271,194 @@ function validateSteps(steps, file, pathPrefix) {
         if (s.recover_hint !== undefined && typeof s.recover_hint !== 'string') {
             throw new WorkflowLoadError(`${p}.recover_hint 必须是 string`, file);
         }
+        if (s.free_text !== undefined) {
+            if (s.type !== 'pause') {
+                throw new WorkflowLoadError(`${p}.free_text 只能用在 type=pause 节点上`, file);
+            }
+            if (s.free_text !== 'halt' && s.free_text !== 'approve') {
+                throw new WorkflowLoadError(`${p}.free_text "${String(s.free_text)}" 非法；合法值: halt / approve`, file);
+            }
+        }
+        // 数字字段类型校验：yaml 给字符串会静默进入运行时算术（NaN footgun），加载期拦掉
+        if (s.maxTurns !== undefined &&
+            (typeof s.maxTurns !== 'number' || !Number.isInteger(s.maxTurns) || s.maxTurns < 1)) {
+            throw new WorkflowLoadError(`${p}.maxTurns 必须是 >= 1 的整数`, file);
+        }
+        if (s.max_retries !== undefined &&
+            (typeof s.max_retries !== 'number' || !Number.isInteger(s.max_retries) || s.max_retries < 0)) {
+            throw new WorkflowLoadError(`${p}.max_retries 必须是 >= 0 的整数`, file);
+        }
+        // 多模态图片输入：仅 llm / agent 节点支持；skill/控制流/确定性 tool 节点
+        // 不接收图片字段，避免 yaml 作者以为图片已传给模型但实际被静默忽略。
+        const multimodalFields = [
+            'images',
+            'parse_inline_images',
+            'image_detail',
+            'image_max_long_side_pixel',
+        ];
+        for (const key of multimodalFields) {
+            if (s[key] !== undefined)
+                assertLlmOrAgentMultimodalField(s, key, p, file);
+        }
+        if (s.images !== undefined) {
+            if (!Array.isArray(s.images)) {
+                throw new WorkflowLoadError(`${p}.images 必须是数组`, file);
+            }
+            for (const [j, item] of s.images.entries()) {
+                if (typeof item === 'string') {
+                    if (item.length === 0) {
+                        throw new WorkflowLoadError(`${p}.images[${j}] 必须是非空 string`, file);
+                    }
+                    continue;
+                }
+                if (!item || typeof item !== 'object' || Array.isArray(item)) {
+                    throw new WorkflowLoadError(`${p}.images[${j}] 必须是 string 或 { source, detail?, max_long_side_pixel? }`, file);
+                }
+                const r = item;
+                if (typeof r.source !== 'string' || r.source.length === 0) {
+                    throw new WorkflowLoadError(`${p}.images[${j}].source 必须是非空 string`, file);
+                }
+                if (r.detail !== undefined && !isValidImageDetail(r.detail)) {
+                    throw new WorkflowLoadError(`${p}.images[${j}].detail 必须是 low/default/high`, file);
+                }
+                if (r.max_long_side_pixel !== undefined &&
+                    (typeof r.max_long_side_pixel !== 'number' ||
+                        !Number.isInteger(r.max_long_side_pixel) ||
+                        r.max_long_side_pixel < 1)) {
+                    throw new WorkflowLoadError(`${p}.images[${j}].max_long_side_pixel 必须是正整数`, file);
+                }
+            }
+        }
+        if (s.parse_inline_images !== undefined &&
+            typeof s.parse_inline_images !== 'boolean') {
+            throw new WorkflowLoadError(`${p}.parse_inline_images 必须是 boolean`, file);
+        }
+        if (s.image_detail !== undefined && !isValidImageDetail(s.image_detail)) {
+            throw new WorkflowLoadError(`${p}.image_detail 必须是 low/default/high`, file);
+        }
+        if (s.image_max_long_side_pixel !== undefined &&
+            (typeof s.image_max_long_side_pixel !== 'number' ||
+                !Number.isInteger(s.image_max_long_side_pixel) ||
+                s.image_max_long_side_pixel < 1)) {
+            throw new WorkflowLoadError(`${p}.image_max_long_side_pixel 必须是正整数`, file);
+        }
+        if (s.history_mode !== undefined) {
+            assertHistoryModeField(s, p, file);
+            if (s.history_mode !== 'shared' && s.history_mode !== 'isolated') {
+                throw new WorkflowLoadError(`${p}.history_mode "${String(s.history_mode)}" 非法；合法值: shared / isolated`, file);
+            }
+        }
         // 控制流字段一致性
         if (s.type === 'branch' && s.condition === undefined) {
             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);
+                }
+                // max_iterations：正整数 或 含 ${} 的模板字符串（运行时插值 + coerce，
+                // 失败响亮报错）。裸字符串数字（"50"）也容忍。其它一律加载期拦掉——
+                // 曾有 "${max_iterations}" 不被插值直接参与 < 比较 → NaN → 静默 0 次迭代。
+                const mi = s.max_iterations;
+                if (!isValidMaxIterations(mi)) {
+                    throw new WorkflowLoadError(`${p}.max_iterations 必须是正整数或含 \${} 的模板字符串，得到: ${JSON.stringify(mi)}`, 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 缺失时等价于无条件跳出（极少用）
+        }
+        // continue：跳到（目标）循环的下一轮迭代；与 break 同族（when 可选）
+        // echo：确定性输出 message（支持 ${} 插值），不烧 LLM
+        if (s.type === 'echo') {
+            requireNonEmptyString(s, 'message', p, file, 'echo');
+        }
+        else if (s.message !== undefined) {
+            throw new WorkflowLoadError(`${p}.message 只能用在 type=echo 节点上`, file);
+        }
+        // target：仅 break/continue 的标签语义（指定要穿透到哪一层循环）
+        if (s.target !== undefined) {
+            if (s.type !== 'break' && s.type !== 'continue') {
+                throw new WorkflowLoadError(`${p}.target 只能用在 type=break / type=continue 节点上`, file);
+            }
+            if (typeof s.target !== 'string' || s.target.length === 0) {
+                throw new WorkflowLoadError(`${p}.target 必须是非空 string（目标循环的 id）`, file);
+            }
+        }
+        // title：任意步可选的人话进度显示名（声明后状态行显示它、不显示块内相对序号）
+        if (s.title !== undefined && (typeof s.title !== 'string' || s.title.length === 0)) {
+            throw new WorkflowLoadError(`${p}.title 必须是非空 string（进度显示名）`, file);
+        }
+        // goal_supplement：动作步与 pause 可声明（产出作为用户补充要求贯穿后续步骤）
+        if (s.goal_supplement !== undefined) {
+            if (typeof s.goal_supplement !== 'boolean') {
+                throw new WorkflowLoadError(`${p}.goal_supplement 必须是 boolean`, file);
+            }
+            const isActionStep = ACTION_KINDS.some((k) => s[k] !== undefined);
+            if (!isActionStep && s.type !== 'pause') {
+                throw new WorkflowLoadError(`${p}.goal_supplement 只能用在动作步（${ACTION_KINDS.join('/')}）或 type=pause 节点上`, file);
+            }
+        }
+        // done_when：仅 agent 步可选（确定性完成条件，引擎 nudge 兜底 announce-not-do 烂尾）
+        if (s.done_when !== undefined) {
+            if (typeof s.done_when !== 'string' || s.done_when.trim().length === 0) {
+                throw new WorkflowLoadError(`${p}.done_when 必须是非空 string（白名单表达式）`, file);
+            }
+            if (s.agent === undefined) {
+                throw new WorkflowLoadError(`${p}.done_when 仅支持 agent 节点`, file);
+            }
+        }
         if (s.type === 'assert' && s.condition === undefined) {
             throw new WorkflowLoadError(`${p} type=assert 必须带 'condition'`, file);
         }
+        // set：确定性变量赋值（曾有 yaml 用 llm:"PLAN" 当赋值——模型自由回复非确定，set 是根治）
+        if (s.type === 'set') {
+            if (!s.set ||
+                typeof s.set !== 'object' ||
+                Array.isArray(s.set) ||
+                Object.keys(s.set).length === 0) {
+                throw new WorkflowLoadError(`${p} type=set 必须带非空对象 'set'（{ 变量名: 值 }，值支持 \${} 插值）`, 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()) {
-                if (typeof c !== 'string' || !c.includes(':')) {
+            for (const [ci, c] of rawChecks.entries()) {
+                if (typeof c !== 'string') {
+                    throw new WorkflowLoadError(`${p}.checks[${ci}] 必须是字符串`, file);
+                }
+                // 含 ${...} 模板的 check（如 checks: "${verify_checks}"）在运行时插值后才知道真实值，
+                // 加载期跳过格式校验，交给 verify.ts 在插值后解析。否则这类合法的动态配置会被
+                // 误判为"损坏 yaml"而整个工作流加载失败（ralph-loop 的 run_verify 即如此）。
+                if (c.includes('${'))
+                    continue;
+                if (!c.includes(':')) {
                     throw new WorkflowLoadError(`${p}.checks[${ci}] 格式错误，应为 "type:value"（如 "file_exists:./x"）`, file);
                 }
             }
@@ -232,50 +476,6 @@ function validateSteps(steps, file, pathPrefix) {
                 validateSteps(s.else, file, `${p}.else`);
         }
         // ---------------- ADR-05 新增校验 ----------------
-        // parallel：必须有非空 fork[]，递归校验子步骤
-        if (s.type === 'parallel') {
-            if (!Array.isArray(s.fork) || s.fork.length === 0) {
-                throw new WorkflowLoadError(`${p} type=parallel 必须有 fork: [...]（至少 1 个子步骤）`, file);
-            }
-            validateSteps(s.fork, file, `${p}.fork`);
-        }
-        else if (s.fork !== undefined) {
-            throw new WorkflowLoadError(`${p}.fork 只能用在 type=parallel 节点上`, file);
-        }
-        // vote：voters_count (2~10) / rules / input 必填；threshold 可选但越界要拦
-        if (s.type === 'vote') {
-            const vc = s.voters_count;
-            const rules = s.rules;
-            const input = s.input;
-            const missing = typeof vc !== 'number' ||
-                !Number.isInteger(vc) ||
-                vc < 2 ||
-                vc > 10 ||
-                typeof rules !== 'string' ||
-                rules.length === 0 ||
-                typeof input !== 'string' ||
-                input.length === 0;
-            if (missing) {
-                throw new WorkflowLoadError(`${p} type=vote 要求 voters_count (2~10), rules, input 三个字段`, file);
-            }
-            if (s.threshold !== undefined) {
-                const t = s.threshold;
-                if (typeof t !== 'number' ||
-                    !Number.isInteger(t) ||
-                    t < 1 ||
-                    t > vc) {
-                    throw new WorkflowLoadError(`${p} threshold=${String(t)} 超出范围；必须是 1 <= threshold <= voters_count(${vc})`, file);
-                }
-            }
-        }
-        else {
-            // 非 vote 节点不应携带 vote-only 字段
-            for (const k of ['voters_count', 'rules', 'threshold']) {
-                if (s[k] !== undefined) {
-                    throw new WorkflowLoadError(`${p}.${k} 只能用在 type=vote 节点上`, file);
-                }
-            }
-        }
         // output_schema：必须是 object；不能用在控制流节点上
         if (s.output_schema !== undefined) {
             if (typeof s.output_schema !== 'object' ||
@@ -313,7 +513,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 +532,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/multimodal.js

@@ -0,0 +1,37 @@
+import { isAbsolute, resolve } from 'node:path';
+import { interpolate } from './expressions.js';
+export function resolveWorkflowMultimodalOptions(step, vars, ctx, onMissing) {
+    const imageDetail = step.image_detail;
+    const imageMaxLongSidePixel = step.image_max_long_side_pixel;
+    const imageInputs = (step.images ?? []).map((item) => {
+        if (typeof item === 'string') {
+            return {
+                source: resolveWorkflowImageSource(interpolate(item, vars, { onMissing }), ctx),
+                detail: imageDetail,
+                maxLongSidePixel: imageMaxLongSidePixel,
+            };
+        }
+        return {
+            source: resolveWorkflowImageSource(interpolate(item.source, vars, { onMissing }), ctx),
+            detail: item.detail ?? imageDetail,
+            maxLongSidePixel: item.max_long_side_pixel ?? imageMaxLongSidePixel,
+        };
+    });
+    return {
+        imageInputs: imageInputs.length > 0 ? imageInputs : undefined,
+        parseInlineImages: step.parse_inline_images,
+        imageDetail,
+        imageMaxLongSidePixel,
+    };
+}
+function resolveWorkflowImageSource(source, ctx) {
+    const clean = source.trim();
+    if (/^https?:\/\//i.test(clean) ||
+        /^data:image\//i.test(clean) ||
+        clean.startsWith('file://') ||
+        clean.startsWith('~/') ||
+        isAbsolute(clean)) {
+        return clean;
+    }
+    return resolve(ctx.cwd, clean);
+}

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

@@ -6,30 +6,25 @@
  *
  *  传统 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 { describeCaptureContract, effectiveGoalAnchor, interpretMiniReActResult, runStepQuery, 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 +52,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 +61,49 @@ 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)}`
+        : '';
+    // 通用目标锚定（同 agent/llm/skill 步）：恢复 agent 也要看到用户原始目标
+    // 与补充要求，不能只有 def.description 的"工作流总目标"（E10）。
+    const anchor = effectiveGoalAnchor(ctx);
+    const fullPrompt = anchor
+        ? `${anchor}\n\n${recoverPrompt}${schemaHint}`
+        : recoverPrompt + schemaHint;
     try {
-        const result = yield* runMiniReAct({
-            messages,
-            tools,
-            output_schema: step.output_schema,
-            provider: ctx.provider,
-            signal: ctx.signal,
-            maxTurns: step.maxTurns ?? 12,
-        });
-        const outcome = interpretMiniReActResult(result, step.output_schema !== undefined);
+        // 委托 TAOR 引擎执行（共享消费层 runStepQuery）——事件透传给 UI（显示恢复进度）。
+        // 注意剥掉 step 的 allowed_tools 白名单：原步收敛工具是为弱模型聚焦，
+        // 恢复 agent 的职责正是「随机应变换路径」，要全工具箱（保持 v0.9 行为）。
+        const { rawText, sawLlmError, sawMaxTurns, llmErrorDetail } = yield* runStepQuery(fullPrompt, { ...step, allowed_tools: undefined }, ctx, { maxTurns: step.maxTurns ?? 25 });
+        // 恢复是兜底路径：无论 provider 失败还是模型空答，都按「没救回」返回
+        // ok:false（不抛重试——retry 在进入 recover 前已用尽）；只是归因更诚实。
+        if (!rawText.trim() && sawLlmError) {
+            return {
+                ok: false,
+                reason: `LLM 调用失败且无产出${llmErrorDetail ? `—— ${truncate(llmErrorDetail, 300)}` : ''}`,
+            };
+        }
+        // 恢复 agent 也撞 maxTurns 截断 → 截断产出不可信，诚实「未救回」
+        if (sawMaxTurns) {
+            return {
+                ok: false,
+                reason: `恢复 agent 达到最大轮数 ${step.maxTurns ?? 25} 被截断，产出不可信（未救回）`,
+            };
+        }
+        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 +113,7 @@ export async function* runRecovery(step, vars, ctx, errorMsg) {
         };
     }
     catch (e) {
-        // miniReAct 抛错（用尽轮数 / 重复工具调用 / schema 解析失败 / 中断）→ 恢复失败。
+        // runStepQuery 抛错（编程性异常 / 中断竞态）→ 恢复失败。
         return { ok: false, reason: e.message ?? String(e) };
     }
 }