@xmanrui/dsh-im 0.14.0 → 0.16.0

package/src/channels/feishu/feishu-cards.mjs

@@ -0,0 +1,155 @@
+/**
+ * Feishu interactive-card builders for the dsh-im menu / session-list /
+ * workspace-list UX. All builders return the JSON string the
+ * `im.message.create` API expects as `content` for `msg_type: interactive`
+ * (card schema 2.0; callback buttons live inside a column_set/column layout).
+ *
+ * Buttons carry a small `{ action }` callback behavior that
+ * `card.action.trigger` events echo back (when the app subscribes that
+ * callback); every button also carries a numeric label so the number-reply
+ * fallback stays usable without button callbacks.
+ */
+
+export const MENU_PAGE_SIZE = 10;
+
+function plainText(content) {
+  return { tag: 'plain_text', content: String(content) };
+}
+
+function markdown(content) {
+  return { tag: 'lark_md', content: String(content) };
+}
+
+function button(content, actionValue) {
+  return {
+    tag: 'column_set',
+    flex_mode: 'none',
+    columns: [{
+      tag: 'column',
+      width: 'weighted',
+      weight: 1,
+      elements: [{
+        tag: 'button',
+        text: plainText(content),
+        type: 'default',
+        width: 'fill',
+        behaviors: [{ type: 'callback', value: { action: actionValue } }],
+      }],
+    }],
+  };
+}
+
+function safeTitle(value) {
+  const title = String(value ?? '').replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+/gu, ' ').replace(/\s+/gu, ' ').trim();
+  return title || '暂无标题';
+}
+
+function cardWith(headerText, elements) {
+  return JSON.stringify({
+    schema: '2.0',
+    header: { title: plainText(headerText), template: 'blue' },
+    body: { elements },
+  });
+}
+
+/** The main command menu (buttons + number-reply fallback). */
+export function menuCard() {
+  return cardWith('🤖 助手菜单', [
+    { tag: 'div', text: markdown('**点击按钮或直接回复数字**') },
+    button('1 · 会话列表', 'sessions'),
+    button('2 · 工作区', 'workspaces'),
+    button('3 · 新会话', 'new'),
+    button('4 · 状态', 'status'),
+    button('5 · 帮助', 'help'),
+    // Repair must remain number-driven. Apps that need this command do not
+    // have card.action.trigger yet, so rendering it as a callback button would
+    // send the user straight back to Feishu's broken callback setup popup.
+    { tag: 'div', text: markdown('**6 · 修复卡片按钮**（请直接回复数字 **6**）') },
+  ]);
+}
+
+/** One-shot callback probe used only after an existing app was re-authorized. */
+export function cardActionProbeCard(nonce) {
+  if (typeof nonce !== 'string' || !/^[A-Za-z0-9_-]{16,128}$/.test(nonce)) {
+    throw new TypeError('A safe card-action probe nonce is required');
+  }
+  return cardWith('🧪 验证卡片按钮', [
+    {
+      tag: 'div',
+      text: markdown('授权已提交。请点击下方按钮；机器人真实收到回调后才会判定修复成功。'),
+    },
+    {
+      tag: 'column_set',
+      flex_mode: 'none',
+      columns: [{
+        tag: 'column',
+        width: 'weighted',
+        weight: 1,
+        elements: [{
+          tag: 'button',
+          text: plainText('完成验证'),
+          type: 'primary',
+          width: 'fill',
+          behaviors: [{
+            type: 'callback',
+            value: { action: 'repair_verify', nonce },
+          }],
+        }],
+      }],
+    },
+  ]);
+}
+
+/**
+ * One page of the workspace's sessions. Each row is a bind button; the
+ * number label equals the reply-number for the same action (fallback).
+ */
+export function sessionListCard(workspace, sessions, page, total) {
+  const start = page * MENU_PAGE_SIZE;
+  const slice = sessions.slice(start, start + MENU_PAGE_SIZE);
+  const pageCount = Math.max(1, Math.ceil(total / MENU_PAGE_SIZE));
+  const elements = [
+    { tag: 'div', text: markdown(`**工作区**：\`${workspace}\`\n共 **${total}** 个会话${total > MENU_PAGE_SIZE ? `（第 ${page + 1}/${pageCount} 页）` : ''}`) },
+    ...slice.map((session, offset) => button(
+      `${offset + 1}. ${safeTitle(session.title)}`,
+      `use:${session.sessionId}`,
+    )),
+  ];
+  if (page > 0) elements.push(button('◀ 上一页', `sessions:${page - 1}`));
+  if (page + 1 < pageCount) elements.push(button('下一页 ▶', `sessions:${page + 1}`));
+  elements.push({ tag: 'div', text: markdown('回复数字（1~N）同样可以绑定本页会话。') });
+  return cardWith('📂 会话列表', elements);
+}
+
+/** The workspace list card (switch-workspace buttons + reply fallback). */
+export function workspaceListCard(paths, current) {
+  const elements = paths.length === 0
+    ? [{ tag: 'div', text: markdown('当前 Host 上没有已登记的工作区。') }]
+    : [
+        { tag: 'div', text: markdown(`回复数字切换工作区，或点击按钮：`) },
+        ...paths.map((path, index) => button(
+          `${index + 1}. ${path}${path === current ? '（当前）' : ''}`,
+          `workspace:${path}`,
+        )),
+      ];
+  return cardWith('🗂 工作区', elements);
+}
+
+/** The card-menu help text (number-driven, no command memorization). */
+export function menuHelpText() {
+  return [
+    '🤖 助手菜单（回复数字即可，无需记命令）',
+    '',
+    '1 · /sessionlist  列出会话（回复数字绑定）',
+    '2 · /workspacelist  列出工作区（回复数字切换）',
+    '3 · /new  开启新会话',
+    '4 · /status  连接状态',
+    '5 · /help  本帮助',
+    '6 · /repair  修复卡片按钮（请回复数字 6）',
+    '',
+    '直接发送文字/图片即继续当前会话。',
+    '/session ID 或序号  绑定已有会话',
+    '/compact  压缩上下文',
+    '/workspace 绝对路径  切换工作区',
+  ].join('\n');
+}

