ppxans-harness 2.6.0 → 3.2.1

package/src/orchestrator/dag.js

@@ -1,83 +1,90 @@
-// src/orchestrator/dag.js - DAG 任务编排 (军团从 broadcast/dispatch 升级为任务图)
-// 纯函数零依赖: topoLevels 拓扑分层 + runDag 分层并行执行 + 依赖结果数据流
-// graph.nodes = [{ id, task, dependsOn?: [id], agent?: name }]
-
-// 拓扑分层 (Kahn 算法): 返回 [ [同层可并行的节点id], ... ], 检测环
-// v1.0.8: 校验重复 id / 依赖不存在 (原实现静默丢弃不存在的依赖, 重复 id 误报成环)
-export function topoLevels(nodes) {
-  const ids = new Set();
-  for (const n of nodes) {
-    if (!n || !n.id) throw new Error("DAG 节点缺 id");
-    if (ids.has(n.id)) throw new Error(`DAG 节点 id 重复: ${n.id}`);
-    ids.add(n.id);
-  }
-  const indeg = new Map();
-  const children = new Map();
-  for (const n of nodes) {
-    const deps = n.dependsOn || [];
-    for (const d of deps) {
-      if (!ids.has(d)) throw new Error(`DAG 节点 ${n.id} 依赖不存在的节点: ${d}`);
-    }
-    indeg.set(n.id, deps.length);
-    for (const d of deps) {
-      if (!children.has(d)) children.set(d, []);
-      children.get(d).push(n.id);
-    }
-  }
-  const levels = [];
-  let frontier = nodes.filter((n) => indeg.get(n.id) === 0).map((n) => n.id);
-  const seen = new Set();
-  while (frontier.length) {
-    levels.push(frontier);
-    const next = [];
-    for (const id of frontier) {
-      seen.add(id);
-      for (const c of children.get(id) || []) {
-        indeg.set(c, indeg.get(c) - 1);
-        if (indeg.get(c) === 0) next.push(c);
-      }
-    }
-    frontier = next;
-  }
-  if (seen.size < nodes.length) {
-    const cyclic = [...ids].filter((id) => !seen.has(id)).join(",");
-    throw new Error("DAG 存在环, 无法编排: " + cyclic);
-  }
-  return levels;
-}
-
-// 执行 DAG: 每层节点并行, 上游结果作为 deps 传给下游 executor。
-// executor(id, node, deps) => Promise<result>, deps = { 依赖id: 结果 }
-// concurrency: 每层并发的上限 (默认 0 = 不设限, 兼容旧调用; Legion 会传入自己的 maxConcurrent)
-export async function runDag(graph, executor, { concurrency = 0 } = {}) {
-  const byId = new Map(graph.nodes.map((n) => [n.id, n]));
-  const levels = topoLevels(graph.nodes);
-  const results = {};
-  const order = [];
-  const cap = concurrency > 0 ? concurrency : Infinity;
-  for (const level of levels) {
-    // 有界并发: 层内若超出 cap, 用轮询槽位的方式逐个交给并行执行, 避免一次性 Promise.all 打爆子进程
-    let idx = 0;
-    const runOne = async (id) => {
-      const node = byId.get(id);
-      const deps = {};
-      for (const d of node.dependsOn || []) deps[d] = results[d];
-      results[id] = await executor(id, node, deps);
-      order.push(id);
-    };
-    await new Promise((resolveAll) => {
-      let active = 0;
-      let doneCount = 0;
-      const tick = () => {
-        while (active < cap && idx < level.length) {
-          const id = level[idx++];
-          active++;
-          runOne(id).finally(() => { active--; doneCount++; tick(); });
-        }
-        if (doneCount >= level.length) resolveAll();
-      };
-      tick();
-    });
-  }
-  return { results, order };
-}
+// src/orchestrator/dag.js - DAG 任务编排 (军团从 broadcast/dispatch 升级为任务图)
+// 纯函数零依赖: topoLevels 拓扑分层 + runDag 分层并行执行 + 依赖结果数据流
+// graph.nodes = [{ id, task, dependsOn?: [id], agent?: name }]
+
+// 拓扑分层 (Kahn 算法): 返回 [ [同层可并行的节点id], ... ], 检测环
+// v1.0.8: 校验重复 id / 依赖不存在 (原实现静默丢弃不存在的依赖, 重复 id 误报成环)
+export function topoLevels(nodes) {
+  const ids = new Set();
+  for (const n of nodes) {
+    if (!n || !n.id) throw new Error("DAG 节点缺 id");
+    if (ids.has(n.id)) throw new Error(`DAG 节点 id 重复: ${n.id}`);
+    ids.add(n.id);
+  }
+  const indeg = new Map();
+  const children = new Map();
+  for (const n of nodes) {
+    const deps = n.dependsOn || [];
+    for (const d of deps) {
+      if (!ids.has(d)) throw new Error(`DAG 节点 ${n.id} 依赖不存在的节点: ${d}`);
+    }
+    indeg.set(n.id, deps.length);
+    for (const d of deps) {
+      if (!children.has(d)) children.set(d, []);
+      children.get(d).push(n.id);
+    }
+  }
+  const levels = [];
+  let frontier = nodes.filter((n) => indeg.get(n.id) === 0).map((n) => n.id);
+  const seen = new Set();
+  while (frontier.length) {
+    levels.push(frontier);
+    const next = [];
+    for (const id of frontier) {
+      seen.add(id);
+      for (const c of children.get(id) || []) {
+        indeg.set(c, indeg.get(c) - 1);
+        if (indeg.get(c) === 0) next.push(c);
+      }
+    }
+    frontier = next;
+  }
+  if (seen.size < nodes.length) {
+    const cyclic = [...ids].filter((id) => !seen.has(id)).join(",");
+    throw new Error("DAG 存在环, 无法编排: " + cyclic);
+  }
+  return levels;
+}
+
+// 执行 DAG: 每层节点并行, 上游结果作为 deps 传给下游 executor。
+// executor(id, node, deps) => Promise<result>, deps = { 依赖id: 结果 }
+// concurrency: 每层并发的上限 (默认 0 = 不设限, 兼容旧调用; Legion 会传入自己的 maxConcurrent)
+export async function runDag(graph, executor, { concurrency = 0 } = {}) {
+  const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+  const levels = topoLevels(graph.nodes);
+  const results = {};
+  const order = [];
+  const cap = concurrency > 0 ? concurrency : Infinity;
+  for (const level of levels) {
+    // 有界并发: 层内若超出 cap, 用轮询槽位的方式逐个交给并行执行, 避免一次性 Promise.all 打爆子进程
+    let idx = 0;
+    const runOne = async (id) => {
+      const node = byId.get(id);
+      const deps = {};
+      for (const d of node.dependsOn || []) deps[d] = results[d];
+      // 2026-09-18 修复 (P1): executor 抛错原样冒泡, runOne().finally() 链上无人接住
+      //   → unhandled rejection → Node 进程直接崩溃 (任一 agent 超时/失败即炸整个编排)。
+      //   现捕获后把错误文本作为该节点结果, 下游节点可感知失败, 编排整体继续。
+      try {
+        results[id] = await executor(id, node, deps);
+      } catch (e) {
+        results[id] = `[执行失败] ${e && e.message ? e.message : e}`;
+      }
+      order.push(id);
+    };
+    await new Promise((resolveAll) => {
+      let active = 0;
+      let doneCount = 0;
+      const tick = () => {
+        while (active < cap && idx < level.length) {
+          const id = level[idx++];
+          active++;
+          runOne(id).finally(() => { active--; doneCount++; tick(); });
+        }
+        if (doneCount >= level.length) resolveAll();
+      };
+      tick();
+    });
+  }
+  return { results, order };
+}

