@zhin.js/adapter-onebot12 4.0.5 → 5.0.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @zhin.js/adapter-onebot12
 
+## 5.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@6.0.0
+
 ## 4.0.5
 
 ### Patch Changes

package/adapters/onebot12.js

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

package/adapters/onebot12.ts

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

package/lib/onebot12-endpoint-commands.js

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

package/lib/onebot12-runtime-state.js

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

package/lib/protocol.d.ts

@@ -137,13 +137,14 @@ export declare function isBotMentioned(ev: OneBot12Event): boolean;
  * canonical MediaRef → OneBot 12 媒体字段（扩展字段降级形状）。
  * spec 正式投递形状是 `file_id`（先 upload_file 物化，见
  * {@link uploadOneBot12MediaSegments}）；上传失败时按常见扩展字段
- * 降级输出：url → `url`、base64 → `data`、本地路径 → `path`。
+ * 降级输出：url → `url`、base64 → `data`、本地路径 → `path`；
+ * kind=file（平台不透明引用）直接按 `file_id` 复投。
  */
 export declare function mediaRefToOneBot12Fields(media: MediaRef): Record<string, unknown>;
 /**
  * Wire-encode an already-rendered outbound payload into OneBot 12 message segments.
  * 入参假定已经 core `normalizeOutboundPayload` 归一为 canonical Segment[]；
- * 旧 wire 形状（mention / 裸 `{url,file,base64}`）保持兼容透传。
+ * 媒体段只认 `data.media`（canonical MediaRef），无 MediaRef 的媒体段 warn 后丢弃。
  */
 export declare function formatOutboundSegments(payload: unknown): OneBot12Segment[];
 /** 端点动作调用签名（WS echo 请求 / webhook api_url HTTP）。 */

package/lib/protocol.js

@@ -3,7 +3,9 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://12.onebot.dev/
  */
