@zhin.js/adapter-kook 7.0.2 → 7.0.3

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @zhin.js/adapter-kook
 
+## 7.0.3
+
+### Patch Changes
+
+- Updated dependencies [afc0e66]
+- Updated dependencies [2e41ad5]
+- Updated dependencies [9f57124]
+  - @zhin.js/core@1.5.2
+  - @zhin.js/adapter@1.1.5
+  - @zhin.js/im-contract@1.0.1
+  - @zhin.js/plugin-runtime@1.1.3
+  - @zhin.js/command@1.0.7
+  - @zhin.js/host-http@1.0.6
+  - @zhin.js/agent@1.1.3
+  - zhin.js@6.0.2
+
 ## 7.0.2
 
 ### Patch Changes

package/README.md

@@ -7,7 +7,7 @@ Zhin.js KOOK（开黑啦）适配器（Plugin Runtime），默认通过 **WebSoc
 - WebSocket Gateway 入站（默认；无需公网 HTTPS / host）
 - Webhook 入站（`connection: webhook` + `httpHostToken` + `verify_token`）
 - 解析频道与私聊文本消息
-- 出站 `send({ target, payload })` → KOOK KMarkdown（`channel:id` / `private:id`）
+- 出站 `send({ conversation, payload })` → KOOK KMarkdown（`kind: 'channel' | 'private'`）
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 
 ## 安装
@@ -25,8 +25,8 @@ pnpm add @zhin.js/adapter-kook
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 - **WebSocket 路径无需** `@zhin.js/host-http` / `@zhin.js/host-router`
 
-入站：`gateway.receive({ adapter, target: 'channel:…'|'private:…', content, sender, metadata })`  
-出站：`send({ target, payload })` → `sendChannelMsg` / `sendPrivateMsg`
+入站：`gateway.receive({ conversation, message, content, sender, metadata })`（ConversationRef：`channel` 频道消息带 guild `parent`，`private` 私聊）  
+出站：`send({ conversation, payload })` → `sendChannelMsg` / `sendPrivateMsg`
 
 ## 前置条件
 

package/lib/endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement, EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
@@ -18,10 +18,7 @@ export declare class KookWebsocketEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     /** Test / internal: admit a message when open. */
     admit(msg: KookInboundMessage): void;
     recallMessage(messageId: string): Promise<void>;
@@ -61,10 +58,7 @@ export declare class KookWebhookEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     /** Test / internal: admit a message when open. */
     admit(msg: KookInboundMessage): void;
     recallMessage(messageId: string): Promise<void>;

package/lib/endpoint.js

@@ -1,6 +1,6 @@
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { registerKookAgentEndpoint } from './kook-agent-deps.js';
-import { formatInboundContent, formatInboundTarget, formatOutboundKmarkdown, isKookBotMentioned, parseSendTarget, senderDisplayName, } from './protocol.js';
+import { formatInboundContent, formatOutboundKmarkdown, isKookBotMentioned, kookInboundConversation, senderDisplayName, } from './protocol.js';
 import { registerKookWebhookRoutes } from './webhook.js';
 import { defaultCreateClient, defaultCreateWebhookClient, normalizeKookMessage, } from './ws.js';
 const logger = getLogger('kook');
