ppxans-harness 2.4.0

package/src/mode/graph.js

@@ -0,0 +1,41 @@
+// src/mode/graph.js - Graph / Workflow 模式
+// 显式工作流编排: 按节点顺序执行, 每个节点走 react 工具循环, 结果 checkpoint 到会话日志。
+// 适合: 企业级、可审计、可恢复的确定性流程。当前为顺序 DAG, 未来可扩展依赖/并行。
+import { buildMessages } from "./index.js";
+
+// 归一化 workflow 节点: 接受字符串数组或 { name, task } 对象数组
+export function normalizeNodes(workflow) {
+  if (!Array.isArray(workflow)) return [];
+  return workflow.map((node) => {
+    if (typeof node === "string") return { name: node, task: node };
+    return { name: String(node.name || node.task || ""), task: String(node.task || node.name || "") };
+  }).filter((n) => n.task);
+}
+
+export async function graphExecutor(agent, userMsg, { sessionKey = "default", workflow = null } = {}) {
+  if (!agent.llm) {
+    return (await agent._localIntent(userMsg)) || "[皮皮虾] 未配置模型 provider (配置见 docs/QUICKSTART.md 第 3 节)。";
+  }
+  // workflow 来源: opts 传入 > config.agent.workflow > 默认单节点
+  const raw = workflow || (agent.config.agent && agent.config.agent.workflow) || [userMsg];
+  const nodes = normalizeNodes(raw);
+  if (!nodes.length) {
+    const messages = await buildMessages(agent, userMsg, sessionKey);
+    return agent._llmWithFallback(messages);
+  }
+
+  const base = await buildMessages(agent, userMsg, sessionKey);
+  const results = [];
+  for (const node of nodes) {
+    let r;
+    try {
+      r = await agent._llmWithFallback([...base, { role: "user", content: `[节点: ${node.name}] ${node.task}` }]);
+    } catch (e) {
+      r = `(节点 ${node.name} 失败: ${e.message})`;
+    }
+    // checkpoint: 节点结果落会话日志, 崩溃后可恢复/审计
+    try { agent.sessionStore.append(sessionKey, "tool/result", { content: `[workflow:${node.name}] ${r}` }); } catch {}
+    results.push(`节点[${node.name}]:\n${r}`);
+  }
+  return results.join("\n\n");
+}

package/src/mode/index.js

@@ -0,0 +1,64 @@
+// src/mode/index.js - Agent 模式注册表 (编排策略可插拔)
+// 把「怎么编排」从 chat() 里抽出来, 每种模式是一个 executor(agent, userMsg, opts) -> reply。
+// 内置: react(工具循环) / single(纯对话) / plan-exec / router / blackboard / graph / legion。
+// 默认 react; 用 config.agent.mode 或 chat({ mode }) 切换。
+
+export class ModeRegistry {
+  constructor() {
+    this.modes = new Map(); // name -> executor
+  }
+
+  register(name, executor) {
+    if (!name || typeof executor !== "function") throw new Error("模式注册失败: 需 name + executor 函数");
+    this.modes.set(name, executor);
+    return this;
+  }
+
+  has(name) { return this.modes.has(name); }
+  get(name) { return this.modes.get(name); }
+  list() { return [...this.modes.keys()]; }
+
+  // 执行某模式: executor(agent, userMsg, opts) -> reply
+  async run(name, agent, userMsg, opts = {}) {
+    const exe = this.modes.get(name);
+    if (!exe) throw new Error(`[模式] 未知模式: ${name} (可用: ${this.list().join(", ")})`);
+    return exe(agent, userMsg, opts);
+  }
+}
+
+// 组装 [system + 历史 + 当前] 消息 (含防重复), 供各 executor 复用
+export async function buildMessages(agent, userMsg, sessionKey = "default") {
+  const system = agent._context(userMsg);
+  const history = await agent._loadHistory(sessionKey);
+  const messages = [{ role: "system", content: system }, ...history];
+  const hist = agent._getSession(sessionKey);
+  const isRepeat = hist[hist.length - 1]?.role === "user" && hist[hist.length - 1].content === String(userMsg);
+  if (!isRepeat) messages.push({ role: "user", content: agent._userContent(userMsg) });
+  return messages;
+}
+
+// ---- 内置模式 ----
+
+// ReAct: 推理-行动-观察循环 (带工具, 默认模式)
+async function reactExecutor(agent, userMsg, { sessionKey = "default" } = {}) {
+  if (!agent.llm) {
+    return (await agent._localIntent(userMsg)) || "[皮皮虾] 未配置模型 provider，仅本地记忆 + 工具模式 (配置见 docs/QUICKSTART.md 第 3 节)。";
+  }
+  const messages = await buildMessages(agent, userMsg, sessionKey);
+  return agent._llmWithFallback(messages);
+}
+
+// 单Agent: 纯 LLM 对话, 不挂工具 (省 token, 适合纯问答/闲聊)
+async function singleExecutor(agent, userMsg, { sessionKey = "default" } = {}) {
+  if (!agent.llm) return "[皮皮虾] 未配置模型 provider (配置见 docs/QUICKSTART.md 第 3 节)。";
+  const messages = await buildMessages(agent, userMsg, sessionKey);
+  const r = await agent.llm.chat(messages);
+  return r.content;
+}
+
+// 注册内置模式
+export function registerDefaultModes(registry) {
+  registry.register("react", reactExecutor);
+  registry.register("single", singleExecutor);
+  return registry;
+}

