@zhin.js/adapter-line 3.0.4 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @zhin.js/adapter-line
 
+## 4.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
+
+## 3.0.5
+
+### Patch Changes
+
+- Updated dependencies [d8bf702]
+  - @zhin.js/host-http@1.0.4
+  - @zhin.js/agent@1.0.10
+  - @zhin.js/core@1.4.3
+  - zhin.js@5.0.3
+
 ## 3.0.4
 
 ### Patch Changes

package/adapters/line.js

@@ -18,7 +18,7 @@ export default defineAdapter({
     },
     create(context) {
         const config = resolveLineConfig(context.config);
-        // 注册到插件运行时状态（line endpoint list 的"运行中"数据源）
+        // 注册到插件运行时状态（line.endpoint list 的"运行中"数据源）
         context.use(lineRuntimeStateToken).endpoints.set(config.name, {
             name: config.name,
             mode: 'webhook',

package/adapters/line.ts

@@ -23,7 +23,7 @@ export default defineAdapter<LineAdapterConfig>({
   },
   create(context) {
     const config = resolveLineConfig(context.config);
-    // 注册到插件运行时状态（line endpoint list 的"运行中"数据源）
+    // 注册到插件运行时状态（line.endpoint list 的"运行中"数据源）
     context.use(lineRuntimeStateToken).endpoints.set(config.name, {
       name: config.name,
       mode: 'webhook',

package/lib/line-endpoint-commands.js

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

package/lib/line-runtime-state.js

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

package/lib/protocol.js

@@ -3,6 +3,9 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import { createHmac, timingSafeEqual } from 'node:crypto';
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('line');
 export function resolveLineConfig(config = {}) {
     const entry = config.endpoints?.find((item) => item.context === 'line');
     const channelSecret = config.channelSecret
@@ -108,6 +111,32 @@ function buildTextMessage(text) {
     const truncated = text.length > 5000 ? `${text.slice(0, 4997)}...` : text;
     return { type: 'text', text: truncated };
 }
+/**
+ * 解析 image/audio/video 段的投递源（canonical MediaRef 唯一来源）。
+ * LINE Messaging API 媒体消息仅消费远程 HTTPS URL（无上传通道），
+ * 因此只有 kind=url 可投递；base64 / path / file 一律 warn + 丢弃。
+ */
+function resolveMediaUrl(seg) {
+    const media = (seg.data ?? {}).media;
+    if (!isMediaRef(media)) {
+        logger.warn(formatCompact({
+            op: 'line_outbound_media_dropped',
+            type: seg.type,
+            reason: 'missing_media_ref',
+        }));
+        return undefined;
+    }
+    if (media.kind !== 'url') {
+        logger.warn(formatCompact({
+            op: 'line_outbound_media_dropped',
+            type: seg.type,
+            reason: 'unsupported_media_kind',
+            kind: media.kind,
+        }));
+        return undefined;
+    }
+    return media.value;
+}
 /**
  * Wire-encode an already-rendered outbound payload into LINE Reply/Push messages.
  * Segment canonicalization is intentionally not done here.
@@ -145,33 +174,39 @@ export function formatOutboundMessages(payload) {
                     messages.push(buildTextMessage(`@${String(data.name || data.id)}`));
                 }
                 break;
-            case 'image':
-                if (typeof data.url === 'string' && data.url) {
+            case 'image': {
+                const url = resolveMediaUrl(item);
+                if (url) {
                     messages.push({
                         type: 'image',
-                        originalContentUrl: data.url,
-                        previewImageUrl: data.url,
+                        originalContentUrl: url,
+                        previewImageUrl: url,
                     });
                 }
                 break;
-            case 'video':
-                if (typeof data.url === 'string' && data.url) {
+            }
+            case 'video': {
+                const url = resolveMediaUrl(item);
+                if (url) {
                     messages.push({
                         type: 'video',
-                        originalContentUrl: data.url,
-                        previewImageUrl: typeof data.previewUrl === 'string' ? data.previewUrl : data.url,
+                        originalContentUrl: url,
+                        previewImageUrl: typeof data.previewUrl === 'string' ? data.previewUrl : url,
                     });
                 }
                 break;
-            case 'audio':
-                if (typeof data.url === 'string' && data.url) {
+            }
+            case 'audio': {
+                const url = resolveMediaUrl(item);
+                if (url) {
                     messages.push({
                         type: 'audio',
-                        originalContentUrl: data.url,
+                        originalContentUrl: url,
                         duration: typeof data.duration === 'number' ? data.duration : 0,
                     });
                 }
                 break;
+            }
             case 'location':
                 messages.push({
                     type: 'location',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-line",
-  "version": "3.0.4",
+  "version": "4.0.0",
   "description": "Zhin.js LINE Messaging API adapter for Plugin Runtime (HTTP webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -32,21 +32,21 @@
     "directory": "plugins/adapters/line"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/command": "1.0.4",
-    "@zhin.js/core": "1.4.3",
-    "@zhin.js/host-http": "1.0.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.9",
-    "@zhin.js/core": "1.4.3",
-    "@zhin.js/host-http": "1.0.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": {
@@ -60,11 +60,11 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^26.1.0",
+    "@types/node": "^26.1.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.9"
+    "@zhin.js/agent": "1.1.0"
   },
   "files": [
     "adapters",

package/plugin.js

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

package/src/line-endpoint-commands.ts

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

package/src/line-runtime-state.ts

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

package/src/protocol.ts

@@ -5,6 +5,10 @@
 
 import { createHmac, 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('line');
 
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface LineAdapterConfig {
@@ -272,6 +276,33 @@ function buildTextMessage(text: string): LineReplyMessage {
   return { type: 'text', text: truncated };
 }
 
+/**
+ * 解析 image/audio/video 段的投递源（canonical MediaRef 唯一来源）。
+ * LINE Messaging API 媒体消息仅消费远程 HTTPS URL（无上传通道），
+ * 因此只有 kind=url 可投递；base64 / path / file 一律 warn + 丢弃。
+ */
+function resolveMediaUrl(seg: LineWireSegment): string | undefined {
+  const media = (seg.data ?? {}).media;
+  if (!isMediaRef(media)) {
+    logger.warn(formatCompact({
+      op: 'line_outbound_media_dropped',
+      type: seg.type,
+      reason: 'missing_media_ref',
+    }));
+    return undefined;
+  }
+  if (media.kind !== 'url') {
+    logger.warn(formatCompact({
+      op: 'line_outbound_media_dropped',
+      type: seg.type,
+      reason: 'unsupported_media_kind',
+      kind: media.kind,
+    }));
+    return undefined;
+  }
+  return media.value;
+}
+
 /**
  * Wire-encode an already-rendered outbound payload into LINE Reply/Push messages.
  * Segment canonicalization is intentionally not done here.
@@ -312,33 +343,39 @@ export function formatOutboundMessages(payload: unknown): LineReplyMessage[] {
           messages.push(buildTextMessage(`@${String(data.name || data.id)}`));
         }
         break;
-      case 'image':
-        if (typeof data.url === 'string' && data.url) {
+      case 'image': {
+        const url = resolveMediaUrl(item);
+        if (url) {
           messages.push({
             type: 'image',
-            originalContentUrl: data.url,
-            previewImageUrl: data.url,
+            originalContentUrl: url,
+            previewImageUrl: url,
           });
         }
         break;
-      case 'video':
-        if (typeof data.url === 'string' && data.url) {
+      }
+      case 'video': {
+        const url = resolveMediaUrl(item);
+        if (url) {
           messages.push({
             type: 'video',
-            originalContentUrl: data.url,
-            previewImageUrl: typeof data.previewUrl === 'string' ? data.previewUrl : data.url,
+            originalContentUrl: url,
+            previewImageUrl: typeof data.previewUrl === 'string' ? data.previewUrl : url,
           });
         }
         break;
-      case 'audio':
-        if (typeof data.url === 'string' && data.url) {
+      }
+      case 'audio': {
+        const url = resolveMediaUrl(item);
+        if (url) {
           messages.push({
             type: 'audio',
-            originalContentUrl: data.url,
+            originalContentUrl: url,
             duration: typeof data.duration === 'number' ? data.duration : 0,
           });
         }
         break;
+      }
       case 'location':
         messages.push({
           type: 'location',