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

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

@@ -55,6 +55,8 @@
  * await notifier.finishTask({ messageId, status: "completed" });
  * ```
  */
+import { type LarkSessionCardStore } from "./lark-card-state-store";
+import { type ActivityMessage, type ToolCallView, type SubSessionActivity } from "./sub-session-activity";
 /**
  * 卡片状态。
  *
@@ -79,7 +81,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;
 /** 里程碑（关键节点）：时间 + 标题 + 描述 */
@@ -151,6 +160,13 @@ export interface ProcessStep {
 export interface TaskMeta {
     /** 任务 ID（#4223） */
     id?: number | string;
+    /**
+     * ★ 澄清 22:37：该任务所属的 sub-session（卡片**真正**的主键）。
+     *
+     * task 卡渲染时把它放进「刷新活性」按钮 value —— 因为刷新永远读 session
+     * store。缺省时该按钮退化为 task 兜底路径（见 handler 注释）。
+     */
+    sessionId?: string;
     /** 任务标题 */
     title?: string;
     /** 任务描述 */
@@ -236,6 +252,14 @@ export interface FinishTaskOptions {
     /** 终态补充说明（会作为最后一条里程碑 append） */
     finalStep?: string;
     progress?: number;
+    /**
+     * ★ Task #5384（CV R2 MINOR-5）：本次新增的过程步骤。
+     *
+     * 与 {@link UpdateTaskOptions.processSteps} 同义 —— 终态/暂停路径同样要能
+     * 携带过程信息，否则「收尾前那几步」在 session 卡上会整段丢失
+     * （task 卡路径原本也没有，但 session 卡有「执行动态」，不该丢）。
+     */
+    processSteps?: ProcessStep[];
     /**
      * 收尾里程碑的自定义标题（Task #4536 / xval round2 NIT 3）
      *
@@ -262,7 +286,22 @@ export interface StartTaskResult {
 export interface LarkCardPatchNotifierOptions {
     /** 启动时是否 pin（默认 true） */
     pinOnStart?: boolean;
-    /** 结束时是否 unpin（默认 true） */
+    /**
+     * ★ CV R3 M3：**session 卡持久层**（默认取进程单例）。
+     *
+     * 为什么不复用 task 卡持久层：`lark_card.task_id INTEGER PRIMARY KEY` 装不下
+     * `session_xxx`。没有这张表时，「重启 + 无 task」的 session 会**又发一张卡**
+     * （reviewer M3，属实）。
+     *
+     * 传 `null` 可显式关闭持久化（单测用，避免污染真实库）。
+     */
+    sessionCardStore?: LarkSessionCardStore | null;
+    /**
+     * 结束时是否 unpin（Task #5164 需求 2a：**默认 false**）
+     *
+     * 任务完成/暂停时不再自动取消置顶 —— pin 去留由用户手动决定。
+     * 需要旧行为（自动 unpin）的调用方显式传 true。
+     */
     unpinOnFinish?: boolean;
 }
 export interface CardPayload {
@@ -559,6 +598,147 @@ export declare function buildTaskCard(opts: {
      * running/stopped 折叠）。
      */
     expandTimeline?: boolean;
+    /**
+     * ★ Task #5360：sub-session 活性快照（用户点「🔄 刷新活性」后才有）
+     *
+     * ## 为什么是 `undefined` / `null` 三态
+     *
+     * - `undefined` —— 调用方**没查过**活性（首次发卡 / 普通 patch）：
+     *   整个活性面板**不渲染**，卡片与改造前逐字节一致（零回归风险）。
+     * - 非 undefined（含 `null`）—— 调用方**查过了**：
+     *   渲染 `⚡ 子会话活性` 面板；`null` 表示"查了但没数据"，渲染「暂无数据」。
+     *
+     * 这样区分很重要：用户点刷新后如果什么都没有，"面板消失"会让人以为
+     * 按钮没生效；"面板在但写暂无数据"才是诚实的反馈。
+     */
+    activity?: SubSessionActivity | null;
+    /** ★ Task #5360：活性面板的时间基准（注入便于测试；缺省 `Date.now()`） */
+    activityNow?: number;
+    /** ★ Task #5360：任务是否已终态（决定活性档位报「已结束」而非「疑似停滞」） */
+    activityTerminal?: boolean;
+}): CardPayload;
+/**
+ * ★ Task #5360（补充需求 22:31）—— 构造**无 task**（session-only）的卡片。
+ *
+ * ## 用户需求
+ *
+ * > 「有 sub-session 但无 task —— 也要能刷新看 subsession 情况」
+ *
+ * ## 与 `buildTaskCard` 的关系：**并列而非复用**
+ *
+ * 为什么不给 `buildTaskCard` 加一堆 `if (无 task)` 分支：
+ * - task 卡有「建群/解散群」「任务详情（ID/目标/父任务/优先级）」「进度 %」
+ *   —— 这些对 session 全都无意义，硬塞会渲染出一堆 `undefined` 占位
+ * - 反过来 session 需要的「会话详情（sessionId / 所属 agent / 起止）」
+ *   task 卡没有
+ *
+ * 所以是**两张卡**，但**共用**同一套零件：
+ * `buildCollapsiblePanel` / `appendHr` / `formatActivityLines` /
+ * `sanitizeInlineText` / `truncateHeadTitle`
+ * —— 活性判定与文案口径因此与 task 卡**逐字一致**（不会出现同一个
+ * session 在两张卡里颜色不同）。
+ *
+ * ## 按钮：刷新活性**始终有**；建群/解散群**仅在有 task 时**渲染
+ *
+ * - 刷新活性：session 主键，任何 session 卡都有（这是本次改造的核心）
+ * - 建群/解散群：绑定在 task 上，无 task 时 `value.taskId` 无从填充 ——
+ *   渲染一个点不动的按钮比不渲染更糟，所以有 task 才出。
+ */
+/** session 卡累计状态（notifier 内部 + patch 复用） */
+export interface SessionCardState {
+    title?: string;
+    statusPhrase?: string;
+    agentType?: string;
+    startedAt?: string;
+    elapsedText?: string;
+    milestones: Milestone[];
+    updateCount: number;
+    lifecycle?: "running" | "completed" | "timeout" | "failed" | "stopped";
+    profile?: string;
+    sessionId?: string;
+    /** ★ CV R5：上次的活性快照（patch 未传时沿用，避免擦掉消息数/最近消息） */
+    activity?: SubSessionActivity | null;
+    /** ★ Task #5420：上次的最近消息列表（patch 未传时沿用，避免擦面板） */
+    recentMessages?: ActivityMessage[] | ToolCallView[];
+    /**
+     * ★ Task #5364 返工（BLOCKER-5）：该 session 内创建的 roy 任务（**可选增强**）。
+     *
+     * 用户 08:13 定稿第 2 点：「若该会话有任务相关信息 → 把原任务卡的信息渲染在
+     * 这张子会话卡上（**合并**，不是并列）」。
+     *
+     * 上一版只把它当「刷新时的临时入参」传，首卡（startSessionCard）不传 ⇒
+     * 生产上 task 卡链路照旧独立发一张，两张并列 —— 直接违背定稿。
+     *
+     * 现在纳入 state：里程碑式的 task 更新（进度/状态/操作记录）在 patch 时
+     * **沿用上一次已知的 task 快照**，不会因为二次事件没带 task 就消失。
+     */
+    task?: NonNullable<Parameters<typeof buildSessionCard>[0]["task"]>;
+    /** task 专属群 chatId（有群时渲染「进入专属群」/「解散该群」） */
+    perTaskChatId?: string;
+    perTaskChatName?: string;
+}
+export declare function buildSessionCard(opts: {
+    /** sub-session id（卡片主键） */
+    sessionId: string;
+    /** 会话标题（自定义 agent 名 / 任务描述）；缺省显示 sessionId 截断 */
+    title?: string;
+    /** 状态短语（已运行 / 已结束 …）；缺省按 lifecycle 推导 */
+    statusPhrase?: string;
+    /**
+     * ★ 澄清（22:37）：session 层的**生命周期**。
+     *
+     * 与 task 无关 —— 没建 task 的 sub-session 一样会 完成/超时/被停。
+     * 缺省 `running`。
+     */
+    lifecycle?: "running" | "completed" | "timeout" | "failed" | "stopped";
+    /** ★ 澄清（22:37）：task 专属群 chatId（有 task 且已建群时渲染「进入群」） */
+    perTaskChatId?: string;
+    /**
+     * ★ 澄清（22:37）：该 session 内创建的 roy 任务（**可选增强**）。
+     *
+     * 有 → 卡片多一块「📋 任务信息」面板（taskId / title / 状态 / 进度 /
+     * 操作记录），**原有 task 信息一个不少**；
+     * 无 → 只显示 session 活性，卡片身份不变。
+     */
+    task?: {
+        id: number;
+        title?: string;
+        status?: string;
+        progress?: number;
+        currentStatus?: string;
+        /** 操作记录（里程碑形态，渲染成时间线） */
+        milestones?: Milestone[];
+        /** ★ CV MAJOR-5：其余元信息（用户要求「一个不少」） */
+        priority?: string;
+        parentTaskId?: number;
+        goals?: string;
+        createdAt?: string;
+        updatedAt?: string;
+    };
+    /** 所属 agent（subagentType），可选 */
+    agentType?: string;
+    /** 开始时间（ISO） */
+    startedAt?: string;
+    /** 已运行时长（人类可读，如 "12m"）—— 由调用方算好，避免本模块读时钟 */
+    elapsedText?: string;
+    /** 最近的活动里程碑（session 没有 task 时间线，用事件级的短列表） */
+    milestones?: Milestone[];
+    /** ★ 活性快照（与 task 卡同源渲染）。undefined = 不渲染；null = 暂无数据 */
+    activity?: SubSessionActivity | null;
+    /**
+     * ★ Task #5420：最近消息列表（「💬 会话查看」面板）。
+     *
+     * ⚠️ 返工（2026-11-13 08:21）：面板改为展示**最近 5 条工具调用**
+     * （工具名 + reason）。字段名保留 recentMessages（存量状态兼容，
+     * state 沿用逻辑不动），但装配点现在装的是 ToolCallView[]。
+     *
+     * undefined = 不渲染面板（首卡零噪音）；
+     * [] = 查了确实没有 → 面板显示「暂无工具调用」（诚实）。
+     */
+    recentMessages?: ActivityMessage[] | import("./sub-session-activity").ToolCallView[];
+    activityNow?: number;
+    /** 更新计数（spinner 轮换 + "第 N 次更新"） */
+    updateCount?: number;
 }): CardPayload;
 /**
  * 生成"打开飞书群"的 app link（Task #4230 follow-up 修复）
@@ -661,6 +841,19 @@ export declare class LarkCardPatchNotifier {
      * unpin 基础设施，只是渲染的卡片与自持的时间线不同。
      */
     private readonly workflowStates;
+    /**
+     * ★ 补充需求（22:31）：**session 卡**的累计状态（key = messageId）。
+     *
+     * 与 `states`（task 卡）分开存：
+     * - task 卡状态里的 `meta` 是 `TaskMeta`（含 goals/priority/progress）
+     * - session 卡只有 `sessionId` + 少量展示字段
+     * 混在一个 Map 里会让 `buildCardWithActivity` 取到 session 状态并当成
+     * task meta 渲染（输出一堆 undefined 占位）。分开最省心。
+     */
+    private readonly sessionStates;
+    /**  CV R4：session 卡状态别名（渲染 + patch 都需要） */
+    /** ★ CV R3 M3：session 卡持久层（`null` = 显式关闭） */
+    private readonly sessionStore?;
     constructor(options?: LarkCardPatchNotifierOptions);
     /** 取（或创建）某 messageId 的 mutex —— 不同卡片互不阻塞 */
     private mutexFor;
@@ -787,6 +980,283 @@ export declare class LarkCardPatchNotifier {
     updateMetaAndBuildCard(messageId: string, meta: TaskMeta, opts?: {
         clearPerTaskChat?: boolean;
     }): CardPayload | undefined;
+    /**
+     * ★ Task #5360 — 用活性快照重建卡片（用户点「🔄 刷新活性」时调用）。
+     *
+     * ## 为什么需要这个专门方法（不复用 `updateMetaAndBuildCard`）
+     *
+     * `updateMetaAndBuildCard` 是给"群建/解散"用的：它只改 meta 再 rebuild。
+     * 刷新活性要的是**同一张卡的累计状态 + 一份新活性快照**，且**绝不能**
+     * 走 `updateTask`（那会 patch + updateCount+1，用户点 5 次刷新 = 时间线
+     * 少 5 次"更新"预算，还把 spinner 转乱）。
+     *
+     * ## 返回 undefined 的语义
+     *
+     * notifier 没有该 messageId 的状态（进程重启后还没 hydrate）→ undefined。
+     * 调用方（action handler）据此 fallback 重建卡片 —— 与
+     * `buildCardAfterGroupChange` 完全同一套降级语义。
+     */
+    buildCardWithActivity(messageId: string, activity: SubSessionActivity | null, opts?: {
+        terminal?: boolean;
+        now?: number;
+    }): CardPayload | undefined;
+    /**
+     * ★ CV R4 BLOCKER：**给已存在的 session 卡发 patch**（生命周期推进时用）。
+     *
+     * ## 为什么必须有它（用户需求没被真正满足）
+     *
+     * 「超时、完成等生命周期事件也体现在卡片上」—— 但 `startSessionCard`
+     * 每次都是 `messages-send` = **发一条新消息**。若每个生命周期都 start：
+     * - 一个 session 会产出「启动卡 + 完成卡」**两张**（用户看到重复卡）
+     * - 每张都被 pin ⇒ 置顶堆积
+     * - 「一张卡承载整个生命周期」这个语义根本没实现
+     *
+     * 正确做法：`running` 发首卡，后续生命周期 **patch 同一张**。
+     *
+     * ## 返回值语义
+     *
+     * `false` = 本 notifier 没有该 session 的卡记录（重启未 hydrate / 从没发过）
+     * ⇒ 调用方据此走 `startSessionCard` 发首卡。
+     */
+    updateSessionCard(opts: {
+        sessionId: string;
+        chatId?: string;
+        profile?: string;
+        lifecycle: "running" | "completed" | "timeout" | "failed" | "stopped";
+        /** 追加的里程碑（如「子会话完成」） */
+        milestones?: Milestone[];
+        activity?: SubSessionActivity | null;
+        /** ★ Task #5364 返工：该 session 内的任务信息（渲染进**同一张** session 卡） */
+        task?: Parameters<typeof buildSessionCard>[0]["task"];
+        perTaskChatId?: string;
+        perTaskChatName?: string;
+    }): Promise<boolean>;
+    /** sessionId → messageId 映射（用于「patch 同一张卡」查找） */
+    private readonly sessionCardIds;
+    /**
+     * ★ Task #5364 返工：taskId → sessionId 反向索引。
+     *
+     * 用途（两处，都是「手里只有 taskId」的场景）：
+     * 1. `LarkCliTaskNotifyHook` 收到 task 事件时要知道该 patch **哪张 session 卡**
+     *    （一张卡的语义要求 task 更新写进 session 卡，而不是另发 task 卡）
+     * 2. 旧 task 卡的「🔄 刷新活性」按钮 value 只有 taskId
+     *    （`resolveSessionIdByTask` 端口的同步兜底）
+     *
+     * ⚠️ 内存索引（进程内）。进程重启后由 hook 层从 lark_card 表 hydrate 补齐。
+     */
+    private readonly taskToSessionId;
+    /** 按 sessionId 找这张卡的状态（找不到 → undefined） */
+    private findSessionCardBySessionId;
+    /** 这个 messageId 是否属于一张 **session 卡**（★ Task #5384 守卫入口）。 */
+    isSessionCardMessage(messageId: string): boolean;
+    /**
+     * ★ Task #5384：把 **task 侧的更新**应用进 session 卡，返回可 patch 的卡片。
+     *
+     * 语义（保证「信息一个不少」且「卡身份不变」）：
+     * - 卡身份：`buildSessionCard` 渲染 ⇒ header 恒为「📊 子会话实时更新（…）」，
+     *   「🔄 刷新活性」按钮与「🆔 会话 ID」面板恒在。
+     * - 信息不丢：本次里程碑并进执行动态；task 的 meta/status/progress
+     *   合并进「📋 任务信息」面板（carry-forward，未传则沿用上一次）。
+     * - 过程步骤（task 侧的 processSteps）没有独立面板，转成里程碑形态并入，
+     *   宁可换一种展示也不能丢（用户看的是「发生了什么」）。
+     */
+    private applyTaskEventToSessionCard;
+    /**
+     * ★ Task #5364 返工：登记 `taskId → sessionId` 映射（生产装配 / 持久层恢复用）。
+     *
+     * 为什么暴露成公开方法：hook 层的事件上下文里可能只有 taskId（`task:after.*`
+     * 的 payload 不带 sub-session），而卡片更新必须落到 session 卡上。
+     */
+    bindTaskToSession(taskId: number, sessionId: string): void;
+    /**
+     * ★ Task #5364 返工（BLOCKER-4 重启分支）：**认领**一张已存在的 session 卡。
+     *
+     * ## 为什么必须有
+     *
+     * `sessionCardIds` / `sessionStates` 是内存字段。进程重启后它们都是空的，
+     * 此时若只靠 `getSessionCardMessageId()` 判断「有没有卡」，答案恒为"没有"
+     * ⇒ `upsertSessionCard` 会走 `startSessionCard` 再发一张。
+     * 于是**每次重启都会给同一个 session 多一张卡**（用户「一个 session 只有一张卡」
+     * 的硬要求被静默破坏）。
+     *
+     * 本方法让调用方（hook 的 `restoreCardState`）用持久层里的权威 messageId
+     * 把内存索引补回来 —— 之后的所有 patch 都会命中同一张卡。
+     */
+    adoptSessionCard(sessionId: string, messageId: string, state?: Partial<SessionCardState>): void;
+    /** ★ CV R3 M3：把 session 卡写进持久层（失败只 warn，不阻断发卡） */
+    private persistSessionCardRecord;
+    /**
+     * ★ CV R3 M3：从持久层**回灌**全部已知 session 卡（启动时调用）。
+     *
+     * 语义：把 `lark_session_card` 里的 `sessionId → messageId` 灌回内存索引，
+     * 让重启后的第一次 `upsertSessionCard` 走 **patch** 而不是 `startSessionCard`。
+     *
+     * @returns 回灌的条数（诊断用）
+     */
+    restoreSessionCardsFromStore(): number;
+    applySessionGroupChange(messageId: string, opts: {
+        sessionId: string;
+        /** 新群 chatId；缺省/空 ⇒ 视为「解散」，清掉卡上的群与链接 */
+        perTaskChatId?: string;
+        perTaskChatName?: string;
+    }): CardPayload | undefined;
+    /** ★ Task #5364 返工：按 taskId 反查 sessionId（没有 → undefined，**不猜**）。 */
+    getSessionIdByTask(taskId: number): string | undefined;
+    /** ★ Task #5364 返工：按 sessionId 查已发的卡 messageId（诊断 / 幂等断言用）。 */
+    getSessionCardMessageId(sessionId: string): string | undefined;
+    /** ★ Task #5364 返工：该 session 卡当前的累计状态（**生产形状测试**断言用）。 */
+    getSessionCardState(sessionId: string): SessionCardState | undefined;
+    /**
+     * ★ Task #5417：把原 session 的进展**双写**到关联群 session 的卡上。
+     *
+     * ## 设计（方案 A，用户定稿）
+     *
+     * 新群有自己的卡（session_id = 群 session id = chatId）。
+     * 原 session 的进展事件 patch 原卡后，调用方用本方法把同一条
+     * 进展同步到新群卡 —— 新群卡的 state **独立累积**（不是复制原卡），
+     * 符合 #5364 单卡规格（每 session 每 chat 一张）。
+     *
+     * ## 语义
+     *
+     * - `findGroupSession` 未注入 / 反查不到群 / 群 session 就是原 session
+     *   ⇒ no-op（返回 false，不报错）
+     * - 新群还没有卡 ⇒ `upsertSessionCard` 会为群 session 发首卡
+     *   （best-effort；发送失败向上抛，调用方 warn）
+     * - 已有卡 ⇒ patch 同一张（不重发）
+     *
+     * @param originSessionId 原 session id
+     * @param opts 与 upsertSessionCard 同形的增量（lifecycle/milestones/…）
+     * @param findGroupSession 反查端口（SessionComponent.findGroupChatForSession）
+     */
+    syncGroupCardFromOrigin(originSessionId: string, opts: {
+        lifecycle?: "running" | "completed" | "timeout" | "failed" | "stopped";
+        milestones?: Array<{
+            title: string;
+            timestamp: string;
+            description?: string;
+        }>;
+        title?: string;
+    }, findGroupSession?: (sid: string) => Promise<{
+        chatId: string;
+        aliasSessionId?: string;
+    } | undefined>): Promise<boolean>;
+    /**
+     * ★ CV R4：按 sessionId **复用或新建** session 卡（生命周期推进的正确入口）。
+     *
+     * - 已有卡 → patch（一张卡承载整个生命周期）
+     * - 没有卡 → start（首卡 + pin）
+     *
+     * 这才是「生命周期事件体现在卡片上」的正确实现；调用方不该自己判断。
+     */
+    upsertSessionCard(opts: {
+        chatId: string;
+        profile?: string;
+        sessionId: string;
+        title?: string;
+        statusPhrase?: string;
+        agentType?: string;
+        startedAt?: string;
+        elapsedText?: string;
+        milestones?: Milestone[];
+        lifecycle: "running" | "completed" | "timeout" | "failed" | "stopped";
+        activity?: SubSessionActivity | null;
+        /** ★ Task #5364 返工（BLOCKER-5）：session 内的任务信息（合并渲染） */
+        task?: Parameters<typeof buildSessionCard>[0]["task"];
+        perTaskChatId?: string;
+        perTaskChatName?: string;
+    }): Promise<{
+        messageId: string;
+        created: boolean;
+    }>;
+    /**
+     * ★ Task #5364 返工：per-session 的 upsert 串行化锁（见 upsertSessionCard 注释）。
+     *
+     * key = sessionId；只保护「读有没有卡 → 决定 start/update」这一段，
+     * 不保护 patch 本身（那个有 `mutexFor(messageId)` 自己的锁）。
+     */
+    private readonly sessionUpsertMutexes;
+    /**
+     * ★ CV R3 BLOCKER-2：**首次发 session 卡**（无 task 的 sub-session 也要有卡）。
+     *
+     * 与 `startTask` 并列：同一个 notifier、同一套 send/pin 基础设施，
+     * 只是渲染 `buildSessionCard` 且状态存进 `sessionStates`。
+     *
+     * 发完把 messageId 记进 `sessionStates`，之后 `buildSessionCardWithActivity`
+     * 才能 patch 同一张卡（而不是每次刷新都 fallback 重建）。
+     */
+    startSessionCard(opts: {
+        chatId: string;
+        profile?: string;
+        sessionId: string;
+        title?: string;
+        statusPhrase?: string;
+        agentType?: string;
+        startedAt?: string;
+        elapsedText?: string;
+        milestones?: Milestone[];
+        lifecycle?: "running" | "completed" | "timeout" | "failed" | "stopped";
+        /** ★ CV R5：首卡也记下活性（后续 patch 未传时可沿用） */
+        activity?: SubSessionActivity | null;
+        /**
+         * ★ Task #5364 返工（BLOCKER-5）：首卡就带上 task 区块。
+         *
+         * 上一版首卡不传 task ⇒ task 卡链路独立再发一张 ⇒ 两张并列。
+         * 用户 08:13 定稿：**一张 session 卡**，task 信息是卡上的区块。
+         */
+        task?: Parameters<typeof buildSessionCard>[0]["task"];
+        perTaskChatId?: string;
+        perTaskChatName?: string;
+    }): Promise<StartTaskResult>;
+    /**
+     * ★ 补充需求（22:31）—— session-only 卡片按 messageId 重建（带活性）。
+     *
+     * 与 `buildCardWithActivity` 的区别：那个按 messageId 取 **task** 卡的
+     * 累计状态；session 卡的状态另存一份（`sessionStates`），互不干扰。
+     *
+     * 返回 `undefined` = 本 notifier 没有这张 session 卡的状态（重启未 hydrate）
+     * ⇒ 调用方 fallback 重建。session 卡没有 task 的 title/status 可丢，
+     * 所以重建损失最小。
+     */
+    buildSessionCardWithActivity(messageId: string, sessionId: string, activity: SubSessionActivity | null, opts?: {
+        now?: number;
+        /** ★ 澄清 22:37：session 层生命周期（完成/超时/停止） */
+        lifecycle?: "running" | "completed" | "timeout" | "failed" | "stopped";
+        /** ★ 澄清 22:37：关联 task 的增强信息（有则渲染任务面板） */
+        task?: Parameters<typeof buildSessionCard>[0]["task"];
+        /**
+         * ★ Task #5420：最近消息列表（「💬 会话查看」面板）。
+         * undefined = 本次没查（沿用 state 里的上次值，与 activity 同语义）。
+         */
+        recentMessages?: ActivityMessage[] | ToolCallView[];
+    }): CardPayload | undefined;
+    /**
+     * ★ 补充需求（22:31）—— 记录 session 卡的累计状态（供 refresh 重建）。
+     *
+     * 只存渲染必需的最小字段，不存活性快照本身（活性每次刷新都要重读，
+     * 缓存它会显示过期数据 —— 那正是用户点刷新要避免的）。
+     */
+    rememberSessionCard(messageId: string, state: {
+        title?: string;
+        statusPhrase?: string;
+        agentType?: string;
+        startedAt?: string;
+        elapsedText?: string;
+        milestones?: Milestone[];
+        updateCount?: number;
+        /** ★ 澄清 22:37：session 层生命周期 */
+        lifecycle?: "running" | "completed" | "timeout" | "failed" | "stopped";
+        /** ★ CV R4：patch 时要用 profile（多 appId）与 sessionId（反查） */
+        profile?: string;
+        sessionId?: string;
+        /** ★ CV R5：上次的活性快照 */
+        activity?: SubSessionActivity | null;
+        /** ★ Task #5420：上次的最近消息列表 */
+        recentMessages?: ActivityMessage[] | ToolCallView[];
+        /** ★ Task #5364 返工：任务区块 + 专属群（合并渲染） */
+        task?: NonNullable<Parameters<typeof buildSessionCard>[0]["task"]>;
+        perTaskChatId?: string;
+        perTaskChatName?: string;
+    }): void;
     /**
      * ★ Task #5020 —— 已经走到**真终态**的卡片（review round-4 MAJOR）。
      *
@@ -805,6 +1275,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 卡片数（测试/自检用） */
@@ -893,3 +1390,46 @@ export declare class LarkCardPatchNotifier {
      */
     private extractMessageId;
 }
+/**
+ * ## 为什么必须有这个单例（真机事故复盘）
+ *
+ * `sessionCardIds` / `sessionStates` / `states` 都是 **notifier 实例字段**。
+ * 只要「发首卡」和「后续 patch」不是同一个实例，就必然发生：
+ *
+ * ```
+ * 事件 1（running）  → 实例 A：没有该 session 的卡 → startSessionCard 发**新卡**
+ * 事件 2（completed）→ 实例 B：还是没有        → 又发**新卡**
+ * ```
+ *
+ * 真机取证（2026-11-12 gonglin 群，单 session）：0813 定稿「一个 session 只有
+ * 一张卡」，实测发出 **3 张**（2 张 session 卡 + 1 张 task 卡）。
+ *
+ * 根因是上一版靠 `env.getPluginInstance()/env._pluginInstances` 去「借」插件的
+ * notifier —— 但生产 `Environment` **根本没有这两个属性**（全仓 grep 只有那
+ * 一处引用、从无注入方）⇒ 每次调用都落 `?? new LarkCardPatchNotifier()`。
+ *
+ * ## 语义
+ *
+ * - **进程内唯一**：`LarkCliTaskNotifyHook` 默认构造、卡片 action handler、
+ *   事件线程的 `sessionCardSender` 全部走这里取同一个实例
+ * - 单测要隔离：显式传 `cardNotifier` 构造参数（既有 55 条测试都这么做），
+ *   或者调用 {@link __resetSharedLarkCardNotifierForTest}
+ */
+/**
+ * ★ Task #5364 返工：session 卡上「任务信息」区块的渲染载荷类型。
+ *
+ * 显式导出，避免调用方写 `Parameters<typeof buildSessionCard>[0]["task"]`
+ * 这种又长又容易写错的类型（也确实被写错过一次：内联 import(...) 语法非法）。
+ */
+export type SessionCardTaskPayload = NonNullable<Parameters<typeof buildSessionCard>[0]["task"]>;
+/**
+ * 取进程级共享 notifier（首次调用时创建）。
+ *
+ * ⚠️ 只在**生产装配**里用。任何需要独立状态的场景（单测 / 多租户）都要
+ * 显式 `new LarkCardPatchNotifier()` 并注入。
+ */
+export declare function getSharedLarkCardNotifier(): LarkCardPatchNotifier;
+/** 测试钩子：丢弃单例（避免用例间状态串味）。 */
+export declare function __resetSharedLarkCardNotifierForTest(): void;
+/** 诊断：当前是否已有单例（不创建）。 */
+export declare function hasSharedLarkCardNotifier(): boolean;

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

@@ -2,13 +2,17 @@ import {
   DEFAULT_APP_LINK_BASE,
   HEAD_TITLE_MAX_WIDTH,
   LarkCardPatchNotifier,
+  __resetSharedLarkCardNotifierForTest,
   buildChatAppLink,
   buildCollapsiblePanel,
+  buildSessionCard,
   buildTaskCard,
   buildWorkflowCard,
   formatDateTimeForDisplay,
   formatDurationMs,
   formatTimestampForDisplay,
+  getSharedLarkCardNotifier,
+  hasSharedLarkCardNotifier,
   humanizeValue,
   isTerminalStatusForTimeline,
   isTerminalStatusForWorkflowTimeline,
@@ -22,8 +26,10 @@ import {
   resolveTaskTitleForDisplay,
   sanitizeInlineText,
   truncateHeadTitle
-} from "../../../shared/@ai-setting/roy-agent-core-w0qjeq2v.js";
-import"../../../shared/@ai-setting/roy-agent-core-qq96p0tj.js";
+} from "../../../shared/@ai-setting/roy-agent-core-shb1qsyg.js";
+import"../../../shared/@ai-setting/roy-agent-core-418zc9ha.js";
+import"../../../shared/@ai-setting/roy-agent-core-6k8mb7zx.js";
+import"../../../shared/@ai-setting/roy-agent-core-5s2t8z00.js";
 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";
@@ -41,13 +47,17 @@ export {
   isTerminalStatusForWorkflowTimeline,
   isTerminalStatusForTimeline,
   humanizeValue,
+  hasSharedLarkCardNotifier,
+  getSharedLarkCardNotifier,
   formatTimestampForDisplay,
   formatDurationMs,
   formatDateTimeForDisplay,
   buildWorkflowCard,
   buildTaskCard,
+  buildSessionCard,
   buildCollapsiblePanel,
   buildChatAppLink,
+  __resetSharedLarkCardNotifierForTest,
   LarkCardPatchNotifier,
   HEAD_TITLE_MAX_WIDTH,
   DEFAULT_APP_LINK_BASE