@zhin.js/adapter-lark 5.0.5 → 6.0.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @zhin.js/adapter-lark
 
+## 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.6
+
+### Patch Changes
+
+- d52f3c5: fix: QQ 适配器群聊误识别为私聊、game-kit 启动崩溃、全面补齐 recallMessage
+
+  - fix(cli): `resolveChannelType` 增加 `metadata.channelKind` 检查，修复 QQ/Discord/KOOK 群聊消息被误分类为私聊
+  - fix(game-kit): `createHostGameDb` 改用延迟代理模型，避免数据库启动前解析模型导致崩溃
+  - feat(qq): 实现 `recallMessage`，解析复合 messageId 路由到对应 SDK 撤回方法；`normalizeQqMessage` 增加 `message_type` 缺失时的回退检测
+  - feat(slack): 实现 `recallMessage`，利用已有 compound ref 和 `chat.delete` API
+  - feat(onebot11): 两个 endpoint 类实现 `recallMessage`（`delete_msg`）
+  - feat(onebot12): 两个 endpoint 类实现 `recallMessage`（`delete_message`）
+  - feat(napcat): 三个 endpoint 类实现 `recallMessage`（`delete_msg`）
+  - feat(discord): 两个 endpoint 类实现 `recallMessage`；`send()` 改为返回 `channelId:snowflake` 复合 ID
+  - feat(telegram): 实现 `recallMessage`（`deleteMessage`）；`send()` 改为返回 `chatId:messageId` 复合 ID
+  - feat(kook): 两个 endpoint 类实现 `recallMessage`，利用 kook-client `recallMsg` API
+  - feat(lark): 实现 `recallMessage`（`DELETE /im/v1/messages/{id}`）
+  - feat(wecom): 实现 `recallMessage`（`POST /cgi-bin/message/recall`）
+
 ## 5.0.5
 
 ### Patch Changes

package/adapters/lark.js

@@ -11,7 +11,8 @@ import { larkRuntimeStateToken } from "../lib/lark-runtime-state.js";
 export { LarkEndpoint } from "../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
