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

package/dist/env/event-source/event-source-handlers.js

@@ -1,7 +1,10 @@
 import {
+  LARK_CHANNEL_PROMPT_SECTION_TITLE,
+  LARK_PROMPT_LENGTH_BUDGET,
   LarkCliInstance,
   bountyCliHandler,
   bountyIMHandler,
+  buildLarkChannelSystemPrompt,
   buildLarkRecommendedAction,
   builtInHandlers,
   extractCommandText,
@@ -10,29 +13,33 @@ import {
   larkCliHandler,
   patchCardByLarkCli,
   renderRuleNoticeSection,
-  timerHandler
-} from "../../shared/@ai-setting/roy-agent-core-t3rrb959.js";
-import"../../shared/@ai-setting/roy-agent-core-bxkjk7zx.js";
+  resolveLarkChannelSystemPrompt,
+  timerHandler,
+  wecomCliHandler
+} from "../../shared/@ai-setting/roy-agent-core-xf6z96qy.js";
+import"../../shared/@ai-setting/roy-agent-core-vx8zc847.js";
 import {
   cliCommandHandler
 } from "../../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-6cy43nss.js";
+import"../../shared/@ai-setting/roy-agent-core-d1n4jbza.js";
+import"../../shared/@ai-setting/roy-agent-core-7dd0s3xb.js";
+import"../../shared/@ai-setting/roy-agent-core-rykf7c04.js";
 import"../../shared/@ai-setting/roy-agent-core-c2gbt68e.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";
-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-ntn32q7j.js";
 import"../../shared/@ai-setting/roy-agent-core-mkc3zshb.js";
 import"../../shared/@ai-setting/roy-agent-core-az13yzmc.js";
