ppxans-harness 2.6.0 → 3.2.1

package/src/bus/circuit-breaker.js

@@ -15,6 +15,7 @@ export class CircuitBreaker {
     this._state = "closed";              // closed | open | half_open
     this._failures = [];                 // 窗口内失败时间戳
     this._openedAt = 0;
+    this._probeAt = 0;                   // half_open 探测放行时刻 (探测超时兜底用)
     this._calls = 0;
     this._opens = 0;
     this._probeFailures = 0;
@@ -36,12 +37,19 @@ export class CircuitBreaker {
     if (this._state === "open") {
       if (now - this._openedAt >= this.cooldownMs) {
         this._state = "half_open";
+        this._probeAt = now;
         return { allowed: true, probe: true }; // 探测放行
       }
       if (this.failPolicy === "fail-closed") return { allowed: false, reason: "circuit-open" };
       return { allowed: true, degraded: true }; // fail-open: 放行但标记降级
     }
-    // half_open: 只放一个探测, 其余短路
+    // half_open: 只放一个探测, 其余短路。
+    // 2026-09-18 修复 (P2): 探测方若从不回报 after() (调用方遗漏/崩溃), 原实现永久卡死在
+    //   half_open 全拒绝。兜底: 探测放行超过一个冷却期仍无回报, 允许重新探测。
+    if (now - this._probeAt >= this.cooldownMs) {
+      this._probeAt = now;
+      return { allowed: true, probe: true, reprobe: true };
+    }
     return { allowed: false, reason: "circuit-half-open" };
   }
 

package/src/bus/runtime-bus.js

@@ -1,94 +1,108 @@
-// 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 = []; }
-}
-
+import { debug } from "../utils/logger.js";
+// 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 (e) { debug(`[bus/runtime-bus] 已忽略异常: ${e && e.message ? e.message : e}`); } }
+    // 2026-09-18 修复 (P1): on("*") 通配订阅此前从不分发 (emit 只查精确 type),
+    //   trace() 与一切 "*" 观察者永久空转。现补齐通配分发 (精确 set 之后)。
+    if (type !== "*") {
+      const wild = this._events.get("*");
+      if (wild) for (const fn of wild) { try { fn(ev); } catch (e) { debug(`[bus/runtime-bus] 已忽略异常: ${e && e.message ? e.message : e}`); } }
+    }
+    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;
+      let timer = null;
+      // finish 时清掉超时定时器: 否则每个 command 都把事件循环挂住 timeoutMs
+      const finish = (r) => {
+        if (done) return;
+        done = true;
+        if (timer) { clearTimeout(timer); timer = null; }
+        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) timer = 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

@@ -1,35 +1,58 @@
-// 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;
-  }
+// src/channels/base.js - 通道基类
+// 统一通道接口: 每个通道实现 connect/send/disconnect
+// 可选能力: test() 连通性探测 (配置是否可用), mount(server) 把 webhook 路由挂到 HTTP server
+import { readBody, sendJson } from "../utils/http.js";
+
+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; }
+
+  // ---- webhook 型通道的公共辅助 (2026-09-18 重构: feishu/wechat 原各抄一份) ----
+
+  // 路由注册器: 优先注册到主 HTTP 通道的统一路由表 (单一 request handler 分发, 无多 listener 竞态);
+  // 未提供主通道时退化为挂到 server 的 request 事件 (仅路径匹配, 调用方自行防双响应)
+  _registrar(server, httpChannel) {
+    if (httpChannel && typeof httpChannel.registerWebhook === "function") {
+      return (path, fn) => httpChannel.registerWebhook(path, fn);
+    }
+    return (path, fn) => { if (server && typeof server.on === "function") server.on("request", fn); };
+  }
+
+  // 读满请求体 (webhook 回调用, 无大小限制 —— 各通道自行校验内容)
+  _readBody(req) {
+    return readBody(req);
+  }
+
+  // 统一的 JSON 响应
+  _sendJson(res, code, obj) {
+    sendJson(res, code, obj);
+  }
+
+  // 收到消息 → 调 agent 处理 → 回发
+  async handleMessage(from, text) {
+    const reply = await this.agent.chat(text);
+    await this.send(from, reply);
+    return reply;
+  }
 }

package/src/channels/feishu.js

@@ -1,127 +1,119 @@
-// 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;
-  }
+// 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 = this._registrar(server, httpChannel);
+    register(this.webhookPath, async (req, res) => {
+      const body = await this._readBody(req);
+      // 飞书事件订阅用请求头 X-Lark-Request-Token 携带 verify_token (body 内 token 极少存在, 仅作纵深)
+      if (this.verifyToken && req.headers["x-lark-request-token"] !== this.verifyToken) {
+        return this._sendJson(res, 403, { error: "invalid token" });
+      }
+      try {
+        return this._sendJson(res, 200, await this.handleWebhook(body));
+      } catch (e) {
+        return this._sendJson(res, 500, { 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;
+  }
 }