@ai-setting/roy-agent-core 1.7.76 → 1.7.85

package/dist/env/event-source/wecom-media.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @fileoverview Task #5199 — 企微媒体（图片/文件）下载解密落盘
+ *
+ * ## 背景（用户实测问题）
+ *
+ * 企微长连接模式下 `image`/`file`/`video` 消息只带：
+ * - `image_url`（或 `image.voice_url` 等）：加密媒体下载地址，
+ *   **5 分钟内有效**；
+ * - `aeskey`：Base64 编码的 AES 密钥。
+ *
+ * 此前 WecomWsBridge 只透传消息文本（图片 → `[image]` 占位符），
+ * agent 看不到图片内容（用户反馈：「收到图片但没获取到图片内容」）。
+ *
+ * ## 解密协议（官方文档 101463 + SDK 源码取证，Task #5142）
+ *
+ * - **AES-256-CBC**，PKCS#7 填充到 **32 字节倍数**（不是 Node 默认 16），
+ *   必须 `setAutoPadding(false)` + 手动去填充（对齐官方 SDK decryptFile）；
+ * - **IV = aeskey 解码后的前 16 字节**（aeskey 是 Base64 的 32 字节密钥）；
+ * - 下载 URL 5 分钟内有效 → 下载失败如实报错。
+ *
+ * @see wecom-cli-handler.ts（extractText 图片分支注入落盘路径）
+ * @see wecom-media.test.ts
+ */
+/** 默认媒体落盘目录 */
+export declare const WECOM_MEDIA_DIR = "/tmp/wecom-media";
+/** 测试注入媒体目录（生产勿用） */
+export declare function setWecomMediaDir(dir: string): string;
+/** 测试重置（恢复默认目录） */
+export declare function __resetWecomMediaDirForTest(): void;
+/** 当前生效的媒体目录 */
+export declare function getWecomMediaDir(): string;
+/**
+ * 解密企微媒体（AES-256-CBC，PKCS#7 32 字节块）。
+ *
+ * 对齐官方 SDK `decryptFile`（@wecom/aibot-node-sdk dist/index.cjs.js）：
+ * 1. aesKey 是 Base64 编码的 32 字节密钥；
+ * 2. IV = key 前 16 字节；
+ * 3. `setAutoPadding(false)`（Node 默认按 16 字节块去填充会 bad decrypt）；
+ * 4. 手动校验并去除 PKCS#7 填充（padLen ∈ [1,32]，全部字节一致）。
+ *
+ * @param encrypted 加密的媒体数据
+ * @param aesKeyBase64 Base64 编码的 aeskey（来自消息体 image.aeskey 等）
+ * @returns 解密后的明文 Buffer
+ * @throws 参数非法 / 密钥错误 / padding 损坏时抛错（不静默返回垃圾数据）
+ */
+export declare function decryptWecomMedia(encrypted: Buffer, aesKeyBase64: string): Buffer;
+/** 从消息体提取出的媒体引用 */
+export interface WecomMediaRef {
+    /** 媒体类型（image / file / video / voice） */
+    kind: "image" | "file" | "video" | "voice";
+    /** 加密媒体下载地址（5 分钟内有效） */
+    url: string;
+    /** Base64 编码的 AES 密钥 */
+    aeskey: string;
+    /** 原始文件名（file 类型才有） */
+    filename?: string;
+}
+/**
+ * 从企微消息体提取媒体引用（image / file / video / voice）。
+ *
+ * - 单媒体消息：body.image / body.file / body.video / body.voice；
+ * - mixed 消息：遍历 body.mixed.msg_item[]，收集所有媒体 item；
+ * - 缺 url 或缺 aeskey 的 item 跳过（不产生坏引用）。
+ */
+export declare function extractWecomMediaRefs(body: Record<string, unknown>): WecomMediaRef[];
+/** 下载器返回值（测试注入用） */
+export interface WecomMediaFetchResult {
+    ok: boolean;
+    status: number;
+    buffer: Buffer;
+    /** 从 Content-Disposition 解析的文件名（可选） */
+    filename?: string;
+}
+/** 下载器签名（生产用全局 fetch；测试注入 mock） */
+export type WecomMediaFetcher = (url: string) => Promise<WecomMediaFetchResult>;
+/** fetchAndSaveWecomMedia 入参 */
+export interface FetchWecomMediaInput {
+    msgid: string;
+    url: string;
+    aeskey: string;
+    kind: WecomMediaRef["kind"];
+    /** 下载器（测试注入；缺省用全局 fetch） */
+    fetcher?: WecomMediaFetcher;
+    /** 原始文件名（可选） */
+    filename?: string;
+    /**
+     * ★ Task #5313：会话 id —— 落盘子目录，实现跨群媒体隔离。
+     * 缺省时保持旧行为（直接落媒体根目录）。
+     */
+    chatId?: string;
+}
+/**
+ * 下载企微加密媒体 → 解密 → 落盘，返回本地路径。
+ *
+ * - 下载失败（HTTP 非 200）→ 抛错（URL 5 分钟有效，失败必须可见）；
+ * - 解密失败（aeskey 错误/数据损坏）→ 抛错（不落垃圾文件）；
+ * - 成功 → saveWecomMediaFile 落盘（msgid_filename）。
+ */
+export declare function fetchAndSaveWecomMedia(input: FetchWecomMediaInput): Promise<string>;
+/** saveWecomMediaFile 入参 */
+export interface SaveWecomMediaInput {
+    /** 消息 ID（文件名前缀，防同名覆盖） */
+    msgid: string;
+    /** 原始文件名（可缺省，用 msgid 兜底） */
+    filename?: string;
+    /** 解密后的媒体数据 */
+    buffer: Buffer;
+    /**
+     * ★ Task #5313：会话 id —— 落盘到 `<mediaDir>/<safeChatId>/` 子目录。
+     *
+     * 背景：此前所有会话共用一个扁平目录，mediaFiles 只按 msgid 区分，
+     * agent 扫目录时会把别的群的历史图片当成本条消息的附件。
+     * 按 chatId 分层后跨群天然隔离（整目录清理也更容易）。
+     *
+     * 缺省（undefined）→ 保持旧行为，直接落媒体根目录。
+     */
+    chatId?: string;
+}
+/**
+ * 把解密后的媒体数据落盘到媒体目录。
+ *
+ * - 目录：默认 `/tmp/wecom-media`（测试可注入）；传 chatId 时落到
+ *   `<mediaDir>/<chatId>/` 子目录（Task #5313 跨群隔离）；
+ * - 文件名：`<msgid>_<basename(filename)>`（路径穿越防护：
+ *   只取 basename，`../../etc/passwd` → `passwd`）；
+ * - 目录不存在时自动创建。
+ *
+ * @returns 落盘的绝对路径
+ */
+export declare function saveWecomMediaFile(input: SaveWecomMediaInput): Promise<string>;

