@xmanrui/dsh-im 4.15.0 → 4.16.1

package/plugin-src/host/channels/wecom-app/rpc.mjs

@@ -0,0 +1,225 @@
+import { SET_CONTEXT_ENHANCEMENT_ENDPOINT, validContextEnhancementPayload } from '../shared/context-enhancement-rpc.mjs';
+import { SET_ACCESS_POLICY_ENDPOINT, validAccessPolicyPayload } from '../shared/access-policy-rpc.mjs';
+import { resolveRpcAuthority } from '../../rpc-authority.mjs';
+import { publicWorkspaceError, SET_WORKSPACE_ENDPOINT, validWorkspacePayload } from '../shared/workspace-rpc.mjs';
+import { SET_AGENT_PRESET_ENDPOINT, validAgentPresetPayload } from '../shared/agent-preset-rpc.mjs';
+import { SET_MODEL_ENDPOINT, validModelPayload } from '../shared/model-setting-rpc.mjs';
+import {
+  connectionTestTargetUnavailable,
+  publicConnectionTestResult,
+} from '../../../../src/channels/shared/connection-test.mjs';
+
+export const WECOM_APP_RPC_CHANNEL = '/wecom-app';
+export const WECOM_APP_ENDPOINTS = Object.freeze({
+  status: 'connection.status',
+  bindApp: 'bot.bind',
+  updateSettings: 'bot.settings.update',
+  resetCallbackSecret: 'bot.callback-secret.reset',
+  reconnectBot: 'bot.reconnect',
+  deleteBot: 'bot.delete',
+  setWorkspace: SET_WORKSPACE_ENDPOINT,
+  setModel: SET_MODEL_ENDPOINT,
+  setAgentPreset: SET_AGENT_PRESET_ENDPOINT,
+  setContextEnhancement: SET_CONTEXT_ENHANCEMENT_ENDPOINT,
+  setAccessPolicy: SET_ACCESS_POLICY_ENDPOINT,
+});
+export const WECOM_APP_RPC_ENDPOINTS = Object.freeze(Object.values(WECOM_APP_ENDPOINTS));
+
+const FORBIDDEN_PUBLIC_KEYS = new Set([
+  'secret', 'secretRef', 'token', 'encodingAESKey', 'callbackTokenRef', 'callbackKeyRef',
+  'callbackSecret', 'corpSecret', 'bot_info',
+]);
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function exactKeys(value, allowed) {
+  return isRecord(value) && Object.keys(value).every((key) => allowed.includes(key));
+}
+
+function validId(value) {
+  return typeof value === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(value);
+}
+
+function validCredential(value, maxLength) {
+  return typeof value === 'string' && value.trim().length > 0 && value.length <= maxLength;
+}
+
+function payloadFailure(endpoint, payload) {
+  if (!isRecord(payload)) return 'Payload must be an object.';
+  if (endpoint === WECOM_APP_ENDPOINTS.status) return exactKeys(payload, []) ? null : 'connection.status does not accept fields.';
+  if (endpoint === WECOM_APP_ENDPOINTS.bindApp) {
+    const allowed = ['corpId', 'agentId', 'secret', 'token', 'encodingAESKey', 'apiBaseUrl', 'callbackBaseUrl', 'streamEnabled'];
+    if (!exactKeys(payload, allowed)) return 'bot.bind received unsupported fields.';
+    if (!validCredential(payload.corpId, 128) || !validCredential(payload.agentId, 32)
+      || !validCredential(payload.secret, 256) || !validCredential(payload.token, 128)
+      || !validCredential(payload.encodingAESKey, 128)) {
+      return 'bot.bind requires corpId, agentId, secret, token, and encodingAESKey.';
+    }
+    if (payload.apiBaseUrl !== undefined && payload.apiBaseUrl !== null && typeof payload.apiBaseUrl !== 'string') {
+      return 'bot.bind received an invalid apiBaseUrl.';
+    }
+    if (payload.callbackBaseUrl !== undefined && payload.callbackBaseUrl !== null && typeof payload.callbackBaseUrl !== 'string') {
+      return 'bot.bind received an invalid callbackBaseUrl.';
+    }
+    if (payload.streamEnabled !== undefined && payload.streamEnabled !== true && payload.streamEnabled !== false) {
+      return 'bot.bind received an invalid streamEnabled flag.';
+    }
+    return null;
+  }
+  if (endpoint === WECOM_APP_ENDPOINTS.updateSettings) {
+    if (!exactKeys(payload, ['botId', 'apiBaseUrl', 'callbackBaseUrl', 'streamEnabled']) || !validId(payload.botId)) {
+      return 'bot.settings.update requires a botId and settings fields.';
+    }
+    if (payload.apiBaseUrl !== undefined && payload.apiBaseUrl !== null && typeof payload.apiBaseUrl !== 'string') {
+      return 'bot.settings.update received an invalid apiBaseUrl.';
+    }
+    if (payload.callbackBaseUrl !== undefined && payload.callbackBaseUrl !== null && typeof payload.callbackBaseUrl !== 'string') {
+      return 'bot.settings.update received an invalid callbackBaseUrl.';
+    }
+    if (payload.streamEnabled !== undefined && payload.streamEnabled !== true && payload.streamEnabled !== false) {
+      return 'bot.settings.update received an invalid streamEnabled flag.';
+    }
+    return null;
+  }
+  if (endpoint === WECOM_APP_ENDPOINTS.resetCallbackSecret) {
+    return exactKeys(payload, ['botId']) && validId(payload.botId)
+      ? null : 'bot.callback-secret.reset requires a botId.';
+  }
+  if (endpoint === WECOM_APP_ENDPOINTS.reconnectBot) {
+    return exactKeys(payload, ['botId', 'sendTest'])
+      && validId(payload.botId)
+      && (payload.sendTest === undefined || payload.sendTest === true)
+      ? null : 'bot.reconnect requires a botId and optional sendTest=true.';
+  }
+  if (endpoint === WECOM_APP_ENDPOINTS.deleteBot) {
+    return exactKeys(payload, ['botId', 'confirm']) && validId(payload.botId) && payload.confirm === true
+      ? null : 'bot.delete requires a botId and confirm=true.';
+  }
+  if (endpoint === WECOM_APP_ENDPOINTS.setWorkspace) {
+    return validWorkspacePayload(payload) ? null : '请输入工作区绝对路径。';
+  }
+  if (endpoint === WECOM_APP_ENDPOINTS.setModel) {
+    return validModelPayload(payload) ? null : '请选择有效模型。';
+  }
+  if (endpoint === WECOM_APP_ENDPOINTS.setAgentPreset) {
+    return validAgentPresetPayload(payload) ? null : '请选择 Agent Preset。';
+  }
+  if (endpoint === WECOM_APP_ENDPOINTS.setContextEnhancement) {
+    return validContextEnhancementPayload(payload) ? null : '请提交有效的上下文增强设置。';
+  }
+  if (endpoint === WECOM_APP_ENDPOINTS.setAccessPolicy) {
+    return validAccessPolicyPayload(payload) ? null : '请提交有效的访问设置。';
+  }
+  return 'Unknown Enterprise WeChat app endpoint.';
+}
+
+function sanitizePublic(value) {
+  if (Array.isArray(value)) return value.map(sanitizePublic);
+  if (!isRecord(value)) return value;
+  const safe = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (!FORBIDDEN_PUBLIC_KEYS.has(key)) safe[key] = sanitizePublic(child);
+  }
+  return safe;
+}
+
+function publicStatus(status) {
+  return sanitizePublic(structuredClone(status));
+}
+
+export function createWecomAppRpcHandler(controller) {
+  for (const method of ['status', 'bindApp', 'updateAppSettings', 'resetCallbackSecret', 'reconnectBot', 'deleteBot']) {
+    if (typeof controller?.[method] !== 'function') {
+      throw new TypeError(`A complete Enterprise WeChat app controller is required (${method})`);
+    }
+  }
+  return async (endpoint, payload, signal) => {
+    if (signal?.aborted) return { ok: false, error: { code: 'cancelled', message: 'The request was cancelled.', details: {} } };
+    if (!WECOM_APP_RPC_ENDPOINTS.includes(endpoint)) {
+      return { ok: false, error: { code: 'bad-request', message: 'Unknown Enterprise WeChat app endpoint.', details: {} } };
+    }
+    const invalid = payloadFailure(endpoint, payload);
+    if (invalid) return { ok: false, error: { code: 'bad-request', message: invalid } };
+    try {
+      let value;
+      if (endpoint === WECOM_APP_ENDPOINTS.status) value = await publicStatus(await controller.status());
+      else if (endpoint === WECOM_APP_ENDPOINTS.bindApp) {
+        value = await publicStatus(await controller.bindApp(payload));
+      } else if (endpoint === WECOM_APP_ENDPOINTS.updateSettings) {
+        value = await publicStatus(await controller.updateAppSettings(payload.botId, {
+          apiBaseUrl: payload.apiBaseUrl,
+          callbackBaseUrl: payload.callbackBaseUrl,
+          streamEnabled: payload.streamEnabled,
+        }));
+      } else if (endpoint === WECOM_APP_ENDPOINTS.resetCallbackSecret) {
+        value = await publicStatus(await controller.resetCallbackSecret(payload.botId));
+      } else if (endpoint === WECOM_APP_ENDPOINTS.reconnectBot) {
+        const snapshot = await controller.reconnectBot(payload.botId);
+        if (signal?.aborted) {
+          return { ok: false, error: { code: 'cancelled', message: 'The request was cancelled.', details: {} } };
+        }
+        let testMessage;
+        if (payload.sendTest === true) {
+          const connected = snapshot?.bots?.some(
+            (bot) => bot?.botId === payload.botId && bot?.connected === true,
+          );
+          if (!connected || typeof controller.sendConnectionTest !== 'function') {
+            testMessage = publicConnectionTestResult(connectionTestTargetUnavailable('企业微信应用'));
+          } else {
+            try {
+              await controller.sendConnectionTest(payload.botId);
+              testMessage = publicConnectionTestResult();
+            } catch (error) {
+              testMessage = publicConnectionTestResult(error);
+            }
+          }
+        }
+        value = await publicStatus({ ...snapshot, ...(testMessage ? { testMessage } : {}) });
+      } else if (endpoint === WECOM_APP_ENDPOINTS.setWorkspace) {
+        if (typeof controller.updateWorkspace !== 'function') throw new Error('Workspace update is unavailable');
+        value = await publicStatus(await controller.updateWorkspace(payload.botId, payload.workspace));
+      } else if (endpoint === WECOM_APP_ENDPOINTS.setModel) {
+        if (typeof controller.updateModel !== 'function') throw new Error('Model update is unavailable');
+        value = await publicStatus(await controller.updateModel(payload.botId, payload.model));
+      } else if (endpoint === WECOM_APP_ENDPOINTS.setContextEnhancement) {
+        if (typeof controller.updateContextEnhancement !== 'function') throw new Error('Context enhancement update is unavailable');
+        value = await controller.updateContextEnhancement(
+          payload.botId, payload.config, (status) => publicStatus(status),
+        );
+      } else if (endpoint === WECOM_APP_ENDPOINTS.setAccessPolicy) {
+        if (typeof controller.updateAccessPolicy !== 'function') throw new Error('Access policy update is unavailable');
+        value = await controller.updateAccessPolicy(
+          payload.botId, payload.policy, (status) => publicStatus(status),
+        );
+      } else if (endpoint === WECOM_APP_ENDPOINTS.setAgentPreset) {
+        if (typeof controller.updateAgentPreset !== 'function') throw new Error('Agent Preset update is unavailable');
+        value = await publicStatus(await controller.updateAgentPreset(payload.botId, payload.agentPreset));
+      } else {
+        value = await publicStatus(await controller.deleteBot(payload.botId));
+      }
+      return signal?.aborted
+        ? { ok: false, error: { code: 'cancelled', message: 'The request was cancelled.', details: {} } }
+        : { ok: true, value };
+    } catch (error) {
+      const workspaceError = publicWorkspaceError(error);
+      return signal?.aborted
+        ? { ok: false, error: { code: 'cancelled', message: 'The request was cancelled.', details: {} } }
+        : { ok: false, error: workspaceError
+          ? { ...workspaceError, details: {} }
+          : { code: 'wecom-app-operation-failed', message: '企业微信应用操作失败，请稍后重试。', details: {} } };
+    }
+  };
+}
+
+export function installWecomAppRpc(ctx, controller, options, authority) {
+  if (!ctx?.connection?.rpc || typeof ctx.connection.rpc.handle !== 'function') {
+    throw new TypeError('DSH Host Connection RPC is required');
+  }
+  return ctx.connection.rpc.handle(
+    WECOM_APP_RPC_CHANNEL,
+    createWecomAppRpcHandler(controller, options),
+    { authority: resolveRpcAuthority(authority) },
+  );
+}

