ppxans-harness 2.4.0 → 3.2.0

package/src/mode/graph.js

@@ -1,41 +1,42 @@
-// 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");
-}
+// src/mode/graph.js - Graph / Workflow 模式
+// 显式工作流编排: 按节点顺序执行, 每个节点走 react 工具循环, 结果 checkpoint 到会话日志。
+// 适合: 企业级、可审计、可恢复的确定性流程。当前为顺序 DAG, 未来可扩展依赖/并行。
+import { buildMessages } from "./index.js";
+import { debug } from "../utils/logger.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 (e) { debug(`[mode/graph] 已忽略异常: ${e && e.message ? e.message : e}`); }
+    results.push(`节点[${node.name}]:\n${r}`);
+  }
+  return results.join("\n\n");
+}

package/src/mode/index.js

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

@@ -1,51 +1,54 @@
-// 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)";
-}
+// 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);
+    // 真实 broadcast 返回形状: { agent, id, type:'reply', reply } 或 { agent, type:'error', error }
+    // (曾误写成 { status:'fulfilled', value:{ reply } } —— 那是测试桩伪造的形状, 导致此处恒为空,
+    //  军团 broadcast 模式在真实环境永远走兜底串)
+    const ok = results.filter((r) => r && r.type === "reply" && r.reply);
+    if (ok.length) return ok[0].reply;
+  } catch (e) {
+    warn("[legion] broadcast 失败:", e.message);
+  }
+  return "[军团] 所有 agent 均未返回有效结果 (请确认已 spawnAgent 或配置 config.agent.legion.size)";
+}

package/src/mode/plan-exec.js

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

@@ -1,40 +1,28 @@
-// 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);
-}
+// src/mode/router.js - Router + Skill 模式
+// 意图路由: 按用户输入匹配已安装技能, 把匹配到的 SKILL.md 注入上下文后执行。
+// 适合: 多领域任务, 快速定位专门能力; 按需加载技能, 省 token。
+import path from "node:path";
+import { SkillLoader } from "../skills/loader.js";
+import { debug } from "../utils/logger.js";
+
+// 技能匹配移至 src/skills/search.js (2026-10-01): name 加权 + 高置信阈值 + 歧义不押注,
+// 并供 skill_search 工具复用同一打分器。此处保持转出口兼容既有 import。
+export { matchSkill } from "../skills/search.js";
+
+export async function routerExecutor(agent, userMsg, { sessionKey = "default" } = {}) {
+  if (!agent.llm) {
+    return (await agent._localIntent(userMsg)) || "[皮皮虾] 未配置模型 provider (配置见 docs/QUICKSTART.md 第 3 节)。";
+  }
+  // 1. 技能路由: 匹配用户输入到已安装技能
+  // 2026-10-01 优化: 复用 agent.skills (原每条消息 new 一个 loader 全量重扫),
+  // 命中即 trackUse — 路由路径此前绕过了使用统计, 自进化飞轮 (auto_skill/升级闸门) 因此少计数。
+  const loader = agent.skills || new SkillLoader(path.join(agent.root, "skills"));
+  const skill = matchSkill(loader, userMsg);
+  if (skill && typeof loader.trackUse === "function") { try { loader.trackUse(skill.id); } catch (e) { debug(`[mode/router] 已忽略异常: ${e && e.message ? e.message : e}`); } }
+  // 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

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