@zhushanwen/pi-subagent-workflow 4.0.0 → 5.0.0-dev.0

package/src/orchestration/__tests__/script-lint.test.ts

@@ -345,3 +345,321 @@ describe("多种错误同时存在", () => {
     expect(lines).toEqual(sorted);
   });
 });
+
+// ── agent description / meta.phases / phase 一致性（新增 warning 检查）─
+
+describe("agent() 缺 description/label — warning", () => {
+  it("agent 无 description/label → 1 warning", () => {
+    const src = `await agent({ prompt: "x" });\n`;
+    const result = lintScript(src);
+
+    const descWarnings = warnings(result.findings).filter((w) =>
+      /description.*unnamed/i.test(w.message));
+    expect(descWarnings).toHaveLength(1);
+    expect(descWarnings[0].line).toBe(1);
+  });
+
+  it("agent 有 description → 0 此类 warning", () => {
+    const src = `await agent({ prompt: "x", description: "review-diff" });\n`;
+    const result = lintScript(src);
+
+    expect(warnings(result.findings).some((w) => /description.*unnamed/i.test(w.message)))
+      .toBe(false);
+  });
+
+  it("agent 有 label（description 别名）→ 0 此类 warning", () => {
+    const src = `await agent({ prompt: "x", label: "review-diff" });\n`;
+    const result = lintScript(src);
+
+    expect(warnings(result.findings).some((w) => /description.*unnamed/i.test(w.message)))
+      .toBe(false);
+  });
+});
+
+// ── MF-4 重构核心回归：字符串剔除 / 非字面量实参跳过 ──────────────
+//
+// review-fix-loop L281 误报根因：字符串字面量里的 "agent(s)" 被 `\bagent\s*\(` 命中，
+// 误开 agent 调用范围；三连误报根因：agent(callVar) 非字面量实参在调用点静态不可见。
+// forEachAgentCallRange 对两者都有专门分支（stripStringsAndComments / argTail 非 `{` 跳过），
+// 下面用例锁定这些新增逻辑（MF-3）。
+
+describe("MF-4 回归：字符串字面量里的 agent(...) 不误触发", () => {
+  it("`const s = \"agent(s)\";` 字符串不触发 description 检测（review-fix-loop L281 回归）", () => {
+    const src = [
+      `const s = "agent(s)";`,
+      `await agent({ prompt: "x", description: "d" });`,
+      ``,
+    ].join("\n");
+    const result = lintScript(src);
+
+    // 字符串不产生幻影调用范围：真实调用只有 1 个且有 description → 0 warning
+    expect(warnings(result.findings).filter((w) => /description.*unnamed/i.test(w.message)))
+      .toHaveLength(0);
+    // 也不产生 outputSchema 等连带误报
+    expect(errors(result.findings)).toHaveLength(0);
+  });
+
+  it("字符串字面量里含完整调用形态 agent({...}) 同样不误触发（剔除逻辑真正生效的用例）", () => {
+    // 若 stripStringsAndComments 失效，此串会被当成字面量调用（argTail 以 { 开头）
+    // 并因缺 description 报 warning——本用例即失败
+    const src = [
+      `const s = "agent({ prompt: 'x' })";`,
+      `await agent({ prompt: "x", description: "d" });`,
+      ``,
+    ].join("\n");
+    const result = lintScript(src);
+
+    expect(warnings(result.findings).filter((w) => /description.*unnamed/i.test(w.message)))
+      .toHaveLength(0);
+  });
+
+  it("模板串内 agent({...}) 完整调用形态不误触发（反引号剔除路径）", () => {
+    // MF-4 既有用例只覆盖双引号字面量；workflow 脚本 prompt 常用模板串（含 ${} 插值）。
+    // 若 `...` 反引号剔除失效，模板串里的 agent({...}) 会开幻影调用范围并误报缺 description
+    const src = [
+      "const prompt = `agent({ prompt: '${x}' })`;",
+      `await agent({ prompt: "x", description: "d" });`,
+      ``,
+    ].join("\n");
+    const result = lintScript(src);
+
+    expect(warnings(result.findings).filter((w) => /description.*unnamed/i.test(w.message)))
+      .toHaveLength(0);
+    expect(errors(result.findings)).toHaveLength(0);
+  });
+
+  it("块注释内 agent({...}) 完整调用形态不误触发（/* */ 剔除路径）", () => {
+    // 行首 /* 注释由行级跳过兜底；行尾块注释（非行首前缀）走 stripStringsAndComments 的
+    // /* */ 剔除路径——若失效，注释里的 agent({...}) 会开幻影调用范围并误报缺 description
+    const src = [
+      `/* agent({ prompt: 'x' }) */`,
+      `const s = "x"; /* agent({ prompt: 'y' }) */`,
+      `await agent({ prompt: "x", description: "d" });`,
+      ``,
+    ].join("\n");
+    const result = lintScript(src);
+
+    expect(warnings(result.findings).filter((w) => /description.*unnamed/i.test(w.message)))
+      .toHaveLength(0);
+    expect(errors(result.findings)).toHaveLength(0);
+  });
+});
+
+describe("MF-4 回归：非字面量实参 agent(callVar) / agent(expr()) 跳过", () => {
+  it("agent(callVar) 不产生 description warning，且不误伤后续真实 agent 调用", () => {
+    const src = [
+      `const call = { prompt: "x" };`,
+      `await agent(call);`,
+      `await agent({ prompt: "y", description: "d" });`,
+      ``,
+    ].join("\n");
+    const result = lintScript(src);
+
+    // 三连误报根因：非字面量实参被当成缺 description 报 warning
+    expect(warnings(result.findings).filter((w) => /description.*unnamed/i.test(w.message)))
+      .toHaveLength(0);
+  });
+
+  it("agent(expr()) 表达式实参同样跳过", () => {
+    const src = [
+      `await agent(buildCall());`,
+      `await agent({ prompt: "y", description: "d" });`,
+      ``,
+    ].join("\n");
+    const result = lintScript(src);
+
+    expect(warnings(result.findings).filter((w) => /description.*unnamed/i.test(w.message)))
+      .toHaveLength(0);
+  });
+
+  it("非字面量实参 + 后续真实调用缺 description → 只对真实调用报 1 条", () => {
+    // 跳过逻辑不能吞掉后面真正缺 description 的调用
+    const src = [
+      `await agent(call);`,
+      `await agent({ prompt: "y" });`,
+      ``,
+    ].join("\n");
+    const result = lintScript(src);
+
+    const descWarnings = warnings(result.findings).filter((w) => /description.*unnamed/i.test(w.message));
+    expect(descWarnings).toHaveLength(1);
+    expect(descWarnings[0].line).toBe(2);
+  });
+});
+
+// ── MF-4 回归：checkAgentDescription 的两个跳过分支 ────────────────
+
+describe("MF-4 回归：展开形态 / schema 内嵌 description", () => {
+  it("agent({ ...call, agent: ... }) 展开形态 → 0 description warning（review-fix-loop 三连误报根因修复点）", () => {
+    const src = [
+      `const call = { prompt: "x", model: "m" };`,
+      `await agent({ ...call, agent: "reviewer" });`,
+      ``,
+    ].join("\n");
+    const result = lintScript(src);
+
+    // 展开形态 description 来自运行时对象、调用点静态不可见——无法验证即不报
+    expect(warnings(result.findings).filter((w) => /description.*unnamed/i.test(w.message)))
+      .toHaveLength(0);
+  });
+
+  it("多行 agent 调用内 schema properties 含 description 字符串 → 仍报「无 description」warning（I-10 回归）", () => {
+    const src = [
+      `await agent({`,
+      `  prompt: "x",`,
+      `  schema: {`,
+      `    type: "object",`,
+      `    properties: {`,
+      `      result: { type: "string", description: "the result" },`,
+      `    },`,
+      `  },`,
+      `});`,
+      ``,
+    ].join("\n");
+    const result = lintScript(src);
+
+    // schema 内嵌的 description 是 JSON Schema 字段说明，不是 agent 选项——
+    // 若被误判为「已提供」则漏报（无 warning），本用例锁定仍报 warning
+    const descWarnings = warnings(result.findings).filter((w) => /description.*unnamed/i.test(w.message));
+    expect(descWarnings).toHaveLength(1);
+    expect(descWarnings[0].line).toBe(1);
+  });
+
+  it("schema 块剔除后，真正的 agent 选项 description 仍被识别（不误伤）", () => {
+    const src = [
+      `await agent({`,
+      `  prompt: "x",`,
+      `  schema: { properties: { r: { description: "d" } } },`,
+      `  description: "review-diff",`,
+      `});`,
+      ``,
+    ].join("\n");
+    const result = lintScript(src);
+
+    expect(warnings(result.findings).filter((w) => /description.*unnamed/i.test(w.message)))
+      .toHaveLength(0);
+  });
+});
+
+describe("meta.phases 非字符串数组 — warning", () => {
+  it("phases: [{...}] 对象数组 → warning", () => {
+    const src = [
+      `const meta = { phases: [{ title: "a" }, { title: "b" }] };`,
+      `await agent({ prompt: "x", description: "d" });`,
+      ``,
+    ].join("\n");
+    const result = lintScript(src);
+
+    expect(warnings(result.findings).some((w) => /meta\.phases.*string array/i.test(w.message)))
+      .toBe(true);
+  });
+
+  it("phases: ['a'] 字符串数组 → 0 此类 warning", () => {
+    const src = [
+      `const meta = { phases: ["a"] };`,
+      `phase("a");`,
+      `await agent({ prompt: "x", description: "d" });`,
+      ``,
+    ].join("\n");
+    const result = lintScript(src);
+
+    expect(warnings(result.findings).some((w) => /meta\.phases.*string array/i.test(w.message)))
+      .toBe(false);
+  });
+
+  it("多行对象数组（phases: [ 换行 { ... }）→ warning（MF-5 跨行匹配）", () => {
+    const src = [
+      `const meta = { phases: [`,
+      `  { title: "a" },`,
+      `  { title: "b" },`,
+      `] };`,
+      `await agent({ prompt: "x", description: "d" });`,
+      ``,
+    ].join("\n");
+    const result = lintScript(src);
+
+    expect(warnings(result.findings).some((w) => /meta\.phases.*string array/i.test(w.message)))
+      .toBe(true);
+  });
+
+  it("多行字符串数组（phases: [ 换行 'a' ]）→ 0 此类 warning", () => {
+    const src = [
+      `const meta = { phases: [`,
+      `  "a",`,
+      `] };`,
+      `phase("a");`,
+      `await agent({ prompt: "x", description: "d" });`,
+      ``,
+    ].join("\n");
+    const result = lintScript(src);
+
+    expect(warnings(result.findings).some((w) => /meta\.phases.*string array/i.test(w.message)))
+      .toBe(false);
+  });
+});
+
+describe("声明 phases 与 phase() 调用一致性 — warning", () => {
+  it("声明 + 调用一致 → 0 此类 warning", () => {
+    const src = [
+      `const meta = { phases: ["review"] };`,
+      `phase("review");`,
+      `await agent({ prompt: "x", description: "d" });`,
+      ``,
+    ].join("\n");
+    const result = lintScript(src);
+
+    expect(warnings(result.findings).some((w) =>
+      /never set via phase|called but not in meta\.phases/i.test(w.message))).toBe(false);
+  });
+
+  it("声明了但从不 phase() 调用 → warning", () => {
+    const src = [
+      `const meta = { phases: ["review", "fix"] };`,
+      `await agent({ prompt: "x", description: "d" });`,
+      ``,
+    ].join("\n");
+    const result = lintScript(src);
+
+    expect(warnings(result.findings).some((w) => /never set via phase/i.test(w.message)))
+      .toBe(true);
+  });
+
+  it("phase() 调用了但未声明 → warning", () => {
+    const src = [
+      `const meta = { phases: ["review"] };`,
+      `phase("fix");`,
+      `await agent({ prompt: "x", description: "d" });`,
+      ``,
+    ].join("\n");
+    const result = lintScript(src);
+
+    expect(warnings(result.findings).some((w) => /called but not in meta\.phases/i.test(w.message)))
+      .toBe(true);
+  });
+
+  it("对象数组 phases 不触发一致性 warning（由 checkMetaPhases 负责）", () => {
+    // 对象数组场景：checkPhaseConsistency 应跳过提取，不产生 never-set warning
+    const src = [
+      `const meta = { phases: [{ title: "a" }] };`,
+      `await agent({ prompt: "x", description: "d" });`,
+      ``,
+    ].join("\n");
+    const result = lintScript(src);
+
+    expect(warnings(result.findings).some((w) => /never set via phase/i.test(w.message)))
+      .toBe(false);
+  });
+
+  it("无 phases 声明 + 无 phase() 调用 → 0 warning（skip 分支）", () => {
+    // checkPhaseConsistency 的 declared/called 都为空 → 提前 return（脚本不使用 phase 机制）。
+    // 断言用全量 warning 而非 message 正则过滤——skip 分支若产生 spurious warning 也会被捕获
+    const src = [
+      `const meta = { name: "x" };`,
+      `await agent({ prompt: "x", description: "d" });`,
+      ``,
+    ].join("\n");
+    const result = lintScript(src);
+
+    expect(warnings(result.findings)).toHaveLength(0);
+  });
+});

