ppxans-harness 2.4.0 → 3.2.0

package/src/plugin/context.js

@@ -1,79 +1,80 @@
-// 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();
-  }
-}
+import { debug } from "../utils/logger.js";
+// 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 (e) { debug(`[plugin/context] 已忽略异常: ${e && e.message ? e.message : e}`); }
+    }
+    this._disposers = [];
+    this._services.clear();
+  }
+}

package/src/plugin/index.js

@@ -1,62 +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;
-}
+// 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/plugin/v3.js

@@ -0,0 +1,73 @@
+// src/plugin/v3.js - v3.0 新层装配插件 (protocol/session/permissions/hooks/commands/evidence)
+// codex 对齐升级: 权限引擎 + 钩子链 + 斜杠命令 + 目标看板, 全部走「一切皆插件」装配, 可被用户插件替换。
+import path from "node:path";
+import { createHookRegistry } from "../hooks/index.js";
+import {
+  createPermissionEngine,
+  AskForApproval,
+  SandboxPolicy,
+} from "../permissions/index.js";
+import { createRegistryWithUserCommands } from "../commands/index.js";
+import { createGoalBoard } from "../evidence/index.js";
+import { createProtocolBus } from "../protocol/index.js";
+import { info } from "../utils/logger.js";
+
+// 钩子链插件: claude-code 六事件 (PreToolUse/PostToolUse/PreCompact/SessionStart/...)
+export const hooksPlugin = (ctx) => {
+  ctx.provide("hooks", createHookRegistry());
+};
+
+// 权限引擎插件: codex AskForApproval 四档 + SandboxPolicy 三档 + opencode 规则链
+// 配置: config.agent.approval_mode / config.agent.sandbox / config.agent.network_access
+export const permissionsPlugin = (ctx) => {
+  const config = ctx.consume("config");
+  const agentCfg = config.agent || {};
+  const engine = createPermissionEngine({
+    approvalMode: agentCfg.approval_mode || AskForApproval.ON_REQUEST,
+    sandbox: agentCfg.sandbox || SandboxPolicy.WORKSPACE_WRITE,
+    workspaceRoot: ctx.consume("root"),
+    networkAccess: agentCfg.network_access !== false,
+    rules: Array.isArray(agentCfg.permission_rules) ? agentCfg.permission_rules : [],
+  });
+  // 用户自定义规则: [{pattern, action}] (opencode 风格, 有序 last-match-wins)
+  for (const r of Array.isArray(agentCfg.permission_rules) ? agentCfg.permission_rules : []) {
+    if (r && r.pattern && r.action) engine.addRule(r.pattern, r.action);
+  }
+  ctx.provide("permissions", engine);
+};
+
+// 斜杠命令插件: claude-code 统一命令模型 + 用户命令目录 .ppx/commands/*.md
+export const commandsPlugin = (ctx) => {
+  const root = ctx.consume("root");
+  const registry = createRegistryWithUserCommands(path.join(root, ".ppx", "commands"));
+  ctx.provide("commands", registry);
+};
+
+// 证据/看板插件: OMH prepared/observed 边界 + goal board 目标看板
+export const evidencePlugin = (ctx) => {
+  ctx.provide("goalBoard", createGoalBoard());
+};
+
+// 协议总线插件: codex SQ/EQ 双队列
+// 2026-10-03 接线 (P2): WAL 原硬编码 null (注释宣称"默认 data/protocol/eq.jsonl" 但从未开启) →
+// 默认落盘 data/protocol/eq.wal.jsonl (config.protocol.wal_enabled=false 可关), 支持崩溃后 replay()。
+// EQ 事件另有真实消费方: channels/http.js 订阅后经 SSE /events 广播给 Web UI 时间线。
+export const protocolPlugin = (ctx) => {
+  const dataDir = ctx.consume("dataDir");
+  const config = ctx.consume("config") || {};
+  const walEnabled = config?.protocol?.wal_enabled !== false;
+  const bus = createProtocolBus({
+    walPath: walEnabled && dataDir ? path.join(dataDir, "protocol", "eq.wal.jsonl") : null,
+  });
+  ctx.provide("protocolBus", bus);
+  info(`[v3] 协议总线就绪 (SQ/EQ${walEnabled ? " + WAL" : ""})`);
+};
+
+// v3 全量插件组 (builtinPlugins 之后追加装配)
+export const v3Plugins = [
+  hooksPlugin,
+  permissionsPlugin,
+  commandsPlugin,
+  evidencePlugin,
+  protocolPlugin,
+];

package/src/protocol/index.js

