ppxans-harness 2.4.0

package/src/orchestrator/supervisor.js

@@ -0,0 +1,177 @@
+// src/orchestrator/supervisor.js - supervisor 编排模式 (P3⑨)
+// 吸收 LangGraph supervisor 拓扑 + OpenAI Agents SDK handoff 思想 (仅思想, 无源码复制):
+//   监督者(S) 分解任务 → 派发给多个专家子 agent (E1..En) → 收集结果 →
+//   S 综合/评审 → 决定: 接受最终答案 / 发现分歧 → 重新派发修正 / 升级人工。
+// 皮皮虾自研实现, 构建在现有 Legion (多进程) + delegate 仲裁之上。
+// 与 delegate.js 的 arbitrate (一次性聚合) 互补: supervisor 是完整编排循环 (可多轮修正)。
+
+// 带超时等待 (防子 agent 卡死) — 定时器必须清理
+export 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));
+}
+
+export const SUPERVISOR_DEFAULTS = {
+  maxRounds: 3,          // 最多几轮修正
+  timeoutMs: 120000,     // 每轮子 agent 超时
+  minConsensus: 0.6,     // 一致率低于此值视为分歧 (需重新派发)
+};
+
+// ---- 纯函数: 从子结果中识别分歧 ----
+// results: [{agent, reply}]  reply 为文本
+// 返回 { consensus: 0~1, clusters: [{key, members, replies}], divergent: boolean }
+// 用词法相似度聚类 (零依赖, 可升级 embedding)
+export function findDisagreement(results, { minConsensus = SUPERVISOR_DEFAULTS.minConsensus } = {}) {
+  const list = (results || []).filter((r) => r && typeof r.reply === "string" && r.reply.trim());
+  if (list.length < 2) return { consensus: 1, clusters: [{ key: "solo", members: list, replies: list.map((r) => r.reply) }], divergent: false };
+
+  // 贪心聚类: 相似度 > 0.4 归一组
+  const clusters = [];
+  const assigned = new Set();
+  for (let i = 0; i < list.length; i++) {
+    if (assigned.has(i)) continue;
+    const members = [list[i]];
+    assigned.add(i);
+    for (let j = i + 1; j < list.length; j++) {
+      if (assigned.has(j)) continue;
+      if (lexSim(list[i].reply, list[j].reply) > 0.4) {
+        members.push(list[j]);
+        assigned.add(j);
+      }
+    }
+    clusters.push({ key: "c" + clusters.length, members, replies: members.map((m) => m.reply) });
+  }
+  const largest = Math.max(...clusters.map((c) => c.members.length));
+  const consensus = largest / list.length;
+  return { consensus, clusters, divergent: consensus < minConsensus };
+}
+
+function lexSim(a, b) {
+  // 中文连续串用字符 bigram (词级 Jaccard 对中文短句失效), 与 playbook.js 同策略
+  const ta = String(a || "");
+  const tb = String(b || "");
+  if (!ta || !tb) return 0;
+  const tk = (s) => {
+    const words = s.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+    if (words.length > 1) return words;
+    const chars = s.replace(/\s+/g, "").toLowerCase();
+    const out = [];
+    for (let i = 0; i < chars.length - 1; i++) out.push(chars.slice(i, i + 2));
+    return out.length ? out : chars.split("");
+  };
+  const A = new Set(tk(ta));
+  const B = new Set(tk(tb));
+  if (!A.size || !B.size) return 0;
+  let inter = 0;
+  for (const w of A) if (B.has(w)) inter++;
+  return (2 * inter) / (A.size + B.size);
+}
+
+// ---- 纯函数: 组装监督者修正提示词 (把分歧/缺陷反馈给子 agent) ----
+export function buildRevisionPrompt(task, feedback) {
+  const lines = (feedback || []).map((f, i) => `${i + 1}. ${f}`).join("\n");
+  return `${task}\n\n【监督者反馈】以下问题需修正:\n${lines}\n\n请针对反馈逐条修正, 只解决反馈问题, 不要引入新内容。`;
+}
+
+// ---- 监督者循环 ----
+// opts: { legion, agents: [name...], task, judge, maxRounds, timeoutMs, minConsensus, onRound }
+// 返回 { answer, rounds, consensus, divergent, history: [{round, results, feedback}] }
+export async function runSupervisor({ legion, agents = [], task = "", judge = "", maxRounds = SUPERVISOR_DEFAULTS.maxRounds, timeoutMs = SUPERVISOR_DEFAULTS.timeoutMs, minConsensus = SUPERVISOR_DEFAULTS.minConsensus, onRound = null, llm = null, finalize = null } = {}) {
+  const history = [];
+  let currentTask = task;
+  let answer = "";
+  let rounds = 0;
+
+  for (let r = 0; r < maxRounds; r++) {
+    rounds = r + 1;
+    // 派发给所有专家
+    const results = [];
+    for (const name of agents) {
+      try {
+        const resp = await withTimeout(
+          legion.send(name, { type: "chat", message: currentTask }, { timeout: timeoutMs + 5000 }),
+          timeoutMs,
+          `监督者派发→${name}`
+        );
+        results.push({ agent: name, reply: String(resp?.reply || "").trim() || "(无回复)" });
+      } catch (e) {
+        results.push({ agent: name, reply: `[失败] ${e.message}` });
+      }
+    }
+
+    // 分歧检测
+    const { consensus, divergent, clusters } = findDisagreement(results, { minConsensus });
+    const roundRec = { round: r + 1, results, consensus, divergent, feedback: [] };
+
+    // 监督者评审: 有 LLM 且有多结果时, 让监督者决定是否接受或给反馈
+    let accept = !divergent;
+    let feedback = [];
+    if (llm && results.length >= 2) {
+      const verdict = await judgeRound(llm, task, results, judge);
+      accept = verdict.accept;
+      feedback = verdict.feedback;
+    } else if (divergent) {
+      feedback = [`各方结果存在分歧 (一致率 ${(consensus * 100).toFixed(0)}%), 请重新给出更一致的结论。`];
+    }
+    roundRec.feedback = feedback;
+    history.push(roundRec);
+    onRound?.(roundRec);
+
+    if (accept) {
+      // 监督者 (或 finalize) 产出最终答案
+      if (llm) {
+        const final = await finalizeRound(llm, task, results, judge);
+        answer = final;
+      } else {
+        answer = results[0]?.reply || "";
+      }
+      return { answer, rounds, consensus, divergent: false, history };
+    }
+    // 不通过: 带反馈重新派发
+    currentTask = buildRevisionPrompt(task, feedback.length ? feedback : ["请给出更精确、一致的答案。"]);
+  }
+  // 达到轮数上限: 返回最近一轮结果 + 分歧标记
+  const last = history[history.length - 1];
+  answer = last.results.map((r) => `【${r.agent}】${r.reply}`).join("\n\n");
+  return { answer, rounds, consensus: last.consensus, divergent: true, history };
+}
+
+// 监督者评审: 综合各结果, 决定接受/打回 + 反馈
+async function judgeRound(llm, task, results, judge) {
+  const input = results.map((r) => `【${r.agent}】\n${String(r.reply).slice(0, 1500)}`).join("\n\n");
+  try {
+    const r = await llm.chat([
+      { role: "system", content: "你是监督者。评估各专家子 agent 的结果是否满足任务要求。输出 JSON: {\"accept\": true/false, \"feedback\": [\"问题1\", \"问题2\"]}。accept=true 时 feedback 为空数组。只输出 JSON。" },
+      { role: "user", content: `【任务】${String(task).slice(0, 1000)}\n${judge ? `【评审要求】${judge}\n` : ""}【各方结果】\n${input.slice(0, 5000)}` },
+    ]);
+    const text = String(r?.content || "").replace(/```(?:json)?\s*/g, "").replace(/```/g, "").trim();
+    const m = text.match(/\{[\s\S]*\}/);
+    if (!m) return { accept: false, feedback: ["监督者输出格式错误, 请重新回答"] };
+    const parsed = JSON.parse(m[0]);
+    return {
+      accept: parsed.accept === true,
+      feedback: Array.isArray(parsed.feedback) ? parsed.feedback.slice(0, 5).map(String) : [],
+    };
+  } catch {
+    return { accept: false, feedback: ["监督者评审失败, 请重新回答"] };
+  }
+}
+
+// 监督者定稿: 综合各结果给最终答案
+async function finalizeRound(llm, task, results, judge) {
+  const input = results.map((r) => `【${r.agent}】\n${String(r.reply).slice(0, 2000)}`).join("\n\n");
+  try {
+    const r = await llm.chat([
+      { role: "system", content: "你是监督者。综合各专家结果, 给出最终整合答案。直接输出最终答案, 不要复述过程。" },
+      { role: "user", content: `【任务】${String(task).slice(0, 1000)}\n${judge ? `【评审要求】${judge}\n` : ""}【各方结果】\n${input.slice(0, 6000)}` },
+    ]);
+    return String(r?.content || "").trim() || "(监督者无输出)";
+  } catch {
+    return results.map((r) => `【${r.agent}】${r.reply}`).join("\n\n");
+  }
+}
+
+export default { runSupervisor, findDisagreement, buildRevisionPrompt };

