@xmanrui/dsh-im 4.11.0 → 4.13.0

package/src/channels/shared/workspace-session.mjs

@@ -15,6 +15,7 @@ function workspaceSession(harness, sessionId) {
     isRunning: (...args) => harness.isSessionRunning(sessionId, ...args),
     hasActiveTurn: (...args) => harness.hasActiveTurn(sessionId, ...args),
     stopActiveTurn: (...args) => harness.stopActiveTurn(sessionId, ...args),
+    stopDeferredTurn: (...args) => harness.stopDeferredTurn?.(sessionId, ...args) ?? false,
     steerActiveTurn: (...args) => harness.steerActiveTurn(sessionId, ...args),
     ask: (...args) => harness.ask(sessionId, ...args),
   };
@@ -51,6 +52,7 @@ export async function askInWorkspaceSession({
   createOptions,
   existsOptions,
   askOptions,
+  deferredDelivery,
 }) {
   const initialTitle = contextEnhanced
     ? initialSessionTitle({
@@ -97,7 +99,20 @@ export async function askInWorkspaceSession({
         artifacts.push(artifact);
         await originalOnArtifact?.(artifact);
       };
-      const answer = await binding.session.ask(content ?? text, artifactOptions);
+      let answer;
+      try {
+        answer = await binding.session.ask(content ?? text, artifactOptions);
+      } catch (error) {
+        if (error?.code === 'harness-reply-timeout' && deferredDelivery) {
+          try {
+            const { coordinator, ...destination } = deferredDelivery();
+            await coordinator.trackTimeout(error, { ...destination, key, sessionId: binding.sessionId });
+          } catch (registrationError) {
+            console.warn('[dsh-im] unable to persist deferred delivery:', registrationError.message);
+          }
+        }
+        throw error;
+      }
       return {
         sessionId: binding.sessionId,
         answer,

package/src/channels/wecom/state-store.mjs

@@ -1,3 +1,4 @@
+import { deferredStateAccess, normalizeDeferredState } from '../shared/deferred-state.mjs';
 import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 
@@ -14,6 +15,7 @@ function normalizeState(value) {
   return {
     version: 1,
     sessions,
+    ...(value.deferred ? { deferred: normalizeDeferredState(value.deferred) } : {}),
     seenMessageIds: Array.isArray(value.seenMessageIds)
       ? value.seenMessageIds.filter((id) => typeof id === 'string').slice(-1_000)
       : [],
@@ -24,6 +26,7 @@ export class WecomStateStore {
   #path;
   #state = structuredClone(EMPTY_STATE);
   #writeQueue = Promise.resolve();
+  #deferred = deferredStateAccess(() => this.#state, () => this.#persist());
 
   constructor(path) {
     this.#path = path;
@@ -40,6 +43,11 @@ export class WecomStateStore {
     return this;
   }
 
+  deferredEntries() { return this.#deferred.entries(); }
+  putDeferred(entry) { return this.#deferred.put(entry); }
+  patchDeferred(id, patch) { return this.#deferred.patch(id, patch); }
+  removeDeferred(id) { return this.#deferred.remove(id); }
+
   sessionFor(key) {
     return this.#state.sessions[key] ?? null;
   }

package/src/channels/wecom/wecom-bridge.mjs

@@ -1,4 +1,9 @@
+import { createDeferredDeliveryCoordinator, deferredOutcomeText } from '../shared/deferred-delivery-coordinator.mjs';
 import { generateReqId } from '@wecom/aibot-node-sdk';
+import { randomUUID } from 'node:crypto';
+import {
+  parseWecomMenu, wecomList, wecomMenu, wecomMenuText, wecomSettings, wecomTemplateCard,
+} from './wecom-cards.mjs';
 import {
   harnessAnswerForQuestion,
   harnessQuestionText,
@@ -25,7 +30,7 @@ import {
   isPresetCommand,
   runPresetCommand,
 } from '../shared/preset-command.mjs';
-import { runWorkspaceCommand } from '../shared/workspace-command.mjs';
+import { runWorkspaceCommand, workspacePathSnapshot } from '../shared/workspace-command.mjs';
 import { askInWorkspaceSession } from '../shared/workspace-session.mjs';
 import { captureContextEnhancement, enhanceContextContent } from '../shared/context-enhancement.mjs';
 import {
@@ -68,6 +73,7 @@ function helpText() {
     t('企业微信机器人已连接 DeepSeek Harness。'),
     '',
     t('直接发送文字、图片或文件即可继续当前会话。'),
+    t('/menu 或 /m  打开可点击的功能菜单'),
     t('/new  开启一个全新会话'),
     t('/compact  压缩当前会话的较早上下文'),
     t('/history [数量]  查看最近历史消息（默认 3 条，最多 5 条）'),
@@ -352,15 +358,17 @@ function thinkingProgressText(update) {
 }
 
 function streamContent(thinkingText, answerText = '', { finish = false } = {}) {
+  const answer = String(answerText ?? '').trim();
+  // Progress is transient: the final frame must contain only the delivered text.
+  if (finish) return answer;
+
   const thinking = String(thinkingText ?? '')
     .replace(/<\/?think>/gi, '')
     .trim();
-  const answer = String(answerText ?? '').trim();
   if (!thinking) return answer;
-  const thinkBlock = finish || answer
-    ? `<think>${thinking}</think>`
+  return answer
+    ? `<think>${thinking}</think>\n${answer}`
     : `<think>${thinking}`;
-  return answer ? `${thinkBlock}\n${answer}` : thinkBlock;
 }
 
 function artifactFailureText(fileName, error) {
@@ -536,6 +544,7 @@ export class WecomHarnessBridge {
   #client;
   #harness;
   #state;
+  #deferred;
   #contextEnhancement;
   #accessPolicy;
   #status;
@@ -554,6 +563,9 @@ export class WecomHarnessBridge {
   #approvals;
   #batchInputs = new BatchInputManager();
   #prefetchedImageCount = 0;
+  #menus = new Map();
+  #eventIds = new Set();
+  #cardFrames = new WeakSet();
 
   constructor({
     client,
@@ -586,6 +598,9 @@ export class WecomHarnessBridge {
     this.#generateReqId = generateStreamId;
     this.#fileUploadTimeoutMs = Math.min(fileUploadTimeoutMs, DEFAULT_FILE_UPLOAD_TIMEOUT_MS);
     this.#signal = signal;
+    this.#deferred = createDeferredDeliveryCoordinator({ harness, state, signal, logger,
+      deliver: (entry, outcome) => this.#deliverDeferredOutcome(entry, outcome),
+    });
     this.#approvals = new HarnessApprovalQueue({ label: 'wecom', logger });
   }
 
@@ -593,6 +608,264 @@ export class WecomHarnessBridge {
     return structuredClone(this.#status);
   }
 
+  #mainMenu() {
+    return wecomMenu({
+      workspace: this.#harness.currentWorkspace?.(),
+      workspaces: [[t('更多选项…'), '/menu workspaces']],
+    });
+  }
+
+  async #showMain(frame, { welcome = false } = {}) {
+    const key = conversationKey(frame);
+    const workspace = this.#harness.currentWorkspace?.();
+    const sessionId = this.#state.sessionFor(key);
+    // The welcome reply has a five-second deadline. Show immediate controls,
+    // then load the selectors independently of that reply window.
+    if (welcome) await this.#sendMenu(frame, this.#mainMenu(), { welcome: true });
+    const options = { signal: this.#signal };
+    const settled = await Promise.allSettled([
+      workspacePathSnapshot(this.#harness, options),
+      this.#harness.listWorkspaceSessions?.(workspace, options),
+      (async () => {
+        const session = sessionId ? this.#harness.workspaceSession?.(sessionId) : null;
+        return typeof session?.models === 'function'
+          ? session.models(options) : this.#harness.listModels?.(options);
+      })(),
+      this.#harness.agentPresetSettings?.(options),
+    ]);
+    this.#signal?.throwIfAborted();
+    const [paths, listed, catalog, settings] = settled.map((result) => result.status === 'fulfilled' ? result.value : null);
+    const sessions = (listed?.sessions ?? []).map((item) => [item.title || t('暂无标题'), `/session ${item.sessionId}`]);
+    const models = (catalog?.groups ?? []).flatMap((group) => group.models.map((model) => [
+      `${model.name} (${group.id})`, `/model ${group.id}/${model.id}`,
+    ]));
+    const presets = [[t('跟随 Host 默认'), '/preset --default'], ...(settings?.agentPresetCatalog?.items ?? []).map((item) => [
+      item.label || item.id, `/preset ${/^\d+$/u.test(item.id) ? 'id:' : ''}${item.id}`,
+    ])];
+    const currentPreset = settings?.agentPreset;
+    const settingsMenu = wecomSettings({
+      sessions, models, presets, sessionId,
+      currentModel: catalog?.current ? `/model ${catalog.current.provider}/${catalog.current.model}` : null,
+      currentPreset: currentPreset ? `/preset ${/^\d+$/u.test(currentPreset) ? 'id:' : ''}${currentPreset}` : '/preset --default',
+      presetLabel: settings?.agentPresetCatalog?.items.find((item) => item.id === currentPreset)?.label,
+    });
+    await this.#sendMenu(frame, settingsMenu, { active: welcome });
+    if (welcome) return;
+    await this.#sendMenu(frame, wecomMenu({ workspace,
+      workspaces: (paths?.paths ?? (workspace ? [workspace] : [])).map((path) => [path, `/workspace ${path}`]),
+    }), { active: true });
+  }
+
+  #rememberMenu(frame, menu) {
+    const taskId = `menu_${randomUUID()}`;
+    const now = Date.now();
+    for (const [id, entry] of this.#menus) {
+      if (entry.expiresAt <= now) this.#menus.delete(id);
+    }
+    while (this.#menus.size >= 256) this.#menus.delete(this.#menus.keys().next().value);
+    this.#menus.set(taskId, {
+      menu, key: conversationKey(frame),
+      workspace: this.#harness.currentWorkspace?.(), expiresAt: now + 30 * 60_000,
+    });
+    return wecomTemplateCard(menu, taskId);
+  }
+
+  async #sendMenu(frame, menu, { welcome = false, active = false } = {}) {
+    this.#signal?.throwIfAborted();
+    const body = bodyOf(frame);
+    const chatId = body.chattype === 'group' ? body.chatid : body.from.userid;
+    const card = this.#rememberMenu(frame, menu);
+    try {
+      if (welcome) {
+        await this.#client.replyWelcome(frame, { msgtype: 'template_card', template_card: card });
+      } else if (active || this.#cardFrames.has(frame)) {
+        await this.#client.sendMessage(chatId, { msgtype: 'template_card', template_card: card });
+      } else {
+        await this.#client.replyTemplateCard(frame, card);
+      }
+    } catch (error) {
+      this.#menus.delete(card.task_id);
+      this.#logger.warn?.('[dsh-im:wecom] menu delivery failed; using text:', error);
+      if (welcome) {
+        await this.#client.replyWelcome(frame, { msgtype: 'text', text: { content: wecomMenuText(menu) } });
+      } else {
+        await this.#sendImmediate(frame, chatId, wecomMenuText(menu));
+      }
+    }
+  }
+
+  acceptEvent(frame) {
+    const body = bodyOf(frame);
+    const id = nonEmptyString(body.msgid);
+    if (this.#signal?.aborted || !id || this.#eventIds.has(id) || this.#state.hasSeen(id)) {
+      return Promise.resolve();
+    }
+    this.#eventIds.add(id);
+    let task;
+    task = this.#processEvent(frame).catch((error) => {
+      if (this.#signal?.aborted) return;
+      this.#status.lastError = error?.message ?? String(error);
+      this.#logger.warn?.('[dsh-im:wecom] menu event failed:', error);
+    }).finally(() => {
+      this.#eventIds.delete(id);
+      this.#commandTasks.delete(task);
+    });
+    this.#commandTasks.add(task);
+    return task;
+  }
+
+  async #processEvent(frame) {
+    const body = bodyOf(frame);
+    const senderId = nonEmptyString(body.from?.userid);
+    const type = body.event?.eventtype;
+    if (!senderId || !['enter_chat', 'template_card_event'].includes(type)) return;
+    const chattype = body.chattype ?? (body.chatid ? 'group' : 'single');
+    if (!['single', 'group'].includes(chattype) || (chattype === 'group' && !body.chatid)) return;
+    const normalized = { ...frame, body: { ...body, chattype } };
+    const chatId = chattype === 'group' ? body.chatid : senderId;
+    const access = evaluateInboundAccess(this.#accessPolicy, {
+      conversationType: chattype === 'single' ? 'direct' : 'group', senderIds: senderId, isCommand: true,
+    });
+    if (!access.allowed) {
+      if (type === 'template_card_event' && access.reason === 'command-not-allowed') {
+        await this.#sendActive(chatId, t(COMMAND_PERMISSION_DENIED_MESSAGE));
+      }
+      return;
+    }
+    await this.#state.markSeen(body.msgid);
+    const key = conversationKey(normalized);
+    if (type === 'enter_chat') {
+      if (chattype === 'single') await this.#showMain(normalized, { welcome: true });
+      return;
+    }
+    // Live callbacks nest these fields; older SDK examples show them flat.
+    const callback = body.event.template_card_event ?? body.event;
+    const entry = this.#menus.get(callback.task_id);
+    const choice = typeof callback.event_key === 'string' && /^\d+$/u.test(callback.event_key)
+      ? entry?.menu.entries[callback.event_key] : null;
+    if (!entry || entry.expiresAt <= Date.now() || !Array.isArray(choice)
+      || entry.key !== key) {
+      await this.#sendActive(chatId, t('这个菜单已过期，请回复 /m 重新打开。'));
+      return;
+    }
+    this.#menus.delete(callback.task_id);
+    // Acknowledge before Host RPC. Keep a valid button card: text_notice requires a URL.
+    const acknowledgedMenu = { title: choice[0], description: t('已收到操作，请查看下方结果。'),
+      entries: [[t('重新打开菜单'), '/menu']] };
+    await this.#client.updateTemplateCard(frame, wecomTemplateCard(acknowledgedMenu, callback.task_id), [senderId]).then(() => {
+      this.#menus.set(callback.task_id, { ...entry, menu: acknowledgedMenu });
+    }).catch((error) => {
+      this.#logger.warn?.('[dsh-im:wecom] menu acknowledgement failed:', error);
+    });
+    let commands = [choice[1]];
+    if (choice[1] === 'apply' || choice[1].startsWith('select:')) {
+      const selectors = (entry.menu.selectors ?? []).filter((item) => choice[1] === 'apply' || item.key === choice[1].slice(7));
+      const selectedItems = callback.selected_items?.selected_item ?? callback.selected_items ?? [];
+      if (!Array.isArray(selectedItems)) {
+        await this.#sendActive(chatId, t('请选择一个选项后再应用。'));
+        return;
+      }
+      commands = [];
+      for (const selector of selectors) {
+        const selected = selectedItems.find((item) => item?.question_key === selector.key);
+        const ids = selected?.option_ids?.option_id ?? selected?.option_ids ?? ['0'];
+        const id = ids[0];
+        if (!Array.isArray(ids) || ids.length !== 1 || !/^\d+$/u.test(id) || !selector.entries[Number(id)]) {
+          await this.#sendActive(chatId, t('请选择一个选项后再应用。'));
+          return;
+        }
+        const command = selector.entries[Number(id)][1];
+        if (command) commands.push(command);
+      }
+    }
+    const navigation = commands.find((command) => parseWecomMenu(command));
+    if (navigation) commands = [navigation];
+    if (!navigation && entry.workspace !== this.#harness.currentWorkspace?.()) {
+      await this.#sendActive(chatId, t('工作区已变化，请从新菜单重新选择。'));
+    } else {
+      for (const [index, command] of commands.entries()) {
+        const commandFrame = { ...normalized, body: { ...normalized.body,
+          msgid: `card:${body.msgid}:${index}`, msgtype: 'text', text: { content: command },
+        } };
+        this.#cardFrames.add(commandFrame);
+        await this.accept(commandFrame);
+      }
+      if (!commands.length) await this.#sendActive(chatId, t('设置未改变。'));
+    }
+    if (!navigation) {
+      this.#cardFrames.add(normalized);
+      await this.#showMain(normalized);
+    }
+  }
+
+  async #runMenuCommand(frame, text, _harness, _state, key) {
+    const menu = parseWecomMenu(text);
+    const options = { signal: this.#signal };
+    if (menu) {
+      let content;
+      if (menu.section === 'main') {
+        await this.#showMain(frame);
+        return { messages: [] };
+      }
+      else {
+        let title;
+        let entries;
+        let description = '';
+        if (menu.section === 'sessions') {
+          title = t('📋 会话列表');
+          const listed = await this.#harness.listWorkspaceSessions(this.#harness.currentWorkspace(), options);
+          entries = listed.sessions.map((session) => [
+            `${session.sessionId === this.#state.sessionFor(key) ? '✓ ' : ''}${session.title || t('暂无标题')}`,
+            `/session ${session.sessionId}`,
+          ]);
+        } else if (menu.section === 'workspaces') {
+          title = t('🗂 工作区列表');
+          const { paths, current } = await workspacePathSnapshot(this.#harness, options);
+          entries = paths.map((path) => [`${path === current ? '✓ ' : ''}${path}`, `/workspace ${path}`]);
+        } else if (menu.section === 'models') {
+          title = t('🧠 切换模型');
+          const sessionId = this.#state.sessionFor(key);
+          const session = sessionId ? this.#harness.workspaceSession?.(sessionId) : null;
+          const catalog = typeof session?.models === 'function'
+            ? await session.models(options) : await this.#harness.listModels(options);
+          entries = catalog.groups.flatMap((group) => group.models.map((model) => [
+            `${catalog.current?.provider === group.id && catalog.current?.model === model.id ? '✓ ' : ''}${model.name} (${group.id})`,
+            `/model ${group.id}/${model.id}`,
+          ]));
+          if (catalog.failures?.length) description = t('部分模型暂不可用，可稍后重试。');
+        } else {
+          title = t('🤖 切换预设');
+          const settings = await this.#harness.agentPresetSettings(options);
+          entries = [[t('🔄 跟随默认'), '/preset --default'], ...settings.agentPresetCatalog.items.map((item) => [
+            `${settings.agentPreset === item.id ? '✓ ' : ''}${item.label || item.id}`,
+            `/preset ${/^\d+$/u.test(item.id) ? 'id:' : ''}${item.id}`,
+          ])];
+          description = t('预设仅用于之后的新会话。');
+        }
+        this.#harness.assertWorkspaceScope?.();
+        content = wecomList({ title, entries, description, ...menu });
+      }
+      await this.#sendMenu(frame, content);
+      return { messages: [] };
+    }
+    const command = text.toLowerCase();
+    if (command === '/help') return { message: helpText() };
+    if (command === '/status') {
+      await this.#harness.ensureRunning(options);
+      return { message: t('企业微信机器人与 DeepSeek Harness 连接正常。') };
+    }
+    if (this.#queues.has(key) || this.#pendingInteractions.has(key) || this.#approvals.hasPending(key)
+      || this.#batchInputs.status(key).phase !== 'idle') {
+      return { message: t('当前任务仍在运行，请先停止任务或等待任务完成后再开启新会话。') };
+    }
+    if (command === '/new') {
+      await this.#state.clearSession(key);
+      return { message: t('已开启新会话。请发送你的问题。') };
+    }
+    return await runWorkspaceCommand(text, this.#harness, key)
+      ?? await runCompactCommand(text, this.#harness, this.#state, key, options);
+  }
+
   accept(frame) {
     if (this.#signal?.aborted) return Promise.resolve();
     const body = bodyOf(frame);
@@ -617,6 +890,8 @@ export class WecomHarnessBridge {
       text: commandText,
       hasImages: hasInboundImages(commandMessage),
       hasFiles: hasInboundFiles(commandMessage),
+      ...(parseWecomMenu(commandText) && !hasInboundImages(commandMessage) && !hasInboundFiles(commandMessage)
+        ? { isCommand: true } : {}),
     });
     if (!access.allowed) {
       this.#acceptedMessageIds.set(messageId, null);
@@ -663,12 +938,16 @@ export class WecomHarnessBridge {
         return this.#finishBatchResult(frame, messageId, chatId, result);
       }
     }
+    const menuCommand = !hasInboundImages(commandMessage) && !hasInboundFiles(commandMessage)
+      && (parseWecomMenu(commandText) || ['/help', '/status', '/new'].includes(commandText.toLowerCase())
+        || this.#cardFrames.has(frame));
     const commandRunner = isHistoryCommand(commandText) ? runHistoryCommand
       : hasInboundFiles(commandMessage) ? null : isControlCommand(commandText)
       ? runControlCommand
       : (isModelCommand(commandText)
           ? runModelCommand
-          : (isPresetCommand(commandText) ? runPresetCommand : null));
+          : (isPresetCommand(commandText) ? runPresetCommand : menuCommand
+            ? (...args) => this.#runMenuCommand(frame, ...args) : null));
     if (commandRunner) {
       let task;
       task = this.#processFastCommand(
@@ -850,6 +1129,11 @@ export class WecomHarnessBridge {
     return task;
   }
 
+  async #deliverDeferredOutcome(entry, outcome) {
+    await this.#sendActive(entry.target.chatId, deferredOutcomeText(outcome));
+    return true;
+  }
+
   async waitForIdle() {
     await Promise.allSettled([
       ...this.#queues.values(),
@@ -859,6 +1143,7 @@ export class WecomHarnessBridge {
       ...this.#approvalTasks,
       ...this.#commandTasks,
     ]);
+    await this.#deferred.whenIdle();
   }
 
   async #processFastCommand(frame, messageId, chatId, key, message, runner) {
@@ -875,6 +1160,7 @@ export class WecomHarnessBridge {
       pendingInteraction: this.#pendingInteractions.has(key)
         || this.#approvals.hasPending(key),
       control: { owner: this, key },
+      deferredDelivery: this.#deferred,
     });
     if (result?.stopped) {
       await Promise.allSettled([
@@ -904,6 +1190,7 @@ export class WecomHarnessBridge {
 
   async #sendImmediate(frame, chatId, text) {
     this.#signal?.throwIfAborted();
+    if (this.#cardFrames.has(frame)) return this.#sendActive(chatId, text);
     const chunks = splitUtf8(text);
     if (chunks.length === 0) return;
     try {
@@ -1064,6 +1351,7 @@ export class WecomHarnessBridge {
       await this.#state.markSeen(messageId);
       promptRecorded = true;
       const { answer, artifacts = [] } = await askInWorkspaceSession({
+        deferredDelivery: () => ({ coordinator: this.#deferred, target: { chatId } }),
         harness: this.#harness,
         state: this.#state,
         key,

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

@@ -0,0 +1,101 @@
+import { t } from '../shared/i18n.mjs';
+
+const MENU_COMMAND = /^\/m(?:enu)?(?:\s+(sessions|workspaces|models|presets)(?:\s+(\d+))?)?$/iu;
+
+export function parseWecomMenu(text) {
+  const match = MENU_COMMAND.exec(text.trim());
+  return match ? { section: match[1]?.toLowerCase() ?? 'main', page: Number(match[2] ?? 0) } : null;
+}
+
+function clean(value, length = 80) {
+  return [...String(value ?? '').replace(/[\p{Cc}\p{Cf}]/gu, ' ')].slice(0, length).join('');
+}
+
+function selector(key, title, entries, currentLabel, currentCommand, moreCommand) {
+  const choices = entries.filter(([, command]) => command !== currentCommand);
+  const visible = choices.slice(0, choices.length > 9 ? 8 : 9);
+  return {
+    key, title,
+    entries: [[currentLabel || t('保持当前'), null], ...visible,
+      ...(choices.length > 9 ? [[t('更多选项…'), moreCommand]] : [])],
+  };
+}
+
+export function wecomSettings({ sessions = [], models = [], presets = [], sessionId,
+  currentModel, currentPreset, presetLabel } = {}) {
+  return {
+    title: t('🤖 助手中心'),
+    description: t('选择会话、模型或预设后，点击应用设置。'),
+    selectors: [
+      selector('session', t('会话'), sessions,
+        sessions.find(([, command]) => command === `/session ${sessionId}`)?.[0] || t('新会话'),
+        `/session ${sessionId}`, '/menu sessions'),
+      selector('model', t('模型'), models,
+        models.find(([, command]) => command === currentModel)?.[0] || t('跟随默认模型'),
+        currentModel, '/menu models'),
+      selector('preset', t('预设'), presets, presetLabel || t('跟随 Host 默认'),
+        currentPreset, '/menu presets'),
+    ],
+    entries: [[t('应用设置'), 'apply']],
+  };
+}
+
+export function wecomMenu({ workspace, workspaces = [] } = {}) {
+  return {
+    title: t('工作区与任务'),
+    selectors: [selector('workspace', t('工作区'), workspaces,
+      workspace, `/workspace ${workspace}`, '/menu workspaces')],
+    entries: [
+      [t('切换工作区'), 'select:workspace'],
+      [t('🆕 新会话'), '/new'],
+      [t('⏹ 停止'), '/stop'], [t('📐 压缩'), '/compact'],
+      [t('📊 状态'), '/status'], [t('📖 帮助'), '/help'],
+    ],
+  };
+}
+
+// A native selector carries names; buttons only apply or navigate the selection.
+export function wecomList({ title, section, entries, page = 0, description = '' }) {
+  const pages = Math.max(1, Math.ceil(entries.length / 10));
+  const current = Math.min(Math.max(0, page), pages - 1);
+  const visible = entries.slice(current * 10, current * 10 + 10);
+  const buttons = visible.length ? [[t('应用选择'), 'select:choice']] : [];
+  if (current > 0) buttons.push([t('上一页'), `/menu ${section} ${current - 1}`]);
+  if (current + 1 < pages) buttons.push([t('下一页'), `/menu ${section} ${current + 1}`]);
+  buttons.push([t('返回'), '/menu']);
+  return {
+    title,
+    description: `${current + 1} / ${pages}${description ? ` · ${description}` : ''}`,
+    detail: visible.length ? '' : t('暂无可用选项。'),
+    selectors: visible.length ? [{ key: 'choice', title, entries: visible }] : [],
+    entries: buttons,
+  };
+}
+
+export function wecomTemplateCard(menu, taskId) {
+  const selections = menu.selectors?.map((item) => ({
+    question_key: item.key, title: clean(item.title, 13), selected_id: '0',
+    option_list: item.entries.map(([label], index) => ({ id: String(index), text: clean(label, 60) })),
+  })) ?? [];
+  const multiple = selections.length > 1;
+  return {
+    card_type: multiple ? 'multiple_interaction' : 'button_interaction',
+    task_id: taskId,
+    main_title: { title: clean(menu.title, 36),
+      ...(menu.description ? { desc: clean(menu.description, 100) } : {}) },
+    ...(menu.detail ? { sub_title_text: menu.detail.slice(0, 500) } : {}),
+    ...(multiple ? { select_list: selections, submit_button: { text: menu.entries[0][0], key: '0' } }
+      : { ...(selections.length ? { button_selection: selections[0] } : {}),
+    button_list: menu.entries.map(([label], index) => ({
+      text: clean(label, 36), key: String(index), style: index === 0 ? 1 : 2,
+    })) }),
+  };
+}
+
+export function wecomMenuText(menu) {
+  return [menu.title, menu.description, menu.detail,
+    ...menu.selectors?.flatMap((item) => item.entries.filter(([, command]) => command)
+      .map(([label, command]) => `${label}：${command}`)) ?? [],
+    ...menu.entries.filter(([, command]) => command.startsWith('/'))
+      .map(([label, command]) => `${label}：${command}`)].filter(Boolean).join('\n');
+}

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

@@ -168,6 +168,8 @@ export class WecomRuntime {
     client.on('reconnecting', onReconnecting);
     client.on('error', onError);
     client.on('message', onMessage);
+    client.on('event.enter_chat', (frame) => this.#bridge?.acceptEvent(frame));
+    client.on('event.template_card_event', (frame) => this.#bridge?.acceptEvent(frame));
 
     let timer;
     try {