minimal-agent 0.13.0 → 0.14.0

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

@@ -1,721 +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';
-import type { StepDef, WorkflowDef } from './types.js';
-
-export class WorkflowLoadError extends Error {
-  constructor(message: string, public readonly file?: string) {
-    super(message);
-    this.name = 'WorkflowLoadError';
-  }
-}
-
-/**
- * 扫描双源目录，返回所有 *.yaml / *.yml 解析后的 workflow。
- * 永远不抛；坏文件 console.warn 并跳过。
- */
-export async function listWorkflows(workingDir?: string): Promise<WorkflowDef[]> {
-  const out: WorkflowDef[] = [];
-  const seen = new Set<string>();
-  const roots = getResourceSearchPaths('workflows', import.meta.url, workingDir);
-
-  for (const root of roots) {
-    let entries: string[];
-    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 as Error).message}`);
-      }
-    }
-  }
-  return out;
-}
-
-/** 按 name 查找。找不到返回 null —— 调用方决定如何提示用户。 */
-export async function findWorkflowByName(
-  name: string,
-  workingDir?: string,
-): Promise<WorkflowDef | null> {
-  const all = await listWorkflows(workingDir);
-  const normalized = normalizeWorkflowLookupName(name);
-  return all.find((w) => w.name === normalized || workflowFileBaseName(w) === normalized) ?? null;
-}
-
-function stripYamlExt(name: string): string {
-  return name.replace(/\.ya?ml$/i, '');
-}
-
-function normalizeWorkflowLookupName(name: string): string {
-  return stripYamlExt(basename(name));
-}
-
-function workflowFileBaseName(workflow: WorkflowDef): string | null {
-  if (!workflow.__source) return null;
-  return stripYamlExt(basename(workflow.__source));
-}
-
-/** 读单个 yaml 文件 → 解析 → 校验。失败抛 WorkflowLoadError。 */
-export async function parseWorkflowFile(file: string): Promise<WorkflowDef> {
-  let raw: string;
-  try {
-    raw = await readFile(file, 'utf8');
-  } catch (e) {
-    throw new WorkflowLoadError(`无法读取 ${file}: ${(e as Error).message}`, file);
-  }
-  let data: unknown;
-  try {
-    data = parseYamlLib(raw);
-  } catch (e) {
-    throw new WorkflowLoadError(`yaml 语法错误: ${(e as Error).message}`, file);
-  }
-  if (!data || typeof data !== 'object') {
-    throw new WorkflowLoadError('yaml 根节点必须是对象', file);
-  }
-  validate(data as Record<string, unknown>, file);
-  const def = data as WorkflowDef;
-  def.__source = file;
-  return def;
-}
-
-// ---------------- 手写最小校验 ----------------
-
-function validate(obj: Record<string, unknown>, file: string): void {
-  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 as unknown[], file, '');
-
-  // self_heal 校验（可选）
-  if (obj.self_heal !== undefined) {
-      const sh = obj.self_heal as Record<string, unknown>;
-      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 as unknown[]).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 as unknown[]).entries()) {
-      if (!item || typeof item !== 'object') {
-        throw new WorkflowLoadError(`inputs[${i}] 必须是对象`, file);
-      }
-      const r = item as Record<string, unknown>;
-      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'] as const;
-
-// onError 合法值（单一来源：onError 校验 + editor schema 同步测试）。
-export const ON_ERROR_VALUES = ['halt', 'continue', 'recover'] as const;
-
-function isValidMaxIterations(value: unknown): boolean {
-  return (
-    (typeof value === 'number' && Number.isInteger(value) && value > 0) ||
-    (typeof value === 'string' && (value.includes('${') || /^\d+$/.test(value.trim())))
-  );
-}
-
-function isValidImageDetail(value: unknown): boolean {
-  return value === 'low' || value === 'default' || value === 'high';
-}
-
-function assertLlmOrAgentMultimodalField(
-  s: Record<string, unknown>,
-  key: string,
-  p: string,
-  file: string,
-): void {
-  if (s.llm === undefined && s.agent === undefined) {
-    throw new WorkflowLoadError(`${p}.${key} 仅支持 llm / agent 节点`, file);
-  }
-}
-
-function assertHistoryModeField(
-  s: Record<string, unknown>,
-  p: string,
-  file: string,
-): void {
-  if (s.llm === undefined && s.agent === undefined && s.skill === undefined) {
-    throw new WorkflowLoadError(
-      `${p}.history_mode 只能用在 llm / agent / skill 节点上`,
-      file,
-    );
-  }
-}
-
-function requireNonEmptyString(
-  s: Record<string, unknown>,
-  key: string,
-  p: string,
-  file: string,
-  typeName: string,
-): void {
-  if (typeof s[key] !== 'string' || String(s[key]).length === 0) {
-    throw new WorkflowLoadError(`${p} type=${typeName} requires non-empty '${key}'`, file);
-  }
-}
-
-function validateSteps(steps: unknown[], file: string, pathPrefix: string): void {
-  const seenIds = new Set<string>();
-  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 as Record<string, unknown>;
-    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'] as (keyof StepDef)[];
-    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 as (typeof ON_ERROR_VALUES)[number])
-    ) {
-      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 as string)) {
-          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 as unknown[]).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 as Record<string, unknown>;
-        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 as unknown[], 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 as Record<string, unknown>).length === 0
-      ) {
-        throw new WorkflowLoadError(
-          `${p} type=set 必须带非空对象 'set'（{ 变量名: 值 }，值支持 \${} 插值）`,
-          file,
-        );
-      }
-    }
-    if (s.type === 'verify') {
-      // 兼容两种格式：YAML 数组 或逗号分隔字符串
-      const rawChecks: unknown[] = 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 as unknown[], file, `${p}.then`);
-      if (Array.isArray(s.else)) validateSteps(s.else as unknown[], 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 as unknown[]).entries()) {
-        if (!cf || typeof cf !== 'object' || Array.isArray(cf)) {
-          throw new WorkflowLoadError(
-            `${p}.context_files[${j}] 必须是 { path: string, hint?: string } 对象`,
-            file,
-          );
-        }
-        const r = cf as Record<string, unknown>;
-        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 as unknown[]).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 as unknown[]).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,
-            );
-        }
-    }
-  }
-}