@@ -48,7 +55,9 @@ 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 {
+  wecomCliHandler,
   timerHandler,
+  resolveLarkChannelSystemPrompt,
   renderRuleNoticeSection,
   patchCardByLarkCli,
   larkCliHandler,
@@ -58,7 +67,10 @@ export {
   cliCommandHandler,
   builtInHandlers,
   buildLarkRecommendedAction,
+  buildLarkChannelSystemPrompt,
   bountyIMHandler,
   bountyCliHandler,
-  LarkCliInstance
+  LarkCliInstance,
+  LARK_PROMPT_LENGTH_BUDGET,
+  LARK_CHANNEL_PROMPT_SECTION_TITLE
 };

package/dist/env/event-source/index.d.ts

@@ -9,6 +9,7 @@ export { BUILT_IN_EVENT_SOURCE_TYPES, BUILT_IN_EVENT_SOURCE_TYPE_LIST } from "./
 export { isBuiltInEventSourceType, isValidEventSourceType, getDefaultConfigForType, validateEventSourceConfig, } from "./types";
 export { EventSourceComponent } from "./event-source-component";
 export { COMMAND_PREFIX, isCommandMessage, extractCommandInvocation, CommandRegistry, getGlobalCommandRegistry, handleCommandMessage, } from "./command-registry";
+export { esCommand, resolveEsFilePath } from "./es-command";
 export type { CommandInvocation, CommandContext, CommandOutput, CommandTextOutput, CommandCardOutput, CommandResult, CommandDefinition, } from "./command-registry";
 export { renderTextCard, renderFallbackModelCard, isFallbackModelCard, FALLBACK_MODEL_ACTIONS, FALLBACK_MODEL_ACTION_NS, } from "./command-cards";
 export type { LarkCard } from "./command-types";
@@ -17,7 +18,10 @@ export type { CommandCardActionEvent, CommandCardActionPorts, CommandCardActionR
 export { fallbackModelCommand, listCommand, readFallbackModelList, readRawFallbackModelArray, writeFallbackModelList, DEFAULT_CONFIG_PATH, } from "./fallback-model-command";
 export { EventStoreImpl, setSharedEventStore, getSharedEventStore, resetSharedEventStore, } from "./event-store";
 export type { EventStore, TriggerEventInput, TriggerEventMetadata, PersistedEvent, EventStoreOptions, } from "./event-store";
-export { larkCliHandler, timerHandler, bountyIMHandler, cliCommandHandler, builtInHandlers, getBuiltInHandler, extractMetadata, } from "./event-source-handlers";
+export { larkCliHandler, timerHandler, bountyIMHandler, cliCommandHandler, wecomCliHandler, builtInHandlers, getBuiltInHandler, extractMetadata, buildLarkRecommendedAction, buildLarkChannelSystemPrompt, resolveLarkChannelSystemPrompt, LARK_CHANNEL_PROMPT_SECTION_TITLE, LARK_PROMPT_LENGTH_BUDGET, } from "./event-source-handlers";
+export { WECOM_CLI_ES_TYPE, WECOM_CHAT_ID_PREFIX, WECOM_WS_DEFAULT_URL, wecomCliHandler as wecomCliHandlerDirect, buildWecomReplyChannel, buildWecomNotifyPrompt, buildWecomChannelSystemPrompt, WECOM_CHANNEL_PROMPT_SECTION_TITLE, parseWecomFrame, readWecomCredentialsFile, resolveWecomCredentials, WECOM_CREDENTIALS_DEFAULT_PATH, resolveWecomBinary, probeCommandBinary, readWecomCliConfig, } from "./wecom-cli-handler";
+export type { WecomReplyChannelInput, WecomNotifyPromptInput, WecomChannelSystemPromptInput, WecomCredentials, ParsedWecomFrame, } from "./wecom-cli-handler";
+export { sanitizeWecomFrame } from "./wecom-ws-bridge";
 export { CLI_COMMAND_ES_TYPE, CLI_SESSION_CHAT_ID_PREFIX, buildCliReplyChannel, parseCliSessionChatId, } from "./cli-command-handler";
 export type { CliReplyChannel, CliNoticeSink } from "./cli-command-handler";
 export { TimerInstance } from "./timer-handler";

package/dist/env/event-source/index.js

@@ -1,7 +1,7 @@
-import"../../shared/@ai-setting/roy-agent-core-b4x6x4k2.js";
+import"../../shared/@ai-setting/roy-agent-core-m1fgtnrc.js";
 import {
   EventSourceComponent
-} from "../../shared/@ai-setting/roy-agent-core-cxy143m4.js";
+} from "../../shared/@ai-setting/roy-agent-core-begm7ytz.js";
 import {
   BountyIMInstance,
   COMMAND_PREFIX,
@@ -9,10 +9,23 @@ import {
   DEFAULT_CONFIG_PATH,
   FALLBACK_MODEL_ACTIONS,
   FALLBACK_MODEL_ACTION_NS,
+  LARK_CHANNEL_PROMPT_SECTION_TITLE,
+  LARK_PROMPT_LENGTH_BUDGET,
   TimerInstance,
+  WECOM_CHANNEL_PROMPT_SECTION_TITLE,
+  WECOM_CHAT_ID_PREFIX,
+  WECOM_CLI_ES_TYPE,
+  WECOM_CREDENTIALS_DEFAULT_PATH,
+  WECOM_WS_DEFAULT_URL,
   bountyIMHandler,
   buildDefaultBountyIMSystemPrompt,
+  buildLarkChannelSystemPrompt,
+  buildLarkRecommendedAction,
+  buildWecomChannelSystemPrompt,
+  buildWecomNotifyPrompt,
+  buildWecomReplyChannel,
   builtInHandlers,
+  esCommand,
   extractCommandInvocation,
   extractMetadata,
   fallbackModelCommand,
@@ -25,15 +38,25 @@ import {
   isFallbackModelCard,
   larkCliHandler,
   listCommand,
+  parseWecomFrame,
+  probeCommandBinary,
   readFallbackModelList,
   readRawFallbackModelArray,
+  readWecomCliConfig,
+  readWecomCredentialsFile,
   renderFallbackModelCard,
   renderTextCard,
   resolveBountyIMSystemPrompt,
+  resolveEsFilePath,
+  resolveLarkChannelSystemPrompt,
+  resolveWecomBinary,
+  resolveWecomCredentials,
+  sanitizeWecomFrame,
   timerHandler,
   translateCardActionToCommand,
+  wecomCliHandler,
   writeFallbackModelList
-} from "../../shared/@ai-setting/roy-agent-core-t3rrb959.js";
+} from "../../shared/@ai-setting/roy-agent-core-xf6z96qy.js";
 import {
   BUILT_IN_EVENT_SOURCE_TYPES,
   BUILT_IN_EVENT_SOURCE_TYPE_LIST,
@@ -42,7 +65,7 @@ import {
   isBuiltInEventSourceType,
   isValidEventSourceType,
   validateEventSourceConfig
-} from "../../shared/@ai-setting/roy-agent-core-bxkjk7zx.js";
+} from "../../shared/@ai-setting/roy-agent-core-vx8zc847.js";
 import {
   CLI_COMMAND_ES_TYPE,
   CLI_SESSION_CHAT_ID_PREFIX,
@@ -51,7 +74,9 @@ import {
   parseCliSessionChatId
 } from "../../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 {
   EventStoreImpl,
   getSharedEventStore,
@@ -59,19 +84,19 @@ import {
   setSharedEventStore
 } from "../../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-6cy43nss.js";
+import"../../shared/@ai-setting/roy-agent-core-d1n4jbza.js";
+import"../../shared/@ai-setting/roy-agent-core-7dd0s3xb.js";
+import"../../shared/@ai-setting/roy-agent-core-rykf7c04.js";
 import"../../shared/@ai-setting/roy-agent-core-c2gbt68e.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";
-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-ntn32q7j.js";
 import"../../shared/@ai-setting/roy-agent-core-mkc3zshb.js";
 import"../../shared/@ai-setting/roy-agent-core-az13yzmc.js";
@@ -88,16 +113,27 @@ import"../../shared/@ai-setting/roy-agent-core-85xyctnb.js";
 import"../../shared/@ai-setting/roy-agent-core-fs0mn2jk.js";
 export {
   writeFallbackModelList,
+  wecomCliHandler as wecomCliHandlerDirect,
+  wecomCliHandler,
   validateEventSourceConfig,
   translateCardActionToCommand,
   timerHandler,
   setSharedEventStore,
+  sanitizeWecomFrame,
+  resolveWecomCredentials,
+  resolveWecomBinary,
+  resolveLarkChannelSystemPrompt,
+  resolveEsFilePath,
   resolveBountyIMSystemPrompt,
   resetSharedEventStore,
   renderTextCard,
   renderFallbackModelCard,
+  readWecomCredentialsFile,
+  readWecomCliConfig,
   readRawFallbackModelArray,
   readFallbackModelList,
+  probeCommandBinary,
+  parseWecomFrame,
   parseCliSessionChatId,
   listCommand,
   larkCliHandler,
@@ -115,12 +151,25 @@ export {
   fallbackModelCommand,
   extractMetadata,
   extractCommandInvocation,
+  esCommand,
   cliCommandHandler,
   builtInHandlers,
+  buildWecomReplyChannel,
+  buildWecomNotifyPrompt,
+  buildWecomChannelSystemPrompt,
+  buildLarkRecommendedAction,
+  buildLarkChannelSystemPrompt,
   buildDefaultBountyIMSystemPrompt,
   buildCliReplyChannel,
   bountyIMHandler,
+  WECOM_WS_DEFAULT_URL,
+  WECOM_CREDENTIALS_DEFAULT_PATH,
+  WECOM_CLI_ES_TYPE,
+  WECOM_CHAT_ID_PREFIX,
+  WECOM_CHANNEL_PROMPT_SECTION_TITLE,
   TimerInstance,
+  LARK_PROMPT_LENGTH_BUDGET,
+  LARK_CHANNEL_PROMPT_SECTION_TITLE,
   FALLBACK_MODEL_ACTION_NS,
   FALLBACK_MODEL_ACTIONS,
   EventStoreImpl,

package/dist/env/event-source/types.d.ts

@@ -40,11 +40,22 @@ export declare const BUILT_IN_EVENT_SOURCE_TYPES: {
      * 「CLI 没有 IM 通道，输出到 stdout」的 prompt（而不是套用飞书模板）。
      */
     readonly CLI_COMMAND: "cli-command";
+    /**
+     * ★ Task #5142：企业微信（WeCom）也是一个事件源。
+     *
+     * 走企微官方 CLI `wecom-cli`（npm: `@wecom/cli`）。
+     *
+     * ⚠️ **必须是新类型名 `wecom-cli`，不能抄 `lark-cli`**：
+     * `getHandlerForEsType(esType)` 是 v2 notify prompt 的唯一分派 key，
+     * 抄成 lark-cli 会让 agent 拿到「用 lark-cli 发到 oc_xxx」的 prompt，
+     * 而企微根本没有 oc_xxx。
+     */
+    readonly WECOM_CLI: "wecom-cli";
 };
 /**
  * 内置事件源类型列表
  */
-export declare const BUILT_IN_EVENT_SOURCE_TYPE_LIST: ("lark-cli" | "timer" | "bounty-im" | "cli-command")[];
+export declare const BUILT_IN_EVENT_SOURCE_TYPE_LIST: ("lark-cli" | "timer" | "bounty-im" | "cli-command" | "wecom-cli")[];
 /**
  * HandleRuleConfig
  *
@@ -161,8 +172,27 @@ export interface EventSourceConfig {
      *
      * 内置 bounty-im handler 在 config.systemPrompt 未设置时使用默认 prompt；
      * 用户可显式覆盖。
+     *
+     * ★ ES-M1（Task #5144）：lark-cli 渠道在 lean 模式下，未配置本字段时
+     * 也会注入渠道静态 prompt（buildLarkChannelSystemPrompt），规则文本
+     * 前置到 system prompt；配置了则用户值在前 + 渠道 prompt 在后。
      */
     systemPrompt?: string;
+    /**
+     * 渠道 prompt 模式（ES-M1，Task #5144；默认 "lean"）
+     *
+     * - "lean"（默认）：渠道静态回复规则（关键 0/1/2/3、30KB 上限、禁分段、
+     *   --as bot、mktemp+jq 模板，~1566 tok）前置注入 system prompt；
+     *   per-event recommendedAction 压缩为动态小卡片（action 一句话 +
+     *   replyTo 四元组）。
+     * - "legacy"：per-source 回退开关 —— 行为与旧版完全一致
+     *   （recommendedAction 4.4KB 长模板、无渠道 systemPrompt 注入）。
+     *
+     * 用途：灰度期如果 sub-agent / 第三方 consumer 依赖
+     * `payload.message` 里 JSON 的长模板规则文本，可将该 source
+     * 回退为 legacy。
+     */
+    channelPromptMode?: "legacy" | "lean";
     /**
      * Agent IM 地址（bounty-im 类型用，格式：agent-id@host）
      *
@@ -244,6 +274,30 @@ export interface EventMetadata {
     senderEmail?: string;
     /** 租户 key */
     tenantKey?: string;
+    /**
+     * ★ Task #5212：lark 引用消息上下文
+     *
+     * lark-cli `im.message.receive_v1` 事件的引用字段归一化：
+     * - rootId:   根消息 id（root_id）
+     * - parentId: 直接回复的父消息 id（reply_to / parent_id）
+     * - threadId: thread id（thread_id），仅 thread 场景存在
+     *
+     * 无任何引用字段（普通消息）时为 undefined。
+     * agent 据此知道当前消息是对哪条消息的回复。
+     */
+    replyContext?: {
+        rootId?: string;
+        parentId?: string;
+        threadId?: string;
+        /**
+         * ★ Task #5251：企微引用内容（quote 内嵌原文归一文本）
+         *
+         * 企微长连接协议直接内嵌被引用内容（SDK BaseMessage.quote），
+         * 无被引用消息 id —— 因此企微侧只有 quotedText，
+         * 无 rootId/parentId/threadId（那些是 lark 侧字段）。
+         */
+        quotedText?: string;
+    };
     /**
      * 事件源注入到 agent systemPrompt 的专属 prompt
      *
@@ -262,6 +316,45 @@ export interface EventMetadata {
 export interface RecommendedAction {
     /** 动作描述 */
     action: string;
+    /**
+     * ★ ES-M1（Task #5144）：静态规则是否已前置到渠道 system prompt。
+     *
+     * lean 模式（默认）下 extractMetadata 会置 `true`：
+     * 规则文本（关键 0/1/2/3、30KB 上限、禁分段、--as bot、mktemp+jq
+     * 模板）不再出现在 `action` 里，而是注入了渠道 system prompt
+     * （EventMetadata.systemPrompt）。旧 consumer / 灰度观察者可据此
+     * 识别"卡片已瘦身"这一新形态。
+     *
+     * legacy 模式不设置该字段（保持旧版形态识别）。
+     */
+    staticRulesInSystemPrompt?: true;
+    /**
+     * ★ Task #5212（DS review MAJOR-2）：lark 引用消息上下文
+     *
+     * 当前消息「是对哪条消息的回复」的定位信息（rootId / parentId / threadId）。
+     *
+     * ⚠️ 为什么挂在 recommendedAction 而不是只挂 metadata：
+     *   agent 实际收到的 user message = `payload.message` =
+     *   `JSON.stringify({ rawData, recommendedAction, triggerEventId? })`
+     *   —— **不含 metadata 键**。只写进 evt.metadata / evt.payload.metadata
+     *   的话，agent 读不到任何 parentId 值，需求（「让 agent LLM 看到是对某
+     *   消息 id 的回复」）无法闭环。
+     *
+     * 无引用字段（普通消息）时为 undefined（不产生空对象）。
+     */
+    replyContext?: {
+        rootId?: string;
+        parentId?: string;
+        threadId?: string;
+        /**
+         * ★ Task #5251：企微引用内容（quote 内嵌原文归一文本）
+         *
+         * 企微长连接协议直接内嵌被引用内容（SDK BaseMessage.quote），
+         * 无被引用消息 id —— 因此企微侧只有 quotedText，
+         * 无 rootId/parentId/threadId（那些是 lark 侧字段）。
+         */
+        quotedText?: string;
+    };
     /** 回复目标（如果有） */
     replyTo?: {
         appId?: string;
@@ -346,6 +439,13 @@ export interface EventSourceEventPayload {
      * 反查原始 chatId。
      */
     triggerEventId?: string;
+    /**
+     * Task #5199：已落盘媒体文件的本地路径（image/file/video/voice）。
+     *
+     * WecomCliInstance.handleWsFrame 异步下载解密后写入；
+     * agent 用 understand_image(image_source=<path>) 读图。
+     */
+    mediaFiles?: string[];
 }
 /**
  * EventSource 事件

package/dist/env/event-source/wecom-card-action-handler.d.ts

@@ -0,0 +1,141 @@
+/**
+ * @fileoverview Task #5203 — 企微卡片按钮点击处理
+ *
+ * ## 触发链路
+ *
+ * 用户点 button_interaction 卡片按钮
+ * → 企微推 `template_card_event`（aibot_event_callback，5 秒窗口）
+ * → WecomCliInstance.handleWsFrame 分流（不走 Agent）
+ * → 本模块 handleWecomCardAction：
+ *   1. 解析 event_key / task_id（反解出 roy 任务号）
+ *   2. 触发对应 task 操作（mark_done → taskComponent.updateTask(status=completed)）
+ *   3. 经 aibot_respond_update_msg（透传回调 req_id）更新卡片按钮态
+ *
+ * ## 设计原则（对齐 lark-card-action-handler.ts）
+ *
+ * - 纯函数 + IO 端口注入（markTaskDone / reopenTask / updateCard）
+ * - 失败明确返回 ok=false，不静默成功
+ * - 并发去重：同 (cardTaskId, action) 处理中 → 后到的拒绝
+ *   （用户双击会产生两条独立回调）
+ *
+ * ## task_id 反解
+ *
+ * 发卡时 task_id 形如 `roy-task-<taskId>-<seq>-<rand>`（wecom-card-builder）；
+ * 回调原样带回 → 用前缀 `roy-task-` 反解出数字任务号。
+ * 非 roy-task 前缀（外部卡片）→ taskId=null，动作不执行。
+ */
+import { type WecomMilestoneLite } from "./wecom-card-builder";
+/** 卡片动作类型 */
+export type WecomCardAction = "view" | "mark_done" | "reopen";
+/** 解析出的卡片动作事件 */
+export interface WecomCardActionEvent {
+    /** 用户点的按钮 key（WecomCardActionKey 之一或外部自定义） */
+    eventKey: string;
+    /** 回调带回的原始 task_id（原样回填更新帧） */
+    cardTaskId: string;
+    /** 反解出的任务号；非 roy-task 前缀 → null */
+    taskId: number | null;
+    /** 操作者 userid */
+    userId: string;
+    /** 回调帧 req_id（更新帧必须原样透传） */
+    reqId: string;
+}
+/** IO 端口（caller 注入；本模块保持纯函数） */
+export interface WecomCardActionPorts {
+    /** 标记任务完成（status=completed） */
+    markTaskDone: (taskId: number) => Promise<void>;
+    /** 重新打开任务（status=active） */
+    reopenTask: (taskId: number) => Promise<void>;
+    /**
+     * 更新卡片（aibot_respond_update_msg，5 秒窗口内）
+     * @param cardTaskId 回调带回的原始 task_id
+     * @param timeline view 动作时携带的操作时间线（可选）
+     * @param action ★ Task #5250：触发动作（决定更新后的按钮：
+     *   view/reopen → 可点击「刷新详情」；mark_done → 「已处理」）
+     */
+    updateCard: (reqId: string, cardTaskId: string, statusLabel: string, note?: string, timeline?: WecomMilestoneLite[], action?: WecomCardAction, 
+    /**
+     * ★ Task #5273：任务号+标题（可选，渲染进更新卡 main_title）
+     */
+    extra?: {
+        taskNumber?: number;
+        taskTitle?: string;
+    }) => Promise<void>;
+    /**
+     * ★ Task #5203：读任务的操作时间线（milestones + processSteps）。
+     *
+     * view 动作用它把完整操作记录刷进卡片正文。
+     * 无记录 / 读取失败 → 返回 []（降级为简单按钮态更新）。
+     */
+    loadTimeline?: (taskId: number) => WecomMilestoneLite[];
+    /**
+     * ★ Task #5273：读任务号+标题（渲染进更新卡 main_title，
+     * 修复「卡片缺 Task #ID 和 title」）。
+     *
+     * ★ CV-B1（Task #5273 返工）：生产实现（wecom-cli-handler）
+     *   从 taskComponent 读任务，返回 **Promise** —— 端口签名必须
+     *   允许 Promise，消费端 doHandle 必须 await。
+     * 返回 undefined / reject / 抛错 → 降级为无标题（卡片更新不阻断）。
+     */
+    loadTaskTitle?: (taskId: number) => {
+        title?: string;
+        number?: number;
+    } | undefined | Promise<{
+        title?: string;
+        number?: number;
+    } | undefined>;
+}
+/** 处理结果 */
+export interface WecomCardActionResult {
+    ok: boolean;
+    /** 执行的动作（解析失败时缺省） */
+    action?: WecomCardAction;
+    error?: string;
+}
+/** 测试钩子：清空 in-flight 去重表（仅供单测 beforeEach 使用） */
+export declare function __resetWecomCardActionInflightForTest(): void;
+/**
+ * 从 WS 帧解析 template_card_event。
+ *
+ * 非 template_card_event（消息帧 / 其他事件）→ null。
+ */
+export declare function extractWecomCardAction(frame: unknown): WecomCardActionEvent | null;
+/**
+ * 处理卡片按钮点击。
+ *
+ * @returns 处理结果（ok=true 表示动作已执行 + 卡片已更新）
+ */
+export declare function handleWecomCardAction(frame: unknown, ports: WecomCardActionPorts): Promise<WecomCardActionResult>;
+/**
+ * 构造卡片更新帧（aibot_respond_update_msg）。
+ *
+ * 供 caller（WecomCliInstance）把 ports.updateCard 接到 bridge.respond：
+ * bridge.respond(reqId, buildWecomCardUpdateBody(...).body)。
+ *
+ * 独立导出是为了单测不依赖 bridge。
+ */
+export declare function buildWecomCardUpdateBody(input: {
+    cardTaskId: string;
+    statusLabel: string;
+    note?: string;
+    /** ★ Task #5203：view 动作携带的操作时间线 */
+    timeline?: WecomMilestoneLite[];
+    /**
+     * ★ Task #5250：触发更新的动作（决定更新后的按钮）。
+     *
+     * - view / reopen → 保留可点击的「刷新详情」（key=task_view）：
+     *   用户可**重复点击**刷新最新里程碑/操作记录
+     * - mark_done / 缺省（旧调用方）→ 死按钮「已处理」
+     *   （key=task_done_ack，终态确认，向后兼容 #5203 行为）
+     */
+    action?: WecomCardAction;
+    /**
+     * ★ Task #5273：任务号+标题（可选，渲染进 main_title，
+     * 修复「更新卡缺 Task #ID 和 title」）
+     */
+    taskTitle?: string;
+    taskNumber?: number;
+}): {
+    cmd: string;
+    body: Record<string, unknown>;
+};