@@ -61,18 +61,17 @@ export class KookWebsocketEndpoint {
         this.#started = false;
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         const body = formatOutboundKmarkdown(payload);
-        const parsed = parseSendTarget(target);
         const client = this.#requireClient();
-        const result = parsed.kind === 'private'
-            ? await client.sendPrivateMsg(parsed.id, body)
-            : await client.sendChannelMsg(parsed.id, body);
+        const result = conversation.kind === 'private'
+            ? await client.sendPrivateMsg(conversation.id, body)
+            : await client.sendChannelMsg(conversation.id, body);
         const messageId = result?.msg_id != null ? String(result.msg_id) : '';
         logger.debug(formatCompact({
             op: 'kook_send',
             endpoint: this.#options.config.name,
-            target,
+            target: `${conversation.kind}:${conversation.id}`,
             messageId,
         }));
         return messageId;
@@ -83,14 +82,13 @@ export class KookWebsocketEndpoint {
             return;
         if (msg.authorBot)
             return;
-        const target = formatInboundTarget(msg);
+        const conversation = kookInboundConversation(String(this.#options.id), msg);
         const selfId = this.#client?.self_id != null ? String(this.#client.self_id) : undefined;
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target,
+            conversation,
+            message: { conversation, id: msg.id },
             content: formatInboundContent(msg),
             sender: senderDisplayName(msg),
-            id: msg.id,
             metadata: Object.freeze({
                 endpoint: this.#options.config.name,
                 channelKind: msg.channelKind,
@@ -102,7 +100,7 @@ export class KookWebsocketEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'kook_gateway_receive_failed',
-                target,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
@@ -220,18 +218,17 @@ export class KookWebhookEndpoint {
         this.#started = false;
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         const body = formatOutboundKmarkdown(payload);
-        const parsed = parseSendTarget(target);
         const client = this.#requireClient();
-        const result = parsed.kind === 'private'
-            ? await client.sendPrivateMsg(parsed.id, body)
-            : await client.sendChannelMsg(parsed.id, body);
+        const result = conversation.kind === 'private'
+            ? await client.sendPrivateMsg(conversation.id, body)
+            : await client.sendChannelMsg(conversation.id, body);
         const messageId = result?.msg_id != null ? String(result.msg_id) : '';
         logger.debug(formatCompact({
             op: 'kook_send',
             endpoint: this.#options.config.name,
-            target,
+            target: `${conversation.kind}:${conversation.id}`,
             messageId,
         }));
         return messageId;
@@ -242,14 +239,13 @@ export class KookWebhookEndpoint {
             return;
         if (msg.authorBot)
             return;
-        const target = formatInboundTarget(msg);
+        const conversation = kookInboundConversation(String(this.#options.id), msg);
         const selfId = this.#client?.self_id != null ? String(this.#client.self_id) : undefined;
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target,
+            conversation,
+            message: { conversation, id: msg.id },
             content: formatInboundContent(msg),
             sender: senderDisplayName(msg),
-            id: msg.id,
             metadata: Object.freeze({
                 endpoint: this.#options.config.name,
                 channelKind: msg.channelKind,
@@ -261,7 +257,7 @@ export class KookWebhookEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'kook_gateway_receive_failed',
-                target,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export { formatInboundContent, formatInboundTarget, formatOutboundKmarkdown, parseSendTarget, resolveKookConfig, senderDisplayName, KookPermission, type KookAdapterConfig, type KookInboundMessage, type KookWireSegment, type LogLevel, type ParsedSendTarget, type ResolvedKookConfig, type ResolvedKookWebhookConfig, type ResolvedKookWebsocketConfig, } from './protocol.js';
+export { formatInboundContent, formatOutboundKmarkdown, resolveKookConfig, senderDisplayName, KookPermission, type KookAdapterConfig, type KookInboundMessage, type KookWireSegment, type LogLevel, type ResolvedKookConfig, type ResolvedKookWebhookConfig, type ResolvedKookWebsocketConfig, } from './protocol.js';
 export { KookWebhookEndpoint, KookWebsocketEndpoint, type KookEndpointOptions, type KookWebhookEndpointOptions, } from './endpoint.js';
 export { registerKookWebhookRoutes, handleKookWebhookRequest, type KookWebhookHandler, } from './webhook.js';
 export { defaultCreateClient, defaultCreateWebhookClient, normalizeKookMessage, type CreateKookClient, type KookClientTransport, } from './ws.js';

package/lib/index.js

@@ -1,4 +1,4 @@
-export { formatInboundContent, formatInboundTarget, formatOutboundKmarkdown, parseSendTarget, resolveKookConfig, senderDisplayName, KookPermission, } from './protocol.js';
+export { formatInboundContent, formatOutboundKmarkdown, resolveKookConfig, senderDisplayName, KookPermission, } from './protocol.js';
 export { KookWebhookEndpoint, KookWebsocketEndpoint, } from './endpoint.js';
 export { registerKookWebhookRoutes, handleKookWebhookRequest, } from './webhook.js';
 export { defaultCreateClient, defaultCreateWebhookClient, normalizeKookMessage, } from './ws.js';

package/lib/protocol.d.ts

@@ -3,6 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import type { IncomingMessage } from 'node:http';
+import type { ConversationRef } from '@zhin.js/im-contract';
 export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'mark' | 'off';
 export declare enum KookPermission {
     Normal = 1,
@@ -106,16 +107,12 @@ export interface KookWireSegment {
     readonly type: string;
     readonly data?: Record<string, unknown>;
 }
-export interface ParsedSendTarget {
-    readonly kind: 'private' | 'channel';
-    readonly id: string;
-}
 export declare function resolveKookConfig(config?: KookAdapterConfig): ResolvedKookConfig;
 /**
- * Gateway reply target：`private:uid` / `channel:cid`，便于 send() 还原 API。
+ * 入站归一化 → ConversationRef：频道消息的所属 guild 进 `parent`（guild 容器
+ * 映射为 channel 容器）；私聊（PERSON）无容器，直接 kind 'private'。
  */
-export declare function formatInboundTarget(msg: KookInboundMessage): string;
-export declare function parseSendTarget(target: string): ParsedSendTarget;
+export declare function kookInboundConversation(endpointId: string, msg: KookInboundMessage): ConversationRef;
 export declare function senderDisplayName(msg: KookInboundMessage): string;
 /** Build inbound text for MessageGateway.receive */
 export declare function formatInboundContent(msg: KookInboundMessage): string;

package/lib/protocol.js

@@ -62,23 +62,18 @@ export function resolveKookConfig(config = {}) {
     };
 }
 /**
- * Gateway reply target：`private:uid` / `channel:cid`，便于 send() 还原 API。
+ * 入站归一化 → ConversationRef：频道消息的所属 guild 进 `parent`（guild 容器
+ * 映射为 channel 容器）；私聊（PERSON）无容器，直接 kind 'private'。
  */
-export function formatInboundTarget(msg) {
-    return `${msg.channelKind}:${msg.channelId}`;
-}
-export function parseSendTarget(target) {
-    const sep = target.indexOf(':');
-    if (sep <= 0) {
-        return { kind: 'channel', id: target };
-    }
-    const head = target.slice(0, sep);
-    const rest = target.slice(sep + 1);
-    if (head === 'private')
-        return { kind: 'private', id: rest };
-    if (head === 'channel' || head === 'group')
-        return { kind: 'channel', id: rest };
-    return { kind: 'channel', id: target };
+export function kookInboundConversation(endpointId, msg) {
+    return {
+        endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+        kind: msg.channelKind,
+        id: msg.channelId,
+        ...(msg.guildId && msg.channelKind === 'channel'
+            ? { parent: { kind: 'channel', id: msg.guildId } }
+            : {}),
+    };
 }
 export function senderDisplayName(msg) {
     return msg.authorName || msg.authorId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-kook",
-  "version": "7.0.2",
+  "version": "7.0.3",
   "description": "Zhin.js KOOK adapter for Plugin Runtime (WebSocket gateway or Webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,20 +34,21 @@
   },
   "dependencies": {
     "kook-client": "^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/adapter": "1.1.5",
+    "@zhin.js/command": "1.0.7",
+    "@zhin.js/core": "1.5.2",
+    "@zhin.js/host-http": "1.0.6",
+    "@zhin.js/im-contract": "1.0.1",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.2"
+    "@zhin.js/plugin-runtime": "1.1.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/agent": "1.1.2",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/plugin-runtime": "1.1.2",
-    "zhin.js": "6.0.1"
+    "@zhin.js/adapter": "1.1.5",
+    "@zhin.js/agent": "1.1.3",
+    "@zhin.js/core": "1.5.2",
+    "@zhin.js/plugin-runtime": "1.1.3",
+    "zhin.js": "6.0.2"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -65,9 +66,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.2",
-    "@zhin.js/host-http": "1.0.5",
-    "zhin.js": "6.0.1"
+    "@zhin.js/agent": "1.1.3",
+    "@zhin.js/host-http": "1.0.6",
+    "zhin.js": "6.0.2"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -7,6 +7,7 @@ import type {
   EndpointGroup,
   EndpointInstance,
   EndpointManagement,
+  EndpointSendRequest,
 } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
@@ -15,10 +16,9 @@ import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { registerKookAgentEndpoint } from './kook-agent-deps.js';
 import {
   formatInboundContent,
-  formatInboundTarget,
   formatOutboundKmarkdown,
   isKookBotMentioned,
-  parseSendTarget,
+  kookInboundConversation,
   senderDisplayName,
   type KookInboundMessage,
   type ResolvedKookWebhookConfig,
@@ -102,18 +102,17 @@ export class KookWebsocketEndpoint implements EndpointInstance {
     logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const body = formatOutboundKmarkdown(payload);
-    const parsed = parseSendTarget(target);
     const client = this.#requireClient();
-    const result = parsed.kind === 'private'
-      ? await client.sendPrivateMsg(parsed.id, body)
-      : await client.sendChannelMsg(parsed.id, body);
+    const result = conversation.kind === 'private'
+      ? await client.sendPrivateMsg(conversation.id, body)
+      : await client.sendChannelMsg(conversation.id, body);
     const messageId = result?.msg_id != null ? String(result.msg_id) : '';
     logger.debug(formatCompact({
       op: 'kook_send',
       endpoint: this.#options.config.name,
-      target,
+      target: `${conversation.kind}:${conversation.id}`,
       messageId,
     }));
     return messageId;
@@ -123,14 +122,13 @@ export class KookWebsocketEndpoint implements EndpointInstance {
   admit(msg: KookInboundMessage): void {
     if (!this.#open) return;
     if (msg.authorBot) return;
-    const target = formatInboundTarget(msg);
+    const conversation = kookInboundConversation(String(this.#options.id), msg);
     const selfId = this.#client?.self_id != null ? String(this.#client.self_id) : undefined;
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target,
+      conversation,
+      message: { conversation, id: msg.id },
       content: formatInboundContent(msg),
       sender: senderDisplayName(msg),
-      id: msg.id,
       metadata: Object.freeze({
         endpoint: this.#options.config.name,
         channelKind: msg.channelKind,
@@ -142,7 +140,7 @@ export class KookWebsocketEndpoint implements EndpointInstance {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'kook_gateway_receive_failed',
-        target,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });
@@ -282,18 +280,17 @@ export class KookWebhookEndpoint implements EndpointInstance {
     logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const body = formatOutboundKmarkdown(payload);
-    const parsed = parseSendTarget(target);
     const client = this.#requireClient();
-    const result = parsed.kind === 'private'
-      ? await client.sendPrivateMsg(parsed.id, body)
-      : await client.sendChannelMsg(parsed.id, body);
+    const result = conversation.kind === 'private'
+      ? await client.sendPrivateMsg(conversation.id, body)
+      : await client.sendChannelMsg(conversation.id, body);
     const messageId = result?.msg_id != null ? String(result.msg_id) : '';
     logger.debug(formatCompact({
       op: 'kook_send',
       endpoint: this.#options.config.name,
-      target,
+      target: `${conversation.kind}:${conversation.id}`,
       messageId,
     }));
     return messageId;
@@ -303,14 +300,13 @@ export class KookWebhookEndpoint implements EndpointInstance {
   admit(msg: KookInboundMessage): void {
     if (!this.#open) return;
     if (msg.authorBot) return;
-    const target = formatInboundTarget(msg);
+    const conversation = kookInboundConversation(String(this.#options.id), msg);
     const selfId = this.#client?.self_id != null ? String(this.#client.self_id) : undefined;
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target,
+      conversation,
+      message: { conversation, id: msg.id },
       content: formatInboundContent(msg),
       sender: senderDisplayName(msg),
-      id: msg.id,
       metadata: Object.freeze({
         endpoint: this.#options.config.name,
         channelKind: msg.channelKind,
@@ -322,7 +318,7 @@ export class KookWebhookEndpoint implements EndpointInstance {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'kook_gateway_receive_failed',
-        target,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });

package/src/index.ts

@@ -1,8 +1,6 @@
 export {
   formatInboundContent,
-  formatInboundTarget,
   formatOutboundKmarkdown,
-  parseSendTarget,
   resolveKookConfig,
   senderDisplayName,
   KookPermission,
@@ -10,7 +8,6 @@ export {
   type KookInboundMessage,
   type KookWireSegment,
   type LogLevel,
-  type ParsedSendTarget,
   type ResolvedKookConfig,
   type ResolvedKookWebhookConfig,
   type ResolvedKookWebsocketConfig,

package/src/protocol.ts

@@ -8,6 +8,7 @@ import { inflateSync } from 'node:zlib';
 import type { IncomingMessage } from 'node:http';
 import { pickCredential } from '@zhin.js/adapter';
 import { isMediaRef } from '@zhin.js/core';
+import type { ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('kook');
@@ -133,11 +134,6 @@ export interface KookWireSegment {
   readonly data?: Record<string, unknown>;
 }
 
-export interface ParsedSendTarget {
-  readonly kind: 'private' | 'channel';
-  readonly id: string;
-}
-
 export function resolveKookConfig(config: KookAdapterConfig = {}): ResolvedKookConfig {
   const entry = config.endpoints?.find((item) => item.context === 'kook' || !item.context);
   const token = pickCredential(config.token, entry?.token, process.env.KOOK_TOKEN, process.env.KOOK_BOT_TOKEN);
@@ -194,22 +190,18 @@ export function resolveKookConfig(config: KookAdapterConfig = {}): ResolvedKookC
 }
 
 /**
- * Gateway reply target：`private:uid` / `channel:cid`，便于 send() 还原 API。
+ * 入站归一化 → ConversationRef：频道消息的所属 guild 进 `parent`（guild 容器
+ * 映射为 channel 容器）；私聊（PERSON）无容器，直接 kind 'private'。
  */
-export function formatInboundTarget(msg: KookInboundMessage): string {
-  return `${msg.channelKind}:${msg.channelId}`;
-}
-
-export function parseSendTarget(target: string): ParsedSendTarget {
-  const sep = target.indexOf(':');
-  if (sep <= 0) {
-    return { kind: 'channel', id: target };
-  }
-  const head = target.slice(0, sep);
-  const rest = target.slice(sep + 1);
-  if (head === 'private') return { kind: 'private', id: rest };
-  if (head === 'channel' || head === 'group') return { kind: 'channel', id: rest };
-  return { kind: 'channel', id: target };
+export function kookInboundConversation(endpointId: string, msg: KookInboundMessage): ConversationRef {
+  return {
+    endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+    kind: msg.channelKind,
+    id: msg.channelId,
+    ...(msg.guildId && msg.channelKind === 'channel'
+      ? { parent: { kind: 'channel' as const, id: msg.guildId } }
+      : {}),
+  };
 }
 
 export function senderDisplayName(msg: KookInboundMessage): string {