package/src/mode/legion.js

@@ -0,0 +1,51 @@
+// src/mode/legion.js - 多 Agent 军团模式
+// 把 Legion (多进程军团 + DAG 编排) 接入 mode 系统, chat({ mode: "legion" }) 可用。
+// 编排策略:
+//   - 有 workflow (DAG 节点数组) 时走 runDag: 按依赖拓扑分层并行, 上游结果流入下游
+//   - 无 workflow 时走 broadcast: 同一问题广播给全部 agent, 取第一个有效回复
+// 军团配置: config.agent.legion = { size, workflow } 或 config.orchestrator
+// 可注入: opts.legion (测试/复用已有军团实例, 免重复 spawn)
+import path from "node:path";
+import { Legion } from "../orchestrator/legion.js";
+import { warn } from "../utils/logger.js";
+
+export async function legionExecutor(agent, userMsg, { sessionKey = "default", legion = null, workflow = null, size = null } = {}) {
+  const cfg = (agent.config && (agent.config.agent?.legion || agent.config.orchestrator)) || {};
+
+  // 1. 拿或懒建军团 (缓存到 agent, 复用子进程, 不重复 spawn)
+  let L = legion || agent._legion;
+  if (!L) {
+    L = new Legion();
+    const n = size || cfg.size || 2;
+    for (let i = 0; i < n; i++) {
+      // 每个 agent 独立数据目录, 隔离记忆/会话, 互不干扰
+      const dataDir = path.join(agent.dataDir, "legion", `agent-${i}`);
+      L.spawnAgent(`agent-${i}`, { dataDir });
+    }
+    agent._legion = L;
+  }
+
+  // 2. 编排: workflow(DAG) 优先, 否则 broadcast
+  const wf = workflow || cfg.workflow;
+  if (Array.isArray(wf) && wf.length) {
+    // v1.0.8: 校验节点结构 (需 {id, task}), 防字符串数组直接 TypeError
+    const bad = wf.find((n) => !n || typeof n !== "object" || !n.id || !n.task);
+    if (bad) return `[军团] workflow 节点需 {id, task} 对象, 非法节点: ${JSON.stringify(bad).slice(0, 80)}`;
+    try {
+      const { results } = await L.runDag({ nodes: wf });
+      const lines = Object.entries(results).map(([id, r]) => `【${id}】\n${r}`);
+      return lines.join("\n\n");
+    } catch (e) {
+      return `[军团] DAG 编排失败: ${e.message}`;
+    }
+  }
+
+  try {
+    const results = await L.broadcast("chat", userMsg);
+    const ok = results.filter((r) => r.status === "fulfilled" && r.value && r.value.reply);
+    if (ok.length) return ok[0].value.reply;
+  } catch (e) {
+    warn("[legion] broadcast 失败:", e.message);
+  }
+  return "[军团] 所有 agent 均未返回有效结果 (请确认已 spawnAgent 或配置 config.agent.legion.size)";
+}

package/src/mode/plan-exec.js