@@ -0,0 +1,148 @@
+// src/protocol/index.js - SQ/EQ 双队列事件流 (对齐 OpenAI Codex SubmissionQueue/EventQueue)
+// 通道层与内核解耦的唯一总线:
+//   SubmissionQueue: 用户操作入队 (op = {id, type, payload}), 先提交先处理
+//   EventQueue:       结构化事件出队 + 订阅回调 + WAL 回放 (JSONL)
+import fs from "node:fs";
+import path from "node:path";
+
+// 操作类型 (用户侧动作, 进 SQ)
+export const OpType = {
+  USER_TURN: "user_turn",
+  INTERRUPT: "interrupt",
+  RESUME: "resume",
+  APPROVE: "approve",
+  DENY: "deny",
+};
+
+// 事件类型 (内核产出, 供 Web UI 时间线渲染, 进 EQ)
+export const EventType = {
+  TASK_STARTED: "task_started",
+  AGENT_MESSAGE: "agent_message",
+  TOOL_CALLED: "tool_called",
+  TOOL_OUTPUT: "tool_output",
+  APPROVAL_REQUESTED: "approval_requested",
+  APPROVAL_RESOLVED: "approval_resolved",
+  TASK_COMPLETE: "task_complete",
+  TASK_ABORTED: "task_aborted",
+  TURN_DIFF: "turn_diff",
+  ERROR: "error",
+  TOKEN_COUNT: "token_count",
+  PLAN_UPDATED: "plan_updated",
+  COMPACTED: "compacted",
+};
+
+// SubmissionQueue: 用户操作入队, 内部数组队列, 先提交先处理
+export function createSubmissionQueue() {
+  let _seq = 0;
+  const queue = [];
+
+  // 默认 id: t_<时间戳>_<自增序号> (对齐 codex Id::UnixMs 唯一性)
+  function _newId() {
+    _seq += 1;
+    return `t_${Date.now()}_${_seq}`;
+  }
+
+  // 提交一个操作, 返回分配/给定的 id
+  function submit(op = {}) {
+    const id = op.id || _newId();
+    queue.push({ id, type: op.type, payload: op.payload });
+    return id;
+  }
+
+  // 取出最早一个未处理 op 并出队 (无则 null) — 对齐 codex nextIdle 语义
+  function nextIdle() {
+    return queue.length ? queue.shift() : null;
+  }
+
+  // 取走全部 op 并清空队列
+  function drain() {
+    const out = queue.splice(0, queue.length);
+    return out;
+  }
+
+  return { submit, nextIdle, drain };
+}
+
+// EventQueue: 结构化事件出队 + 订阅回调 + WAL 回放
+export function createEventQueue({ walPath = null } = {}) {
+  let _seq = 0;
+  const events = [];   // 内存历史
+  const subs = [];     // 订阅回调
+
+  // WAL 目录不存在先建 (递归)
+  if (walPath) {
+    const dir = path.dirname(walPath);
+    if (dir && !fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // 推送一个事件: ev = {id?, ts?, type, payload}; seq 自增
+  function push(ev) {
+    _seq += 1;
+    const full = {
+      id: ev.id || `e_${Date.now()}_${_seq}`,
+      ts: ev.ts || Date.now(),
+      seq: _seq,
+      type: ev.type,
+      payload: ev.payload,
+    };
+    events.push(full);
+    // 同步落 WAL (JSONL, 一行一 JSON)
+    if (walPath) {
+      fs.appendFileSync(walPath, JSON.stringify(full) + "\n", "utf8");
+    }
+    // 同步通知订阅回调 (单个回调异常不影响事件流)
+    for (const fn of subs) {
+      try { fn(full); } catch { /* 订阅回调不应中断事件流 */ }
+    }
+    return full;
+  }
+
+  // 订阅: 返回取消订阅函数
+  function subscribe(fn) {
+    subs.push(fn);
+    return () => {
+      const i = subs.indexOf(fn);
+      if (i >= 0) subs.splice(i, 1);
+    };
+  }
+
+  // 回放 WAL: 读文件返回全部事件
+  function replay() {
+    if (!walPath || !fs.existsSync(walPath)) return [];
+    const out = [];
+    for (const line of fs.readFileSync(walPath, "utf8").split("\n").filter(Boolean)) {
+      try { out.push(JSON.parse(line)); } catch { /* 跳过损坏行 */ }
+    }
+    return out;
+  }
+
+  // 内存历史快照
+  function history() {
+    return [...events];
+  }
+
+  return { push, subscribe, replay, history };
+}
+
+// createProtocolBus: 便捷工厂 — 把 SQ/EQ 与常用提交动作打包
+export function createProtocolBus({ walPath } = {}) {
+  const sq = createSubmissionQueue();
+  const eq = createEventQueue({ walPath });
+
+  // 提交一个用户回合 (USER_TURN op)
+  function submitUserTurn(text) {
+    return sq.submit({ type: OpType.USER_TURN, payload: { text } });
+  }
+
+  // 中断当前回合 (INTERRUPT op)
+  function interrupt() {
+    return sq.submit({ type: OpType.INTERRUPT, payload: {} });
+  }
+
+  // 关闭总线 (无持久连接, 留作未来扩展点)
+  function close() {
+    /* noop */
+  }
+
+  return { sq, eq, submitUserTurn, interrupt, close };
+}