@ai-setting/roy-agent-core 1.7.77 → 1.7.88

package/dist/env/event-source/wecom-respond-registry.js

@@ -0,0 +1,33 @@
+import {
+  __resetWecomReplySentForTest,
+  __resetWecomRespondRegistryForTest,
+  autoReplyWecomTurn,
+  getWecomRespondTarget,
+  markWecomReplySent,
+  registerWecomRespondTarget,
+  sendWecomReply,
+  sendWecomTemplateCard,
+  unregisterWecomRespondTarget,
+  wasWecomReplySent,
+  wecomRespondTool
+} from "../../shared/@ai-setting/roy-agent-core-h1e1fm9b.js";
+import"../../shared/@ai-setting/roy-agent-core-c4ec7k0p.js";
+import"../../shared/@ai-setting/roy-agent-core-418zc9ha.js";
+import"../../shared/@ai-setting/roy-agent-core-p31ftgq9.js";
+import"../../shared/@ai-setting/roy-agent-core-5s2t8z00.js";
+import"../../shared/@ai-setting/roy-agent-core-7f7t9wwp.js";
+import"../../shared/@ai-setting/roy-agent-core-85xyctnb.js";
+import"../../shared/@ai-setting/roy-agent-core-fs0mn2jk.js";
+export {
+  wecomRespondTool,
+  wasWecomReplySent,
+  unregisterWecomRespondTarget,
+  sendWecomTemplateCard,
+  sendWecomReply,
+  registerWecomRespondTarget,
+  markWecomReplySent,
+  getWecomRespondTarget,
+  autoReplyWecomTurn,
+  __resetWecomRespondRegistryForTest,
+  __resetWecomReplySentForTest
+};

package/dist/env/event-source/wecom-session-card-sender.d.ts

