@zhin.js/adapter-dingtalk 1.1.4 → 1.1.5

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @zhin.js/adapter-dingtalk
 
+## 1.1.5
+
+### Patch Changes
+
+- b9b3953: 新增钉钉 Stream 长连接接收模式，保留默认 HTTP webhook。官方网关注册确认、共享生命周期重连与心跳、停止取消、回调 ACK 和有界去重；失败不会假报连接成功。
+- b9b3953: Stop synthesizing message IDs after outbound API calls. Missing real platform IDs now report an unknown delivery outcome and must not be retried automatically. DingTalk webhook success responses without a message ID therefore remain unconfirmed under the current receipt contract.
+
+  LINE reply and push use their actual sentMessages IDs. Reply HTTP 400 errors no longer trigger automatic push fallback: rejected or partially successful replies could otherwise duplicate a message. Locally expired cached reply tokens still select push before a reply request is made.
+
+- b9b3953: Reject QQ outbound responses carrying a nonzero platform error even when they contain a message ID. Classify DingTalk HTTP client rejection separately from uncertain server/network outcomes and avoid exposing raw platform response text in delivery errors.
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+- Updated dependencies [b9b3953]
+  - @zhin.js/adapter@1.1.16
+  - @zhin.js/im-contract@1.1.3
+  - @zhin.js/core@1.1.40
+  - @zhin.js/host-http@1.1.3
+  - @zhin.js/tool@1.1.3
+  - @zhin.js/skill@1.1.3
+  - @zhin.js/agent-feature@1.1.3
+
 ## 1.1.4
 
 ### Patch Changes

package/README.md

@@ -67,12 +67,20 @@ plugins:
 | 钉钉类型 | 入站 content（文本摘要） | 出站 wire |
 |----------|--------------------------|-----------|
 | text | 原文 | text |
-| picture | `[image]` | picture（需 `url`） |
+| picture | `[image]` | Markdown 图片链接（canonical HTTP(S) `url`） |
 | file | `[file: name]` | — |
 | audio / video | `[audio]` / `[video]` | — |
 | markdown | 原文或 `[markdown]` | markdown |
 | link | — | link |
 
