ppxans-harness 2.4.0

package/src/tools/catalog.js

@@ -0,0 +1,159 @@
+// src/tools/catalog.js - 工具注册表 (参考 openhanako tool-catalog + deepseek Capability Seam)
+// 升级: 能力缝三分法(Definition元数据/Provider实现/Consumer策略) + 热挂载(enable/disable/unregister) + 元数据枚举
+// P0 (2026-09-15): 策略订阅者链 + deny-wins 合并 (吸收 Aegis/HookBus 治理语义) ——
+//   安全策略 (命令守卫/免疫闸门/防注入) 挂到工具执行唯一收口, 成为架构不变量而非可选行为
+import { info } from "../utils/logger.js";
+import { normalizeMeta, runWithPolicy, toDescriptor, TOOL_ERROR_PREFIX } from "./seam.js";
+
+export { TOOL_ERROR_PREFIX };
+
+// ---- Deny-Wins 决策合并 (HookBus consolidate 语义) ----
+// 多个策略订阅者对同一工具调用给出冲突决策时:
+//   任一 deny 一票否决 (取最高优先级 reason); 否则任一 ask → ask; 否则 allow
+// 保证安全策略不能被低优先级 allow 投票覆盖 (纵深防御: 治理/合规/预算可叠加互不干扰)
+export function consolidateDecisions(decisions) {
+  const denies = decisions.filter((d) => d && d.decision === "deny");
+  if (denies.length > 0) {
+    const top = denies.reduce((a, b) => ((a.priority || 0) >= (b.priority || 0) ? a : b));
+    return { decision: "deny", reason: top.reason || "策略拒绝", priority: top.priority || 0 };
+  }
+  const asks = decisions.filter((d) => d && d.decision === "ask");
+  if (asks.length > 0) {
+    const top = asks.reduce((a, b) => ((a.priority || 0) >= (b.priority || 0) ? a : b));
+    return { decision: "ask", reason: top.reason || "需要审批", priority: top.priority || 0 };
+  }
+  return { decision: "allow", reason: null, priority: 0 };
+}
+
+export class ToolCatalog {
+  constructor() {
+    this.tools = new Map(); // name -> meta (Definition + Provider)
+    this.policySubscribers = []; // 策略订阅者: { fn(name,args,ctx)->Decision|null, priority, name }
+  }
+
+  // ---- Definition + Provider 注册 ----
+  register(def) {
+    if (!def || typeof def.execute !== "function") {
+      throw new Error(`工具注册失败: 需 name + execute (got ${def && def.name})`);
+    }
+    const meta = normalizeMeta(def); // 关键: execute 缺失由 normalizeMeta 的 name 校验兜底
+    this.tools.set(meta.name, meta);
+    info(`能力已注册: ${meta.name} [${meta.category}/${meta.power}]`);
+    return this;
+  }
+
+  // ---- 热挂载: 卸载 ----
+  unregister(name) {
+    const had = this.tools.delete(name);
+    if (had) info(`能力已卸载: ${name}`);
+    return had;
+  }
+
+  // ---- 热挂载: 启用/禁用 ----
+  enable(name) {
+    const t = this.tools.get(name);
+    if (!t) return false;
+    t.enabled = true;
+    return true;
+  }
+
+  disable(name) {
+    const t = this.tools.get(name);
+    if (!t) return false;
+    t.enabled = false;
+    return true;
+  }
+
+  // ---- OpenAI 兼容的 tools 格式 (给 LLM 用, 只含启用项) ----
+  toOpenAI() {
+    return [...this.tools.values()]
+      .filter((t) => t.enabled)
+      .map((t) => ({
+        type: "function",
+        function: { name: t.name, description: t.description, parameters: t.parameters },
+      }));
+  }
+
+  // ---- 审计: 可选注入审计哈希链 (未注入时零开销, 保持向后兼容) ----
+  // 吸收自 ppx-v2: 每次工具调用落一条 append-only + SHA-256 链式记录, 防审计日志被悄悄改写
+  setAudit(auditLog) {
+    this.audit = auditLog || null;
+    return this;
+  }
+
+  // ---- 策略订阅者 (P0): 工具执行唯一收口上的安全策略链 ----
+  // fn(name, args, ctx) -> Promise<{decision:'allow'|'deny'|'ask', reason?, priority?}> | null (null/undefined = 弃权)
+  // priority: 高者优先 (合并冲突决策时取高优先级 reason); 默认 0
+  // 订阅者异常不拖垮工具执行: 记日志并视同弃权 (fail-open), 但可被上层熔断器保护 (见 src/bus/circuit-breaker.js)
+  addPolicySubscriber(fn, { priority = 0, name = "" } = {}) {
+    if (typeof fn !== "function") throw new Error("策略订阅者需为函数");
+    const sub = { fn, priority: Number(priority) || 0, name: name || `policy-${this.policySubscribers.length + 1}` };
+    this.policySubscribers.push(sub);
+    return () => {
+      const i = this.policySubscribers.indexOf(sub);
+      if (i >= 0) this.policySubscribers.splice(i, 1);
+    };
+  }
+
+  // 未注入策略订阅者时零开销 (空数组循环天然跳过)
+  async _runPolicyChain(name, args, ctx) {
+    if (!this.policySubscribers.length) return { decision: "allow", reason: null, priority: 0 };
+    const results = await Promise.all(this.policySubscribers.map(async (sub) => {
+      try {
+        const d = await sub.fn(name, args, ctx);
+        if (!d || !d.decision) return null;
+        return { decision: d.decision, reason: d.reason || null, priority: d.priority ?? sub.priority };
+      } catch (e) {
+        info(`[policy] 订阅者 ${sub.name} 异常, 视同弃权: ${e?.message || e}`);
+        return null;
+      }
+    }));
+    return consolidateDecisions(results.filter(Boolean));
+  }
+
+  // ---- Consumer: 统一策略执行 ----
+  async call(name, args, ctx = {}) {
+    const meta = this.tools.get(name);
+    if (!meta) {
+      return `${TOOL_ERROR_PREFIX} 未知工具: ${name}`;
+    }
+    info(`tool: ${name}(${JSON.stringify(args)})`);
+    // P0: 策略链先行 (deny-wins) —— 免疫闸门/命令守卫/防注入在此拦截, 不可被旁路
+    const policy = await this._runPolicyChain(name, args, ctx);
+    if (policy.decision === "deny") {
+      return `${TOOL_ERROR_PREFIX} ${name}: 策略拦截: ${policy.reason || "未授权"}`;
+    }
+    if (policy.decision === "ask") {
+      return `${TOOL_ERROR_PREFIX} ${name}: 需要人工审批: ${policy.reason || "敏感操作"}`;
+    }
+    if (!this.audit) return runWithPolicy(meta, args, ctx);
+    const t0 = Date.now();
+    try {
+      const r = await runWithPolicy(meta, args, ctx);
+      const failed = typeof r === "string" && r.startsWith(TOOL_ERROR_PREFIX);
+      this.audit.append({ tool: name, args, ok: !failed, error: failed ? String(r).slice(0, 200) : null, ms: Date.now() - t0 });
+      return r;
+    } catch (e) {
+      this.audit.append({ tool: name, args, ok: false, error: e?.message || String(e), ms: Date.now() - t0 });
+      throw e;
+    }
+  }
+
+  has(name) {
+    return this.tools.has(name);
+  }
+
+  // 元数据查询 (v1.6.0 第四刀: 超时重试需要知道工具是否幂等/超时预算)
+  metaOf(name) {
+    return this.tools.get(name) || null;
+  }
+
+  list() {
+    return [...this.tools.keys()];
+  }
+
+  // ---- 元数据枚举 (供 selfmod / 追踪) ----
+  listDetailed() {
+    return [...this.tools.values()].map(toDescriptor);
+  }
+}

