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

package/dist/env/task/plugins/lark-card-state-store.d.ts

@@ -67,6 +67,14 @@ export interface LarkCardState {
     updatedAt: number;
     /** 终结时间（ms epoch）；仅 status=closed 有值 */
     closedAt?: number;
+    /**
+     * ★ Task #5364 返工：该任务卡片实际归属的 **sub-session id**。
+     *
+     * 用途：进程重启后，`task:after.update` 这类只带 taskId 的事件仍能知道
+     * 「该 patch 哪张 **session** 卡」（一个 session 一张卡的前提）。
+     * 缺省（旧行 / 非 session 卡）⇒ 走传统 task 卡路径。
+     */
+    sessionId?: string;
     /**
      * 卡片自持的累积内容（Task #4536 / xval MAJOR 3）
      *
@@ -135,3 +143,55 @@ export declare function getDefaultLarkCardDbPath(): string;
  *   持久化层故障让通知路径整体崩掉（诉求 C：健壮性）。
  */
 export declare function createLarkCardStateStore(dbPath?: string): LarkCardStateStore;
+/** 取进程级共享持久层（首次调用时创建）。 */
+export declare function getSharedLarkCardStateStore(): LarkCardStateStore;
+/** 测试钩子：丢弃单例（避免用例间串味 / 连到真实库）。 */
+export declare function __resetSharedLarkCardStateStoreForTest(): void;
+/**
+ * 为什么需要独立表（不能塞进 `lark_card`）
+ *
+ * `lark_card.task_id INTEGER PRIMARY KEY` 装不下 `session_xxx` 字符串；
+ * 而本轮的核心语义是「**一个 session 一张卡**」—— 无 task 的 session 也必须
+ * 能重启后找回自己的卡，否则每次都多发一张（用户硬要求被静默破坏）。
+ *
+ * 表：`lark_session_card`，主键 `session_id`。零迁移风险（新表 IF NOT EXISTS）。
+ */
+export interface LarkSessionCardRecord {
+    sessionId: string;
+    messageId: string;
+    chatId: string;
+    profile?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+/** session 卡持久化端口 */
+export interface LarkSessionCardStore {
+    upsert(rec: LarkSessionCardRecord): void;
+    get(sessionId: string): LarkSessionCardRecord | undefined;
+    list(): LarkSessionCardRecord[];
+    delete(sessionId: string): void;
+    close(): void;
+}
+/** 内存实现（测试 / SQLite 不可用时降级） */
+export declare class MemoryLarkSessionCardStore implements LarkSessionCardStore {
+    private readonly records;
+    upsert(rec: LarkSessionCardRecord): void;
+    get(sessionId: string): LarkSessionCardRecord | undefined;
+    list(): LarkSessionCardRecord[];
+    delete(sessionId: string): void;
+    close(): void;
+}
+/** SQLite 实现 */
+export declare class SqliteLarkSessionCardStore implements LarkSessionCardStore {
+    private readonly db;
+    constructor(dbPath: string);
+    upsert(rec: LarkSessionCardRecord): void;
+    get(sessionId: string): LarkSessionCardRecord | undefined;
+    list(): LarkSessionCardRecord[];
+    delete(sessionId: string): void;
+    close(): void;
+}
+/** 创建 session 卡持久层（与 task 卡同一套降级语义） */
+export declare function createLarkSessionCardStore(dbPath?: string): LarkSessionCardStore;
+export declare function getSharedLarkSessionCardStore(): LarkSessionCardStore;
+export declare function __resetSharedLarkSessionCardStoreForTest(): void;

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 / 排查用） */
@@ -401,6 +417,51 @@ export declare class LarkCliTaskNotifyHook implements Hook {
      * LarkCardPatchNotifier.renderContextAsLines 负责（卡片里绝不出现 JSON）。
      */
     private buildTaskMeta;
+    /**
+     * ★ Task #5364 返工：解析该 task 所属的 sub-session id。
+     *
+     * 顺序（都不猜）：
+     * 1. notifier 反向索引（本进程发过卡 / 事件里绑定过）
+     * 2. 持久层 `lark_card.session_id`（重启后仍有效）
+     * 3. EnvContext 的 replyChannel / envEvent（sub-agent 运行时带）
+     */
+    private resolveSessionIdForTask;
+    /**
+     * ★ Task #5364 返工（BLOCKER-5/6）：把 task 事件渲染进**已有的 session 卡**。
+     *
+     * ## 用户定稿（2026-11-12 08:13 / 08:15）
+     *
+     * - 「一个 session 只有一张卡」
+     * - 「有 task → task 信息渲染在这张 session 卡上」（合并，不是并列）
+     * - 飞书：**任务状态更新自动同步**（自动 patch 同一张卡）
+     *
+     * ## 实现
+     *
+     * 已有该 session 的卡 → `updateSessionCard`（patch 同一 messageId，带 task 区块）
+     * ；没有 → 返回 false，调用方退回落旧的 task 卡路径（首次由 session 生命周期
+     * 事件发卡；task 先到就先由这里发「session 卡 + task 区块」）。
+     */
+    private patchSessionCardForTask;
+    /**
+     * ★ Task #5417：群 session 反查端口（由 ES 装配点注入）。
+     * 未注入 ⇒ task 侧双写退化为 no-op（不影响原卡链路）。
+     */
+    syncGroupCardFromOriginFn?: (sid: string) => Promise<{
+        chatId: string;
+        aliasSessionId?: string;
+    } | undefined>;
+    /**
+     * ★ Task #5364 返工（BLOCKER-4 重启分支）：把「task 的卡 = 那张 session 卡」
+     * 写进持久层。
+     *
+     * 重启后 `restoreCardState` 读到 `{messageId: <session 卡>, sessionId}` ⇒
+     * `adoptSessionCard` 恢复内存索引 ⇒ 后续 patch 命中同一张卡（不再多发）。
+     */
+    private recordSessionCardForTask;
+    /** sub-agent 类型（有则显示「执行 Agent」行） */
+    private resolveAgentType;
+    /** TaskMeta → buildSessionCard 的 task 区块载荷 */
+    private buildSessionCardTask;
     /**
      * operation → 卡片时间线条目（里程碑 + 过程步骤 + 当前步骤）
      *

package/dist/env/task/plugins/sub-session-activity.d.ts

@@ -0,0 +1,415 @@
+/**
+ * @fileoverview Task #5360 — sub-session 活性（liveness）公共纯函数层
+ *
+ * ## 用户需求（2026-11-11 20:50）
+ *
+ * > 「卡片新增「刷新」按钮（类似企微卡片的刷新按钮）：按下后展示该任务对应
+ * >   subsession 的消息数 + 最近一条 msg（截断）—— 用来判断有无 LLM 推进」
+ *
+ * ## 为什么需要这一层
+ *
+ * 飞书卡片（`lark-card-action-handler`）和企微卡片（`wecom-card-action-handler`）
+ * 都要展示同一份活性数据。如果两边各写一份：
+ *
+ * - liveness 阈值（5min / 20min）会漂移 → 同一个任务在两个渠道显示不同颜色
+ * - 截断规则会漂移 → 一边切词一边不切
+ * - `taskId → subSessionId` 反查会漂移 → 一边查得到一边查不到
+ *
+ * 所以**判定逻辑全部纯函数**放这里，两侧只负责渲染（飞书 markdown / 企微 quote）。
+ *
+ * ## 数据从哪来（不新造轮子）
+ *
+ * `BackgroundTaskManager.getSubSessionActivity(bgProcessId)`（delegate-tool.ts:2406）
+ * 早就存在，此前只被 `query_background_process` 工具消费（Task #4720 Fix B）。
+ * 它内部读 `session.messageCount` / `session.updatedAt`，任何失败返回 undefined
+ * （不抛）—— 本模块沿用这一语义。
+ *
+ * 本模块**不**直接依赖 SessionComponent / BackgroundTaskManager 的类型：
+ * 用最小结构端口（`SubSessionActivityPorts`），便于单测注入假实现，
+ * 也避免 core 内部循环依赖。
+ */
+/** sub-session 活性快照（飞书 / 企微 / CLI 统一形状） */
+export interface SubSessionActivity {
+    /** sub-session id（仅诊断用，不渲染给用户） */
+    subSessionId: string;
+    /** 消息总数（`session.messageCount`） */
+    messageCount: number;
+    /** 最后写入时间（ms epoch） */
+    updatedAt: number;
+    /** 最近一条有内容的消息（已截断） */
+    lastMessage?: ActivityMessage;
+}
+/** 最近一条消息（已截断） */
+export interface ActivityMessage {
+    /** 角色（user / assistant / tool / system …） */
+    role: string;
+    /** 已截断的正文 */
+    content: string;
+    /** 消息时间戳（ms epoch，可选） */
+    timestamp?: number;
+}
+/**
+ * ★ Task #5420 返工：装配点传入消息的**最小**结构。
+ *
+ * 为什么不直接用 `SessionMessage`：装配点（event-source-handlers.ts）
+ * 拿到的 session store 消息可能带 parts（新格式：content=""，正文在
+ * parts），这里只需要 role/content/parts 三个字段，收窄依赖面。
+ */
+export interface SessionMessageLite {
+    role?: string;
+    content?: string;
+    timestamp?: number;
+    /** 新格式消息正文（content 为空时从这里提取） */
+    parts?: Array<Record<string, unknown>>;
+}
+/**
+ * 活性档位。
+ *
+ * ★ 阈值理由（不是拍脑袋）：`task.lastUpdatedAt` 的**心跳周期就是 20 分钟**
+ *   （见 delegate-tool.ts 里 "subSessionUpdatedAt / 不再依赖缩短心跳" 的注释）。
+ *   也就是说，一个**健康**的长时间任务最多 20 分钟没有新消息。所以：
+ *   - `< 5min`  → 明显在跑（一轮 ReAct 通常几分钟）
+ *   - `5~20min` → 还在心跳窗口内，但当前这一轮比较久 → 慢
+ *   - `≥ 20min` → 连心跳窗口都超了 → 疑似停滞（该看 trace 了）
+ */
+export type ActivityLevel = "active" | "slow" | "stalled" | "terminal" | "unknown";
+/** liveness 判定结果 */
+export interface ActivityLiveness {
+    level: ActivityLevel;
+    /** 单字符信号灯：🟢 / 🟡 / 🔴 / ⚪ / ❔ */
+    dot: string;
+    /** 档位短语（"活跃" / "缓慢" / "疑似停滞" / "已结束" / "未知"） */
+    label: string;
+    /** 多久之前（"3 分钟前" / "刚刚"）；updatedAt 缺失时 undefined */
+    agoText?: string;
+}
+/** 活跃档位阈值（毫秒） */
+export declare const ACTIVITY_ACTIVE_MS: number;
+export declare const ACTIVITY_SLOW_MS: number;
+/** 最近消息正文的默认截断长度 */
+export declare const DEFAULT_ACTIVITY_MESSAGE_MAX = 200;
+/**
+ * 把「多久之前」渲染成中文短语。
+ *
+ * - 负数 / NaN / 未来时间 → "刚刚"（时钟回拨不该渲染 "−3 分钟前"）
+ * - < 60s → "刚刚"
+ * - < 60min → "N 分钟前"
+ * - < 24h → "N 小时前"
+ * - 其它 → "N 天前"
+ */
+export declare function formatAgo(updatedAt: number | undefined, now: number): string | undefined;
+/** `20:47:12` 形态的钟点（本地时间，卡片窄，不要日期） */
+export declare function formatClockTime(ts: number | undefined): string | undefined;
+/**
+ * 判定活性档位。
+ *
+ * @param activity 活性快照（undefined = 拿不到数据）
+ * @param now      当前时间（注入便于测试）
+ * @param terminal 该任务是否已终态（终态任务永远不是 "stalled"，是 "已结束"）
+ */
+export declare function resolveActivityLiveness(activity: SubSessionActivity | undefined, now: number, terminal?: boolean): ActivityLiveness;
+/**
+ * 截断最近消息正文。
+ *
+ * 为什么不用 `String.slice`：卡片上出现「半个单词 + …」很难读
+ * （企微侧已有同款踩坑记录，见 wecom-card-builder 的 `clipWord`）。
+ *
+ * 策略（与 `clipWord` 对齐但不复用 —— 那个是 wecom 私有且带 CJK 交界逻辑）：
+ * 1. 先 `flattenInline` 压平换行 / 折叠空白（卡片是单行渲染）
+ * 2. 有空格 → 回退到最后一个空格边界
+ * 3. 否则硬截（CJK 无空格，硬截是正确的；不该给中文塞省略号断词）
+ */
+export declare function truncateActivityMessage(text: string | undefined, max?: number): string;
+/**
+ * 渲染成飞书 markdown 行（`⚡ 子会话活性` 面板正文）。
+ *
+ * ## 输出形态
+ *
+ * 有数据：
+ * ```
+ * 🟢 活跃（3 分钟前有写入） · 消息数 128 条
+ * 🕐 最近写入：20:47:12
+ * 💬 最近消息：[assistant] 已定位到 wecom-card-builder.ts:485 …
+ * ```
+ *
+ * 无数据（**绝不返回空数组** —— 否则用户分不清"没数据"和"按钮没生效"）：
+ * ```
+ * ❔ 暂无数据（子会话已归档或未落盘）
+ * ```
+ */
+export declare function formatActivityLines(activity: SubSessionActivity | undefined, now: number, terminal?: boolean): string[];
+/**
+ * 渲染成企微 `quote_area`（`{title, text}`）。
+ *
+ * ## 为什么是 quote_area 而不是 horizontal_content_list
+ *
+ * 企微 `horizontal_content_list` 协议上限 **6 条**（`MAX_HORIZONTAL_ROWS`），
+ * 进展/更新卡的 6 条已被「状态 + 5 条时间线」占满。把活性塞进去必然挤掉
+ * 时间线 = 违反用户「之前展示的信息一个都不能少」。
+ *
+ * ## 为什么 text 是单行
+ *
+ * `quote_area.quote_text` 真网实证只渲染 ~2 行（见 wecom-card-builder 头注释里
+ * Task #5203 的取证）。所以压成 1~2 行短文本，完整消息截断到 80 字。
+ *
+ * @returns `{title, text, overflow}` —— `overflow=true` 时调用方应把 text
+ *          降级到 `sub_title_text`（见 buildWecomCardUpdateFrame）
+ */
+export declare function formatActivityQuote(activity: SubSessionActivity | undefined, now: number, terminal?: boolean): {
+    title: string;
+    text: string;
+    overflow: boolean;
+};
+/** `listTasks()` 返回元素的**最小**结构（不依赖 BackgroundTask 全量类型） */
+export interface BackgroundTaskLite {
+    id: string;
+    subSessionId: string;
+    associatedTaskId?: number;
+}
+/**
+ * 在后台任务表里按 roy 任务号反查 `{bgProcessId, subSessionId}`。
+ *
+ * ## 为什么要这个反查（而不是直接读 task.context）
+ *
+ * `task.background.*` 事件 payload 里 `backgroundTaskId` / `subSessionId` /
+ * `associatedTaskId` 三个 id 齐全 —— 但那是**事件 payload**，不是持久层。
+ * 卡片回调（`card.action.trigger`）只带回 `messageId` + `action.value.taskId`，
+ * **没有** backgroundTaskId。而 `lark_card` / `wecom_cards` 表都只按 taskId 索引。
+ *
+ * 所以必须从 `BackgroundTaskManager.listTasks()` 反查。命中率：
+ * - 活跃任务：100%（在 `tasks` Map 里）
+ * - 已终结任务：也在（`listTasks()` 返回 `tasks ∪ terminalTasks`，
+ *   delegate-tool.ts 注释已证）—— 所以「点已完成任务卡片的刷新」也能拿到
+ * - 进程重启后：内存表空 → undefined → 卡片渲染「暂无数据」（不抛、不阻断 patch）
+ *
+ * 多命中时取**最后一个**（`listTasks()` 是 Map 插入序，同 taskId 的复用
+ * sub-session 场景下，越晚的越新鲜）。
+ */
+export declare function findBackgroundTaskByAssociatedTaskId(tasks: readonly BackgroundTaskLite[] | undefined, taskId: number): BackgroundTaskLite | undefined;
+/**
+ * session-only 活性 probe 的端口。
+ *
+ * ## 与 `createActivityProbe` 的区别（为什么不能复用）
+ *
+ * `createActivityProbe(taskId)` 走的是
+ * ```
+ * taskId → findBackgroundTaskByAssociatedTaskId → bgTask.subSessionId → 活性
+ * ```
+ * 这条链**必须先有 task**（`associatedTaskId` 来自 task 表）。而本次需求是
+ * 「有 sub-session 但**无** task」—— 那条链的第一环就不存在。
+ *
+ * 所以新增一条**直达**路径：调用方已经把 sessionId 拿在手里，直接读 store。
+ *
+ * ## 共用部分（刻意复用，避免阈值漂移）
+ *
+ * 拿到的 `{messageCount, updatedAt, lastMessage}` 之后，仍走同一套
+ * `resolveActivityLiveness` / `formatActivityLines` / `formatActivityQuote`
+ * —— 两个渠道、两种主键的卡片，颜色与文案口径必须完全一致。
+ */
+export interface SessionActivityPorts {
+    /** 读 session 元信息（`sessionComponent.get()`）；缺失/抛错 ⇒ undefined */
+    getSession?: (sessionId: string) => Promise<{
+        messageCount?: number;
+        updatedAt?: number;
+    } | null | undefined> | {
+        messageCount?: number;
+        updatedAt?: number;
+    } | null | undefined;
+    /**
+     * ★ CV BLOCKER-3：读该 session 的**生命周期**（哪个后台任务在跑它、状态如何）。
+     *
+     * 这是「超时/完成/停止体现在卡片上」的唯一可信来源 —— 不能靠 task.status
+     * （没 task 就没有），也不能硬写 false。装配点实现：
+     * `sessionId → BackgroundTaskManager.listTasks() 里 subSessionId 命中 → status`
+     * （running/pending → running；completed/timeout/failed/stopped 直接映射）。
+     *
+     * 不注入 / 抛错 / 找不到 → 视为 `running`（乐观：宁可显示在跑，
+     * 也不要凭空宣布结束）。
+     */
+    getLifecycle?: (sessionId: string) => Promise<SessionLifecycle | undefined> | SessionLifecycle | undefined;
+    /** 读最近一条消息（`getMessages(id, {offset:-1, limit:1})`） */
+    getLastMessage?: (sessionId: string) => Promise<ActivityMessage | undefined> | ActivityMessage | undefined;
+}
+/**
+ * 造 `sessionId → ActivityProbeResult` 的异步 probe（无 task 场景）。
+ *
+ * ## 全链路 best-effort（与 task 路径同一纪律）
+ *
+ * - `getSession` 缺失 / 返回空 / 抛错 ⇒ `{activity: undefined}`（渲染「暂无数据」）
+ * - `getLastMessage` 抛错 ⇒ activity 保留（只是没有最近消息）
+ * - **永不抛**：刷新卡片绝不能因为取数失败而失败
+ *
+ * ## 为什么 `messageCount` 允许缺省
+ *
+ * `sessionComponent.get()` 在部分存储实现下可能不带 `messageCount`
+ * （旧行 / memory 后端）。此时用 0 起步而不是报错 —— 卡片仍能显示
+ * 「最近消息 + 最后写入时间」，那才是判断 LLM 有无推进的关键信号。
+ */
+export declare function createSessionActivityProbe(ports: SessionActivityPorts): (sessionId: string) => Promise<ActivityProbeResult>;
+/**
+ * probe 依赖的最小端口集。
+ *
+ * 全部 optional：任一缺失只降级（返回 undefined），绝不抛 —— 与
+ * `getSubSessionActivity` 既有语义一致。
+ */
+export interface SubSessionActivityPorts {
+    /** 列后台任务（`BackgroundTaskManager.listTasks()`） */
+    listBackgroundTasks?: () => readonly BackgroundTaskLite[] | undefined;
+    /** 读 sub-session 消息数 + 最后写入时间（`getSubSessionActivity`） */
+    getSubSessionActivity?: (bgProcessId: string) => Promise<{
+        messageCount: number;
+        updatedAt: number;
+    } | undefined> | {
+        messageCount: number;
+        updatedAt: number;
+    } | undefined;
+    /** 读最近一条消息（`sessionComponent.getMessages(id, {offset:-1, limit:1})`） */
+    getLastMessage?: (subSessionId: string) => Promise<ActivityMessage | undefined> | ActivityMessage | undefined;
+    /** 该任务是否终态（决定 liveness 是否报 "已结束" 而不是 "疑似停滞"） */
+    isTerminalTask?: (taskId: number) => Promise<boolean> | boolean;
+}
+/** session 层生命周期（★ CV BLOCKER-3：比 boolean 更有表达力） */
+export type SessionLifecycle = "running" | "completed" | "timeout" | "failed" | "stopped";
+/** probe 返回的完整活性快照（含生命周期，供渲染层用） */
+export interface ActivityProbeResult {
+    activity?: SubSessionActivity;
+    /** 是否终态（便于老调用方继续用布尔判断） */
+    terminal: boolean;
+    /**
+     * ★ CV BLOCKER-3：具体生命周期。
+     *
+     * 为什么不能只有 `terminal: boolean`：用户明令「超时、完成等生命周期事件
+     * 也要体现在卡片上」—— 单一布尔把 timeout / failed / stopped 全压成
+     * 「已完成」，用户看不出到底是哪种结束。有 task 时可由 task.status 映射，
+     * **无 task 时必须由本字段承载**。
+     *
+     * 缺省（不传）⇒ 由 `terminal` 推导（true→completed / false→running）。
+     */
+    lifecycle?: SessionLifecycle;
+}
+/**
+ * 造一个 `taskId → ActivityProbeResult` 的异步 probe。
+ *
+ * ## 全链路 best-effort
+ *
+ * 每一步都 try/catch 后降级：
+ * - `listBackgroundTasks` 缺失/抛错 → 返回 `{activity: undefined}`（渲染「暂无数据」）
+ * - 反查不到 bg 任务 → 同上
+ * - `getSubSessionActivity` 抛错/undefined → 仍返回 activity（messageCount=0，
+ *   updatedAt 用 `Date.now()` 兜底会让 liveness 假报"活跃"，所以此时**返回 undefined**）
+ * - `getLastMessage` 抛错 → activity 保留，只是没有 `lastMessage`
+ *
+ * ⇒ 卡片 patch 永远不会因为活性取数失败而失败。
+ */
+export declare function createActivityProbe(ports: SubSessionActivityPorts): (taskId: number) => Promise<ActivityProbeResult>;
+/**
+ * 把一条 `SessionMessage` 归一化成 `ActivityMessage`（截断 + 角色提取）。
+ *
+ * 供两侧装配点在 `getLastMessage` 端口实现里复用，避免两份截断逻辑。
+ *
+ * ★ CV MINOR-2（#5420）：空 content **不再返回 undefined** ——
+ *   tool 角色消息常把 payload 放 parts、content 为空，此前被
+ *   装配点 filter 掉 ⇒ 「最新 5 条」排不满、与事实不符。
+ *   现在保留消息、content 用占位「（无文本内容）」，
+ *   条数与库内事实一致。原语义（活性面板的 lastMessage）
+ *   不受影响：那里拿到空占位同样可读。
+ */
+export declare function toActivityMessage(msg: {
+    role?: string;
+    content?: string;
+    timestamp?: number;
+    parts?: Array<Record<string, unknown>>;
+} | undefined, max?: number): ActivityMessage | undefined;
+/**
+ * 把 `BackgroundTaskManager.listTasks()` 里那条任务的 status 映射成 session 生命周期。
+ *
+ * 为什么单独抽出来并导出：飞书（`event-source-handlers.ts`）与企微
+ * （`wecom-cli-handler.ts`）两个装配点都要做同一件事，各写一份必然漂移 ——
+ * 同一个 session 在飞书显示「已完成」、企微显示「运行中」是最糟的体验。
+ *
+ * 未知/缺失 → `running`（乐观：宁可显示还在跑，也不要凭空宣布结束）。
+ */
+export declare function mapBgTaskStatusToSessionLifecycle(status: string | undefined): SessionLifecycle;
+/** 最近消息默认条数（用户拍板：A 五条） */
+export declare const RECENT_MESSAGE_LIMIT = 5;
+/** 每条消息内容（reason）的截断长度（卡片窄，5 条 × 100 字不撑爆） */
+export declare const RECENT_MESSAGE_MAX = 100;
+/**
+ * role → 展示名称。
+ *
+ * session store 里**没有真实发送者名**，只有 role —— 用户拍板
+ * 「名称（发送者，session 消息取 role user/assistant）」，
+ * 所以名称 = role 的友好映射。未知 role 原样标注（不猜）。
+ */
+export declare function recentMessageRoleLabel(role: string | undefined): string;
+/**
+ * 把最近消息列表渲染成卡片 markdown 行。
+ *
+ * ## 形态（★ Task #5420 返工：标题去重 + 工具名/reason）
+ *
+ * ```
+ * - 👤 用户：先完成工具改造吧…
+ * - 🤖 助手：task_create：建返工任务…
+ * ```
+ *
+ * 标题只出现在面板 title（「💬 最近消息」）一处；
+ * 列表首行**不再**重复「最近消息（最新 N 条）：」
+ * （用户实测截图：标题重复两次）。
+ *
+ * ## 三态语义
+ *
+ * - 5 条 → 5 行
+ * - 不足 5 条 → 实际条数（诚实显示）
+ * - 0 条 / undefined → 单行「暂无消息」（不渲染空面板假象）
+ *
+ * 每条内容复用 `truncateActivityMessage`（flattenInline 单行化 +
+ * 词边界截断），与活性面板同口径，不漂移。
+ */
+export declare function formatRecentMessageLines(messages: ActivityMessage[] | undefined, max?: number): string[];
+/** 一条工具调用的展示形态 */
+export interface ToolCallView {
+    /** 工具名（ToolCallPart.toolName） */
+    toolName: string;
+    /** 调用意图（ToolCallPart.arguments.reason，#5422 注入）；旧调用可能没有 */
+    reason?: string;
+}
+/**
+ * 从 session 消息列表提取**工具调用**（tool-call part）。
+ *
+ * ## 真实结构（生产 sessions.db 勘察，#5420 返工）
+ *
+ * assistant 消息 `parts` 含 ToolCallPart：
+ * `{type:'tool-call', toolName, arguments, toolCallId, state}`。
+ * reason 是 #5422 注入的必填参数（`arguments.reason`）；
+ * `arguments` 可能是对象或 JSON 字符串（两种都兼容）。
+ *
+ * ## 降级
+ *
+ * - 非工具消息（text/user/tool-result）→ 跳过
+ * - 无 reason 的旧调用 / arguments 解析失败 → `reason: undefined`
+ *   （保留该调用，渲染层显示「—」；不抛）
+ */
+export declare function extractToolCallsFromMessages(messages: Array<{
+    role?: string;
+    content?: string;
+    timestamp?: number;
+    parts?: Array<Record<string, unknown>>;
+}> | undefined): ToolCallView[];
+/**
+ * 把工具调用列表渲染成卡片 markdown 行（★ #5420 返工）。
+ *
+ * ## 形态（用户澄清 08:21：展示工具名称和 reason）
+ *
+ * ```
+ * 🔧 最近工具调用（最新 5 条）：
+ * - bash：查看目录结构
+ * - read_file：读源码定位根因
+ * ```
+ *
+ * ## 三态语义（与旧 formatRecentMessageLines 同纪律）
+ *
+ * - 有调用 → 标题（**只出现一次**，修旧版标题双写）+ 每行「工具名：reason」
+ * - 无 reason 的旧调用 → 「—」
+ * - 0 条 / undefined → 单行「暂无工具调用」（不渲染空面板假象）
+ */
+export declare function formatRecentToolCallLines(calls: ToolCallView[] | undefined, max?: number): string[];

package/dist/env/task/plugins/wecom-card-state-store.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @fileoverview WecomCardStateStore — 企微任务进展消息的持久化记录（Task #5193）
+ *
+ * ## 为什么需要（与 lark-cards.db 同因）
+ *
+ * 企微 wecom-cli **没有** interactive card / 消息更新 API ——
+ * 进展卡片是**每次更新发一条新 markdown**。但节流判定、
+ * 「无卡片不凭空发卡」守卫、终态收尾都需要知道
+ * 「这个 task 是否发过、发到哪个 chat、当前什么状态」。
+ *
+ * ## 与 lark-card-state-store 的关系
+ *
+ * 结构对齐（同一套接口语义），但**独立库文件**（wecom-cards.db）：
+ * - lark-cards.db 有 messageId（可 patch 同一张卡）
+ * - wecom-cards.db 无 messageId 语义（每条都是新消息），
+ *   记录 `taskId → chatId / status / timeline / updateCount`
+ *
+ * ## 记录生命周期
+ *
+ * ```
+ * create 成功 → upsert({status:"open"})
+ * update 成功 → touch（updateCount+1，timeline 追加）
+ * 节流        → touch timeline（数据不丢，只是不发）
+ * completed/failed/cancelled → markClosed()
+ * delete      → markClosed()（保留记录便于追溯）
+ * ```
+ *
+ * ★ 终态**不删除**记录：保留 chatId / timeline 便于事后追溯。
+ */
+/** 记录状态（与 LarkCardRecordStatus 语义一致） */
+export type WecomCardRecordStatus = "open" | "paused" | "closed";
+/** 一条企微卡片持久化记录 */
+export interface WecomCardState {
+    /** 任务 ID（主键） */
+    taskId: number;
+    /** 企微 chat_id（单聊=userid，群聊=chatid） */
+    chatId: string;
+    /** 当前 pin 状态（企微无 pin，恒 false；保留字段对齐接口） */
+    pinned: boolean;
+    /** 记录状态 */
+    status: WecomCardRecordStatus;
+    /** 首次发卡时间（ms epoch） */
+    createdAt: number;
+    /** 最后更新时间（ms epoch） */
+    updatedAt: number;
+    /** 终结时间（ms epoch）；仅 status=closed 有值 */
+    closedAt?: number;
+    /** 已发送的更新条数（诊断用） */
+    updateCount: number;
+    /**
+     * 累积时间线（JSON 字符串：Milestone[]）
+     *
+     * ★ 企微每次发新消息都要带**完整历史时间线**（无 patch 能力），
+     *   所以时间线必须持久化 —— 重启后第一条 update 也要能渲染
+     *   完整历史。
+     */
+    timeline?: string;
+}
+/** 持久化端口（hook 只依赖这个接口，便于测试注入内存实现） */
+export interface WecomCardStateStore {
+    /** 写入或覆盖一条记录 */
+    upsert(state: WecomCardState): void;
+    /** 按 taskId 读取 */
+    get(taskId: number): WecomCardState | undefined;
+    /** 列出全部记录（诊断用） */
+    list(): WecomCardState[];
+    /** 标记为暂停（保留记录） */
+    markPaused(taskId: number): void;
+    /** 从暂停/终结翻回进行中（resume） */
+    markReopened(taskId: number): void;
+    /** 标记终结（completed / failed / cancelled / deleted） */
+    markClosed(taskId: number): void;
+    /** 真删除（仅测试/手工清理用） */
+    delete(taskId: number): void;
+    /** 释放资源 */
+    close(): void;
+}
+/**
+ * 内存实现（测试 / 降级）
+ *
+ * ★ 独立导出（`createMemoryWecomCardStore`），测试直接用，
+ *   不经过 `createWecomCardStateStore` 的测试环境守卫。
+ */
+export declare class MemoryWecomCardStateStore implements WecomCardStateStore {
+    private readonly records;
+    upsert(state: WecomCardState): void;
+    get(taskId: number): WecomCardState | undefined;
+    list(): WecomCardState[];
+    markPaused(taskId: number): void;
+    markReopened(taskId: number): void;
+    markClosed(taskId: number): void;
+    delete(taskId: number): void;
+    close(): void;
+}
+/** 测试工厂：内存 store */
+export declare function createMemoryWecomCardStore(): WecomCardStateStore;
+export declare class SqliteWecomCardStateStore implements WecomCardStateStore {
+    private readonly db;
+    constructor(dbPath: string);
+    upsert(state: WecomCardState): void;
+    get(taskId: number): WecomCardState | undefined;
+    list(): WecomCardState[];
+    markPaused(taskId: number): void;
+    markReopened(taskId: number): void;
+    markClosed(taskId: number): void;
+    delete(taskId: number): void;
+    close(): void;
+}
+/** 默认库文件路径：`$HOME/.local/share/roy-agent/wecom-cards.db` */
+export declare function getDefaultWecomCardDbPath(): string;
+/**
+ * 创建持久化 store
+ *
+ * ★ 失败降级：SQLite 打不开时**不抛错**，回落内存实现并 warn ——
+ *   卡片该发还得发，绝不能因为持久化层故障让通知路径整体崩掉。
+ *
+ * ★ 测试环境保护（与 createLarkCardStateStore 同配方）：
+ *   bun test 环境 + 未显式指定路径 → 一律返回内存实现（零副作用），
+ *   防止测试污染真实用户库。
+ */
+export declare function createWecomCardStateStore(dbPath?: string): WecomCardStateStore;