ppxans-harness 2.4.0

package/src/bus/runtime-bus.js

@@ -0,0 +1,94 @@
+// src/bus/runtime-bus.js - ②循环系: 全局 Runtime 总线 (RC1 §2 动态行为层地基)
+// 在 session.js 会话事件日志之上新增一层"全局总线", 打通模块间函数直连的接缝:
+//   - Event:   事实广播 (发生了什么), 只读, 谁都能订阅
+//   - Command: 意图 (要执行什么), 带 id + 处理器, 返回 Result
+//   - State:   全局运行时状态槽 (可读写, 供①/⑦读倾向, 供观测)
+// 零依赖, 纯 Node 原生。设计对齐 RC1 §5.2 总线消息类型。
+export class RuntimeBus {
+  constructor({ name = "runtime", historyLimit = 200 } = {}) {
+    this.name = name;
+    this._events = new Map();        // type -> Set<handler>
+    this._handlers = new Map();      // verb -> handler
+    this._state = new Map();         // 状态槽
+    this._history = [];              // 最近事件 (可观测/审计)
+    this._historyLimit = historyLimit;
+    this._seq = 0;                   // 全局序列
+    this._interceptors = [];         // 命令前置拦截器 (⑧免疫可挂闸门)
+  }
+
+  // ---------- Event (事实广播, 只读) ----------
+  emit(type, payload = {}, meta = {}) {
+    this._seq++;
+    const ev = { seq: this._seq, ts: Date.now(), type, payload, meta };
+    this._history.push(ev);
+    if (this._history.length > this._historyLimit) this._history.shift();
+    const set = this._events.get(type);
+    if (set) for (const fn of set) { try { fn(ev); } catch {} }
+    return ev;
+  }
+
+  on(type, handler) {
+    if (!this._events.has(type)) this._events.set(type, new Set());
+    this._events.get(type).add(handler);
+    return () => this.off(type, handler);
+  }
+
+  off(type, handler) {
+    const set = this._events.get(type);
+    if (set) set.delete(handler);
+  }
+
+  // ---------- Command (意图 + 处理器, 返回 Result) ----------
+  command(verb, payload = {}, { timeoutMs = 0 } = {}) {
+    return new Promise((resolve) => {
+      const handler = this._handlers.get(verb);
+      if (!handler) return resolve({ ok: false, error: `no-command-handler:${verb}`, payload });
+      let done = false;
+      const finish = (r) => { if (done) return; done = true; resolve(r); };
+      const id = `${verb}:${this._seq++}`;
+      const cmd = { id, ts: Date.now(), verb, payload };
+      // 拦截器链 (⑧免疫: 可在执行前做权限/风险校验, 拒绝则短路)
+      const run = async (i) => {
+        if (i >= this._interceptors.length) {
+          try { finish(await handler(cmd)); }
+          catch (e) { finish({ ok: false, error: String(e?.message || e), cmdId: id }); }
+          return;
+        }
+        try {
+          await this._interceptors[i](cmd, () => run(i + 1));
+        } catch (e) {
+          finish({ ok: false, error: String(e?.message || e), cmdId: id, blocked: true });
+        }
+      };
+      run(0);
+      if (timeoutMs > 0) setTimeout(() => finish({ ok: false, error: "command-timeout", cmdId: id }), timeoutMs);
+      this.emit("command", { id, verb, payload });
+    });
+  }
+
+  register(verb, handler) { this._handlers.set(verb, handler); return this; }
+
+  // 命令前置拦截器 (⑧免疫闸门挂载点)
+  intercept(fn) { this._interceptors.push(fn); return () => { const i = this._interceptors.indexOf(fn); if (i >= 0) this._interceptors.splice(i, 1); }; }
+
+  // ---------- State (运行时状态槽) ----------
+  get(key, fallback) {
+    if (!this._state.has(key)) return fallback;
+    return this._state.get(key);
+  }
+  set(key, value) { this._state.set(key, value); this._state._rev = (this._state._rev || 0) + 1; this.emit("state", { key, value }); return value; }
+  has(key) { return this._state.has(key); }
+
+  // ---------- 观测/审计 ----------
+  // 最近事件 (含 command), 供 trace/调试/审计拉取
+  recent(n = 50) { return this._history.slice(-n); }
+  // 挂总线之旅: 返回可断开回放的订阅器 (调试用)
+  trace() {
+    const out = [];
+    const off = this.on("*", (ev) => out.push(ev));
+    return { events: out, stop: off };
+  }
+  clearHistory() { this._history = []; }
+}
+
+export default RuntimeBus;

