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

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

@@ -0,0 +1,426 @@
+/**
+ * @fileoverview Task #5203 — 企微真卡片（template_card）构造器
+ *
+ * ## 为什么存在
+ *
+ * #5193 用 markdown 模拟进展卡片（wecom-cli msg_type 无 template_card）。
+ * Task #5202 官方文档实锤：aibot WS 长连接协议**原生支持** template_card
+ * （aibot_send_msg 直发 + aibot_respond_update_msg 更新）——
+ * wecom-cli 只是没封装，走 WecomWsBridge 直发即可。
+ *
+ * ## 协议依据（官方文档取证，Task #5202/#5203）
+ *
+ * - 主动推送（101463）：`{cmd:"aibot_send_msg", headers:{req_id},
+ *   body:{chatid, chat_type, msgtype:"template_card", template_card:{...}}}`
+ *   chat_type：1 单聊（userid）/ 2 群聊 / 0 兼容
+ * - 模板卡片类型（101032）：
+ *   - text_notice：main_title / emphasis_content 必填，card_action 必填
+ *   - button_interaction：main_title / button_list / task_id 必填，
+ *     button_list ≤6，按钮 key 最长 1024 字节不可重复
+ *   - task_id：同一个机器人不能重复，只能由数字字母和 "_-@" 组成，≤128 字节
+ * - 卡片更新（101463）：`{cmd:"aibot_respond_update_msg",
+ *   headers:{req_id:事件回调透传}, body:{response_type:"update_template_card",
+ *   template_card:{...}}}` — 仅适用于 template_card_event，5 秒内回复；
+ *   template_card.task_id 须与回调收到的 task_id 一致
+ * - 按钮点击回调：template_card_event，event.event_key = 按钮 key
+ *
+ * ## task_id 策略
+ *
+ * 企微的 task_id 是「同一张卡的标识」（更新时用），而我们的任务
+ * 生命周期会**多次发卡**（每次进展一张新卡，企微无主动 patch）。
+ * ⇒ 发卡时用 `newWecomCardTaskId(taskId)`（带序号/时间戳，保证不重复）；
+ *   更新时必须用**回调里带回的 task_id**（buildWecomCardUpdateFrame 的
+ *   taskId 参数 = 回调解析出的原始 task_id）。
+ *
+ * @see wecom-ws-bridge.ts（帧发送）
+ * @see wecom-task-notify-plugin.ts（hook 接线）
+ */
+import { type SubSessionActivity } from "../task/plugins/sub-session-activity";
+/** 企微侧活性入参别名（与飞书侧同名类型，语义一致） */
+export type WecomActivityLike = SubSessionActivity;
+/** 标准按钮动作 key（回调 event_key 据此分发） */
+export declare const WecomCardActionKey: {
+    /** 查看详情（刷操作时间线） */
+    readonly VIEW: "task_view";
+    /** 标记完成 */
+    readonly MARK_DONE: "task_mark_done";
+    /** 重新打开 */
+    readonly REOPEN: "task_reopen";
+    /**
+     * ★ Task #5360：刷新 sub-session 活性（消息数 + 最近一条消息）。
+     *
+     * ## 为什么与 VIEW 分成两个按钮（而不是把活性塞进「刷新详情」）
+     *
+     * 企微 `horizontal_content_list` 协议上限 **6 条**（`MAX_HORIZONTAL_ROWS`），
+     * 而进展/更新卡的 6 条已经被「状态 + 5 条操作时间线」占满。把活性挤进去
+     * 必然挤掉操作时间线 —— 直接违反用户「之前展示的信息一个都不能少」。
+     *
+     * 所以：`task_view` 管时间线（旧语义零变更），`task_refresh_activity`
+     * 管活性（走 quote_area，不占 horizontal 预算）。
+     */
+    readonly REFRESH_ACTIVITY: "task_refresh_activity";
+    /**
+     * ★ Task #5419：建**关联飞书群**（对齐飞书 #5403/#5397）。
+     *
+     * 用户 2026-11-13：「另外也有按钮进行飞书建群哈，功能跟飞书一样，
+     * 建关联飞书群，建完可以展示或者发一条企微消息带上飞书群跳转链接哈」
+     *
+     * ## 为什么企微卡可以有「飞书群」按钮
+     *
+     * wecom-card-builder 旧注释（#5360）说「企微侧本来就没有 per-task
+     * 群概念」—— 那指的是**企微群**。#5403 之后建群的目标是
+     * **飞书群**（群 session 独立 + 注入背景事件），与企微群概念
+     * 正交：企微只是「遥控器」，群在飞书侧。
+     */
+    readonly CREATE_LARK_GROUP: "task_create_lark_group";
+};
+export type WecomCardActionKey = (typeof WecomCardActionKey)[keyof typeof WecomCardActionKey];
+/** 企微按钮 style：1 默认蓝 / 2 次要灰 / 3 / 4 强调（官方 1~4） */
+export type WecomButtonStyle = 1 | 2 | 3 | 4;
+export interface WecomCardButton {
+    text: string;
+    style?: WecomButtonStyle;
+    key: string;
+}
+export interface WecomHorizontalContent {
+    keyname: string;
+    value: string;
+    type?: 0 | 1;
+    url?: string;
+}
+export interface WecomMilestoneLite {
+    title: string;
+    timestamp: string;
+    description?: string;
+}
+/** text_notice 卡片结构（只声明我们用到的字段） */
+export interface WecomTextNoticeCard {
+    card_type: "text_notice";
+    main_title: {
+        title: string;
+        desc?: string;
+    };
+    emphasis_content: {
+        title: string;
+        desc: string;
+    };
+    sub_title_text?: string;
+    horizontal_content_list: WecomHorizontalContent[];
+    quote_area: {
+        type?: number;
+        title: string;
+        quote_text: string;
+    };
+    card_action: {
+        type: number;
+        url?: string;
+    };
+}
+/** button_interaction 卡片结构（只声明我们用到的字段） */
+export interface WecomButtonInteractionCard {
+    card_type: "button_interaction";
+    main_title: {
+        title: string;
+        desc?: string;
+    };
+    sub_title_text?: string;
+    horizontal_content_list?: WecomHorizontalContent[];
+    quote_area?: {
+        type?: number;
+        title: string;
+        quote_text: string;
+    };
+    button_list: WecomCardButton[];
+    card_action?: {
+        type: number;
+        url?: string;
+    };
+    /** ★ 必填：同一机器人不能重复；更新时须与回调一致 */
+    task_id: string;
+}
+/**
+ * 任务的稳定 task_id 前缀：`roy-task-<taskId>`。
+ *
+ * 用途：
+ * - 发卡时作为 `newWecomCardTaskId` 的前缀（可从回调 task_id 反解任务号）
+ * - 更新时**不能**用它（发卡用的是带序号的全量 id）——
+ *   更新帧的 task_id 必须原样用回调带回的值
+ */
+export declare function wecomCardTaskIdForTask(taskId: number): string;
+/**
+ * ★ 补充需求（22:31）：**session 卡**的稳定 task_id 前缀。
+ *
+ * 与 `roy-task-` 并列 —— 回调时用它区分「这张卡挂在 task 上」还是
+ * 「挂在 sub-session 上」。两种前缀互不包含（`roy-task-` vs `roy-session-`），
+ * 反解无歧义。
+ */
+export declare const ROY_SESSION_PREFIX = "roy-session-";
+/**
+ * 造 session 卡的稳定 task_id。
+ *
+ * ## 格式（★ 澄清 22:37：session 是主键，task 是附加值）
+ *
+ * ```
+ * roy-session-<sessionId>                ← 无关联 task
+ * roy-session-<sessionId>@task-<taskId>  ← 有关联 task
+ * ```
+ *
+ * 用 `@task-` 而不是再嵌前缀：企微 task_id 字符集限定「数字字母和 `_-@`」，
+ * `@` 合法；且 `roy-session-` 与 `roy-task-` 本来就互斥，反解无歧义。
+ *
+ * ⚠️ 反解时**只取 sessionId 部分**（task 段仅用于诊断/未来扩展）——
+ * 刷新永远读 session store，这是本次澄清的核心。
+ */
+export declare function wecomCardTaskIdForSession(sessionId: string, taskId?: number): string;
+/** session 卡 task_id 里「附加 task 段」的分隔符 */
+export declare const WECOM_SESSION_TASK_SEP = "@task-";
+/**
+ * 生成一张新卡的 task_id：`roy-task-<taskId>-<seq>-<rand>`。
+ *
+ * 协议硬约束：同一机器人不能重复 → 加序号 + 随机后缀。
+ * 字符集：数字字母和 "_-@"（官方 101032）。
+ */
+export declare function newWecomCardTaskId(taskId: number): string;
+/**
+ * 构造 text_notice 进展卡（任务状态一览）。
+ *
+ * 信息密度对齐 #5193 markdown 卡：标题+进度+状态+时间线+最新操作。
+ */
+export declare function buildWecomTextNoticeCard(input: {
+    taskId: number;
+    title: string;
+    statusLabel: string;
+    progress: number;
+    description?: string;
+    changeSummary?: string;
+    milestones: WecomMilestoneLite[];
+    /** 终态（completed/cancelled/…）→ sub_title_text 收尾文案 */
+    terminal?: boolean;
+}): WecomTextNoticeCard;
+/**
+ * 构造 button_interaction 交互卡（可点击按钮更新状态）。
+ *
+ * @param input.taskId 用于生成 task_id（回调据此反解任务）
+ * @param input.buttons 超过 6 个时只取前 6 个（协议上限）
+ */
+export declare function buildWecomButtonInteractionCard(input: {
+    taskId: number;
+    title: string;
+    statusLabel: string;
+    progress: number;
+    description?: string;
+    changeSummary?: string;
+    milestones?: WecomMilestoneLite[];
+    buttons: WecomCardButton[];
+    /** 已有的 task_id（更新场景复用；发新卡时不传自动生成） */
+    cardTaskId?: string;
+}): WecomButtonInteractionCard;
+/** session 层生命周期（与飞书侧同义） */
+export type WecomSessionLifecycle = "running" | "completed" | "timeout" | "failed" | "stopped";
+/**
+ * ★ Task #5364（DS review R1 MAJOR-2）—— **刷新帧**用的生命周期。
+ *
+ * 比 `WecomSessionLifecycle` 多一个 `unknown`：刷新时若持久层没有该
+ * session 的记录（进程重启 / store 读失败 / 更早版本发的卡），我们
+ * **不知道**它是什么状态。此时必须如实说「未知」而不是乐观地报
+ * 「运行中」—— 后者会和活性侧的 🔴 疑似停滞 同时出现在一张卡上，
+ * 给用户两个互相矛盾的信号。
+ */
+export type WecomSessionUpdateLifecycle = WecomSessionLifecycle | "unknown";
+/**
+ * ★ Task #5360（用户明令「企微也是这个逻辑」）—— 构造**企微 session 卡**。
+ *
+ * ## 与 task 卡的关系：并列，共用零件
+ *
+ * 不复用 `buildWecomButtonInteractionCard` 的原因：那个签名是
+ * `taskId: number`（必填）+ `buildWecomTextNoticeCard` 的进度百分比语义，
+ * session 没有 task 号也没有「进度 %」。硬塞会渲染出 `Task #0` / `0%` 这类噪音。
+ *
+ * 共用的是：`WecomButtonInteractionCard` 结构、按钮裁剪、`formatActivityQuote`
+ * （⇒ 活性阈值与文案与飞书/企微 task 卡**完全一致**，不会出现同一个
+ * session 在两个渠道颜色不同）。
+ *
+ * ## 主键
+ *
+ * `task_id = roy-session-<sessionId>[@task-<n>]` —— 回调时
+ * `parseRoySessionId` 反解出干净的 sessionId，刷新走 session 主键路径。
+ *
+ * ## 建群按钮（★ Task #5419 更新）
+ *
+ * #5360 时企微侧没有建群按钮（当时建群目标是企微群，确实没有）。
+ * #5403 之后建群目标改为**飞书群**（独立群 session + 背景事件），
+ * 企微卡只是遥控入口 —— 用户 2026-11-13 明令「也有按钮进行飞书
+ * 建群哈，功能跟飞书一样」。故 session 卡无条件渲染「建飞书群」。
+ */
+export declare function buildWecomSessionCard(input: {
+    /** ★ 主键：sub-session id */
+    sessionId: string;
+    /** session 层生命周期（★ 与有无 task 无关） */
+    lifecycle?: WecomSessionLifecycle;
+    /** 会话标题（描述 / agent 名）；缺省用 sessionId 截断 */
+    title?: string;
+    /** 所属 agent（subagentType） */
+    agentType?: string;
+    /** 开始时间（ISO） */
+    startedAt?: string;
+    /** 已运行时长（人类可读） */
+    elapsedText?: string;
+    /**
+     * ★ 该 session 内创建的 task（可选增强）。
+     * 有 → 卡上多一行任务信息；无 → 只显示 session 活性。
+     */
+    task?: {
+        id: number;
+        title?: string;
+        status?: string;
+        progress?: number;
+    };
+    /** 活性快照。undefined = 不渲染；null = 暂无数据 */
+    activity?: WecomActivityLike | null;
+    activityNow?: number;
+    /** 执行动态（会话级里程碑） */
+    milestones?: WecomMilestoneLite[];
+}): WecomButtonInteractionCard;
+/**
+ * 构造 aibot_send_msg 直发 template_card 帧。
+ *
+ * @param input.chatType "single"（chat_type=1，chatid=userid）|
+ *                      "group"（chat_type=2，chatid=群 chatid）
+ */
+export declare function buildWecomSendCardFrame(input: {
+    chatId: string;
+    chatType: "single" | "group";
+    card: WecomTextNoticeCard | WecomButtonInteractionCard;
+    /** 显式 req_id（缺省自动生成 aibot_send_msg_ 前缀） */
+    reqId?: string;
+}): {
+    cmd: string;
+    headers: {
+        req_id: string;
+    };
+    body: Record<string, unknown>;
+};
+/**
+ * 构造 aibot_respond_update_msg 更新帧（按钮点击后 5 秒窗口内）。
+ *
+ * ★ 协议硬约束：
+ * - req_id 必须**原样透传** template_card_event 回调帧的 req_id
+ * - template_card.task_id 必须与回调收到的 task_id 一致
+ *   （回调的 task_id 是发卡时的全量 id，不是 roy-task-<n> 前缀）
+ *
+ * @param input.taskId 回调解析出的**原始** task_id（原样回填）
+ */
+export declare function buildWecomCardUpdateFrame(input: {
+    reqId: string;
+    /** 回调带回的原始 task_id（原样回填，不做转换） */
+    taskId: string;
+    statusLabel: string;
+    note?: string;
+    /** 更新后的按钮列表（如把「标记完成」换成「已确认」） */
+    buttonOverrides?: WecomCardButton[];
+    /**
+     * ★ Task #5203 时间线详情：操作记录（milestones + processSteps）
+     * 渲染成 quote_area 引用文本（每行一条，最新在上）。
+     */
+    timeline?: WecomMilestoneLite[];
+    /**
+     * ★ Task #5273：任务标题（可选）。
+     *
+     * 用户反馈更新卡缺任务号/标题 → main_title 从
+     * `📋 ${statusLabel}` 升级为
+     * `📋 Task #<n> · <title> · ${statusLabel}`（缺省字段自动省略，
+     * 向后兼容旧调用方）。
+     */
+    taskTitle?: string;
+    /** ★ Task #5273：roy 任务号（可选，与 taskTitle 配对渲染） */
+    taskNumber?: number;
+    /**
+     * ★ Task #5360：sub-session 活性（用户点「刷新活性」时传入）。
+     *
+     * - `undefined` → 不渲染活性（普通 view / mark_done，行为与改造前一致）
+     * - `null`      → 渲染「暂无数据」（用户点过了，必须有反馈）
+     * - 快照        → 渲染信号灯 + 消息数 + 最近消息
+     */
+    activity?: WecomActivityLike | null;
+    /** ★ Task #5360：活性时间基准（注入便于测试；缺省 Date.now()） */
+    activityNow?: number;
+    /** ★ Task #5360：任务是否终态（决定报「已结束」而非「疑似停滞」） */
+    activityTerminal?: boolean;
+}): {
+    cmd: string;
+    headers: {
+        req_id: string;
+    };
+    body: Record<string, unknown>;
+};
+/**
+ * ★ Task #5364（用户 2026-11-12 08:34 拍板 B）——
+ * 构造 **session 卡的更新帧**（`aibot_respond_update_msg`）。
+ *
+ * ## 为什么需要它（B 方案的落点）
+ *
+ * 企微协议：`aibot_respond_update_msg` 只能在 `template_card_event` 回调的
+ * 5 秒窗口内、用回调带回的 `req_id` 发。生命周期事件没有 req_id ⇒ **无法主动
+ * patch**。所以「一张卡承载整个生命周期」只能靠**用户点按钮把窗口打开**。
+ *
+ * ⇒ 这张帧必须在**一次渲染里装齐全部信息**（这是用户唯一能看到的最新快照）：
+ *
+ * | 信息 | 来源 | 为什么不能省 |
+ * |------|------|--------------|
+ * | 生命周期状态 | store.lifecycle | 用户要知道「跑完了没 / 是超时还是失败」 |
+ * | 会话详情（id/agent/已运行） | store + startedAt | 首次发卡时的信息，刷新不能擦掉 |
+ * | 任务增强（Task #id/title/status） | store.associatedTaskId → task | 有 task 时后端不再发 task 卡，信息必须在这 |
+ * | 操作记录（milestones 时间线） | store.milestones | 「这一路发生了什么」 |
+ * | 活性（消息数 + 最近 msg） | 实时 probe | 判断 LLM 有没有真在推进 |
+ *
+ * ## 与 `buildWecomSessionCard`（首发帧）的关系
+ *
+ * 同一套排版口径（生命周期文案表 / 行裁剪 / `formatActivityQuote`），
+ * 但它是**整卡替换**（update 帧的 schema 要求），所以这里重新组装一份，
+ * 而不是复用首发卡的返回值 —— 首发卡是 `aibot_send_msg` 的 body 形状。
+ *
+ * @param input.reqId 回调带回的 req_id（**必须**，缺失直接抛）
+ * @param input.cardTaskId 回调带回的原始 `template_card.task_id`（原样回填）
+ */
+export declare function buildWecomSessionUpdateFrame(input: {
+    reqId: string;
+    /** 回调带回的原始 task_id（协议要求原样回填） */
+    cardTaskId: string;
+    sessionId: string;
+    lifecycle: WecomSessionUpdateLifecycle;
+    /** 会话标题（缺省用 sessionId 截断） */
+    title?: string;
+    agentType?: string;
+    /** 开始时间（ISO）；用于算「已运行」 */
+    startedAt?: string;
+    /** 已运行时长（优先用调用方算好的；缺省由 startedAt + now 推导） */
+    elapsedText?: string;
+    /** 关联 roy 任务（可选增强） */
+    task?: {
+        id: number;
+        title?: string;
+        status?: string;
+        progress?: number;
+    };
+    /** 累积操作记录（最新在后；渲染时反转成最新在顶部） */
+    milestones?: WecomMilestoneLite[];
+    /**
+     * ★ Task #5419：该 session 已关联的**飞书群** chatId。
+     *
+     * 有 ⇒ horizontal 加一行「飞书群」（applink 跳转），
+     * 建群后按钮翻面语义由 handler 控制（幂等命中不重复建）。
+     */
+    perTaskChatId?: string;
+    /** ★ CV 5419 MAJOR-3：建群失败提示（渲染进 sub_title） */
+    errorHint?: string;
+    /** 活性快照。undefined = 不渲染；null = 暂无数据（用户点了必须有反馈） */
+    activity?: WecomActivityLike | null;
+    /** 时间基准（注入便于测试） */
+    now?: number;
+}): {
+    cmd: string;
+    headers: {
+        req_id: string;
+    };
+    body: Record<string, unknown>;
+};