@zhin.js/adapter-dingtalk 1.1.3 → 1.1.5

package/lib/protocol.d.ts

@@ -6,21 +6,29 @@ import type { IncomingMessage } from 'node:http';
 import { type ConversationRef } from '@zhin.js/im-contract';
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
 export interface DingTalkEndpointConfig {
+    readonly streamProxy?: import('./stream-proxy.js').DingTalkStreamProxy;
     readonly id: string;
     readonly appKey: string;
     readonly appSecret: string;
+    readonly mode?: 'webhook' | 'stream';
     readonly webhookPath?: string;
     readonly robotCode?: string;
     readonly apiBaseUrl?: string;
+    readonly cardTemplateId?: string;
+    readonly cardButtonCount?: number;
 }
 export interface ResolvedDingTalkConfig {
+    readonly streamProxy?: import('./stream-proxy.js').DingTalkStreamProxy;
     readonly context: 'dingtalk';
+    readonly mode?: 'webhook' | 'stream';
     readonly id: string;
     readonly appKey: string;
     readonly appSecret: string;
     readonly webhookPath: string;
     readonly robotCode?: string;
     readonly apiBaseUrl: string;
+    readonly cardTemplateId?: string;
+    readonly cardButtonCount?: number;
 }
 export interface DingTalkMessage {
     readonly msgtype?: string;
@@ -35,6 +43,7 @@ export interface DingTalkMessage {
     readonly senderNick?: string;
     readonly senderCorpId?: string;
     readonly sessionWebhook?: string;
+    readonly sessionWebhookExpiredTime?: number;
     readonly chatbotCorpId?: string;
     readonly chatbotUserId?: string;
     readonly isAdmin?: boolean;
@@ -119,9 +128,8 @@ export declare function verifySignature(appSecret: string, timestamp: string, si
  * Segment canonicalization is intentionally not done here: media segments carry
  * the canonical `data.media` MediaRef and nothing else is consulted.
  *
- * 钉钉机器人媒体消息仅支持远程 URL（picture.picURL）：
- * - image 段 kind=url → 直发 picture；
- * - 其余 kind / audio / video / file 段无投递面，warn + 丢弃。
+ * 钉钉机器人图片使用官方 Markdown HTTP(S) 图片链接，保留同载荷文本和图片顺序。
+ * 本地媒体上传、原生引用、音频/视频/文件未接线，在请求前明确拒绝。
  */
 export declare function formatOutboundBody(payload: unknown): DingTalkSendBody;
 export declare function headerValue(headers: IncomingMessage['headers'], name: string): string;

package/lib/protocol.js

@@ -3,9 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import { createHmac, timingSafeEqual } from 'node:crypto';
-import { isMediaRef } from '@zhin.js/im-contract';
-import { formatCompact, getLogger } from '@zhin.js/logger';
-const logger = getLogger('dingtalk');
+import { EndpointDeliveryError, isMediaRef } from '@zhin.js/im-contract';
 /**
  * 钉钉回调消息 @ 机器人判定：机器人被 @ 时回调带 `isInAtList: true`；
  * 部分回调形态的 `atUserIds` / `atUsers[].dingtalkId` 会包含机器人 robotCode（来自配置）。
@@ -23,20 +21,31 @@ export function isDingtalkBotMentioned(event, robotCode) {
     return (event.atUsers ?? []).some((user) => user.dingtalkId === robotCode);
 }
 export function resolveDingTalkConfig(config) {
+    if (config.streamProxy && (!Number.isInteger(config.streamProxy.port) || config.streamProxy.port < 1 || config.streamProxy.port > 65535
+        || typeof config.streamProxy.serverName !== 'string' || !config.streamProxy.serverName || /[\s/:@?#]/.test(config.streamProxy.serverName)))
+        throw new TypeError('Invalid DingTalk streamProxy port/serverName');
+    if (config.mode !== undefined && !['webhook', 'stream'].includes(config.mode))
+        throw new TypeError('Invalid DingTalk mode');
     const id = requiredEndpointField(config.id, 'id');
     const appKey = requiredEndpointField(config.appKey, 'appKey');
     const appSecret = requiredEndpointField(config.appSecret, 'appSecret');
     const webhookPath = normalizeWebhookPath(config.webhookPath ?? '/dingtalk/webhook');
     const apiBaseUrl = (config.apiBaseUrl ?? 'https://oapi.dingtalk.com').replace(/\/$/, '');
     const robotCode = config.robotCode;
+    if (config.cardButtonCount !== undefined && (!Number.isInteger(config.cardButtonCount) || config.cardButtonCount < 1 || config.cardButtonCount > 5))
+        throw new TypeError('cardButtonCount must be 1..5');
     return {
+        ...(config.streamProxy ? { streamProxy: config.streamProxy } : {}),
         context: 'dingtalk',
+        mode: config.mode ?? 'webhook',
         id,
         appKey,
         appSecret,
         webhookPath,
         ...(robotCode ? { robotCode } : {}),
         apiBaseUrl,
+        ...(config.cardTemplateId ? { cardTemplateId: config.cardTemplateId } : {}),
+        cardButtonCount: config.cardButtonCount ?? 2,
     };
 }
 function requiredEndpointField(value, field) {
@@ -131,9 +140,8 @@ export function verifySignature(appSecret, timestamp, sign) {
  * Segment canonicalization is intentionally not done here: media segments carry
  * the canonical `data.media` MediaRef and nothing else is consulted.
  *
- * 钉钉机器人媒体消息仅支持远程 URL（picture.picURL）：
- * - image 段 kind=url → 直发 picture；
- * - 其余 kind / audio / video / file 段无投递面，warn + 丢弃。
+ * 钉钉机器人图片使用官方 Markdown HTTP(S) 图片链接，保留同载荷文本和图片顺序。
+ * 本地媒体上传、原生引用、音频/视频/文件未接线，在请求前明确拒绝。
  */
 export function formatOutboundBody(payload) {
     if (typeof payload === 'string') {
@@ -174,34 +182,50 @@ export function formatOutboundBody(payload) {
                 }
                 break;
             }
-            case 'image': {
+            case 'reply':
+                throw new EndpointDeliveryError('unsupported_operation', 'DingTalk native quoted replies are not implemented', 'not_sent');
+            case 'share': {
+                if (['audio', 'artist', 'duration', 'config'].some(key => data[key] !== undefined)) {
+                    throw new EndpointDeliveryError('unsupported_operation', 'dingtalk rich share metadata is not implemented', 'not_sent');
+                }
+                let url;
+                try {
+                    url = new URL(String(data.url ?? ''));
+                }
+                catch {
+                    throw new EndpointDeliveryError('invalid_payload', 'DingTalk share requires an HTTP(S) URL', 'not_sent');
+                }
+                if (!['https:', 'http:'].includes(url.protocol))
+                    throw new EndpointDeliveryError('invalid_payload', 'DingTalk share requires an HTTP(S) URL', 'not_sent');
                 if (media)
-                    break;
+                    throw new EndpointDeliveryError('invalid_payload', 'DingTalk accepts one link card per message', 'not_sent');
+                media = { msgtype: 'link', link: { title: String(data.title ?? '链接'), text: String(data.description ?? data.content ?? ''), messageUrl: url.toString(), ...(typeof data.image === 'string' ? { picUrl: data.image } : {}) } };
+                break;
+            }
+            case 'keyboard':
+                throw new EndpointDeliveryError('unsupported_operation', 'DingTalk native keyboard callback requires an interactive card template and is not implemented', 'not_sent');
+            case 'image': {
                 const ref = data.media;
                 if (isMediaRef(ref) && ref.kind === 'url') {
-                    media = {
-                        msgtype: 'picture',
-                        picture: { picURL: ref.value },
-                    };
+                    let url;
+                    try {
+                        url = new URL(ref.value);
+                    }
+                    catch {
+                        throw new EndpointDeliveryError('invalid_payload', 'DingTalk image requires an HTTP(S) URL', 'not_sent');
+                    }
+                    if (!['https:', 'http:'].includes(url.protocol))
+                        throw new EndpointDeliveryError('invalid_payload', 'DingTalk image requires an HTTP(S) URL', 'not_sent');
+                    markdownTitle ??= '消息';
+                    textParts.push(`\n![](${ref.value.replace(/[()\s]/g, character => encodeURIComponent(character))})\n`);
                     break;
                 }
-                logger.warn(formatCompact({
-                    op: 'dingtalk_outbound_media_dropped',
-                    type: item.type,
-                    reason: isMediaRef(ref) ? `unsupported_kind:${ref.kind}` : 'missing_media_ref',
-                }));
-                break;
+                throw new EndpointDeliveryError('unsupported_operation', 'DingTalk image upload is not implemented; use a canonical HTTP(S) URL', 'not_sent');
             }
             case 'audio':
             case 'video':
             case 'file':
-                // 钉钉机器人无音频/视频/文件投递面，warn + 丢弃
-                logger.warn(formatCompact({
-                    op: 'dingtalk_outbound_media_dropped',
-                    type: item.type,
-                    reason: 'undeliverable_msgtype',
-                }));
-                break;
+                throw new EndpointDeliveryError('unsupported_operation', 'DingTalk audio/video/file delivery is not implemented', 'not_sent');
             case 'markdown':
                 markdownTitle ??= String(data.title || '消息');
                 textParts.push(String(data.content ?? data.text ?? ''));
@@ -224,7 +248,7 @@ export function formatOutboundBody(payload) {
         }
     }
     if (media)
-        return media;
+        return media.link && textParts.length ? { ...media, link: { ...media.link, text: [...textParts, media.link.text].filter(Boolean).join('\n') } } : media;
     if (markdownTitle !== undefined) {
         return {
             msgtype: 'markdown',

package/lib/stream-proxy.d.ts

@@ -0,0 +1,7 @@
+import WebSocket from 'ws';
+export interface DingTalkStreamProxy {
+    readonly port: number;
+    readonly serverName: string;
+}
+/** Route TCP only. WSS HTTP Host, path, ticket, TLS SNI and peer validation stay original. */
+export declare function createDingTalkStreamSocket(url: string, proxy?: DingTalkStreamProxy): WebSocket;

package/lib/stream-proxy.js

@@ -0,0 +1,18 @@
+import tls from 'node:tls';
+import WebSocket from 'ws';
+import { getLogger } from '@zhin.js/logger';
+/** Route TCP only. WSS HTTP Host, path, ticket, TLS SNI and peer validation stay original. */
+export function createDingTalkStreamSocket(url, proxy) {
+    if (!proxy)
+        return new WebSocket(url);
+    const target = new URL(url);
+    if (target.protocol !== 'wss:' || target.hostname !== proxy.serverName || (target.port && target.port !== '443')) {
+        // The hostname is safe diagnostics; never print URL/query/ticket or SDK errors.
+        getLogger('dingtalk').warn(`Stream proxy rejected gateway hostname: ${target.hostname}`);
+        throw new Error('DingTalk Stream proxy gateway identity changed; update the fixed upstream before retrying');
+    }
+    return new WebSocket(url, {
+        createConnection: (options) => tls.connect({ ...options, path: undefined, host: '127.0.0.1', port: proxy.port,
+            servername: target.hostname, rejectUnauthorized: true }),
+    });
+}

package/lib/stream.d.ts

@@ -0,0 +1,25 @@
+import type { DingTalkFetch } from './endpoint.js';
+import type { DingTalkEvent, ResolvedDingTalkConfig } from './protocol.js';
+export declare const CARD_TOPIC = "/v1.0/card/instances/callback";
+export declare const ROBOT_TOPIC = "/v1.0/im/bot/messages/get";
+export interface DingTalkStreamSocket {
+    on(event: string, listener: (...args: any[]) => void): unknown;
+    send(data: string): void;
+    terminate(): void;
+    ping(): void;
+}
+export type DingTalkStreamSocketFactory = (url: string) => DingTalkStreamSocket;
+/** Official gateway wire contract; reconnect/heartbeat belong to the shared lifecycle. */
+export declare class DingTalkStream {
+    #private;
+    readonly config: ResolvedDingTalkConfig;
+    readonly fetch: DingTalkFetch;
+    readonly admit: (event: DingTalkEvent) => Promise<void>;
+    readonly isOpen: () => boolean;
+    readonly createSocket: DingTalkStreamSocketFactory;
+    readonly admitCard?: ((event: import("./cards.js").DingTalkCardCallback, id: string) => Promise<void>) | undefined;
+    readonly lifecycle: import("@zhin.js/adapter").EndpointLifecycle;
+    constructor(config: ResolvedDingTalkConfig, fetch: DingTalkFetch, admit: (event: DingTalkEvent) => Promise<void>, isOpen: () => boolean, createSocket?: DingTalkStreamSocketFactory, admitCard?: ((event: import("./cards.js").DingTalkCardCallback, id: string) => Promise<void>) | undefined);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}

package/lib/stream.js

@@ -0,0 +1,138 @@
+import { createDingTalkStreamSocket } from './stream-proxy.js';
+import { createEndpointLifecycle } from 'zhin.js/adapter';
+export const CARD_TOPIC = '/v1.0/card/instances/callback';
+export const ROBOT_TOPIC = '/v1.0/im/bot/messages/get';
+/** Official gateway wire contract; reconnect/heartbeat belong to the shared lifecycle. */
+export class DingTalkStream {
+    config;
+    fetch;
+    admit;
+    isOpen;
+    createSocket;
+    admitCard;
+    lifecycle;
+    #active;
+    #socket;
+    #seen = new Map();
+    #pending = new Set();
+    constructor(config, fetch, admit, isOpen, createSocket = (url) => createDingTalkStreamSocket(url, config.streamProxy), admitCard) {
+        this.config = config;
+        this.fetch = fetch;
+        this.admit = admit;
+        this.isOpen = isOpen;
+        this.createSocket = createSocket;
+        this.admitCard = admitCard;
+        this.lifecycle = createEndpointLifecycle({ name: config.id, heartbeat: { intervalMs: 30_000, watchdogMisses: 2 } });
+    }
+    async start() {
+        await this.lifecycle.start(async (handle) => {
+            const controller = new AbortController();
+            this.#active = controller;
+            const transport = {};
+            handle.onForceClose(() => { controller.abort(); transport.socket?.terminate(); });
+            const response = await this.fetch('https://api.dingtalk.com/v1.0/gateway/connections/open', {
+                method: 'POST', headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+                body: JSON.stringify({ clientId: this.config.appKey, clientSecret: this.config.appSecret,
+                    subscriptions: [{ type: 'CALLBACK', topic: ROBOT_TOPIC }, ...(this.admitCard && this.config.cardTemplateId ? [{ type: 'CALLBACK', topic: CARD_TOPIC }] : [])], ua: 'zhin.js' }),
+                signal: AbortSignal.any([controller.signal, AbortSignal.timeout(30_000)]),
+            });
+            if (!response.ok)
+                throw new Error(`DingTalk Stream gateway HTTP ${response.status}`);
+            const gateway = await response.json();
+            if (controller.signal.aborted)
+                return;
+            if (!gateway.endpoint || !gateway.ticket)
+                throw new Error('Invalid DingTalk Stream gateway response');
+            const url = new URL(gateway.endpoint);
+            if (url.protocol !== 'wss:')
+                throw new Error('DingTalk Stream requires WSS');
+            url.searchParams.set('ticket', gateway.ticket);
+            const current = this.createSocket(url.toString());
+            transport.socket = current;
+            this.#socket = current;
+            await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => { current.terminate(); reject(new Error('DingTalk Stream connection timeout')); }, 30_000);
+                const clear = () => clearTimeout(timer);
+                controller.signal.addEventListener('abort', clear, { once: true });
+                current.on('open', () => {
+                    if (controller.signal.aborted || this.#socket !== current) {
+                        current.terminate();
+                        return;
+                    }
+                    clear();
+                    this.lifecycle.startHeartbeat(() => current.ping());
+                    resolve();
+                });
+                current.on('error', () => { clear(); current.terminate(); reject(new Error('DingTalk Stream transport error')); });
+                current.on('close', () => {
+                    clear();
+                    if (this.#socket === current)
+                        this.#socket = undefined;
+                    handle.notifyClosed('transport closed');
+                    reject(new Error('DingTalk Stream closed before connection'));
+                });
+                current.on('pong', () => { if (!controller.signal.aborted)
+                    this.lifecycle.notifyHeartbeatAck(); });
+                current.on('message', (raw) => {
+                    if (controller.signal.aborted || this.#socket !== current)
+                        return;
+                    this.lifecycle.notifyHeartbeatAck();
+                    let frame;
+                    try {
+                        frame = JSON.parse(raw.toString());
+                    }
+                    catch {
+                        return;
+                    }
+                    if (frame.type === 'SYSTEM') {
+                        // REGISTERED is optional; successful WSS handshake already establishes the subscribed transport.
+                        if (frame.headers?.topic === 'ping' || frame.headers?.topic === 'disconnect') {
+                            current.send(JSON.stringify({ code: 200, headers: frame.headers, message: 'OK', data: frame.data }));
+                            if (frame.headers.topic === 'disconnect')
+                                current.terminate();
+                        }
+                        return;
+                    }
+                    if (frame.type !== 'CALLBACK' || ![ROBOT_TOPIC, ...(this.admitCard && this.config.cardTemplateId ? [CARD_TOPIC] : [])].includes(frame.headers?.topic ?? '') || !frame.headers?.messageId)
+                        return;
+                    const id = frame.headers.messageId;
+                    const ack = () => {
+                        if (!controller.signal.aborted && this.#socket === current)
+                            current.send(JSON.stringify({ code: 200,
+                                headers: { contentType: 'application/json', messageId: id }, message: 'OK', data: JSON.stringify({ response: null }) }));
+                    };
+                    const now = Date.now();
+                    for (const [key, time] of this.#seen)
+                        if (now - time > 300_000)
+                            this.#seen.delete(key);
+                    if (this.#seen.has(id)) {
+                        ack();
+                        return;
+                    }
+                    if (!this.isOpen() || this.#pending.has(id) || this.#pending.size >= 100)
+                        return;
+                    let event;
+                    try {
+                        event = JSON.parse(frame.data ?? '');
+                    }
+                    catch {
+                        return;
+                    }
+                    const card = frame.headers.topic === CARD_TOPIC;
+                    if (!event || typeof event !== 'object' || (!card && !event.msgtype))
+                        return;
+                    this.#pending.add(id);
+                    void (card ? this.admitCard(event, id) : this.admit(event)).then(() => {
+                        if (controller.signal.aborted)
+                            return;
+                        this.#seen.set(id, Date.now());
+                        while (this.#seen.size > 10_000)
+                            this.#seen.delete(this.#seen.keys().next().value);
+                        ack();
+                    }).catch(() => { }).finally(() => this.#pending.delete(id));
+                });
+            });
+        });
+    }
+    async stop() { this.#active?.abort(); await this.lifecycle.stop(); this.#socket = undefined; this.#seen.clear(); }
+}

package/lib/webhook.d.ts

@@ -7,7 +7,7 @@ import { type DingTalkEvent, type ResolvedDingTalkConfig } from './protocol.js';
 export interface DingTalkWebhookHandler {
     readonly config: ResolvedDingTalkConfig;
     readonly isOpen: boolean;
-    admit(event: DingTalkEvent): void;
+    admit(event: DingTalkEvent): void | Promise<void>;
 }
 export declare function registerDingTalkWebhookRoutes(http: HttpHost, handler: DingTalkWebhookHandler): HttpRouteRegistration[];
 export declare function handleDingTalkWebhookRequest(request: IncomingMessage, response: ServerResponse, handler: DingTalkWebhookHandler): Promise<void>;

package/lib/webhook.js

@@ -34,7 +34,7 @@ export async function handleDingTalkWebhookRequest(request, response, handler) {
             return;
         }
         if (event.msgtype && handler.isOpen) {
-            handler.admit(event);
+            await handler.admit(event);
         }
         response.writeHead(200, { 'Content-Type': 'application/json' });
         response.end(JSON.stringify({ code: 0, msg: 'success' }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-dingtalk",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Zhin.js DingTalk (钉钉) adapter for Plugin Runtime (HTTP webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,24 +33,25 @@
     "directory": "plugins/adapters/dingtalk"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.15",
-    "@zhin.js/agent-feature": "1.1.2",
-    "@zhin.js/core": "1.1.38",
+    "ws": "^8.18.3",
+    "@zhin.js/adapter": "1.1.16",
+    "@zhin.js/agent-feature": "1.1.3",
+    "@zhin.js/core": "1.1.40",
     "@zhin.js/feature-kit": "1.1.2",
-    "@zhin.js/host-http": "1.1.2",
-    "@zhin.js/im-contract": "1.1.2",
+    "@zhin.js/host-http": "1.1.3",
+    "@zhin.js/im-contract": "1.1.3",
     "@zhin.js/logger": "1.1.1",
-    "@zhin.js/skill": "1.1.2",
-    "@zhin.js/tool": "1.1.2"
+    "@zhin.js/skill": "1.1.3",
+    "@zhin.js/tool": "1.1.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.15",
-    "@zhin.js/command": "^1.1.2",
-    "@zhin.js/core": "^1.1.38",
-    "@zhin.js/host-http": "^1.1.2",
-    "@zhin.js/permission": "^1.1.2",
-    "zhin.js": "^1.1.3"
+    "@zhin.js/adapter": "^1.1.16",
+    "@zhin.js/command": "^1.1.4",
+    "@zhin.js/core": "^1.1.40",
+    "@zhin.js/host-http": "^1.1.3",
+    "@zhin.js/permission": "^1.1.3",
+    "zhin.js": "^1.1.5"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -68,7 +69,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "zhin.js": "1.1.3"
+    "@types/ws": "^8.18.1",
+    "zhin.js": "1.1.5"
   },
   "files": [
     "adapters",

package/schema.json

@@ -76,6 +76,47 @@
           "id": {
             "type": "string",
             "description": "Dingtalk bot name"
+          },
+          "mode": {
+            "type": "string",
+            "enum": [
+              "webhook",
+              "stream"
+            ],
+            "default": "webhook"
+          },
+          "cardTemplateId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Stream interactive card template ID"
+          },
+          "cardButtonCount": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 5,
+            "default": 2,
+            "description": "Fixed button count in the card template"
+          },
+          "streamProxy": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "port": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535
+              },
+              "serverName": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^[^\\s/:@?#]+$"
+              }
+            },
+            "required": [
+              "port",
+              "serverName"
+            ],
+            "description": "故障验收专用：TCP固定127.0.0.1，保留真实WSS TLS身份"
           }
         },
         "required": [
@@ -89,6 +130,26 @@
       "type": "string",
       "default": "",
       "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    },
+    "mode": {
+      "type": "string",
+      "enum": [
+        "webhook",
+        "stream"
+      ],
+      "default": "webhook"
+    },
+    "cardTemplateId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stream interactive card template ID"
+    },
+    "cardButtonCount": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 5,
+      "default": 2,
+      "description": "Fixed button count in the card template"
     }
   },
   "required": [

package/src/cards.ts

@@ -0,0 +1,62 @@
+import { randomUUID } from 'node:crypto';
+import { EndpointDeliveryError, type ConversationRef } from '@zhin.js/im-contract';
+import type { DingTalkMessage, ResolvedDingTalkConfig } from './protocol.js';
+
+export interface DingTalkCardCallback { outTrackId?: string; spaceType?: string; spaceId?: string; userId?: string; userIdType?: number; corpId?: string; content?: string }
+interface CardRecord { conversation: ConversationRef; spaceType: string; spaceId: string; staffId?: string; senderId?: string; corpId?: string; payloads: Set<string>; expiresAt: number }
+/** Endpoint-owned, bounded correlation. Cards from old generations deliberately cannot dispatch. */
+export class DingTalkCards {
+  #epoch = 0;
+  #records = new Map<string, CardRecord>();
+  #contexts = new Map<string, DingTalkMessage>();
+  remember(conversation: ConversationRef, event: DingTalkMessage): void {
+    this.#contexts.delete(conversation.id); this.#contexts.set(conversation.id, event);
+    while (this.#contexts.size > 1024) this.#contexts.delete(this.#contexts.keys().next().value!);
+  }
+  clear(): void { this.#epoch++; this.#records.clear(); this.#contexts.clear(); }
+  prepare(config: ResolvedDingTalkConfig, conversation: ConversationRef, payload: unknown) {
+    const segments = Array.isArray(payload) ? payload : [payload];
+    const keyboard = segments.filter(item => item && typeof item === 'object' && item.type === 'keyboard');
+    if (!keyboard.length) return undefined;
+    if (config.mode !== 'stream' || !config.cardTemplateId) throw new EndpointDeliveryError('card_template_required', 'DingTalk callbacks require a configured Stream card template', 'not_sent');
+    if (keyboard.length !== 1) throw new EndpointDeliveryError('invalid_payload', 'DingTalk supports one keyboard per card', 'not_sent');
+    const rows = keyboard[0].data?.rows;
+    if (!Array.isArray(rows) || rows.some(row => !Array.isArray(row))) throw new EndpointDeliveryError('invalid_payload', 'DingTalk keyboard requires button rows', 'not_sent');
+    const buttons = rows.flat();
+    const count = config.cardButtonCount ?? 2;
+    if (!buttons.length || buttons.length > count || buttons.some((button: any) => typeof button.label !== 'string' || typeof button.payload !== 'string' || !button.payload || button.disabled)) throw new EndpointDeliveryError('invalid_payload', 'DingTalk keyboard exceeds the fixed template or contains invalid/disabled buttons', 'not_sent');
+    const context = this.#contexts.get(conversation.id);
+    if (!context || (conversation.kind !== 'group' && conversation.kind !== 'private')) throw new EndpointDeliveryError('card_context_required', 'DingTalk card requires a current inbound conversation', 'not_sent');
+    const spaceType = conversation.kind === 'group' ? 'IM_GROUP' : 'IM_ROBOT';
+    const spaceId = spaceType === 'IM_GROUP' ? conversation.id : context.senderStaffId;
+    if (!spaceId) throw new EndpointDeliveryError('card_context_required', 'DingTalk private card requires senderStaffId', 'not_sent');
+    const text = segments.filter(item => item?.type !== 'keyboard').map(item => {
+      if (typeof item === 'string') return item;
+      if (item?.type === 'text' || item?.type === 'markdown') return String(item.data?.text ?? item.data?.content ?? '');
+      throw new EndpointDeliveryError('invalid_payload', 'DingTalk interactive cards accept text/markdown and keyboard only', 'not_sent');
+    }).join('');
+    const cardParamMap: Record<string, string> = { title: '消息', text };
+    for (let i = 0; i < count; i++) { cardParamMap[`button${i}_label`] = buttons[i]?.label ?? ''; cardParamMap[`button${i}_payload`] = buttons[i]?.payload ?? ''; cardParamMap[`button${i}_visible`] = buttons[i] ? 'true' : 'false'; }
+    const id = randomUUID();
+    const record: CardRecord = { conversation, spaceType, spaceId, staffId: context.senderStaffId, senderId: context.senderId, corpId: context.senderCorpId, payloads: new Set(buttons.map((button: any) => button.payload)), expiresAt: Date.now() + 3_600_000 };
+    return { id, record, epoch: this.#epoch, body: { cardTemplateId: config.cardTemplateId, outTrackId: id, cardData: { cardParamMap }, callbackType: 'STREAM', userIdType: 1, openSpaceId: `dtv1.card//${spaceType}.${spaceId}`, imGroupOpenSpaceModel: { supportForward: false }, imRobotOpenSpaceModel: { supportForward: false }, ...(spaceType === 'IM_GROUP' ? { imGroupOpenDeliverModel: { robotCode: config.robotCode ?? config.appKey } } : { imRobotOpenDeliverModel: { spaceType: 'IM_ROBOT' } }) } };
+  }
+  confirm(prepared: NonNullable<ReturnType<DingTalkCards['prepare']>>, response: any): string {
+    const delivery = response?.result?.deliverResults?.find((item: any) => item.spaceType === prepared.record.spaceType && item.spaceId === prepared.record.spaceId);
+    if (response?.success === false || delivery?.success === false) throw new EndpointDeliveryError('platform_rejected', 'DingTalk card delivery was rejected', 'rejected');
+    if (response?.success !== true || response.result?.outTrackId !== prepared.id || delivery?.success !== true) throw new EndpointDeliveryError('delivery_unconfirmed', 'DingTalk card delivery is unconfirmed', 'unknown');
+    if (prepared.epoch !== this.#epoch) throw new EndpointDeliveryError('delivery_unconfirmed', 'DingTalk card completed after endpoint retirement', 'unknown');
+    this.#records.set(prepared.id, prepared.record);
+    for (const [id, record] of this.#records) if (record.expiresAt <= Date.now()) this.#records.delete(id);
+    while (this.#records.size > 1024) this.#records.delete(this.#records.keys().next().value!);
+    return prepared.id;
+  }
+  resolve(callback: DingTalkCardCallback) {
+    const record = this.#records.get(callback.outTrackId ?? '');
+    if (!record || record.expiresAt <= Date.now() || callback.spaceType !== record.spaceType || callback.spaceId !== record.spaceId || callback.userIdType !== 1 || !callback.userId || (record.corpId && callback.corpId !== record.corpId) || (record.spaceType === 'IM_ROBOT' && callback.userId !== record.staffId)) throw new Error('DingTalk card callback correlation failed');
+    const content = JSON.parse(callback.content ?? '') as { cardPrivateData?: { params?: { action?: unknown } } };
+    const payload = content.cardPrivateData?.params?.action;
+    if (typeof payload !== 'string' || !record.payloads.has(payload)) throw new Error('DingTalk card callback payload mismatch');
+    return { conversation: record.conversation, payload, sourceMessageId: callback.outTrackId!, senderId: callback.userId === record.staffId ? record.senderId ?? callback.userId : callback.userId };
+  }
+}