dsh-im-union 0.4.8 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,76 @@
 
 本项目版本号遵循语义化版本；发布面与宿主兼容矩阵见 `scripts/hosts.mjs`（README 管理块同源）。
 
+## 0.5.0（QQ 渠道能力补齐：出站图片 / Markdown / 入站图片文件 / 审批按钮 / 群管理）
+
+对照 `_ref-im/dsh-qqbot`（同一套 QQ 官方 api-v2）逐面解锁 `src/channels/qq.ts`，遵守净室 / 零运行时依赖 / D7 纪律。
+
+### Added
+
+- **出站图片 `caps.fileOut` + `sendFile`**：上传换 file_info → msg_type=7 携带 **`media: { file_info }`**（体形按官方 `@tencent-connect/qqbot-nodejs` 1.0.5 `sendMediaMessage` 对账，非旧式 `image: file_info`）；上传采用**双形态递降**：先官方 SDK 小文件形态（JSON + base64 `file_data`，`file_type=1`、`srv_send_msg=false`），被平台确定性拒绝再回退官方文档记载的 multipart/form-data 形态一次（网络不确定绝不重试，D7 免白占配额）；群/单聊分 `/files` 端点，窗口内带 msg_id/seq；一举激活网关 SVG→PNG 附图链、产物回传与 `/export`。非图片 mime（zip/文件）优雅拒绝（官方 file_type=4 未开放）；304080/40093002 确定性转译
+- **Markdown 出站 msg_type=2**：正文含 `![` 图片内嵌或 `qqbot-media://` 时走 markdown 通道；被平台确定性拒绝（如 304036 无模板权限）自动降级纯文本重发一次
+- **Markdown 内联本地图片自动上传（task_8）**：新增 `QqAdapter.uploadMarkdownImage`（3 步 `/v2/media-images`：prepare→COS 直传→complete，sha256 内容指纹去重、10MB 上限），gateway 投递前将正文 `![](本地路径)` 经宿主 `workspaceFiles` 受管读（workspaceRoot 限定，适配器不碰盘）取字节上传、回替 `qqbot-media://` url；非 QQ/无本地图/读失败/上传失败均原样保留
+- **入站图片/文件 `caps.imageIn/fileIn`**：事件 `attachments[].url`（rkey 时效）即时下载填 `images[]/files[]`（含 mimeType）；群聊图片 content_type 实测为 'file' → 兼用 URL 形态判定；无 arrayBuffer/非 2xx/空字节按占位不丢事件；入站派发改串行链保序（异步下载不打乱消息顺序）
+- **审批/提问按钮 `askChoices`（keyboard）**：msg_type=2 + **`keyboard: { content: { rows } }`**（官方 InlineKeyboard 包装层，少一层平台不渲染），action.type=1 回传；收到 INTERACTION_CREATE 后**best-effort `PUT /interactions/{id} {code:0}` 上确认**再结算；D5 仅接受发起者点按；`config.keyboard=on` 才订阅 INTERACTION intent 并置 `nativeChoices=true`（默认关=零风险，未配置回退数字菜单）
+- **语音入站免解码**：优先取事件原生 `asr_refer_text` 作正文，无则占位；不引入 silk 解码依赖
+- **QQ 群管理**：新建 `src/channels/qq-group-admin.ts`（FEATURE_GATES 门控 + 端点/错误码人话映射），QqAdapter 暴露入群申请列表/审批、群禁言查询/设置、消息撤回；经 `/qq` 命令面可达，仅群聊、作用于本群、需 `config.groupAdminUsers` 授权名单（空=命令惰性拒绝）+ 机器人为群管理员
+
+### Notes
+
+- 撤回/编辑 `editStream`、原生流式 `nativeStream` 本轮不做（协议语义未逐面核实、与 dsh-qqbot 打平）
+- 全量 753 单测绿（QQ +8）；真机农场冒烟需 QQ 凭据待验
+
+## 0.4.12（飞书审批卡片：权限 ask 走按钮确认）
+
+### Added
+
+- **飞书 `askChoices` 实装（本插件第一个真按钮面渠道）**：宿主审批（T1.9）不只能回「1/2/c」文本，而是直接收到一张带「允许一次 / 拒绝」按钮的卡片，点按钮即定夺。`caps.nativeChoices` 由 false 改 true（此前所有渠道都是 false 或缺面，飞书是第一个把这条分支跑通的）
+- **协议事实（真机实测，写进代码注释）**：飞书 2.0 schema 的 `body.elements` **已不支持 `action` 标签**（`230099 / 200861 unsupported tag action`），按钮卡片必须走 1.0 形态（顶层 `elements` + `action`/`button`）；而内联 `interactive` 消息不碰 cardkit 实体面，**不需要 `cardkit:card:write`**（与流式卡片不同一条权限链）
+- **回传走同一条长连接**：`EventDispatcher` 注册 `card.action.trigger`（官方 SDK 1.76 自带该分发 + 按 chatId 去重/加锁/排队），无需另开 webhook；回包给 `toast` 让用户看到「已记录：拒绝」
+
+### Fixed
+
+- **按钮期间用户打字会被当成新任务丢给模型**：原 `handleApproval` 的按钮分支是直接 `await adapter.askChoices(...)`，期间**不登记 pending**，所以用户习以为常地回一句「可以」会落进会话队列。现改为**按钮 + 文本双路竞速**（`approvalViaButtons`）：卡片在位时「1/2/c」同样定夺，先到为准
+- **按钮面无渠道侧超时**：适配器 `askChoices` 自带 5 分钟上限（与 D5 对齐）+ `signal` abort 即收；`disconnect()` 释放所有在位卡片（空答=取消，fail-closed）
+
+### Changed
+
+- `askChoices` 契约加第 6 个可选参 `opts.ownerUserId`：卡片回传带的是点击者身份，需比对发起者才能守 D5（**只有发起者能定夺**，他人点击不改判，只回 toast 说明）
+- 飞书 `multi=true` 明确拒接（卡片无多选原语）：抛错后 broker 回落文本菜单，不造假成单选
+- 迟到的重复点按（卡还在、pending 已清）一律忽略；审批卡按 `message_id` 键控，同聊天先后两张卡不会串台
+
+## 0.4.11（回合内「处理中」信号 — 引擎接线 + 飞书表情落地）
+
+### Added
+
+- **引擎侧第一次真正调 `setTyping`**：`runTurn` 在 prompt 前发回合开始信号（`caps.typing` 位 + `setTyping` 方法双门控）。此前 Discord/Telegram/Matrix/QQ/微信 六个适配器都实现了 `setTyping`，但引擎侧**零调用点**——它们全是死代码；这次一并激活
+- **飞书「处理中」落地为表情回应**：飞书无 typing API（客户端不暴露），实测 `POST/DELETE /open-apis/im/v1/messages/{id}/reactions` 全链 `code 0`，因此在用户本条入站消息上贴 `OnIt`（官方「需处理/进行中」语义）：回合开始贴、回复/卡片落定即删、没删成 2 分钟 TTL 自清；同一聊天只留一个；表情接口缺权/限频/消息被撕一律静默，不阻断回合
+- 飞书 `caps.typing` / `caps.statusReaction` 由 false 改 true（声明=真实现：两个位同一个落地物）
+
+### Changed
+
+- 入站接收时记住 `chatId → message_id`（状态位锚点）；状态位仅沾在用户那条消息上，不额外发一条「思考中…」占位消息，不污染会话历史
+
+## 0.4.10（多回合接续：同一聊天不得被劈成两条轨迹）
+
+### Fixed
+
+- **飞书第二回合另起会话，轨迹分叉（真机 desktop 实证）**：`apply` 期会话后端是 `none`，首回合入站时 `ensureSessionId` 直接返回隐式 id（`im:union:feishu:dm:oc_…`）——宿主按该 id 落了盘（目录 `im~003Aunion…`）；惰性后端随后升级 `native`，第二回合就调 `createSession(hint)`，而 desktop 线 `sessionController.create` 面缺位 → 回退 `agents.create`（不收 sessionId）→ 宿主生成 `session-uuid`，`router.bind` 改绑到 UUID。结果同一聊天被劈成两段：首段在 `im:union:` 目录（进「频道」分组），第二段在 `session-uuid` 目录（落「未分组」），jsonl 各写各的
+- **修法（先查后建）**：`ensureSessionId` 在 `createSession` 之前先查宿主会话列表，已有该 `im:union:` id 则直接接续（不 create、不重复应用账号偏好——存量会话不动）；命中后进进程内缓存，后续回合不重复查。查询面异常/缺位按「未存在」处理，仍走 create 兜底
+- **可操作的排障日志**：宿主改派成非 `im:` 前缀 id（会落「未分组」）时，除既有「请求 id → 宿主实际 id」info，另打一条 warn 给出 `/session <原隐式 id>` 的接回手段；不再只留一条 id 差异让人猜
+
+## 0.4.9（飞书诊断假红收口 + 可选密钥不再算缺失）
+
+### Fixed
+
+- **飞书「凭据无效」假红（真机 desktop 实证）**：`diagnose` 凭据位探的是 `GET /open-apis/bot/v2/info`——该路径不存在（服务端回 `404 page not found` 纯文本，SDK 对非 2xx 直接抛），于是任何正确凭据都落 catch 分支报「凭据或网络无效」。现改探 `POST /open-apis/auth/v3/tenant_access_token/internal`（唯一对 appSecret 做真裁决的面：错 secret → 10014），并把「机器人能力」拆成独立位 `bot-ability`（`GET /open-apis/bot/v3/info`：有 bot → code 0；无 bot → 11205）——bot 面本身不校验 secret（错 secret 同样回 11205），探它只能验能力不能验凭据
+- **「长连接通过」不再被误读为可收发**：`ws-long-connection` 置 passed 时附提示「长连接已建立（不能据此推定机器人能力/消息权限已开通）」——无机器人能力时事件不投递、消息发不出，与长连接握手是两件事
+- **可选密钥被算成「凭据缺失」**：`listPublic` 对 meta 里所有 `secret:true` 字段一律下发 `configured`，设置页据此把未入库的**可选**键（飞书 `dashScopeKey` 语音、微信 `botToken` 扫码自动写）标成红徽标「凭据缺失：…」，观感上等同连接被阻断。现 `secretFields` 随字段下发 `required`，客户端只对 `required!==false` 的缺失出红徽标
+
+### Changed
+
+- 诊断 hint 不再一律「凭据或网络无效」：网络类错误回「网络不可达：<message>」，其余回「凭据探测失败：<message>」（只取 error.message，不透传 axios config——那里带着 Authorization 与请求体）
+
 ## 0.4.8（宿主枚举补票：0.2.1-rc.3）
 
 ### Changed