package/src/channels/base.js

@@ -0,0 +1,35 @@
+// src/channels/base.js - 通道基类
+// 统一通道接口: 每个通道实现 connect/send/disconnect
+// 可选能力: test() 连通性探测 (配置是否可用), mount(server) 把 webhook 路由挂到 HTTP server
+export class Channel {
+  constructor(name, agent) {
+    this.name = name;
+    this.agent = agent;
+    this.connected = false;
+  }
+
+  async connect() { throw new Error(`${this.name}: connect() 未实现`); }
+  async send(to, text) { throw new Error(`${this.name}: send() 未实现`); }
+  async disconnect() { this.connected = false; }
+
+  // 连通性测试: 默认尝试 connect (验证配置能建立连接), 返回 { ok, detail }
+  // 需要网络探测的通道可覆盖为更细的校验 (如验证 token)
+  async test() {
+    try {
+      await this.connect();
+      return { ok: true, detail: `${this.name} 配置有效` };
+    } catch (e) {
+      return { ok: false, detail: e.message };
+    }
+  }
+
+  // 把 webhook 路由挂到 HTTP server (若通道是 webhook 型); 默认不挂载
+  mount(/* httpServer */) { return null; }
+
+  // 收到消息 → 调 agent 处理 → 回发
+  async handleMessage(from, text) {
+    const reply = await this.agent.chat(text);
+    await this.send(from, reply);
+    return reply;
+  }
+}

package/src/channels/feishu.js

