@zhin.js/adapter-dingtalk 5.0.5 → 6.0.1

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @zhin.js/adapter-dingtalk
 
+## 6.0.1
+
+### Patch Changes
+
+- Updated dependencies [c8f4d45]
+  - @zhin.js/plugin-runtime@1.1.2
+  - @zhin.js/host-http@1.0.5
+  - @zhin.js/adapter@1.1.4
+  - @zhin.js/agent@1.1.1
+  - @zhin.js/command@1.0.6
+  - @zhin.js/core@1.5.1
+  - zhin.js@6.0.1
+
+## 6.0.0
+
+### Patch Changes
+
+- 4fbff5d: feat!: 多模态双向 Segment 一贯制（BREAKING，无兼容层）
+
+  全框架唯一媒体表达统一为 canonical `Segment` + `MediaRef{kind: url|path|base64|file, value, mime_type?, file_name?, size?}`，新增 audio/video/file 段类型；所有第二形状（legacy `data.url/file/base64` 字段、`mediaRefFromLegacyData`/`mediaRefToLegacyFields` 桥、双写）全部删除。
+
+  - **core**：`SendContent` 一等支持 `Segment[]`；endpoint 出站载荷只含 canonical 段；`resolveOutboundMediaPolicy` 改为纯声明驱动（adapter definition `segments.outboundMedia`），内置策略表删除，未声明回退 `url-or-text`；`ImageContent` 旧桥删除。
+  - **ai**：新增 `MediaContentBlock`/`MediaBlockRef`（Segment 同构）与 `UserMessage.media`（当前 turn 媒体，**不持久化**——存储层自动剥离）；`createUserMessage(text, media?)` 签名变更（`ImageContent` 删除）；provider 边界序列化器 `filterMediaBlocksForProvider` + 能力表（缺省 image-only，不支持类型降级占位文本）；ai-sdk 桥媒体块 → SDK image/file parts。
+  - **agent**：入站 turn 注入（`turn/inbound-media.ts`）——commMessage 媒体段 → 当前 turn `UserMessage.media`；图片 path 物化、音频默认 STT（`@zhin.js/speech` 可选，失败降级占位）、视频/文件占位；`publishOutboundElements` 产出 canonical Segment；`transcribeAudioPayload` 导出。
+  - **cli**：`bridgeRuntimeMessage` 回复链路媒体段透传，不再压平为文本（`$reply` 直达 normalize → adapter）。
+  - **全部 20 个平台适配器**：出站媒体只消费 `data.media`（url 直发 / base64 直发 / 平台上传 / 读盘），入站媒体产出 canonical `data.media`；`segments.outboundMedia` 声明与实际消费逐一核对修正；QQ 入站新增 canonical segments（image/audio/video/file/mention/face/reply），图片/语音/视频不再丢失。
+
+  迁移：适配器/插件产媒体一律用 `{ type, data: { media: MediaRef } }`；发送 legacy `data.url/file/base64` 形状的段会被 warn 丢弃。
+
+- Updated dependencies [7c1e63a]
+- Updated dependencies [4fbff5d]
+- Updated dependencies [5b94d9c]
+  - @zhin.js/command@1.0.5
+  - @zhin.js/adapter@1.1.3
+  - @zhin.js/core@1.5.0
+  - @zhin.js/agent@1.1.0
+  - zhin.js@6.0.0
+
 ## 5.0.5
 
 ### Patch Changes

package/adapters/dingtalk.js