@@ -0,0 +1,50 @@
+// src/mode/plan-exec.js - Plan & Execute 模式
+// 先让 LLM 生成完整计划(步骤清单), 再逐步执行(每步走 react 工具循环), 最后汇总。
+// 适合: 可分解的多步任务, 结构化、可预测、减少中间推理浪费。
+import { buildMessages } from "./index.js";
+
+// 解析 LLM 返回的步骤清单 (JSON 数组, 容忍 markdown 代码块包裹)
+export function parseSteps(text) {
+  const cleaned = String(text || "").replace(/```(?:json|JSON)?\s*/g, "").replace(/```/g, "").trim();
+  const m = cleaned.match(/\[[\s\S]*\]/);
+  if (!m) return [];
+  try {
+    const arr = JSON.parse(m[0]);
+    return Array.isArray(arr) ? arr.map((x) => String(x).trim()).filter(Boolean) : [];
+  } catch { return []; }
+}
+
+// 规划: LLM 生成步骤清单 (无 LLM 返回空)
+async function planSteps(agent, userMsg) {
+  if (!agent.llm) return [];
+  const r = await agent.llm.chat([
+    { role: "system", content: "你是任务规划器。把用户的任务分解成 2-6 个可独立执行的具体步骤, 每步一句话(含要做什么)。只输出 JSON 数组, 例如 [\"读取配置文件\", \"修改端口\", \"重启服务\"]。不要解释。" },
+    { role: "user", content: String(userMsg).slice(0, 2000) },
+  ]);
+  return parseSteps(r.content);
+}
+
+export async function planExecExecutor(agent, userMsg, { sessionKey = "default", maxSteps = 6 } = {}) {
+  if (!agent.llm) {
+    return (await agent._localIntent(userMsg)) || "[皮皮虾] 未配置模型 provider (配置见 docs/QUICKSTART.md 第 3 节)。";
+  }
+  // 1. 规划
+  const steps = (await planSteps(agent, userMsg)).slice(0, maxSteps);
+  if (!steps.length) {
+    // 规划失败: 退回 react 模式
+    const messages = await buildMessages(agent, userMsg, sessionKey);
+    return agent._llmWithFallback(messages);
+  }
+  // 2. 逐步执行 (每步走工具循环)
+  const base = await buildMessages(agent, userMsg, sessionKey);
+  const results = [];
+  for (let i = 0; i < steps.length; i++) {
+    const stepMsg = [...base, { role: "user", content: `[第 ${i + 1}/${steps.length} 步] ${steps[i]}` }];
+    let r;
+    try { r = await agent._llmWithFallback(stepMsg); }
+    catch (e) { r = `(步骤失败: ${e.message})`; }
+    results.push(`步骤${i + 1}: ${steps[i]}\n${r}`);
+  }
+  // 3. 汇总
+  return results.join("\n\n");
+}

package/src/mode/router.js

@@ -0,0 +1,40 @@
+// src/mode/router.js - Router + Skill 模式
+// 意图路由: 按用户输入匹配已安装技能, 把匹配到的 SKILL.md 注入上下文后执行。
+// 适合: 多领域任务, 快速定位专门能力; 按需加载技能, 省 token。
+import path from "node:path";
+import { SkillLoader } from "../skills/loader.js";
+import { buildMessages } from "./index.js";
+
+// 技能匹配: 中文用连续两字(bigram)命中描述, 英文/数字用词命中
+export function matchSkill(loader, text) {
+  const skills = loader.list();
+  const q = String(text || "").toLowerCase();
+  let best = null, bestScore = 0;
+  for (const s of skills) {
+    const desc = (s.description || "").toLowerCase();
+    let score = 0;
+    const bigrams = new Set();
+    const cjk = q.match(/[\u4e00-\u9fff]+/g) || [];
+    for (const seg of cjk) for (let i = 0; i < seg.length - 1; i++) bigrams.add(seg.slice(i, i + 2));
+    for (const bg of bigrams) if (desc.includes(bg)) score += 1;
+    const words = q.match(/[a-z0-9]+/g) || [];
+    for (const w of words) if (w.length >= 2 && desc.includes(w)) score += 1;
+    if (score > bestScore) { bestScore = score; best = s; }
+  }
+  return bestScore >= 1 ? best : null;
+}
+
+export async function routerExecutor(agent, userMsg, { sessionKey = "default" } = {}) {
+  if (!agent.llm) {
+    return (await agent._localIntent(userMsg)) || "[皮皮虾] 未配置模型 provider (配置见 docs/QUICKSTART.md 第 3 节)。";
+  }
+  // 1. 技能路由: 匹配用户输入到已安装技能
+  const loader = new SkillLoader(path.join(agent.root, "skills"));
+  const skill = matchSkill(loader, userMsg);
+  // 2. 注入技能内容到 system prompt, 再执行 (场景上下文已由 agent._context 注入)
+  const system = agent._context(userMsg)
+    + (skill ? `\n\n[已激活技能: ${skill.name}]\n${loader.read(skill.id)}` : "");
+  const history = await agent._loadHistory(sessionKey);
+  const messages = [{ role: "system", content: system }, ...history, { role: "user", content: String(userMsg) }];
+  return agent._llmWithFallback(messages);
+}