package/dist/env/event-source/wecom-respond-registry.d.ts

@@ -0,0 +1,151 @@
+/**
+ * @fileoverview Task #5174（用户明令 2026-11-08 11:29）— 企微回复注册表 + `wecom_respond` 工具
+ *
+ * ## 出站主路径 = wecom-cli（CLI 已授权）
+ *
+ * 用户明令：「彻底改造下回复出站用 cli 吧，已经验证可以收到消息了，不用 ws 回」。
+ *
+ * 发送顺序：
+ *   1. **CLI**（`wecom-cli message aibot send --msg-type markdown`）—— 主路径
+ *   2. **WS 回帧**（`aibot_respond_msg`，req_id 透传）—— CLI 失败时 fallback
+ *      （两者都不可用时如实报错，绝不假装已发送）
+ *
+ * ## chat_id 语义（实测硬约束）
+ *
+ * - WS 回调里的 `from.userid`（如 `DongZhaoKun`）**不是** CLI 可用的 chat_id
+ *   → CLI 报 40073「非法的 chat_id」
+ * - CLI 需要真实 userid（`wotnB7Wg...` 形态）→ 由 `contact users search` 解析
+ *   （`wecom-cli-sender.resolveWecomCliChatId`，带内存缓存）
+ *
+ * ## 注册表
+ *
+ * `WecomCliInstance.startWithBridge()` 把实例登记进来（`sourceId → target`），
+ * `stop()` 注销；工具通过 `EnvContext.sourceId` 反查，从而拿到：
+ * - `respond(reqId, body)` —— WS fallback
+ * - `sourceId` 对应的配置（CLI 出站不需要实例，但保留用于 fallback）
+ *
+ * @see wecom-cli-sender.ts（CLI 出站实现）
+ * @see wecom-ws-bridge.ts（WS 回帧 fallback）
+ */
+import type { Tool } from "../types";
+/** 注册表条目：WS fallback 所需的最小面 */
+export interface WecomRespondTarget {
+    /** 发送 WS 回帧（透传原消息 req_id）；返回错误而不抛（best-effort） */
+    respond(reqId: string, body: Record<string, unknown>): Error | undefined;
+    /**
+     * 主动推送帧（Task #5203：aibot_send_msg 直发 template_card）。
+     * 返回错误而不抛（best-effort）。
+     */
+    sendCmd?(cmd: string, body: Record<string, unknown>): Error | undefined;
+}
+/** 登记一个可回复的企微实例（sourceId → target） */
+export declare function registerWecomRespondTarget(sourceId: string, target: WecomRespondTarget): void;
+/** 注销（实例 stop 时调用） */
+export declare function unregisterWecomRespondTarget(sourceId: string): void;
+/** 查询（工具执行时用） */
+export declare function getWecomRespondTarget(sourceId: string): WecomRespondTarget | undefined;
+/** 测试用：清空注册表 */
+export declare function __resetWecomRespondRegistryForTest(): void;
+/** 出站发送入参 */
+export interface WecomSendInput {
+    /** 事件源 ID（用于查 WS fallback 实例） */
+    sourceId: string;
+    /** 原始 WS 回调的 userid / chatid（CLI 侧会自动解析成真实 userid） */
+    rawChatId: string;
+    /** 原消息帧 req_id（WS fallback 用） */
+    reqId?: string;
+    /** 回复正文 */
+    content: string;
+}
+/** 出站发送结果 */
+export interface WecomSendResult {
+    ok: boolean;
+    /** 实际走通的通道 */
+    channel?: "cli" | "ws";
+    /** 失败原因（两个通道都失败时给出合并说明） */
+    error?: string;
+}
+/**
+ * 发送企微回复：**被动回帧优先（有 reqId 时），CLI 兜底**（永不抛）。
+ *
+ * ## 为什么被动回帧优先（Task #5287 回复引用）
+ *
+ * 取证结论（官方文档 101463 + CLI schema 实查）：
+ * - 主动推送（CLI `message.aibot.send` / WS `aibot_send_msg`）schema
+ *   **无 quote/引用字段** —— 协议不支持发消息时主动引用某条消息；
+ * - 被动回复（WS `aibot_respond_msg`，headers.req_id 原样透传）时，
+ *   企微服务端**自动**把回复引用到触发回调的用户消息（群聊场景）。
+ *
+ * ⇒ 要让用户看到「回复引用了哪条消息」，必须走被动回帧。
+ *   因此有 reqId 且 WS 实例在线时**优先** WS 被动回帧；
+ *   CLI 降为 fallback（无 reqId / WS 失败 / 无实例时仍可用，
+ *   #5174「CLI 主路径」行为在无 reqId 场景不回归）。
+ *
+ * 发送顺序：
+ *   1. **WS 被动回帧**（reqId 存在 + 注册实例在线）—— 带引用语义
+ *   2. **CLI**（`wecom-cli message aibot send --msg-type markdown`）—— fallback
+ *   3. 都失败 → `{ok:false, error}`（两个原因都带上，便于排障）
+ */
+export declare function sendWecomReply(input: WecomSendInput): Promise<WecomSendResult>;
+/** 卡片直发入参 */
+export interface WecomTemplateCardSendInput {
+    /** 事件源 ID（查注册的 WS 实例） */
+    sourceId: string;
+    /** 会话 ID（单聊=userid，群聊=群 chatid） */
+    chatId: string;
+    /** 会话类型（决定 chat_type：1 单聊 / 2 群聊） */
+    chatType: "single" | "group";
+    /** 卡片结构体（wecom-card-builder 构造） */
+    card: Record<string, unknown>;
+}
+/**
+ * 经 WS 长连接直发 template_card（aibot_send_msg 主动推送）。
+ *
+ * ## 为什么不走 wecom-cli
+ *
+ * wecom-cli v1.3.4 的 msg_type 枚举只有 markdown/image/file/voice/video，
+ * 没封装 template_card（官方仓源码 grep 零命中，Task #5202 取证）。
+ * WS 协议原生支持 → 直发。
+ *
+ * best-effort：永不抛；失败返回 `{ok:false, error}`。
+ *
+ * ⚠️ 主动推送前提（官方 101463）：需用户先在会话中给机器人发过消息；
+ * 限频 30 条/分钟、1000 条/小时（调用方节流）。
+ */
+export declare function sendWecomTemplateCard(input: WecomTemplateCardSendInput): Promise<WecomSendResult>;
+/**
+ * `wecom_respond` —— 回复企微用户（CLI 主路径，WS fallback）。
+ *
+ * 参数：
+ * - `content`：回复正文（markdown）
+ * - `chat_id`：**可选**，回复目标；缺省时从 EnvContext 事件 metadata 取
+ *   （单聊=senderId；群聊=chatid）。CLI 侧会自动解析成真实 userid。
+ * - `req_id`：**可选**，原消息帧 req_id（WS fallback 用）；缺省从 metadata.reqId 取
+ */
+export declare const wecomRespondTool: Tool;
+/** 标记本轮已发送（wecom_respond 工具成功时调用） */
+export declare function markWecomReplySent(explicitBag?: Record<string, unknown>): void;
+/** 本轮是否已发送过 */
+export declare function wasWecomReplySent(explicitBag?: Record<string, unknown>): boolean;
+/** 测试用：清空标记 */
+export declare function __resetWecomReplySentForTest(explicitBag?: Record<string, unknown>): void;
+/**
+ * 框架级兜底：turn 结束后，若本轮没发过回复且事件来自企微 → 直接把
+ * assistant 的最终文本发出去（CLI 主路径 → WS fallback）。
+ *
+ * 触发条件（全部满足）：
+ * 1. `envEvent.type === "event-source.event.wecom-cli"`
+ * 2. 最终文本非空
+ * 3. 本轮**尚未**通过 `wecom_respond` 工具发送（避免双发）
+ *
+ * @returns 发送结果；不满足触发条件时返回 `{skipped: true}`
+ */
+export declare function autoReplyWecomTurn(envEvent: unknown, finalText: string): Promise<{
+    skipped: true;
+    reason: string;
+} | {
+    skipped: false;
+    ok: boolean;
+    channel?: "cli" | "ws";
+    error?: string;
+}>;

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/index.js