@@ -18,7 +18,7 @@ export default defineAdapter({
     },
     create(context) {
         const config = resolveDingTalkConfig(context.config);
-        // 注册到插件运行时状态（dingtalk endpoint list 的"运行中"数据源）
+        // 注册到插件运行时状态（dingtalk.endpoint list 的"运行中"数据源）
         context.use(dingtalkRuntimeStateToken).endpoints.set(config.name, {
             name: config.name,
             mode: 'webhook',

package/adapters/dingtalk.ts

@@ -23,7 +23,7 @@ export default defineAdapter<DingTalkAdapterConfig>({
   },
   create(context) {
     const config = resolveDingTalkConfig(context.config);
-    // 注册到插件运行时状态（dingtalk endpoint list 的"运行中"数据源）
+    // 注册到插件运行时状态（dingtalk.endpoint list 的"运行中"数据源）
     context.use(dingtalkRuntimeStateToken).endpoints.set(config.name, {
       name: config.name,
       mode: 'webhook',

package/lib/dingtalk-endpoint-commands.js

@@ -1,5 +1,5 @@
 /**
- * `dingtalk endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * `dingtalk.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
  * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
  */
 import { createEndpointCommands } from '@zhin.js/adapter';

package/lib/dingtalk-runtime-state.js

@@ -1,6 +1,6 @@
 /**
  * DingTalk 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `dingtalk endpoint` 命令共享（同一 owner generation）。
+ * 由 plugin.ts setup() provide，adapter create 与 `dingtalk.endpoint` 命令共享（同一 owner generation）。
  */
 import { defineEndpointRuntimeStateToken } from '@zhin.js/adapter';
 export const dingtalkRuntimeStateToken = defineEndpointRuntimeStateToken('dingtalk');

package/lib/protocol.d.ts

@@ -114,7 +114,12 @@ export declare const MAX_TIMESTAMP_DRIFT_MS: number;
 export declare function verifySignature(appSecret: string, timestamp: string, sign: string): boolean;
 /**
  * Wire-encode an already-rendered outbound payload into DingTalk robot body.
- * Segment canonicalization is intentionally not done here.
+ * 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 + 丢弃。
  */
 export declare function formatOutboundBody(payload: unknown): DingTalkSendBody;
 export declare function headerValue(headers: IncomingMessage['headers'], name: string): string;

package/lib/protocol.js

@@ -3,6 +3,9 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import { createHmac, timingSafeEqual } from 'node:crypto';
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('dingtalk');
 /**
  * 钉钉回调消息 @ 机器人判定：机器人被 @ 时回调带 `isInAtList: true`；
  * 部分回调形态的 `atUserIds` / `atUsers[].dingtalkId` 会包含机器人 robotCode（来自配置）。
@@ -117,7 +120,12 @@ export function verifySignature(appSecret, timestamp, sign) {
 }
 /**
  * Wire-encode an already-rendered outbound payload into DingTalk robot body.
- * Segment canonicalization is intentionally not done here.
+ * 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 + 丢弃。
  */
 export function formatOutboundBody(payload) {
     if (typeof payload === 'string') {
@@ -157,13 +165,33 @@ export function formatOutboundBody(payload) {
                 }
                 break;
             }
-            case 'image':
-                if (!media) {
+            case 'image': {
+                if (media)
+                    break;
+                const ref = data.media;
+                if (isMediaRef(ref) && ref.kind === 'url') {
                     media = {
                         msgtype: 'picture',
-                        picture: { picURL: String(data.url ?? data.file ?? '') },
+                        picture: { picURL: ref.value },
                     };
+                    break;
                 }
+                logger.warn(formatCompact({
+                    op: 'dingtalk_outbound_media_dropped',
+                    type: item.type,
+                    reason: isMediaRef(ref) ? `unsupported_kind:${ref.kind}` : 'missing_media_ref',
+                }));
+                break;
+            }
+            case 'audio':
+            case 'video':
+            case 'file':
+                // 钉钉机器人无音频/视频/文件投递面，warn + 丢弃
+                logger.warn(formatCompact({
+                    op: 'dingtalk_outbound_media_dropped',
+                    type: item.type,
+                    reason: 'undeliverable_msgtype',
+                }));
                 break;
             case 'markdown':
                 if (!media) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-dingtalk",
-  "version": "5.0.5",
+  "version": "6.0.1",
   "description": "Zhin.js DingTalk (钉钉) adapter for Plugin Runtime (HTTP webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,21 +33,21 @@
     "directory": "plugins/adapters/dingtalk"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/command": "1.0.4",
-    "@zhin.js/core": "1.4.3",
-    "@zhin.js/host-http": "1.0.4",
+    "@zhin.js/adapter": "1.1.4",
+    "@zhin.js/command": "1.0.6",
+    "@zhin.js/core": "1.5.1",
+    "@zhin.js/host-http": "1.0.5",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.1"
+    "@zhin.js/plugin-runtime": "1.1.2"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/agent": "1.0.10",
-    "@zhin.js/core": "1.4.3",
-    "@zhin.js/host-http": "1.0.4",
-    "@zhin.js/plugin-runtime": "1.1.1",
-    "zhin.js": "5.0.3"
+    "@zhin.js/adapter": "1.1.4",
+    "@zhin.js/agent": "1.1.1",
+    "@zhin.js/core": "1.5.1",
+    "@zhin.js/host-http": "1.0.5",
+    "@zhin.js/plugin-runtime": "1.1.2",
+    "zhin.js": "6.0.1"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -65,8 +65,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.10",
-    "zhin.js": "5.0.3"
+    "@zhin.js/agent": "1.1.1",
+    "zhin.js": "6.0.1"
   },
   "files": [
     "adapters",

package/plugin.js

@@ -9,7 +9,7 @@ export default definePlugin({
         displayName: 'DingTalk (钉钉) Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表（dingtalk endpoint list 的"运行中"数据源）
+        // 运行中 endpoint 注册表（dingtalk.endpoint list 的"运行中"数据源）
         context.resources.provide(dingtalkRuntimeStateToken, createEndpointRuntimeState());
         return registerDingtalkPlatformPermitChecker();
     },

package/src/dingtalk-endpoint-commands.ts

@@ -1,5 +1,5 @@
 /**
- * `dingtalk endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * `dingtalk.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
  * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
  */
 import { createEndpointCommands } from '@zhin.js/adapter';

package/src/dingtalk-runtime-state.ts

@@ -1,6 +1,6 @@
 /**
  * DingTalk 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `dingtalk endpoint` 命令共享（同一 owner generation）。
+ * 由 plugin.ts setup() provide，adapter create 与 `dingtalk.endpoint` 命令共享（同一 owner generation）。
  */
 import { defineEndpointRuntimeStateToken } from '@zhin.js/adapter';
 

package/src/protocol.ts

@@ -6,6 +6,11 @@
 import { createHmac, timingSafeEqual } from 'node:crypto';
 import type { IncomingMessage } from 'node:http';
 
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+
+const logger = getLogger('dingtalk');
+
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface DingTalkAdapterConfig {
   readonly name?: string;
@@ -223,7 +228,12 @@ export function verifySignature(
 
 /**
  * Wire-encode an already-rendered outbound payload into DingTalk robot body.
- * Segment canonicalization is intentionally not done here.
+ * 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 + 丢弃。
  */
 export function formatOutboundBody(payload: unknown): DingTalkSendBody {
   if (typeof payload === 'string') {
@@ -267,13 +277,32 @@ export function formatOutboundBody(payload: unknown): DingTalkSendBody {
         }
         break;
       }
-      case 'image':
-        if (!media) {
+      case 'image': {
+        if (media) break;
+        const ref = data.media;
+        if (isMediaRef(ref) && ref.kind === 'url') {
           media = {
             msgtype: 'picture',
-            picture: { picURL: String(data.url ?? data.file ?? '') },
+            picture: { picURL: ref.value },
           };
+          break;
         }
+        logger.warn(formatCompact({
+          op: 'dingtalk_outbound_media_dropped',
+          type: item.type,
+          reason: isMediaRef(ref) ? `unsupported_kind:${ref.kind}` : 'missing_media_ref',
+        }));
+        break;
+      }
+      case 'audio':
+      case 'video':
+      case 'file':
+        // 钉钉机器人无音频/视频/文件投递面，warn + 丢弃
+        logger.warn(formatCompact({
+          op: 'dingtalk_outbound_media_dropped',
+          type: item.type,
+          reason: 'undeliverable_msgtype',
+        }));
         break;
       case 'markdown':
         if (!media) {