package/src/tools/command-guard.js

@@ -0,0 +1,112 @@
+// src/tools/command-guard.js - 命令守卫 (吸收 Hermes Agent approval 机制)
+// 三层防线:
+//   1. 用户 deny 规则 (config.security.deny, glob 风格) — 最高优先级, 即使 allow_all 也拦
+//   2. 硬黑名单 HARD_BLOCK (rm -rf /、fork bomb、写裸设备、管道到 shell 等) — allow_all 也拦
+//   3. 常规高危黑名单 DEFAULT_DENY (继承皮皮虾 P0) — allow_all 放行
+//   4. 白名单前缀 (allow_all=false 时) — 只放行已知安全命令前缀
+// 反混淆: normalizeCommand 先去引号再规范化空白, 防 `rm ""-rf` / `bash <(curl)` 引号技巧绕过
+
+// ---- 反混淆规范化: 仅用于检测, 不用于实际执行 ----
+export function normalizeCommand(cmd) {
+  let s = String(cmd || "");
+  s = s.replace(/["'`]/g, ""); // 去引号防绕过
+  s = s.replace(/\s+/g, " ").trim(); // 合并空白
+  return s;
+}
+
+// ---- 硬黑名单: allow_all 也无法放行 (破坏宿主 / 不可逆 / 远程代码落地执行) ----
+// v1.0.9: rm 类正则去掉行首/符号前缀限制 — `env rm --no-preserve-root /` 等前缀变体 (sudo/env/&&) 曾绕过
+export const HARD_BLOCK = [
+  { pattern: /rm\s+(-[a-z]*r[a-z]*\s+)*--?no-preserve-root(\s|$)/i, reason: "rm --no-preserve-root 破坏根目录" },
+  { pattern: /rm\s+(-[a-z]*r[a-z]*\s+)*\/\s*$/i, reason: "rm -rf / 类删除根目录" },
+  { pattern: /:\s*\(\s*\)\s*\{\s*:\s*\|/, reason: "fork bomb 进程炸弹" },
+  { pattern: /mkfs[.\s][^\n;]*\/dev\/(sd[a-z]|nvme[0-9])/i, reason: "格式化磁盘设备" },
+  { pattern: /dd\s+[^\n;]*of=\/dev\/(sd[a-z]|nvme[0-9])/i, reason: "dd 写裸磁盘设备" },
+  { pattern: /(curl|wget)\s+[^\s|;&]+\s*\|[\s]*(ba|z|k)?sh/i, reason: "管道下载内容到 shell 执行 (不可信代码)" },
+  { pattern: /(ba|z|k)?sh\s*<\s*\(\s*(curl|wget)/i, reason: "进程替换执行远程内容" },
+];
+
+// ---- 常规高危黑名单 (继承皮皮虾 P0: 删除/格式化/关机/强杀/强制推送等) ----
+export const DEFAULT_DENY = [
+  /delete|erase|rmdir|rd \/s|deltree/i,
+  /format\s/i, /mkfs/i, /fdisk/i, /diskpart/i, /shutdown/i,
+  /restart/i, /reboot/i, /halt/i, /poweroff/i,
+  /reg\s+delete/i, /taskkill/i, /pkill/i, /kill\s+-9/i,
+  /rm\s+-rf/i, /rm\s+-fr/i,
+  /curl|wget|Invoke-WebRequest|iwr/i,
+  /git\s+push.*--force/i, /git\s+reset.*--hard/i,
+];
+
+export const DEFAULT_ALLOW_PREFIX = [
+  "git", "npm", "npx", "yarn", "pnpm", "node", "python", "python3",
+  "ls", "dir", "pwd", "cat", "type", "echo", "head", "tail", "grep",
+  "find", "wc", "cp", "copy", "mv", "move", "mkdir", "touch", "tree",
+  "cd", "help", "ipconfig", "netstat", "tasklist", "whoami", "date", "time", "tsc",
+];
+
+// 命中拦截后附加的指引: 明确告知不要重试/改写绕过 (Hermes approval 同款约束)
+export const DENY_HINT = " 命中后不要重试或改写命令绕过 — 确需执行请让用户调整 security 配置。";
+
+// glob 风格规则 ('git push --force*') -> 正则
+export function globToRegExp(glob) {
+  let s = String(glob || "").trim();
+  if (!s) return null;
+  s = s.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+  try { return new RegExp("^" + s + "$", "i"); } catch { return null; }
+}
+
+// 统一检查入口:
+//   opts = { allowAll|allow_all, allowPrefix, denyList, deny, hardBlock }
+//   v1.0.9: 兼容 snake 配置键 allow_all (config.security.allow_all 是 snake, 原只认 camel 导致 allow_all=true 永不生效)
+//   返回 { ok: true, normalized } | { ok: false, reason, hard }
+export function checkCommand(cmd, opts = {}) {
+  const normalized = normalizeCommand(cmd);
+  if (!normalized) return { ok: false, hard: false, reason: "空命令" };
+
+  // 1. 用户 deny 规则 (最高优先级, allow_all 也拦)
+  const userDeny = (opts && opts.deny) || [];
+  for (const d of userDeny) {
+    const re = d instanceof RegExp ? d : globToRegExp(d);
+    if (re && re.test(normalized)) {
+      return { ok: false, hard: true, reason: "用户 deny 规则拦截: " + String(d).slice(0, 60) };
+    }
+  }
+
+  // 2. 硬黑名单 (allow_all 也拦)
+  const hardBlock = (opts && opts.hardBlock) || HARD_BLOCK;
+  for (const { pattern, reason } of hardBlock) {
+    if (pattern.test(normalized)) return { ok: false, hard: true, reason: "硬黑名单拦截: " + reason };
+  }
+
+  // 3. 常规高危黑名单 (allow_all 放行)
+  const deny = (opts && opts.denyList) || DEFAULT_DENY;
+  for (const re of deny) {
+    if (re.test(normalized)) return { ok: false, hard: false, reason: "命令被拒绝: 命中高危黑名单 (delete/format/shutdown/curl等)" };
+  }
+
+  // 4. 白名单前缀 (allow_all=false 时)
+  const allowAll = !!(opts && (opts.allowAll || opts.allow_all));
+  if (!allowAll) {
+    const allowPrefix = (opts && opts.allowPrefix) || DEFAULT_ALLOW_PREFIX;
+    const first = normalized.split(/[\s|&;>]+/)[0];
+    const hit = allowPrefix.some((a) => first.toLowerCase().replace(/\.exe$/i, "") === a.toLowerCase());
+    if (!hit) {
+      return { ok: false, hard: false, reason: `命令不在白名单: ${first}. 允许: git/npm/node/python/cat/cp/mkdir 等, 或设置 security.allow_all.` };
+    }
+  }
+
+  return { ok: true, normalized };
+}
+
+// 兼容导出 (旧 isDeniedCommand 语义: 只查常规高危 + 硬黑名单 + 用户 deny, 不看白名单)
+export function isDeniedCommand(cmd, options) {
+  return !checkCommand(cmd, { ...(options || {}), allowAll: true }).ok;
+}
+
+// 兼容导出 (旧 isAllowedCommand 语义: allow_all 直接放行, 否则查前缀白名单; 不查 deny)
+export function isAllowedCommand(cmd, options) {
+  if (options && (options.allowAll || options.allow_all)) return true;
+  const allowPrefix = (options && options.allowPrefix) || DEFAULT_ALLOW_PREFIX;
+  const first = String(cmd || "").trim().split(/[\s|&;>]+/)[0];
+  return allowPrefix.some((a) => first.toLowerCase().replace(/\.exe$/i, "") === a.toLowerCase());
+}

package/src/tools/custom.js

@@ -0,0 +1,47 @@
+// src/tools/custom.js - 用户自定义工具注册
+// 目标: 用户不改源码即可扩展 agent 能力。
+// 扫描 <customDir>/*.cjs (或 .js), 每个文件导出工具定义 { name, description, parameters, execute },
+// 用 ToolCatalog.register 注册, 与内置工具同权 (可被 LLM 调用、可 enable/disable)。
+// 示例 (custom-tools/hello.cjs):
+//   module.exports = {
+//     name: "hello",
+//     description: "返回问候语。",
+//     parameters: { type: "object", properties: { name: { type: "string" } }, required: [] },
+//     execute: async (args) => `你好, ${args.name || "世界"}!`,
+//   };
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { info, warn } from "../utils/logger.js";
+
+function isToolDef(v) {
+  return v && typeof v === "object" && typeof v.name === "string" && v.name && typeof v.execute === "function";
+}
+
+// 同步注册 (构造函数内可用): 用 createRequire 加载 CommonJS 工具文件
+export function registerCustomTools(catalog, customDir) {
+  if (!customDir || !fs.existsSync(customDir)) return 0;
+  const require = createRequire(import.meta.url);
+  let files = [];
+  try { files = fs.readdirSync(customDir); } catch { return 0; }
+  const candidates = files.filter((f) => f.endsWith(".cjs") || f.endsWith(".js")).sort();
+
+  let count = 0;
+  for (const f of candidates) {
+    const full = path.join(customDir, f);
+    try {
+      const mod = require(full);
+      const def = mod && mod.default ? mod.default : mod;
+      if (!isToolDef(def)) {
+        warn(`[custom-tools] ${f} 需导出 { name, description, parameters, execute }, 跳过`);
+        continue;
+      }
+      catalog.register(def);
+      count += 1;
+    } catch (e) {
+      warn(`[custom-tools] 加载 ${f} 失败: ${e.message}`);
+    }
+  }
+  if (count) info(`[custom-tools] 已注册 ${count} 个自定义工具`);
+  return count;
+}

package/src/tools/delegate.js

@@ -0,0 +1,297 @@
+// src/tools/delegate.js - 多 agent 自主协作工具 (spawn_agent)
+// 让 agent 在工具循环里自主决定 spawn 子 agent 分工 (ANS 神经元中枢的最小实现):
+//   - 主 agent 分析任务 → 认为需要专门角色/并行/隔离 → 调 spawn_agent
+//   - 子 agent: 独立会话目录 (隔离) + 共享全局经验库 (ANS 全局记忆)
+//   - 子 agent 复用懒建军团 (agent._legion), 不重复 spawn 进程
+// v2 (2026-08-17): 吸收 Anthropic 多智能体研究洞察
+//   - 并行任务: tasks 数组并行派发多个子 agent (专才 + 并行化)
+//   - 差异化上下文: perspectives 注入每个子 agent 专属视角, 对抗同质失败
+//   - 仲裁聚合: arbitrate 时主 agent LLM 综合各子结果做最终裁决
+// v3 (2026-08-17): 吸收 Superpowers SDD 子代理驱动开发
+//   - review 循环: 实施者 -> 只读审查者 -> (发现问题 -> 修复 -> 复审) * fixRounds -> 熔断停放
+//   - 审查者只读 (PPX_AGENT_READONLY), 实施者修复复用原进程 (上下文完整)
+//   - 账本 ledger: 全程记录审查/修复轮次, 熔断时未决发现交主 agent 裁定
+import path from "node:path";
+import { Legion } from "../orchestrator/legion.js";
+
+const DELEGATE_TIMEOUT_MS = 120000; // 子任务最长等待 (防卡死主 agent 工具循环)
+
+// ---- SDD review 循环: 纯函数 (可测) ----
+
+// 严重级标签映射 (v1.0.8): 内部表示 Critical/Important/Minor, 展示用中文, 解析兼容中英
+export function severityLabel(s) {
+  if (s === "Critical" || s === "严重" || s === "P0") return "严重";
+  if (s === "Important" || s === "重要" || s === "P1") return "重要";
+  return "次要";
+}
+function severityOf(token) {
+  if (token === "严重" || token === "P0") return "Critical";
+  if (token === "重要" || token === "P1") return "Important";
+  if (token === "Critical" || token === "Important") return token; // 英文 token 原样映射
+  return "Minor";
+}
+
+// 解析审查者输出 -> 发现列表 [{ severity, finding }]
+// 期望格式: 每行 "[严重|重要|次要] 描述" (兼容英文 Critical/Important/Minor), 无发现为 "(无发现)"
+export function parseReviewFindings(text) {
+  if (!text) return [];
+  const out = [];
+  const re = /\[(严重|重要|次要|Critical|Important|Minor)\]\s*([^\n]+)/g;
+  let m;
+  while ((m = re.exec(String(text)))) {
+    const finding = m[2].trim();
+    if (finding) out.push({ severity: severityOf(m[1]), finding });
+  }
+  return out;
+}
+
+// 是否需要触发修复: 有 Critical/Important
+export function needsFix(findings) {
+  return findings.some((f) => f.severity === "Critical" || f.severity === "Important");
+}
+
+// 组装审查者提示词 (只读审查契约)
+export function buildReviewPrompt(workDesc, judge, perspective) {
+  const p = perspective ? `\n【审查视角】${perspective}` : "";
+  return `你是只读审查者。审查下面"产出"中实施者的结果, 找出问题。严格遵守: 只读审查, 禁止修改/写入任何文件, 禁止执行命令。
+
+【任务要求】${workDesc}
+【审查准则】${judge || "对照任务要求检查: 功能正确性 / 需求满足度 / 边界情况 / 明显风险"}${p}
+
+【产出】
+${"<产出内容>"}
+
+输出发现清单, 每行一条, 格式 "[严重级] 描述", 严重级用:
+- [严重] 功能错误 / 需求未满足 / 会导致失败
+- [重要] 质量缺陷 / 边界情况 / 明显风险
+- [次要] 小改进 / 风格
+没有任何问题时只输出一行 "(无发现)"。不要输出其他内容。`;
+}
+
+// 修复提示词: 把未决发现交给实施者修复
+export function buildFixPrompt(task, findings) {
+  const open = findings.filter((f) => f.severity === "Critical" || f.severity === "Important");
+  const lines = open.map((f) => `[${severityLabel(f.severity)}] ${f.finding}`).join("\n");
+  return `上一轮产出存在以下 ${open.length} 项问题, 请逐一修复 (只解决这些问题, 不要引入新问题):\n${lines}\n\n原始任务: ${task}`;
+}
+
+// ---- 纯函数: 组装多子结果 + 视角 (仲裁输入) ----
+export function buildArbitrationInput(tasks, results, perspectives) {
+  return tasks.map((t, i) => {
+    const p = perspectives?.[i] ? ` (视角: ${perspectives[i]})` : "";
+    return `【子任务${i + 1}${p}】${t}\n【结果${i + 1}】${String(results[i] || "").slice(0, 2000)}`;
+  }).join("\n\n");
+}
+
+// 主 agent 聚合评审 (仲裁者模式): 综合各子结果, 输出最终裁决
+// 无 LLM 或评审失败时退化为简单拼接 (不阻塞)
+export async function arbitrate(agent, tasks, results, perspectives, judge) {
+  const input = buildArbitrationInput(tasks, results, perspectives);
+  const system = "你是多 agent 结果的仲裁者。综合各方结果, 识别分歧与共识, 给出一个整合后的最终答案。直接输出最终答案, 不要复述过程。";
+  const user = input + (judge ? `\n\n【评审要求】${judge}` : "");
+  try {
+    const r = await agent.llm.chat([
+      { role: "system", content: system },
+      { role: "user", content: user.slice(0, 6000) },
+    ]);
+    const text = String(r?.content || "").trim();
+    return text || `(仲裁无输出)\n\n${input}`;
+  } catch (e) {
+    return `(仲裁失败, 直出各方结果)\n\n${input}`;
+  }
+}
+
+// 带超时等待 (防子 agent 卡死) — 定时器必须清理, 否则快速 resolve 后仍挂起 120s 阻止进程退出
+function withTimeout(p, ms, label) {
+  let timer;
+  const timeout = new Promise((_, rej) => {
+    timer = setTimeout(() => rej(new Error(`${label}超时 (${ms / 1000}s)`)), ms);
+  });
+  return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
+}
+
+// ---- SDD review 循环: 实施 -> 只读审查 -> (修复 -> 复审) * N -> 熔断 ----
+// 返回: 通过时 "✅ 审查通过..." + 产出; 熔断时 "⚠️ 未决发现停放..." + 产出
+// namePrefix: 多任务 review 时传入 `${role}_${ts}_${i}`, 保证每对 agent 名唯一
+async function runReviewLoop({ agent, L, task, perspective, role, judge, fixRounds, namePrefix = null }) {
+  const ts = Date.now().toString(36);
+  const implName = namePrefix ? `${namePrefix}_impl` : `${role}_impl_${ts}`;
+  const revName = namePrefix ? `${namePrefix}_rev` : `${role}_rev_${ts}`;
+  const mkOpts = (n) => ({ dataDir: path.join(agent.dataDir, "legion", n), globalDataDir: agent.globalDataDir });
+  L.spawnAgent(implName, mkOpts(implName));
+  // 审查者只读: PPX_AGENT_READONLY=1 时 worker 禁用全部修改/执行工具
+  L.spawnAgent(revName, { ...mkOpts(revName), env: { PPX_AGENT_READONLY: "1" } });
+  if (agent.lifecycle) agent.lifecycle.reproduce(2);
+
+  const max = (() => { // v1.0.8: fix_rounds=0 应能设 0 (原 `|| 3` 把 0 变 3)
+    const parsed = Number(fixRounds);
+    return Number.isFinite(parsed) ? Math.min(Math.max(parsed, 0), 5) : 3;
+  })(); // 熔断上限 (Superpowers 5 轮, 默认 3 控成本; 0 = 不修复直接停放)
+  const ledger = [];
+  let findings = [];
+  let result = "";
+
+  // 1. 实施
+  try {
+    const r = await withTimeout(L.send(implName, { type: "chat", message: task, perspective }, { timeout: DELEGATE_TIMEOUT_MS + 5000 }), DELEGATE_TIMEOUT_MS, "实施");
+    result = String(r?.reply || "").trim() || "(实施者无回复)";
+  } catch (e) {
+    return `[工具错误] spawn_agent(review): 实施失败: ${e.message}`;
+  }
+  ledger.push({ round: 0, step: "implement" });
+
+  // 2. 审查 + 修复循环
+  let round = 0;
+  while (true) {
+    const reviewText = await (async () => {
+      try {
+        const r = await withTimeout(L.send(revName, { type: "chat", message: buildReviewPrompt(task, judge, perspective) + `\n\n【产出】\n${result.slice(0, 6000)}`, perspective }, { timeout: DELEGATE_TIMEOUT_MS + 5000 }), DELEGATE_TIMEOUT_MS, "审查");
+        return String(r?.reply || "");
+      } catch (e) {
+        return `[Critical] 审查者不可用: ${e.message}`;
+      }
+    })();
+    findings = parseReviewFindings(reviewText);
+    ledger.push({ round, step: "review", findings });
+    if (!needsFix(findings)) break;   // 通过
+    if (round >= max) break;          // 熔断
+    round++;
+    try {
+      const r = await withTimeout(L.send(implName, { type: "chat", message: buildFixPrompt(task, findings), perspective }, { timeout: DELEGATE_TIMEOUT_MS + 5000 }), DELEGATE_TIMEOUT_MS, `修复第${round}轮`);
+      result = String(r?.reply || "").trim() || "(实施者无回复)";
+    } catch (e) {
+      ledger.push({ round, step: "fix", error: e.message });
+      break;
+    }
+    ledger.push({ round, step: "fix" });
+  }
+
+  // 3. 汇总: 通过 or 熔断停放 (账本交主 agent 裁定)
+  const open = findings.filter((f) => f.severity === "Critical" || f.severity === "Important");
+  if (open.length) {
+    return `⚠️ 审查未通过: 达到修复上限 (${max} 轮), 以下 ${open.length} 项未决发现已停放, 请主 agent 裁定是否接受当前产出:\n`
+      + open.map((f) => `- [${severityLabel(f.severity)}] ${f.finding}`).join("\n")
+      + `\n\n当前产出:\n${result}`;
+  }
+  const summary = findings.length
+    ? findings.map((f) => `[${severityLabel(f.severity)}]`).join(" ")
+    : "无";
+  return `✅ 审查通过 (审查发现: ${summary})\n\n${result}`;
+}
+
+export function registerDelegateTools(catalog, _opts = {}) {
+  catalog.register({
+    name: "spawn_agent",
+    description: "派生子 agent 处理子任务并等待结果。适合需要专门角色、并行、或隔离执行的任务 (如数据分析、代码审查、多角度论证)。子 agent 共享全局经验库。支持: 单个 task; 或 tasks 数组并行派发多个子 agent + perspectives 差异化视角; arbitrate=true 时主 agent 仲裁聚合各方结果; review=true 时走 SDD 审查循环: 实施者干活 -> 只读审查者挑问题 -> 修复 -> 复审, 达上限熔断停放交主 agent 裁定 (单任务直接审查; 多任务每个子任务独立一对实施+审查, 可配 arbitrate 聚合)。",
+    parameters: {
+      type: "object",
+      properties: {
+        task: { type: "string", description: "单个子任务描述 (清晰完整, 含上下文); 与 tasks 二选一" },
+        tasks: { type: "array", items: { type: "string" }, description: "并行子任务列表 (每个子 agent 一个), 适合多角度论证/并行处理; 与 task 二选一" },
+        perspectives: { type: "array", items: { type: "string" }, description: "差异化视角列表, 与 tasks 一一对应, 注入每个子 agent 专属视角 (对抗同质失败), 可缺省" },
+        role: { type: "string", description: "子 agent 角色名 (如 数据分析师/代码审查员), 默认 helper" },
+        arbitrate: { type: "boolean", description: "是否由主 agent 仲裁聚合所有子结果 (并行/多任务 review 时推荐), 默认 false 直接返回拼接结果" },
+        judge: { type: "string", description: "仲裁评审指令 (arbitrate=true 时生效, 如 找出最可靠结论/合并去重); review=true 时为审查准则, 可缺省" },
+        review: { type: "boolean", description: "SDD 审查循环: 实施者 -> 只读审查者 -> 发现问题自动修复复审, 达上限熔断, 默认 false。单 task 与多 tasks 均支持" },
+        fix_rounds: { type: "number", description: "审查循环最大修复轮数 (review=true 时生效, 默认 3, 上限 5)" },
+      },
+    },
+    execute: async (args, ctx) => {
+      const agent = ctx?.agent;
+      if (!agent) return "[工具错误] spawn_agent: 无 agent 上下文";
+      // 先校验参数, 再校验环境 (输入校验优先)
+      let tasks = null;
+      if (Array.isArray(args.tasks) && args.tasks.length) {
+        tasks = args.tasks.map((t) => String(t).slice(0, 4000));
+      } else if (args.task) {
+        tasks = [String(args.task).slice(0, 4000)];
+      }
+      if (!tasks) return "[工具错误] spawn_agent: 需要 task 或 tasks";
+      if (!agent.llm) return "[工具错误] spawn_agent: 主 agent 未配置模型, 无法委派";
+      // 懒建军团 (复用已有, 避免重复 spawn 进程)
+      let L = agent._legion;
+      if (!L) { L = new Legion(); agent._legion = L; }
+      const role = String(args.role || "helper").replace(/[^\w-]/g, "_").slice(0, 24);
+
+      const perspectives = Array.isArray(args.perspectives) ? args.perspectives.map((p) => String(p)).slice(0, tasks.length) : [];
+
+      try {
+        // SDD review 循环: 实施 -> 审查 -> 修复 -> 熔断
+        // 单任务: 直接跑; 多任务: 每个任务独立一对 (实施者+只读审查者), 并行跑, 可仲裁聚合
+        if (args.review) {
+          const prefix = `${role}_${Date.now().toString(36)}`;
+          if (tasks.length === 1) {
+            return await runReviewLoop({
+              agent, L, task: tasks[0],
+              perspective: perspectives[0],
+              role, judge: args.judge,
+              fixRounds: args.fix_rounds,
+              namePrefix: `${prefix}_0`,
+            });
+          }
+          // 多任务: 并行各任务 review, 各自独立 (agent 名唯一, 不冲突)
+          const settled = await Promise.all(tasks.map(async (task, i) => {
+            try {
+              return await runReviewLoop({
+                agent, L, task,
+                perspective: perspectives[i],
+                role, judge: args.judge,
+                fixRounds: args.fix_rounds,
+                namePrefix: `${prefix}_${i}`,
+              });
+            } catch (e) {
+              return `[子任务${i + 1} review 失败] ${e.message}`;
+            }
+          }));
+          if (args.arbitrate) {
+            return await arbitrate(agent, tasks, settled, perspectives, args.judge);
+          }
+          return tasks.map((t, i) => {
+            const p = perspectives?.[i] ? ` (${perspectives[i]})` : "";
+            return `【子任务${i + 1}${p}】${t}\n${settled[i]}`;
+          }).join("\n\n");
+        }
+        // 并行 spawn 子 agent: 每个独立数据目录 + 独立视角
+        const names = tasks.map((_, i) => `${role}_${i}_${Date.now().toString(36)}`);
+        for (const n of names) {
+          L.spawnAgent(n, {
+            dataDir: path.join(agent.dataDir, "legion", n),
+            globalDataDir: agent.globalDataDir,
+          });
+        }
+        // 生命周期: 繁衍计数 (ANS: reproducing)
+        if (agent.lifecycle) agent.lifecycle.reproduce(names.length);
+
+        // 并行派发, 全部等结果 (各自独立超时)
+        const settled = await Promise.all(tasks.map(async (task, i) => {
+          try {
+            const reply = await withTimeout(
+              L.send(names[i], { type: "chat", message: task, perspective: perspectives[i] }, { timeout: DELEGATE_TIMEOUT_MS + 5000 }),
+              DELEGATE_TIMEOUT_MS,
+              `子任务${i + 1}`
+            );
+            return { ok: true, reply: reply.reply || "(子 agent 无回复)" };
+          } catch (e) {
+            return { ok: false, reply: `[子任务${i + 1}失败] ${e.message}` };
+          }
+        }));
+        const results = settled.map((s) => s.reply);
+
+        // 单任务: 保持旧行为, 直接返回子 agent 回复
+        if (tasks.length === 1) return results[0];
+
+        // 多任务: 有 arbitrate 走主 agent 仲裁聚合, 否则拼接各方结果
+        if (args.arbitrate) {
+          const out = await arbitrate(agent, tasks, results, perspectives, args.judge);
+          return out;
+        }
+        return tasks.map((t, i) => {
+          const p = perspectives?.[i] ? ` (${perspectives[i]})` : "";
+          return `【子任务${i + 1}${p}】${t}\n${results[i]}`;
+        }).join("\n\n");
+      } catch (e) {
+        return `[工具错误] spawn_agent: ${e.message}`;
+      }
+    },
+  });
+}