package/src/orchestration/script-lint.ts

@@ -16,6 +16,9 @@
  * 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。
  *
@@ -110,20 +113,44 @@ function checkLine(lineText: string, lineNum: number): LintFinding[] {
 }
 
 /**
- * 找出 source 中所有 agent 调用跨度，检查错误的选项 key。
+ * 剔除字符串字面量与注释内容（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: ...,
- * outputSchema, ← error: 应为 schema
- * })
+ * 单行 agent 调用（如 `agent({ prompt: 'x' })`）的 startLine === endLine。
+ * 与 checkAgentCalls / checkAgentDescription 共享同一套范围定义，确保
+ * outputSchema 检查与 description 检查覆盖完全相同的调用集合（含 parallel/pipeline
+ * 内嵌的 agent() 调用——它们同样被 `\bagent\s*\(` 匹配）。
  *
- * 定位 agent 调用边界，检查 outputSchema 是否作为 key（非 value 如 `schema: outputSchema`）。
+ * 匹配前逐行剔除字符串/注释内容（MF-4）：字符串字面量里的 "agent(s)" 不再误触发。
+ * 非字面量实参（agent(callVar) / agent(expr)）跳过不回调：description 等选项在调用点
+ * 静态不可见，checkAgentDescription 无法验证运行时构造的调用——继续报 warning 即误报
+ * （review-fix-loop 的 agent(call) 三连误报根因）。
+ *
+ * @param callback (startLine, endLine) 0-based 行号
  */
