@zhin.js/adapter-kook 6.0.5 → 7.0.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @zhin.js/adapter-kook
 
+## 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
+
+- d52f3c5: fix: QQ 适配器群聊误识别为私聊、game-kit 启动崩溃、全面补齐 recallMessage
+
+  - fix(cli): `resolveChannelType` 增加 `metadata.channelKind` 检查，修复 QQ/Discord/KOOK 群聊消息被误分类为私聊
+  - fix(game-kit): `createHostGameDb` 改用延迟代理模型，避免数据库启动前解析模型导致崩溃
+  - feat(qq): 实现 `recallMessage`，解析复合 messageId 路由到对应 SDK 撤回方法；`normalizeQqMessage` 增加 `message_type` 缺失时的回退检测
+  - feat(slack): 实现 `recallMessage`，利用已有 compound ref 和 `chat.delete` API
+  - feat(onebot11): 两个 endpoint 类实现 `recallMessage`（`delete_msg`）
+  - feat(onebot12): 两个 endpoint 类实现 `recallMessage`（`delete_message`）
+  - feat(napcat): 三个 endpoint 类实现 `recallMessage`（`delete_msg`）
+  - feat(discord): 两个 endpoint 类实现 `recallMessage`；`send()` 改为返回 `channelId:snowflake` 复合 ID
+  - feat(telegram): 实现 `recallMessage`（`deleteMessage`）；`send()` 改为返回 `chatId:messageId` 复合 ID
+  - feat(kook): 两个 endpoint 类实现 `recallMessage`，利用 kook-client `recallMsg` API
+  - feat(lark): 实现 `recallMessage`（`DELETE /im/v1/messages/{id}`）
+  - feat(wecom): 实现 `recallMessage`（`POST /cgi-bin/message/recall`）
+
 ## 6.0.5
 
 ### 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/endpoint.d.ts

@@ -24,6 +24,7 @@ export declare class KookWebsocketEndpoint implements EndpointInstance {
     }): Promise<string>;
     /** Test / internal: admit a message when open. */
     admit(msg: KookInboundMessage): void;
+    recallMessage(messageId: string): Promise<void>;
     getRoleList(guildId: string): Promise<{
         role_id: string | number;
         name: string;
@@ -66,6 +67,7 @@ export declare class KookWebhookEndpoint implements EndpointInstance {
     }): Promise<string>;
     /** Test / internal: admit a message when open. */
     admit(msg: KookInboundMessage): void;
+    recallMessage(messageId: string): Promise<void>;
     checkAndRememberSn(sn: number): boolean;
     getRoleList(guildId: string): Promise<{
         role_id: string | number;

package/lib/endpoint.js

@@ -107,6 +107,11 @@ export class KookWebsocketEndpoint {
             }));
         });
     }
+    async recallMessage(messageId) {
+        if (!messageId)
+            return;
+        await this.#requireClient().recallMsg?.(messageId);
+    }
     // ── Agent tool surface ──────────────────────────────────────────────
     async getRoleList(guildId) {
         return this.#requireClient().pickGuild(guildId).getRoleList();
@@ -261,6 +266,11 @@ export class KookWebhookEndpoint {
             }));
         });
     }
+    async recallMessage(messageId) {
+        if (!messageId)
+            return;
+        await this.#requireClient().recallMsg?.(messageId);
+    }
     checkAndRememberSn(sn) {
         if (this.#processedSn.has(sn))
             return false;

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/lib/ws.d.ts

@@ -11,6 +11,7 @@ export interface KookClientTransport {
     sendPrivateMsg(userId: string, message: string): Promise<{
         msg_id?: string | number;
     }>;
+    recallMsg?(messageId: string): Promise<boolean>;
     pickGuild(guildId: string): {
         kick(userId: string): Promise<boolean>;
         getRoleList(): Promise<Array<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-kook",
-  "version": "6.0.5",
+  "version": "7.0.0",
   "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/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.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": {
@@ -65,9 +65,9 @@
     "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",
-    "zhin.js": "5.0.3"
+    "zhin.js": "6.0.0"
   },
   "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/endpoint.ts

@@ -148,6 +148,11 @@ export class KookWebsocketEndpoint implements EndpointInstance {
     });
   }
 
+  async recallMessage(messageId: string): Promise<void> {
+    if (!messageId) return;
+    await this.#requireClient().recallMsg?.(messageId);
+  }
+
   // ── Agent tool surface ──────────────────────────────────────────────
 
   async getRoleList(guildId: string) {
@@ -323,6 +328,11 @@ export class KookWebhookEndpoint implements EndpointInstance {
     });
   }
 
+  async recallMessage(messageId: string): Promise<void> {
+    if (!messageId) return;
+    await this.#requireClient().recallMsg?.(messageId);
+  }
+
   checkAndRememberSn(sn: number): boolean {
     if (this.#processedSn.has(sn)) return false;
     this.#processedSn.add(sn);

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':

package/src/ws.ts

@@ -24,6 +24,7 @@ export interface KookClientTransport {
     userId: string,
     message: string,
   ): Promise<{ msg_id?: string | number }>;
+  recallMsg?(messageId: string): Promise<boolean>;
   pickGuild(guildId: string): {
     kick(userId: string): Promise<boolean>;
     getRoleList(): Promise<Array<{