@zhin.js/adapter-kook 6.0.6 → 7.0.1

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @zhin.js/adapter-kook
 
+## 7.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/agent@1.1.1
+  - @zhin.js/command@1.0.6
+  - @zhin.js/core@1.5.1
+  - zhin.js@6.0.1
+
+## 7.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
+
 ## 6.0.6
 
 ### Patch Changes

package/adapters/kook.js

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

package/adapters/kook.ts

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

package/lib/kook-endpoint-commands.js

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

package/lib/kook-runtime-state.js

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

package/lib/protocol.js

@@ -5,6 +5,9 @@
 import { createDecipheriv, timingSafeEqual } from 'node:crypto';
 import { inflateSync } from 'node:zlib';
 import { pickCredential } from '@zhin.js/adapter';
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('kook');
 export var KookPermission;
 (function (KookPermission) {
     KookPermission[KookPermission["Normal"] = 1] = "Normal";
@@ -95,6 +98,32 @@ export function isKookBotMentioned(msg, selfId) {
     const marker = `(met)${selfId}(met)`;
     return (msg.content || '').includes(marker) || (msg.rawMessage || '').includes(marker);
 }
+/**
+ * 解析 image/audio/video/file 段的投递 URL（canonical MediaRef 唯一来源）。
+ * KOOK KMarkdown 媒体只能消费远程 URL；base64 / path / file 引用无法经
+ * KMarkdown 投递，warn 后丢弃（返回 undefined）。
+ */
+function resolveOutboundMediaUrl(seg) {
+    const media = (seg.data ?? {}).media;
+    if (!isMediaRef(media)) {
+        logger.warn(formatCompact({
+            op: 'kook_outbound_media_dropped',
+            type: seg.type,
+            reason: 'missing_media_ref',
+        }));
+        return undefined;
+    }
+    if (media.kind !== 'url') {
+        logger.warn(formatCompact({
+            op: 'kook_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 KOOK KMarkdown.
  * Segment canonicalization is intentionally not done here.
@@ -126,18 +155,26 @@ export function formatOutboundKmarkdown(payload) {
                 const id = String(data.user_id ?? data.qq ?? data.id ?? '');
                 return id === 'all' ? '(met)all(met)' : `(met)${id}(met)`;
             }
-            case 'image':
-                return `![${String(data.alt || '图片')}](${String(data.url || data.file || '')})`;
+            case 'image': {
+                const url = resolveOutboundMediaUrl(item);
+                return url ? `![${String(data.alt || '图片')}](${url})` : '';
+            }
             case 'face':
                 return `(emj)${String(data.name || 'emoji')}(emj)[${String(data.id ?? '')}]`;
             case 'link':
                 return `[${String(data.text || data.url || '')}](${String(data.url || '')})`;
-            case 'video':
-                return `[视频](${String(data.url || data.file || '')})`;
-            case 'audio':
-                return `[音频](${String(data.url || data.file || '')})`;
-            case 'file':
-                return `[文件: ${String(data.name || '未命名')}](${String(data.url || data.file || '')})`;
+            case 'video': {
+                const url = resolveOutboundMediaUrl(item);
+                return url ? `[视频](${url})` : '';
+            }
+            case 'audio': {
+                const url = resolveOutboundMediaUrl(item);
+                return url ? `[音频](${url})` : '';
+            }
+            case 'file': {
+                const url = resolveOutboundMediaUrl(item);
+                return url ? `[文件: ${String(data.name || '未命名')}](${url})` : '';
+            }
             case 'bold':
                 return `**${String(data.text ?? '')}**`;
             case 'italic':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-kook",
-  "version": "6.0.6",
+  "version": "7.0.1",
   "description": "Zhin.js KOOK adapter for Plugin Runtime (WebSocket gateway or Webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,20 +34,20 @@
   },
   "dependencies": {
     "kook-client": "^1.0.4",
-    "@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"
   },
   "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/plugin-runtime": "1.1.1",
-    "zhin.js": "5.0.3"
+    "@zhin.js/adapter": "1.1.4",
+    "@zhin.js/agent": "1.1.1",
+    "@zhin.js/core": "1.5.1",
+    "@zhin.js/plugin-runtime": "1.1.2",
+    "zhin.js": "6.0.1"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -65,9 +65,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.10",
-    "@zhin.js/host-http": "1.0.4",
-    "zhin.js": "5.0.3"
+    "@zhin.js/agent": "1.1.1",
+    "@zhin.js/host-http": "1.0.5",
+    "zhin.js": "6.0.1"
   },
   "files": [
     "adapters",

package/plugin.js

@@ -9,7 +9,7 @@ export default definePlugin({
         displayName: 'KOOK WebSocket Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表（kook endpoint list 的"运行中"数据源）
+        // 运行中 endpoint 注册表（kook.endpoint list 的"运行中"数据源）
         context.resources.provide(kookRuntimeStateToken, createEndpointRuntimeState());
         // 平台权限门禁：guild_owner / guild_admin / channel_admin 等（agent 工具 platformPermit）
         return registerKookPlatformPermitChecker();

package/src/kook-endpoint-commands.ts

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

package/src/kook-runtime-state.ts

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

package/src/protocol.ts

@@ -7,6 +7,10 @@ import { createDecipheriv, timingSafeEqual } from 'node:crypto';
 import { inflateSync } from 'node:zlib';
 import type { IncomingMessage } from 'node:http';
 import { pickCredential } from '@zhin.js/adapter';
+import { isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+
+const logger = getLogger('kook');
 
 export type LogLevel =
   | 'trace'
@@ -228,6 +232,33 @@ export function isKookBotMentioned(msg: KookInboundMessage, selfId?: string): bo
   return (msg.content || '').includes(marker) || (msg.rawMessage || '').includes(marker);
 }
 
+/**
+ * 解析 image/audio/video/file 段的投递 URL（canonical MediaRef 唯一来源）。
+ * KOOK KMarkdown 媒体只能消费远程 URL；base64 / path / file 引用无法经
+ * KMarkdown 投递，warn 后丢弃（返回 undefined）。
+ */
+function resolveOutboundMediaUrl(seg: KookWireSegment): string | undefined {
+  const media = (seg.data ?? {}).media;
+  if (!isMediaRef(media)) {
+    logger.warn(formatCompact({
+      op: 'kook_outbound_media_dropped',
+      type: seg.type,
+      reason: 'missing_media_ref',
+    }));
+    return undefined;
+  }
+  if (media.kind !== 'url') {
+    logger.warn(formatCompact({
+      op: 'kook_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 KOOK KMarkdown.
  * Segment canonicalization is intentionally not done here.
@@ -260,18 +291,26 @@ export function formatOutboundKmarkdown(payload: unknown): string {
           const id = String(data.user_id ?? data.qq ?? data.id ?? '');
           return id === 'all' ? '(met)all(met)' : `(met)${id}(met)`;
         }
-        case 'image':
-          return `![${String(data.alt || '图片')}](${String(data.url || data.file || '')})`;
+        case 'image': {
+          const url = resolveOutboundMediaUrl(item);
+          return url ? `![${String(data.alt || '图片')}](${url})` : '';
+        }
         case 'face':
           return `(emj)${String(data.name || 'emoji')}(emj)[${String(data.id ?? '')}]`;
         case 'link':
           return `[${String(data.text || data.url || '')}](${String(data.url || '')})`;
-        case 'video':
-          return `[视频](${String(data.url || data.file || '')})`;
-        case 'audio':
-          return `[音频](${String(data.url || data.file || '')})`;
-        case 'file':
-          return `[文件: ${String(data.name || '未命名')}](${String(data.url || data.file || '')})`;
+        case 'video': {
+          const url = resolveOutboundMediaUrl(item);
+          return url ? `[视频](${url})` : '';
+        }
+        case 'audio': {
+          const url = resolveOutboundMediaUrl(item);
+          return url ? `[音频](${url})` : '';
+        }
+        case 'file': {
+          const url = resolveOutboundMediaUrl(item);
+          return url ? `[文件: ${String(data.name || '未命名')}](${url})` : '';
+        }
         case 'bold':
           return `**${String(data.text ?? '')}**`;
         case 'italic':