@ai-setting/roy-agent-core 1.7.51 → 1.7.53

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

@@ -0,0 +1,651 @@
+/**
+ * @fileoverview LarkCardPatchNotifier - 单卡片 patch 不刷屏通知器（Task #4230 重写）
+ *
+ * 封装"单卡片 patch"逻辑：每个 task 在飞书群里只有**一张**交互式卡片，
+ * 状态变化时只 patch 这张卡片的内容（不刷屏），并且把卡片**置顶**（pin），
+ * 让用户随时能看到任务进展。
+ *
+ * ## 设计要点
+ *
+ * 1. **生命周期**：startTask → updateTask* → finishTask
+ *    - startTask: `im +messages-send` 发初始卡片 → 拿 messageId → `im pins create` 置顶
+ *    - updateTask: `im messages patch` 改同一卡片内容（进度/当前步骤/里程碑/过程时间线）
+ *    - finishTask: `im messages patch` 终态 + `im pins delete` 取消置顶
+ *
+ * 2. **卡片样式（用户验收过的 live card 样式）**
+ *    - header.title       📊 Task 实时更新（<标题>）
+ *    - header.subtitle    spinner: '<emoji>' | <状态短语>
+ *    - 实时进度（进度条 / 进行中）
+ *    - 当前步骤
+ *    - 🎯 里程碑时间线
+ *    - 🔧 过程时间线
+ *    - footer：🔄 更新次数 | 🔄 Spinner | 🟣 状态
+ *
+ * 3. **lark-cli 参数契约（Task #4230 修复，2026-10-15 用 tongzhuli profile 实测）**
+ *    - `im +messages-send`：`--msg-type interactive --content <card JSON>` ✅
+ *      （+shortcut 的 --content 直接吃 card JSON；旧的 `{"content":...}` 双重包裹会 230099）
+ *    - `im messages patch`：**只能**用 `--data '{"content":"<card JSON 字符串>"}'`
+ *      ❌ 不能传 `--content`（unknown flag → 秒失败 → 卡片永远停在初始态）
+ *    - `im pins create`：**只能**用 `--data '{"message_id":"om_xxx"}'`
+ *      ❌ 不能传 `--chat-id/--message-id`（unknown flag → pin 永远失败）
+ *    - `im pins delete`：`--message-id om_xxx --yes`（high-risk-write，必须 --yes）
+ *
+ * 4. **状态自持（不刷屏 + 持续滚动）**
+ *    - 同一 messageId 的里程碑/过程时间线由 notifier 自己累积（append + 去重）
+ *    - 每次 update 递增更新次数并轮换 spinner emoji（"持续滚动"观感）
+ *    - caller 只需要传"本次新增了什么"，不需要自己维护全量历史
+ *
+ * 5. **并发串行化**：同一 messageId 的 patch 走 mutex，避免飞书端并发覆盖
+ *
+ * 6. **错误处理**
+ *    - 发卡/pat 失败 → 抛错（caller 决定是否 graceful degrade）
+ *    - pin/unpin 失败 → 非致命（warn + span 属性标记），卡片仍可见
+ *
+ * @example
+ * ```typescript
+ * const notifier = new LarkCardPatchNotifier();
+ * const { messageId, pinned } = await notifier.startTask({
+ *   chatId: "oc_xxx", profile: "tongzhuli", taskId: 4221, taskTitle: "调研",
+ * });
+ * await notifier.updateTask({
+ *   messageId, status: "running", taskId: 4221, taskTitle: "调研",
+ *   currentStep: "扫描 GitHub Issues",
+ *   milestones: [{ title: "调研启动", timestamp: new Date().toISOString() }],
+ * });
+ * await notifier.finishTask({ messageId, status: "completed" });
+ * ```
+ */
+/**
+ * 卡片状态。
+ *
+ * ★ Part 2（workflow 通知）：新增 `"stopped"`（灰）—— task 只会用前三种，
+ *   但同一套卡片骨架要给 workflow run 复用，而 workflow 有 stopped 终态。
+ */
+export type CardStatus = "running" | "completed" | "failed" | "stopped";
+/** workflow 卡片状态（与 CardStatus 同集合；语义别名，便于阅读） */
+export type WorkflowCardStatus = CardStatus;
+/** 里程碑（关键节点）：时间 + 标题 + 描述 */
+export interface Milestone {
+    /** 里程碑标题（如 "调研启动"），会被拼进 "🟢 <title>" */
+    title: string;
+    /** ISO 8601 时间戳；缺省时渲染 "—" */
+    timestamp?: string;
+    /** 补充说明（渲染成 "  → <description>"） */
+    description?: string;
+}
+/** 过程步骤（中间步骤）：时间段 + 描述 */
+export interface ProcessStep {
+    /** 步骤标题（如 "扫描 GitHub Issues"） */
+    title: string;
+    /** ISO 8601 起始时间；缺省时不渲染时间行 */
+    timestamp?: string;
+    /** ISO 8601 结束时间；缺省时渲染成 "→ 现在" */
+    endTimestamp?: string;
+    /** 补充说明（渲染成 "  → <description>"） */
+    description?: string;
+    /** 步骤分类（如 research / code / test），有值时追加到标题括号内 */
+    category?: string;
+}
+/**
+ * 任务元信息（卡片顶部"任务栏位"区块的数据源）
+ *
+ * ★ 用户验收要求（Task #4230 v2）：
+ *   卡片第一块必须是任务栏位：任务 ID / 标题 / 描述 / 目标 / 父任务 / 优先级 / context…
+ *   且 context 要渲染成**人类可读的 markdown**（绝不出现 JSON 原文）。
+ */
+export interface TaskMeta {
+    /** 任务 ID（#4223） */
+    id?: number | string;
+    /** 任务标题 */
+    title?: string;
+    /** 任务描述 */
+    description?: string;
+    /** 目标与预期交付物（task.goals_and_expected_deliverables） */
+    goals?: string;
+    /** 父任务 ID（无父任务时不渲染） */
+    parentTaskId?: number;
+    /** 优先级（low/medium/high） */
+    priority?: string;
+    /** 任务类型（normal/cycle/longterm） */
+    type?: string;
+    /** 项目路径 */
+    projectPath?: string;
+    /** task.context 原始 JSON 字符串 —— 渲染时会被展开成可读 bullet，不显示 JSON */
+    context?: string;
+    /** 任务当前状态描述（task.current_status） */
+    currentStatus?: string;
+    /**
+     * ★ Task #4331：专属群 chatId（决定卡片顶部按钮 + 下方链接渲染）
+     *
+     * - undefined 或空：渲染"为这个任务建群"按钮 + 不显示链接
+     * - 有值：渲染"解散该群"按钮 + 显示飞书 applink "进入群"
+     *
+     * 通常从 task.context.larkPerTaskChatId 读出，由 LarkCliTaskNotifyHook
+     * 透传给 buildTaskCard / updateTask。
+     */
+    perTaskChatId?: string;
+    /**
+     * ★ Task #4331：专属群名（可选，仅在渲染链接文本"进入群 XXX"时使用）
+     *
+     * 若未提供，默认显示"进入群"。
+     */
+    perTaskChatName?: string;
+}
+export interface StartTaskOptions {
+    /** 飞书 chat ID (oc_xxx) */
+    chatId: string;
+    /** lark-cli profile（多 appId 场景用） */
+    profile?: string;
+    /** 任务元信息（栏位区块 + header 标题） */
+    meta: TaskMeta;
+    /** 首次渲染时的里程碑（通常一条 "Task 创建"） */
+    milestones?: Milestone[];
+}
+export interface UpdateTaskOptions {
+    /** 飞书 message_id（startTask 返回值） */
+    messageId: string;
+    /** 飞书 chat ID（仅用于诊断/日志，patch 不依赖它） */
+    chatId?: string;
+    /** lark-cli profile */
+    profile?: string;
+    status: CardStatus;
+    /** 任务元信息（缺省时沿用 startTask 时缓存的那份） */
+    meta?: TaskMeta;
+    /**
+     * 真实进度百分比（0-100）。
+     *
+     * ★ 只在调用方**确实知道**进度时传（禁止拿耗时估算假进度）。
+     *   缺省时进度区渲染"进行中"而不是假百分比。
+     */
+    progress?: number;
+    /** 本次新增的里程碑（会 append 到已有序列并去重） */
+    milestones?: Milestone[];
+    /** 本次新增的过程信息（会 append 到已有列表并去重） */
+    processSteps?: ProcessStep[];
+}
+export interface FinishTaskOptions {
+    messageId: string;
+    chatId?: string;
+    profile?: string;
+    status: Extract<CardStatus, "completed" | "failed">;
+    meta?: TaskMeta;
+    /** 终态补充说明（会作为最后一条里程碑 append） */
+    finalStep?: string;
+    progress?: number;
+}
+/** 改投链接卡片的入参（Task #4230 follow-up） */
+export interface RedirectNoticeOptions {
+    /** 发到哪个群（通常是"触发群"，即被判定为别 task 专属群的那个） */
+    chatId: string;
+    profile?: string;
+    /** 本 task */
+    taskId?: number | string;
+    taskTitle?: string;
+    /** 卡片实际落在哪个群 */
+    targetChatId: string;
+    /** 目标群名（渲染成可点击文本；缺省显示"专属群"） */
+    targetChatName?: string;
+    /** 改投原因（诊断，写进卡片文案） */
+    reason?: string;
+}
+export interface StartTaskResult {
+    messageId: string;
+    /** pin 是否成功（失败不影响卡片可见性，但 trace 里可查） */
+    pinned: boolean;
+    /** pin 失败原因（诊断用） */
+    pinError?: string;
+}
+export interface LarkCardPatchNotifierOptions {
+    /** 启动时是否 pin（默认 true） */
+    pinOnStart?: boolean;
+    /** 结束时是否 unpin（默认 true） */
+    unpinOnFinish?: boolean;
+}
+export interface CardPayload {
+    schema: "2.0";
+    header: {
+        title: {
+            tag: "plain_text";
+            content: string;
+        };
+        subtitle: {
+            tag: "plain_text";
+            content: string;
+        };
+        template: string;
+    };
+    body: {
+        elements: Array<Record<string, any>>;
+    };
+}
+/**
+ * workflow 运行元信息（卡片顶部"运行栏位"区块的数据源）
+ *
+ * ★ 与 {@link TaskMeta} 对应：task 卡片顶部是"任务栏位"，workflow 卡片顶部是
+ *   "运行栏位"（workflow 名 / runId / workflowId / 触发输入摘要）。
+ */
+export interface WorkflowMeta {
+    /** run 标识（== sessionId，engine 的 workflow:*.run 载荷提供） */
+    runId: string;
+    /** workflow 名称（人可读，用于卡片标题） */
+    workflowName?: string;
+    /** workflow 定义 id（可选） */
+    workflowId?: string;
+    /** 触发输入（before.run 提供）；渲染时会被 humanize，绝不输出 JSON 原文 */
+    input?: unknown;
+}
+export interface StartWorkflowOptions {
+    /** 飞书 chat ID (oc_xxx) */
+    chatId: string;
+    /** lark-cli profile（多 appId 场景用） */
+    profile?: string;
+    /** workflow 运行元信息（栏位区块 + header 标题） */
+    meta: WorkflowMeta;
+    /** DAG 节点总数 */
+    totalNodes?: number;
+    /** 已产出结果的节点数 */
+    completedNodes?: number;
+    /** 首次渲染时的里程碑（通常一条 "Workflow 启动"） */
+    milestones?: Milestone[];
+    /** 首次渲染时的过程记录 */
+    processSteps?: ProcessStep[];
+}
+export interface UpdateWorkflowOptions {
+    /** 飞书 message_id（startWorkflow 返回值） */
+    messageId: string;
+    /** 飞书 chat ID（仅用于诊断/日志，patch 不依赖它） */
+    chatId?: string;
+    /** lark-cli profile */
+    profile?: string;
+    /** 运行状态（缺省沿用上一次；默认为 running） */
+    status?: WorkflowCardStatus;
+    /** workflow 运行元信息（缺省时沿用 startWorkflow 时缓存的那份） */
+    meta?: WorkflowMeta;
+    /** 当前节点 id（渲染成"当前节点"） */
+    currentNode?: string;
+    /** 当前节点类型（agent / tool / ...） */
+    currentNodeType?: string;
+    /** 已产出结果的节点数（进度分子） */
+    completedNodes?: number;
+    /** DAG 节点总数（进度分母） */
+    totalNodes?: number;
+    /** 真实进度百分比（0-100）。缺省时由 completedNodes/totalNodes 推算 */
+    progress?: number;
+    /** 运行耗时（毫秒） */
+    durationMs?: number;
+    /** 失败原因 */
+    error?: string;
+    /** 本次新增的里程碑（append + 去重） */
+    milestones?: Milestone[];
+    /** 本次新增的过程信息（append + 去重） */
+    processSteps?: ProcessStep[];
+}
+export interface FinishWorkflowOptions {
+    messageId: string;
+    chatId?: string;
+    profile?: string;
+    /** 终态：completed / failed / stopped */
+    status: Extract<WorkflowCardStatus, "completed" | "failed" | "stopped">;
+    meta?: WorkflowMeta;
+    totalNodes?: number;
+    completedNodes?: number;
+    progress?: number;
+    durationMs?: number;
+    error?: string;
+    /** 终态补充说明（会作为最后一条里程碑 append） */
+    finalStep?: string;
+}
+/**
+ * 格式化 ISO 8601 时间戳为人类可读的 HH:mm:ss（北京时间 UTC+8）
+ *
+ * cross-validation ⚠️ #5 修复：原实现直接显示 ISO 8601 字符串（如 "2026-10-15T01:42:05.000Z"）
+ * 对用户不友好。改为显示 HH:mm:ss（中国用户视角，北京时间）。
+ *
+ * @param iso ISO 8601 字符串；无效输入返回原值（保持向后兼容）
+ */
+export declare function formatTimestampForDisplay(iso: string | undefined): string;
+/**
+ * 把多行/带 markdown 标记的长文本压成**单行可读文本**（用于卡片里的行内栏位）
+ *
+ * 背景（实测问题）：agent 写的 task.description / milestoneDescription 常含
+ * `## 标题`、`- 列表`、换行 —— 直接塞进卡片的一个 bullet 会把卡片结构撑坏
+ * （标题级别会被飞书渲染成大标题，列表项和下一行黏在一起）。
+ *
+ * 处理：标题标记去掉、列表项转 "·"、换行转 " · "、压缩空白、超长截断。
+ * 路径 / 命令 / 中文正文不受影响。
+ */
+export declare function sanitizeInlineText(text: string, maxLen?: number): string;
+/** ISO 8601 时间串 → 北京时间 "YYYY-MM-DD HH:mm"（非 ISO 时原样返回） */
+export declare function formatDateTimeForDisplay(value: string): string;
+/**
+ * 渲染进度条（用户验收样式：▓ 填充 + ░ 空白 + 百分比）
+ *
+ * @param progress 0-100
+ */
+export declare function renderProgressBar(progress: number): string;
+/**
+ * 解析任务标题显示文本（cross-validation ⚠️ #4 修复）
+ *
+ * 优先级：
+ * 1. opts.taskTitle（caller 明确提供）→ 原样使用
+ * 2. opts.taskId + opts.title → "#<taskId> <title>"
+ * 3. opts.taskId 单独 → "#<taskId>"
+ * 4. 兜底 → "Task"（绝不暴露 chatId）
+ */
+export declare function resolveTaskTitleForDisplay(opts: {
+    taskTitle?: string;
+    taskId?: number | string;
+    title?: string;
+}): string;
+/**
+ * 任务定位信息行（Task #2325 保留：项目 / worktree / 前序上下文）
+ *
+ * 旧实现把这些信息渲染在普通文本通知里；卡片化后放进卡片顶部一行，
+ * 保证"飞书里一眼看出任务归属哪个项目 / 哪个 worktree / 关联哪个前序任务"。
+ */
+/**
+ * 把任意值渲染成**人类可读文本**（绝不输出 JSON 原文）
+ *
+ * - string / number / boolean → 原样（超长截断）
+ * - array  → 逐项 humanize 后用 "、" 连接
+ * - object → 逐字段 "key: value" 用 " · " 连接（递归一层）
+ *
+ * ★ 用户要求：卡片里不要出现 JSON。
+ */
+export declare function humanizeValue(value: unknown, maxLen?: number): string;
+/**
+ * 渲染"任务栏位"区块（用户验收要求的第一块）
+ *
+ * 顺序：任务 ID → 标题 → 描述 → 目标 → 父任务 → 优先级/类型 → 状态 → context 展开
+ *
+ * ★ context 是 task.context 的 JSON 字符串，这里会被**展开成可读 bullet**
+ *   （已知字段用友好标签，未知字段用原 key），绝不直接输出 JSON。
+ */
+export declare function renderTaskInfoLines(meta: TaskMeta): string[];
+/**
+ * task.context(JSON 字符串) → 可读 bullet 行
+ *
+ * 坏 JSON / 非对象 → 返回空数组（渲染时安全跳过，不崩、不输出 JSON）。
+ */
+export declare function renderContextAsLines(context?: string): string[];
+/**
+ * 渲染里程碑序列（可变化）
+ *
+ * 样式：`- **HH:mm:ss** <title>` + 可选缩进说明行（markdown 列表，飞书渲染稳定）
+ */
+export declare function renderMilestones(milestones: Milestone[]): string;
+/**
+ * 渲染过程信息 list（可变化）
+ *
+ * 样式：`- **HH:mm:ss → 现在** <title>` + 可选缩进说明行
+ */
+export declare function renderProcessSteps(steps: ProcessStep[]): string;
+/**
+ * 构造 card JSON payload（Card 2.0 schema，用户验收样式 Task #4230 v2）
+ *
+ * 布局（严格按用户指定顺序）：
+ * 1. header.title = 📊 Task 实时更新；header.subtitle = spinner + 状态 + 更新次数
+ * 2. **任务栏位**：任务 ID / 标题 / 描述 / 目标 / 父任务 / 优先级·类型 / context（展开为 bullet）
+ * 3. **里程碑序列**（可变化）
+ * 4. **过程信息 list**（可变化）
+ * 5. **progress 百分比**（最后一块）
+ *
+ * ★ 所有内容都是 markdown 可渲染文本，不出现 JSON 原文。
+ */
+export declare function buildTaskCard(opts: {
+    status: CardStatus;
+    meta: TaskMeta;
+    milestones?: Milestone[];
+    processSteps?: ProcessStep[];
+    progress?: number;
+    updateCount?: number;
+    spinner?: string;
+}): CardPayload;
+/**
+ * 生成"打开飞书群"的 app link（Task #4230 follow-up 修复）
+ *
+ * ★ 踩坑记录（用户实测反馈）：之前用的是
+ *   `https://applink.larkoffice.com/client/chat/chatDetail?chat_id=<oc_xxx>`
+ *   —— 这是 **Lark 国际版**域名 + 老路径，飞书客户端点进去打不开群。
+ *
+ * 正确格式（飞书客户端自己生成的就是这个，见 `lark-cli im +chat-list` 的
+ * `chat_app_link` 字段）：
+ *   `https://applink.feishu.cn/client/chat/open?openChatId=<oc_xxx>`
+ *
+ * @param chatId 飞书群 id（oc_xxx）
+ * @param base applink 基址（默认飞书；Lark 国际版租户可传 applink.larksuite.com）
+ */
+export declare function buildChatAppLink(chatId: string, base?: string): string;
+/** 默认 applink 基址（飞书） */
+export declare const DEFAULT_APP_LINK_BASE = "https://applink.feishu.cn";
+/**
+ * 构造"卡片已改投专属群"的链接卡片（Task #4230 follow-up）
+ *
+ * 为什么是卡片而不是普通消息：
+ * - 用户明确要求「旧逻辑的普通消息通知不要」；
+ * - 改投后触发群里需要一条**可点击**的入口，否则 user 不知道进展卡片去哪了。
+ *
+ * 注意：这张卡片**不携带任务进展内容**，只是一条"去哪看"的指路牌，避免把
+ * 别的 task 的进展细节塞进不属于它的群。
+ */
+export declare function buildRedirectCard(opts: {
+    taskId?: number | string;
+    taskTitle?: string;
+    targetChatId: string;
+    /** 目标群名（渲染成可点击文本；缺省显示"专属群"） */
+    targetChatName?: string;
+    reason?: string;
+}): CardPayload;
+/**
+ * 格式化耗时为人类可读文本（毫秒 → ms / s / m）
+ *
+ * 例：900 → "900ms"；6500 → "6.5s"；2000 → "2s"；120000 → "2m"
+ */
+export declare function formatDurationMs(ms: number | undefined): string;
+/**
+ * 渲染"运行栏位"区块（workflow 名 / runId / 状态 / 节点进度 / 当前节点 / 耗时 /
+ * 失败原因 / 触发输入摘要）
+ *
+ * ★ 所有内容都是 markdown 可渲染文本；触发输入经 humanizeValue 处理，绝不出现 JSON 原文。
+ */
+export declare function renderWorkflowInfoLines(meta: WorkflowMeta, extra: {
+    status: WorkflowCardStatus;
+    totalNodes?: number;
+    completedNodes?: number;
+    currentNode?: string;
+    currentNodeType?: string;
+    durationMs?: number;
+    error?: string;
+}): string[];
+/**
+ * 构造 workflow 进展卡片（Card 2.0 schema，复用 task 卡片骨架）
+ *
+ * 布局（与 task 卡片对齐）：
+ * 1. header.title = 🔄 Workflow 实时更新（<workflow 名>）
+ * 2. **运行栏位**：工作流 / Run ID / Workflow ID / 状态 / 节点进度 / 当前节点 / 耗时 / 失败原因 / 触发输入
+ * 3. **🎯 里程碑序列**
+ * 4. **🔧 过程信息**
+ * 5. **📊 进度**（最后一块；completed 强制 100%）
+ */
+export declare function buildWorkflowCard(opts: {
+    status: WorkflowCardStatus;
+    meta: WorkflowMeta;
+    milestones?: Milestone[];
+    processSteps?: ProcessStep[];
+    progress?: number;
+    completedNodes?: number;
+    totalNodes?: number;
+    currentNode?: string;
+    currentNodeType?: string;
+    durationMs?: number;
+    error?: string;
+    updateCount?: number;
+    spinner?: string;
+}): CardPayload;
+/**
+ * LarkCardPatchNotifier - 封装单卡片 patch 逻辑
+ */
+export declare class LarkCardPatchNotifier {
+    private readonly options;
+    private readonly mutexes;
+    private readonly states;
+    /**
+     * Part 2：workflow 卡片状态（key = messageId）
+     *
+     * 与 task 的 `states` 并列：两套卡片走**同一套** mutex / send / patch / pin /
+     * unpin 基础设施，只是渲染的卡片与自持的时间线不同。
+     */
+    private readonly workflowStates;
+    /**
+     * ★ Task #4237 修复：改投链接卡片幂等表
+     *
+     * key = `${taskId}:${targetChatId}`；同一 (task, 目标群) 只允许发一张
+     * 「任务卡片已改投专属群」卡片 —— 旧实现里两条决策路径各发一次，
+     * 触发群收到两张文案不同的改投卡片。
+     */
+    private readonly redirectsSent;
+    constructor(options?: LarkCardPatchNotifierOptions);
+    /** 取（或创建）某 messageId 的 mutex —— 不同卡片互不阻塞 */
+    private mutexFor;
+    /**
+     * 发送初始卡片 → 拿到 messageId → pin（置顶）
+     *
+     * ★ Task #4230：pin 用 `im pins create --data '{"message_id":...}'`（旧实现传
+     *   `--chat-id/--message-id` 是非法 flag，导致 pin 永远失败 → 用户"还是没有 pin"）。
+     */
+    startTask(opts: StartTaskOptions): Promise<StartTaskResult>;
+    /**
+     * 在"触发群"发一条**链接卡片**，告知任务进展卡片已改投本 task 的专属群
+     *
+     * Task #4230 follow-up：当触发群被判定为"别的 task 的专属群"时，卡片不会
+     * 再落在触发群（避免跨任务污染），但 user 需要知道去哪里看 → 这里补一张
+     * 不含任务进展内容的指路卡片。
+     *
+     * 失败非致命（触发群里发不出去不影响主流程）。
+     */
+    sendRedirectNotice(opts: RedirectNoticeOptions): Promise<boolean>;
+    /**
+     * Patch 同一卡片（状态/进度/当前步骤 + 累积里程碑与过程时间线）
+     *
+     * ★ Task #4230：patch 用 `im messages patch --data '{"content":"<card JSON>"}'`
+     *   （旧实现传 `--content` 是非法 flag → 秒失败 → 卡片永远停在初始态）。
+     */
+    updateTask(opts: UpdateTaskOptions): Promise<void>;
+    /**
+     * 完成任务：patch final status（终态里程碑 → 进度 100%）+ unpin
+     *
+     * ★ Task #4230：unpin 需要 `--yes`（`im pins delete` 是 high-risk-write，
+     *   旧实现漏了 --yes → unpin 静默失败）。
+     */
+    finishTask(opts: FinishTaskOptions): Promise<void>;
+    /**
+     * ★ Task #4339：只更新卡片的任务元信息（meta），**保留**已累积的
+     * 里程碑 / 过程时间线 / 进度 / 更新次数。
+     *
+     * 用途：用户在卡片顶部点「为这个任务建群 / 解散该群」后，按钮需要翻面、
+     * 群链接需要出现/隐藏，但**不能**把这张卡片的进展历史冲掉。
+     *
+     * 旧实现（handler 里裸调 `buildTaskCard` 只塞 1 条 "Task 创建" 里程碑）的
+     * 后果：用户点一下按钮，卡片就退回"初始态"，之前几十次进展更新全没了。
+     *
+     * ★ 同时**会**同步更新内部 `state.meta` —— 否则下一次 `updateTask`
+     *   会用旧 meta 重建卡片，把刚显示的群链接又抹掉。
+     *
+     * @param opts.clearPerTaskChat 「解散群」时必须传 true：
+     *        `mergeTaskMeta` 会跳过 undefined/"" 值，**无法**用它清除字段，
+     *        所以这里显式 delete 掉 `perTaskChatId` / `perTaskChatName`。
+     * @returns 可直接提交给飞书 patch 的卡片；返回 `undefined` 表示本 notifier
+     *          没有该 messageId 的状态（进程重启 / 卡片不是本 notifier 发的），
+     *          caller 需自行 fallback 构建。
+     */
+    updateMetaAndBuildCard(messageId: string, meta: TaskMeta, opts?: {
+        clearPerTaskChat?: boolean;
+    }): CardPayload | undefined;
+    /** 诊断：当前跟踪中的卡片数（测试/自检用） */
+    trackedCardCount(): number;
+    /** 诊断：当前跟踪中的 workflow 卡片数（测试/自检用） */
+    trackedWorkflowCardCount(): number;
+    /**
+     * 发送 workflow 初始卡片 → 拿到 messageId → pin（置顶）
+     *
+     * 与 {@link startTask} 同构：同样的 send 参数契约、同样的 pin 参数契约、
+     * 同样的"pin 失败非致命"语义。差别只在渲染的是 workflow 卡片。
+     */
+    startWorkflow(opts: StartWorkflowOptions): Promise<StartTaskResult>;
+    /**
+     * Patch 同一张 workflow 卡片（状态/进度/当前节点 + 累积里程碑与过程时间线）
+     *
+     * 与 {@link updateTask} 同构（mutex 串行化、时间线 append+去重、spinner 轮换）。
+     */
+    updateWorkflow(opts: UpdateWorkflowOptions): Promise<void>;
+    /**
+     * 结束 workflow：patch 终态（completed 绿 / failed 红 / stopped 灰）→ unpin → 清理跟踪
+     *
+     * 与 {@link finishTask} 同构：终态里程碑 append、completed 强制 100%、
+     * unpin 非致命、最后清理内存（避免泄漏）。
+     */
+    finishWorkflow(opts: FinishWorkflowOptions): Promise<void>;
+    /**
+     * 构建 `im +messages-send` 的 args（卡片模式）
+     *
+     * 关键点（官方 lark-cli 文档 + 2026-10-15 tongzhuli profile 实测）：
+     * - --msg-type interactive
+     * - --content 是 **card JSON 字符串**（不包裹 {"content": "..."}）
+     *   - post 格式才用 {"zh_cn":{"content":[[{"tag":"md","text":"..."}]]}} 包裹
+     *   - interactive 卡片直接传 card JSON（header + body）
+     *   - 误用 post 格式 → 飞书 API 报错 code 230099 / ext 200621 "parse card json err"
+     * - --as bot（否则用 user 身份，bot 才能在群里发卡片）
+     * - profile 注入到 args 头部
+     */
+    buildSendCardArgs(opts: {
+        chatId: string;
+        profile?: string;
+        card: CardPayload;
+    }): string[];
+    /**
+     * 构建 `im messages patch` 的 args
+     *
+     * ★ Task #4230 修复：patch **只**接受 `--data '{"content":"<card JSON 字符串>"}'`。
+     *   传 `--content` 会报 `unknown flag "--content"`（秒失败）→ 卡片永远不更新。
+     *   content 必须是 **JSON 序列化后的字符串**（second stringify）。
+     */
+    buildPatchCardArgs(opts: {
+        messageId: string;
+        profile?: string;
+        card: CardPayload;
+    }): string[];
+    /**
+     * 构建 `im pins create` 的 args（置顶卡片）
+     *
+     * ★ Task #4230 修复：pins create **只**接受 `--data '{"message_id":"om_xxx"}'`。
+     *   旧实现传 `--chat-id/--message-id` → `unknown flag "--chat-id"` → pin 永远失败。
+     */
+    buildPinArgs(opts: {
+        messageId: string;
+        profile?: string;
+    }): string[];
+    /**
+     * 构建 `im pins delete` 的 args（取消置顶）
+     *
+     * ★ Task #4230 修复：pins delete 是 high-risk-write，**必须**带 `--yes`，
+     *   否则 lark-cli 拒绝执行 → unpin 静默失败。
+     */
+    buildUnpinArgs(opts: {
+        messageId: string;
+        profile?: string;
+    }): string[];
+    /**
+     * 调 lark-cli（spawn）并把 args/exit code 记进 span
+     *
+     * ★ Task #4230：加上 @TracedAs，让 `debug trace` 能直接看到
+     *   send/patch/pin/unpin 每一步的真实 args + 退出码（旧版这些内部方法没有
+     *   span，patch 失败只能在日志里翻，trace 树断在 lark-cli-task-notify.execute）。
+     */
+    private runLarkCli;
+    /**
+     * 从 lark-cli +messages-send 响应里提取 message_id
+     *
+     * 响应格式：{"ok": true, "data": {"message_id": "om_xxx"}}
+     */
+    private extractMessageId;
+}