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

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,12 +1,12 @@
 import {
   BaseEnvironment
-} from "../shared/@ai-setting/roy-agent-core-ew6qb5yx.js";
+} from "../shared/@ai-setting/roy-agent-core-p6ks90tb.js";
 import {
   TaskComponent
-} from "../shared/@ai-setting/roy-agent-core-rhtdspx6.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-q813vafd.js";
 import"../shared/@ai-setting/roy-agent-core-8gxth0eh.js";
@@ -14,21 +14,23 @@ 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-0v27y99n.js";
+} from "../shared/@ai-setting/roy-agent-core-begm7ytz.js";
 import {
   builtInHandlers,
   larkCliHandler
-} from "../shared/@ai-setting/roy-agent-core-3gpygqcx.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-rsn44n9y.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-ezvpreqz.js";
@@ -36,20 +38,20 @@ 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-hd3n57zs.js";
-import"../shared/@ai-setting/roy-agent-core-w0qjeq2v.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-9vhq7fvv.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 {

package/dist/env/task/delegate/delegate-tool.d.ts

@@ -236,6 +236,16 @@ export interface BackgroundTask {
      * 顺序 = 优先级（主模型失败后逐个尝试）。
      */
     fallbackModels?: string[];
+    /**
+     * ★ Task #5217 fix 2 — 父 agent 本次 run 的 channel systemPrompt
+     * （context.metadata.systemPrompt，如 lean lark 渠道 prompt）。
+     * 透传给 sub-agent 的 AgentContext.metadata.systemPrompt，
+     * 使 AgentComponent._run 把它追加到 sub-agent 的 LLM system message。
+     *
+     * 注意：与 model 一样**不写进 sub-agent 的注册配置** —— per-run
+     * 透传天然每次都是最新值（channel prompt 是 per-event 的）。
+     */
+    systemPrompt?: string;
     /**
      * ★ Task #4552 (A1)：本任务被允许的运行时长（毫秒，createTask 时确定）。
      *
@@ -280,6 +290,16 @@ export interface BackgroundTask {
         profile?: string;
         params?: Record<string, unknown>;
     };
+    /**
+     * ★ Task #5265 — delegate 时刻的 pluginEnabled 快照。
+     *
+     * 后台任务通知轮（task.background.* 合成 envEvent）此前
+     * pluginEnabled={}（空）→ WecomTaskNotifyPlugin 等 ES 插件的
+     * pluginEnabled 守卫拦截 → 不发卡（用户只见纯文本）。
+     * createTask 时快照 parent EnvContext.pluginEnabled，
+     * publishBackgroundEvent 时写进 event.metadata.pluginEnabled。
+     */
+    pluginEnabledSnapshot?: Record<string, boolean>;
 }
 /**
  * Task #4794 — BackgroundTaskManager.dispose() 的行为选项。
@@ -347,6 +367,12 @@ export interface CreateBackgroundTaskOptions {
      * Task #4724 — 父 agent 的兜底模型**有序列表**，透传给 sub-agent。
      */
     fallbackModels?: string[];
+    /**
+     * ★ Task #5217 fix 2 — 父 agent 本次 run 的 channel systemPrompt
+     * （context.metadata.systemPrompt，如 lean lark 渠道 prompt）。
+     * 透传给 sub-agent 的 AgentContext.metadata.systemPrompt。
+     */
+    systemPrompt?: string;
 }
 /**
  * 构建 entry-agent 调度的 prompt 包装 (Task #2164 beta-compare divergence #2)
@@ -578,7 +604,7 @@ export declare class BackgroundTaskManager {
      *
      * @internal 测试 / 集成用，普通调用方走 publishBackgroundEvent 私有方法
      */
-    publishBackgroundEventWithTrigger<T>(type: string, payload: T, parentSessionId: string | undefined, triggerEventId: string, replyChannel?: BackgroundTask["replyChannel"]): void;
+    publishBackgroundEventWithTrigger<T>(type: string, payload: T, parentSessionId: string | undefined, triggerEventId: string, replyChannel?: BackgroundTask["replyChannel"], pluginEnabledSnapshot?: Record<string, boolean>): void;
     /**
      * Task #3xxx — 解析 AskUserError 信息
      *
@@ -782,6 +808,34 @@ declare function _captureReplyChannelSnapshot(): BackgroundTask["replyChannel"]
  * traced 版 captureReplyChannelSnapshot（供 debug trace 观测 task 的回复目标快照）。
  */
 export declare const captureReplyChannelSnapshot: typeof _captureReplyChannelSnapshot;
