@zhin.js/adapter-satori 4.0.4 → 5.0.1

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @zhin.js/adapter-satori
 
+## 5.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/command@1.0.6
+  - @zhin.js/core@1.5.1
+  - zhin.js@6.0.1
+
+## 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.4
 
 ### Patch Changes

package/adapters/satori.js

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

package/adapters/satori.ts

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

package/lib/protocol.js

@@ -4,6 +4,9 @@
  * Spec: https://satori.chat/zh-CN/protocol/overview.html
  */
 import { pickCredential } from '@zhin.js/adapter';
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('satori');
 /** Opcode：EVENT=0, PING=1, PONG=2, IDENTIFY=3, READY=4, META=5 */
 export const SatoriOpcode = {
     EVENT: 0,
@@ -141,6 +144,34 @@ export function parseMessageRef(id) {
     }
     return { channelId: '', messageId: id };
 }
+/**
+ * 解析媒体段（image/audio/video/file）的投递源，canonical MediaRef 为唯一来源：
+ * - kind=url → 直发 URL；
+ * - kind=base64 → 规范为 `base64://` 前缀内联（Satori img/file 元素消费内联数据）。
+ * 无 canonical 媒体引用或来源不可投递（path / file 本端点不物化）时 warn + 丢弃。
+ */
+function resolveMediaSrc(type, data) {
+    const media = data.media;
+    if (!isMediaRef(media)) {
+        logger.warn(formatCompact({
+            op: 'satori_outbound_media_dropped',
+            type,
+            reason: 'missing_media_ref',
+        }));
+        return undefined;
+    }
+    if (media.kind === 'url')
+        return media.value;
+    if (media.kind === 'base64') {
+        return media.value.startsWith('base64://') ? media.value : `base64://${media.value}`;
+    }
+    logger.warn(formatCompact({
+        op: 'satori_outbound_media_dropped',
+        type,
+        reason: `unsupported_media_kind:${media.kind}`,
+    }));
+    return undefined;
+}
 /**
  * Wire-encode an already-rendered outbound payload into Satori message content.
  * Segment canonicalization is intentionally not done here.
@@ -174,13 +205,14 @@ export function formatSatoriOutbound(payload) {
                 parts.push(`@${String(data.name ?? data.id ?? data.target ?? '')}`);
                 break;
             case 'image':
-                if (typeof data.url === 'string')
-                    parts.push(`[image:${data.url}]`);
-                break;
-            case 'file':
-                if (typeof data.url === 'string')
-                    parts.push(`[file:${data.url}]`);
+            case 'audio':
+            case 'video':
+            case 'file': {
+                const src = resolveMediaSrc(item.type, data);
+                if (src)
+                    parts.push(`[${item.type}:${src}]`);
                 break;
+            }
             default:
                 break;
         }

package/lib/satori-endpoint-commands.js

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

package/lib/satori-runtime-state.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-satori",
-  "version": "4.0.4",
+  "version": "5.0.1",
   "description": "Zhin.js Satori adapter for Plugin Runtime (WebSocket client)",
   "type": "module",
   "main": "./lib/index.js",
@@ -39,25 +39,25 @@
   },
   "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/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"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
     "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "@zhin.js/host-http": "1.0.4"
+    "@zhin.js/host-http": "1.0.5"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/core": "1.4.3",
-    "@zhin.js/plugin-runtime": "1.1.1",
-    "zhin.js": "5.0.3"
+    "@zhin.js/adapter": "1.1.4",
+    "@zhin.js/core": "1.5.1",
+    "@zhin.js/plugin-runtime": "1.1.2",
+    "zhin.js": "6.0.1"
   },
   "peerDependenciesMeta": {
     "zhin.js": {

package/plugin.js

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

package/src/protocol.ts

@@ -5,6 +5,10 @@
  */
 
 import { pickCredential } from '@zhin.js/adapter';
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+
+const logger = getLogger('satori');
 
 /** Opcode：EVENT=0, PING=1, PONG=2, IDENTIFY=3, READY=4, META=5 */
 export const SatoriOpcode = {
@@ -260,6 +264,34 @@ export function parseMessageRef(id: string): { channelId: string; messageId: str
   return { channelId: '', messageId: id };
 }
 
+/**
+ * 解析媒体段（image/audio/video/file）的投递源，canonical MediaRef 为唯一来源：
+ * - kind=url → 直发 URL；
+ * - kind=base64 → 规范为 `base64://` 前缀内联（Satori img/file 元素消费内联数据）。
+ * 无 canonical 媒体引用或来源不可投递（path / file 本端点不物化）时 warn + 丢弃。
+ */
+function resolveMediaSrc(type: string, data: Record<string, unknown>): string | undefined {
+  const media = data.media;
+  if (!isMediaRef(media)) {
+    logger.warn(formatCompact({
+      op: 'satori_outbound_media_dropped',
+      type,
+      reason: 'missing_media_ref',
+    }));
+    return undefined;
+  }
+  if (media.kind === 'url') return media.value;
+  if (media.kind === 'base64') {
+    return media.value.startsWith('base64://') ? media.value : `base64://${media.value}`;
+  }
+  logger.warn(formatCompact({
+    op: 'satori_outbound_media_dropped',
+    type,
+    reason: `unsupported_media_kind:${media.kind}`,
+  }));
+  return undefined;
+}
+
 /**
  * Wire-encode an already-rendered outbound payload into Satori message content.
  * Segment canonicalization is intentionally not done here.
@@ -294,11 +326,13 @@ export function formatSatoriOutbound(payload: unknown): string {
         parts.push(`@${String(data.name ?? data.id ?? data.target ?? '')}`);
         break;
       case 'image':
-        if (typeof data.url === 'string') parts.push(`[image:${data.url}]`);
-        break;
-      case 'file':
-        if (typeof data.url === 'string') parts.push(`[file:${data.url}]`);
+      case 'audio':
+      case 'video':
+      case 'file': {
+        const src = resolveMediaSrc(item.type, data);
+        if (src) parts.push(`[${item.type}:${src}]`);
         break;
+      }
       default:
         break;
     }

package/src/satori-endpoint-commands.ts

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

package/src/satori-runtime-state.ts

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