package/src/orchestrator/experts.js

@@ -0,0 +1,76 @@
+// src/orchestrator/experts.js - 专家名册 (2026-10-02)
+// 对标 MetaGPT/ChatDev 的固化分工: 代码交给代码专家, 设计交给设计专家。
+// 每个专家 = 中文名 (角色) + 专属视角 (perspective, 注入 worker 对抗同质失败) + 可选只读约束。
+// spawn_agent.expert / experts 参数消费本名册; 视角只是提示不是牢笼, worker 仍有全部上下文能力。
+
+export const EXPERTS = {
+  code: {
+    name: "代码专家",
+    perspective:
+      "你是代码专家。聚焦实现正确性: 边界条件/异常路径/并发风险/最小改动原则。给出具体到文件与函数级建议, 不空谈架构。",
+  },
+  architect: {
+    name: "架构专家",
+    perspective:
+      "你是架构专家。聚焦模块边界/依赖方向/扩展成本/复杂度风险。先看全局再下结论, 明确说哪些不该做。",
+  },
+  review: {
+    name: "代码审查专家",
+    perspective:
+      "你是代码审查专家。只报告不修改。按严重度分级 (Critical/Important/Suggestion) 输出问题清单, 每条给出位置与理由。",
+    readonly: true,
+  },
+  test: {
+    name: "测试专家",
+    perspective:
+      "你是测试专家。聚焦边界用例/异常路径/回归风险。给出可直接落地的测试清单, 标注优先级。",
+  },
+  security: {
+    name: "安全专家",
+    perspective:
+      "你是安全专家。只读审查。聚焦注入/密钥泄露/权限边界/数据暴露面/危险命令, 按风险等级输出。",
+    readonly: true,
+  },
+  design: {
+    name: "设计专家",
+    perspective:
+      "你是设计专家。聚焦用户体验/信息架构/交互一致性/中文向导友好度。给具体可执行的改进项, 不给空洞美学口号。",
+  },
+  docs: {
+    name: "文档专家",
+    perspective:
+      "你是文档专家。聚焦准确性/完整性/示例可跑性/术语一致。逐条指出文档与实际行为的偏差。",
+  },
+  data: {
+    name: "数据专家",
+    perspective:
+      "你是数据专家。聚焦数据质量/口径一致性/统计方法合理性。结论必须带数据依据, 说不确定就明说。",
+  },
+  product: {
+    name: "产品专家",
+    perspective:
+      "你是产品专家。聚焦用户价值/优先级/MVP 边界/需求澄清。明确回答: 为谁解决什么问题, 什么先不做。",
+  },
+};
+
+// 解析专家: 支持英文 id (code) / 中文名 (代码专家, 模糊包含匹配), 不区分大小写; 未命中返回 null
+export function resolveExpert(key) {
+  if (!key) return null;
+  const k = String(key).trim();
+  if (!k) return null;
+  const lower = k.toLowerCase();
+  // 1. 精确 id
+  if (EXPERTS[lower]) return EXPERTS[lower];
+  // 2. 中文名/别名模糊匹配 (专家名或 id 被查询串包含)
+  for (const [id, e] of Object.entries(EXPERTS)) {
+    if (lower.includes(id) || k.includes(e.name) || e.name.includes(k)) return e;
+  }
+  return null;
+}
+
+// 名册摘要 (工具描述/错误提示用)
+export function listExperts() {
+  return Object.entries(EXPERTS)
+    .map(([id, e]) => `${id}(${e.name}${e.readonly ? "/只读" : ""})`)
+    .join("、");
+}