@@ -1,55 +1,57 @@
 import {
   BaseEnvironment
-} from "../shared/@ai-setting/roy-agent-core-zycadbpx.js";
+} from "../shared/@ai-setting/roy-agent-core-p6ks90tb.js";
 import {
   TaskComponent
-} from "../shared/@ai-setting/roy-agent-core-z43aj03k.js";
+} from "../shared/@ai-setting/roy-agent-core-qk9hd89p.js";
 import"../shared/@ai-setting/roy-agent-core-2akfd64z.js";
 import"../shared/@ai-setting/roy-agent-core-jm136jzh.js";
-import"../shared/@ai-setting/roy-agent-core-aa2j7bk9.js";
+import"../shared/@ai-setting/roy-agent-core-cha0jc7n.js";
 import"../shared/@ai-setting/roy-agent-core-fttgm52a.js";
-import"../shared/@ai-setting/roy-agent-core-ntq0gz7q.js";
+import"../shared/@ai-setting/roy-agent-core-q813vafd.js";
 import"../shared/@ai-setting/roy-agent-core-8gxth0eh.js";
 import"../shared/@ai-setting/roy-agent-core-vffccgf6.js";
 import"../shared/@ai-setting/roy-agent-core-p5cz9m8v.js";
 import {
   EventSourceComponent
-} from "../shared/@ai-setting/roy-agent-core-cxy143m4.js";
+} from "../shared/@ai-setting/roy-agent-core-begm7ytz.js";
 import {
   builtInHandlers,
   larkCliHandler
-} from "../shared/@ai-setting/roy-agent-core-t3rrb959.js";
+} from "../shared/@ai-setting/roy-agent-core-xf6z96qy.js";
 import {
   EventSourceInitHooks,
   getDefaultConfigForType,
   isBuiltInEventSourceType,
   isValidEventSourceType,
   validateEventSourceConfig
-} from "../shared/@ai-setting/roy-agent-core-bxkjk7zx.js";
+} from "../shared/@ai-setting/roy-agent-core-vx8zc847.js";
 import"../shared/@ai-setting/roy-agent-core-v0hf14bj.js";
 import"../shared/@ai-setting/roy-agent-core-tm1mxttk.js";