@@ -0,0 +1,135 @@
+/**
+ * @fileoverview Task #5360 —— 企微 **session 卡发送器**（无 task 的 sub-session）
+ *
+ * ## 用户需求
+ *
+ * > 「企微也是这个逻辑哈」（22:32）+「以 sub-session 为基底」（22:37）
+ *
+ * ## 为什么单独一个模块（不复用 lark 的 sessionCardSender）
+ *
+ * 飞书发卡是 `lark-cli im +messages-send --msg-type interactive`（spawn 子进程）；
+ * 企微发卡是 WS `aibot_send_msg`（长连接帧）。两条完全不同的传输通道，
+ * 混在一个 sender 里只会靠 if/else 分支，且会把「渠道 guard」的责任
+ * 推给运行时的字符串比较 —— 那正是 R4 抓出的错渠道风险。
+ *
+ * ⇒ 明确分成两个 sender，各自由**渠道自己的**事件路径调用。
+ *
+ * ## 设计（纯函数 + 端口注入，便于单测）
+ *
+ * | 关注点 | 谁负责 |
+ * |--------|--------|
+ * | 卡片长什么样 | `buildWecomSessionCard`（wecom-card-builder，已测） |
+ * | 发到哪 | 本模块的 `resolveWecomSendTarget`（从 event 取 chatId/chatType/sourceId） |
+ * | 怎么发 | `sendCard` 端口（生产接 `sendWecomTemplateCard`） |
+ *
+ * ## 全链路 best-effort
+ *
+ * 任何一步失败（无 chatId / 无 sourceId / 发送报错）都只 log，**绝不抛** ——
+ * 生命周期事件是 fire-and-forget，抛出去会污染事件消费循环。
+ */
+import type { EnvEvent } from "../types";
+import { type WecomSessionLifecycle } from "./wecom-card-builder";
+import { type WecomSessionCardStore } from "../task/plugins/wecom-session-card-store";
+/** 企微发送目标 */
+export interface WecomSessionCardTarget {
+    /** 事件源 ID（WS 实例反查用） */
+    sourceId: string;
+    /** 单聊 = userid；群聊 = 群 chatid */
+    chatId: string;
+    chatType: "single" | "group";
+}
+/**
+ * 从事件里解析企微发送目标。
+ *
+ * ## 渠道判定（为什么这里要显式判断）
+ *
+ * 本 sender 只处理**企微**事件。若把飞书事件的 chatId（`oc_xxx`）当企微
+ * userid 发，WS 会静默丢弃（或报错）—— 与 R4 抓出的「错渠道发送」同一类问题，
+ * 只是方向相反。所以这里要求 `replyChannel.type === "wecom-cli"`，
+ * 判不出来就返回 `undefined`（调用方丢弃，不猜）。
+ *
+ * ## chatType 判定
+ *
+ * 优先 `params.chatType`（`buildWecomReplyChannel` 写入的权威值）；
+ * 缺省时看 `params.wecomChatId` 是否存在 —— 有原始 group chatid ⇒ group。
+ * 都没有 ⇒ `single`（企微单聊的 chatId 就是 userid，官方语义）。
+ */
+export declare function resolveWecomSessionCardTarget(event: EnvEvent): WecomSessionCardTarget | undefined;
+/** 从事件 payload 里取 session 卡需要的信息 */
+export interface WecomSessionCardPayload {
+    sessionId: string;
+    lifecycle: WecomSessionLifecycle;
+    title?: string;
+    agentType?: string;
+    startedAt?: string;
+}
+/**
+ * 解析 `task.background.session_started` 的 payload。
+ *
+ * 缺 `subSessionId` ⇒ `undefined`（没有主键，无从发卡）。
+ * `lifecycle` 非法/缺失 ⇒ `running`（乐观：宁可显示在跑，也不凭空宣布结束）。
+ */
+export declare function parseWecomSessionCardPayload(event: EnvEvent): WecomSessionCardPayload | undefined;
+/** sender 依赖的最小端口集（全部可选 ⇒ 缺了只降级） */
+export interface WecomSessionCardSenderPorts {
+    /**
+     * ★ Task #5364：session 卡持久层（**B 方案的核心**）。
+     *
+     * 一个 session 生命周期内只发一张卡 ⇒ 后续 lifecycle 必须落在这里，
+     * 刷新时才有数据可渲染。不注入 ⇒ 内部用内存实现兜底（同实例内仍只发
+     * 一次；进程重启会重发一张，属于可接受的降级）。
+     */
+    store?: WecomSessionCardStore;
+    /**
+     * 发卡（生产：`sendWecomTemplateCard`）。
+     *
+     * `card` 是 `buildWecomSessionCard` 的输出，原样传给 WS 帧构造。
+     */
+    sendCard?: (input: {
+        sourceId: string;
+        chatId: string;
+        chatType: "single" | "group";
+        card: Record<string, unknown>;
+        /** ★ sessionId（供实现方记录 sessionId→公开消息定位，便于后续 patch/诊断） */
+        sessionId: string;
+    }) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** 日志（测试可注入；缺省 console） */
+    warn?: (msg: string) => void;
+    /** 时间基准（注入便于测试；缺省 Date.now()） */
+    now?: () => number;
+}
+/**
+ * 造一个 `(event) => Promise<void>` 的企微 session 卡 sender。
+ *
+ * **永不抛**：这是 fire-and-forget 生命周期事件的投递路径。
+ *
+ * ## ★ Task #5364 语义变更（用户 2026-11-12 08:34 拍板 B）
+ *
+ * > 「企微改成**只维护一张卡 + 靠按钮触发更新**」
+ *
+ * | 事件 | 旧行为（#5360，被用户否掉） | 新行为（B 方案） |
+ * |------|---------------------------|------------------|
+ * | 首次 lifecycle | 发一张卡 | 发一张卡 + 落库 |
+ * | 后续 lifecycle | **再发一张卡**（刷屏 + 重复 pin） | **不发**，只更新持久层 |
+ * | 用户点「刷新」 | 只刷活性 | 从持久层 + 实时活性重建**整张卡** |
+ *
+ * ## 为什么这是唯一可行的形态（协议硬约束，不是偷懒）
+ *
+ * `aibot_respond_update_msg` 必须在 `template_card_event` 回调的 5 秒窗口内、
+ * 用回调带回的 `req_id` 发（#5203 已真网取证）。生命周期事件不是回调、
+ * 没有 req_id ⇒ **根本发不出 update 帧**。所以「主动 patch」这条路在企微
+ * 上不存在；要「一张卡」只能把更新的机会押在用户点按钮那一刻。
+ *
+ * 反过来：**如果我们仍然每条 lifecycle 都发卡，就不是一张卡** —— 这正是
+ * 用户否掉的形态。所以「后续不发」是本模块最重要的不变量，有测试断言
+ * `sendCard` 调用次数恒为 1。
+ *
+ * ## 发卡失败不落库（重要）
+ *
+ * 否则后续事件会以为「已经有卡了」而永不再发 ⇒ 用户真的一张卡都看不到。
+ * 失败就让它下次事件再试（最多多发一张，也好过零张）。
+ */
+export declare function createWecomSessionCardSender(ports: WecomSessionCardSenderPorts): (event: EnvEvent) => Promise<void>;