+/**
+ * ★ Task #5265 — 把当前 EnvContext.pluginEnabled 拍成不可变快照。
+ *
+ * ## 为什么需要（生产故障 2026-11-10 12:45）
+ *
+ * 后台任务完成通知链路（task.background.completed → 通知会话）的
+ * 合成 envEvent **pluginEnabled={}（空）** →
+ * WecomTaskNotifyPlugin.execute 的 pluginEnabled 守卫
+ * （key=wecom-bot-2:WecomTaskNotifyPlugin）不通过 → 插件直接 return
+ * 不发卡（用户只看到纯文本）。
+ *
+ * 主会话（事件轮直发）pluginEnabled 由 event-source-handlers 构建
+ * （有 key）→ 有卡。合成事件（publishBackgroundEvent）此前不携带
+ * pluginEnabled，dispatcher 的重建逻辑依赖 metadata.plugins（也为空）
+ * → 守卫拦截。
+ *
+ * 修复：delegate 时刻快照 pluginEnabled，随 task 存
+ * `BackgroundTask.pluginEnabledSnapshot`，publishBackgroundEvent 时
+ * 写进 event.metadata.pluginEnabled —— 通知轮合成 envEvent 自带，
+ * dispatcher / buildRunEnvContext 透传 → 守卫放行。
+ *
+ * 返回 undefined 当没有 EnvContext / 没有 pluginEnabled（向后兼容）。
+ */
+declare function _capturePluginEnabledSnapshot(): Record<string, boolean> | undefined;
+/**
+ * traced 版 capturePluginEnabledSnapshot（供 debug trace 观测快照结果）。
+ */
+export declare const capturePluginEnabledSnapshot: typeof _capturePluginEnabledSnapshot;
 declare function handleBackgroundTask(backgroundTaskManager: BackgroundTaskManager, parentSessionId: string, description: string, prompt: string, subagentType: string, timeout?: number, similarTaskIds?: number[], 
 /**
  * ★ 2026-07-10 新增（Task #1752 subSessionId 复用机制）
@@ -804,5 +858,11 @@ model?: string, fallbackModel?: string,
  * Task #4724 — 父 agent 本次 run 的兜底模型**有序列表**。
  * 透传给 createTask → sub-agent 的 AgentContext（顺序 = 优先级）。
  */
-fallbackModels?: string[]): Promise<ToolResult>;
+fallbackModels?: string[], 
+/**
+ * ★ Task #5217 fix 2 — 父 agent 本次 run 的 channel systemPrompt
+ * （ToolContext.metadata.systemPrompt，per-event）。
+ * 透传给 createTask → sub-agent 的 AgentContext.metadata.systemPrompt。
+ */
+systemPrompt?: string): Promise<ToolResult>;
 export { handleBackgroundTask };

package/dist/env/task/delegate/delegate-tool.js

@@ -7,12 +7,13 @@ import {
   WORKFLOW_COMPAT_ALIASES,
   buildEntryAgentPrompt,
   builtInSubAgents,
+  capturePluginEnabledSnapshot,
   captureReplyChannelSnapshot,
   createDelegateTool,
   deriveTriggerEventIdFromEnvContext,
   getSubAgentSpec,
   handleBackgroundTask
-} from "../../../shared/@ai-setting/roy-agent-core-aa2j7bk9.js";
+} from "../../../shared/@ai-setting/roy-agent-core-cha0jc7n.js";
 import"../../../shared/@ai-setting/roy-agent-core-fttgm52a.js";
 import"../../../shared/@ai-setting/roy-agent-core-na18zwj0.js";
 import"../../../shared/@ai-setting/roy-agent-core-9vxh6f8h.js";