-import"../shared/@ai-setting/roy-agent-core-ghnagzrh.js";
+import"../shared/@ai-setting/roy-agent-core-2stt4rp5.js";
+import"../shared/@ai-setting/roy-agent-core-b31v3qpv.js";
+import"../shared/@ai-setting/roy-agent-core-m3vjepzz.js";
 import"../shared/@ai-setting/roy-agent-core-na18zwj0.js";
 import"../shared/@ai-setting/roy-agent-core-9vxh6f8h.js";
-import"../shared/@ai-setting/roy-agent-core-abqhkbn3.js";
+import"../shared/@ai-setting/roy-agent-core-ezvpreqz.js";
 import"../shared/@ai-setting/roy-agent-core-1pg0fepg.js";
 import"../shared/@ai-setting/roy-agent-core-tr3ep81v.js";
 import"../shared/@ai-setting/roy-agent-core-m46fe3x4.js";
 import"../shared/@ai-setting/roy-agent-core-4rtg69cn.js";
-import"../shared/@ai-setting/roy-agent-core-p3zv1mx5.js";
-import"../shared/@ai-setting/roy-agent-core-nmx9934r.js";
+import"../shared/@ai-setting/roy-agent-core-d1n4jbza.js";
+import"../shared/@ai-setting/roy-agent-core-7dd0s3xb.js";
 import {
   WorkflowComponent
-} from "../shared/@ai-setting/roy-agent-core-v87njmq7.js";
+} from "../shared/@ai-setting/roy-agent-core-0dh8npnz.js";
 import"../shared/@ai-setting/roy-agent-core-es203w7p.js";
 import"../shared/@ai-setting/roy-agent-core-h0x19xgn.js";
 import"../shared/@ai-setting/roy-agent-core-1ce3fqrk.js";