package/src/persona/index.js

@@ -0,0 +1,29 @@
+// src/persona/index.js - 人格系统
+// 从 identity.md + ishiki.md 组装人格 prompt (参考 openhanako)
+import fs from "node:fs";
+import path from "node:path";
+import { readText } from "../utils/store.js";
+
+export class Persona {
+  constructor(rootDir) {
+    this.configDir = path.join(rootDir, "config");
+    this.identity = readText(path.join(this.configDir, "identity.md"), "皮皮虾");
+    this.ishiki = readText(path.join(this.configDir, "ishiki.md"), "- 直接、务实");
+  }
+
+  // 组装 system prompt
+  systemPrompt(userName = "兄弟") {
+    return `${this.identity}
+
+## 人格定义
+${this.ishiki}
+
+## 你面对的用户
+${userName}`;
+  }
+
+  reload() {
+    this.identity = readText(path.join(this.configDir, "identity.md"), "皮皮虾");
+    this.ishiki = readText(path.join(this.configDir, "ishiki.md"), "- 直接、务实");
+  }
+}

package/src/plugin/builtin.js

@@ -0,0 +1,212 @@
+// src/plugin/builtin.js - 皮皮虾内置插件集 (一切皆插件)
+// 借鉴 deepseek-harness 的 "everything is a plugin": 每个模块是一个插件, 通过 ctx.provide 注册服务。
+// 装配顺序即依赖顺序 (依赖在前), 任何插件都可被用户插件替换或扩展。
+import path from "node:path";
+import { Healer } from "../selfheal/healer.js";
+import { Persona } from "../persona/index.js";
+import { FactStore, MemoryTicker, Experience, L0Recorder, SceneStore, PersonaStore } from "../memory/index.js";
+import { SessionStore } from "../memory/session.js";
+import {
+  ToolCatalog, registerBuiltinTools, registerAdvancedTools, Scheduler,
+  registerMethodTools, registerSelfmodTools, registerCustomTools, registerDocumentTools,
+  registerGovernanceTools,
+} from "../tools/index.js";
+import { embedderFromConfig } from "../llm/embedder.js";
+import { LocalShellProvider } from "../seam/shell.js";
+import { registerDelegateTools } from "../tools/delegate.js";
+import { Traces } from "../utils/trace.js";
+import { AuditLog } from "../audit/audit-chain.js";
+import { RuntimeBus } from "../bus/runtime-bus.js";
+import { PlaybookStore } from "../evolve/playbook.js";
+import { MemoryHealthMonitor } from "../services/memory-health.js";
+import { FailureEpisodeStore } from "../memory/failure-episode.js";
+import { CanvasStore } from "../memory/canvas.js";
+import { AssetHub } from "../memory/asset-hub.js";
+import { exportMemorySnapshot, mergeSnapshotBack, hasSnapshot } from "../memory/fork.js";
+
+// fork 工具 (供 ctx.consume("fork") 取用)
+const forkTools = { exportMemorySnapshot, mergeSnapshotBack, hasSnapshot };
+export { isUsableProvider, resolveLLM, resolveAllLLMs } from "../llm/router.js";
+import { ModeRegistry, registerDefaultModes } from "../mode/index.js";
+import { planExecExecutor } from "../mode/plan-exec.js";
+import { routerExecutor } from "../mode/router.js";
+import { blackboardExecutor } from "../mode/blackboard.js";
+import { graphExecutor } from "../mode/graph.js";
+import { legionExecutor } from "../mode/legion.js";
+
+// ---- LLM 路由 (唯一真相源已迁至 src/llm/router.js, 此文件仅 re-export 向后兼容) ----
+// router.js 负责: 占位死配置过滤 / 云端真key优先 / 本地零配置兜底 / 健康排序 / PPX_PROVIDER 强制
+// 此处保留导出名, agent/热重载/插件继续用 builtin.resolveLLM 等旧引用。
+
+// ---- 内置插件: 每个 (ctx) => void, 用 ctx.provide 注册服务 ----
+
+
+export const busPlugin = (ctx) => {
+  // ②循环系: 全局 Runtime 总线。必须最先装配, 其他插件可 ctx.consume("bus") 挂订阅/注册命令。
+  const bus = new RuntimeBus();
+  ctx.provide("bus", bus);
+  // 状态槽: sessionKey 归属 (给观测/审计看当前活跃会话)
+  bus.set("bootedAt", Date.now());
+  return bus;
+};
+
+export const healerPlugin = (ctx) => {
+  const healer = new Healer(ctx.consume("root"));
+  healer.markDirty();
+  const health = healer.heal();
+  ctx.provide("healer", healer);
+  ctx.provide("health", health);
+};
+
+export const personaPlugin = (ctx) => {
+  ctx.provide("persona", new Persona(ctx.consume("root")));
+};
+
+export const factsPlugin = (ctx) => {
+  const config = ctx.consume("config");
+  ctx.provide("facts", new FactStore(ctx.consume("dataDir"), config.memory || {}));
+};
+
+export const experiencePlugin = (ctx) => {
+  // 经验库走全局共享目录 (ANS 全局记忆): 跨 agent 共享经验, 写入用文件锁防并发覆盖
+  ctx.provide("experience", new Experience(ctx.consume("globalDataDir") || ctx.consume("dataDir")));
+};
+
+export const sessionPlugin = (ctx) => {
+  const config = ctx.consume("config");
+  const sessions = new SessionStore(ctx.consume("dataDir"));
+  // 启动时清理过期会话 (config.memory.session_max_age_days, 默认 30; 0/负=不清理)
+  const maxAge = Number(config.memory?.session_max_age_days ?? 30);
+  if (maxAge > 0) {
+    const removed = sessions.pruneOld({ maxAgeDays: maxAge });
+    if (removed.length) info(`[sessions] 清理过期会话 ${removed.length} 个: ${removed.join(", ")}`);
+  }
+  ctx.provide("sessions", sessions);
+};
+
+export const memoryPlugin = (ctx) => {
+  const facts = ctx.consume("facts");
+  const sessions = ctx.consume("sessions");
+  ctx.provide("memory", new MemoryTicker(ctx.consume("dataDir"), facts, null, sessions));
+};
+
+export const llmPlugin = (ctx) => {
+  const config = ctx.consume("config");
+  ctx.provide("llm", resolveLLM(config));
+  ctx.provide("allProviders", resolveAllLLMs(config));
+};
+
+export const memoryLayersPlugin = (ctx) => {
+  const sessions = ctx.consume("sessions");
+  const dataDir = ctx.consume("dataDir");
+  const userName = ctx.consume("userName") || "兄弟";
+  ctx.provide("l0", new L0Recorder(sessions, dataDir));
+  ctx.provide("scenes", new SceneStore(dataDir));
+  ctx.provide("personaStore", new PersonaStore(dataDir, { userName }));
+};
+
+export const tracesPlugin = (ctx) => {
+  ctx.provide("traces", new Traces(ctx.consume("dataDir")));
+};
+
+export const auditPlugin = (ctx) => {
+  // 审计哈希链 (吸收自 ppx-v2): append-only + SHA-256 链式防篡改账本。
+  // 与 core/trace.js 的事件流互补 —— trace 面向"可观测", audit 面向"可追责/防篡改"。
+  // config.audit.enabled === false 时关闭 (供性能敏感场景), 默认开启。
+  const config = ctx.consume("config");
+  if (config?.audit?.enabled === false) {
+    ctx.provide("audit", null);
+    return null;
+  }
+  const audit = new AuditLog(ctx.consume("dataDir"));
+  ctx.provide("audit", audit);
+  return audit;
+};
+
+export const toolsPlugin = (ctx) => {
+  const root = ctx.consume("root");
+  const dataDir = ctx.consume("dataDir");
+  const config = ctx.consume("config");
+  const facts = ctx.consume("facts");
+  const memory = ctx.consume("memory");
+  const tools = new ToolCatalog();
+  registerBuiltinTools(tools, { rootDir: root, facts, memory });
+  const scheduler = new Scheduler(dataDir);
+  ctx.provide("scheduler", scheduler);
+  registerAdvancedTools(tools, { dataDir, scheduler, onMemoryNote: (note) => facts.add(note, { source: "schedule" }) });
+  registerMethodTools(tools);
+  registerSelfmodTools(tools, { skillsDir: path.join(root, "skills") });
+  // 用户自定义工具 (不改源码扩展能力)
+  const customDir = path.join(root, (config.tools && config.tools.custom_dir) || "custom-tools");
+  registerCustomTools(tools, customDir);
+  // 文档加载器 (RAG: read_document / ingest_document)
+  registerDocumentTools(tools, { rootDir: root });
+  // 向量化: 配了 config.embedding 则自动注入 embedder, 检索切 dense+BM25 RRF; 否则纯 BM25 兜底
+  const embedder = embedderFromConfig(config);
+  if (embedder) facts.setEmbedder(embedder);
+  // 多 agent 自主协作: spawn_agent 工具 (agent 自主派生子 agent 分工)
+  registerDelegateTools(tools, {});
+  // Shell 能力 seam: 命令执行解耦为可替换 provider (本地/未来沙箱/Docker)
+  ctx.provide("shell", new LocalShellProvider());
+  // 审计哈希链接入工具执行收口 (未启用时为 null, catalog 内部零开销跳过)
+  tools.setAudit(ctx.consume("audit"));
+  // 记忆治理 + 审计校验 + 运维工具 (吸收自 ppx-v2, 共 10 个)
+  registerGovernanceTools(tools, {
+    rootDir: root,
+    dataDir,
+    facts,
+    audit: ctx.consume("audit"),
+    personaStore: ctx.consume("personaStore"),
+    healer: ctx.consume("healer"),
+    experience: ctx.consume("experience"),
+  });
+  ctx.provide("tools", tools);
+  ctx.provide("toolsEnabled", config.tools?.enabled !== false);
+};
+
+export const modePlugin = (ctx) => {
+  const registry = new ModeRegistry();
+  registerDefaultModes(registry);
+  // 更多编排模式 (可插拔): plan-exec / router / blackboard / graph
+  registry.register("plan-exec", planExecExecutor);
+  registry.register("router", routerExecutor);
+  registry.register("blackboard", blackboardExecutor);
+  registry.register("graph", graphExecutor);
+  registry.register("legion", legionExecutor);
+  ctx.provide("modes", registry);
+};
+
+// P2⑧: 内置插件权限位 (函数外赋值, compose 调用前即可读)
+//   tools/shell 属敏感服务 (SENSITIVE_SERVICES), 需 full-access
+toolsPlugin.access = "full-access";
+
+export const evolvePlugin = (ctx) => {
+  // P1④⑤⑥: 进化系插件 —— Playbook 引擎 / 记忆健康监控 / 故障记忆
+  // P2⑥⑦: 符号画布 / 会话 fork 基线
+  // 提供服务, 消费方按需取用; 未接线时零开销 (不强制)。
+  const dataDir = ctx.consume("dataDir");
+  ctx.provide("playbook", new PlaybookStore(dataDir));
+  ctx.provide("memoryHealth", new MemoryHealthMonitor());
+  ctx.provide("failures", new FailureEpisodeStore(dataDir));
+  ctx.provide("canvas", new CanvasStore(dataDir));
+  ctx.provide("fork", forkTools);
+  ctx.provide("assets", new AssetHub(dataDir)); // P3⑩: 记忆资产中枢
+};
+
+// 默认内置插件装配顺序 (依赖在前)
+export const builtinPlugins = [
+  busPlugin, // ②循环系: 全局总线必须最先 (依赖在前)
+  healerPlugin,
+  personaPlugin,
+  factsPlugin,
+  experiencePlugin,
+  sessionPlugin,
+  memoryPlugin,
+  llmPlugin,
+  memoryLayersPlugin,
+  tracesPlugin,
+  auditPlugin, // 审计哈希链 (toolsPlugin 依赖它注入 catalog, 必须在前)
+  toolsPlugin,
+  evolvePlugin, // P1: playbook / memoryHealth / failures (tools 之后, 依赖 dataDir)
+  modePlugin,
+];

