@zhin.js/adapter-milky 5.0.5 → 6.0.0

package/CHANGELOG.md

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

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

package/adapters/milky.ts

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

package/lib/milky-endpoint-commands.js

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

package/lib/milky-runtime-state.js

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

package/lib/protocol.d.ts

@@ -143,6 +143,8 @@ export declare function parseSendTarget(target: string): ParsedSendTarget;
 /**
  * Wire-encode an already-rendered outbound payload into Milky outgoing segments.
  * Segment canonicalization is intentionally not done here.
+ * 媒体段（image/audio/record/video）只消费 canonical `data.media` MediaRef；
+ * file 段 Milky 消息 API 无对应 wire 段（文件走 upload_* API），warn + 丢弃。
  */
 export declare function formatOutboundSegments(payload: unknown): MilkyOutgoingSegment[];
 export declare function buildSendAction(target: string, message: MilkyOutgoingSegment[]): {

package/lib/protocol.js

@@ -3,6 +3,9 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://milky.ntqqrev.org/
  */
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('milky');
 function normalizeConnection(connection) {
     if (connection === 'sse' || connection === 'webhook' || connection === 'wss')
         return connection;
@@ -300,9 +303,52 @@ export function parseSendTarget(target) {
         return { message_type: 'private', id: rest };
     return { message_type: 'private', id: target };
 }
+/**
+ * 解析 image/audio/video 段的投递 uri（canonical MediaRef 唯一来源）：
+ * - kind=url → http(s):// 直发；
+ * - kind=base64 → base64:// 直发；
+ * - kind=path / file → Milky 资源 uri 仅消费 http(s):// 与 base64://，不支持，丢弃。
+ */
+function resolveMediaUri(data) {
+    const media = data.media;
+    if (!isMediaRef(media))
+        return undefined;
+    if (media.kind === 'url')
+        return media.value;
+    if (media.kind === 'base64') {
+        return media.value.startsWith('base64://') ? media.value : `base64://${media.value}`;
+    }
+    return undefined;
+}
+/** 媒体段 → Milky 资源段（image/record/video）；不可投递时 warn + 丢弃。 */
+function normalizeMediaSegment(seg) {
+    const data = seg.data ?? {};
+    const wireType = seg.type === 'image'
+        ? 'image'
+        : seg.type === 'video'
+            ? 'video'
+            : 'record';
+    const uri = resolveMediaUri(data);
+    if (!uri) {
+        const media = data.media;
+        logger.warn(formatCompact({
+            op: 'milky_outbound_media_dropped',
+            type: seg.type,
+            reason: isMediaRef(media) ? 'unsupported_media_kind' : 'missing_media_ref',
+            ...(isMediaRef(media) ? { kind: media.kind } : {}),
+        }));
+        return null;
+    }
+    return {
+        type: wireType,
+        data: wireType === 'video' ? { uri, thumb_uri: data.thumb_uri } : { uri },
+    };
+}
 /**
  * Wire-encode an already-rendered outbound payload into Milky outgoing segments.
  * Segment canonicalization is intentionally not done here.
+ * 媒体段（image/audio/record/video）只消费 canonical `data.media` MediaRef；
+ * file 段 Milky 消息 API 无对应 wire 段（文件走 upload_* API），warn + 丢弃。
  */
 export function formatOutboundSegments(payload) {
     if (typeof payload === 'string') {
@@ -364,25 +410,21 @@ export function formatOutboundSegments(payload) {
                 break;
             }
             case 'image':
-                out.push({
-                    type: 'image',
-                    data: { uri: String(data.url ?? data.uri ?? '') },
-                });
-                break;
             case 'record':
-                out.push({
-                    type: 'record',
-                    data: { uri: String(data.url ?? data.uri ?? '') },
-                });
+            case 'audio':
+            case 'video': {
+                const media = normalizeMediaSegment(item);
+                if (media)
+                    out.push(media);
                 break;
-            case 'video':
-                out.push({
-                    type: 'video',
-                    data: {
-                        uri: String(data.url ?? data.uri ?? ''),
-                        thumb_uri: data.thumb_uri,
-                    },
-                });
+            }
+            case 'file':
+                // Milky 消息 API 无 file 段（文件走 upload_private/group_file），无法投递
+                logger.warn(formatCompact({
+                    op: 'milky_outbound_media_dropped',
+                    type,
+                    reason: 'unsupported_segment',
+                }));
                 break;
             default:
                 out.push({ type, data: data });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-milky",
-  "version": "5.0.5",
+  "version": "6.0.0",
   "description": "Zhin.js Milky 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"
@@ -53,16 +53,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

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

package/src/milky-endpoint-commands.ts

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

package/src/milky-runtime-state.ts

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

package/src/protocol.ts

@@ -4,7 +4,11 @@
  * Spec: https://milky.ntqqrev.org/
  */
 
+import { isMediaRef } from '@zhin.js/core';
 import type { Segment } from '@zhin.js/core/runtime';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+
+const logger = getLogger('milky');
 
 /** Transitional legacy endpoint row (`endpoints[]` with `context: milky`). */
 export interface MilkyLegacyEndpointRow {
@@ -435,9 +439,52 @@ export function parseSendTarget(target: string): ParsedSendTarget {
   return { message_type: 'private', id: target };
 }
 
+/**
+ * 解析 image/audio/video 段的投递 uri（canonical MediaRef 唯一来源）：
+ * - kind=url → http(s):// 直发；
+ * - kind=base64 → base64:// 直发；
+ * - kind=path / file → Milky 资源 uri 仅消费 http(s):// 与 base64://，不支持，丢弃。
+ */
+function resolveMediaUri(data: Record<string, unknown>): string | undefined {
+  const media = data.media;
+  if (!isMediaRef(media)) return undefined;
+  if (media.kind === 'url') return media.value;
+  if (media.kind === 'base64') {
+    return media.value.startsWith('base64://') ? media.value : `base64://${media.value}`;
+  }
+  return undefined;
+}
+
+/** 媒体段 → Milky 资源段（image/record/video）；不可投递时 warn + 丢弃。 */
+function normalizeMediaSegment(seg: MilkyWireSegment): MilkyOutgoingSegment | null {
+  const data = seg.data ?? {};
+  const wireType = seg.type === 'image'
+    ? 'image'
+    : seg.type === 'video'
+      ? 'video'
+      : 'record';
+  const uri = resolveMediaUri(data);
+  if (!uri) {
+    const media = data.media;
+    logger.warn(formatCompact({
+      op: 'milky_outbound_media_dropped',
+      type: seg.type,
+      reason: isMediaRef(media) ? 'unsupported_media_kind' : 'missing_media_ref',
+      ...(isMediaRef(media) ? { kind: media.kind } : {}),
+    }));
+    return null;
+  }
+  return {
+    type: wireType,
+    data: wireType === 'video' ? { uri, thumb_uri: data.thumb_uri } : { uri },
+  };
+}
+
 /**
  * Wire-encode an already-rendered outbound payload into Milky outgoing segments.
  * Segment canonicalization is intentionally not done here.
+ * 媒体段（image/audio/record/video）只消费 canonical `data.media` MediaRef；
+ * file 段 Milky 消息 API 无对应 wire 段（文件走 upload_* API），warn + 丢弃。
  */
 export function formatOutboundSegments(payload: unknown): MilkyOutgoingSegment[] {
   if (typeof payload === 'string') {
@@ -500,25 +547,20 @@ export function formatOutboundSegments(payload: unknown): MilkyOutgoingSegment[]
         break;
       }
       case 'image':
-        out.push({
-          type: 'image',
-          data: { uri: String(data.url ?? data.uri ?? '') },
-        });
-        break;
       case 'record':
-        out.push({
-          type: 'record',
-          data: { uri: String(data.url ?? data.uri ?? '') },
-        });
+      case 'audio':
+      case 'video': {
+        const media = normalizeMediaSegment(item);
+        if (media) out.push(media);
         break;
-      case 'video':
-        out.push({
-          type: 'video',
-          data: {
-            uri: String(data.url ?? data.uri ?? ''),
-            thumb_uri: data.thumb_uri,
-          },
-        });
+      }
+      case 'file':
+        // Milky 消息 API 无 file 段（文件走 upload_private/group_file），无法投递
+        logger.warn(formatCompact({
+          op: 'milky_outbound_media_dropped',
+          type,
+          reason: 'unsupported_segment',
+        }));
         break;
       default:
         out.push({ type, data: data as Record<string, unknown> });