-    // image 段经 /im/v1/images 物化为 image_key（url 下载后上传）；
+    // image 段 canonical MediaRef 经 /im/v1/images 物化为 image_key
+    // （base64 解码 / path 读盘 / url 下载后上传，kind=file 平台引用直通）；
     // 卡片交互未接入出站通道，交互段降级纯文本。
     segments: {
         outboundMedia: ['url', 'upload'],
@@ -19,7 +20,7 @@ export default defineAdapter({
     },
     create(context) {
         const config = resolveLarkConfig(context.config);
-        // 注册到插件运行时状态（lark endpoint list 的"运行中"数据源）
+        // 注册到插件运行时状态（lark.endpoint list 的"运行中"数据源）
         context.use(larkRuntimeStateToken).endpoints.set(config.name, {
             name: config.name,
             mode: 'webhook',

package/adapters/lark.ts

@@ -16,7 +16,8 @@ export type { LarkEndpointOptions, LarkFetch } from '../src/endpoint.js';
 
 export default defineAdapter<LarkAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
-  // image 段经 /im/v1/images 物化为 image_key（url 下载后上传）；
+  // image 段 canonical MediaRef 经 /im/v1/images 物化为 image_key
+  // （base64 解码 / path 读盘 / url 下载后上传，kind=file 平台引用直通）；
   // 卡片交互未接入出站通道，交互段降级纯文本。
   segments: {
     outboundMedia: ['url', 'upload'],
@@ -24,7 +25,7 @@ export default defineAdapter<LarkAdapterConfig>({
   },
   create(context) {
     const config = resolveLarkConfig(context.config);
-    // 注册到插件运行时状态（lark endpoint list 的"运行中"数据源）
+    // 注册到插件运行时状态（lark.endpoint list 的"运行中"数据源）
     context.use(larkRuntimeStateToken).endpoints.set(config.name, {
       name: config.name,
       mode: 'webhook',

package/lib/endpoint.d.ts

@@ -44,6 +44,7 @@ export declare class LarkEndpoint implements EndpointInstance {
         readonly target: string;
         readonly payload: unknown;
     }): Promise<string>;
+    recallMessage(messageId: string): Promise<void>;
     /** POST /im/v1/images（image_type=message），返回 image_key；失败返回 null。 */
     uploadImage(media: Parameters<typeof resolveMediaBinary>[0]): Promise<string | null>;
     /** Test / internal: admit a parsed message when open (non-webhook path). */

package/lib/endpoint.js

@@ -123,9 +123,15 @@ export class LarkEndpoint {
         }));
         return messageId;
     }
+    async recallMessage(messageId) {
+        if (!messageId || messageId.startsWith('outbound:'))
+            return;
+        await this.#request(`/im/v1/messages/${messageId}`, { method: 'DELETE' });
+    }
     /**
      * im/v1 消息 image 段只接受 image_key：canonical MediaRef（base64/本地路径/URL）
-     * 先经 /im/v1/images 物化；上传失败降级为文本（alt 优先），不阻断发送。
+     * 先经 /im/v1/images 物化，产物回写为 MediaRef kind=file（平台不透明引用）；
+     * 上传失败降级为文本（alt 优先），不阻断发送。
      */
     async #materializeOutboundMedia(payload) {
         if (!Array.isArray(payload))
@@ -145,7 +151,10 @@ export class LarkEndpoint {
                 const alt = typeof data.alt === 'string' && data.alt ? data.alt : '[image]';
                 return { type: 'text', data: { text: alt } };
             }
-            return { type: 'image', data: { image_key: imageKey } };
+            return {
+                type: 'image',
+                data: { media: { kind: 'file', value: imageKey } },
+            };
         }));
     }
     /** POST /im/v1/images（image_type=message），返回 image_key；失败返回 null。 */

package/lib/lark-endpoint-commands.js

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

package/lib/lark-runtime-state.js

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

package/lib/media-upload.d.ts

@@ -9,7 +9,7 @@ export declare function resolveMediaBinary(media: MediaRef, download?: (url: str
 /** /im/v1/images 的 multipart body（image_type=message 用于消息内图片）。 */
 export declare function buildImageUploadForm(binary: MediaBinary): FormData;
 /**
- * 出站 image 段的媒体引用：已有 image_key/file_key 的视为已物化；
- * 否则读 canonical `data.media`，兼容旧 wire `{url,file,base64}` 字段。
+ * 出站 image 段待上传的媒体引用（canonical `data.media` 唯一来源）：
+ * kind=file 为平台不透明引用（image_key/file_key），已物化无需再上传，返回 undefined。
  */
 export declare function readOutboundImageMedia(data: Record<string, unknown>): MediaRef | undefined;

package/lib/media-upload.js

@@ -5,7 +5,7 @@
  */
 import { readFile } from 'node:fs/promises';
 import { basename } from 'node:path';
-import { isMediaRef, mediaRefFromLegacyData } from '@zhin.js/core';
+import { isMediaRef } from '@zhin.js/core';
 const MIME_EXT = {
     'image/jpeg': 'jpg',
     'image/png': 'png',
@@ -46,17 +46,13 @@ export function buildImageUploadForm(binary) {
     return form;
 }
 /**
- * 出站 image 段的媒体引用：已有 image_key/file_key 的视为已物化；
- * 否则读 canonical `data.media`，兼容旧 wire `{url,file,base64}` 字段。
+ * 出站 image 段待上传的媒体引用（canonical `data.media` 唯一来源）：
+ * kind=file 为平台不透明引用（image_key/file_key），已物化无需再上传，返回 undefined。
  */
 export function readOutboundImageMedia(data) {
-    if (typeof data.image_key === 'string' && data.image_key)
+    if (!isMediaRef(data.media))
         return undefined;
-    if (typeof data.file_key === 'string' && data.file_key)
+    if (data.media.kind === 'file')
         return undefined;
-    if (typeof data.key === 'string' && data.key)
-        return undefined;
-    if (isMediaRef(data.media))
-        return data.media;
-    return mediaRefFromLegacyData(data);
+    return data.media;
 }

package/lib/protocol.js

@@ -3,6 +3,9 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import { createHash, timingSafeEqual } from 'node:crypto';
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('lark');
 export function resolveLarkConfig(config = {}) {
     const entry = config.endpoints?.find((item) => item.context === 'lark');
     const appId = config.appId ?? entry?.appId ?? process.env.LARK_APP_ID;
@@ -169,23 +172,39 @@ export function formatOutboundBody(payload) {
                 break;
             case 'image':
                 if (!media) {
-                    media = {
-                        msg_type: 'image',
-                        content: JSON.stringify({
-                            // image_key 由 endpoint 上传物化写入；file_key/key/url 为旧调用方兼容入口。
-                            image_key: data.image_key ?? data.file_key ?? data.key ?? data.url,
-                        }),
-                    };
+                    // image_key 唯一来源：canonical MediaRef kind=file（endpoint 上传物化产物或调用方既有平台引用）
+                    const ref = data.media;
+                    if (isMediaRef(ref) && ref.kind === 'file') {
+                        media = {
+                            msg_type: 'image',
+                            content: JSON.stringify({ image_key: ref.value }),
+                        };
+                    }
+                    else {
+                        logger.warn(formatCompact({
+                            op: 'lark_outbound_media_dropped',
+                            type: 'image',
+                            reason: isMediaRef(ref) ? 'unmaterialized_media' : 'missing_media_ref',
+                        }));
+                    }
                 }
                 break;
             case 'file':
                 if (!media) {
-                    media = {
-                        msg_type: 'file',
-                        content: JSON.stringify({
-                            file_key: data.file_key ?? data.key,
-                        }),
-                    };
+                    const ref = data.media;
+                    if (isMediaRef(ref) && ref.kind === 'file') {
+                        media = {
+                            msg_type: 'file',
+                            content: JSON.stringify({ file_key: ref.value }),
+                        };
+                    }
+                    else {
+                        logger.warn(formatCompact({
+                            op: 'lark_outbound_media_dropped',
+                            type: 'file',
+                            reason: isMediaRef(ref) ? 'unmaterialized_media' : 'missing_media_ref',
+                        }));
+                    }
                 }
                 break;
             case 'card':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-lark",
-  "version": "5.0.5",
+  "version": "6.0.0",
   "description": "Zhin.js Lark/Feishu (飞书) adapter for Plugin Runtime (HTTP webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,21 +34,21 @@
     "directory": "plugins/adapters/lark"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/command": "1.0.4",
-    "@zhin.js/core": "1.4.3",
+    "@zhin.js/adapter": "1.1.3",
+    "@zhin.js/command": "1.0.5",
+    "@zhin.js/core": "1.5.0",
     "@zhin.js/host-http": "1.0.4",
     "@zhin.js/logger": "1.0.75",
     "@zhin.js/plugin-runtime": "1.1.1"
   },
   "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/adapter": "1.1.3",
+    "@zhin.js/agent": "1.1.0",
+    "@zhin.js/core": "1.5.0",
     "@zhin.js/host-http": "1.0.4",
     "@zhin.js/plugin-runtime": "1.1.1",
-    "zhin.js": "5.0.3"
+    "zhin.js": "6.0.0"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -66,8 +66,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.0",
+    "zhin.js": "6.0.0"
   },
   "files": [
     "adapters",

package/plugin.js

@@ -9,7 +9,7 @@ export default definePlugin({
         displayName: 'Lark/Feishu (飞书) Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表（lark endpoint list 的"运行中"数据源）
+        // 运行中 endpoint 注册表（lark.endpoint list 的"运行中"数据源）
         context.resources.provide(larkRuntimeStateToken, createEndpointRuntimeState());
         return registerLarkPlatformPermitChecker();
     },

package/src/endpoint.ts

@@ -176,9 +176,15 @@ export class LarkEndpoint implements EndpointInstance {
     return messageId;
   }
 
+  async recallMessage(messageId: string): Promise<void> {
+    if (!messageId || messageId.startsWith('outbound:')) return;
+    await this.#request(`/im/v1/messages/${messageId}`, { method: 'DELETE' });
+  }
+
   /**
    * im/v1 消息 image 段只接受 image_key：canonical MediaRef（base64/本地路径/URL）
-   * 先经 /im/v1/images 物化；上传失败降级为文本（alt 优先），不阻断发送。
+   * 先经 /im/v1/images 物化，产物回写为 MediaRef kind=file（平台不透明引用）；
+   * 上传失败降级为文本（alt 优先），不阻断发送。
    */
   async #materializeOutboundMedia(payload: unknown): Promise<unknown> {
     if (!Array.isArray(payload)) return payload;
@@ -194,7 +200,10 @@ export class LarkEndpoint implements EndpointInstance {
         const alt = typeof data.alt === 'string' && data.alt ? data.alt : '[image]';
         return { type: 'text', data: { text: alt } };
       }
-      return { type: 'image', data: { image_key: imageKey } };
+      return {
+        type: 'image',
+        data: { media: { kind: 'file', value: imageKey } },
+      };
     }));
   }
 

package/src/lark-endpoint-commands.ts

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

package/src/lark-runtime-state.ts

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

package/src/media-upload.ts

@@ -5,7 +5,7 @@
  */
 import { readFile } from 'node:fs/promises';
 import { basename } from 'node:path';
-import { isMediaRef, mediaRefFromLegacyData, type MediaRef } from '@zhin.js/core';
+import { isMediaRef, type MediaRef } from '@zhin.js/core';
 
 export interface MediaBinary {
   readonly data: Buffer;
@@ -59,13 +59,11 @@ export function buildImageUploadForm(binary: MediaBinary): FormData {
 }
 
 /**
- * 出站 image 段的媒体引用：已有 image_key/file_key 的视为已物化；
- * 否则读 canonical `data.media`，兼容旧 wire `{url,file,base64}` 字段。
+ * 出站 image 段待上传的媒体引用（canonical `data.media` 唯一来源）：
+ * kind=file 为平台不透明引用（image_key/file_key），已物化无需再上传，返回 undefined。
  */
 export function readOutboundImageMedia(data: Record<string, unknown>): MediaRef | undefined {
-  if (typeof data.image_key === 'string' && data.image_key) return undefined;
-  if (typeof data.file_key === 'string' && data.file_key) return undefined;
-  if (typeof data.key === 'string' && data.key) return undefined;
-  if (isMediaRef(data.media)) return data.media;
-  return mediaRefFromLegacyData(data);
+  if (!isMediaRef(data.media)) return undefined;
+  if (data.media.kind === 'file') return undefined;
+  return data.media;
 }

package/src/protocol.ts

@@ -5,6 +5,10 @@
 
 import { createHash, 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('lark');
 
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface LarkAdapterConfig {
@@ -291,23 +295,37 @@ export function formatOutboundBody(payload: unknown): LarkSendBody {
         break;
       case 'image':
         if (!media) {
-          media = {
-            msg_type: 'image',
-            content: JSON.stringify({
-              // image_key 由 endpoint 上传物化写入；file_key/key/url 为旧调用方兼容入口。
-              image_key: data.image_key ?? data.file_key ?? data.key ?? data.url,
-            }),
-          };
+          // image_key 唯一来源：canonical MediaRef kind=file（endpoint 上传物化产物或调用方既有平台引用）
+          const ref = data.media;
+          if (isMediaRef(ref) && ref.kind === 'file') {
+            media = {
+              msg_type: 'image',
+              content: JSON.stringify({ image_key: ref.value }),
+            };
+          } else {
+            logger.warn(formatCompact({
+              op: 'lark_outbound_media_dropped',
+              type: 'image',
+              reason: isMediaRef(ref) ? 'unmaterialized_media' : 'missing_media_ref',
+            }));
+          }
         }
         break;
       case 'file':
         if (!media) {
-          media = {
-            msg_type: 'file',
-            content: JSON.stringify({
-              file_key: data.file_key ?? data.key,
-            }),
-          };
+          const ref = data.media;
+          if (isMediaRef(ref) && ref.kind === 'file') {
+            media = {
+              msg_type: 'file',
+              content: JSON.stringify({ file_key: ref.value }),
+            };
+          } else {
+            logger.warn(formatCompact({
+              op: 'lark_outbound_media_dropped',
+              type: 'file',
+              reason: isMediaRef(ref) ? 'unmaterialized_media' : 'missing_media_ref',
+            }));
+          }
         }
         break;
       case 'card':