package/src/plugin/context.js

@@ -0,0 +1,79 @@
+// src/plugin/context.js - 轻量服务注册表 (零依赖插件系统核心)
+// 借鉴 deepseek-harness 的 Cordis "everything is a plugin" 理念, 但零依赖、同步、极简:
+//   - 插件 = (ctx) => void 函数, 通过 ctx.provide(key, value) 注册服务, ctx.consume(key) 消费服务
+//   - 注册是可逆效果: ctx.onDispose(fn) 挂卸载钩子, ctx.dispose() 逆序执行
+//   - 支持父子 context: 子 context 的 consume 会向父查找 (用于 agent 内 scope 隔离)
+// P2⑧ (2026-09-15): 插件两级权限 (吸收 HanaAgent restricted/full-access 思想) ——
+//   敏感服务 (路由/生命周期/页面/工具链) 只允许 full-access 插件注册; restricted 插件
+//   只能注册普通服务。compose 时校验, 违规注册直接拒绝 (代码强制, 不靠约定)。
+export const PLUGIN_ACCESS = { RESTRICTED: "restricted", FULL: "full-access" };
+
+// 敏感服务: 仅 full-access 插件可注册 (注册到这些 key 会触发权限校验)
+const SENSITIVE_SERVICES = new Set([
+  "routes",        // HTTP 路由
+  "lifecycle",     // 生命周期钩子
+  "tools",         // 工具链
+  "shell",         // 命令执行
+  "pages",         // 页面
+  "providers",     // LLM provider
+  "extensions",    // 扩展
+]);
+
+export class Context {
+  constructor(parent = null, { access = PLUGIN_ACCESS.RESTRICTED } = {}) {
+    this.parent = parent;
+    this.access = access;       // P2⑧: 当前插件权限位
+    this._services = new Map(); // key -> value
+    this._disposers = [];       // 可逆效果 (dispose 时逆序执行)
+  }
+
+  // P2⑧: 切换权限位 —— 返回共享同一存储的包装 (原型继承), 仅 access 不同。
+  // 这样 restricted 插件注册的普通服务, 顶层 ctx.consume 也能查到 (服务仍全局可见),
+  // 但敏感 key 注册会被拒绝。
+  withAccess(access) {
+    const wrapper = Object.create(this);
+    wrapper.access = access;
+    return wrapper;
+  }
+
+  // 注册服务 (返回 value 便于链式)
+  provide(key, value) {
+    // P2⑧: 敏感服务权限校验 —— restricted 插件注册敏感 key 被拒
+    if (SENSITIVE_SERVICES.has(key) && this.access !== PLUGIN_ACCESS.FULL) {
+      throw new Error(`[插件权限] 注册 ${key} 需要 full-access, 当前 ${this.access}`);
+    }
+    this._services.set(key, value);
+    return value;
+  }
+
+  // 消费服务: 先查自己, 再向上查父 context
+  consume(key) {
+    if (this._services.has(key)) return this._services.get(key);
+    if (this.parent) return this.parent.consume(key);
+    return undefined;
+  }
+
+  has(key) {
+    if (this._services.has(key)) return true;
+    if (this.parent) return this.parent.has(key);
+    return false;
+  }
+
+  // 注册可逆效果 (卸载时执行), 返回取消函数
+  onDispose(fn) {
+    this._disposers.push(fn);
+    return () => {
+      const i = this._disposers.indexOf(fn);
+      if (i >= 0) this._disposers.splice(i, 1);
+    };
+  }
+
+  // 卸载: 逆序执行所有 disposer
+  async dispose() {
+    for (const fn of [...this._disposers].reverse()) {
+      try { await fn(); } catch {}
+    }
+    this._disposers = [];
+    this._services.clear();
+  }
+}

