minimal-agent 0.12.0 → 0.14.0

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

@@ -1,573 +0,0 @@
-/**
- * ============================================================
- *  plugins/workflow-runner/src/loader.ts —— workflow yaml 双源加载 + 校验
- * ------------------------------------------------------------
- *  - 扫描 cwd/workflows/ 与 packageRoot/workflows/（cwd 优先，复用
- *    getResourceSearchPaths 契约）
- *  - 一个坏 yaml 不应拖累其它工作流（catch 单文件错误，继续扫描）
- *  - 目录不存在 / 为空 → 静默返回 []（默认 T-A-O-R 不受影响）
- *
- *  不引 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 { basename, join } from 'node:path';
-import { parse as parseYamlLib } from 'yaml';
-import { getResourceSearchPaths } from '../../../src/plugin-sdk.js';
-export class WorkflowLoadError extends Error {
-    file;
-    constructor(message, file) {
-        super(message);
-        this.file = file;
-        this.name = 'WorkflowLoadError';
-    }
-}
-/**
- * 扫描双源目录，返回所有 *.yaml / *.yml 解析后的 workflow。
- * 永远不抛；坏文件 console.warn 并跳过。
- */
-export async function listWorkflows(workingDir) {
-    const out = [];
-    const seen = new Set();
-    const roots = getResourceSearchPaths('workflows', import.meta.url, workingDir);
-    for (const root of roots) {
-        let entries;
-        try {
-            entries = await readdir(root);
-        }
-        catch {
-            continue;
-        }
-        for (const f of entries) {
-            if (!f.endsWith('.yaml') && !f.endsWith('.yml'))
-                continue;
-            const full = join(root, f);
-            try {
-                const def = await parseWorkflowFile(full);
-                if (!seen.has(def.name)) {
-                    seen.add(def.name);
-                    out.push(def);
-                }
-            }
-            catch (e) {
-                // eslint-disable-next-line no-console
-                console.warn(`[workflows] 忽略损坏的 yaml ${full}: ${e.message}`);
-            }
-        }
-    }
-    return out;
-}
-/** 按 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) {
-    let raw;
-    try {
-        raw = await readFile(file, 'utf8');
-    }
-    catch (e) {
-        throw new WorkflowLoadError(`无法读取 ${file}: ${e.message}`, file);
-    }
-    let data;
-    try {
-        data = parseYamlLib(raw);
-    }
-    catch (e) {
-        throw new WorkflowLoadError(`yaml 语法错误: ${e.message}`, file);
-    }
-    if (!data || typeof data !== 'object') {
-        throw new WorkflowLoadError('yaml 根节点必须是对象', file);
-    }
-    validate(data, file);
-    const def = data;
-    def.__source = file;
-    return def;
-}
-// ---------------- 手写最小校验 ----------------
-function validate(obj, file) {
-    if (typeof obj.name !== 'string' || obj.name.length === 0) {
-        throw new WorkflowLoadError("缺少必填字段 'name'（string）", file);
-    }
-    if (typeof obj.description !== 'string' || obj.description.length === 0) {
-        throw new WorkflowLoadError("缺少必填字段 'description'（string）", file);
-    }
-    if (!Array.isArray(obj.steps) || obj.steps.length === 0) {
-        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);
-        }
-        for (const [i, item] of obj.inputs.entries()) {
-            if (!item || typeof item !== 'object') {
-                throw new WorkflowLoadError(`inputs[${i}] 必须是对象`, file);
-            }
-            const r = item;
-            if (typeof r.name !== 'string' || r.name.length === 0) {
-                throw new WorkflowLoadError(`inputs[${i}].name 必填`, file);
-            }
-            if (r.type !== undefined && r.type !== 'string' && r.type !== 'number' && r.type !== 'enum') {
-                throw new WorkflowLoadError(`inputs[${i}].type 必须是 string/number/enum`, 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/workflowEditorSchemaSync.test.ts）。
-// editor 因 D2 红线禁止 import 后端、手抄了同一份；后端在此演进时该测试会红，提示同步 editor。
-export const CONTROL_FLOW_TYPES = new Set([
-    'assert',
-    'verify',
-    'set',
-    'branch',
-    'loop',
-    'break',
-    'continue',
-    'echo',
-    'pause',
-]);
-/**
- * `uses:` 的合法取值。与 `types.ts::HostCapability` 同源 —— 加新能力要两处一起改，
- * 单测钉住二者一致（漏改的表现是 yaml 写了却静默不生效）。
- */
-export const VALID_HOST_CAPABILITIES = new Set(['browser', 'computer']);
-export const VALID_STEP_TYPES = new Set([
-    'assert',
-    'verify',
-    'set',
-    'branch',
-    'loop',
-    'break',
-    'continue',
-    'echo',
-    'pause',
-]);
-// 动作字段里「自带 kind 含义」的那几个（不含 type —— type 的 kind 由其值决定）。
-// 单一来源：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()) {
-        const p = pathPrefix ? `${pathPrefix}.steps[${i}]` : `steps[${i}]`;
-        if (!item || typeof item !== 'object') {
-            throw new WorkflowLoadError(`${p} 必须是对象`, file);
-        }
-        const s = item;
-        if (typeof s.id !== 'string' || s.id.length === 0) {
-            throw new WorkflowLoadError(`${p}.id 必填`, file);
-        }
-        // id 唯一仅在同级 steps 数组内强制
-        if (seenIds.has(s.id)) {
-            throw new WorkflowLoadError(`${p}.id "${s.id}" 在当前 steps 列表中重复`, file);
-        }
-        seenIds.add(s.id);
-        // type 枚举校验（提前于动作互斥，给更准确的错误信息）
-        if (s.type !== undefined && (typeof s.type !== 'string' || !VALID_STEP_TYPES.has(s.type))) {
-            throw new WorkflowLoadError(`${p}.type "${String(s.type)}" 非法；合法值: ${[...VALID_STEP_TYPES].join(' / ')}`, file);
-        }
-        // 动作字段恰好一个（ACTION_KINDS 单一来源 + 控制流 type）
-        const actionFields = [...ACTION_KINDS, 'type'];
-        const present = actionFields.filter((k) => s[k] !== undefined);
-        if (present.length === 0) {
-            throw new WorkflowLoadError(`${p} 必须有以下字段之一: ${actionFields.join(' / ')}`, file);
-        }
-        if (present.length > 1) {
-            throw new WorkflowLoadError(`${p} 同时设置了 ${present.join(', ')}；只允许其中一个`, file);
-        }
-        // onError 枚举校验：runner 只认 halt/continue/recover，typo 会被静默当 halt，
-        // 故在加载期拦掉，给作者明确错误。
-        if (s.onError !== undefined &&
-            !ON_ERROR_VALUES.includes(s.onError)) {
-            throw new WorkflowLoadError(`${p}.onError "${String(s.onError)}" 非法；合法值: ${ON_ERROR_VALUES.join(' / ')}`, file);
-        }
-        // recover_hint 必须是字符串（仅 onError:'recover' 时有意义，但不强制配对）
-        if (s.recover_hint !== undefined && typeof s.recover_hint !== 'string') {
-            throw new WorkflowLoadError(`${p}.recover_hint 必须是 string`, file);
-        }
-        // uses：宿主能力声明。写错的代价是「这一步安静地拿不到能力」，而工具的报错
-        // （「当前宿主未启用 Computer Use」）完全指不向拼错的 yaml —— 所以在加载期拦掉。
-        if (s.uses !== undefined) {
-            if (!Array.isArray(s.uses)) {
-                throw new WorkflowLoadError(`${p}.uses 必须是数组，如 uses: [computer]`, file);
-            }
-            for (const capability of s.uses) {
-                if (!VALID_HOST_CAPABILITIES.has(capability)) {
-                    throw new WorkflowLoadError(`${p}.uses 含非法能力 "${String(capability)}"；合法值: ${[...VALID_HOST_CAPABILITIES].join(' / ')}`, file);
-                }
-            }
-            // uses 只对确定性 tool 步有意义：llm/agent/skill 走 runQuery，工具上下文由
-            // 主循环提供；控制流步根本不调工具。声明在这些步上是作者的误解，早点说破。
-            if (s.tool === undefined) {
-                throw new WorkflowLoadError(`${p}.uses 只能用在 tool 步上（当前步不是 tool 步）。`
-                    + `agent/llm/skill 步的工具上下文由主循环提供，无需也不能在此声明。`, 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') {
-            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') {
-            // 兼容两种格式：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 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);
-                }
-            }
-        }
-        if (s.type === 'branch') {
-            if (s.then !== undefined && !Array.isArray(s.then)) {
-                throw new WorkflowLoadError(`${p}.then 必须是数组`, file);
-            }
-            if (s.else !== undefined && !Array.isArray(s.else)) {
-                throw new WorkflowLoadError(`${p}.else 必须是数组`, file);
-            }
-            if (Array.isArray(s.then))
-                validateSteps(s.then, file, `${p}.then`);
-            if (Array.isArray(s.else))
-                validateSteps(s.else, file, `${p}.else`);
-        }
-        // ---------------- ADR-05 新增校验 ----------------
-        // output_schema：必须是 object；不能用在控制流节点上
-        if (s.output_schema !== undefined) {
-            if (typeof s.output_schema !== 'object' ||
-                s.output_schema === null ||
-                Array.isArray(s.output_schema)) {
-                throw new WorkflowLoadError(`${p}.output_schema 必须是对象`, file);
-            }
-            if (typeof s.type === 'string' && CONTROL_FLOW_TYPES.has(s.type)) {
-                throw new WorkflowLoadError(`${p}.output_schema 不能用在 type=${s.type} 控制流节点上`, file);
-            }
-            // P3：output_schema 在 skill 节点上是静默 no-op（execSkillStep 无视它）。
-            // 与其悄悄丢弃，不如 loader 直接拒绝——仅 llm 节点支持 structured output。
-            if (s.skill !== undefined) {
-                throw new WorkflowLoadError(`${p}.output_schema 暂不支持 skill 节点（仅 llm 节点生效）`, file);
-            }
-        }
-        // context_files：[{ path, hint? }]；不能用在控制流节点上
-        if (s.context_files !== undefined) {
-            if (!Array.isArray(s.context_files)) {
-                throw new WorkflowLoadError(`${p}.context_files 必须是数组`, file);
-            }
-            for (const [j, cf] of s.context_files.entries()) {
-                if (!cf || typeof cf !== 'object' || Array.isArray(cf)) {
-                    throw new WorkflowLoadError(`${p}.context_files[${j}] 必须是 { path: string, hint?: string } 对象`, file);
-                }
-                const r = cf;
-                if (typeof r.path !== 'string' || r.path.length === 0) {
-                    throw new WorkflowLoadError(`${p}.context_files[${j}].path 必填（非空 string）`, file);
-                }
-                if (r.hint !== undefined && typeof r.hint !== 'string') {
-                    throw new WorkflowLoadError(`${p}.context_files[${j}].hint 必须是 string`, file);
-                }
-            }
-            if (typeof s.type === 'string' && CONTROL_FLOW_TYPES.has(s.type)) {
-                throw new WorkflowLoadError(`${p}.context_files 不能用在 type=${s.type} 控制流节点上`, file);
-            }
-            // P3：context_files 同样是 skill 节点的静默 no-op（execSkillStep 无视它），
-            // 仅 llm 节点经 runQuery 生效——loader 直接拒绝，避免悄悄丢弃。
-            if (s.skill !== undefined) {
-                throw new WorkflowLoadError(`${p}.context_files 暂不支持 skill 节点（仅 llm 节点生效）`, file);
-            }
-        }
-        // allowed_tools：string[]；不能用在控制流节点上
-        if (s.allowed_tools !== undefined) {
-            if (!Array.isArray(s.allowed_tools) ||
-                !s.allowed_tools.every((x) => typeof x === 'string' && x.length > 0)) {
-                throw new WorkflowLoadError(`${p}.allowed_tools 必须是非空 string 数组`, file);
-            }
-            if (typeof s.type === 'string' && CONTROL_FLOW_TYPES.has(s.type)) {
-                throw new WorkflowLoadError(`${p}.allowed_tools 不能用在 type=${s.type} 控制流节点上`, file);
-            }
-            // P3：allowed_tools 与 context_files 配对，skill 节点上同样无效——一并拒绝。
-            if (s.skill !== undefined) {
-                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);
-            }
-        }
-    }
-}