package/client.js

@@ -785,7 +785,8 @@ select.diu-input { appearance: auto; }
 
       var missingSecrets = [];
       (row.secretFields || []).forEach(function (sf) {
-        if (!sf.configured) missingSecrets.push(sf.key);
+        // 可选密钥（语音 DashScope Key / 扫码 botToken）未入库不算缺失：不进红徽标。
+        if (!sf.configured && sf.required !== false) missingSecrets.push(sf.key);
       });
       var badge = row.paused
         ? h(Tag, { tone: 'Muted' }, t('accounts.state.paused'))

package/dsh.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dsh-im-union",
   "name": "dsh-im-union",
-  "version": "0.4.8",
+  "version": "0.5.0",
   "description": {
     "en": "Union IM bridge for DeepSeek Harness: multi-account bots across messaging platforms, each chat bound to its own session, with cross-host-version compatibility (0.1.2-rc.1 .. 0.2.1-rc.3).",
     "zh": "DeepSeek Harness 的 IM 联合桥：多平台多账号机器人、每个聊天绑定独立会话，跨宿主版本兼容（0.1.2-rc.1 至 0.2.1-rc.3）。"

package/lib/channels/feishu.d.ts

@@ -63,6 +63,25 @@ interface FeishuUploadResult {
 interface FeishuResourceResult {
     getReadableStream?: () => AsyncIterable<Uint8Array>;
 }
+/** 卡片回传事件（card.action.trigger）归一后的形——SDK 长连接与 webhook 两形态共用。 */
+export interface FeishuCardAction {
+    messageId: string;
+    chatId: string;
+    operator: {
+        openId?: string;
+        userId?: string;
+    };
+    action: {
+        value?: Record<string, unknown>;
+    };
+}
+/**
+ * 从 card.action.trigger 负载取关键字段。两种形态都要接：
+ * - 长连接/webhook 原始体：`{schema:'2.0', header:{event_type}, event:{context, operator, action}}`；
+ * - SDK 安全管道 normalize 后的形：`{messageId, chatId, operator:{openId}, action:{value}}`。
+ * 缺关键字段回 undefined（调用方丢弃，不猜）。
+ */
+export declare function extractCardAction(payload: any): FeishuCardAction | undefined;
 export interface LarkLike {
     WSClient: new (options: {
         appId: string;
@@ -73,7 +92,7 @@ export interface LarkLike {
         }) => Promise<void> | void;
     };
     EventDispatcher: new (options: Record<string, unknown>) => {
-        register: (handlers: Record<string, (data: FeishuEventPayload) => Promise<void> | void>) => unknown;
+        register: (handlers: Record<string, (data: any) => unknown>) => unknown;
     };
     Client: new (options: {
         appId: string;
@@ -202,13 +221,22 @@ export declare class FeishuAdapter implements ChannelAdapter {
     /** 语音档位（未开启=undefined：入站只留占位，零外部调用）。 */
     private readonly voice;
     private tenantToken;
+    /** chatId → 最近一条入站消息 id（typing 状态位挂在用户那条消息上）。 */
+    private readonly lastInboundMessageId;
+    /** chatId → 在位「处理中」表情（回复落地/超时回收）。 */
+    private readonly typingReactions;
     private listeners;
     private client;
     private wsClient;
     private lark;
     private readonly log;
     /** 事件处理器表（测试注入口：直接驱动 receive handler）。 */
-    handlers: Record<string, (data: FeishuEventPayload) => Promise<void> | void> | undefined;
+    handlers: Record<string, (data: any) => unknown> | undefined;
+    /**
+     * 在位的选项卡：message_id → 待答。
+     * 键用 message_id 而非 chatId：一个聊天可能先后出多张卡，旧卡迟到点击不得误判新卡。
+     */
+    private readonly pendingChoices;
     constructor(options: FeishuAdapterOptions);
     onMessage(listener: MessageListener): () => void;
     private requireLark;
@@ -219,6 +247,33 @@ export declare class FeishuAdapter implements ChannelAdapter {
     /** 权限类错误码 → 可读引导（不透传内部错误体）。 */
     private translateApiError;
     reply(address: ChatAddress, text: string): Promise<Receipt>;
+    /**
+     * 回合开始「处理中」信号（引擎在 prompt 前调用）。飞书无 typing API，落地为
+     * 给用户本条入站消息加 OnIt 表情；同一聊天只留一个，回复落地/2 分钟超时自清。
+     * 任一环节失败一律静默——这是增强项，不得阻断回合。
+     */
+    setTyping(address: ChatAddress): Promise<void>;
+    /** 回收「处理中」表情（重复调用幂等）。 */
+    private clearTyping;
+    /**
+     * 审批/选项确认卡片（T1.9 按钮面）。
+     * 协议事实（真机实测）：2.0 schema 的 `body.elements` 已不支持 `action` 标签
+     * （230099 / 200861 unsupported tag action），按钮只能走 1.0 形态（顶层 elements）；
+     * 内联 interactive 消息不碰 cardkit 实体面，因此不需要卡片实体权限。
+     * multi=true 不接（卡片无多选原语）：抛错由 broker 回落文本菜单，不造假。
+     */
+    askChoices(address: ChatAddress, question: string, options: readonly string[], multi: boolean, signal?: AbortSignal, opts?: {
+        ownerUserId?: string;
+    }): Promise<{
+        answer: string;
+        uncertain: boolean;
+    }>;
+    /**
+     * 卡片按钮点击回传（card.action.trigger，长连接同一条通道）。
+     * D5 纪律：只有发起者能定夺，他人点击不改判；超时/pending 已清则忽略。
+     * 回包给 toast（飞书卡片回调响应），让用户看到「已记录」。
+     */
+    private handleCardAction;
     /**
      * 出站文件（T2.4）：im.v1.file.create（file_type=stream）→ im.v1.message.create
      * （msg_type=file, content.file_key）。限额：引擎 FILE_BUDGET 在上游已裁（20 MiB ≤ 4），
@@ -257,12 +312,26 @@ export declare class FeishuAdapter implements ChannelAdapter {
     speak(address: ChatAddress, text: string, _signal?: AbortSignal): Promise<Receipt>;
     /** tenant_access_token 自管（提前 60s 刷新；公开协议 auth/v3/internal）。 */
     private token;
+    /** 通用 REST（带 tenant token）：「处理中」表情等非卡片面共用。 */
+    private rest;
     private cardApi;
     /** 开流：建卡片实体（streaming_mode 开）→ interactive 消息引用 card_id。 */
     beginStream(address: ChatAddress): Promise<import('./types.js').ReplyStream>;
     private createCardMessage;
     authorize(): boolean | undefined;
     diagnose(): Promise<ChannelDiagnosisCheck[]>;
+    /**
+     * 凭据探测：auth/v3/tenant_access_token 换 token（唯一对 appSecret 做真裁决的面）。
+     * 曾探 `/open-apis/bot/v2/info`——该路径不存在（服务端 404 纯文本、SDK 直接抛），
+     * 任何凭据都落「凭据或网络无效」；且 bot 面本身不校验 secret（错 secret 同样回
+     * 11205），探它只能验能力不能验凭据——故拆成凭据位与机器人能力位两条。
+     */
+    private credentialsCheck;
+    /**
+     * 机器人能力探测：GET /open-apis/bot/v3/info（有 bot → code 0；无 bot → 11205）。
+     * 这是「长连接通了却收不到消息」的判定位：无机器人能力时事件不投递、消息发不出。
+     */
+    private botAbilityCheck;
     /**
      * 语音档位诊断（T3.5 三态）：
      * - 未启用（voiceEnabled 非 'true'）= unverified——能力存在但未开通，不谎报；
@@ -271,8 +340,8 @@ export declare class FeishuAdapter implements ChannelAdapter {
      * 未注入探测面时不真起进程（禁真实副作用），诚实报 unverified。
      */
     private voiceCheck;
-    /** 测试/诊断驱动：模拟一条 receive 事件（与 SDK handler 同一入口）。 */
-    injectEvent(eventName: string, payload: FeishuEventPayload): Promise<void>;
+    /** 测试/诊断驱动：模拟一条事件（与 SDK handler 同一入口）；回传 handler 的响应体。 */
+    injectEvent(eventName: string, payload: unknown): Promise<unknown>;
 }
 /**
  * 工厂挂 registry（懒加载动态 import SDK 面）。语音档位全配置驱动、默认关：

package/lib/channels/feishu.js

@@ -3,12 +3,63 @@ const MAX_MESSAGE_LENGTH = 4000;
 const OPEN_BASE = 'https://open.feishu.cn';
 const STREAM_ELEMENT_ID = 'imu_stream';
 const CARD_UPDATE_THROTTLE_MS = 1_500;
+/**
+ * 回合内「处理中」信号：飞书无 typing API（客户端不暴露），用**入站消息的表情回应**
+ * 当状态位——实测 POST/DELETE /im/v1/messages/{id}/reactions 全链 code 0。
+ * OnIt = 官方「需处理/进行中」语义；回复落地或超时即删，不污染历史。
+ */
+const TYPING_EMOJI = 'OnIt';
+const TYPING_TTL_MS = 120_000;
+/**
+ * 卡片按钮回传（审批确认）等待上限：与宿主审批红线 D5 的 5 分钟对齐。
+ * 适配器自己必须定时：broker 的按钮分支是直接 `await askChoices(...)`，
+ * 不挂它自己的超时——没人点又不能永久悬挂。
+ */
+const CHOICE_TIMEOUT_MS = 5 * 60 * 1000;
 /** 开发者后台「批量导入权限」模板（权限补全引导， diagnose 附送）。 */
 export const FEISHU_PERMISSION_TEMPLATE = JSON.stringify({
     scopes: ['im:message', 'im:message:send_as_bot', 'im:chat', 'im:resource', 'cardkit:card:write'],
 }, null, 2);
 /** 无权限类平台错误码（发消息/读事件常见）。 */
 const PERMISSION_ERROR_CODES = new Set([99991672, 2300024, 230027, 99991668]);
+/** 凭据类错误码：auth/v3/tenant_access_token 对 appId/appSecret 的直接裁决。 */
+const CREDENTIAL_ERROR_CODES = new Set([10003, 10013, 10014]);
+/** 机器人能力未开通（bot/v3/info 回 11205，im 面回 232025）。 */
+const BOT_ABILITY_MISSING_CODES = new Set([11205, 232025]);
+/**
+ * 从 card.action.trigger 负载取关键字段。两种形态都要接：
+ * - 长连接/webhook 原始体：`{schema:'2.0', header:{event_type}, event:{context, operator, action}}`；
+ * - SDK 安全管道 normalize 后的形：`{messageId, chatId, operator:{openId}, action:{value}}`。
+ * 缺关键字段回 undefined（调用方丢弃，不猜）。
+ */
+export function extractCardAction(payload) {
+    if (payload === null || typeof payload !== 'object')
+        return undefined;
+    const nested = payload.event !== null && typeof payload.event === 'object' ? payload.event : payload;
+    const ctx = nested.context !== null && typeof nested.context === 'object' ? nested.context : {};
+    const messageId = typeof nested.messageId === 'string' ? nested.messageId
+        : typeof ctx.open_message_id === 'string' ? ctx.open_message_id
+            : typeof nested.open_message_id === 'string' ? nested.open_message_id : undefined;
+    const chatId = typeof nested.chatId === 'string' ? nested.chatId
+        : typeof ctx.open_chat_id === 'string' ? ctx.open_chat_id
+            : typeof nested.open_chat_id === 'string' ? nested.open_chat_id : undefined;
+    if (messageId === undefined || chatId === undefined)
+        return undefined;
+    const operator = (nested.operator ?? {});
+    const action = (nested.action ?? {});
+    const value = action.value !== null && typeof action.value === 'object' ? action.value : undefined;
+    return {
+        messageId,
+        chatId,
+        operator: {
+            ...(typeof operator.openId === 'string' ? { openId: operator.openId } : {}),
+            ...(typeof operator.open_id === 'string' ? { openId: operator.open_id } : {}),
+            ...(typeof operator.userId === 'string' ? { userId: operator.userId } : {}),
+            ...(typeof operator.user_id === 'string' ? { userId: operator.user_id } : {}),
+        },
+        action: { ...(value === undefined ? {} : { value }) },
+    };
+}
 /** 网络类错误判定（结果不明）——与确定性平台拒收分档。 */
 function isNetworkLike(error) {
     return error instanceof Error && /网络|timeout|timed out|unreachable|socket|ECONN|fetch/i.test(error.message);
@@ -83,6 +134,10 @@ export class FeishuAdapter {
     /** 语音档位（未开启=undefined：入站只留占位，零外部调用）。 */
     voice;
     tenantToken;
+    /** chatId → 最近一条入站消息 id（typing 状态位挂在用户那条消息上）。 */
+    lastInboundMessageId = new Map();
+    /** chatId → 在位「处理中」表情（回复落地/超时回收）。 */
+    typingReactions = new Map();
     listeners = [];
     client;
     wsClient;
@@ -90,6 +145,11 @@ export class FeishuAdapter {
     log;
     /** 事件处理器表（测试注入口：直接驱动 receive handler）。 */
     handlers;
+    /**
+     * 在位的选项卡：message_id → 待答。
+     * 键用 message_id 而非 chatId：一个聊天可能先后出多张卡，旧卡迟到点击不得误判新卡。
+     */
+    pendingChoices = new Map();
     constructor(options) {
         this.options = options;
         if (typeof options.appId !== 'string' || options.appId === '' || typeof options.appSecret !== 'string' || options.appSecret === '') {
@@ -123,9 +183,10 @@ export class FeishuAdapter {
         this.caps = {
             editStream: false,
             nativeStream: this.cardMode === 'card',
-            nativeChoices: false,
-            statusReaction: false,
-            typing: false,
+            nativeChoices: true,
+            // typing 落地=表情回应（无平台 typing API）；两者同源，故一起声明。
+            statusReaction: true,
+            typing: true,
             imageIn: false,
             fileIn: true,
             fileOut: true,
@@ -156,6 +217,10 @@ export class FeishuAdapter {
                 const message = normalizeFeishuMessage(data);
                 if (message === undefined)
                     return;
+                // 「处理中」状态位锚点：后面 setTyping 用它给用户这条消息贴 OnIt。
+                const inboundId = data?.message?.message_id;
+                if (typeof inboundId === 'string' && inboundId !== '')
+                    this.lastInboundMessageId.set(message.address.chatId, inboundId);
                 // 入站文件下载（T2.4）：失败降级为无附件，不丢整条。
                 await this.fillFiles(message, data?.message);
                 // 入站语音转写（T3.5）：失败回占位文案，同样不丢整条。
@@ -163,6 +228,8 @@ export class FeishuAdapter {
                 for (const listener of this.listeners)
                     listener(message);
             },
+            // 卡片按钮回传（审批确认）：长连接下飞书把 card.action.trigger 推同一条连接。
+            'card.action.trigger': async (data) => this.handleCardAction(data),
         };
         const dispatcher = new lark.EventDispatcher({}).register(this.handlers);
         await this.wsClient.start({ eventDispatcher: dispatcher });
@@ -171,6 +238,12 @@ export class FeishuAdapter {
     async disconnect() {
         this.connected = false;
         this.wsClient = undefined;
+        // 拆除即释放所有在位选项卡（空答=取消，fail-closed，不伪装批准）。
+        for (const [, pending] of [...this.pendingChoices]) {
+            clearTimeout(pending.timer);
+            pending.resolve('');
+        }
+        this.pendingChoices.clear();
     }
     async sendMessagePayload(address, msgType, content) {
         const client = this.client;
@@ -213,8 +286,147 @@ export class FeishuAdapter {
         return new Error(`feishu: 平台拒绝请求（code ${code}）`);
     }
     async reply(address, text) {
+        // 回复即收轮：先回收「处理中」状态位（失败不影响投递）。
+        void this.clearTyping(address);
         return this.createMessage(address, text);
     }
+    /**
+     * 回合开始「处理中」信号（引擎在 prompt 前调用）。飞书无 typing API，落地为
+     * 给用户本条入站消息加 OnIt 表情；同一聊天只留一个，回复落地/2 分钟超时自清。
+     * 任一环节失败一律静默——这是增强项，不得阻断回合。
+     */
+    async setTyping(address) {
+        const messageId = this.lastInboundMessageId.get(address.chatId);
+        if (messageId === undefined)
+            return;
+        await this.clearTyping(address);
+        try {
+            const data = await this.rest('POST', `/open-apis/im/v1/messages/${messageId}/reactions`, {
+                reaction_type: { emoji_type: TYPING_EMOJI },
+            });
+            const reactionId = data.reaction_id;
+            if (typeof reactionId !== 'string' || reactionId === '')
+                return;
+            this.typingReactions.set(address.chatId, { messageId, reactionId });
+            const timer = setTimeout(() => void this.clearTyping(address), TYPING_TTL_MS);
+            timer.unref?.();
+        }
+        catch {
+            // 表情权限缺位/限频：静默，不影响回合。
+        }
+    }
+    /** 回收「处理中」表情（重复调用幂等）。 */
+    async clearTyping(address) {
+        const pending = this.typingReactions.get(address.chatId);
+        if (pending === undefined)
+            return;
+        this.typingReactions.delete(address.chatId);
+        try {
+            await this.rest('DELETE', `/open-apis/im/v1/messages/${pending.messageId}/reactions/${pending.reactionId}`);
+        }
+        catch {
+            // 消息被撤回/表情已被手动移除：无需处理。
+        }
+    }
+    /**
+     * 审批/选项确认卡片（T1.9 按钮面）。
+     * 协议事实（真机实测）：2.0 schema 的 `body.elements` 已不支持 `action` 标签
+     * （230099 / 200861 unsupported tag action），按钮只能走 1.0 形态（顶层 elements）；
+     * 内联 interactive 消息不碰 cardkit 实体面，因此不需要卡片实体权限。
+     * multi=true 不接（卡片无多选原语）：抛错由 broker 回落文本菜单，不造假。
+     */
+    async askChoices(address, question, options, multi, signal, opts) {
+        const client = this.client;
+        if (client === undefined)
+            throw new Error('feishu: 客户端未初始化（先 connect）');
+        if (multi)
+            throw new Error('feishu: 多选无卡片原语（回落文本菜单）');
+        const labels = options.map((option) => String(option)).filter((label) => label !== '');
+        if (labels.length === 0)
+            throw new Error('feishu: 选项为空');
+        const card = {
+            config: { wide_screen_mode: true },
+            header: { title: { tag: 'plain_text', content: '需要确认' } },
+            elements: [
+                { tag: 'div', text: { tag: 'lark_md', content: question } },
+                {
+                    tag: 'action',
+                    actions: labels.map((label, index) => ({
+                        tag: 'button',
+                        text: { tag: 'plain_text', content: label },
+                        type: index === 0 ? 'primary' : 'default',
+                        value: { imu: 'choice', label },
+                    })),
+                },
+            ],
+        };
+        const response = await client.im.message.create({
+            params: { receive_id_type: 'chat_id' },
+            data: { receive_id: address.chatId, msg_type: 'interactive', content: JSON.stringify(card) },
+        });
+        if (typeof response?.code === 'number' && response.code !== 0)
+            throw this.translateApiError(response.code, response.msg);
+        const messageId = typeof response?.message_id === 'string' ? response.message_id : undefined;
+        if (messageId === undefined)
+            throw new Error('feishu: 交互卡片未返回 message_id');
+        return new Promise((resolveOuter) => {
+            let done = false;
+            const onAbort = () => settle('');
+            const settle = (answer) => {
+                if (done)
+                    return;
+                done = true;
+                const held = this.pendingChoices.get(messageId);
+                if (held !== undefined) {
+                    clearTimeout(held.timer);
+                    this.pendingChoices.delete(messageId);
+                }
+                if (signal !== undefined)
+                    signal.removeEventListener('abort', onAbort);
+                // 卡片已确定发出，后续任何结果（点/超时/取消/撤回）都是确定性的。
+                resolveOuter({ answer, uncertain: false });
+            };
+            if (signal !== undefined) {
+                if (signal.aborted) {
+                    settle('');
+                    return;
+                }
+                signal.addEventListener('abort', onAbort, { once: true });
+            }
+            const timer = setTimeout(() => settle(''), CHOICE_TIMEOUT_MS);
+            timer.unref?.();
+            this.pendingChoices.set(messageId, {
+                labels,
+                ownerUserId: opts?.ownerUserId,
+                resolve: settle,
+                timer,
+            });
+        });
+    }
+    /**
+     * 卡片按钮点击回传（card.action.trigger，长连接同一条通道）。
+     * D5 纪律：只有发起者能定夺，他人点击不改判；超时/pending 已清则忽略。
+     * 回包给 toast（飞书卡片回调响应），让用户看到「已记录」。
+     */
+    async handleCardAction(payload) {
+        const evt = extractCardAction(payload);
+        if (evt === undefined)
+            return undefined;
+        const pending = this.pendingChoices.get(evt.messageId);
+        if (pending === undefined)
+            return undefined;
+        const owner = pending.ownerUserId;
+        if (owner !== undefined && evt.operator.openId !== owner && evt.operator.userId !== owner) {
+            return { toast: { type: 'info', content: '该请求只接受发起者的答复' } };
+        }
+        const raw = evt.action.value?.label;
+        const label = typeof raw === 'string' ? raw : '';
+        if (!pending.labels.includes(label)) {
+            return { toast: { type: 'error', content: '未能识别该按钮，请用文本回复' } };
+        }
+        pending.resolve(label);
+        return { toast: { type: 'success', content: `已记录：${label}` } };
+    }
     /**
      * 出站文件（T2.4）：im.v1.file.create（file_type=stream）→ im.v1.message.create
      * （msg_type=file, content.file_key）。限额：引擎 FILE_BUDGET 在上游已裁（20 MiB ≤ 4），
@@ -453,6 +665,21 @@ export class FeishuAdapter {
         this.tenantToken = { value: json.tenant_access_token, expireAtMs: Date.now() + Number(json.expire ?? 3600) * 1000 };
         return this.tenantToken.value;
     }
+    /** 通用 REST（带 tenant token）：「处理中」表情等非卡片面共用。 */
+    async rest(method, path, body) {
+        const token = await this.token();
+        const response = await this.fetchImpl(`${OPEN_BASE}${path}`, {
+            method,
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        const json = await response.json();
+        if (!response.ok || (typeof json.code === 'number' && json.code !== 0)) {
+            const code = Number(json.code ?? response.status);
+            throw new Error(`feishu: 请求失败（code ${code}：${String(json.msg ?? '')}）`);
+        }
+        return (json.data ?? {});
+    }
     async cardApi(method, path, body) {
         const token = await this.token();
         const response = await this.fetchImpl(`${OPEN_BASE}${path}`, {
@@ -517,6 +744,8 @@ export class FeishuAdapter {
                 await self.cardApi('PATCH', `/open-apis/cardkit/v1/cards/${cardId}/settings`, {
                     config: { streaming_mode: false },
                 }).catch((error) => self.log(`feishu: 关闭流式模式失败：${error.message}`));
+                // 卡片已落定 = 回合可见结果到位，「处理中」表情该收了。
+                await self.clearTyping(address);
                 return { platformMessageId: sent, uncertain: false };
             },
             abort() {
@@ -541,21 +770,14 @@ export class FeishuAdapter {
     }
     async diagnose() {
         const checks = [];
-        try {
-            if (this.client === undefined)
-                throw new Error('未连接');
-            const response = await this.client.request({ method: 'GET', url: '/open-apis/bot/v2/info' });
-            const ok = response?.code === undefined || response.code === 0;
-            checks.push({ name: 'credentials-valid', status: ok ? 'passed' : 'failed', hint: ok ? undefined : `code ${response?.code}` });
-        }
-        catch (error) {
-            checks.push({ name: 'credentials-valid', status: 'failed', hint: '凭据或网络无效，请检查 appId/appSecret' });
-        }
+        checks.push(await this.credentialsCheck());
         checks.push({
             name: 'ws-long-connection',
             status: this.connected ? 'passed' : 'unverified',
-            hint: this.connected ? undefined : '未连接',
+            // 长连接只证明握手成功：事件真投递还需机器人能力 + receive_v1 订阅。
+            hint: this.connected ? '长连接已建立（不能据此推定机器人能力/消息权限已开通）' : '未连接',
         });
+        checks.push(await this.botAbilityCheck());
         checks.push({
             name: 'permission-im-message',
             status: 'unverified',
@@ -576,6 +798,74 @@ export class FeishuAdapter {
         checks.push(await this.voiceCheck());
         return checks;
     }
+    /**
+     * 凭据探测：auth/v3/tenant_access_token 换 token（唯一对 appSecret 做真裁决的面）。
+     * 曾探 `/open-apis/bot/v2/info`——该路径不存在（服务端 404 纯文本、SDK 直接抛），
+     * 任何凭据都落「凭据或网络无效」；且 bot 面本身不校验 secret（错 secret 同样回
+     * 11205），探它只能验能力不能验凭据——故拆成凭据位与机器人能力位两条。
+     */
+    async credentialsCheck() {
+        const client = this.client;
+        if (client === undefined)
+            return { name: 'credentials-valid', status: 'failed', hint: '未连接：先连接后再检查' };
+        try {
+            const response = await client.request({
+                method: 'POST',
+                url: '/open-apis/auth/v3/tenant_access_token/internal',
+                data: { app_id: this.options.appId, app_secret: this.options.appSecret },
+            });
+            const code = response?.code;
+            if (code === undefined || code === 0) {
+                return typeof response?.tenant_access_token === 'string'
+                    ? { name: 'credentials-valid', status: 'passed' }
+                    : { name: 'credentials-valid', status: 'unverified', hint: 'code 0 但未回 tenant_access_token' };
+            }
+            return {
+                name: 'credentials-valid',
+                status: 'failed',
+                hint: CREDENTIAL_ERROR_CODES.has(code)
+                    ? `appId/appSecret 无效（code ${code}）：核对凭据库条目`
+                    : `凭据探测被拒（code ${code}）`,
+            };
+        }
+        catch (error) {
+            // 只取 message（不透传 error 体：axios config 里带着 Authorization/body）。
+            const message = error?.message ?? String(error);
+            return {
+                name: 'credentials-valid',
+                status: 'failed',
+                hint: isNetworkLike(error) ? `网络不可达：${message}` : `凭据探测失败：${message}`,
+            };
+        }
+    }
+    /**
+     * 机器人能力探测：GET /open-apis/bot/v3/info（有 bot → code 0；无 bot → 11205）。
+     * 这是「长连接通了却收不到消息」的判定位：无机器人能力时事件不投递、消息发不出。
+     */
+    async botAbilityCheck() {
+        const client = this.client;
+        if (client === undefined)
+            return { name: 'bot-ability', status: 'unverified', hint: '未连接：先连接后再检查' };
+        try {
+            const response = await client.request({ method: 'GET', url: '/open-apis/bot/v3/info' });
+            const code = response?.code;
+            if (code === undefined || code === 0) {
+                return { name: 'bot-ability', status: 'passed', hint: '机器人能力已开通；收发消息仍受 im:message 权限约束' };
+            }
+            if (BOT_ABILITY_MISSING_CODES.has(code)) {
+                return {
+                    name: 'bot-ability',
+                    status: 'failed',
+                    hint: '应用未开通「机器人」能力（code 11205）：开发者后台「添加应用能力 → 机器人」并发布版本，否则长连接通也收不到消息事件、发不出消息',
+                };
+            }
+            return { name: 'bot-ability', status: 'failed', hint: `机器人能力探测被拒（code ${code}）` };
+        }
+        catch (error) {
+            const message = error?.message ?? String(error);
+            return { name: 'bot-ability', status: 'unverified', hint: `机器人能力探测未完成：${message}` };
+        }
+    }
     /**
      * 语音档位诊断（T3.5 三态）：
      * - 未启用（voiceEnabled 非 'true'）= unverified——能力存在但未开通，不谎报；
@@ -603,12 +893,12 @@ export class FeishuAdapter {
             ? { name: 'voice-pipeline', status: 'passed', hint: `ffmpeg 到位（${String(probe.version ?? '')}）；ASR/TTS 需首次实调用实证权限与配额` }
             : { name: 'voice-pipeline', status: 'failed', hint: `语音探测失败：${voiceFailureText(probe.failure)}（内部：${String(probe.failure?.message ?? '')}）` };
     }
-    /** 测试/诊断驱动：模拟一条 receive 事件（与 SDK handler 同一入口）。 */
+    /** 测试/诊断驱动：模拟一条事件（与 SDK handler 同一入口）；回传 handler 的响应体。 */
     async injectEvent(eventName, payload) {
         const handler = this.handlers?.[eventName];
         if (handler === undefined)
             throw new Error(`feishu: 未注册事件 ${eventName}`);
-        await handler(payload);
+        return await handler(payload);
     }
 }
 class FeishuUncertainError extends Error {