@@ -35,6 +36,7 @@ export {
   deriveTriggerEventIdFromEnvContext,
   createDelegateTool,
   captureReplyChannelSnapshot,
+  capturePluginEnabledSnapshot,
   builtInSubAgents,
   buildEntryAgentPrompt,
   WORKFLOW_COMPAT_ALIASES,

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

@@ -5,7 +5,7 @@ import {
   BackgroundTaskEventTypes,
   BackgroundTaskManager,
   createDelegateTool
-} from "../../../shared/@ai-setting/roy-agent-core-aa2j7bk9.js";
+} from "../../../shared/@ai-setting/roy-agent-core-cha0jc7n.js";
 import"../../../shared/@ai-setting/roy-agent-core-fttgm52a.js";
 import"../../../shared/@ai-setting/roy-agent-core-na18zwj0.js";
 import"../../../shared/@ai-setting/roy-agent-core-9vxh6f8h.js";

package/dist/env/task/index.js

@@ -5,10 +5,10 @@ import {
   TaskPriorityEnum,
   TaskStatusEnum,
   TaskTypeEnum
-} from "../../shared/@ai-setting/roy-agent-core-rhtdspx6.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-q813vafd.js";
 import {

package/dist/env/task/plugins/index.d.ts

@@ -10,6 +10,8 @@ export { TASK_COMPLETION_HINT_ANCHOR, TASK_COMPLETE_ITEM_BY_ITEM, TASK_COMPLETE_
 export type { DecisionPort, DecisionRequest, DecisionAnswer, DecisionResponse, } from "./decision-port";
 export { WORKFLOW_EXTRACTOR_PROMPT, formatExtractorInput, formatExtractorInputFromDescription, parseExtractorOutput, } from "./workflow-extractor-agent";
 export { LarkCliTaskNotifyHook, createLarkCliTaskNotifyHook, type TaskNotifyConfig, NotifyType, } from "./lark-cli-task-notify-plugin";
+export { WecomTaskNotifyHook, createWecomTaskNotifyHook, extractWecomFields, buildWecomTaskCard, WecomNotifyType, type WecomTaskNotifyConfig, type WecomMilestone, } from "./wecom-task-notify-plugin";
+export { createWecomCardStateStore, createMemoryWecomCardStore, MemoryWecomCardStateStore, SqliteWecomCardStateStore, getDefaultWecomCardDbPath, type WecomCardState, type WecomCardStateStore, } from "./wecom-card-state-store";
 export { PerTaskGroupChatPlugin, createPerTaskGroupChatPlugin, type PerTaskGroupConfig, } from "./per-task-group-chat-plugin";
 export { LarkCardPatchNotifier, type LarkCardPatchNotifierOptions, buildTaskCard, buildWorkflowCard, renderProgressBar, renderMilestones, renderProcessSteps, renderTaskInfoLines, renderContextAsLines, renderWorkflowInfoLines, formatTimestampForDisplay, formatDateTimeForDisplay, formatDurationMs, sanitizeInlineText, humanizeValue, resolveTaskTitleForDisplay, buildChatAppLink, DEFAULT_APP_LINK_BASE, type CardStatus, type WorkflowCardStatus, type Milestone, type ProcessStep, type TaskMeta, type WorkflowMeta, type CardPayload, type StartTaskOptions, type UpdateTaskOptions, type FinishTaskOptions, type StartTaskResult, type StartWorkflowOptions, type UpdateWorkflowOptions, type FinishWorkflowOptions, } from "./lark-card-patch-notifier";
 export { createLarkCardStateStore, getDefaultLarkCardDbPath, MemoryLarkCardStateStore, SqliteLarkCardStateStore, type LarkCardState, type LarkCardRecordStatus, type LarkCardStateStore, } from "./lark-card-state-store";

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

@@ -5,26 +5,37 @@ import {
   LayaCompletionPlugin,
   LayaDecisionPlugin,
   MemoryLarkCardStateStore,
+  MemoryWecomCardStateStore,
   NotifyType,
   PerTaskGroupChatPlugin,
   SqliteLarkCardStateStore,
+  SqliteWecomCardStateStore,
   TaskTagPlugin,
   WORKFLOW_EXTRACTOR_PROMPT,
+  WecomNotifyType,
+  WecomTaskNotifyHook,
   buildCompletionHint,
   buildCompletionQuestion,
+  buildWecomTaskCard,
   createAutoTaskPlugin,
   createLarkCardStateStore,
   createLarkCliTaskNotifyHook,
   createLayaCompletionPlugin,
   createLayaDecisionPlugin,
+  createMemoryWecomCardStore,
   createPerTaskGroupChatPlugin,
+  createWecomCardStateStore,
+  createWecomTaskNotifyHook,
+  extractWecomFields,
   formatExtractorInput,
   formatExtractorInputFromDescription,
   getDefaultLarkCardDbPath,
+  getDefaultWecomCardDbPath,
   parseExtractorOutput,
   registerLayaCompletionTaskHook,
   renderCompletionState
-} from "../../../shared/@ai-setting/roy-agent-core-rsn44n9y.js";
+} from "../../../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-ezvpreqz.js";
@@ -55,7 +66,7 @@ import {
   renderWorkflowInfoLines,
   resolveTaskTitleForDisplay,
   sanitizeInlineText
-} from "../../../shared/@ai-setting/roy-agent-core-w0qjeq2v.js";
+} from "../../../shared/@ai-setting/roy-agent-core-7dd0s3xb.js";
 import"../../../shared/@ai-setting/roy-agent-core-1v4g0d4x.js";
 import"../../../shared/@ai-setting/roy-agent-core-cgtq6427.js";
 import"../../../shared/@ai-setting/roy-agent-core-er070zjq.js";