package/dist/env/event-source/wecom-session-card-sender.js

@@ -0,0 +1,153 @@
+import {
+  createMemoryWecomSessionCardStore
+} from "../../shared/@ai-setting/roy-agent-core-7kvpc0w5.js";
+import {
+  buildWecomSessionCard
+} from "../../shared/@ai-setting/roy-agent-core-c4ec7k0p.js";
+import"../../shared/@ai-setting/roy-agent-core-418zc9ha.js";
+import"../../shared/@ai-setting/roy-agent-core-6k8mb7zx.js";
+import"../../shared/@ai-setting/roy-agent-core-5s2t8z00.js";
+import"../../shared/@ai-setting/roy-agent-core-7f7t9wwp.js";
+import"../../shared/@ai-setting/roy-agent-core-85xyctnb.js";
+import"../../shared/@ai-setting/roy-agent-core-fs0mn2jk.js";
+
+// src/env/event-source/wecom-session-card-sender.ts
+function resolveWecomSessionCardTarget(event) {
+  const metadata = event?.metadata;
+  const rc = metadata?.replyChannel;
+  if (rc?.type !== "wecom-cli")
+    return;
+  const chatId = typeof rc.chatId === "string" && rc.chatId.trim() ? rc.chatId : undefined;
+  if (!chatId)
+    return;
+  const sourceId = typeof rc.params?.sourceId === "string" && rc.params.sourceId || (typeof metadata?.sourceId === "string" ? metadata.sourceId : undefined);
+  if (!sourceId)
+    return;
+  const chatType = rc.params?.chatType === "group" || rc.params?.chatType === "single" ? rc.params.chatType : rc.params?.wecomChatId ? "group" : "single";
+  return { sourceId, chatId, chatType };
+}
+var LIFECYCLES = new Set([
+  "running",
+  "completed",
+  "timeout",
+  "failed",
+  "stopped"
+]);
+var LIFECYCLE_MILESTONE_PHRASE = {
+  running: "运行中",
+  completed: "已完成",
+  timeout: "已超时",
+  failed: "已失败",
+  stopped: "已停止"
+};
+function parseWecomSessionCardPayload(event) {
+  const p = event?.payload ?? {};
+  const sessionId = typeof p.subSessionId === "string" && p.subSessionId.trim() ? p.subSessionId : undefined;
+  if (!sessionId)
+    return;
+  const lifecycle = typeof p.lifecycle === "string" && LIFECYCLES.has(p.lifecycle) ? p.lifecycle : "running";
+  return {
+    sessionId,
+    lifecycle,
+    ...typeof p.description === "string" && p.description ? { title: p.description } : {},
+    ...typeof p.subagentType === "string" && p.subagentType ? { agentType: p.subagentType } : {},
+    ...typeof p.startedAt === "number" ? { startedAt: new Date(p.startedAt).toISOString() } : {}
+  };
+}
+function parseAssociatedTaskId(event) {
+  const p = event?.payload ?? {};
+  const raw = p.associatedTaskId;
+  const n = typeof raw === "number" ? raw : typeof raw === "string" && /^\d+$/.test(raw.trim()) ? Number(raw) : undefined;
+  return typeof n === "number" && Number.isSafeInteger(n) && n > 0 ? n : undefined;
+}
+function createWecomSessionCardSender(ports) {
+  const warn = ports.warn ?? ((m) => console.warn(m));
+  const store = ports.store ?? createMemoryWecomSessionCardStore();
+  const nowFn = ports.now ?? Date.now;
+  return async (event) => {
+    try {
+      const target = resolveWecomSessionCardTarget(event);
+      if (!target)
+        return;
+      const payload = parseWecomSessionCardPayload(event);
+      if (!payload)
+        return;
+      const existing = store.get(payload.sessionId);
+      const at = nowFn();
+      const milestone = {
+        title: LIFECYCLE_MILESTONE_PHRASE[payload.lifecycle],
+        timestamp: new Date(at).toISOString()
+      };
+      const prevMilestones = (() => {
+        if (!existing?.milestones)
+          return [];
+        try {
+          const arr = JSON.parse(existing.milestones);
+          return Array.isArray(arr) ? arr : [];
+        } catch {
+          return [];
+        }
+      })();
+      const milestones = [...prevMilestones, milestone];
+      const associatedTaskId = parseAssociatedTaskId(event) ?? existing?.associatedTaskId;
+      const terminal = payload.lifecycle !== "running";
+      const persist = (over = {}) => {
+        try {
+          store.upsert({
+            sessionId: payload.sessionId,
+            chatId: target.chatId,
+            chatType: target.chatType,
+            sourceId: target.sourceId,
+            cardTaskId: existing?.cardTaskId ?? "",
+            lifecycle: payload.lifecycle,
+            ...payload.title || existing?.title ? { title: payload.title ?? existing.title } : {},
+            ...payload.agentType || existing?.agentType ? { agentType: payload.agentType ?? existing.agentType } : {},
+            ...payload.startedAt || existing?.startedAt ? { startedAt: payload.startedAt ?? existing.startedAt } : {},
+            ...associatedTaskId !== undefined ? { associatedTaskId } : {},
+            milestones: JSON.stringify(milestones),
+            createdAt: existing?.createdAt ?? at,
+            updatedAt: at,
+            ...terminal ? { closedAt: at } : {},
+            ...over
+          });
+        } catch (err) {
+          warn(`[wecom-session-card] store upsert failed for ${payload.sessionId}: ` + `${err instanceof Error ? err.message : String(err)}`);
+        }
+      };
+      if (!existing) {
+        if (!ports.sendCard)
+          return;
+        const card = buildWecomSessionCard({
+          sessionId: payload.sessionId,
+          lifecycle: payload.lifecycle,
+          ...payload.title ? { title: payload.title } : {},
+          ...payload.agentType ? { agentType: payload.agentType } : {},
+          ...payload.startedAt ? { startedAt: payload.startedAt } : {}
+        });
+        const r = await ports.sendCard({
+          sourceId: target.sourceId,
+          chatId: target.chatId,
+          chatType: target.chatType,
+          card,
+          sessionId: payload.sessionId
+        });
+        if (!r?.ok) {
+          warn(`[wecom-session-card] send failed for ${payload.sessionId}: ` + `${r?.error ?? "unknown"}`);
+          return;
+        }
+        persist({
+          cardTaskId: String(card.task_id ?? payload.sessionId)
+        });
+        return;
+      }
+      persist();
+    } catch (err) {
+      warn(`[wecom-session-card] sender threw: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  };
+}
+export {
+  resolveWecomSessionCardTarget,
+  parseWecomSessionCardPayload,
+  createWecomSessionCardSender
+};

package/dist/env/event-source/wecom-ws-bridge.d.ts

@@ -0,0 +1,213 @@
+/**
+ * @fileoverview Task #5165 — 企微长连接 WebSocket 桥
+ *
+ * ## 为什么自实现（不用 @wecom/aibot-node-sdk）
+ *
+ * 1. core 已依赖 `ws@^8.16.0`（bounty-im-handler 同款用法），
+ *    不新增任何 npm 依赖（npm 官方 registry 挂，见 Task #5142）；
+ * 2. 协议极简（4 种帧），SDK 的认证/心跳/重连语义已全部吃透
+ *    （读 SDK dist/index.cjs.js 源码取证，Task #5142）；
+ * 3. 避免第三方依赖供应链风险。
+ *
+ * ## 协议（官方文档 101463 + SDK 源码取证）
+ *
+ * - 认证帧：`{cmd:"aibot_subscribe", headers:{req_id}, body:{bot_id, secret}}`
+ *   响应：无 cmd，`headers.req_id` 前缀 `aibot_subscribe_`，`errcode==0` 成功
+ * - 心跳：`{cmd:"ping", headers:{req_id}}`，响应 req_id 前缀 `ping_`，建议 30s
+ * - 消息：`{cmd:"aibot_msg_callback", headers:{req_id}, body:{msgid,...}}`
+ * - 事件：`{cmd:"aibot_event_callback", headers:{req_id}, body:{...}}`
+ * - 回复：`{cmd:"aibot_respond_msg", headers:{req_id:原样透传}, body:{...}}`
+ * - 断线重连：指数退避；认证失败与断线**独立计数**
+ * - ⚠️ 每机器人同一时刻只允许 1 条长连接（新连接踢旧连接）
+ *
+ * @see packages/core/src/env/event-source/wecom-ws-bridge.test.ts
+ * @see docs/research/2026-11-07-wecom-cli-and-roy-agent-es.md
+ */
+import type { WebSocket } from "ws";
+/** 企微长连接默认地址（官方文档 101463） */
+export declare const WECOM_WS_URL = "wss://openws.work.weixin.qq.com";
+/** 心跳间隔（官方建议 30s） */
+export declare const WECOM_HEARTBEAT_INTERVAL_MS = 30000;
+/** 重连基础延迟（指数退避起点） */
+export declare const WECOM_RECONNECT_BASE_DELAY_MS = 1000;
+/** 重连最大延迟（指数退避封顶） */
+export declare const WECOM_RECONNECT_MAX_DELAY_MS = 60000;
+/** 默认最大重连次数（断线场景） */
+export declare const WECOM_MAX_RECONNECT_ATTEMPTS = 10;
+/** 默认最大认证失败次数（凭据错误重试无用） */
+export declare const WECOM_MAX_AUTH_FAILURE_ATTEMPTS = 5;
+/** 生成 `<prefix>_<timestamp>_<random>` 形态的 req_id（对齐官方 SDK） */
+export declare function generateWecomReqId(prefix: string): string;
+/** 通用帧形状（收发共用） */
+export interface WecomFrame {
+    cmd?: string;
+    headers?: {
+        req_id?: string;
+    };
+    body?: Record<string, unknown>;
+    errcode?: number;
+    errmsg?: string;
+}
+/** 构造认证帧（aibot_subscribe） */
+export declare function buildWecomAuthFrame(botId: string, secret: string): WecomFrame & {
+    cmd: string;
+    body: Record<string, unknown>;
+};
+/** 构造心跳帧（ping） */
+export declare function buildWecomHeartbeatFrame(): WecomFrame & {
+    cmd: string;
+};
+/**
+ * 构造回复帧（aibot_respond_msg，Task #5174）。
+ *
+ * ★ 协议硬约束（官方文档 101463 + SDK 源码取证）：
+ * - `headers.req_id` 必须**原样透传**原消息帧的 req_id
+ *   （服务端靠它把回复关联到原消息/会话）；
+ * - body 是消息体（msgtype: text / markdown / image / ...）；
+ * - 收到回调后 24h 内可回复；限频 30 条/分钟。
+ *
+ * @param reqId 原消息帧的 req_id（空则抛错 —— 关联缺失等于发不出去）
+ * @param body  消息体（如 `{msgtype:"text", text:{content:"..."}}`）
+ */
+export declare function buildWecomRespondFrame(reqId: string, body: Record<string, unknown>): WecomFrame & {
+    cmd: string;
+    body: Record<string, unknown>;
+};
+/** 便捷构造：text 回复帧 */
+export declare function buildWecomRespondTextFrame(reqId: string, content: string): WecomFrame & {
+    cmd: string;
+    body: Record<string, unknown>;
+};
+/** 判定是否认证响应（req_id 前缀 `aibot_subscribe_`，无论成败） */
+export declare function isWecomAuthResponse(frame: WecomFrame): boolean;
+/** 判定是否心跳响应（req_id 前缀 `ping_`） */
+export declare function isWecomHeartbeatResponse(frame: WecomFrame): boolean;
+/**
+ * 判定是否「服务端踢线」事件帧（Task #5203）。
+ *
+ * ## 为什么需要它（真网根因）
+ *
+ * 企微「每机器人同一时刻只允许 1 条长连接」——新连接建起来会把旧连接踢掉。
+ * 踢线时服务端**只发一个事件帧** `disconnected_event`，
+ * **TCP 连接并不关闭**（socket 仍 ESTAB，心跳 ping/pong 仍正常往返）。
+ *
+ * ⇒ 原实现只在 `ws.on("close")` 时重连 ⇒ 被踢线的 bridge **永远不重连**，
+ *   变成「心跳正常但业务流量全丢」的僵尸连接（真网现象：用户点卡片按钮，
+ *   回调送不达 ES，app.log 里只有 disconnected_event，没有 template_card_event）。
+ *
+ * @see https://developer.work.weixin.qq.com/document/path/101463（长连接规范）
+ */
+export declare function isWecomDisconnectedEvent(frame: unknown): boolean;
+/**
+ * 清洗帧中的 secret 字段（DS review B1，Task #5165）。
+ *
+ * 浅拷贝 + 删除顶层与 body 层的 `secret` —— 服务端 echo 请求体时
+ * 防止认证 secret 经 onMessage → rawEvent 泄漏给 LLM。
+ */
+export declare function sanitizeWecomFrame(frame: WecomFrame): WecomFrame;
+/** WsBridge 配置 */
+export interface WecomWsBridgeOptions {
+    botId: string;
+    secret: string;
+    /** 覆盖默认 ws 地址（测试 / 内网代理用） */
+    wsUrl?: string;
+    /** WebSocket 工厂（测试注入 mock；生产用 `new (await import('ws')).WebSocket`） */
+    wsFactory?: (url: string) => WebSocket;
+    heartbeatIntervalMs?: number;
+    reconnectBaseDelayMs?: number;
+    reconnectMaxDelayMs?: number;
+    maxReconnectAttempts?: number;
+    maxAuthFailureAttempts?: number;
+}
+/**
+ * 企微长连接桥（对齐官方 SDK 语义，自实现于 ws）。
+ *
+ * 状态机：
+ *   connect() → open → 发认证帧 → 认证响应
+ *     ├─ errcode==0 → authenticated → 启动心跳
+ *     └─ errcode!=0 → auth 失败计数 → 指数退避重连
+ *   close/error → 断线计数 → 指数退避重连
+ *   stop() → 手动关闭，不再重连
+ *
+ * ⚠️ 每机器人同一时刻只允许 1 条长连接（新连接踢旧连接）。
+ */
+export declare class WecomWsBridge {
+    private opts;
+    private readonly botId;
+    private readonly secret;
+    private wsFactory;
+    private wsUrl;
+    private ws?;
+    private heartbeatTimer?;
+    private reconnectTimer?;
+    private reconnectAttempts;
+    private authFailureAttempts;
+    private manualClose;
+    private lastCloseWasAuthFailure;
+    private stopped;
+    private onMessageCb?;
+    private onAuthenticatedCb?;
+    private onReconnectingCb?;
+    private onErrorCb?;
+    constructor(opts: WecomWsBridgeOptions);
+    onMessage(cb: (frame: WecomFrame) => void): void;
+    onAuthenticated(cb: () => void): void;
+    onReconnecting(cb: (attempt: number) => void): void;
+    onError(cb: (err: Error) => void): void;
+    /** 建立连接（open 后自动发认证帧） */
+    connect(): void;
+    private optsBotId;
+    private optsSecret;
+    /** 处理服务端帧（认证响应 / 心跳响应 / 消息 / 事件） */
+    private handleFrame;
+    private sendFrame;
+    /**
+     * 发送回复帧（aibot_respond_msg，Task #5174）。
+     *
+     * best-effort 语义：返回错误而不抛 —— 调用方（handler）在
+     * 事件回调里，抛错会打断事件处理链。
+     *
+     * @param reqId 原消息帧的 req_id（原样透传）
+     * @param body  消息体
+     * @returns 发送失败时返回 Error；成功返回 undefined
+     */
+    respond(reqId: string, body: Record<string, unknown>): Error | undefined;
+    /**
+     * 主动推送帧（Task #5203：aibot_send_msg 直发 template_card）。
+     *
+     * 与 respond 的区别：respond 必须关联原消息 req_id（被动回复），
+     * sendCmd 是**主动推送**（req_id 由开发者自行生成，用于关联
+     * 请求与响应）—— 不依赖用户消息触发。
+     *
+     * best-effort 语义同 respond：返回错误而不抛。
+     *
+     * @param cmd  命令类型（如 "aibot_send_msg"）
+     * @param body 消息体
+     */
+    sendCmd(cmd: string, body: Record<string, unknown>): Error | undefined;
+    /**
+     * 发送自定义帧（req_id 由调用方透传，Task #5203 回归修复）。
+     *
+     * ★ 为什么需要：卡片更新（aibot_respond_update_msg）必须
+     *   **原样透传** template_card_event 回调帧的 req_id
+     *   （5 秒窗口关联），而 sendCmd 自己生成 req_id、
+     *   respond() 硬包成 aibot_respond_msg —— 两者都不满足。
+     *
+     * best-effort 语义同 respond/sendCmd：返回错误而不抛。
+     *
+     * @param frame 完整帧（cmd + headers.req_id + body）
+     */
+    sendFrameWithReqId(frame: {
+        cmd: string;
+        headers: {
+            req_id: string;
+        };
+        body: Record<string, unknown>;
+    }): Error | undefined;
+    private startHeartbeat;
+    private stopHeartbeat;
+    /** 指数退避重连（认证失败与断线独立计数） */
+    private scheduleReconnect;
+    /** 手动停止（不再重连） */
+    stop(): void;
+}

package/dist/env/hook/index.js

@@ -2,7 +2,7 @@ import {
   createHook,
   createPriorityHook,
   init_hook
-} from "../../shared/@ai-setting/roy-agent-core-ax9e9szb.js";
+} from "../../shared/@ai-setting/roy-agent-core-smf94h73.js";
 import {
   AgentHookPoints,
   HookManager,
@@ -13,10 +13,10 @@ import {
   executeLLMHook,
   executeToolHook,
   globalHookManager
-} from "../../shared/@ai-setting/roy-agent-core-cpcd24n2.js";
-import"../../shared/@ai-setting/roy-agent-core-qqaak24r.js";
-import"../../shared/@ai-setting/roy-agent-core-7cbpmk4q.js";
-import"../../shared/@ai-setting/roy-agent-core-qq96p0tj.js";
+} from "../../shared/@ai-setting/roy-agent-core-yet36q5k.js";
+import"../../shared/@ai-setting/roy-agent-core-tkpp1ba0.js";
+import"../../shared/@ai-setting/roy-agent-core-p31ftgq9.js";
+import"../../shared/@ai-setting/roy-agent-core-5s2t8z00.js";
 import"../../shared/@ai-setting/roy-agent-core-7f7t9wwp.js";
 import"../../shared/@ai-setting/roy-agent-core-85xyctnb.js";
 import"../../shared/@ai-setting/roy-agent-core-fs0mn2jk.js";