-import"../shared/@ai-setting/roy-agent-core-mww0mnd9.js";
+import"../shared/@ai-setting/roy-agent-core-7bpj859q.js";
 import"../shared/@ai-setting/roy-agent-core-ddyk1rc0.js";
 import"../shared/@ai-setting/roy-agent-core-0qyrk5k0.js";
 import"../shared/@ai-setting/roy-agent-core-hhrg314p.js";
 import"../shared/@ai-setting/roy-agent-core-12n08pg5.js";
-import"../shared/@ai-setting/roy-agent-core-6cy43nss.js";
+import"../shared/@ai-setting/roy-agent-core-rykf7c04.js";
 import"../shared/@ai-setting/roy-agent-core-6rh8k6ba.js";
 import"../shared/@ai-setting/roy-agent-core-6atd905e.js";
 import"../shared/@ai-setting/roy-agent-core-dqxec05w.js";
@@ -68,8 +70,8 @@ import"../shared/@ai-setting/roy-agent-core-jagkferh.js";
 import {
   AgentComponent,
   AgentComponentConfigSchema
-} from "../shared/@ai-setting/roy-agent-core-q5r75vev.js";
-import"../shared/@ai-setting/roy-agent-core-v85n42ve.js";
+} from "../shared/@ai-setting/roy-agent-core-dkrvmjsh.js";
+import"../shared/@ai-setting/roy-agent-core-ze5cqpf2.js";
 import"../shared/@ai-setting/roy-agent-core-jvv2h3d6.js";
 import"../shared/@ai-setting/roy-agent-core-ed233k5z.js";
 import {
@@ -77,7 +79,7 @@ import {
   getXDGPath,
   getXDGPaths
 } from "../shared/@ai-setting/roy-agent-core-qxnbvgwe.js";
-import"../shared/@ai-setting/roy-agent-core-f77k3gqt.js";
+import"../shared/@ai-setting/roy-agent-core-h21gngxf.js";
 import"../shared/@ai-setting/roy-agent-core-0snm5hc5.js";
 import"../shared/@ai-setting/roy-agent-core-fghc2m8z.js";
 import"../shared/@ai-setting/roy-agent-core-zjdzk1gg.js";

package/dist/env/task/backend/index.js

@@ -1,6 +1,7 @@
 import {
   TASK_COMPLETED_STATUS_WORD,
-  TASK_DELIVERABLE_RECORDED
+  TASK_DELIVERABLE_RECORDED,
+  TASK_TO_VALIDATE_STATUS_WORD
 } from "../../../shared/@ai-setting/roy-agent-core-4rtg69cn.js";
 import"../../../shared/@ai-setting/roy-agent-core-fs0mn2jk.js";
 // src/env/task/backend/task-store-backend.ts
@@ -166,6 +167,41 @@ class TaskStoreBackend {
     const reread = await this.resolve(record.nativeId);
     return this.toTask(reread ?? updated);
   }
+  async preCompleteTask(id, sessionId, deliverable, progressSummary) {
+    const record = await this.resolve(id);
+    if (!record)
+      return null;
+    if (record.type === "cycle") {
+      throw new Error(`Cannot pre-complete cycle task: #${record.id} - ${record.title}. Cycle tasks are not meant to be completed or submitted for acceptance.`);
+    }
+    const toValidateWording = progressSummary ? `${TASK_TO_VALIDATE_STATUS_WORD}：${progressSummary}` : TASK_TO_VALIDATE_STATUS_WORD;
+    const patch = {
+      status: "to_validate",
+      current_status: toValidateWording
+    };
+    if (deliverable) {
+      patch.context = mergeDeliverableIntoContext(record.context, deliverable);
+    }
+    const updated = await this.port.updateTask(record.nativeId, patch);
+    if (!updated)
+      return null;
+    const descParts = [];
+    const deliverableLine = formatDeliverableForOperation(deliverable);
+    if (deliverableLine)
+      descParts.push(deliverableLine);
+    if (progressSummary)
+      descParts.push(progressSummary);
+    await this.createOperation({
+      taskId: updated.id,
+      sessionId: sessionId ?? this.defaultSessionId,
+      milestoneType: "milestone",
+      milestoneTitle: `${TASK_TO_VALIDATE_STATUS_WORD}（to_validate）：Task #${updated.id} submitted for acceptance`,
+      milestoneDescription: descParts.join(" / ") || TASK_TO_VALIDATE_STATUS_WORD,
+      ...deliverable ? { mdPath: deliverable } : {}
+    });
+    const reread = await this.resolve(record.nativeId);
+    return this.toTask(reread ?? updated);
+  }
   async getTaskTree(id, depth = -1) {
     const root = await this.resolve(id);
     if (!root)

package/dist/env/task/backend/task-store-backend.d.ts

@@ -62,6 +62,18 @@ export declare class TaskStoreBackend implements TaskBackend {
     updateTask(id: TaskId, input: BackendUpdateTaskOptions): Promise<Task | null>;
     deleteTask(id: TaskId): Promise<boolean>;
     completeTask(id: TaskId, sessionId?: string, deliverable?: string): Promise<Task | null>;
+    /**
+     * Task #5078 — 提交待验证（两阶段验收 #5073 的 backend 实现）。
+     *
+     * 语义与 `TaskComponent.preCompleteTask` 同构：
+     * status → to_validate、current_status → 待验证措辞、
+     * deliverable merge 进 context、milestone operation 留痕。
+     *
+     * 与 TaskComponent 的唯一差别：**不 fire AFTER_COMPLETE 钩子** ——
+     * backend 没有 hook 链（#5035 已确认），goal 判定由上层负责
+     * （MCP 侧 = 插件 withGoalCheck；TaskComponent 侧 = 插件链）。
+     */
+    preCompleteTask(id: TaskId, sessionId?: string, deliverable?: string, progressSummary?: string): Promise<Task | null>;
     /**
      * review B1 — roy 的 `task-tree-tool.ts` 在子树模式下调这个方法；
      * 老 facade 缺它导致 `task_tree(parent_task_id=…)` 直接抛