@@ -87,24 +98,32 @@ export {
   registerLayaCompletionTaskHook,
   parseExtractorOutput,
   humanizeValue,
+  getDefaultWecomCardDbPath,
   getDefaultLarkCardDbPath,
   formatTimestampForDisplay,
   formatExtractorInputFromDescription,
   formatExtractorInput,
   formatDurationMs,
   formatDateTimeForDisplay,
+  extractWecomFields,
+  createWecomTaskNotifyHook,
+  createWecomCardStateStore,
   createTaskOpWatermarkPlugin,
   createPerTaskGroupChatPlugin,
+  createMemoryWecomCardStore,
   createLayaDecisionPlugin,
   createLayaCompletionPlugin,
   createLarkCliTaskNotifyHook,
   createLarkCardStateStore,
   createAutoTaskPlugin,
   buildWorkflowCard,
+  buildWecomTaskCard,
   buildTaskCard,
   buildCompletionQuestion,
   buildCompletionHint,
   buildChatAppLink,
+  WecomTaskNotifyHook,
+  WecomNotifyType,
   WORKFLOW_EXTRACTOR_PROMPT,
   TaskTagPlugin,
   TaskOpWatermarkPlugin,
@@ -115,9 +134,11 @@ export {
   TASK_COMPLETE_VERIFY_DUTY,
   TASK_COMPLETE_ITEM_BY_ITEM,
   TASK_COMPLETE_ACCEPTANCE,
+  SqliteWecomCardStateStore,
   SqliteLarkCardStateStore,
   PerTaskGroupChatPlugin,
   NotifyType,
+  MemoryWecomCardStateStore,
   MemoryLarkCardStateStore,
   LayaDecisionPlugin,
   LayaCompletionPlugin,

package/dist/env/task/plugins/lark-card-patch-notifier.d.ts

@@ -79,7 +79,14 @@ export type CardStatus = "running" | "completed" | "failed" | "stopped"
  * 语义上必须分开：用户看到「🚫 已取消」会以为任务还能找回来；
  * 硬删除后任务真的没了，卡片应显示「🗑️ 已删除」。
  */
- | "deleted";
+ | "deleted"
+/**
+ * ★ Task #5164 需求 2b：任务进入「待验证」（两阶段验收，
+ *   task_pre_complete 置 to_validate）。**非终态**活跃等待态：
+ *   卡片保持可更新，但 header 第二行显示专属短语「🔍 待验证」，
+ *   让用户一眼看出任务在等验收而不是在跑。
+ */
+ | "to_validate";
 /** workflow 卡片状态（与 CardStatus 同集合；语义别名，便于阅读） */
 export type WorkflowCardStatus = CardStatus;
 /** 里程碑（关键节点）：时间 + 标题 + 描述 */
@@ -262,7 +269,12 @@ export interface StartTaskResult {
 export interface LarkCardPatchNotifierOptions {
     /** 启动时是否 pin（默认 true） */
     pinOnStart?: boolean;
-    /** 结束时是否 unpin（默认 true） */
+    /**
+     * 结束时是否 unpin（Task #5164 需求 2a：**默认 false**）
+     *
+     * 任务完成/暂停时不再自动取消置顶 —— pin 去留由用户手动决定。
+     * 需要旧行为（自动 unpin）的调用方显式传 true。
+     */
     unpinOnFinish?: boolean;
 }
 export interface CardPayload {
@@ -805,6 +817,33 @@ export declare class LarkCardPatchNotifier {
      * 不会被旧 messageId 的终态记录误伤。
      */
     private finalisedCards;
+    /**
+     * ★ Task #5182 follow-up：解除某张卡片的终态标记（reopen 用）。
+     *
+     * ## 为什么需要
+     *
+     * `finalisedCards` 守卫（Task #5020）会吞掉 finishTask 之后的
+     * 一切 updateTask —— 这对「迟到的并发更新」是正确语义，但对
+     * **reopen**（closed 卡片 + 任务重新激活 → 复用原卡）是错的：
+     * reopen 本来就是要"复活"这张卡。真网取证（2026-11-08 18:00）：
+     * reopenReuseCard 打了「已复用原卡」日志 + pin 成功，但 patch
+     * 被守卫静默吞掉，卡片内容停在「已完成」。
+     *
+     * ## 行为
+     *
+     * - 从 finalisedCards 删除 messageId（守卫解除）
+     * - 内存态不存在时从 exportState 快照恢复？—— 不，states 已被
+     *   finishTask delete，快照无从取。调用方（reopenReuseCard）
+     *   会经 mergeTimelineState/updateTask 的默认 state 重建时间线，
+     *   并由 hook 层 hydrate（restoreCardState → hydrateState）补齐。
+     * - 对未终结的卡是 no-op（finalisedCards 本就没有该 id）
+     */
+    unfinaliseCard(messageId: string): void;
+    /**
+     * ★ Task #5182 follow-up：测试注入点 —— 替换 runLarkCli 的执行器。
+     * 仅测试使用（生产路径不设置），避免真 spawn lark-cli。
+     */
+    testRunner?: (argv: string[], op: string) => Promise<string>;
     /** 诊断：当前跟踪中的卡片数（测试/自检用） */
     trackedCardCount(): number;
     /** 诊断：当前跟踪中的 workflow 卡片数（测试/自检用） */

package/dist/env/task/plugins/lark-card-patch-notifier.js

@@ -22,7 +22,7 @@ import {
   resolveTaskTitleForDisplay,
   sanitizeInlineText,
   truncateHeadTitle
-} from "../../../shared/@ai-setting/roy-agent-core-w0qjeq2v.js";
+} from "../../../shared/@ai-setting/roy-agent-core-7dd0s3xb.js";
 import"../../../shared/@ai-setting/roy-agent-core-qq96p0tj.js";
 import"../../../shared/@ai-setting/roy-agent-core-7f7t9wwp.js";
 import"../../../shared/@ai-setting/roy-agent-core-85xyctnb.js";

package/dist/env/task/plugins/lark-cli-task-notify-plugin.d.ts

@@ -339,6 +339,22 @@ export declare class LarkCliTaskNotifyHook implements Hook {
      *   持久层 `pinned=false`（如实反映真实状态，不谎报）。
      */
     private repinAfterResume;
+    /**
+     * ★ Task #5182 — reopen 复用原卡（用户明令 2026-11-08 15:56）
+     *
+     * 场景：lark-cards.db 里该 task 的记录是 `closed`，但任务被重新激活
+     * （status → active 等活跃态）。旧实现发一张新卡（同 task 两张卡、
+     * 历史时间线留在旧卡上）；新实现：
+     *
+     *   1. patch 原 messageId：内容 = 当前任务态 + 「🔄 任务重新打开」里程碑
+     *   2. 新增一条 reopen 操作记录进卡片时间线（用户可见的 reopen 痕迹）
+     *   3. 重新 pin（终态时被 unpin 过；pin 状态必须跟任务状态一致）
+     *   4. 持久层 markReopened（closed → open，messageId 不变）
+     *
+     * @returns true = 原卡复用成功（caller 直接返回，不再走建卡路径）；
+     *          false = 原卡 patch 失败（caller 降级走发新卡路径）
+     */
+    private reopenReuseCard;
     /** 合并「写记录」所需的公共字段（读旧记录失败也不抛，降级为 now） */
     private buildCardState;
     /** 对外只读：某 task 的持久化卡片记录（debug / 排查用） */