@zhushanwen/pi-subagent-workflow 3.0.0 → 4.0.0

package/agents/reviewer.md

@@ -2,7 +2,7 @@
 name: reviewer
 description: 代码审查 agent（diff 分析、问题发现）
 color: "#ef4444"
-tools: read
+tools: read, structured-output
 ---
 
 You are a code reviewer. Your role is to find bugs, logic errors, and security issues.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",
@@ -40,7 +40,7 @@
     ]
   },
   "dependencies": {
-    "@xyz-agent/extension-protocol": "^0.2.0",
+    "@xyz-agent/extension-protocol": "^0.3.0",
     "@zhushanwen/pi-extension-logger": "0.2.0"
   },
   "peerDependencies": {

package/skills/workflow-script-format/SKILL.md

@@ -54,7 +54,8 @@ const meta = { name: 'workflow-name', description: '...', phases: ['phase1', 'ph
 支持三种签名：
 - `agent(promptString)` — 最简，prompt 字符串，返回 content 字符串
 - `agent(promptString, { label?, schema?, ... })` — 字符串 + opts（`label` 是 `description` 的别名）
-- `agent({ prompt, schema?, description?, agent?, skill?, timeoutMs?, model?, scene? })` — 完整 opts 对象
+- `agent({ prompt, schema?, description?, agent?, skill?, timeoutMs?, model?, scene?, thinkingLevel? })` — 完整 opts 对象
+  - `thinkingLevel?` (`string`) — 思考强度，合法值 `off | minimal | low | medium | high | xhigh`，透传至 pi CLI 拼接为 `--model provider/modelId:thinkingLevel`（与 `model?` 同效，影响子 agent 推理预算）
 
 Returns `parsedOutput` (structured data when schema provided) or `content` (string).
 

package/src/execution/__tests__/agent-registry.test.ts

@@ -173,7 +173,7 @@ describe("createPackageBuiltinRegistry", () => {
     expect(builtin.get("orchestrator")?.tools).toEqual([
       "todo", "goal_control", "workflow", "subagent", "ask_user",
     ]);
-    expect(builtin.get("reviewer")?.tools).toEqual(["read"]);
+    expect(builtin.get("reviewer")?.tools).toEqual(["read", "structured-output"]);
     expect(builtin.get("planner")?.tools).toEqual(["read"]);
     expect(builtin.get("oracle")?.tools).toEqual(["read"]);
     expect(builtin.get("context-builder")?.tools).toEqual(["read"]);

package/src/interface/__tests__/detectors.test.ts

@@ -44,6 +44,20 @@ describe("findFlattenedArgKeys (workflow args flatten detector — P0)", () => {
     expect(findFlattenedArgKeys({ action: "status" })).toEqual([]);
   });
 
+  it("triggers for review-fix-loop args flattened to top level (incl. batchN prefix)", () => {
+    expect(
+      findFlattenedArgKeys({ action: "run", name: "review-fix-loop", targetType: "git-diff", target: "main" }),
+    ).toEqual(["targetType", "target"]);
+    expect(
+      findFlattenedArgKeys({ action: "run", name: "review-fix-loop", batch1: "reviewer", autoCommit: true }),
+    ).toEqual(["batch1", "autoCommit"]);
+    expect(
+      findFlattenedArgKeys({ action: "run", name: "review-fix-loop", args: { targetType: "git-diff", target: "main" } }),
+    ).toEqual([]);
+    // 未知键（如 batchl 拼错）不属于白名单，不触发平铺检测（由 workflow 内白名单校验报错）
+    expect(findFlattenedArgKeys({ action: "run", name: "x", batchl: "reviewer" })).toEqual([]);
+  });
+
   it("returns [] for non-object input", () => {
     expect(findFlattenedArgKeys(null)).toEqual([]);
     expect(findFlattenedArgKeys(undefined)).toEqual([]);

package/src/interface/tool-workflow.ts

@@ -99,7 +99,15 @@ const RUNID_SHORT = 8;
 /** 已知 workflow args 子字段——run action 的 args 顶层键。弱模型常把 task/items 等
  *  平铺到 workflow params 顶层（缺 args 嵌套），actionRun 静默 args={} 启动缺参 run（P0）。
  *  用此清单检测平铺形态，报错带 Correct 正例纠正。 */
-const KNOWN_ARG_KEYS = ["task", "target", "perspectives", "items", "itemsJson", "operation"];
+const KNOWN_ARG_KEYS = [
+  "task", "target", "perspectives", "items", "itemsJson", "operation",
+  // review-fix-loop 参数（内置 workflow，2026-08 新增）
+  "targetType", "agents", "batchNames", "reviewPrompt", "fixPrompt",
+  "autoCommit", "maxRounds", "stuckThreshold", "skipCleanAgents", "recheckAfterFix",
+];
+
+/** 前缀式参数（batch1..batchN 动态编号，无法枚举） */
+const KNOWN_ARG_KEY_PREFIXES = [/^batch\d+$/];
 
 /**
  * 检测弱模型把 args 子字段平铺到 workflow params 顶层（P0 静默失败防护）。
@@ -110,7 +118,9 @@ export function findFlattenedArgKeys(params: unknown): string[] {
   if (typeof params !== "object" || params === null) return [];
   const p = params as Record<string, unknown>;
   const args = typeof p.args === "object" && p.args !== null ? p.args : undefined;
-  return KNOWN_ARG_KEYS.filter((k) => k in p && !(args !== undefined && k in args));
+  const isKnownKey = (k: string) =>
+    KNOWN_ARG_KEYS.includes(k) || KNOWN_ARG_KEY_PREFIXES.some((re) => re.test(k));
+  return Object.keys(p).filter((k) => isKnownKey(k) && !(args !== undefined && k in args));
 }
 
 // ── Types ────────────────────────────────────────────────────
@@ -239,8 +249,11 @@ export function registerWorkflowTool(
       "chain (sequential 3-step: analyze→transform→synthesize; args: task), " +
       "parallel (multi-perspective analysis; args: target, optional perspectives), " +
       "scatter-gather (split→parallel→merge; args: task), " +
-      "map-reduce (parallel map→reduce; args: items/itemsJson + operation). " +
-      "Example: {\"action\":\"run\",\"name\":\"parallel\",\"args\":{\"target\":\"src/auth.ts\"}}.",
+      "map-reduce (parallel map→reduce; args: items/itemsJson + operation), " +
+      "review-fix-loop (multi-batch review→fix loop; args: targetType + target required, optional batch1..batchN). " +
+      "Example: {\"action\":\"run\",\"name\":\"parallel\",\"args\":{\"target\":\"src/auth.ts\"}}." +
+      "Use review-fix-loop when the user wants iterative code/doc review with fixes until clean " +
+      "(it is the ONLY built-in workflow that writes files; autoCommit defaults to false)." +
       "DISCOVERY: If unsure what workflows exist, call the workflow-script tool with " +
       "action:list first — it returns all available scripts (built-in + user-generated) " +
       "with source tags and descriptions. Then use this tool's run action to start one.",

package/src/orchestration/__tests__/worker-script-builder.test.ts

@@ -222,3 +222,38 @@ describe("buildWorkerScript — W2 agent() returnMeta mode", () => {
   });
 });
 
+// ── thinkingLevel 参数透传（agent() 三分支） ──
+// 验证 thinkingLevel 在 string / task-agent / object.prompt 三个分支均被透传至
+// agent-call 的 opts，且加入 _knownFields 白名单（object.prompt 分支整体透传，
+// 不被 unknown-fields warn 误报）。底层 AgentCallOpts→mapToExecuteOptions→
+// buildSpawnArgs 拼 pi CLI --model provider/modelId:thinkingLevel 已打通，
+// 此处只验入口层 wiring。
+
+describe("buildWorkerScript — agent() thinkingLevel passthrough (3 branches)", () => {
+  const script = buildWorkerScript("// noop user script");
+
+  it("string branch extracts thinkingLevel from secondArg (parity with model/scene/phase)", () => {
+    // agent("prompt", {thinkingLevel:"high"}) → string 分支 opts 提取 thinkingLevel
+    const stringBranch = script.match(/typeof firstArg === "string"[\s\S]*?\};/);
+    expect(stringBranch).toBeTruthy();
+    expect(stringBranch![0]).toContain(
+      "thinkingLevel: (secondArg && typeof secondArg === \"object\" && secondArg.thinkingLevel) || undefined",
+    );
+  });
+
+  it("task/agent branch includes thinkingLevel in opts (parity with model/skill/timeoutMs)", () => {
+    // agent({task, agent, thinkingLevel}) → task/agent 快捷分支透传 thinkingLevel
+    const taskAgentBranch = script.match(/firstArg\.task \|\| firstArg\.agent[\s\S]*?\};/);
+    expect(taskAgentBranch).toBeTruthy();
+    expect(taskAgentBranch![0]).toContain("thinkingLevel: firstArg.thinkingLevel");
+  });
+
+  it("thinkingLevel is a known field (object.prompt branch passes through without unknown-fields warn)", () => {
+    // object.prompt 分支 opts = firstArg 整体透传，thinkingLevel 自然带入；
+    // 但必须进 _knownFields 白名单，否则 Object.keys(opts) 含 thinkingLevel 会触发
+    // unknown-fields warn（workerLogs 污染）。验证 Set 与 warn 文案均识别 thinkingLevel。
+    expect(script).toContain('"thinkingLevel"');
+    expect(script).toMatch(/Known fields:.*thinkingLevel/);
+  });
+});
+

package/src/orchestration/worker-script-builder.ts

@@ -191,6 +191,7 @@ export function buildWorkerScript(userScript: string): string {
     '        model: (secondArg && typeof secondArg === "object" && secondArg.model) || undefined,',
     '        scene: (secondArg && typeof secondArg === "object" && secondArg.scene) || undefined,\n' +
       '        phase: (secondArg && typeof secondArg === "object" && secondArg.phase) || undefined,',
+      '        thinkingLevel: (secondArg && typeof secondArg === "object" && secondArg.thinkingLevel) || undefined,',
     '      };',
     '    } else if (typeof firstArg === "object" && firstArg !== null) {',
     '      if (firstArg.prompt) {',
@@ -211,6 +212,7 @@ export function buildWorkerScript(userScript: string): string {
     '          fork: firstArg.fork,',
     '          worktree: firstArg.worktree,',
     '          returnMeta: firstArg.returnMeta,',
+    '          thinkingLevel: firstArg.thinkingLevel,',
     '        };',
     '      } else {',
     '        opts = firstArg;',
@@ -220,10 +222,10 @@ export function buildWorkerScript(userScript: string): string {
     '    }',
     '',
     '    // Validate known agent() fields to catch API misuse early',
-    '    const _knownFields = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta"]);',
+    '    const _knownFields = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel"]);',
     '    const _unknownFields = Object.keys(opts).filter((k) => !_knownFields.has(k));',
     '    if (_unknownFields.length > 0) {',
-    '      _pushWorkerLog("warn", ["[workflow] agent() received unknown fields: " + _unknownFields.join(", ") + ". Known fields: prompt, description, schema, model, scene, label, task, agent, phase, skill, timeoutMs, cwd, fork, worktree, returnMeta"]);',
+    '      _pushWorkerLog("warn", ["[workflow] agent() received unknown fields: " + _unknownFields.join(", ") + ". Known fields: prompt, description, schema, model, scene, label, task, agent, phase, skill, timeoutMs, cwd, fork, worktree, returnMeta, thinkingLevel"]);',
     '    }',
     '',
     '    const callId = _callIdCounter;',

package/workflows/README.md

@@ -10,6 +10,9 @@
 | `parallel.js` | 多视角并行分析 → 聚合汇总 | `target`（可选 `perspectives`） | 多维度评估同一目标（安全/性能/可维护性等） |
 | `scatter-gather.js` | scatter 拆分 → parallel 处理 → gather 合并 | `task` | 大任务先拆成子任务再并行处理 |
 | `map-reduce.js` | parallel map → reduce 归约 | `items`/`itemsJson` + `operation` | 对已知数组批量变换后归约成单一结果 |
+| `review-fix-loop.js` | 多批串行（批内并行 review → aggregate → fix → 重审） | `targetType` + `target`（可选 `batch1..batchN`） | 代码/文档审查并修复直到 clean；前置检查先行（fallow 等） |
+
+> ⚠️ **review-fix-loop 是唯一带写操作的内置 workflow**（fix 阶段修改文件，`autoCommit=true` 才 commit）。其他 4 个均为只读分析。
 
 ## 用法
 
@@ -49,6 +52,21 @@ workflow run map-reduce --args itemsJson=/path/to/items.json --args operation=".
 
 `items` 直接传 JSON 数组，或 `itemsJson` 传 JSON 文件路径（二选一）。`parallel()` 对每个 item 并行执行 `operation` → reduce 阶段用 `agent()` 把各 item 的 map 结果归约成单一结论（LLM 归约，非纯代码拼接）。
 
+### review-fix-loop — 多批审查-修复循环
+
+```
+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
+```
+
+- `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`
+- ⚠️ **fix 阶段会修改文件；`autoCommit` 默认 false（不 commit）**，需要提交时显式 `autoCommit=true`
+
 ## 编排 API
 
 这些 workflow 内部使用的编排函数（`agent()` / `parallel()` / `pipeline()` / `workflow()`）由 worker 线程注入，完整 API 参考见 `skills/workflow-script-format/SKILL.md`。

package/workflows/review-fix-loop.js

@@ -0,0 +1,677 @@
+// review-fix-loop.js — 通用多批审查-修复循环（内置 workflow）
+//
+// 模式：多批（batch）串行，批内循环（round）：并行 review → aggregate → fix → 重审。
+// 批次用于表达前置依赖（fallow 静态分析等前置检查必须先完成，后续审查才有意义）。
+// 批内某 agent 已无 must-fix（critical/major）则后续轮跳过，优化 token 效率。
+//
+// 用法：
+//   workflow run review-fix-loop --args targetType=git-diff target=main \
+//     batch1=fallow-scan batch2=reviewer autoCommit=true
+//   workflow run review-fix-loop --args targetType=file target=/path/to/doc.md \
+//     batch1=reviewer autoCommit=false
+//
+// ⚠️ 唯一带写操作的内置 workflow：fix 阶段会修改文件（autoCommit=true 时 commit）。
+// ⚠️ lintScript 约束（本脚本已遵守）：含 parallel() 入口，禁止 bare IIFE；
+//    agent() 调用顺序确定（批次按配置顺序稳定排序，callId 重放安全）。
+
+const meta = {
+  name: "review-fix-loop",
+  description: "审查-修复循环：多批串行（批内并行 review → aggregate → fix → 重审直到 clean）。必填 targetType（git-diff/file/dir/text）+ target。批次由 batch1..batchN 控制（如 batch1=fallow-scan batch2=reviewer），用于前置检查先行的场景。注意：唯一带写操作/commit 副作用的内置 workflow，autoCommit 默认 false。",
+  phases: [
+    { title: "Review", detail: "Batch: parallel review by configured agents" },
+    { title: "Fix", detail: "Fix must-fix issues from aggregated report" },
+  ],
+};
+
+// ── 参数解析 + 白名单校验（fail-fast） ────────────────────────────
+
+const TARGET_TYPES = ["git-diff", "file", "dir", "text"];
+const VALID_ARG_KEYS = new Set([
+  "targetType", "target", "agents", "batchNames", "reviewPrompt", "fixPrompt",
+  "autoCommit", "maxRounds", "stuckThreshold", "model", "skipCleanAgents",
+  "recheckAfterFix", "_runId",
+]);
+
+function fail(msg) {
+  throw new Error("review-fix-loop: " + msg);
+}
+
+function normalizeBool(v, name, def) {
+  if (v === undefined || v === null || v === "") return def;
+  if (v === true || v === "true") return true;
+  if (v === false || v === "false") return false;
+  fail("参数 " + name + " 必须是布尔值（true/false），实际: " + JSON.stringify(v));
+}
+
+function normalizeInt(v, name, def) {
+  if (v === undefined || v === null || v === "") return def;
+  const n = typeof v === "number" ? v : Number(String(v).trim());
+  if (!Number.isInteger(n) || n <= 0) fail("参数 " + name + " 必须是正整数，实际: " + JSON.stringify(v));
+  return n;
+}
+
+// 白名单校验：未知参数名（防 batchX 拼错如 batchl）→ 报错
+for (const key of Object.keys($ARGS)) {
+  if (VALID_ARG_KEYS.has(key)) continue;
+  if (/^batch\d+$/.test(key)) continue;
+  fail("未知参数: " + key + "（合法参数: targetType/target/batch1..batchN/agents/batchNames/reviewPrompt/fixPrompt/autoCommit/maxRounds/stuckThreshold/model/skipCleanAgents/recheckAfterFix）");
+}
+
+const targetType = $ARGS.targetType;
+if (!TARGET_TYPES.includes(targetType)) {
+  fail("targetType 必填且必须是枚举之一: " + TARGET_TYPES.join("/") + "（实际: " + JSON.stringify(targetType) + "）");
+}
+const target = typeof $ARGS.target === "string" ? $ARGS.target.trim() : "";
+if (!target) fail("target 必填（git-diff 时传 base ref 如 main；file 传路径；dir 传目录；text 传描述）");
+
+const reviewPrompt = typeof $ARGS.reviewPrompt === "string" && $ARGS.reviewPrompt.trim()
+  ? $ARGS.reviewPrompt.trim()
+  : "审查变更/目标是否存在：逻辑错误、边界条件、类型不安全、遗漏、回归风险、代码规范问题。发现问题分三级：critical（严重，必须修）/ major（重要，应当修）/ minor（轻微，建议修）。critical+major 计入 must_fix。";
+const fixPrompt = typeof $ARGS.fixPrompt === "string" && $ARGS.fixPrompt.trim()
+  ? $ARGS.fixPrompt.trim()
+  : "修复全部 must-fix 问题（critical/major）。最小正确修复，不做重构、不做风格改动。";
+const autoCommit = normalizeBool($ARGS.autoCommit, "autoCommit", false);
+const maxRounds = normalizeInt($ARGS.maxRounds, "maxRounds", 10);
+const stuckThreshold = normalizeInt($ARGS.stuckThreshold, "stuckThreshold", 3);
+const skipCleanAgents = normalizeBool($ARGS.skipCleanAgents, "skipCleanAgents", true);
+const recheckAfterFix = normalizeBool($ARGS.recheckAfterFix, "recheckAfterFix", false);
+const MODEL = typeof $ARGS.model === "string" && $ARGS.model.trim() ? $ARGS.model.trim() : undefined;
+
+// 审查指令模板（按 targetType 生成，注入每个 review agent 的 prompt）
+function buildReviewInstruction() {
+  switch (targetType) {
+    case "git-diff":
+      return "Review `git diff " + target + "...HEAD` for all committed changes against " + target + ".\n" +
+        "ALSO run `git status --porcelain` and `git diff` to review uncommitted working-tree changes " +
+        "(fixes may be uncommitted when autoCommit=false; uncommitted changes ARE in scope).";
+    case "file":
+      return "Read and review the file: " + target;
+    case "dir":
+      return "Explore and review the directory: " + target + " (list files, then read the relevant ones)";
+    case "text":
+      return "Review target: " + target;
+  }
+}
+const reviewInstruction = buildReviewInstruction();
+
+// 批次解析：batch1..batchN（缺号报错）/ agents 简写 / 默认单批 [reviewer]
+function parseBatches() {
+  const batchKeys = Object.keys($ARGS)
+    .filter((k) => /^batch\d+$/.test(k))
+    .sort((a, b) => parseInt(a.slice(5), 10) - parseInt(b.slice(5), 10));
+  const nums = batchKeys.map((k) => parseInt(k.slice(5), 10));
+  for (let i = 1; i <= nums.length; i++) {
+    if (!nums.includes(i)) fail("批次参数缺号：有 batch" + nums.join("/") + " 但无 batch" + i + "（批次必须连续编号）");
+  }
+  if ($ARGS.agents !== undefined && $ARGS.batch1 !== undefined) {
+    fail("agents 与 batch1 不能同时传（agents 是单批简写）");
+  }
+
+  let rawBatches;
+  if (batchKeys.length > 0) {
+    rawBatches = batchKeys.map((k) => $ARGS[k]);
+  } else if ($ARGS.agents !== undefined) {
+    rawBatches = [$ARGS.agents];
+  } else {
+    rawBatches = ["reviewer"]; // 默认单批：包内置通用审查 agent
+  }
+
+  return rawBatches.map((raw, idx) => {
+    if (typeof raw !== "string" || !raw.trim()) fail("batch" + (idx + 1) + " 不能为空");
+    const names = raw.split(",").map((s) => s.trim()).filter(Boolean);
+    if (names.length === 0) fail("batch" + (idx + 1) + " 为空（逗号分隔 agent 名/文件路径）");
+    if (new Set(names).size !== names.length) fail("batch" + (idx + 1) + " 内存在重复 agent: " + names);
+    return names;
+  });
+}
+const BATCHES = parseBatches();
+
+// batchNames（数量校验）
+const rawBatchNames = typeof $ARGS.batchNames === "string" && $ARGS.batchNames.trim()
+  ? $ARGS.batchNames.split(",").map((s) => s.trim()).filter(Boolean)
+  : [];
+if (rawBatchNames.length > 0 && rawBatchNames.length !== BATCHES.length) {
+  fail("batchNames 数量（" + rawBatchNames.length + "）必须与批数（" + BATCHES.length + "）一致");
+}
+const BATCH_NAMES = rawBatchNames.length ? rawBatchNames : BATCHES.map((_, i) => "batch-" + (i + 1));
+
+// fallow-scan 只在 git-diff 类型下有意义
+for (let i = 0; i < BATCHES.length; i++) {
+  if (BATCHES[i].includes("fallow-scan") && targetType !== "git-diff") {
+    fail("fallow-scan 只支持 targetType=git-diff（它审查 git 变更的静态分析），实际 targetType=" + targetType);
+  }
+}
+
+// ── Schemas ─────────────────────────────────────────────────────────
+
+const reviewerSchema = {
+  type: "object",
+  properties: {
+    report_file: { type: "string", description: "Absolute path to the written review report (.md)" },
+    must_fix: { type: "number", description: "Number of must-fix (critical+major) issues found" },
+    suggestion: { type: "number", description: "Number of suggestion-level (minor) issues found" },
+  },
+  required: ["report_file", "must_fix", "suggestion"],
+};
+
+const aggregatorSchema = {
+  type: "object",
+  properties: {
+    report_file: { type: "string", description: "Absolute path to aggregated.md" },
+    must_fix: { type: "number", description: "Total must-fix after dedup across all dimensions" },
+    suggestion: { type: "number", description: "Total suggestions after dedup across all dimensions" },
+  },
+  required: ["report_file", "must_fix", "suggestion"],
+};
+
+// ── Per-run isolation: runId-scoped directories ─────────────────────
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const RUN_ID = ($ARGS._runId && typeof $ARGS._runId === "string") ? $ARGS._runId : "run-" + Date.now();
+const RUN_ROOT = path.join(os.tmpdir(), "review-fix-loop", RUN_ID);
+const STATE_FILE = RUN_ROOT + "/state.json";
+
+fs.mkdirSync(RUN_ROOT, { recursive: true });
+log("Run directory: " + RUN_ROOT);
+
+// ── State management (persistent, atomic writes) ────────────────────
+
+function loadState() {
+  try {
+    return JSON.parse(fs.readFileSync(STATE_FILE, "utf-8"));
+  } catch {
+    return {
+      meta: {
+        runId: RUN_ID, workspace: $WORKSPACE || "", model: MODEL || "(default)",
+        targetType, target, batches: BATCHES, startedAt: new Date().toISOString(),
+      },
+      agentStatus: {},
+      fixCount: 0,
+      batches: [],
+    };
+  }
+}
+
+function saveState(state) {
+  const tmp = STATE_FILE + ".tmp";
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2));
+  fs.renameSync(tmp, STATE_FILE);
+}
+
+// clean 记录：lastCleanBatch + 当时全局 fixCount 快照（跨批跳过判定依据）
+function recordAgentClean(state, agentName, batchIndex) {
+  const s = state.agentStatus[agentName] || { lastCleanBatch: 0, lastCleanFixCount: 0, lastActiveRound: 0, lastMustFix: undefined };
+  s.lastCleanBatch = batchIndex;
+  s.lastCleanFixCount = state.fixCount;
+  s.lastActiveRound = batchIndex;
+  state.agentStatus[agentName] = s;
+}
+
+function recordAgentDirty(state, agentName, mustFix, batchIndex) {
+  const s = state.agentStatus[agentName] || { lastCleanBatch: 0, lastCleanFixCount: 0, lastActiveRound: 0, lastMustFix: undefined };
+  s.lastActiveRound = batchIndex;
+  s.lastMustFix = mustFix;
+  state.agentStatus[agentName] = s;
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+function parseResult(raw) {
+  if (typeof raw === "object" && raw !== null) return raw;
+  if (typeof raw === "string") {
+    let s = raw.trim();
+    const fence = s.match(/^```(?:json)?\s*\n([\s\S]*?)\n?```\s*$/i);
+    if (fence) s = fence[1].trim();
+    if (!s.startsWith("{") && !s.startsWith("[")) {
+      const first = s.indexOf("{");
+      const last = s.lastIndexOf("}");
+      if (first !== -1 && last > first) s = s.slice(first, last + 1);
+    }
+    try { return JSON.parse(s); } catch { /* fall through */ }
+  }
+  return null;
+}
+
+function normalizeAggregatorResult(raw) {
+  const parsed = parseResult(raw);
+  if (!parsed) return null;
+  const mustFix =
+    typeof parsed.must_fix === "number" ? parsed.must_fix :
+    typeof parsed.totalMustFix === "number" ? parsed.totalMustFix :
+    typeof parsed.mustFix === "number" ? parsed.mustFix : undefined;
+  const suggestion =
+    typeof parsed.suggestion === "number" ? parsed.suggestion :
+    typeof parsed.totalSuggestions === "number" ? parsed.totalSuggestions :
+    typeof parsed.suggestions === "number" ? parsed.suggestions : 0;
+  if (typeof mustFix !== "number") return null;
+  return { report_file: parsed.report_file || parsed.reportFile, must_fix: mustFix, suggestion };
+}
+
+function parseAggregatedMd(content) {
+  const mustFixMatch = content.match(/[-*]\s*Must[-_]fix\s*[:：]\s*(\d+)/i);
+  if (!mustFixMatch) return null;
+  const suggestionMatch = content.match(/[-*]\s*Suggestions?\s*[:：]\s*(\d+)/i);
+  return {
+    must_fix: parseInt(mustFixMatch[1], 10),
+    suggestion: suggestionMatch ? parseInt(suggestionMatch[1], 10) : 0,
+  };
+}
+
+// 自定义 .md agent 加载：frontmatter（name/description/model）+ 正文
+function loadAgentMd(filePath) {
+  let content;
+  try {
+    content = fs.readFileSync(filePath, "utf-8");
+  } catch (e) {
+    fail("agent 文件读取失败: " + filePath + " (" + e.message + ")");
+  }
+  let name = path.basename(filePath, ".md");
+  let model, description;
+  let body = content.trim();
+  if (content.startsWith("---")) {
+    const closeIdx = content.indexOf("---", 3);
+    if (closeIdx !== -1) {
+      const yaml = content.slice(3, closeIdx);
+      body = content.slice(closeIdx + 3).trim();
+      const extract = (key) => {
+        const m = yaml.match(new RegExp("^" + key + ":\\s*(.+)$", "m"));
+        if (!m) return undefined;
+        let v = m[1].trim();
+        if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+        return v || undefined;
+      };
+      name = extract("name") || name;
+      model = extract("model");
+      description = extract("description");
+    }
+  }
+  return { name, model, description, systemPrompt: body, report: name, title: description || name, isCustom: true };
+}
+
+// ── Agent defs 解析（每批元素统一解析） ─────────────────────────────
+
+// fallow-scan：内置工具型 def（无 .md，跑 fallow audit 静态分析）
+const FALLOW_DEF = { name: "fallow-scan", title: "FALLOW STATIC ANALYSIS", report: "fallow-scan", isFallow: true };
+
+function resolveAgentDefs(batchNames) {
+  return batchNames.map((item) => {
+    if (item === "fallow-scan") return FALLOW_DEF;
+    if (item.includes("/") || item.endsWith(".md")) return loadAgentMd(item);
+    return { name: item, report: item.replace(/^review-/, ""), title: item.toUpperCase() };
+  });
+}
+
+// ── Build review calls ──────────────────────────────────────────────
+
+function buildReviewCall(def, round, max, batchIndex, roundDir) {
+  const header = "Batch " + batchIndex + " Round " + round + "/" + max + " — " + BATCH_NAMES[batchIndex - 1];
+  const prevBatchesHint = batchIndex > 1
+    ? "\nPrior batch reports (optional context): " + RUN_ROOT + "/batch-*/  (use read)"
+    : "";
+  const base = {
+    model: MODEL || def.model,
+    schema: reviewerSchema,
+    description: def.name,
+    timeoutMs: 1_800_000,
+  };
+
+  if (def.isFallow) {
+    return {
+      ...base,
+      prompt: [
+        header,
+        "",
+        "Fallow static-analysis pre-scan (tool-based, NOT a git-diff review).",
+        "",
+        "Steps:",
+        "1. Check if fallow is installed: `which fallow`",
+        "2. If NOT installed: write the report with a one-line note, must_fix=0, suggestion=0.",
+        "3. If installed, run: `fallow audit --base " + target + " --format json --quiet`",
+        "4. Extract: complexity hotspots, dead code, unused exports, circular deps",
+        "5. Classify findings: critical/major count into must_fix; minor into suggestion.",
+        "",
+        "output 路径：" + roundDir + "/" + def.report + ".md",
+        "Write report to: " + roundDir + "/" + def.report + ".md",
+      ].join("\n"),
+    };
+  }
+
+  const spec = def.isCustom
+    ? "\n\nReviewer specification (from agent file):\n" + def.systemPrompt
+    : "";
+  return {
+    ...base,
+    prompt: [
+      header,
+      "",
+      reviewInstruction + prevBatchesHint,
+      "",
+      "Review requirements:",
+      reviewPrompt + spec,
+      "",
+      "output 路径：" + roundDir + "/" + def.report + ".md",
+      "Write report to: " + roundDir + "/" + def.report + ".md",
+    ].join("\n"),
+    agent: def.isCustom ? undefined : def.name,
+  };
+}
+
+// agent 名解析失败（AgentRegistry not found）时，尝试 review- 前缀兜底
+async function runReviewAgent(call) {
+  let raw = await agent(call);
+  if (raw && typeof raw === "object" && raw.error && typeof raw.error === "string"
+      && raw.error.includes("Agent not found") && call.agent && !call.agent.startsWith("review-")) {
+    log("Agent not found: " + call.agent + " — retrying with review- prefix");
+    raw = await agent({ ...call, agent: "review-" + call.agent });
+  }
+  return raw;
+}
+
+// ── Main loop: batches (serial) × rounds (per-batch) ────────────────
+
+const state = loadState();
+let totalFixed = 0;
+let terminated = "clean";
+let finalMessage = "";
+
+for (let batchIndex = 1; batchIndex <= BATCHES.length; batchIndex++) {
+  const defs = resolveAgentDefs(BATCHES[batchIndex - 1]);
+  const cleanNames = new Set();
+  let round = 0;
+  let prevTotal = -1;
+  let stuckCount = 0;
+  let batchClean = false;
+  let roundHasFix = false; // recheckAfterFix 用：上轮是否有 fix
+  const batchRounds = [];
+
+  // 跨批跳过：agent 在更早批 clean 且此后无 fix → 本批不派发
+  if (batchIndex > 1) {
+    for (const def of defs) {
+      const s = state.agentStatus[def.name];
+      if (s && s.lastCleanBatch && s.lastCleanBatch < batchIndex && s.lastCleanFixCount === state.fixCount) {
+        cleanNames.add(def.name);
+        log("Cross-batch skip: " + def.name + " (clean in batch " + s.lastCleanBatch + ", no fix since)");
+      }
+    }
+  }
+
+  while (round < maxRounds) {
+    round++;
+    log("--- Batch " + batchIndex + "/" + BATCHES.length + " (" + BATCH_NAMES[batchIndex - 1] + ") Round " + round + "/" + maxRounds + " ---");
+
+    phase("Review");
+    const roundDir = RUN_ROOT + "/batch-" + batchIndex + "/round-" + round;
+    fs.mkdirSync(roundDir, { recursive: true });
+
+    let active = defs.filter((def) => !(skipCleanAgents && cleanNames.has(def.name)));
+    if (recheckAfterFix && round > 1 && roundHasFix) {
+      active = defs; // fix 后重派全批（回归防护）
+      cleanNames.clear();
+    }
+
+    if (active.length === 0) {
+      log("All agents clean/skipped — batch " + batchIndex + " done.");
+      batchClean = true;
+      break;
+    }
+
+    log("Review: " + active.map((d) => d.name).join(", ") + " (" + active.length + " agent(s) in parallel)...");
+    const calls = active.map((def) => buildReviewCall(def, round, maxRounds, batchIndex, roundDir));
+    const allRaw = await parallel(calls);
+
+    // per-agent 结果区分：parallel 结果与 calls 一一对应
+    const reviewResults = [];
+    const agentRoundResults = [];
+    for (let i = 0; i < allRaw.length; i++) {
+      const raw = allRaw[i];
+      if (raw && typeof raw === "object" && raw.error) {
+        // fail-fast：审查 agent 调用失败（含 AgentRegistry not found）不得静默跳过
+        fail("审查 agent 调用失败: " + active[i].name + " — " + raw.error);
+      }
+      const parsed = parseResult(raw);
+      if (parsed && typeof parsed.must_fix === "number") {
+        reviewResults.push(parsed);
+        const def = active[i];
+        if (parsed.must_fix === 0) {
+          recordAgentClean(state, def.name, batchIndex);
+          cleanNames.add(def.name);
+        } else {
+          recordAgentDirty(state, def.name, parsed.must_fix, batchIndex);
+        }
+        agentRoundResults.push({ name: def.name, must_fix: parsed.must_fix, suggestion: parsed.suggestion ?? 0, clean: parsed.must_fix === 0 });
+      } else {
+        // tools 受限的 agent（如 tools: read）会过滤掉 structured-output → schema 失效，
+        // 结果缺 must_fix。fail 信息完整 dump raw 便于定位。
+        fail("审查 agent 结果无效（缺 must_fix）: " + active[i].name + " raw=" + JSON.stringify(raw).slice(0, 400));
+      }
+    }
+
+    if (reviewResults.every((r) => r.must_fix === 0)) {
+      log("Batch " + batchIndex + " round " + round + ": all agents clean.");
+      batchRounds.push({ round, mustFix: 0, suggestion: reviewResults.reduce((a, r) => a + (r.suggestion ?? 0), 0), agents: agentRoundResults, modifiedFiles: [] });
+      saveState(state);
+      batchClean = true;
+      break;
+    }
+
+    // ── Aggregate（内置 prompt，不依赖任何 agent.md） ─────────
+    const aggRaw = await agent({
+      prompt: [
+        "Batch " + batchIndex + "/" + BATCHES.length + " Round " + round + "/" + maxRounds + " — AGGREGATE REVIEWS",
+        "",
+        "You have TWO outputs: (1) a markdown report file and (2) a JSON return value.",
+        "",
+        "Sub-review results: " + JSON.stringify(reviewResults, null, 2),
+        "outputDir: " + roundDir,
+        "",
+        "─── PART 1: WRITE FILE ───────────────────────────────────",
+        "Write the human-readable aggregated report to:",
+        roundDir + "/aggregated.md",
+        "",
+        "Top section MUST be:",
+        "```",
+        "## Summary",
+        "- Must-fix: <N>",
+        "- Suggestions: <N>",
+        "- Infos: <N>",
+        "- Dimensions reviewed: <comma-separated>",
+        "- Dedup: <N> duplicates removed",
+        "```",
+        "",
+        "Followed by tables of Must-Fix Issues, Suggestions, Infos, and a Conclusion section.",
+        "The format `- Must-fix: N` and `- Suggestions: N` is critical: a fallback parser depends on it.",
+        "",
+        "─── PART 2: RETURN JSON (CRITICAL — loop reads THIS) ─────",
+        "Your FINAL response MUST be a single JSON object and NOTHING ELSE.",
+        "",
+        "Required shape (exact field names, no aliases, no extras):",
+        "{",
+        '  "report_file": "' + roundDir + '/aggregated.md",',
+        '  "must_fix": <integer>,',
+        '  "suggestion": <integer>',
+        "}",
+        "",
+        "STRICT RULES:",
+        "- Field names MUST be exactly: report_file, must_fix, suggestion",
+        "- must_fix and suggestion MUST be integers — NOT strings, NOT null, NOT undefined",
+        "- The JSON object MUST be the ONLY thing in your final response",
+        "- DO NOT wrap in markdown code fences, DO NOT add prose before/after",
+        "",
+        "─── SELF-CHECK before returning ──────────────────────────",
+        "1. Did you write " + roundDir + "/aggregated.md? If not, do it first.",
+        "2. Is must_fix in your JSON equal to the 'Must-fix: N' in your markdown?",
+        "3. Is your final response the bare JSON object, no fences, no prose?",
+      ].join("\n"),
+      model: MODEL,
+      schema: aggregatorSchema,
+      description: "aggregate",
+      timeoutMs: 1_800_000,
+    });
+
+    let agg = normalizeAggregatorResult(aggRaw);
+
+    if (!agg || typeof agg.must_fix !== "number") {
+      const rawPreview = (typeof aggRaw === "string" ? aggRaw : JSON.stringify(aggRaw)).slice(0, 200);
+      log("Aggregator JSON invalid (len=" + (aggRaw?.length ?? 0) + "): " + rawPreview);
+      const fallbackPath = (agg && agg.report_file) || (roundDir + "/aggregated.md");
+      try {
+        const content = fs.readFileSync(fallbackPath, "utf-8");
+        const parsed = parseAggregatedMd(content);
+        if (parsed && typeof parsed.must_fix === "number") {
+          agg = { report_file: fallbackPath, must_fix: parsed.must_fix, suggestion: parsed.suggestion ?? 0 };
+          log("Fallback parsed from " + fallbackPath + ": must_fix=" + agg.must_fix);
+        }
+      } catch { /* fallback read failed */ }
+
+      if (!agg || typeof agg.must_fix !== "number") {
+        log("Aggregator failed and fallback failed, stopping.");
+        state.batches.push({ index: batchIndex, name: BATCH_NAMES[batchIndex - 1], rounds: batchRounds });
+        saveState(state);
+        terminated = "aggregator-failure";
+        finalMessage = "Batch " + batchIndex + " round " + round + ": aggregator 失败且 fallback 解析失败";
+        batchIndex = BATCHES.length + 1; // 终止外层循环
+        break;
+      }
+    }
+
+    const mustFix = agg.must_fix;
+    const suggestion = agg.suggestion ?? 0;
+    log("Aggregated: " + mustFix + " must-fix + " + suggestion + " suggestion(s).");
+
+    // ── Stuck detection ─────────────────────────────────────
+    const total = mustFix + suggestion;
+    if (prevTotal >= 0 && total >= prevTotal) {
+      stuckCount++;
+      if (stuckCount >= stuckThreshold) {
+        log("Stuck: total issues not decreasing for " + stuckThreshold + " rounds. Stopping.");
+        batchRounds.push({ round, mustFix, suggestion, agents: agentRoundResults, modifiedFiles: [] });
+        state.batches.push({ index: batchIndex, name: BATCH_NAMES[batchIndex - 1], rounds: batchRounds });
+        saveState(state);
+        terminated = "stuck";
+        finalMessage = "Batch " + batchIndex + " round " + round + ": 总问题数连续 " + stuckThreshold + " 轮不下降";
+        batchIndex = BATCHES.length + 1;
+        break;
+      }
+    } else {
+      stuckCount = 0;
+    }
+    prevTotal = total;
+
+    // ── Fix ─────────────────────────────────────────────────
+    phase("Fix");
+    let reportContent;
+    try {
+      reportContent = fs.readFileSync(agg.report_file, "utf-8");
+    } catch {
+      reportContent = "(could not read aggregated report)";
+    }
+
+    let prevHead = "";
+    try {
+      prevHead = require("child_process").execSync(
+        "git rev-parse HEAD", { encoding: "utf-8", timeout: 10_000 }
+      ).trim();
+    } catch {
+      // 非 git 项目（如纯文档目录）：prevHead 为空，跳过 modifiedFiles 统计
+    }
+
+    const commitInstr = autoCommit
+      ? "- After all fixes, stage ONLY the files you modified: `git add <file1> <file2> ...` (explicit paths).\n" +
+        "- NEVER use `git add -A` or `git add .` — the workspace may contain unrelated untracked files.\n" +
+        "- Commit with message: `fix: review batch " + batchIndex + " round " + round + " — " + mustFix + " must-fix`"
+      : "- Do NOT commit. Leave the fixes in the working tree (autoCommit=false).";
+
+    const fxRaw = await agent({
+      prompt: [
+        "Fix round " + round + " (batch " + batchIndex + "): Fix ALL must-fix issues from the aggregated review report below.",
+        "",
+        "## Aggregated Review Report",
+        reportContent,
+        "",
+        "## Instructions",
+        "- Fix every must-fix issue listed in the report",
+        "- Apply the MINIMAL correct fix (no refactoring, no style changes)",
+        "- Verify each fix by reading the changed file afterwards",
+        fixPrompt,
+        commitInstr,
+        "",
+        "Return the count of issues fixed.",
+      ].join("\n"),
+      schema: {
+        type: "object",
+        properties: {
+          fixed_count: { type: "number", description: "Number of issues fixed" },
+          fixes: { type: "array", items: { type: "string" }, description: "One-line description of each fix" },
+        },
+        required: ["fixed_count"],
+      },
+      model: MODEL,
+      description: "fix",
+    });
+
+    const fx = parseResult(fxRaw);
+    if (!fx) {
+      log("Fix agent failed, stopping.");
+      batchRounds.push({ round, mustFix, suggestion, agents: agentRoundResults, modifiedFiles: [] });
+      state.batches.push({ index: batchIndex, name: BATCH_NAMES[batchIndex - 1], rounds: batchRounds });
+      saveState(state);
+      terminated = "fix-failure";
+      finalMessage = "Batch " + batchIndex + " round " + round + ": fix agent 结果无效";
+      batchIndex = BATCHES.length + 1;
+      break;
+    }
+
+    const fixedCount = fx.fixed_count ?? mustFix;
+    totalFixed += fixedCount;
+    state.fixCount++;
+    roundHasFix = true;
+
+    let modifiedFiles = [];
+    if (prevHead) {
+      try {
+        const out = require("child_process").execSync(
+          "git diff --name-only " + prevHead, { encoding: "utf-8", timeout: 10_000 }
+        ).trim();
+        modifiedFiles = out ? out.split("\n") : [];
+      } catch { /* empty */ }
+    }
+    batchRounds.push({ round, mustFix, suggestion, agents: agentRoundResults, modifiedFiles });
+    saveState(state);
+
+    log("Fixed " + fixedCount + " issue(s). Total: " + totalFixed + ". Modified " + modifiedFiles.length + " file(s). Continuing...");
+  }
+
+  if (batchIndex > BATCHES.length) break; // 已终止
+
+  state.batches.push({ index: batchIndex, name: BATCH_NAMES[batchIndex - 1], rounds: batchRounds });
+
+  if (!batchClean) {
+    // 该批达到 maxRounds 仍残留 must-fix → fail-fast，不进入后续批
+    terminated = "max-rounds";
+    finalMessage = "Batch " + batchIndex + " (" + BATCH_NAMES[batchIndex - 1] + ") 达到 maxRounds=" + maxRounds + " 仍有 must-fix，终止整个 workflow";
+    log(finalMessage);
+    saveState(state);
+    batchIndex = BATCHES.length + 1;
+    break;
+  }
+  saveState(state);
+  log("=== Batch " + batchIndex + " (" + BATCH_NAMES[batchIndex - 1] + ") CLEAN ===");
+}
+
+log("\n=== Loop Complete ===");
+saveState(state);
+
+return {
+  batches: BATCHES.length,
+  totalFixed,
+  terminated,
+  targetType,
+  target,
+  runDir: RUN_ROOT,
+  message: terminated === "clean"
+    ? "All batches clean. " + totalFixed + " issue(s) fixed total. State: " + STATE_FILE
+    : finalMessage + ". State: " + STATE_FILE,
+};