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

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

@@ -0,0 +1,373 @@
+/**
+ * @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 WecomActivityLike, type WecomMilestoneLite } from "./wecom-card-builder";
+import type { WecomSessionCardState } from "../task/plugins/wecom-session-card-store";
+import type { ActivityProbeResult } from "../task/plugins/sub-session-activity";
+/**
+ * 卡片动作类型
+ *
+ * ★ Task #5360：新增 `refresh_activity`（刷新 sub-session 活性）。
+ *
+ * 与 `view`（刷操作时间线）分开，因为企微 `horizontal_content_list` 只有
+ * 6 条预算且已被时间线占满 —— 见 wecom-card-builder 的
+ * `WecomCardActionKey.REFRESH_ACTIVITY` 注释。
+ *
+ * ★ Task #5419：新增 `create_lark_group`（建关联飞书群，对齐飞书）。
+ */
+export type WecomCardAction = "view" | "mark_done" | "reopen" | "refresh_activity" | "create_lark_group";
+/** 解析出的卡片动作事件 */
+export interface WecomCardActionEvent {
+    /** 用户点的按钮 key（WecomCardActionKey 之一或外部自定义） */
+    eventKey: string;
+    /** 回调带回的原始 task_id（原样回填更新帧） */
+    cardTaskId: string;
+    /** 反解出的任务号；非 roy-task 前缀 → null */
+    taskId: number | null;
+    /**
+     * ★ 补充需求（22:31）：反解出的 sub-session id（`roy-session-` 前缀）。
+     * 与 `taskId` 互斥：一张卡要么挂 task，要么挂 session。
+     */
+    sessionId: string | 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）
+     * ★ Task #5360：`activity` —— sub-session 活性
+     *   （`undefined` = 不渲染；`null` = 查了但没数据，渲染「暂无数据」）
+     */
+    extra?: {
+        taskNumber?: number;
+        taskTitle?: string;
+        activity?: WecomActivityLike | null;
+        /** ★ Task #5360（CV MAJOR-2）：任务是否已终态（决定 ⚪已结束 vs 🔴疑似停滞） */
+        activityTerminal?: boolean;
+    }) => Promise<void>;
+    /**
+     * ★ Task #5364（B 方案）：用**完整快照**刷新 session 卡。
+     *
+     * 与 `updateCard` 的区别：那个是 task 卡的通用更新（statusLabel/timeline/
+     * activity 三个松散参数）；本端口接收一次完整的 session 快照，由实现方
+     * 调 `buildWecomSessionCardUpdateBody` 渲染「生命周期 + 会话详情 + 任务 +
+     * 操作记录 + 活性」一整套。
+     *
+     * 未注入 ⇒ 自动降级到 `updateCard`（#5360 行为，仅活性）。
+     */
+    updateSessionCard?: (reqId: string, input: {
+        sessionId: string;
+        /** 回调带回的原始 task_id（刷新帧必须原样回填） */
+        cardTaskId: string;
+        /** 持久层快照；undefined = 无记录（降级仅活性） */
+        state?: WecomSessionCardState;
+        /** 实时活性；null = 查了但没数据 */
+        activity: WecomActivityLike | null;
+        /**
+         * ★ Task #5419：session 关联的任务信息（刷新增强）。
+         * undefined = 无任务 / 端口未注入。
+         */
+        task?: {
+            id: number;
+            title?: string;
+            status?: string;
+            progress?: number;
+            milestones?: WecomMilestoneLite[];
+        };
+        /**
+         * ★ Task #5419：已关联飞书群 chatId（建群后刷新帧带群链接）。
+         */
+        perTaskChatId?: string;
+        /**
+         * ★ CV 5419 MAJOR-3：建群失败提示（渲染进 sub_title）。
+         */
+        errorHint?: string;
+        now?: number;
+    }) => 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>;
+    /**
+     * ★ Task #5360：读 sub-session 活性（「刷新活性」动作用）。
+     *
+     * 与飞书侧 `CardActionPorts.loadSubSessionActivity` **同一个 probe 实现**
+     * （`createActivityProbe`），避免两渠道 liveness 阈值漂移。
+     *
+     * 不注入 / 抛错 / undefined ⇒ 卡片渲染「暂无数据」，绝不阻断更新。
+     */
+    loadSubSessionActivity?: (taskId: number) => Promise<ActivityProbeResult> | ActivityProbeResult;
+    /**
+     * ★ 补充需求（22:31）：**session-only** 活性读取（无 task 场景）。
+     *
+     * 与 `loadSubSessionActivity(taskId)` 的区别：后者要从 task 反查 bgTask；
+     * 本端口**直达** session store —— 因为回调里直接带着 sessionId，
+     * 而这条链上根本没有 task。
+     */
+    loadSessionActivity?: (sessionId: string) => Promise<ActivityProbeResult> | ActivityProbeResult;
+    /**
+     * ★ Task #5364（B 方案）：读 **session 卡持久层**快照。
+     *
+     * ## 为什么刷新必须走它（而不是内存 / task）
+     *
+     * B 方案下「后续 lifecycle 不主动 patch，只写持久层」，所以**刷新是唯一
+     * 能看到最新状态的时机**。快照里带着：
+     * - `lifecycle`（超时 / 完成 / 失败 / 停止 —— 单靠活性推不出来）
+     * - `title` / `agentType` / `startedAt` / `associatedTaskId`（首次发卡的信息）
+     * - `milestones`（这一路的状态轨迹）
+     * - `cardTaskId`（刷新帧必须原样回填，否则协议拒绝）
+     *
+     * 读内存 map 的话进程重启就全丢；读 task 的话没有 task 的 session 全丢。
+     *
+     * 不注入 / 抛错 / undefined ⇒ 降级为「只有活性」的刷新卡（**仍更新卡片**，
+     * 用户点了按钮必须有反馈）。
+     */
+    loadSessionCardState?: (sessionId: string) => WecomSessionCardState | undefined | Promise<WecomSessionCardState | undefined>;
+    /**
+     * ★ Task #5418：按 roy 任务号反查 session 卡持久层记录。
+     *
+     * task 卡刷新路径回退 session probe 时需要 sessionId ——
+     * `roy-task-` 前缀卡回调里没有 sessionId，唯一持久化来源是
+     * `wecom_session_card.associated_task_id`。注入方（wecom-cli-handler）
+     * 用 `store.list()` 扫描；缺省 ⇒ 不回退（行为同旧版）。
+     */
+    findSessionCardByTaskId?: (taskId: number) => WecomSessionCardState | undefined | Promise<WecomSessionCardState | undefined>;
+    /**
+     * ★ Task #5419：session → task 反查 + 全量任务信息（刷新增强）。
+     *
+     * 用户 2026-11-13：「有刷新详情按钮可以刷新 subsession 状态
+     * （包括是否建任务，以及任务名称和动态，也包括 subsession 的
+     * 消息数）」。
+     *
+     * 生产接线（wecom-cli-handler）：`TaskComponent.getTaskIdBySessionId`
+     * （task_operation.session_id 反查）+ `getTaskWithOperations`。
+     *
+     * 返回 undefined = 该 session 没建任务（卡上不渲染任务行）；
+     * 抛错 = 降级（不阻断刷新）。
+     */
+    loadSessionTaskInfo?: (sessionId: string) => Promise<{
+        id: number;
+        title?: string;
+        status?: string;
+        progress?: number;
+        milestones?: WecomMilestoneLite[];
+    } | undefined> | {
+        id: number;
+        title?: string;
+        status?: string;
+        progress?: number;
+        milestones?: WecomMilestoneLite[];
+    } | undefined;
+    /**
+     * ★ Task #5419：建**关联飞书群**（对齐飞书 handleGroupActionSessionOnly）。
+     *
+     * 生产接线（wecom-cli-handler）：lark-cli +chat-create +
+     * SessionComponent.attachGroupSession（独立群 session + 1 条
+     * user 背景事件 + metadata linkedFromSessionId）。
+     *
+     * 返回新群 chatId；抛错 = 建群失败（结果翻失败，但卡片仍更新）。
+     */
+    createLarkGroupForSession?: (sessionId: string) => Promise<string>;
+    /**
+     * ★ Task #5419：读该 session 已关联的飞书群（幂等防重复建群）。
+     *
+     * 生产接线：`SessionComponent.findGroupChatForSession`
+     * （扫 metadata linkedFromSessionId，与飞书侧同源）。
+     * 未注入 / 抛错 ⇒ 当作没有群（可能重复建，但不崩）。
+     */
+    findGroupChatForSession?: (sessionId: string) => Promise<{
+        chatId: string;
+    } | undefined> | {
+        chatId: string;
+    } | undefined;
+    /**
+     * ★ Task #5419：建群成功后发一条企微消息带飞书群 applink。
+     *
+     * 用户：「建完可以展示或者发一条企微消息带上飞书群跳转链接哈」。
+     * best-effort：抛错不阻断建群结果。
+     */
+    notifyGroupLink?: (input: {
+        sessionId: string;
+        chatId: string;
+        /** 群名（可选，消息文案用） */
+        chatName?: string;
+        /**
+         * ★ CV 5419 BLOCKER-1：点击按钮的**企微用户** userid。
+         *
+         * 通知消息必须发给企微侧（不是飞书群 —— chatId 是
+         * 飞书群 id，企微 CLI 不认）。缺省时实现方从 session
+         * store 的 chatId 兜底。
+         */
+        userId?: string;
+    }) => Promise<void>;
+}
+/** 处理结果 */
+export interface WecomCardActionResult {
+    ok: boolean;
+    /** 执行的动作（解析失败时缺省） */
+    action?: WecomCardAction;
+    error?: string;
+    /**
+     * ★ Task #5419：create_lark_group 成功时的新群 chatId
+     * （幂等命中时 = 已有群 chatId）。
+     */
+    newChatId?: 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;
+    /**
+     * ★ Task #5360：sub-session 活性
+     * （`undefined` = 不渲染；`null` = 暂无数据）
+     */
+    activity?: WecomActivityLike | null;
+    /** ★ Task #5360（CV MAJOR-2）：任务是否已终态 */
+    activityTerminal?: boolean;
+}): {
+    cmd: string;
+    body: Record<string, unknown>;
+};
+/**
+ * ★ Task #5364（B 方案）—— 构造 **session 卡刷新**的更新帧。
+ *
+ * 独立导出（不走 ports）是为了：
+ * 1. 单测能直接断言渲染结果，不依赖 bridge
+ * 2. `WecomCliInstance` 的 `updateSessionCard` 实现只需要两步：
+ *    `buildWecomSessionCardUpdateBody(...)` → `sendFrameWithReqId`
+ *
+ * ## 为什么快照允许 `undefined`
+ *
+ * B 方案里持久层是「刷新时的唯一数据源」，但它可能不存在（进程刚重启 +
+ * 首次事件丢了 store / 老卡片）。此时**不能不给反馈** —— 用户点了按钮，
+ * 什么都没变比显示「暂无数据」更糟。所以降级路径渲染：状态=「状态未知」+
+ * 活性（活性反而是这时最有用的信号）。
+ */
+export declare function buildWecomSessionCardUpdateBody(input: {
+    /** 回调带回的原始 task_id（原样回填，协议硬约束） */
+    cardTaskId: string;
+    sessionId: string;
+    /**
+     * req_id（协议必填）。命名带 ForTest 是历史遗留：生产路径由
+     * `updateSessionCard` 端口在 `sendFrameWithReqId` 时注入 headers，
+     * 这里仅用于单测直接验证帧结构。
+     */
+    reqIdForTest?: string;
+    /** 持久层快照；undefined = 无记录 */
+    state?: WecomSessionCardState;
+    /** 活性；undefined = 不渲染该块，null = 暂无数据 */
+    activity?: WecomActivityLike | null;
+    now?: number;
+    /** 关联任务（可选覆盖；缺省从 state.associatedTaskId 推导编号） */
+    task?: {
+        id: number;
+        title?: string;
+        status?: string;
+        progress?: number;
+    };
+    /**
+     * ★ Task #5419：已关联飞书群 chatId（渲染「飞书群」行）。
+     */
+    perTaskChatId?: string;
+    /** ★ CV 5419 MAJOR-3：建群失败提示（渲染进 sub_title） */
+    errorHint?: string;
+}): {
+    cmd: string;
+    body: Record<string, unknown>;
+};