@zhushanwen/subagent-core 0.2.0

package/src/orchestration/script-lint.ts

@@ -0,0 +1,766 @@
+/**
+ * Workflow Extension — 静态 lint
+ *
+ * 在执行前捕获常见的 workflow 脚本 API 误用。纯函数，零副作用，零 IO。
+ *
+ * 设计：
+ * - lint 是编排层关注（非技术资源），归属 Engine 层。
+ * - **entry-point 检查**：脚本必须含 agent/parallel/pipeline 之一，否则视为 error。
+ * WorkflowScript.validate 直接委托 lintScript，故 entry-point 检查必须在此。
+ * - LintFinding/LintResult 类型规范的 canonical 源在本文件。
+ *
+ * 检查项：
+ * 1. 必须含 agent/parallel/pipeline 入口（error）
+ * 2. agent 选项中 outputSchema 当 key 用 → 应为 schema（error）
+ * 3. result.output / result.parsedOutput / result.content → agent 返回未包装值（error）
+ * 4. readFileSync/writeFileSync 传状态 → 脆弱（warning）
+ * 5. unlinkSync 清理状态 → 与 subprocess 文件读竞态（warning）
+ * 6. 顶层未 await 的异步 IIFE + 内部调 agent/parallel/pipeline → 子进程被提前 kill（error）
+ * 7. agent() 缺 description/label → TUI /workflows 显示 '(unnamed)'（warning）
+ * 8. meta.phases 非字符串数组（对象数组等）→ 引擎忽略（warning）
+ * 9. meta.phases 声明与 phase() 调用不一致 → 运行时分组与声明脱节（warning）
+ *
+ * 层归属：Engine。
+ *
+ * 参考：domain-models.md §7（validate 语义）。
+ */
+
+/** m4 W2：meta 描述字段长度上限（§5.1 注入段预算约束）。 */
+const DESC_MAX_LENGTH = 200;
+/** m4 W4：agent examples 最少条数（正反各一需 ≥2）。 */
+const EXAMPLES_MIN_COUNT = 2;
+/** m5：examples 上限（注入是每 turn 常驻成本——防数据无界膨胀）。 */
+const EXAMPLES_MAX_COUNT = 4;
+
+/** Lint 检查发现项。 */
+export interface LintFinding {
+ /** error = 会导致运行时崩溃; warning = 可能的错误 */
+  severity: "error" | "warning";
+  line: number;
+  message: string;
+  suggestion: string;
+}
+
+/** Lint 检查结果。 */
+export interface LintResult {
+  valid: boolean;
+  findings: LintFinding[];
+}
+
+/** 必须命中其一——workflow 脚本不调用任何编排函数等于空跑。 */
+import type { AgentMeta } from "../shared/resource-meta.ts";
+import { parseResourceMeta } from "../shared/meta-parser.ts";
+
+const ENTRY_POINT_PATTERNS = [/\bagent\s*\(/, /\bparallel\s*\(/, /\bpipeline\s*\(/] as const;
+
+/**
+ * 检查脚本是否含至少一个编排入口（agent/parallel/pipeline）。
+ * 无入口视为 error——空跑脚本无意义。
+ */
+function checkEntryPoint(source: string): LintFinding[] {
+  const hasEntryPoint = ENTRY_POINT_PATTERNS.some((p) => p.test(source));
+  if (hasEntryPoint) return [];
+  return [
+    {
+      severity: "error",
+      line: 0,
+      message: "Workflow script must call agent(), parallel(), or pipeline() at least once.",
+      suggestion: "Add at least one agent(), parallel(), or pipeline() invocation.",
+    },
+  ];
+}
+
+/**
+ * 检查单行 lint 问题，返回该行的发现项（可能为空）。
+ */
+function checkLine(lineText: string, lineNum: number): LintFinding[] {
+  const results: LintFinding[] = [];
+
+ // 跳过注释行
+  const trimmed = lineText.trim();
+  if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*")) {
+    return results;
+  }
+
+ // result.output / result.parsedOutput / result.content
+  const resultAccessPatterns: Array<{ regex: RegExp; field: string }> = [
+    { regex: /\bresult\s*\.\s*output\b/, field: "output" },
+    { regex: /\bresult\s*\.\s*parsedOutput\b/, field: "parsedOutput" },
+    { regex: /\bresult\s*\.\s*content\b/, field: "content" },
+  ];
+  for (const p of resultAccessPatterns) {
+    if (p.regex.test(lineText)) {
+      results.push({
+        severity: "error",
+        line: lineNum,
+        message: `\`result.${p.field}\` does not exist. agent() returns the unwrapped value directly.`,
+        suggestion: "Use `const value = await agent(...)` and access `value` directly.",
+      });
+    }
+  }
+
+ // 文件传状态（readFileSync of STATE）
+  if (/readFileSync\(.*STATE.*\)|readFileSync\(.*state.*\.json/i.test(lineText)) {
+    results.push({
+      severity: "warning",
+      line: lineNum,
+      message: "Reading a state file between agent calls is fragile (subprocess file access).",
+      suggestion: "Use agent() with `schema` to get structured output directly, avoiding file I/O for state passing.",
+    });
+  }
+
+ // unlinkSync 清理状态
+  if (/unlinkSync.*state/i.test(lineText)) {
+    results.push({
+      severity: "warning",
+      line: lineNum,
+      message: "unlinkSync in finally may race with agent subprocess file reads.",
+      suggestion: "Avoid file-based state passing; use agent() `schema` for structured output.",
+    });
+  }
+
+  return results;
+}
+
+/**
+ * 剔除字符串字面量与注释内容（MF-4）。逐行处理，不跨行。
+ * 用途：`\bagent\s*\(` 不命中字符串里的 "agent(s)"（review-fix-loop L281 误报根因）；
+ * checkAgentDescription 的 `description\s*:` 不把 schema 内嵌 description 字符串当已提供。
+ */
+function stripStringsAndComments(line: string): string {
+  return line
+    .replace(/"(?:\\.|[^"\\])*"/g, "")
+    .replace(/'(?:\\.|[^'\\])*'/g, "")
+    .replace(/`(?:\\.|[^`\\])*`/g, "")
+    .replace(/\/\/.*$/, "")
+    .replace(/\/\*[\s\S]*?\*\//g, "");
+}
+
+/**
+ * 遍历 source 中所有 agent 调用的行范围，对每个调用执行 callback。
+ *
+ * agent 调用可能跨多行，通过括号配对定位起止行：
+ *   agent({
+ *     prompt: ...,
+ *   })
+ *
+ * 单行 agent 调用（如 `agent({ prompt: 'x' })`）的 startLine === endLine。
+ * 与 checkAgentCalls / checkAgentDescription 共享同一套范围定义，确保
+ * outputSchema 检查与 description 检查覆盖完全相同的调用集合（含 parallel/pipeline
+ * 内嵌的 agent() 调用——它们同样被 `\bagent\s*\(` 匹配）。
+ *
+ * 匹配前逐行剔除字符串/注释内容（MF-4）：字符串字面量里的 "agent(s)" 不再误触发。
+ * 非字面量实参（agent(callVar) / agent(expr)）跳过不回调：description 等选项在调用点
+ * 静态不可见，checkAgentDescription 无法验证运行时构造的调用——继续报 warning 即误报
+ * （review-fix-loop 的 agent(call) 三连误报根因）。
+ *
+ * @param callback (startLine, endLine) 0-based 行号
+ */
+function forEachAgentCallRange(
+  source: string,
+  callback: (startLine: number, endLine: number) => void,
+): void {
+  const lines = source.split("\n");
+  let inAgentCall = false;
+  let depth = 0;
+  let agentStartLine = -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+ // 跳过注释
+    if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*")) {
+      continue;
+    }
+
+    // 匹配/计括号都用剔除字符串与注释后的行，避免字面量内容干扰
+    const codeLine = stripStringsAndComments(line);
+
+ // 检测 agent 调用开始
+    if (!inAgentCall && /\bagent\s*\(/.test(codeLine)) {
+      inAgentCall = true;
+      depth = 0;
+      agentStartLine = i;
+ // 从 agent( 开始计括号
+      const afterAgent = codeLine.replace(/^.*?\bagent\s*\(/, "(");
+      // 非字面量实参（agent(callVar) / agent(expr)）→ 跳过（见函数头注释）。
+      // 形如 `agent(` 换行 `{` 的多行字面量调用（argTail 为空）保留原追踪行为。
+      const argTail = afterAgent.trimStart().slice(1).trimStart();
+      if (argTail.length > 0 && !argTail.startsWith("{")) {
+        inAgentCall = false;
+        continue;
+      }
+      for (const ch of afterAgent) {
+        if (ch === "(" || ch === "{" || ch === "[") depth++;
+        if (ch === ")" || ch === "}" || ch === "]") depth--;
+      }
+      if (depth <= 0) {
+ // 单行 agent 调用
+        callback(agentStartLine, i);
+        inAgentCall = false;
+      }
+      continue;
+    }
+
+    if (inAgentCall) {
+      for (const ch of codeLine) {
+        if (ch === "(" || ch === "{" || ch === "[") depth++;
+        if (ch === ")" || ch === "}" || ch === "]") depth--;
+      }
+      if (depth <= 0) {
+        callback(agentStartLine, i);
+        inAgentCall = false;
+      }
+    }
+  }
+}
+
+/**
+ * 找出 source 中所有 agent 调用跨度，检查错误的选项 key（outputSchema）。
+ * 范围遍历委托 forEachAgentCallRange。
+ */
+function checkAgentCalls(source: string): LintFinding[] {
+  const lines = source.split("\n");
+  const findings: LintFinding[] = [];
+  forEachAgentCallRange(source, (startLine, endLine) => {
+    checkAgentCallOptions(lines, startLine, endLine, findings);
+  });
+  return findings;
+}
+
+/**
+ * 检查 agent 调用内的错误选项 key。
+ * 只标记 outputSchema 作为 KEY（属性名）使用的情况，不标记作为 VALUE。
+ *
+ * Error: { outputSchema } ← 简写属性（outputSchema 是 key）
+ * Error: { outputSchema: ... } ← 显式 key
+ * OK: { schema: outputSchema } ← outputSchema 是 value，`schema` 是 key
+ * OK: const outputSchema = {} ← 变量声明（在 agent 调用外）
+ */
+function checkAgentCallOptions(
+  lines: string[],
+  startLine: number,
+  endLine: number,
+  findings: LintFinding[],
+): void {
+  for (let i = startLine; i <= endLine; i++) {
+    const line = lines[i];
+
+ // 跳过变量声明（const/let/var outputSchema = ...）
+    if (/\b(?:const|let|var)\s+outputSchema\b/.test(line)) {
+      continue;
+    }
+
+ // 匹配：outputSchema 作为对象 key（简写或显式）
+    if (/\boutputSchema\s*[,\}]/.test(line) || /\boutputSchema\s*:/.test(line)) {
+ // 排除：outputSchema 作为 value（在另一个 key 的冒号后）
+ // e.g. "schema: outputSchema," — outputSchema 前是冒号
+      const beforeOutput = line.substring(0, line.indexOf("outputSchema"));
+      if (/:\s*$/.test(beforeOutput)) {
+        continue; // outputSchema 是 value，不是 key
+      }
+
+      findings.push({
+        severity: "error",
+        line: i + 1,
+        message: "`outputSchema` is not a valid agent() option.",
+        suggestion: "Use `schema` instead of `outputSchema`.",
+      });
+    }
+  }
+}
+
+/**
+ * 剔除 agent 选项对象里的 schema 块（`schema: {...}` 嵌套对象，括号配对）。
+ * 用于 checkAgentDescription：JSON Schema 的 properties 里常见 `description:` 字段
+ * （schema 文档字段，不是 agent 选项）——只剔字符串字面量时该 key 仍保留，会把
+ * 内嵌 description 误判为「已提供」导致漏报（I-10 修正的剩余部分）。
+ * 输入为已剔除字符串/注释的 range（无引号内容干扰，括号配对安全）。
+ */
+function stripSchemaBlocks(text: string): string {
+  let out = "";
+  let i = 0;
+  while (i < text.length) {
+    const m = text.slice(i).match(/\bschema\s*:\s*\{/);
+    if (!m || m.index === undefined) {
+      out += text.slice(i);
+      break;
+    }
+    const start = i + m.index;
+    const braceIdx = start + m[0].lastIndexOf("{");
+    out += text.slice(i, start);
+    let depth = 0;
+    let j = braceIdx;
+    for (; j < text.length; j++) {
+      if (text[j] === "{") depth++;
+      else if (text[j] === "}") {
+        depth--;
+        if (depth === 0) {
+          j++;
+          break;
+        }
+      }
+    }
+    i = j;
+  }
+  return out;
+}
+
+/**
+ * 检查 agent 调用是否提供 description（或其别名 label）。
+ *
+ * worker-script-builder 取 `firstArg.label || firstArg.description` 作 TUI 显示名，
+ * 两者都缺 → node.agent 为空 → /workflows 视图显示 '(unnamed)'。
+ *
+ * 实现复用 forEachAgentCallRange 的范围定义，在范围内检测 `description:` 或 `label:`
+ * 作为对象 key。两层剔除保证只认 agent 选项层的真正 key：① 字符串字面量（
+ * stripStringsAndComments，MF-4）；② schema 块（stripSchemaBlocks——schema 内嵌的
+ * `description:` 是 JSON Schema 字段说明不是 agent 选项，不剔除会漏报）。
+ */
+function checkAgentDescription(source: string): LintFinding[] {
+  const lines = source.split("\n");
+  const findings: LintFinding[] = [];
+  forEachAgentCallRange(source, (startLine, endLine) => {
+    // range 逐行剔除字符串字面量（MF-4）后再剔除 schema 块：schema 内嵌的
+    // `description:` 对象 key（JSON Schema 字段说明）不再被误判为「已提供」——
+    // 只有 agent 选项层的真正 description/label key 才算数（修正 I-10 漏报方向）。
+    const range = stripSchemaBlocks(lines.slice(startLine, endLine + 1).map(stripStringsAndComments).join("\n"));
+    // 对象以展开开头（agent({ ...call, ... })）：description 来自运行时对象、调用点静态
+    // 不可见——无法验证即不报（review-fix-loop 的 agent({ ...call, agent: ... }) 即此形态）。
+    if (/\{\s*\.\.\./.test(range)) return;
+ // 匹配 description 或 label 作为对象 key（后跟冒号）
+    if (!/\b(description|label)\s*:/.test(range)) {
+      findings.push({
+        severity: "warning",
+        line: startLine + 1,
+        message:
+          "agent() call without `description` (or `label`) will show as '(unnamed)' in TUI.",
+        suggestion:
+          "Add `description: 'kebab-case-name'` to agent() opts for readable /workflows display.",
+      });
+    }
+  });
+  return findings;
+}
+
+// ── 顶层未 await 的异步 IIFE 检测 ───────────────────────────
+
+/**
+ * 匹配未 await 的 async IIFE 起点（粗筛）。
+ *
+ * 形式：`(async function`、`(async ()`、`(async (args)` 后跟 `=>`
+ * 不匹配：`await (async ...`（lookbehind 排除）
+ */
+const BARE_ASYNC_IIFE_PATTERN = /(^|[;\n\s{}(])(?<!await\s)\(async\s+(?:function\b|\(\)|\([^)]*\)\s*=>)/g;
+
+/**
+ * 判断 IIFE 调用表达式是否被某个上下文「接住」（return/赋值/await 链等）。
+ *
+ * 返回 true 表示 IIFE 的 Promise 被接住（合法或可能合法）；
+ * false 表示 IIFE 是孤立语句表达式（fire-and-forget）。
+ *
+ * 判断方法：扫描 IIFE 起点 `(async` 前的非空白 token：
+ *   - 遇到 `=` `return` `await` `(` `[` `,` → 接住
+ *   - 遇到 `;` `{` `}` 或行首 → 孤立语句
+ *
+ * 例：
+ *   `const x = (async ...` → '=' 接住
+ *   `return (async ...` → 'return' 接住
+ *   `(async ...` 行首 → 孤立
+ *   `}; (async ...` → 孤立（前一个语句结束后新起一个）
+ */
+function isIIFEAwaited(source: string, iifeStart: number): boolean {
+  let i = iifeStart - 1;
+  while (i >= 0) {
+    const ch = source[i];
+    if (/\s/.test(ch)) {
+      i--;
+      continue;
+    }
+    // 当前字符是标识符字符 → 向前扫完整标识符
+    if (/[A-Za-z0-9_$]/.test(ch)) {
+      // return / await / yield / 变量名（如 `foo(async ...`）→ 接住
+      return true;
+    }
+    // 单字符操作符
+    if (ch === "=" || ch === "(" || ch === "[" || ch === "," || ch === "?" || ch === ":") {
+      return true;
+    }
+    if (ch === ";" || ch === "{" || ch === "}" || ch === ")") {
+      return false;
+    }
+    // 其他字符（如 `.` `+`），保守视为接住（避免误报）
+    return true;
+  }
+  return false;
+}
+
+/**
+ * 检测未 await 的 async IIFE，且其内部调用了 agent/parallel/pipeline。
+ *
+ * 严重度分级：
+ * - **error**：IIFE 是孤立语句表达式（fire-and-forget）+ 内部调 agent。
+ *   这是 daily-news-impact 的 bug 模式——worker 外层 IIFE 不等内层就 post return，
+ *   主线程 transition done → releaseRuntime → controller.abort() → SIGKILL 子进程。
+ * - **warning**：IIFE 被 `=`/`return`/`(` 等接住（可能后续 await），但内部调 agent。
+ *   提醒作者确认 Promise 真的被 await，不阻断运行。
+ *
+ * 误报规避（不报）：
+ * - await 前缀的 IIFE（lookbehind 排除）
+ * - IIFE 内不含 agent/parallel/pipeline（stock-screening 这类纯 execSync 合法）
+ *
+ * 局限：纯正则 + 括号配对，无法做数据流分析。「赋值后稍后 await」「return 给外层 await」
+ * 都识别为「接住」（warning 而非 error），避免阻断合法写法。
+ */
+function checkBareAsyncIIFE(source: string): LintFinding[] {
+  if (!ENTRY_POINT_PATTERNS.some((p) => p.test(source))) return [];
+
+ // 用 matchAll 检查所有 IIFE（脚本可能有多个，每个都需独立判断）
+  const findings: LintFinding[] = [];
+  for (const match of source.matchAll(BARE_ASYNC_IIFE_PATTERN)) {
+    const iifeStart = match.index ?? 0;
+    const finding = analyzeIIFE(source, iifeStart);
+    if (finding) findings.push(finding);
+  }
+  return findings;
+}
+
+/**
+ * 分析单个 IIFE 起点是否触发 finding。
+ *
+ * 返回 LintFinding（error 或 warning）或 undefined（IIFE 内无 agent/无闭合）。
+ * 详见 checkBareAsyncIIFE 的 [HISTORICAL] 教训记录。
+ */
+function analyzeIIFE(source: string, iifeStart: number): LintFinding | undefined {
+  const iifeLine = source.slice(0, iifeStart).split("\n").length;
+
+  const firstBrace = source.indexOf("{", iifeStart);
+  if (firstBrace === -1) return undefined;
+
+  let depth = 0;
+  let iifeEnd = -1;
+  for (let i = firstBrace; i < source.length; i++) {
+    const ch = source[i];
+    if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) {
+        iifeEnd = i;
+        break;
+      }
+    }
+  }
+  if (iifeEnd === -1) return undefined;
+
+  const iifeBody = source.slice(firstBrace, iifeEnd);
+  const hasAgentInside = ENTRY_POINT_PATTERNS.some((p) => p.test(iifeBody));
+  if (!hasAgentInside) return undefined;
+
+  const awaited = isIIFEAwaited(source, iifeStart);
+  if (awaited) {
+    return {
+      severity: "warning",
+      line: iifeLine,
+      message:
+        "Async IIFE wrapping agent() is assigned/returned but must be awaited. If the surrounding context does not await this Promise, the worker will post `return` early and kill in-flight agent() subprocesses.",
+      suggestion:
+        "Verify the surrounding code awaits this IIFE's Promise. When unsure, prefer top-level await directly (the worker already wraps your script in an async IIFE).",
+    };
+  }
+
+  return {
+    severity: "error",
+    line: iifeLine,
+    message:
+      "Top-level async IIFE is a fire-and-forget statement. The worker's outer IIFE will post `return` before agent() resolves, killing the subprocess via runtime abort.",
+    suggestion:
+      "Remove the IIFE wrapper and use top-level await directly (the worker already wraps your script in an async IIFE). Or `await` the IIFE: `await (async function main() { ... })();`.",
+  };
+}
+
+// ── 显示性检查（description / phase）───────────────────────────
+
+/**
+ * 检查 meta.phases 是否字符串数组。
+ *
+ * 引擎 buildPhaseGroups 只按运行时 node.phase 分组，不读 meta.phases 声明。但 meta.phases
+ * 仍用于文档/一致性检查（见 checkPhaseConsistency），且 SSOT 约定为字符串数组。对象数组
+ * （如 [{title,detail}]）是常见误写，提醒作者改为字符串数组。
+ */
+function checkMetaPhases(source: string): LintFinding[] {
+  const findings: LintFinding[] = [];
+  // 跨行匹配（\s* 含换行）：`phases: [` 与 `{` 换行分离的多行对象数组同样命中。
+  // 原逐行匹配只命中「`[` 与 `{` 同行」，最常见的格式化写法（phases: [ 换行 { ... }）零检出（MF-5）。
+  // 行号从 match index 反推。字符串数组（phases: [\n "a"）不匹配 \s*\{，不会误报。
+  for (const m of source.matchAll(/phases\s*:\s*\[\s*\{/g)) {
+    if (m.index === undefined) continue;
+    const lineNum = source.slice(0, m.index).split("\n").length;
+    findings.push({
+      severity: "warning",
+      line: lineNum,
+      message:
+        "`meta.phases` should be a string array like ['phase1','phase2']. Object arrays are ignored by the engine.",
+      suggestion:
+        "Use `phases: ['analyze','fix']`. Engine groups nodes by runtime `phase()` calls, not by `meta.phases` declarations.",
+    });
+  }
+  return findings;
+}
+
+/**
+ * 检查 meta.phases 声明与 phase() 调用的一致性。
+ *
+ * - 声明了但从未 phase() 调用 → warning（运行时分组用不上，声明形同虚设）
+ * - phase() 调用了但未声明 → warning（声明遗漏，meta.phases 失去文档价值）
+ *
+ * 两者都为空时跳过（脚本不使用 phase 机制，不报）。
+ */
+function checkPhaseConsistency(source: string): LintFinding[] {
+  const findings: LintFinding[] = [];
+
+ // 提取 meta.phases 声明的字符串 + 声明所在行号
+  const declared = new Map<string, number>();
+  const phasesArrayMatch = source.match(/phases\s*:\s*\[[^\]]*\]/);
+  if (phasesArrayMatch && phasesArrayMatch.index !== undefined) {
+    const inner = phasesArrayMatch[0];
+ // 对象数组（如 [{title,detail}]）由 checkMetaPhases 单独报，这里跳过提取，
+ // 避免从对象字段里误抽出字符串作 declared。
+    if (!/\[\s*\{/.test(inner)) {
+      const phasesLine = source.slice(0, phasesArrayMatch.index).split("\n").length;
+      for (const m of inner.matchAll(/['"]([^'"]+)['"]/g)) {
+        if (!declared.has(m[1])) declared.set(m[1], phasesLine);
+      }
+    }
+  }
+
+ // 提取所有 phase() 调用实参 + 首次出现的行号
+  const called = new Map<string, number>();
+  for (const m of source.matchAll(/\bphase\s*\(\s*['"]([^'"]+)['"]/g)) {
+    if (m.index === undefined) continue;
+    const lineNum = source.slice(0, m.index).split("\n").length;
+    if (!called.has(m[1])) called.set(m[1], lineNum);
+  }
+
+ // 两者都为空 → 跳过（脚本不使用 phase 机制）
+  if (declared.size === 0 && called.size === 0) return [];
+
+ // 声明了但从未 phase() 调用
+  for (const [name, line] of declared) {
+    if (!called.has(name)) {
+      findings.push({
+        severity: "warning",
+        line,
+        message: `declared phase '${name}' never set via phase().`,
+        suggestion: `Add phase('${name}') before the agent() calls belonging to this phase, or remove it from meta.phases.`,
+      });
+    }
+  }
+
+ // 调用了但未声明
+  for (const [name, line] of called) {
+    if (!declared.has(name)) {
+      findings.push({
+        severity: "warning",
+        line,
+        message: `phase('${name}') called but not in meta.phases.`,
+        suggestion: `Add '${name}' to meta.phases array, e.g. phases: [..., '${name}'].`,
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * 静态检查 workflow 脚本合法性。
+ *
+ * @param source 脚本源码（原始文件内容）
+ * @returns LintResult（valid = 无 error 级 finding）
+ */
+/**
+ * W2/W3 共享 helper：meta 描述字段长度上限 + 单句判定（workflow lintScript 与
+ * agent lintAgentMeta 共用同一规则——S-5 对称，避免 agent 长 description 常驻膨胀）。
+ *
+ * W2：>200 字符 → error。
+ * W3：括号内容剥离（（…）/（…）与 (...)）后含换行/。；/'. ' 分句 → error。
+ * 输出格式与 severity 约定与 checkMetaQuality 一致（error / line 1 / meta.<field> 前缀）。
+ */
+function checkMetaFieldQuality(field: string, value: string): LintFinding[] {
+  const findings: LintFinding[] = [];
+  // W2
+  if (value.length > DESC_MAX_LENGTH) {
+    findings.push({
+      severity: "error",
+      line: 1,
+      message: `meta.${field} 长度 ${value.length} 超过 ${DESC_MAX_LENGTH} 字符（§5.1 注入段预算约束）`,
+      suggestion: "精简为单句路由描述，细节移入 usage",
+    });
+  }
+  // W3：括号剥离后分句判定
+  const stripped = value
+    .replace(/（[^）]*）/g, "")
+    .replace(/\([^)]*\)/g, "")
+    .replace(/\b(?:e\.g|i\.e)\.\s/g, ""); // 缩写剔除（exec-review F8：括号外 e.g. 不误报）
+  if (/[\n。；]|\.\s/.test(stripped)) {
+    findings.push({
+      severity: "error",
+      line: 1,
+      message: `meta.${field} 非单句（含换行/分句标点）——§5.1 注入段要求一句话路由描述`,
+      suggestion: "精简为单句，细节移入 when/notFor/usage",
+    });
+  }
+  return findings;
+}
+
+/**
+ * W1-W3：SSOT lint（m4）——保 §5.1 注入段 description 短单句、不含已声明参数名。
+ * 仅对 parseResourceMeta 解析成功的 meta 执行（旧 const meta 格式不检查）。
+ *
+ * W1 参数名匹配（非形态匹配）：'note:'/'Example:'/'a=b' 等 prose 不误报（design-review
+ * 探针实测形态匹配误报面）；参数名集合 = meta.parameters.properties keys + patternProperties
+ * 的 word 前缀（^word\\d+$ 转义形态）。检查面 = description + when + notFor 三字段
+ * （同进 §5.1 注入段）。W2/W3 抽到 checkMetaFieldQuality（lintAgentMeta 共用）。
+ */
+function checkMetaQuality(meta: { description?: string; when?: string; notFor?: string; parameters?: Record<string, unknown> }): LintFinding[] {
+  const findings: LintFinding[] = [];
+  const description = meta.description ?? "";
+
+  // W1 参数名集合
+  const paramNames = new Set<string>();
+  if (meta.parameters && typeof meta.parameters === "object") {
+    const props = (meta.parameters as Record<string, unknown>).properties;
+    if (props !== null && typeof props === "object") {
+      for (const k of Object.keys(props as Record<string, unknown>)) paramNames.add(k);
+    }
+    const pp = (meta.parameters as Record<string, unknown>).patternProperties;
+    if (pp !== null && typeof pp === "object") {
+      for (const p of Object.keys(pp as Record<string, unknown>)) {
+        const m = p.match(/^\^([a-zA-Z]+)\\d\+\$$/);
+        if (m) paramNames.add(m[1] as string);
+      }
+    }
+  }
+
+  const fields: Array<[string, string]> = [
+    ["description", description],
+    ["when", meta.when ?? ""],
+    ["notFor", meta.notFor ?? ""],
+  ];
+  for (const [field, value] of fields) {
+    if (value.length === 0) continue;
+    // W1：已声明参数名的 ':'/'=' 形态（参数名转义防 RegExp 注入崩溃——exec-review F2；
+    // ':' 形态加 \\b 前缀防子串误报（subtask: 不命中 task——exec-review F6））
+    for (const name of paramNames) {
+      const nameEsc = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      if (new RegExp(`\\b${nameEsc}:\\s`).test(value) || new RegExp(`\\b${nameEsc}=\\S`).test(value)) {
+        findings.push({
+          severity: "error",
+          line: 1,
+          message: `meta.${field} 包含已声明参数名 '${name}'（'${name}:' / '${name}=' 形态）——参数契约请 read 脚本文件的 @pi-meta parameters 查询，description/when/notFor 只放路由信息`,
+          suggestion: `从 meta.${field} 移除 '${name}: ...' / '${name}=...'，改在 parameters/usage 中声明`,
+        });
+      }
+    }
+    findings.push(...checkMetaFieldQuality(field, value));
+  }
+  return findings;
+}
+
+/**
+ * W2/W3 + W4（m4/m5 挂 agent 加载路径）：description/when/notFor 长度与单句检查
+ * （与 workflow 同规则，S-5 对称）+ examples 正反各一。
+ * RoutingExample.positive 判别（action 是 string 非 null）；examples 缺失 → 无 finding
+ * （未迁移 agent 不报错——m5 挂载安全根基）。
+ */
+export function lintAgentMeta(meta: AgentMeta): LintFinding[] {
+  // W2/W3（S-5 对称）：agent 的 description/when/notFor 与 workflow 同规则
+  // （长度上限 + 单句判定）——formatAgentList 原样注入 systemPrompt，长描述是每 turn 常驻成本。
+  const findings: LintFinding[] = [];
+  const fields: Array<[string, string]> = [
+    ["description", meta.description],
+    ["when", meta.when ?? ""],
+    ["notFor", meta.notFor ?? ""],
+  ];
+  for (const [field, value] of fields) {
+    if (value.length === 0) continue;
+    findings.push(...checkMetaFieldQuality(field, value));
+  }
+
+  const examples = meta.examples;
+  if (examples === undefined) return findings; // 未迁移 agent（无 examples 字段）不报错
+  if (examples.length === 0) {
+    findings.push({
+      severity: "error",
+      line: 1,
+      message: `agent '${meta.name}' 声明了 examples 但为空——需 ≥2 条且正反各一`,
+      suggestion: "补正向样本（何时调用）+ 反向样本（何时不调用）",
+    });
+    return findings;
+  }
+  const hasPositive = examples.some((e) => e.positive === true);
+  const hasNegative = examples.some((e) => e.positive === false);
+  if (examples.length < EXAMPLES_MIN_COUNT || !hasPositive || !hasNegative) {
+    findings.push({
+      severity: "error",
+      line: 1,
+      message: `agent '${meta.name}' 的 examples 需 ≥2 条且正反各一（positive:true 触发路由 + positive:false 反例）`,
+      suggestion: "补正向样本（何时调用）+ 反向样本（何时不调用）",
+    });
+    return findings;
+  }
+  if (examples.length > EXAMPLES_MAX_COUNT) {
+    findings.push({
+      severity: "error",
+      line: 1,
+      message: `agent '${meta.name}' 的 examples ${examples.length} 条超过上限 ${EXAMPLES_MAX_COUNT}（注入段是每 turn 常驻成本）`,
+      suggestion: "精简到 2-4 条：正反各一 + 最多 2 条冗余",
+    });
+  }
+  return findings;
+}
+
+export function lintScript(source: string): LintResult {
+  const lines = source.split("\n");
+  const findings: LintFinding[] = [];
+
+ // 入口检查（必须有 agent/parallel/pipeline 之一）
+  findings.push(...checkEntryPoint(source));
+
+ // 逐行检查（result.output、文件传状态等）
+  for (let i = 0; i < lines.length; i++) {
+    findings.push(...checkLine(lines[i], i + 1));
+  }
+
+  // agent 调用上下文检查（outputSchema 作为 key）
+  findings.push(...checkAgentCalls(source));
+
+ // [HISTORICAL] 顶层未 await 的异步 IIFE + 内部调 agent——子进程被提前 kill。
+ // 教训来源：daily-news-impact.js 用 (async function main(){...})();() 包裹整个脚本，
+ // worker 外层 IIFE 不等内层 IIFE 就 postMessage("return")，主线程 transition done
+ // → release runtime → controller.abort() → spawn 后 2ms SIGKILL 子进程。
+ // 诊断耗时 4 轮：先后误判为 model 故障 / 工具缺失 / turn-signal abort / 并发门闩 gate 异常，
+ // 最终靠 worker-host → handleReturn → release → abort 的调用栈定位。
+  findings.push(...checkBareAsyncIIFE(source));
+
+ // m4 W1-W3：meta 质量（description/when/notFor 短单句 + 不含已声明参数名）。
+ // 仅对 IF1 解析成功的 @pi-meta 执行——旧 const meta 格式（D1 无 adapter）不检查。
+  const meta = parseResourceMeta(source, "workflow");
+  if (meta && meta.kind === "workflow") {
+    findings.push(...checkMetaQuality(meta));
+  }
+
+ // 显示性检查（warning）：agent 缺 description / meta.phases 形式 / phase 一致性。
+ // 目的：让 TUI /workflows 视图避免 unnamed agent 与 (unnamed) phase 分组。
+  findings.push(...checkAgentDescription(source));
+  findings.push(...checkMetaPhases(source));
+  findings.push(...checkPhaseConsistency(source));
+
+  // 按行号排序，稳定输出
+  findings.sort((a, b) => a.line - b.line);
+
+  return {
+    valid: !findings.some((f) => f.severity === "error"),
+    findings,
+  };
+}