package/src/orchestrator/agent-worker.js

@@ -0,0 +1,70 @@
+// src/orchestrator/agent-worker.js - 子 agent 进程 (独立 PPXAgent 实例)
+// 通过 stdin 收消息, stdout 回结果. 每个 worker 完全隔离.
+import { PPXAgent } from "../agent/index.js";
+
+const root = process.cwd();
+// 可选: 独立数据目录 (多进程军团隔离, 避免互踩同一个 data/)
+// 可选: 全局共享目录 (跨 agent 共享经验库 = ANS 全局记忆)
+const agent = new PPXAgent({
+  root,
+  dataDir: process.env.PPX_AGENT_DATA_DIR || undefined,
+  globalDataDir: process.env.PPX_AGENT_GLOBAL_DATA_DIR || undefined,
+});
+
+// 只读审查者模式 (SDD, Superpowers): 禁用一切修改/执行类工具, 只能读/查
+// 供 spawn_agent review 循环的审查者角色使用
+if (process.env.PPX_AGENT_READONLY === "1") {
+  agent.enableReadonlyMode();
+}
+
+// 从 stdin 读 JSON 行
+process.stdin.setEncoding("utf8");
+let buf = "";
+let currentReqId = null; // 当前正在处理的 chat 请求 id (step 事件路由用)
+// v1.0.8: promise 链串行处理 (防止 data 事件并发时 currentReqId/_perspective 互相覆盖)
+let queue = Promise.resolve();
+// step 事件转发: 把 agent 的推理轮次进度实时回给主进程 (turn/step 可观测性)
+agent.setStepEvent((ev) => {
+  if (currentReqId == null) return;
+  process.stdout.write(JSON.stringify({ id: currentReqId, type: "step", ...ev }) + "\n");
+});
+process.stdin.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;
+    queue = queue.then(() => handleLine(line));
+  }
+});
+
+async function handleLine(line) {
+  try {
+    const req = JSON.parse(line);
+    if (req.type === "chat") {
+      currentReqId = req.id;
+      // 差异化上下文 (多 agent 协调): 委派方可注入子 agent 专属视角, 对抗同质失败
+      const prevPerspective = agent._perspective;
+      agent._perspective = req.perspective ? String(req.perspective).slice(0, 4000) : null;
+      let reply;
+      try {
+        reply = await agent.chat(req.message);
+      } finally {
+        agent._perspective = prevPerspective;
+      }
+      currentReqId = null;
+      process.stdout.write(JSON.stringify({ id: req.id, type: "reply", reply }) + "\n");
+    } else if (req.type === "ping") {
+      process.stdout.write(JSON.stringify({ id: req.id, type: "pong", name: agent.config.agent?.name || "ppx" }) + "\n");
+    } else if (req.type === "shutdown") {
+      agent.shutdown();
+      process.stdout.write(JSON.stringify({ id: req.id, type: "bye" }) + "\n");
+      process.exit(0);
+    }
+  } catch (e) {
+    // v1.0.8: error 行必须带 req.id, 否则主进程 Legion.pending 匹配不到永不 settle (永久挂起)
+    process.stdout.write(JSON.stringify({ id: currentReqId || null, type: "error", error: e.message }) + "\n");
+    currentReqId = null;
+  }
+}

package/src/orchestrator/dag.js

@@ -0,0 +1,83 @@
+// 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 };
+}

package/src/orchestrator/index.js

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

package/src/orchestrator/legion.js

@@ -0,0 +1,188 @@
+// 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 }));
+  }
+}