@@ -0,0 +1,127 @@
+// src/channels/feishu.js - 飞书通道适配器 (零依赖, 原生 fetch)
+// 需要配置: app_id, app_secret, verify_token (config/channels.yaml)
+// 用法: 飞书开放平台配置事件订阅 URL 指向本服务的 /feishu/webhook
+import { Channel } from "./base.js";
+
+export class FeishuChannel extends Channel {
+  constructor(agent, { appId, appSecret, verifyToken, webhookPath = "/feishu/webhook" } = {}) {
+    super("feishu", agent);
+    this.appId = appId || process.env.FEISHU_APP_ID || "";
+    this.appSecret = appSecret || process.env.FEISHU_APP_SECRET || "";
+    this.verifyToken = verifyToken || process.env.FEISHU_VERIFY_TOKEN || "";
+    this.webhookPath = webhookPath;
+    this.tenantToken = null;
+    this.tokenExpire = 0;
+    this.lastUser = null; // 最近收到消息的 open_id, 供主动提醒(广播)回发
+  }
+
+  // 主动提醒广播 (to="*") 时回最近联系人; 无记录则报缺接收人
+  _resolveTarget(to) {
+    const target = !to || to === "*" ? this.lastUser : to;
+    return target || null;
+  }
+
+  async _getTenantToken() {
+    if (this.tenantToken && Date.now() < this.tokenExpire) return this.tenantToken;
+    const r = await fetch("https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ app_id: this.appId, app_secret: this.appSecret }),
+      signal: AbortSignal.timeout(15000), // v1.0.8: 网络挂起不永久阻塞
+    });
+    const data = await r.json();
+    if (data.code !== 0) throw new Error(`飞书 token 失败: ${data.msg}`);
+    this.tenantToken = data.tenant_access_token;
+    this.tokenExpire = Date.now() + (data.expire - 60) * 1000;
+    return this.tenantToken;
+  }
+
+  async connect() {
+    if (!this.appId || !this.appSecret) {
+      throw new Error("飞书通道未配置: 需要 app_id + app_secret (config/channels.yaml 或环境变量)");
+    }
+    await this._getTenantToken(); // 验证凭证
+    this.connected = true;
+    return this;
+  }
+
+  // 连通性测试: 用已配置凭证换取 tenant token (真实网络验证)
+  async test() {
+    if (!this.appId || !this.appSecret) {
+      return { ok: false, detail: "未配置 app_id + app_secret" };
+    }
+    try {
+      const token = await this._getTenantToken();
+      return { ok: true, detail: `飞书凭证有效 (tenant_token 获取成功, ${String(token).slice(0, 6)}...)` };
+    } catch (e) {
+      return { ok: false, detail: e.message };
+    }
+  }
+
+  // 把 /feishu/webhook 挂到 HTTP server (webhook 型通道)
+  // v1.0.8: 注册到 HttpChannel 的 webhook 路由 (单一 request handler 分发, 无多 listener 竞态);
+  // 校验飞书事件订阅头 X-Lark-Request-Token
+  mount(server, httpChannel = null) {
+    const register = httpChannel && typeof httpChannel.registerWebhook === "function"
+      ? (path, fn) => httpChannel.registerWebhook(path, fn)
+      : (path, fn) => { /* 无主通道时挂到 server (仅路径匹配, 调用方负责防双响应) */ server && server.on?.("request", fn); };
+    register(this.webhookPath, async (req, res) => {
+      let body = "";
+      for await (const c of req) body += c;
+      // 飞书事件订阅用请求头 X-Lark-Request-Token 携带 verify_token (body 内 token 极少存在, 仅作纵深)
+      if (this.verifyToken && req.headers["x-lark-request-token"] !== this.verifyToken) {
+        res.writeHead(403, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "invalid token" }));
+        return;
+      }
+      try {
+        const out = await this.handleWebhook(body);
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(out));
+      } catch (e) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: e.message }));
+      }
+    });
+  }
+
+  // 处理飞书 webhook 事件 (事件订阅回调)
+  async handleWebhook(body) {
+    // 校验 verify_token (纵深防御; 主校验在 mount 的 X-Lark-Request-Token 头)
+    const data = typeof body === "string" ? JSON.parse(body) : body;
+    if (data.token && data.token !== this.verifyToken) {
+      return { code: 1, msg: "invalid token" };
+    }
+    // URL 验证 (飞书首次配置时)
+    if (data.type === "url_verification") {
+      return { challenge: data.challenge };
+    }
+    // 事件: 消息
+    const event = data.event;
+    if (event && event.type === "im.message.receive_v1" && event.message) {
+      const text = event.message.content ? JSON.parse(event.message.content).text || "" : "";
+      const openId = event.sender?.sender_id?.open_id || "";
+      if (openId) this.lastUser = openId; // 记录最近联系人, 供主动提醒回发
+      if (text) {
+        const reply = await this.agent.chat(text);
+        await this.send(openId || "*", reply);
+      }
+    }
+    return { code: 0 };
+  }
+
+  async send(to, text) {
+    const target = this._resolveTarget(to);
+    if (!target) throw new Error("飞书主动推送缺接收人: 先收到过一条用户消息记录 open_id, 或用 send(openId, ...)");
+    const token = await this._getTenantToken();
+    const r = await fetch("https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id", {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "Authorization": `Bearer ${token}` },
+      body: JSON.stringify({ receive_id: target, msg_type: "text", content: JSON.stringify({ text }) }),
+      signal: AbortSignal.timeout(15000), // v1.0.8: 网络挂起不永久阻塞
+    });
+    const data = await r.json();
+    if (data.code !== 0) throw new Error(`飞书发送失败: ${data.msg}`);
+    return data;
+  }
+}