-import { isMediaRef, mediaRefFromLegacyData } from '@zhin.js/core';
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('onebot12');
 export function resolveOneBot12Config(config = {}) {
     const entry = config.endpoints?.find((item) => item.context === 'onebot12');
     const connection = config.connection
@@ -145,17 +147,19 @@ export function isBotMentioned(ev) {
 }
 /** OneBot 12 携带媒体的段类型。 */
 const ONEBOT12_MEDIA_TYPES = new Set(['image', 'voice', 'audio', 'video', 'file']);
-/** 媒体段 data 里的 canonical-only / legacy 媒体字段，归一后不重复进 wire。 */
-const MEDIA_DATA_SKIP_KEYS = new Set([
-    'media', 'alt', 'mime_type', 'url', 'file', 'base64', 'data', 'path',
-]);
+/** 媒体段 data 里的 canonical 字段，归一后不重复进 wire。 */
+const MEDIA_DATA_SKIP_KEYS = new Set(['media', 'alt', 'mime_type']);
 /**
  * canonical MediaRef → OneBot 12 媒体字段（扩展字段降级形状）。
  * spec 正式投递形状是 `file_id`（先 upload_file 物化，见
  * {@link uploadOneBot12MediaSegments}）；上传失败时按常见扩展字段
- * 降级输出：url → `url`、base64 → `data`、本地路径 → `path`。
+ * 降级输出：url → `url`、base64 → `data`、本地路径 → `path`；
+ * kind=file（平台不透明引用）直接按 `file_id` 复投。
  */
 export function mediaRefToOneBot12Fields(media) {
+    if (media.kind === 'file') {
+        return { file_id: media.value };
+    }
     if (media.kind === 'base64') {
         const value = media.value.startsWith('base64://')
             ? media.value.slice('base64://'.length)
@@ -179,16 +183,24 @@ function oneBot12MediaSegment(type, data) {
     // 已物化为 file_id 的段是 spec 正式形状，原样透传。
     if (typeof data.file_id === 'string' && data.file_id)
         return { type, data };
-    const media = isMediaRef(data.media) ? data.media : mediaRefFromLegacyData(data);
-    if (!media)
-        return { type, data };
+    // canonical MediaRef 唯一来源（中央 normalizeOutboundPayload 已保证 canonical）
+    const media = isMediaRef(data.media) ? data.media : undefined;
+    if (!media) {
+        logger.warn(formatCompact({
+            op: 'onebot12_outbound_media_dropped',
+            type,
+            reason: 'missing_media_ref',
+        }));
+        return null;
+    }
     return { type, data: { ...oneBot12MediaExtra(data), ...mediaRefToOneBot12Fields(media) } };
 }
 /**
  * canonical Segment → OneBot 12 数组段：
  * - mention → mention（`user_id: target`，`target: 'all'` → mention_all）；
  * - reply（`message_id`）→ reply（`message_id`）；
- * - image / voice / audio / video / file 的 MediaRef → url/data/path 扩展字段；
+ * - image / voice / audio / video / file 的 MediaRef → url/data/path/file_id 字段，
+ *   无 canonical MediaRef 的媒体段 warn 后丢弃（返回 null）；
  * - 其余（已是 wire 形状的段、平台扩展段）原样透传。
  */
 function canonicalToOneBotSegment(segment) {
@@ -218,7 +230,7 @@ function canonicalToOneBotSegment(segment) {
 /**
  * Wire-encode an already-rendered outbound payload into OneBot 12 message segments.
  * 入参假定已经 core `normalizeOutboundPayload` 归一为 canonical Segment[]；
- * 旧 wire 形状（mention / 裸 `{url,file,base64}`）保持兼容透传。
+ * 媒体段只认 `data.media`（canonical MediaRef），无 MediaRef 的媒体段 warn 后丢弃。
  */
 export function formatOutboundSegments(payload) {
     if (typeof payload === 'string') {
@@ -243,7 +255,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: '' } }];
 }
@@ -296,7 +310,9 @@ async function uploadOneMediaSegment(item, callAction, onUploadFailed) {
     const data = segment.data ?? {};
     if (typeof data.file_id === 'string' && data.file_id)
         return item;
-    const media = isMediaRef(data.media) ? data.media : mediaRefFromLegacyData(data);
+    // canonical MediaRef 唯一来源；无 MediaRef 的段原样保留，由
+    // formatOutboundSegments warn 后丢弃。
+    const media = isMediaRef(data.media) ? data.media : undefined;
     if (!media)
         return item;
     // kind=file：平台不透明引用（OB12 file_id 复投），直接物化为 file_id。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-onebot12",
-  "version": "4.0.5",
+  "version": "5.0.0",
   "description": "Zhin.js OneBot 12 adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -40,9 +40,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"
@@ -55,10 +55,10 @@
     "@zhin.js/host-http": "1.0.4"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/core": "1.4.3",
+    "@zhin.js/adapter": "1.1.3",
+    "@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

@@ -8,7 +8,7 @@ export default definePlugin({
         displayName: 'OneBot 12 Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表（onebot12 endpoint list 的"运行中"数据源）
+        // 运行中 endpoint 注册表（onebot12.endpoint list 的"运行中"数据源）
         context.resources.provide(onebot12RuntimeStateToken, createEndpointRuntimeState());
     },
 });

package/src/onebot12-endpoint-commands.ts

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

package/src/onebot12-runtime-state.ts

@@ -1,6 +1,6 @@
 /**
  * OneBot12 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `onebot12 endpoint` 命令共享（同一 owner generation）。
+ * 由 plugin.ts setup() provide，adapter create 与 `onebot12.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://12.onebot.dev/
  */
-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('onebot12');
 
 /** Transitional legacy endpoint row (`endpoints[]` with `context: onebot12`). */
 export interface OneBot12LegacyEndpointRow {
@@ -277,18 +280,20 @@ export function isBotMentioned(ev: OneBot12Event): boolean {
 /** OneBot 12 携带媒体的段类型。 */
 const ONEBOT12_MEDIA_TYPES = new Set(['image', 'voice', 'audio', 'video', 'file']);
 
-/** 媒体段 data 里的 canonical-only / legacy 媒体字段，归一后不重复进 wire。 */
-const MEDIA_DATA_SKIP_KEYS = new Set([
-  'media', 'alt', 'mime_type', 'url', 'file', 'base64', 'data', 'path',
-]);
+/** 媒体段 data 里的 canonical 字段，归一后不重复进 wire。 */
+const MEDIA_DATA_SKIP_KEYS = new Set(['media', 'alt', 'mime_type']);
 
 /**
  * canonical MediaRef → OneBot 12 媒体字段（扩展字段降级形状）。
  * spec 正式投递形状是 `file_id`（先 upload_file 物化，见
  * {@link uploadOneBot12MediaSegments}）；上传失败时按常见扩展字段
- * 降级输出：url → `url`、base64 → `data`、本地路径 → `path`。
+ * 降级输出：url → `url`、base64 → `data`、本地路径 → `path`；
+ * kind=file（平台不透明引用）直接按 `file_id` 复投。
  */
 export function mediaRefToOneBot12Fields(media: MediaRef): Record<string, unknown> {
+  if (media.kind === 'file') {
+    return { file_id: media.value };
+  }
   if (media.kind === 'base64') {
     const value = media.value.startsWith('base64://')
       ? media.value.slice('base64://'.length)
@@ -312,11 +317,19 @@ function oneBot12MediaExtra(data: Record<string, unknown>): Record<string, unkno
 function oneBot12MediaSegment(
   type: string,
   data: Record<string, unknown>,
-): OneBot12Segment {
+): OneBot12Segment | null {
   // 已物化为 file_id 的段是 spec 正式形状，原样透传。
   if (typeof data.file_id === 'string' && data.file_id) return { type, data };
-  const media = isMediaRef(data.media) ? data.media : mediaRefFromLegacyData(data);
-  if (!media) return { type, data };
+  // canonical MediaRef 唯一来源（中央 normalizeOutboundPayload 已保证 canonical）
+  const media = isMediaRef(data.media) ? data.media : undefined;
+  if (!media) {
+    logger.warn(formatCompact({
+      op: 'onebot12_outbound_media_dropped',
+      type,
+      reason: 'missing_media_ref',
+    }));
+    return null;
+  }
   return { type, data: { ...oneBot12MediaExtra(data), ...mediaRefToOneBot12Fields(media) } };
 }
 
@@ -324,10 +337,11 @@ function oneBot12MediaSegment(
  * canonical Segment → OneBot 12 数组段：
  * - mention → mention（`user_id: target`，`target: 'all'` → mention_all）；
  * - reply（`message_id`）→ reply（`message_id`）；
- * - image / voice / audio / video / file 的 MediaRef → url/data/path 扩展字段；
+ * - image / voice / audio / video / file 的 MediaRef → url/data/path/file_id 字段，
+ *   无 canonical MediaRef 的媒体段 warn 后丢弃（返回 null）；
  * - 其余（已是 wire 形状的段、平台扩展段）原样透传。
  */
-function canonicalToOneBotSegment(segment: OneBot12WireSegment): OneBot12Segment {
+function canonicalToOneBotSegment(segment: OneBot12WireSegment): OneBot12Segment | null {
   const data = segment.data ?? {};
   switch (segment.type) {
     case 'mention': {
@@ -352,7 +366,7 @@ function canonicalToOneBotSegment(segment: OneBot12WireSegment): OneBot12Segment
 /**
  * Wire-encode an already-rendered outbound payload into OneBot 12 message segments.
  * 入参假定已经 core `normalizeOutboundPayload` 归一为 canonical Segment[]；
- * 旧 wire 形状（mention / 裸 `{url,file,base64}`）保持兼容透传。
+ * 媒体段只认 `data.media`（canonical MediaRef），无 MediaRef 的媒体段 warn 后丢弃。
  */
 export function formatOutboundSegments(payload: unknown): OneBot12Segment[] {
   if (typeof payload === 'string') {
@@ -380,7 +394,8 @@ export function formatOutboundSegments(payload: unknown): OneBot12Segment[] {
       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: '' } }];
 }
@@ -446,7 +461,9 @@ async function uploadOneMediaSegment(
   if (typeof segment.type !== 'string' || !ONEBOT12_MEDIA_TYPES.has(segment.type)) return item;
   const data = segment.data ?? {};
   if (typeof data.file_id === 'string' && data.file_id) return item;
-  const media = isMediaRef(data.media) ? data.media : mediaRefFromLegacyData(data);
+  // canonical MediaRef 唯一来源；无 MediaRef 的段原样保留，由
+  // formatOutboundSegments warn 后丢弃。
+  const media = isMediaRef(data.media) ? data.media : undefined;
   if (!media) return item;
   // kind=file：平台不透明引用（OB12 file_id 复投），直接物化为 file_id。
   if (media.kind === 'file') {