package/src/channels/feishu/feishu-runtime.mjs

@@ -1,4 +1,6 @@
+import { randomUUID } from 'node:crypto';
 import { FeishuHarnessBridge } from './bridge.mjs';
+import { cardActionProbeCard } from './feishu-cards.mjs';
 import { VerifiedFeishuChannel } from './feishu-channel.mjs';
 import {
   connectionTestTargetUnavailable,
@@ -6,6 +8,25 @@ import {
 } from '../shared/connection-test.mjs';
 
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
+const CALLBACK_PROBE_SUCCESS_NOTICE = '✅ 修复完成：已实测收到 card.action.trigger，菜单按钮现在可用。';
+const CALLBACK_PROBE_TIMEOUT_NOTICE = '⚠️ 修复验证超时：未收到测试卡按钮的 card.action.trigger，不能确认按钮已修复。请不要重复授权；先检查飞书开放平台的卡片回调配置，确认后再发送 /repair。';
+const CALLBACK_PROBE_SEND_FAILURE_NOTICE = '⚠️ 修复验证失败：无法发送专用测试卡，不能确认 card.action.trigger 已恢复。请不要重复授权；先检查机器人消息权限和连接状态。';
+const CALLBACK_PROBE_ABORT_NOTICE = '⚠️ 修复验证中断：Runtime 已停止，未完成 card.action.trigger 实测，不能确认修复成功。请不要重复授权；先等待机器人恢复连接。';
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function strictCardOperatorOpenId(event) {
+  return nonEmptyString(event?.operator?.open_id)
+    ?? nonEmptyString(event?.operator?.operator_id?.open_id);
+}
+
+function probeError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
 
 function httpInstanceWithTimeout(httpInstance, timeoutMs) {
   if (!httpInstance || typeof httpInstance.request !== 'function') return undefined;
@@ -41,9 +62,12 @@ export function createBridgeStatus({ allowedSenderCount = 1 } = {}) {
     streamUpdates: 0,
     streamFallbacks: 0,
     streamErrors: 0,
+    cardActionsReceived: 0,
+    cardActionProbesVerified: 0,
     lastMessageAt: null,
     lastReplyAt: null,
     lastRejectedAt: null,
+    lastCardActionAt: null,
     lastError: null,
     agentPreset: 'standard',
     authorizationMode: 'sender-open-id-allowlist',
@@ -59,6 +83,7 @@ export function createBridgeStatus({ allowedSenderCount = 1 } = {}) {
  */
 export class FeishuRuntime {
   #lark;
+  #botId;
   #appId;
   #appSecret;
   #domain;
@@ -69,15 +94,18 @@ export class FeishuRuntime {
   #connectTimeoutMs;
   #requestTimeoutMs;
   #logger;
+  #repair;
   #client = null;
   #bridge = null;
   #wsClient = null;
   #starting = null;
   #abortController = null;
+  #pendingCardActionProbes = new Map();
   #status;
 
   constructor({
     lark,
+    botId,
     appId,
     appSecret,
     domain = 'feishu',
@@ -85,6 +113,7 @@ export class FeishuRuntime {
     ownerOpenIds,
     harness,
     state,
+    repair,
     replyTimeoutMs = 600000,
     connectTimeoutMs = 15000,
     requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
@@ -97,17 +126,22 @@ export class FeishuRuntime {
     if (normalizedOwners.length === 0) throw new Error('FeishuRuntime requires at least one owner open_id');
     if (!harness) throw new Error('FeishuRuntime requires a Harness client');
     if (!state) throw new Error('FeishuRuntime requires a state store');
+    if (repair !== undefined && repair !== null && !nonEmptyString(botId)) {
+      throw new TypeError('FeishuRuntime repair capability requires a botId');
+    }
     if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs <= 0) {
       throw new TypeError('FeishuRuntime requestTimeoutMs must be a positive number');
     }
 
     this.#lark = lark;
+    this.#botId = nonEmptyString(botId);
     this.#appId = appId;
     this.#appSecret = appSecret;
     this.#domain = domain;
     this.#ownerOpenIds = normalizedOwners;
     this.#harness = harness;
     this.#state = state;
+    this.#repair = repair ?? null;
     this.#replyTimeoutMs = replyTimeoutMs;
     this.#connectTimeoutMs = connectTimeoutMs;
     this.#requestTimeoutMs = requestTimeoutMs;
@@ -166,6 +200,10 @@ export class FeishuRuntime {
         state: this.#state,
         status: this.#status,
         allowedSenderOpenIds: new Set(this.#ownerOpenIds),
+        botId: this.#botId,
+        appId: this.#appId,
+        repair: this.#repair,
+        repairOwnerOpenIds: new Set(this.#ownerOpenIds.filter((value) => value !== '*')),
         replyTimeoutMs: this.#replyTimeoutMs,
         signal,
         logger: this.#logger,
@@ -178,6 +216,15 @@ export class FeishuRuntime {
         },
         'im.message.reaction.created_v1': () => ({}),
         'im.message.reaction.deleted_v1': () => ({}),
+        // Interactive-card button callbacks (only delivered when the app
+        // subscribes card.action.trigger; the number-reply fallback covers
+        // apps that do not).
+        'card.action.trigger': (event) => {
+          this.#status.cardActionsReceived += 1;
+          this.#status.lastCardActionAt = new Date().toISOString();
+          if (!this.#consumeCardActionProbe(event)) this.#bridge.onCardAction(event);
+          return {};
+        },
       });
 
       let settleReady;
@@ -244,6 +291,147 @@ export class FeishuRuntime {
     }
   }
 
+  /**
+   * Send a one-shot callback card and resolve only after Feishu delivers the
+   * exact message/nonce/operator tuple over card.action.trigger. The controller
+   * uses this as the final proof for both browser- and chat-initiated repairs.
+   */
+  async beginCardActionProbe({ expectedOperatorOpenId, timeoutMs = 90_000 } = {}) {
+    if (!this.#status.ready || !this.#client) {
+      throw probeError('card_action_probe_unavailable', '飞书机器人尚未连接');
+    }
+    const operatorOpenId = nonEmptyString(expectedOperatorOpenId);
+    if (!operatorOpenId || operatorOpenId === '*') {
+      throw new TypeError('A precise Feishu operator open_id is required');
+    }
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 10 * 60_000) {
+      throw new TypeError('Card-action probe timeout must be between 1 and 600000ms');
+    }
+
+    const nonce = randomUUID().replaceAll('-', '');
+    let response;
+    try {
+      response = await this.#client.im.v1.message.create({
+        params: { receive_id_type: 'open_id' },
+        data: {
+          receive_id: operatorOpenId,
+          msg_type: 'interactive',
+          content: cardActionProbeCard(nonce),
+        },
+      });
+    } catch {
+      void this.#sendCardActionProbeNotice(
+        operatorOpenId,
+        CALLBACK_PROBE_SEND_FAILURE_NOTICE,
+        'failure',
+      );
+      throw probeError('card_action_probe_send_failed', '无法发送飞书卡片回调测试');
+    }
+    if (response?.code && response.code !== 0) {
+      void this.#sendCardActionProbeNotice(
+        operatorOpenId,
+        CALLBACK_PROBE_SEND_FAILURE_NOTICE,
+        'failure',
+      );
+      throw probeError('card_action_probe_send_failed', '无法发送飞书卡片回调测试');
+    }
+    const messageId = nonEmptyString(response?.data?.message_id)
+      ?? nonEmptyString(response?.message_id);
+    if (!messageId) {
+      void this.#sendCardActionProbeNotice(
+        operatorOpenId,
+        CALLBACK_PROBE_SEND_FAILURE_NOTICE,
+        'failure',
+      );
+      throw probeError('card_action_probe_send_failed', '飞书未返回测试卡片的消息 ID');
+    }
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        const current = this.#pendingCardActionProbes.get(messageId);
+        if (!current || current.nonce !== nonce) return;
+        this.#pendingCardActionProbes.delete(messageId);
+        void this.#sendCardActionProbeNotice(
+          operatorOpenId,
+          CALLBACK_PROBE_TIMEOUT_NOTICE,
+          'timeout',
+        );
+        reject(probeError(
+          'card_action_probe_timeout',
+          '在规定时间内未收到飞书卡片按钮回调',
+        ));
+      }, timeoutMs);
+      timeout.unref?.();
+      this.#pendingCardActionProbes.set(messageId, {
+        messageId,
+        nonce,
+        expectedOperatorOpenId: operatorOpenId,
+        timeout,
+        resolve,
+        reject,
+      });
+    });
+  }
+
+  #consumeCardActionProbe(event) {
+    const messageId = nonEmptyString(event?.context?.open_message_id);
+    if (!messageId) return false;
+    const probe = this.#pendingCardActionProbes.get(messageId);
+    if (!probe) return false;
+    const value = event?.action?.value;
+    const operatorOpenId = strictCardOperatorOpenId(event);
+    if (value?.action !== 'repair_verify'
+      || value?.nonce !== probe.nonce
+      || operatorOpenId !== probe.expectedOperatorOpenId) {
+      return false;
+    }
+    clearTimeout(probe.timeout);
+    this.#pendingCardActionProbes.delete(messageId);
+    this.#status.cardActionProbesVerified += 1;
+    // Start the terminal notification before resolving the controller-facing
+    // probe. A repair may rotate the App Secret and immediately replace this
+    // runtime after resolution; initiating the send here keeps chat and web
+    // repair flows equally observable. Notification failure never invalidates
+    // the callback proof itself.
+    void this.#sendCardActionProbeNotice(
+      operatorOpenId,
+      CALLBACK_PROBE_SUCCESS_NOTICE,
+      'success',
+    ).finally(() => {
+      probe.resolve({
+        verified: true,
+        messageId,
+        operatorOpenId,
+      });
+    });
+    return true;
+  }
+
+  #sendCardActionProbeNotice(operatorOpenId, text, outcome) {
+    const client = this.#client;
+    if (!client) {
+      this.#logger.warn?.(`[dsh-feishu] unable to send the callback repair ${outcome} notice`);
+      return Promise.resolve(false);
+    }
+    return Promise.resolve().then(async () => {
+      const response = await client.im.v1.message.create({
+        params: { receive_id_type: 'open_id' },
+        data: {
+          receive_id: operatorOpenId,
+          msg_type: 'text',
+          content: JSON.stringify({ text }),
+        },
+      });
+      if (response?.code && response.code !== 0) {
+        throw new Error('Feishu callback repair notice failed');
+      }
+      return true;
+    }).catch(() => {
+      this.#logger.warn?.(`[dsh-feishu] unable to send the callback repair ${outcome} notice`);
+      return false;
+    });
+  }
+
   async sendConnectionTest(text) {
     if (!this.#status.ready || !this.#client) {
       const error = new Error('飞书机器人尚未连接');
@@ -290,6 +478,16 @@ export class FeishuRuntime {
     const abortController = this.#abortController;
     this.#abortController = null;
     abortController?.abort(new DOMException('Feishu runtime stopped', 'AbortError'));
+    for (const probe of this.#pendingCardActionProbes.values()) {
+      clearTimeout(probe.timeout);
+      void this.#sendCardActionProbeNotice(
+        probe.expectedOperatorOpenId,
+        CALLBACK_PROBE_ABORT_NOTICE,
+        'abort',
+      );
+      probe.reject(probeError('abort', '飞书运行时已停止'));
+    }
+    this.#pendingCardActionProbes.clear();
     this.#status.ready = false;
     if (this.#wsClient) {
       this.#wsClient.close({ force: true });