+### Stream 进阶验收边界
+
+Stream 只承载入站事件，回复仍向本次入站的 `sessionWebhook` 发送 HTTP 请求。当前支持文本、Markdown 和可公网访问的图片 URL；图文组合通过 Markdown 保留文本与图片，图片能否实际显示必须由接收端确认。官方依据：[Stream Markdown 回复](https://opensource.dingtalk.com/developerpedia/docs/explore/tutorials/stream/bot/nodejs/send-markdown/)、[Markdown 图片说明](https://opensource.dingtalk.com/developerpedia/docs/learn/stream/faq/)。
+
+canonical `reply` 原生引用、本地/base64 图片上传、音频/视频/文件目前未实现，请求前返回 `unsupported_operation`，不会发送 `[reply]` 或只发送剩余文字。撤回没有 Endpoint control 端口，属于 `unsupported`；不会自动申请上传或撤回 API 权限。远程图片是 Markdown 内嵌显示，不能据此宣称原生图片消息已验收。
+
+发送需有效的入站会话：缓存尊重 `sessionWebhookExpiredTime`，缺少过期时间时最多保留 5 分钟，最多保存 1024 个会话。Stream 缺少或过期会话时在请求前返回 `session_unavailable`，不自动改走其他 API 或重放。请求发出后的断网、超时或响应缺少真实 `msgId` 仍是 `unknown`，不代表消息未送达；需要人工核对接收端，不能伪造 ID 或自动再次发送。
+
 ## Agent 工具
 
 `agents/dingtalk/skills/dingtalk/tools/` 在 DingTalk Skill 激活后提供 get_user、部门、群聊、工作通知等 Tool。工具声明 `adapter: 'dingtalk'` 后，通过惰性的 `context.$client` 自动取得当前操作的 `DingTalkClient`；无需把 Endpoint id 暴露给模型。
@@ -96,3 +104,31 @@ pnpm --filter @zhin.js/adapter-dingtalk test
 | Webhook 返回 401/403 | 检查 `appSecret`、签名时间戳与服务器时钟 |
 | 能收到但无法回复 | 检查 `robotCode`、应用权限与 session webhook 是否有效 |
 | Endpoint 未出现 | 在日志查 Schema 或凭据错误，再到运行时能力核对 Endpoint |
+
+## Stream 长连接
+
+端点设置 `mode: stream`（默认 `webhook` 保持 HTTP 回调），使用现有 `appKey` / `appSecret`。钉钉后台创建企业内部应用、启用机器人并选择 Stream 模式，发布后加入测试群；无需公网回调地址。
+
+```yaml
+endpoints:
+  - id: test-bot
+    mode: stream
+    appKey: ${DINGTALK_APP_KEY}
+    appSecret: ${DINGTALK_APP_SECRET}
+```
+
+连接通过官方网关获取 WSS 地址和临时 ticket，WSS 握手成功后报告 open（与官方 SDK 一致，不要求可选 REGISTERED 帧）。连接失败会拒绝启动；断线由框架统一退避重连，stop 取消网关请求及 socket，防止迟到连接复活。机器人 CALLBACK 在入站链路成功后 ACK；失败或尚未 open 不 ACK，等待服务端重投。连接内缓存五分钟、最多一万条回调 ID 去重；跨进程业务幂等需要应用持久化处理。HTTP 和 Stream 共用消息归一化及统一出站链路。
+
+协议依据：[钉钉官方 Stream SDK](https://github.com/open-dingtalk/dingtalk-stream-sdk-nodejs)。本适配器直接实现该网关协议，使用共享 EndpointLifecycle 管理重连和心跳。当前新增模式已经过本地注入传输回归，真实租户验收仍需实际应用验证。
+
+
+canonical `share` 编码为原生 `link` 卡片，映射 `url/title/description/image` 到 `messageUrl/title/text/picUrl`。必须实测卡片展示和链接点击；单次消息只支持一个链接卡片。
+
+钉钉原生按钮通过配置关联应用的互动卡片模板实现，使用 Stream 卡片回调；传统 `actionCard` URL 导航不作为按钮业务回调。固定模板字段、数量配置、权限、会话/actor 校验及重启边界见 [模板配置指南](./CARD-TEMPLATE.md)。未配置模板时返回 `card_template_required`，而不是声明平台不支持。
+# Stream 可控断线验收
+
+可选 `streamProxy: { port: 18443, serverName: "实际网关域名" }` 只将 WSS 的 TCP 连接转发到 `127.0.0.1:18443`。原始 HTTPS discovery 仍直连；真实 WSS URL、HTTP Host、ticket、TLS SNI 与证书校验保持原值，不修改系统网络，也不需要账号 B。此入口使用 [ws 的 createConnection 契约](https://github.com/websockets/ws/blob/master/doc/ws.md)，不关闭 TLS 校验。网关主机变化时明确拒绝连接，只记录安全 hostname，绝不回退直连或输出 ticket。
+
+先通过临时启动配置加 `streamProxy`，若未知网关域名，可先填写占位域名；拒绝日志只显示实际 hostname。使用该域名启动 `scripts/platform-acceptance/tcp-fault-proxy.mjs --upstream-host 实际网关域名 --upstream-port 443 --port 18443 --control-port 18444`，将 serverName 同步设为此域名。不要覆盖用户已有 `.env`。恢复正常验收后移除临时配置并停止代理。
+
+正常收发后 `POST http://127.0.0.1:18444/cut`；现有 WSS 立即关闭，Endpoint 的 `transportState` 经统一 lifecycle 进入重连，期间健康记录不能认定在线。`POST /recover` 后仅允许新建连接；需观察重新 `open`，再发送新的唯一 probe，验证入站及可见回包。Stream 入站恢复与 sessionWebhook 出站恢复是不同链路：该代理仅切断 WSS，HTTP 发送未被切断；不能把这次试验记为所有平台网络故障、发送重试或离线消息无损验收。网关域名变化需停止验收并更新固定上游，不能绕代理继续取通过证据。

package/adapters/dingtalk/index.js

@@ -11,10 +11,10 @@ export { DingTalkEndpoint } from "../../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
     // 钉钉机器人媒体消息仅消费远程 URL；Markdown 走原生 msgtype；
-    // 无按钮交互面，交互段降级纯文本。
+    // 原生按钮需配置固定互动卡片模板，由 Stream 接收回调。
     segments: {
         outboundMedia: ['url'],
-        interactive: 'text',
+        interactive: 'native',
         markdown: 'native',
     },
     create(context) {
@@ -22,11 +22,11 @@ export default defineAdapter({
         // 注册到插件运行时状态（dingtalk endpoint list 的"运行中"数据源）
         context.use(dingtalkRuntimeStateToken).endpoints.set(config.id, {
             id: config.id,
-            mode: 'webhook',
+            mode: config.mode ?? 'webhook',
         });
         return new DingTalkEndpoint({
             id: context.id,
-            http: context.use(httpHostToken),
+            http: config.mode === 'stream' ? undefined : context.use(httpHostToken),
             config,
         });
     },

package/adapters/dingtalk/index.ts

@@ -16,10 +16,10 @@ export type { DingTalkEndpointOptions, DingTalkFetch } from '../../src/endpoint.
 export default defineAdapter<DingTalkEndpointConfig>({
   capabilities: ['inbound', 'outbound'],
   // 钉钉机器人媒体消息仅消费远程 URL；Markdown 走原生 msgtype；
-  // 无按钮交互面，交互段降级纯文本。
+  // 原生按钮需配置固定互动卡片模板，由 Stream 接收回调。
   segments: {
     outboundMedia: ['url'],
-    interactive: 'text',
+    interactive: 'native',
     markdown: 'native',
   },
   create(context) {
@@ -27,11 +27,11 @@ export default defineAdapter<DingTalkEndpointConfig>({
     // 注册到插件运行时状态（dingtalk endpoint list 的"运行中"数据源）
     context.use(dingtalkRuntimeStateToken).endpoints.set(config.id, {
       id: config.id,
-      mode: 'webhook',
+      mode: config.mode ?? 'webhook',
     });
     return new DingTalkEndpoint({
       id: context.id,
-      http: context.use(httpHostToken),
+      http: config.mode === 'stream' ? undefined : context.use(httpHostToken),
       config,
     });
   },

package/lib/cards.d.ts

@@ -0,0 +1,77 @@
+import { 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 declare class DingTalkCards {
+    #private;
+    remember(conversation: ConversationRef, event: DingTalkMessage): void;
+    clear(): void;
+    prepare(config: ResolvedDingTalkConfig, conversation: ConversationRef, payload: unknown): {
+        id: `${string}-${string}-${string}-${string}-${string}`;
+        record: CardRecord;
+        epoch: number;
+        body: {
+            imGroupOpenDeliverModel: {
+                robotCode: string;
+            };
+            cardTemplateId: string;
+            outTrackId: `${string}-${string}-${string}-${string}-${string}`;
+            cardData: {
+                cardParamMap: Record<string, string>;
+            };
+            callbackType: string;
+            userIdType: number;
+            openSpaceId: string;
+            imGroupOpenSpaceModel: {
+                supportForward: boolean;
+            };
+            imRobotOpenSpaceModel: {
+                supportForward: boolean;
+            };
+        } | {
+            imRobotOpenDeliverModel: {
+                spaceType: string;
+            };
+            cardTemplateId: string;
+            outTrackId: `${string}-${string}-${string}-${string}-${string}`;
+            cardData: {
+                cardParamMap: Record<string, string>;
+            };
+            callbackType: string;
+            userIdType: number;
+            openSpaceId: string;
+            imGroupOpenSpaceModel: {
+                supportForward: boolean;
+            };
+            imRobotOpenSpaceModel: {
+                supportForward: boolean;
+            };
+        };
+    } | undefined;
+    confirm(prepared: NonNullable<ReturnType<DingTalkCards['prepare']>>, response: any): string;
+    resolve(callback: DingTalkCardCallback): {
+        conversation: ConversationRef;
+        payload: string;
+        sourceMessageId: string;
+        senderId: string;
+    };
+}
+export {};

package/lib/cards.js

@@ -0,0 +1,81 @@
+import { randomUUID } from 'node:crypto';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+/** Endpoint-owned, bounded correlation. Cards from old generations deliberately cannot dispatch. */
+export class DingTalkCards {
+    #epoch = 0;
+    #records = new Map();
+    #contexts = new Map();
+    remember(conversation, event) {
+        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() { this.#epoch++; this.#records.clear(); this.#contexts.clear(); }
+    prepare(config, conversation, payload) {
+        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) => 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 = { 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 = { conversation, spaceType, spaceId, staffId: context.senderStaffId, senderId: context.senderId, corpId: context.senderCorpId, payloads: new Set(buttons.map((button) => 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, response) {
+        const delivery = response?.result?.deliverResults?.find((item) => 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) {
+        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 ?? '');
+        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 };
+    }
+}

package/lib/endpoint.d.ts

@@ -1,8 +1,9 @@
-import { Endpoint } from 'zhin.js/adapter';
+import { type DingTalkCardCallback } from './cards.js';
+import { type DingTalkStreamSocketFactory } from './stream.js';
 /**
  * DingTalkEndpoint — lifecycle, outbound, admit, OpenAPI helpers for agent tools.
  */
-import { type EndpointSendRequest } from 'zhin.js/adapter';
+import { Endpoint, type EndpointSendRequest } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { type DingTalkEvent, type DingTalkMessage, type ResolvedDingTalkConfig } from './protocol.js';
@@ -10,6 +11,7 @@ export type DingTalkFetch = (url: string, init?: {
     readonly method?: string;
     readonly headers?: Record<string, string>;
     readonly body?: string;
+    readonly signal?: AbortSignal;
 }) => Promise<{
     readonly ok: boolean;
     readonly status: number;
@@ -18,7 +20,8 @@ export type DingTalkFetch = (url: string, init?: {
 }>;
 export interface DingTalkEndpointOptions {
     readonly id: CapabilityId;
-    readonly http: HttpHost;
+    readonly http?: HttpHost;
+    readonly createStreamSocket?: DingTalkStreamSocketFactory;
     readonly config: ResolvedDingTalkConfig;
     readonly fetch?: DingTalkFetch;
 }
@@ -59,6 +62,7 @@ export declare class DingTalkEndpoint extends Endpoint<DingTalkClient> {
     #private;
     readonly client: DingTalkClient;
     constructor(options: DingTalkEndpointOptions);
+    get transportState(): import("@zhin.js/adapter").EndpointLifecycleState;
     /** Used by webhook handler. */
     get isOpen(): boolean;
     get config(): ResolvedDingTalkConfig;
@@ -67,6 +71,7 @@ export declare class DingTalkEndpoint extends Endpoint<DingTalkClient> {
     close(): void;
     stop(): Promise<void>;
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    admitCard(event: DingTalkCardCallback, id: string): Promise<void>;
     /** Test / internal: admit a parsed event when open (non-webhook path). */
-    admit(event: DingTalkEvent | DingTalkMessage): void;
+    admit(event: DingTalkEvent | DingTalkMessage): Promise<void>;
 }

package/lib/endpoint.js

@@ -1,3 +1,9 @@
+import { DingTalkCards } from './cards.js';
+import { DingTalkStream } from './stream.js';
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+/**
+ * DingTalkEndpoint — lifecycle, outbound, admit, OpenAPI helpers for agent tools.
+ */
 import { Endpoint } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { normalizeDingtalkSenderForPermit } from './platform-permit.js';
@@ -41,6 +47,8 @@ export class DingTalkEndpoint extends Endpoint {
     #accessToken = { token: '', expires_in: 0, timestamp: 0 };
     #refreshPromise = null;
     #sessionWebhooks = new Map();
+    #stream;
+    #cards = new DingTalkCards();
     #open = false;
     #started = false;
     constructor(options) {
@@ -49,6 +57,7 @@ export class DingTalkEndpoint extends Endpoint {
         this.#options = options;
         this.#fetch = options.fetch ?? globalThis.fetch;
     }
+    get transportState() { return this.#stream?.lifecycle.state ?? (this.#started ? 'open' : 'stopped'); }
     /** Used by webhook handler. */
     get isOpen() {
         return this.#open;
@@ -61,6 +70,11 @@ export class DingTalkEndpoint extends Endpoint {
             return;
         this.#started = true;
         try {
+            if (this.#options.config.mode === 'stream') {
+                this.#stream = new DingTalkStream(this.config, this.#fetch, (event) => this.admit(event), () => this.#open, this.#options.createStreamSocket, (event, id) => this.admitCard(event, id));
+                await this.#stream.start();
+                return;
+            }
             await this.#refreshAccessToken();
             this.#routeReleases.push(...registerDingTalkWebhookRoutes(this.#options.http, this));
             this.#logger.debug(formatCompact({
@@ -83,61 +97,144 @@ export class DingTalkEndpoint extends Endpoint {
     }
     async stop() {
         this.#open = false;
+        await this.#stream?.stop();
         this.#sessionWebhooks.clear();
+        this.#cards.clear();
         for (const release of this.#routeReleases.splice(0))
             release();
         this.#started = false;
         this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
     async send({ conversation, payload }) {
-        const content = formatOutboundBody(payload);
-        const sessionWebhook = this.#sessionWebhooks.get(conversation.id);
-        if (sessionWebhook) {
-            const response = await this.#fetch(sessionWebhook, {
+        try {
+            const card = this.#cards.prepare(this.config, conversation, payload);
+            if (card) {
+                let stage = 'token';
+                let httpStatus;
+                let platformCode;
+                try {
+                    try {
+                        await this.#ensureAccessToken();
+                    }
+                    catch (cause) {
+                        throw new EndpointDeliveryError('token_unavailable', 'DingTalk card token unavailable', 'not_sent', { cause });
+                    }
+                    stage = 'request';
+                    const response = await this.#fetch('https://api.dingtalk.com/v1.0/card/instances/createAndDeliver', { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-acs-dingtalk-access-token': this.#accessToken.token }, body: JSON.stringify(card.body), signal: AbortSignal.timeout(30_000) });
+                    httpStatus = response.status;
+                    stage = 'response';
+                    let data;
+                    try {
+                        data = await response.json();
+                    }
+                    catch {
+                        if (response.ok)
+                            throw new EndpointDeliveryError('invalid_response', 'DingTalk card response could not be parsed', 'unknown');
+                    }
+                    if (data && typeof data === 'object') {
+                        const code = data.code ?? data.errcode;
+                        // Only bounded protocol codes; never log URLs, messages, response bodies or credentials.
+                        if (typeof code === 'number' && Number.isFinite(code))
+                            platformCode = code;
+                        else if (typeof code === 'string' && /^[a-zA-Z][a-zA-Z0-9_.-]{0,95}$/.test(code)
+                            && ![this.#accessToken.token, this.config.appSecret, this.config.appKey].some(secret => secret && code.includes(secret)))
+                            platformCode = code;
+                    }
+                    if (!response.ok)
+                        throw new EndpointDeliveryError('http_error', `DingTalk card HTTP ${response.status}`, response.status >= 400 && response.status < 500 ? 'rejected' : 'unknown');
+                    stage = 'delivery';
+                    return this.#cards.confirm(card, data);
+                }
+                catch (error) {
+                    this.#logger.warn(formatCompact({ op: 'dingtalk_card_delivery_failed', stage, httpStatus, platformCode,
+                        code: error instanceof EndpointDeliveryError ? error.code : 'delivery_unconfirmed' }));
+                    throw error;
+                }
+            }
+            const content = formatOutboundBody(payload);
+            const session = this.#sessionWebhooks.get(conversation.id);
+            const sessionWebhook = session && session.expiresAt > Date.now() ? session.url : undefined;
+            if (session && !sessionWebhook)
+                this.#sessionWebhooks.delete(conversation.id);
+            if (!sessionWebhook && this.config.mode === 'stream') {
+                throw new EndpointDeliveryError('session_unavailable', 'DingTalk Stream send requires a current inbound session webhook', 'not_sent');
+            }
+            if (sessionWebhook) {
+                const response = await this.#fetch(sessionWebhook, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json; charset=utf-8' },
+                    body: JSON.stringify(content),
+                    signal: AbortSignal.timeout(30_000),
+                });
+                if (!response.ok)
+                    throw new EndpointDeliveryError('http_error', `DingTalk HTTP ${response.status}`, response.status >= 400 && response.status < 500 ? 'rejected' : 'unknown');
+                const data = await response.json();
+                if (typeof data.errcode === 'number' && data.errcode !== 0) {
+                    throw new EndpointDeliveryError('platform_rejected', `DingTalk session webhook rejected the outbound request (${data.errcode})`, 'rejected');
+                }
+                this.#logger.debug(formatCompact({
+                    op: 'send',
+                    endpoint: this.#options.config.id,
+                    via: 'sessionWebhook',
+                    to: conversation.id,
+                }));
+                if (data.errcode !== 0)
+                    throw new EndpointDeliveryError('delivery_unconfirmed', 'Malformed platform response', 'unknown');
+                return requireMessageId(data.msgId);
+            }
+            const body = {
+                ...content,
+                ...(this.#options.config.robotCode
+                    ? { robotCode: this.#options.config.robotCode }
+                    : {}),
+            };
+            const data = await this.#request('/robot/send', {
                 method: 'POST',
-                headers: { 'Content-Type': 'application/json; charset=utf-8' },
-                body: JSON.stringify(content),
+                body: body,
             });
-            const data = await response.json();
-            if (data.errcode !== 0) {
-                throw new Error(`Failed to send message via session webhook: ${data.errmsg}`);
+            if (typeof data.errcode === 'number' && data.errcode !== 0) {
+                throw new EndpointDeliveryError('platform_rejected', `DingTalk rejected the outbound request (${data.errcode})`, 'rejected');
             }
-            this.#logger.debug(formatCompact({
-                op: 'send',
-                endpoint: this.#options.config.id,
-                via: 'sessionWebhook',
-                to: conversation.id,
-            }));
-            return data.msgId || `${Date.now()}`;
+            this.#logger.debug(formatCompact({ op: 'send', to: conversation.id }));
+            if (data.errcode !== 0)
+                throw new EndpointDeliveryError('delivery_unconfirmed', 'Malformed platform response', 'unknown');
+            return requireMessageId(data.msgId);
         }
-        const body = {
-            ...content,
-            ...(this.#options.config.robotCode
-                ? { robotCode: this.#options.config.robotCode }
-                : {}),
-        };
-        const data = await this.#request('/robot/send', {
-            method: 'POST',
-            body: body,
-        });
-        if (data.errcode !== 0) {
-            throw new Error(`Failed to send message: ${data.errmsg}`);
+        catch (error) {
+            if (error instanceof EndpointDeliveryError)
+                throw error;
+            throw new EndpointDeliveryError('delivery_unconfirmed', 'Outbound request outcome is unknown', 'unknown', { cause: error });
         }
-        this.#logger.debug(formatCompact({ op: 'send', to: conversation.id }));
-        return data.msgId || `${Date.now()}`;
+    }
+    async admitCard(event, id) {
+        if (!this.#open)
+            throw new Error('DingTalk endpoint is closed');
+        const action = this.#cards.resolve(event);
+        await this.emitAccepted('message.receive', {
+            conversation: action.conversation, message: { conversation: action.conversation, id },
+            content: `[action: ${action.payload}]`, segments: [{ type: 'action', data: { id, payload: action.payload, sourceMessageId: action.sourceMessageId } }],
+            sender: { id: action.senderId }, endpointId: this.config.id,
+            metadata: Object.freeze({ eventType: 'card_callback', sourceMessageId: action.sourceMessageId }),
+        });
     }
     /** Test / internal: admit a parsed event when open (non-webhook path). */
-    admit(event) {
+    async admit(event) {
         if (!this.#open)
             return;
         this.#emitPlatformEvent(event.msgtype || 'event', event);
         if (event.sessionWebhook && event.conversationId) {
-            this.#sessionWebhooks.set(event.conversationId, event.sessionWebhook);
+            const expiresAt = Number.isFinite(event.sessionWebhookExpiredTime) ? event.sessionWebhookExpiredTime : Date.now() + 300_000;
+            this.#sessionWebhooks.delete(event.conversationId);
+            if (expiresAt > Date.now())
+                this.#sessionWebhooks.set(event.conversationId, { url: event.sessionWebhook, expiresAt });
+            while (this.#sessionWebhooks.size > 1024)
+                this.#sessionWebhooks.delete(this.#sessionWebhooks.keys().next().value);
         }
         const conversation = dingtalkInboundConversation(String(this.#options.id), event);
+        this.#cards.remember(conversation, event);
         const chatType = resolveChatType(event.conversationType);
         const permit = normalizeDingtalkSenderForPermit({ isAdmin: event.isAdmin === true });
-        void this.emit('message.receive', {
+        await this.emitAccepted('message.receive', {
             conversation,
             message: { conversation, id: generateMessageId(event) },
             content: formatInboundContent(event),
@@ -157,6 +254,8 @@ export class DingTalkEndpoint extends Endpoint {
                 conversationType: event.conversationType,
             }),
         }).catch((err) => {
+            if (this.config.mode === 'stream')
+                throw err;
             this.#logger.warn(formatCompact({
                 op: 'dingtalk_gateway_receive_failed',
                 conversationId: conversation.id,
@@ -311,10 +410,10 @@ export class DingTalkEndpoint extends Endpoint {
             method,
             headers: { 'Content-Type': 'application/json; charset=utf-8' },
             body: body && method === 'POST' ? JSON.stringify(body) : undefined,
+            signal: AbortSignal.timeout(30_000),
         });
         if (!response.ok) {
-            const text = await response.text().catch(() => '');
-            throw new Error(`DingTalk API error ${response.status}: ${text}`);
+            throw new EndpointDeliveryError('http_error', `DingTalk HTTP ${response.status}`, response.status >= 400 && response.status < 500 ? 'rejected' : 'unknown');
         }
         return await response.json();
     }
@@ -351,3 +450,8 @@ export class DingTalkEndpoint extends Endpoint {
         throw new Error(`Failed to get access token: ${data.errmsg} (${data.errcode})`);
     }
 }
+function requireMessageId(value) {
+    if (typeof value === 'string' && value.trim().length > 0)
+        return value;
+    throw new EndpointDeliveryError('delivery_unconfirmed', 'Platform did not return a real message ID', 'unknown');
+}

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;