package/src/plugin/index.js

@@ -0,0 +1,62 @@
+// src/plugin/index.js - 插件装配器
+// compose(ctx, plugins): 按顺序装配插件 (同步), 返回 ctx 便于链式
+// 插件 = (ctx) => void, 在函数内用 ctx.provide 注册服务、ctx.consume 消费依赖、ctx.onDispose 挂卸载钩子
+// P2⑧: 插件可声明权限 (plugin.access = 'full-access'), 声明方式: 插件函数挂 access 属性 或 导出对象带 access。
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { info, warn } from "../utils/logger.js";
+import { Context, PLUGIN_ACCESS } from "./context.js";
+
+export { Context } from "./context.js";
+
+// 解析插件权限: 函数自身属性 > 导出对象 access 字段; 默认 restricted
+export function pluginAccess(plugin) {
+  if (typeof plugin === "function" && plugin.access) return plugin.access;
+  if (plugin && plugin.access) return plugin.access;
+  return PLUGIN_ACCESS.RESTRICTED;
+}
+
+// 装配插件树: 顺序执行每个插件的 setup
+// v1.0.9: 单个插件 setup 抛错不中断整条装配链 (隔离失败, 其余插件照常)
+// P2⑧: 每个插件在自己的权限 context 里运行 (敏感服务注册受控)。
+//   full-access 插件直接用父 ctx (服务注册到顶层, agent.consume 可见);
+//   restricted 插件用 withAccess 子 context (注册到子, 父链向上可查, 但敏感 key 被拒)。
+export function compose(ctx, plugins = []) {
+  for (const p of plugins) {
+    try {
+      const access = pluginAccess(p);
+      const pCtx = access === PLUGIN_ACCESS.FULL ? ctx : ctx.withAccess(access);
+      if (typeof p === "function") p(pCtx);
+      else if (p && typeof p.setup === "function") p.setup(pCtx);
+    } catch (e) {
+      warn(`[plugins] setup 失败已隔离: ${(e && e.message) || e}`);
+    }
+  }
+  return ctx;
+}
+
+// 扫描 plugins/ 目录加载用户插件 (声明式, 不改源码扩展 agent)
+// 每个 .cjs 导出插件函数 (ctx) => void 或 { setup(ctx) }
+export function loadPlugins(pluginsDir) {
+  if (!pluginsDir || !fs.existsSync(pluginsDir)) return [];
+  const require = createRequire(import.meta.url);
+  let files = [];
+  try { files = fs.readdirSync(pluginsDir); } catch { return []; }
+  const candidates = files.filter((f) => f.endsWith(".cjs") || f.endsWith(".js")).sort();
+  const plugins = [];
+  for (const f of candidates) {
+    const full = path.join(pluginsDir, f);
+    try {
+      const mod = require(full);
+      const plugin = mod && mod.default ? mod.default : mod;
+      if (typeof plugin === "function") plugins.push(plugin);
+      else if (plugin && typeof plugin.setup === "function") plugins.push(plugin);
+      else warn(`[plugins] ${f} 需导出插件函数 (ctx) => void, 跳过`);
+    } catch (e) {
+      warn(`[plugins] 加载 ${f} 失败: ${e.message}`);
+    }
+  }
+  if (plugins.length) info(`[plugins] 已加载 ${plugins.length} 个自定义插件`);
+  return plugins;
+}