package/plugin-src/host/channels/weixin/index.mjs

@@ -1,5 +1,6 @@
 import { createProductionController } from './production.mjs';
-import { installWeixinRpc } from './rpc.mjs';
+import { createWeixinRpcHandler, installWeixinRpc, WEIXIN_RPC_CHANNEL } from './rpc.mjs';
+import { installProductionChannel } from '../shared/startup.mjs';
 
 export const name = 'dsh-weixin-host';
 export const inject = ['connection', 'credentials', 'typertGateway'];
@@ -9,20 +10,12 @@ export async function apply(ctx, config = {}) {
     return installWeixinRpc(ctx, config.controller, config.rpcOptions, config.rpcAuthority);
   }
 
-  const production = await createProductionController(ctx, config, config.internals);
-  const unregisterDelivery = config.deliveryService && production.deliveryAdapter
-    ? config.deliveryService.registerAdapter(production.deliveryAdapter) : undefined;
-  const disposeRpc = installWeixinRpc(
-    ctx,
-    production.controller,
-    config.rpcOptions,
-    config.rpcAuthority,
-  );
-  ctx.effect(() => async () => {
-    await unregisterDelivery?.();
-    await production.close();
-  }, 'dsh-weixin: close account connections');
-  return disposeRpc;
+  return installProductionChannel(ctx, config, {
+    channel: 'weixin',
+    rpcChannel: WEIXIN_RPC_CHANNEL,
+    createProduction: () => createProductionController(ctx, config, config.internals),
+    createHandler: controller => createWeixinRpcHandler(controller, config.rpcOptions),
+  });
 }
 
 export function createWeixinHostPlugin(config) {

package/plugin-src/host/channels/whatsapp/index.mjs

@@ -1,5 +1,6 @@
 import { createProductionController } from './production.mjs';
-import { installWhatsappRpc } from './rpc.mjs';
+import { createWhatsappRpcHandler, installWhatsappRpc, WHATSAPP_RPC_CHANNEL } from './rpc.mjs';
+import { installProductionChannel } from '../shared/startup.mjs';
 
 export const name = 'dsh-im-whatsapp-host';
 export const inject = ['connection', 'typertGateway'];
@@ -8,20 +9,12 @@ export async function apply(ctx, config = {}) {
   if (config?.controller) {
     return installWhatsappRpc(ctx, config.controller, config.rpcOptions, config.rpcAuthority);
   }
-  const production = await createProductionController(ctx, config, config.internals ?? {});
-  const unregisterDelivery = config.deliveryService && production.deliveryAdapter
-    ? config.deliveryService.registerAdapter(production.deliveryAdapter) : undefined;
-  const disposeRpc = installWhatsappRpc(
-    ctx,
-    production.controller,
-    config.rpcOptions,
-    config.rpcAuthority,
-  );
-  ctx.effect(() => async () => {
-    await unregisterDelivery?.();
-    await production.close();
-  }, 'dsh-im: close WhatsApp Web connections');
-  return disposeRpc;
+  return installProductionChannel(ctx, config, {
+    channel: 'whatsapp',
+    rpcChannel: WHATSAPP_RPC_CHANNEL,
+    createProduction: () => createProductionController(ctx, config, config.internals ?? {}),
+    createHandler: controller => createWhatsappRpcHandler(controller, config.rpcOptions),
+  });
 }
 
 export function createWhatsappHostPlugin(config) {

package/plugin-src/host/delivery-adapter.mjs

@@ -9,6 +9,7 @@ const CHANNELS = new Set([
   'feishu',
   'dingtalk',
   'wecom',
+  'wecom-app',
   'qq',
   'slack',
   'telegram',
@@ -82,6 +83,9 @@ function normalizeRoute(channel, kind, route) {
     case 'wecom':
       oneOf(kind, ['user', 'group']);
       return routeWithStrings(route, ['chatId']);
+    case 'wecom-app':
+      oneOf(kind, ['user']);
+      return routeWithStrings(route, ['chatId']);
     case 'qq':
       oneOf(kind, ['user', 'group']);
       return routeWithStrings(route, kind === 'user' ? ['userOpenId'] : ['groupOpenId']);

package/plugin-src/host/delivery-suggestions.mjs

@@ -3,6 +3,7 @@ const CHANNELS = new Set([
   'feishu',
   'dingtalk',
   'wecom',
+  'wecom-app',
   'qq',
   'slack',
   'telegram',
@@ -97,6 +98,8 @@ export function deliverySuggestionFromConversationKey(channel, key) {
         ['direct', 'user', 'chatId'],
         ['group', 'group', 'chatId'],
       ]);
+    case 'wecom-app':
+      return simpleSuggestion(key, [['p2p', 'user', 'chatId']]);
     case 'qq':
       return simpleSuggestion(key, [
         ['c2c', 'user', 'userOpenId'],
@@ -124,6 +127,7 @@ export function privateDeliverySuggestionFromConversationKey(channel, key) {
     feishu: 'p2p',
     dingtalk: 'p2p',
     wecom: 'direct',
+    'wecom-app': 'p2p',
     qq: 'c2c',
     slack: 'direct',
     telegram: 'direct',

package/plugin-src/host/index.mjs

@@ -6,6 +6,7 @@ import { apply as applyQq } from './channels/qq/index.mjs';
 import { apply as applySlack } from './channels/slack/index.mjs';
 import { apply as applyTelegram } from './channels/telegram/index.mjs';
 import { apply as applyWecom } from './channels/wecom/index.mjs';
+import { apply as applyWecomApp } from './channels/wecom-app/index.mjs';
 import { apply as applyWeixin } from './channels/weixin/index.mjs';
 import { apply as applyWhatsapp } from './channels/whatsapp/index.mjs';
 import { installOutboundArtifactTool } from '../../src/channels/shared/semantic/artifact.mjs';
@@ -45,6 +46,7 @@ export function createImHostPlugin(internals = {}) {
   const startWeixin = internals.applyWeixin ?? applyWeixin;
   const startDingtalk = internals.applyDingtalk ?? applyDingtalk;
   const startWecom = internals.applyWecom ?? applyWecom;
+  const startWecomApp = internals.applyWecomApp ?? applyWecomApp;
   const startQq = internals.applyQq ?? applyQq;
   const startSlack = internals.applySlack ?? applySlack;
   const startTelegram = internals.applyTelegram ?? applyTelegram;
@@ -56,6 +58,7 @@ export function createImHostPlugin(internals = {}) {
     ['weixin', startWeixin],
     ['dingtalk', startDingtalk],
     ['wecom', startWecom],
+    ['wecomApp', startWecomApp],
     ['qq', startQq],
     ['slack', startSlack],
     ['telegram', startTelegram],
@@ -145,14 +148,16 @@ export function createImHostPlugin(internals = {}) {
       }
     }
     const failures = [];
-    for (const [channel, start] of channels) {
+    // Each channel mounts its management RPC before awaiting initialization.
+    // Start them together so a slow channel cannot leave later routes absent.
+    await Promise.all(channels.map(async ([channel, start]) => {
       try {
         await start(ctx, channelConfig(config, channel, deliveryService));
       } catch (error) {
         failures.push(error);
         logger.error?.(`[dsh-im] failed to activate ${channel}; continuing with the remaining channels`, error);
       }
-    }
+    }));
     if (failures.length === channels.length) {
       throw new AggregateError(failures, 'dsh-im failed to activate every channel');
     }

package/scripts/verify-model-setting.mjs

@@ -0,0 +1,54 @@
+// Exercise the actual settings card in Chromium without a running Host or IM account.
+// Usage: node scripts/verify-model-setting.mjs [output-directory]
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { build } from 'esbuild';
+
+const browser = process.env.CHROME_PATH ?? [
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome',
+].find(existsSync);
+if (!browser) throw new Error('Set CHROME_PATH to a Chromium/Chrome executable.');
+const output = process.argv[2] ? resolve(process.argv[2]) : await mkdtemp(join(tmpdir(), 'dsh-im-model-ui-'));
+await mkdir(output, { recursive: true });
+const built = await build({
+  entryPoints: [resolve(import.meta.dirname, '../test/browser/model-setting.fixture.js')],
+  bundle: true, write: false, format: 'iife', platform: 'browser', target: 'chrome100',
+  define: { 'process.env.NODE_ENV': '"development"' },
+});
+const htmlPath = join(output, 'preview.html');
+await writeFile(htmlPath, `<!doctype html><html lang="zh-CN"><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>DSH-IM Model Settings</title>
+<style>
+body{margin:0;padding:24px;background:#fff;color:#1f2329;font:14px/20px -apple-system,BlinkMacSystemFont,sans-serif}#app{max-width:760px;margin:auto}#result{max-width:760px;margin:18px auto;font:11px/17px monospace;white-space:pre-wrap;color:#687380}
+@media(max-width:600px){body{padding:12px}}
+@media(prefers-color-scheme:dark){:root{color-scheme:dark;--dsw-alias-bg-layer-1:#202125;--dsw-alias-bg-layer-3:#282a30;--dsw-specific-menu:#282a30;--dsw-alias-bg-module-platform:#25272c;--dsw-alias-label-primary:#e9ebef;--dsw-alias-label-secondary:#b1b5bf;--dsw-alias-label-tertiary:#9a9faa;--dsw-alias-border-l1:#34363c;--dsw-alias-border-l2:#41434c;--dsw-alias-border-l3:#7b9ff9;--dsw-alias-interactive-bg-hover:#353842}body{background:#202125;color:#e9ebef}}
+</style><body><div id="app"></div><pre id="result">Running browser checks…</pre><script>${built.outputFiles[0].text.replace(/<\/script/giu, '<\\/script')}</script></body></html>`);
+for (const [name, size, extra, query] of [
+  ['desktop', '1100,1100', [], ''],
+  ['mobile', '390,1250', [], '?mobile'],
+  ['dark-en', '1100,1100', ['--force-dark-mode'], '?en'],
+]) {
+  const profile = await mkdtemp(join(tmpdir(), 'dsh-im-model-browser-'));
+  const { stdout, stderr } = await promisify(execFile)(browser, [
+    '--headless', '--disable-gpu', '--no-sandbox', '--hide-scrollbars',
+    `--user-data-dir=${profile}`, '--no-first-run', '--no-default-browser-check',
+    `--window-size=${size}`, '--force-device-scale-factor=1', '--virtual-time-budget=8000',
+    ...extra, `--screenshot=${join(output, `${name}.png`)}`, '--dump-dom', pathToFileURL(htmlPath).href + query,
+  ], { maxBuffer: 8 * 1024 * 1024, timeout: 15_000, killSignal: 'SIGKILL' }).catch((error) => {
+    // Some desktop Chromium builds finish dump-dom and the screenshot but
+    // hang during shutdown. Only accept a fully returned fixture result.
+    if (error.killed && /<body\b[^>]*\bdata-result="(?:passed|failed)"/u.test(error.stdout ?? '')) return error;
+    throw error;
+  }).finally(() => rm(profile, { recursive: true, force: true }));
+  await writeFile(join(output, `${name}.html`), stdout);
+  await writeFile(join(output, `${name}.log`), stderr);
+  const result = stdout.match(/<pre id="result">([\s\S]*?)<\/pre>/u)?.[1] ?? 'No browser result';
+  if (!stdout.includes('data-result="passed"')) throw new Error(`${name}: ${result}`);
+  console.log(`${name}: ${result}`);
+}
+console.log(`Previews: ${output}`);

package/src/channels/dingtalk/dingtalk-api.mjs

@@ -337,10 +337,13 @@ function cardMarkdown(text, target) {
 }
 
 function cardData(text, flowStatus, target) {
+  const markdown = cardMarkdown(text, target);
+  // The shared template uses msgContent for processing, finished, and
+  // failed cards. Switching its order to staticMsgContent hides the reply.
   return {
     cardParamMap: {
       flowStatus,
-      msgContent: cardMarkdown(text, target),
+      msgContent: markdown,
       staticMsgContent: '',
       sys_full_json_obj: JSON.stringify({ order: ['msgContent'] }),
       config: JSON.stringify({ autoLayout: true }),
@@ -922,13 +925,17 @@ export function createDingtalkApi({
 
       let delivered = false;
       try {
-        await cardRequest('v1.0/card/instances', {
+        // Deliver the thinking copy in the same request that first shows the
+        // card. Creating an empty instance and filling it after deliver (the
+        // previous three-request sequence) leaves a blank bubble visible in
+        // DingTalk for the time between deliver and the follow-up PUT, and
+        // leaves a permanently blank card if that PUT ever fails.
+        await cardRequest('v1.0/card/instances/createAndDeliver', {
           body: {
+            ...cardDeliverBody(cardInstanceId, normalizedTarget, appKey),
             cardTemplateId: DINGTALK_AI_CARD_TEMPLATE_ID,
             outTrackId: cardInstanceId,
-            cardData: {
-              cardParamMap: { config: JSON.stringify({ autoLayout: true }) },
-            },
+            cardData: cardData(content, '2', normalizedTarget),
             callbackType: 'STREAM',
             cardAtUserIds: normalizedTarget.atUserIds
               ? Object.keys(normalizedTarget.atUserIds)
@@ -938,37 +945,31 @@ export function createDingtalkApi({
           },
           headers,
           signal,
-          action: 'AI Card 创建',
-        });
-        await cardRequest('v1.0/card/instances/deliver', {
-          body: cardDeliverBody(cardInstanceId, normalizedTarget, appKey),
-          headers,
-          signal,
-          action: 'AI Card 投放',
+          action: 'AI Card 创建并投放',
         });
         delivered = true;
-        await cardRequest('v1.0/card/instances', {
-          method: 'PUT',
-          body: { outTrackId: cardInstanceId, cardData: cardData(content, '2', normalizedTarget) },
-          headers,
-          signal,
-          action: 'AI Card 启动',
-        });
-        await cardRequest('v1.0/card/streaming', {
-          method: 'PUT',
-          body: {
-            outTrackId: cardInstanceId,
-            guid: randomUUID(),
-            key: 'msgContent',
-            content: cardMarkdown(content, normalizedTarget).replace(/\n+$/, ''),
-            isFull: true,
-            isFinalize: false,
-            isError: false,
-          },
-          headers,
-          signal,
-          action: 'AI Card 启动',
-        });
+        try {
+          await cardRequest('v1.0/card/streaming', {
+            method: 'PUT',
+            body: {
+              outTrackId: cardInstanceId,
+              guid: randomUUID(),
+              key: 'msgContent',
+              content: cardMarkdown(content, normalizedTarget).replace(/\n+$/, ''),
+              isFull: true,
+              isFinalize: false,
+              isError: false,
+            },
+            headers,
+            signal,
+            action: 'AI Card 启动',
+          });
+        } catch (error) {
+          if (signal?.aborted) throw error;
+          // The card is already visible with the thinking copy from
+          // createAndDeliver above. Keep the instance so finishAiCard can
+          // still replace it in place instead of sending a second message.
+        }
       } catch (error) {
         if (delivered) {
           const cleanupSignal = AbortSignal.timeout(5_000);
@@ -1018,6 +1019,8 @@ export function createDingtalkApi({
       const token = await accessToken({ clientId, clientSecret, signal });
       const headers = { 'x-acs-dingtalk-access-token': token };
       const normalizedContent = cardMarkdown(content, target);
+      // Close the streaming widget before persisting the template's
+      // finished state and full answer in msgContent.
       await cardRequest('v1.0/card/streaming', {
         method: 'PUT',
         body: {
@@ -1033,8 +1036,7 @@ export function createDingtalkApi({
         signal,
         action: 'AI Card 完成',
       });
-      let completed = true;
-      const completionRequest = {
+      await cardRequest('v1.0/card/instances', {
         method: 'PUT',
         body: {
           outTrackId: instanceId,
@@ -1043,18 +1045,9 @@ export function createDingtalkApi({
         },
         headers,
         signal,
-        action: 'AI Card 收口',
-      };
-      try {
-        await cardRequest('v1.0/card/instances', completionRequest);
-      } catch {
-        try {
-          await cardRequest('v1.0/card/instances', completionRequest);
-        } catch {
-          completed = false;
-        }
-      }
-      return { delivered: true, completed };
+        action: 'AI Card 完成状态',
+      });
+      return { delivered: true, completed: true };
     },
 
     failAiCard: failCard,

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

@@ -1336,6 +1336,8 @@ export class DingtalkHarnessBridge {
             providerMessageIds: cardStream.providerMessageIds,
           });
         } else {
+          // Failed streams close the card with a notice pointing to a
+          // follow-up message. Deliver the answer through that fallback.
           textReceipt = createDeliveryReceipt({
             deliveryId: messageId,
             presentation: 'dingtalk-text',
@@ -1411,7 +1413,9 @@ export class DingtalkHarnessBridge {
           ? `${errorText}\n\n${batchFailureMessage}`
           : errorText;
         const streamed = cardStarted && await cardStream.finish(visibleError);
-        if (!streamed) await this.#send(sessionWebhook, visibleError, this.#atUsersFor(message));
+        if (!streamed) {
+          await this.#send(sessionWebhook, visibleError, this.#atUsersFor(message));
+        }
       } catch {
         this.#logger.error?.('[dsh-dingtalk] failed to send the safe error reply');
       }