package/src/orchestrator/index.js

@@ -1,2 +1,2 @@
-// src/orchestrator/index.js - 军团统一出口
+// src/orchestrator/index.js - 军团统一出口
 export { Legion } from "./legion.js";

package/src/orchestrator/legion.js

@@ -1,188 +1,180 @@
-// src/orchestrator/legion.js - Agent 军团编排器
-// 管理多个独立 agent 子进程, 支持并行派发任务、按角色分工
-import { spawn } from "node:child_process";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { EventEmitter } from "node:events";
-import { info, warn, error } from "../utils/logger.js";
-import { runDag } from "./dag.js";
-
-const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
-const WORKER = path.join(ROOT, "src", "orchestrator", "agent-worker.js");
-
-export class Legion extends EventEmitter {
-  constructor({ workerPath = WORKER, nodeBin = process.execPath, maxConcurrent = 8 } = {}) {
-    super();
-    this.workerPath = workerPath;
-    this.nodeBin = nodeBin;
-    this.maxConcurrent = maxConcurrent; // 军团整体并发上限: 防止大 DAG/广播瞬间 spawn 海量子进程
-    this.agents = new Map(); // { name: { proc, pending: Map<id,{resolve,reject}>, counter } }
-  }
-
-  // 有界并发执行器: 以固定并发度跑一批 async 任务, 超出上限的排队 (背压而非一次性 Promise.all)
-  // 这是 broadcast/runDag 层共享的背压口, 避免"并发无数控、大输入一次性打爆子进程数"
-  async _mapBounded(items, fn, { concurrency = this.maxConcurrent } = {}) {
-    const results = new Array(items.length);
-    let idx = 0;
-    const workers = Array.from({ length: Math.max(1, Math.min(concurrency, items.length)) });
-    await Promise.all(workers.map(async () => {
-      while (idx < items.length) {
-        const i = idx++;
-        results[i] = await fn(items[i], i);
-      }
-    }));
-    return results;
-  }
-
-  // 创建一个 agent 子进程
-  spawnAgent(name, { dataDir, globalDataDir, env = {} } = {}) {
-    if (this.agents.has(name)) return this.agents.get(name);
-    const env2 = { ...process.env, ...env };
-    if (dataDir) env2.PPX_AGENT_DATA_DIR = dataDir;
-    // 全局共享目录: 跨 agent 共享经验库 (ANS 全局记忆)
-    if (globalDataDir) env2.PPX_AGENT_GLOBAL_DATA_DIR = globalDataDir;
-    const proc = spawn(this.nodeBin, [this.workerPath], {
-      cwd: ROOT,
-      env: env2,
-      stdio: ["pipe", "pipe", "inherit"],
-    });
-    const entry = { proc, pending: new Map(), counter: 0 };
-    this.agents.set(name, entry);
-
-    proc.stdout.setEncoding("utf8");
-    let buf = "";
-    proc.stdout.on("data", (chunk) => {
-      buf += chunk;
-      let idx;
-      while ((idx = buf.indexOf("\n")) >= 0) {
-        const line = buf.slice(0, idx).trim();
-        buf = buf.slice(idx + 1);
-        if (!line) continue;
-        try {
-          const msg = JSON.parse(line);
-          // step 中间事件: 触发 onProgress 回调, 不消费 pending (等最终 reply)
-          if (msg.type === "step" && msg.id && entry.pending.has(msg.id)) {
-            const p = entry.pending.get(msg.id);
-            if (p && p.onProgress) { try { p.onProgress(msg); } catch {} }
-            continue;
-          }
-          if (msg.id && entry.pending.has(msg.id)) {
-            const { resolve, reject } = entry.pending.get(msg.id);
-            entry.pending.delete(msg.id);
-            if (msg.type === "error") reject(new Error(msg.error));
-            else resolve(msg);
-          }
-        } catch {}
-      }
-    });
-    proc.on("error", (err) => {
-      // v1.0.8: spawn 失败 (node bin 不存在等) 兜底, 拒绝所有 pending, 防永久挂起
-      error(`agent[${name}] 启动失败: ${err.message}`);
-      for (const [, { reject }] of entry.pending) reject(new Error(`agent ${name} 启动失败`));
-      entry.pending.clear();
-      this.agents.delete(name);
-    });
-    proc.on("exit", (code) => {
-      info(`agent[${name}] 退出 code=${code}`);
-      // 拒绝所有 pending
-      for (const [, { reject }] of entry.pending) reject(new Error(`agent ${name} 已退出`));
-      entry.pending.clear();
-      this.agents.delete(name);
-      this.emit("exit", name, code);
-    });
-    info(`agent[${name}] 已启动 (pid=${proc.pid})`);
-    return entry;
-  }
-
-  // 向某 agent 发消息, 返回 Promise (onProgress 可选: 接收 step 中间事件)
-  // v1.0.8: 超时兜底 (默认 30s), worker 卡死/异常不导致 pending 永久挂起
-  send(name, msg, { onProgress, timeout = 30000 } = {}) {
-    const entry = this.agents.get(name);
-    if (!entry || entry.proc.exitCode !== null) {
-      return Promise.reject(new Error(`agent ${name} 未运行`));
-    }
-    const id = ++entry.counter;
-    return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        entry.pending.delete(id);
-        reject(new Error(`agent ${name} 请求超时 (${timeout}ms)`));
-      }, timeout);
-      entry.pending.set(id, {
-        resolve: (v) => { clearTimeout(timer); resolve(v); },
-        reject: (e) => { clearTimeout(timer); reject(e); },
-        onProgress,
-      });
-      try {
-        entry.proc.stdin.write(JSON.stringify({ id, ...msg }) + "\n");
-      } catch (e) {
-        clearTimeout(timer);
-        entry.pending.delete(id);
-        reject(new Error(`agent ${name} 写入失败: ${e.message}`));
-      }
-    });
-  }
-
-  // 并行派发: 同一任务广播给多个 agent, 最快返回
-  async broadcast(type, message, { timeout = 30000 } = {}) {
-    const names = [...this.agents.keys()];
-    if (!names.length) throw new Error("军团为空, 先 spawnAgent");
-    const results = await this._mapBounded(
-      names,
-      (n) => this.send(n, { type, message }, { timeout }).catch((e) => ({ type: "error", error: e.message }))
-    );
-    return names.map((n, i) => ({ agent: n, ...results[i] }));
-  }
-
-  // 按角色分工: 把任务列表分给不同 agent
-  // ⚠️ 实验性 API: 生产代码无内置消费方 (详见 docs/ARCHITECTURE.md)。仅供在交互场景/测试里手动调用。
-  // 逐条串行派发, 吞吐低但稳定; 若需高并发的角色分工, 优先用 runDag。
-  async dispatch(type, tasks) {
-    const names = [...this.agents.keys()];
-    const results = [];
-    for (let i = 0; i < tasks.length; i++) {
-      const name = names[i % names.length];
-      try {
-        const r = await this.send(name, { type, message: tasks[i] });
-        results.push({ agent: name, task: tasks[i], ...r });
-      } catch (e) {
-        results.push({ agent: name, task: tasks[i], type: "error", error: e.message });
-      }
-    }
-    return results;
-  }
-
-  // DAG 任务编排: 按依赖拓扑分层执行, 同层并行, 上游结果传入下游 (P3)
-  // graph = { nodes: [{ id, task, dependsOn?: [id], agent?: name }] }
-  // 返回 { results: {id: reply}, order: [执行顺序] }
-  async runDag(graph) {
-    const names = [...this.agents.keys()];
-    if (!names.length) throw new Error("军团为空, 先 spawnAgent");
-    let rr = 0; // round-robin 派发未指定 agent 的节点
-    return runDag(graph, async (id, node, deps) => {
-      const agent = node.agent || names[rr++ % names.length];
-      const depText = Object.entries(deps)
-        .map(([k, v]) => `${k}: ${String(v).slice(0, 500)}`)
-        .join("\n");
-      const message = node.task + (depText ? "\n\n[上游结果]\n" + depText : "");
-      const r = await this.send(agent, { type: "chat", message });
-      return r.reply;
-    }, { concurrency: this.maxConcurrent });
-  }
-
-  // 关闭所有 agent
-  // v1.0.8: 先发 shutdown 优雅退出, 300ms 后兜底 kill 仍存活进程 (worker 无响应/卡死时不残留)
-  async shutdownAll() {
-    for (const [name] of [...this.agents]) {
-      try { this.send(name, { type: "shutdown" }).catch(() => {}); } catch {}
-    }
-    // 等待退出
-    await new Promise((r) => setTimeout(r, 300));
-    for (const [name, entry] of [...this.agents]) {
-      try { entry.proc.kill(); } catch {}
-    }
-  }
-
-  list() {
-    return [...this.agents.keys()].map((n) => ({ name: n, pid: this.agents.get(n).proc.pid }));
-  }
+// src/orchestrator/legion.js - Agent 军团编排器
+// 管理多个独立 agent 子进程, 支持并行派发任务、按角色分工
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { EventEmitter } from "node:events";
+import { info, error, warn, debug } from "../utils/logger.js";
+import { createLineReader, writeLine } from "../utils/ndjson.js";
+import { runDag } from "./dag.js";
+
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+const WORKER = path.join(ROOT, "src", "orchestrator", "agent-worker.js");
+
+export class Legion extends EventEmitter {
+  constructor({ workerPath = WORKER, nodeBin = process.execPath, maxConcurrent = 8 } = {}) {
+    super();
+    this.workerPath = workerPath;
+    this.nodeBin = nodeBin;
+    this.maxConcurrent = maxConcurrent; // 军团整体并发上限: 防止大 DAG/广播瞬间 spawn 海量子进程
+    this.agents = new Map(); // { name: { proc, pending: Map<id,{resolve,reject}>, counter } }
+  }
+
+  // 有界并发执行器: 以固定并发度跑一批 async 任务, 超出上限的排队 (背压而非一次性 Promise.all)
+  // 这是 broadcast/runDag 层共享的背压口, 避免"并发无数控、大输入一次性打爆子进程数"
+  async _mapBounded(items, fn, { concurrency = this.maxConcurrent } = {}) {
+    const results = new Array(items.length);
+    let idx = 0;
+    const workers = Array.from({ length: Math.max(1, Math.min(concurrency, items.length)) });
+    await Promise.all(workers.map(async () => {
+      while (idx < items.length) {
+        const i = idx++;
+        results[i] = await fn(items[i], i);
+      }
+    }));
+    return results;
+  }
+
+  // 创建一个 agent 子进程
+  spawnAgent(name, { dataDir, globalDataDir, env = {} } = {}) {
+    // 未显式指定 dataDir → worker 退回默认 root(项目根) 的 data/, 即把运行数据写进生产目录。
+    // 2026-10-03: test/legion.test.js 曾因此污染真实 data/ (实测 139 个测试中唯一一个), 此处显式告警。
+    if (!dataDir) warn(`[legion] spawnAgent(${name}) 未指定 dataDir, worker 将写入默认数据目录 (可能是生产 data/)`);
+    if (this.agents.has(name)) return this.agents.get(name);
+    const env2 = { ...process.env, ...env };
+    if (dataDir) env2.PPX_AGENT_DATA_DIR = dataDir;
+    // 全局共享目录: 跨 agent 共享经验库 (ANS 全局记忆)
+    if (globalDataDir) env2.PPX_AGENT_GLOBAL_DATA_DIR = globalDataDir;
+    const proc = spawn(this.nodeBin, [this.workerPath], {
+      cwd: ROOT,
+      env: env2,
+      stdio: ["pipe", "pipe", "inherit"],
+    });
+    const entry = { proc, pending: new Map(), counter: 0 };
+    this.agents.set(name, entry);
+
+    proc.stdout.setEncoding("utf8");
+    const onLine = createLineReader((line) => {
+      try {
+        const msg = JSON.parse(line);
+        // step 中间事件: 触发 onProgress 回调, 不消费 pending (等最终 reply)
+        if (msg.type === "step" && msg.id && entry.pending.has(msg.id)) {
+          const p = entry.pending.get(msg.id);
+          if (p && p.onProgress) { try { p.onProgress(msg); } catch (e) { debug(`[orchestrator/legion] 已忽略异常: ${e && e.message ? e.message : e}`); } }
+          return;
+        }
+        if (msg.id && entry.pending.has(msg.id)) {
+          const { resolve, reject } = entry.pending.get(msg.id);
+          entry.pending.delete(msg.id);
+          if (msg.type === "error") reject(new Error(msg.error));
+          else resolve(msg);
+        }
+      } catch (e) { debug(`[orchestrator/legion] 已忽略异常: ${e && e.message ? e.message : e}`); }
+    });
+    proc.stdout.on("data", onLine);
+    proc.on("error", (err) => {
+      // v1.0.8: spawn 失败 (node bin 不存在等) 兜底, 拒绝所有 pending, 防永久挂起
+      error(`agent[${name}] 启动失败: ${err.message}`);
+      for (const [, { reject }] of entry.pending) reject(new Error(`agent ${name} 启动失败`));
+      entry.pending.clear();
+      this.agents.delete(name);
+    });
+    proc.on("exit", (code) => {
+      info(`agent[${name}] 退出 code=${code}`);
+      // 拒绝所有 pending
+      for (const [, { reject }] of entry.pending) reject(new Error(`agent ${name} 已退出`));
+      entry.pending.clear();
+      this.agents.delete(name);
+      this.emit("exit", name, code);
+    });
+    info(`agent[${name}] 已启动 (pid=${proc.pid})`);
+    return entry;
+  }
+
+  // 向某 agent 发消息, 返回 Promise (onProgress 可选: 接收 step 中间事件)
+  // v1.0.8: 超时兜底 (默认 30s), worker 卡死/异常不导致 pending 永久挂起
+  send(name, msg, { onProgress, timeout = 30000 } = {}) {
+    const entry = this.agents.get(name);
+    if (!entry || entry.proc.exitCode !== null) {
+      return Promise.reject(new Error(`agent ${name} 未运行`));
+    }
+    const id = ++entry.counter;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        entry.pending.delete(id);
+        reject(new Error(`agent ${name} 请求超时 (${timeout}ms)`));
+      }, timeout);
+      entry.pending.set(id, {
+        resolve: (v) => { clearTimeout(timer); resolve(v); },
+        reject: (e) => { clearTimeout(timer); reject(e); },
+        onProgress,
+      });
+      try {
+        writeLine(entry.proc.stdin, { id, ...msg });
+      } catch (e) {
+        clearTimeout(timer);
+        entry.pending.delete(id);
+        reject(new Error(`agent ${name} 写入失败: ${e.message}`));
+      }
+    });
+  }
+
+  // 并行派发: 同一任务广播给多个 agent, 最快返回
+  async broadcast(type, message, { timeout = 30000 } = {}) {
+    const names = [...this.agents.keys()];
+    if (!names.length) throw new Error("军团为空, 先 spawnAgent");
+    const results = await this._mapBounded(
+      names,
+      (n) => this.send(n, { type, message }, { timeout }).catch((e) => ({ type: "error", error: e.message }))
+    );
+    return names.map((n, i) => ({ agent: n, ...results[i] }));
+  }
+
+  // 按角色分工: 把任务列表分给不同 agent
+  // 2026-10-02: 串行 → 有界并行 (_mapBounded 背压, 同 broadcast/runDag 共享 maxConcurrent 口)
+  async dispatch(type, tasks) {
+    const names = [...this.agents.keys()];
+    if (!names.length) throw new Error("军团为空, 先 spawnAgent");
+    return this._mapBounded(tasks, (task, i) => {
+      const name = names[i % names.length];
+      return this.send(name, { type, message: task })
+        .then((r) => ({ agent: name, task, ...r }))
+        .catch((e) => ({ agent: name, task, type: "error", error: e.message }));
+    });
+  }
+
+  // DAG 任务编排: 按依赖拓扑分层执行, 同层并行, 上游结果传入下游 (P3)
+  // graph = { nodes: [{ id, task, dependsOn?: [id], agent?: name }] }
+  // 返回 { results: {id: reply}, order: [执行顺序] }
+  async runDag(graph) {
+    const names = [...this.agents.keys()];
+    if (!names.length) throw new Error("军团为空, 先 spawnAgent");
+    let rr = 0; // round-robin 派发未指定 agent 的节点
+    return runDag(graph, async (id, node, deps) => {
+      const agent = node.agent || names[rr++ % names.length];
+      const depText = Object.entries(deps)
+        .map(([k, v]) => `${k}: ${String(v).slice(0, 500)}`)
+        .join("\n");
+      const message = node.task + (depText ? "\n\n[上游结果]\n" + depText : "");
+      const r = await this.send(agent, { type: "chat", message });
+      return r.reply;
+    }, { concurrency: this.maxConcurrent });
+  }
+
+  // 关闭所有 agent
+  // v1.0.8: 先发 shutdown 优雅退出, 300ms 后兜底 kill 仍存活进程 (worker 无响应/卡死时不残留)
+  async shutdownAll() {
+    for (const [name] of [...this.agents]) {
+      try { this.send(name, { type: "shutdown" }).catch(() => {}); } catch (e) { debug(`[orchestrator/legion] 已忽略异常: ${e && e.message ? e.message : e}`); }
+    }
+    // 等待退出
+    await new Promise((r) => setTimeout(r, 300));
+    for (const [name, entry] of [...this.agents]) {
+      try { entry.proc.kill(); } catch (e) { debug(`[orchestrator/legion] 已忽略异常: ${e && e.message ? e.message : e}`); }
+    }
+  }
+
+  list() {
+    return [...this.agents.keys()].map((n) => ({ name: n, pid: this.agents.get(n).proc.pid }));
+  }
 }