package/src/seam/registry.js

@@ -0,0 +1,98 @@
+// src/seam/registry.js - 通用能力缝注册表 (P0③ seam 骨架)
+// 吸收 deepseek-harness 的 "Service Definition / Service Provider / Consumer" 三分法 + dsh 的 "一个 provider 换整个产品"。
+// 与 src/tools/seam.js (工具级能力缝) 互补: 这里管"服务级可替换能力" (shell/fs/embedder/...),
+//   工具级管"单个工具的 Definition/Provider/Consumer"。
+// 零依赖, 纯 Node 原生。用法:
+//   const reg = createSeamRegistry();
+//   reg.define("shell", { def: "命令执行接口", impl: LocalShellProvider, consumers: ["run_command", "code_act"] });
+//   reg.provide("shell", new LocalShellProvider());        // 注册实现
+//   reg.resolve("shell");                                  // 取实现 (消费方)
+//   reg.swap("shell", new SandboxShellProvider());          // 一行换实现, 消费方跟着切
+//   reg.status();                                          // 可观测: 哪些 seam 有实现/缺实现
+export class SeamRegistry {
+  constructor() {
+    this.seams = new Map(); // key -> { def, implClass, impl, consumers: [], swapped: false }
+  }
+
+  // ---- Service Definition 声明 ----
+  // def: { desc, interface: [方法名], consumers: [消费方标识] } 或字符串描述
+  define(key, def = {}) {
+    if (!key || typeof key !== "string") throw new Error("seam.define: 需 key");
+    const existing = this.seams.get(key);
+    if (existing) {
+      // 幂等: 已存在则合并元数据, 不覆盖已装实现
+      if (def.consumers) existing.consumers = [...new Set([...existing.consumers, ...def.consumers])];
+      if (def.desc) existing.desc = def.desc;
+      return existing;
+    }
+    const seam = {
+      key,
+      desc: def.desc || "",
+      interface: Array.isArray(def.interface) ? def.interface : [],
+      consumers: Array.isArray(def.consumers) ? def.consumers : [],
+      impl: null,
+      implName: null,
+      swapped: false,
+    };
+    this.seams.set(key, seam);
+    return seam;
+  }
+
+  // ---- Service Provider 提供 ----
+  // impl: 实现实例 (或工厂函数返回实例)
+  provide(key, impl, { name = "" } = {}) {
+    if (!this.seams.has(key)) this.define(key);
+    const seam = this.seams.get(key);
+    seam.impl = typeof impl === "function" ? impl() : impl;
+    seam.implName = name || (seam.impl && seam.impl.constructor ? seam.impl.constructor.name : "anonymous");
+    return seam;
+  }
+
+  // ---- Consumer 消费 ----
+  resolve(key) {
+    const seam = this.seams.get(key);
+    return seam && seam.impl ? seam.impl : null;
+  }
+
+  // 解析 + 缺失报错 (消费方友好)
+  require(key) {
+    const impl = this.resolve(key);
+    if (!impl) throw new Error(`seam 缺失实现: ${key} (已声明, 未 provide)`);
+    return impl;
+  }
+
+  // ---- 热替换: 一行换实现, 消费方跟着切 ----
+  swap(key, impl, { name = "" } = {}) {
+    const seam = this.define(key);
+    seam.impl = typeof impl === "function" ? impl() : impl;
+    seam.implName = name || (seam.impl && seam.impl.constructor ? seam.impl.constructor.name : "anonymous");
+    seam.swapped = true;
+    seam.swappedAt = Date.now();
+    return seam;
+  }
+
+  // ---- 可观测 ----
+  status() {
+    const out = [];
+    for (const seam of this.seams.values()) {
+      out.push({
+        key: seam.key,
+        desc: seam.desc,
+        impl: seam.implName,
+        ready: !!seam.impl,
+        swapped: seam.swapped,
+        consumers: [...seam.consumers],
+      });
+    }
+    return out;
+  }
+
+  has(key) { return this.seams.has(key) && !!this.seams.get(key).impl; }
+  keys() { return [...this.seams.keys()]; }
+}
+
+export function createSeamRegistry() {
+  return new SeamRegistry();
+}
+
+export default SeamRegistry;