@zhin.js/adapter-onebot11 5.0.5 → 6.0.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @zhin.js/adapter-onebot11
 
+## 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/onebot11.js

@@ -21,7 +21,7 @@ export default defineAdapter({
     create(context) {
         const config = resolveOneBot11Config(context.config);
         const gateway = context.use(messageGatewayToken);
-        // 注册到插件运行时状态（onebot11 endpoint list 的"运行中"数据源）
+        // 注册到插件运行时状态（onebot11.endpoint list 的"运行中"数据源）
         context.use(onebot11RuntimeStateToken).endpoints.set(config.name, {
             name: config.name,
             mode: config.connection,

package/adapters/onebot11.ts

@@ -28,7 +28,7 @@ export default defineAdapter<OneBot11AdapterConfig>({
   create(context) {
     const config = resolveOneBot11Config(context.config);
     const gateway = context.use(messageGatewayToken);
-    // 注册到插件运行时状态（onebot11 endpoint list 的"运行中"数据源）
+    // 注册到插件运行时状态（onebot11.endpoint list 的"运行中"数据源）
     context.use(onebot11RuntimeStateToken).endpoints.set(config.name, {
       name: config.name,
       mode: config.connection,

package/lib/onebot11-endpoint-commands.js

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

package/lib/onebot11-runtime-state.js

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

package/lib/protocol.d.ts

@@ -130,13 +130,14 @@ export declare function isOneBot11BotMentioned(input: {
 export declare function formatInboundMetadata(ev: OneBot11Event, endpoint: string): Readonly<Record<string, unknown>>;
 /**
  * canonical MediaRef → OneBot `file` 参数：url 直传、base64 → `base64://`、
- * 本地路径 → `file://`（路径在 OneBot 实现侧解析）。
+ * 本地路径 → `file://`（路径在 OneBot 实现侧解析）、kind=file 不透明引用原样透传。
  */
 export declare function mediaRefToOneBotFile(media: MediaRef): string;
 /**
  * Wire-encode an already-rendered outbound payload into OneBot 11 message segments.
  * 入参假定已经 core `normalizeOutboundPayload` 归一为 canonical Segment[]；
- * 旧 wire 形状（at / 裸 `{file,url,base64}`）保持兼容透传。
+ * 媒体段只消费 canonical `data.media`（无 MediaRef 的媒体段 warn + 丢弃），
+ * 其余 wire 形状段（at / 平台扩展段）原样透传。
  */
 export declare function formatOutboundSegments(payload: unknown): OneBot11Segment[];
 export declare function buildSendAction(target: string, message: OneBot11Segment[]): {

package/lib/protocol.js

@@ -3,7 +3,9 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://github.com/botuniverse/onebot-11
  */
-import { isMediaRef, mediaRefFromLegacyData } from '@zhin.js/core';
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('onebot11');
 function normalizeConnection(connection, legacyType) {
     if (connection === 'ws' || connection === 'wss')
         return connection;
@@ -172,7 +174,7 @@ export function formatInboundMetadata(ev, endpoint) {
 }
 /**
  * canonical MediaRef → OneBot `file` 参数：url 直传、base64 → `base64://`、
- * 本地路径 → `file://`（路径在 OneBot 实现侧解析）。
+ * 本地路径 → `file://`（路径在 OneBot 实现侧解析）、kind=file 不透明引用原样透传。
  */
 export function mediaRefToOneBotFile(media) {
     if (media.kind === 'base64') {
@@ -184,25 +186,36 @@ export function mediaRefToOneBotFile(media) {
     return media.value;
 }
 /** 媒体段 data 里的 canonical-only 字段，不进 OneBot wire。 */
-const MEDIA_DATA_SKIP_KEYS = new Set(['media', 'alt', 'url', 'base64', 'file', 'mime_type']);
+const MEDIA_DATA_SKIP_KEYS = new Set(['media', 'alt']);
+/**
+ * image / record / video 段：只消费 canonical `data.media` MediaRef，
+ * 映射为 OneBot `file` 参数；无 MediaRef 时 warn + 丢弃（返回 null）。
+ */
 function oneBotMediaSegment(type, data) {
-    const media = isMediaRef(data.media) ? data.media : mediaRefFromLegacyData(data);
-    if (!media)
-        return { type, data };
+    if (!isMediaRef(data.media)) {
+        logger.warn(formatCompact({
+            op: 'onebot11_outbound_media_dropped',
+            type,
+            reason: 'missing_media_ref',
+        }));
+        return null;
+    }
     const extra = {};
     for (const [key, value] of Object.entries(data)) {
         if (!MEDIA_DATA_SKIP_KEYS.has(key))
             extra[key] = value;
     }
-    return { type, data: { ...extra, file: mediaRefToOneBotFile(media) } };
+    return { type, data: { ...extra, file: mediaRefToOneBotFile(data.media) } };
 }
 /**
  * canonical Segment → OneBot 11 数组段：
  * - mention → at（`qq: target`）；
  * - reply（`message_id`）→ reply（`id`）；
- * - image / audio→record / video 的 MediaRef → `file`（url / base64:// / file://）；
+ * - image / audio→record / video 的 MediaRef → `file`（url / base64:// / file:// / 不透明引用）；
+ * - file 段无 OneBot 11 消息段承载（文件走 upload_*_file API），warn + 丢弃；
  * - face 取 `id`；
  * - 其余（已是 wire 形状的段、平台扩展段）原样透传。
+ * 返回 null 表示该段被丢弃。
  */
 function canonicalToOneBotSegment(segment) {
     const data = segment.data ?? {};
@@ -230,6 +243,13 @@ function canonicalToOneBotSegment(segment) {
             return oneBotMediaSegment(segment.type, data);
         case 'audio':
             return oneBotMediaSegment('record', data);
+        case 'file':
+            logger.warn(formatCompact({
+                op: 'onebot11_outbound_media_dropped',
+                type: 'file',
+                reason: 'file_segment_not_supported',
+            }));
+            return null;
         default:
             return { type: segment.type, data };
     }
@@ -237,7 +257,8 @@ function canonicalToOneBotSegment(segment) {
 /**
  * Wire-encode an already-rendered outbound payload into OneBot 11 message segments.
  * 入参假定已经 core `normalizeOutboundPayload` 归一为 canonical Segment[]；
- * 旧 wire 形状（at / 裸 `{file,url,base64}`）保持兼容透传。
+ * 媒体段只消费 canonical `data.media`（无 MediaRef 的媒体段 warn + 丢弃），
+ * 其余 wire 形状段（at / 平台扩展段）原样透传。
  */
 export function formatOutboundSegments(payload) {
     if (typeof payload === 'string') {
@@ -262,7 +283,9 @@ export function formatOutboundSegments(payload) {
             segs.push({ type: 'text', data: { text: item } });
             continue;
         }
-        segs.push(canonicalToOneBotSegment(item));
+        const seg = canonicalToOneBotSegment(item);
+        if (seg)
+            segs.push(seg);
     }
     return segs.length ? segs : [{ type: 'text', data: { text: '' } }];
 }

package/lib/ws-endpoint.d.ts

@@ -21,6 +21,7 @@ export declare class OneBot11WsEndpoint implements EndpointInstance {
         readonly target: string;
         readonly payload: unknown;
     }): Promise<string>;
+    recallMessage(messageId: string): Promise<void>;
     /** Public API for agent tools / callers. */
     callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
     setTitle(groupId: number, userId: number, title: string, duration?: number): Promise<boolean>;

package/lib/ws-endpoint.js

@@ -85,6 +85,11 @@ export class OneBot11WsEndpoint {
         }));
         return messageId;
     }
+    async recallMessage(messageId) {
+        if (!messageId)
+            return;
+        await this.callApi('delete_msg', { message_id: Number(messageId) });
+    }
     /** Public API for agent tools / callers. */
     callApi(action, params = {}) {
         return callOneBot11WsAction(this.#ws, this.#pending, this.#requestId, action, params);

package/lib/wss-endpoint.d.ts

@@ -21,6 +21,7 @@ export declare class OneBot11WssEndpoint implements EndpointInstance {
         readonly target: string;
         readonly payload: unknown;
     }): Promise<string>;
+    recallMessage(messageId: string): Promise<void>;
     callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
     setTitle(groupId: number, userId: number, title: string, duration?: number): Promise<boolean>;
     admit(ev: OneBot11Event): void;

package/lib/wss-endpoint.js

@@ -82,6 +82,11 @@ export class OneBot11WssEndpoint {
         const data = await this.callApi(action, params);
         return data?.message_id != null ? String(data.message_id) : '';
     }
+    async recallMessage(messageId) {
+        if (!messageId)
+            return;
+        await this.callApi('delete_msg', { message_id: Number(messageId) });
+    }
     callApi(action, params = {}) {
         return callOneBot11WsAction(this.#ws, this.#pending, this.#requestId, action, params);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-onebot11",
-  "version": "5.0.5",
+  "version": "6.0.0",
   "description": "Zhin.js OneBot 11 adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -41,9 +41,9 @@
   },
   "dependencies": {
     "ws": "^8.21.1",
-    "@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"
@@ -54,16 +54,16 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.10",
+    "@zhin.js/agent": "1.1.0",
     "@zhin.js/host-http": "1.0.4"
   },
   "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/plugin-runtime": "1.1.1",
-    "zhin.js": "5.0.3"
+    "zhin.js": "6.0.0"
   },
   "peerDependenciesMeta": {
     "zhin.js": {

package/plugin.js

@@ -9,7 +9,7 @@ export default definePlugin({
         displayName: 'OneBot 11 Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表（onebot11 endpoint list 的"运行中"数据源）
+        // 运行中 endpoint 注册表（onebot11.endpoint list 的"运行中"数据源）
         context.resources.provide(onebot11RuntimeStateToken, createEndpointRuntimeState());
         // 平台权限门禁：scene_admin / scene_owner 由 sender role 判定（见 ws/wss-endpoint admit metadata）
         return registerDefaultScenePlatformPermitChecker('onebot11');

package/src/onebot11-endpoint-commands.ts

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

package/src/onebot11-runtime-state.ts

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

package/src/protocol.ts

@@ -3,7 +3,10 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://github.com/botuniverse/onebot-11
  */
-import { isMediaRef, mediaRefFromLegacyData, type MediaRef } from '@zhin.js/core';
+import { isMediaRef, type MediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+
+const logger = getLogger('onebot11');
 
 /** Transitional legacy endpoint row (`endpoints[]` with `context: onebot11`). */
 export interface OneBot11LegacyEndpointRow {
@@ -295,7 +298,7 @@ export function formatInboundMetadata(
 
 /**
  * canonical MediaRef → OneBot `file` 参数：url 直传、base64 → `base64://`、
- * 本地路径 → `file://`（路径在 OneBot 实现侧解析）。
+ * 本地路径 → `file://`（路径在 OneBot 实现侧解析）、kind=file 不透明引用原样透传。
  */
 export function mediaRefToOneBotFile(media: MediaRef): string {
   if (media.kind === 'base64') {
@@ -308,30 +311,42 @@ export function mediaRefToOneBotFile(media: MediaRef): string {
 }
 
 /** 媒体段 data 里的 canonical-only 字段，不进 OneBot wire。 */
-const MEDIA_DATA_SKIP_KEYS = new Set(['media', 'alt', 'url', 'base64', 'file', 'mime_type']);
+const MEDIA_DATA_SKIP_KEYS = new Set(['media', 'alt']);
 
+/**
+ * image / record / video 段：只消费 canonical `data.media` MediaRef，
+ * 映射为 OneBot `file` 参数；无 MediaRef 时 warn + 丢弃（返回 null）。
+ */
 function oneBotMediaSegment(
   type: 'image' | 'record' | 'video',
   data: Record<string, unknown>,
-): OneBot11Segment {
-  const media = isMediaRef(data.media) ? data.media : mediaRefFromLegacyData(data);
-  if (!media) return { type, data };
+): OneBot11Segment | null {
+  if (!isMediaRef(data.media)) {
+    logger.warn(formatCompact({
+      op: 'onebot11_outbound_media_dropped',
+      type,
+      reason: 'missing_media_ref',
+    }));
+    return null;
+  }
   const extra: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(data)) {
     if (!MEDIA_DATA_SKIP_KEYS.has(key)) extra[key] = value;
   }
-  return { type, data: { ...extra, file: mediaRefToOneBotFile(media) } };
+  return { type, data: { ...extra, file: mediaRefToOneBotFile(data.media) } };
 }
 
 /**
  * canonical Segment → OneBot 11 数组段：
  * - mention → at（`qq: target`）；
  * - reply（`message_id`）→ reply（`id`）；
- * - image / audio→record / video 的 MediaRef → `file`（url / base64:// / file://）；
+ * - image / audio→record / video 的 MediaRef → `file`（url / base64:// / file:// / 不透明引用）；
+ * - file 段无 OneBot 11 消息段承载（文件走 upload_*_file API），warn + 丢弃；
  * - face 取 `id`；
  * - 其余（已是 wire 形状的段、平台扩展段）原样透传。
+ * 返回 null 表示该段被丢弃。
  */
-function canonicalToOneBotSegment(segment: OneBot11WireSegment): OneBot11Segment {
+function canonicalToOneBotSegment(segment: OneBot11WireSegment): OneBot11Segment | null {
   const data = segment.data ?? {};
   switch (segment.type) {
     case 'mention': {
@@ -354,6 +369,13 @@ function canonicalToOneBotSegment(segment: OneBot11WireSegment): OneBot11Segment
       return oneBotMediaSegment(segment.type, data);
     case 'audio':
       return oneBotMediaSegment('record', data);
+    case 'file':
+      logger.warn(formatCompact({
+        op: 'onebot11_outbound_media_dropped',
+        type: 'file',
+        reason: 'file_segment_not_supported',
+      }));
+      return null;
     default:
       return { type: segment.type, data };
   }
@@ -362,7 +384,8 @@ function canonicalToOneBotSegment(segment: OneBot11WireSegment): OneBot11Segment
 /**
  * Wire-encode an already-rendered outbound payload into OneBot 11 message segments.
  * 入参假定已经 core `normalizeOutboundPayload` 归一为 canonical Segment[]；
- * 旧 wire 形状（at / 裸 `{file,url,base64}`）保持兼容透传。
+ * 媒体段只消费 canonical `data.media`（无 MediaRef 的媒体段 warn + 丢弃），
+ * 其余 wire 形状段（at / 平台扩展段）原样透传。
  */
 export function formatOutboundSegments(payload: unknown): OneBot11Segment[] {
   if (typeof payload === 'string') {
@@ -390,7 +413,8 @@ export function formatOutboundSegments(payload: unknown): OneBot11Segment[] {
       segs.push({ type: 'text', data: { text: item } });
       continue;
     }
-    segs.push(canonicalToOneBotSegment(item));
+    const seg = canonicalToOneBotSegment(item);
+    if (seg) segs.push(seg);
   }
   return segs.length ? segs : [{ type: 'text', data: { text: '' } }];
 }

package/src/ws-endpoint.ts

@@ -129,6 +129,11 @@ export class OneBot11WsEndpoint implements EndpointInstance {
     return messageId;
   }
 
+  async recallMessage(messageId: string): Promise<void> {
+    if (!messageId) return;
+    await this.callApi('delete_msg', { message_id: Number(messageId) });
+  }
+
   /** Public API for agent tools / callers. */
   callApi(action: string, params: Record<string, unknown> = {}): Promise<unknown> {
     return callOneBot11WsAction(this.#ws, this.#pending, this.#requestId, action, params);

package/src/wss-endpoint.ts

@@ -123,6 +123,11 @@ export class OneBot11WssEndpoint implements EndpointInstance {
     return data?.message_id != null ? String(data.message_id) : '';
   }
 
+  async recallMessage(messageId: string): Promise<void> {
+    if (!messageId) return;
+    await this.callApi('delete_msg', { message_id: Number(messageId) });
+  }
+
   callApi(action: string, params: Record<string, unknown> = {}): Promise<unknown> {
     return callOneBot11WsAction(this.#ws, this.#pending, this.#requestId, action, params);
   }