-function checkAgentCalls(source: string): LintFinding[] {
-  const findings: LintFinding[] = [];
+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;
@@ -137,37 +164,58 @@ function checkAgentCalls(source: string): LintFinding[] {
       continue;
     }
 
+    // 匹配/计括号都用剔除字符串与注释后的行，避免字面量内容干扰
+    const codeLine = stripStringsAndComments(line);
+
  // 检测 agent 调用开始
-    if (!inAgentCall && /\bagent\s*\(/.test(line)) {
+    if (!inAgentCall && /\bagent\s*\(/.test(codeLine)) {
       inAgentCall = true;
       depth = 0;
       agentStartLine = i;
  // 从 agent( 开始计括号
-      const afterAgent = line.replace(/^.*?\bagent\s*\(/, "(");
+      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 调用
-        checkAgentCallOptions(lines, agentStartLine, i, findings);
+        callback(agentStartLine, i);
         inAgentCall = false;
       }
       continue;
     }
 
     if (inAgentCall) {
-      for (const ch of line) {
+      for (const ch of codeLine) {
         if (ch === "(" || ch === "{" || ch === "[") depth++;
         if (ch === ")" || ch === "}" || ch === "]") depth--;
       }
       if (depth <= 0) {
-        checkAgentCallOptions(lines, agentStartLine, i, findings);
+        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;
 }
 
@@ -213,6 +261,79 @@ function checkAgentCallOptions(
   }
 }
 
+/**
+ * 剔除 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 检测 ───────────────────────────
 
 /**
@@ -348,6 +469,99 @@ function analyzeIIFE(source: string, iifeStart: number): LintFinding | undefined
   };
 }
 
+// ── 显示性检查（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 脚本合法性。
  *
@@ -377,6 +591,12 @@ export function lintScript(source: string): LintResult {
  // 最终靠 worker-host → handleReturn → release → abort 的调用栈定位。
   findings.push(...checkBareAsyncIIFE(source));
 
+ // 显示性检查（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);
 

package/workflows/README.md

@@ -58,13 +58,16 @@ workflow run map-reduce --args itemsJson=/path/to/items.json --args operation=".
 workflow run review-fix-loop --args targetType=git-diff target=main \
   --args batch1=fallow-scan --args batch2=reviewer --args autoCommit=true
 workflow run review-fix-loop --args targetType=file target=/path/to/doc.md \
-  --args batch1=reviewer
+  --args batch1=doc-reviewer
 ```
 
 - `targetType` 枚举：`git-diff`（target=base ref）/ `file`（target=路径）/ `dir`（target=目录）/ `text`（target=自由描述）
 - `batch1..batchN`：批串行，批内并行 review → aggregate → fix → 重审直到 clean；批次用于前置依赖（如 `fallow-scan` 静态分析先行，后续审查才有意义）
-- 批内某 agent 无 must-fix 后后续轮跳过（`skipCleanAgents`，默认 true）；`recheckAfterFix=true` 可在 fix 后重派全批做回归防护
-- agent 项支持：AgentRegistry 名（如 `reviewer`）/ 自定义 .md 文件路径（如 `batch1=/path/to/reviewer.md`）/ 内置 `fallow-scan`
+- 批内某 agent 无 must-fix 后后续轮跳过（`skipCleanAgents` 默认 true + `recheckAfterFix` 默认 false）：clean agent 下轮跳过不重派；显式传 `recheckAfterFix=true` 启用强回归模式——fix 后重派全批，clean agent 走限定 prompt（只审 modifiedFiles ∪ 自检关联点，不诱导全量重扫）
+- agent 项支持：AgentRegistry 名（如 `reviewer`）/ 自定义 .md 文件路径（如 `batch1=/path/to/reviewer.md`）/ 内置 `fallow-scan` / **内置 `doc-reviewer`**（文档场景推荐：`targetType=file/dir` + `batch1=doc-reviewer`，四遍审查方法论：事实锚点核实/逻辑断言验证/落地清单完备性/边界与迁移；无 write 工具，报告经 schema 返回由 workflow 落盘）
+- `fixAgent`（可选）：fix 阶段加载指定 agent（内置名或 .md 路径）；代码场景可在该 agent.md 内写 verify 命令（typecheck/test 实测）当轮拦截编译类回归。⚠️ agent.md 内写的 verify 命令**必须确认能在目标项目可运行**（target 的包管理器/目录结构未知），否则命令失败会误报 fix 状态
+- `maxFixAttempts`（可选，默认 2）：needs-redesign 阈值。问题经 maxFixAttempts 次修复仍未收敛（regressed）→ 终止该批，terminated="needs-redesign"（结构性问题需人工介入，非继续补丁能解决）
+- `convergeNewIssues`（可选，默认 1）+ `convergeRounds`（可选，默认 2）：新发现率收敛阈值。连续 convergeRounds 轮新发现问题 ≤ convergeNewIssues **且**无 open/regressed 活跃条目 → terminated="converged"（推进下一批）。收敛不等于问题全清——需同时满足无活跃条目才终止
 - ⚠️ **fix 阶段会修改文件；`autoCommit` 默认 false（不 commit）**，需要提交时显式 `autoCommit=true`
 
 ## 编排 API