@zhin.js/adapter-discord 7.0.1 → 7.0.3

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @zhin.js/adapter-discord
 
+## 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
+
+- Updated dependencies [696ab1b]
+  - @zhin.js/agent@1.1.2
+  - zhin.js@6.0.1
+
 ## 7.0.1
 
 ### Patch Changes

package/README.md

@@ -7,7 +7,7 @@ Zhin.js Discord 适配器（Plugin Runtime），默认通过 **Gateway WebSocket
 - Gateway WebSocket 入站（默认；无需公网 HTTPS / host）
 - 解析 text / mention / attachment / embed / sticker / button
 - 支持私聊、群组与服务器频道
-- 出站 `send({ target, payload })` → Discord channel message（text / media / embed / keyboard）
+- 出站 `send({ conversation, payload })` → Discord channel message（text / media / embed / keyboard）
 - 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 - Interactions HTTP webhook 延期（需 `httpHostToken`）；配置 `connection: interactions` 会明确报错
 
@@ -25,8 +25,8 @@ pnpm add @zhin.js/adapter-discord discord.js
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 - **无需** `@zhin.js/host-http` / `@zhin.js/host-router`（Gateway 路径）
 
-入站：`gateway.receive({ adapter, target: channelId, content: text, sender, metadata })`  
-出站：`send({ target, payload })` → discord.js channel.send
+入站：`gateway.receive({ conversation, message, content: text, sender, metadata })`（`conversation` 为 `ConversationRef`，guild 频道带 `parent` guild 容器）  
+出站：`send({ conversation, payload })` → discord.js channel.send
 
 ### 平台权限（platform permit）
 

package/lib/endpoint.d.ts

@@ -20,7 +20,7 @@ export declare class DiscordGatewayEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, conversation, payload }: EndpointSendRequest): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     recallMessage(messageId: string): Promise<void>;
     /** Test / internal: admit a message when open. */
     admit(msg: DiscordInboundMessage): void;
@@ -64,7 +64,7 @@ export declare class DiscordInteractionsEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, conversation, payload }: EndpointSendRequest): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     recallMessage(messageId: string): Promise<void>;
     admit(msg: DiscordInboundMessage): void;
 }

package/lib/endpoint.js

@@ -2,11 +2,11 @@
  * DiscordEndpoint — lifecycle, outbound, admit, gateway / interactions modes, agent tool surface.
  */
 import { ChannelType } from 'discord.js';
-import { formatLegacyMessageReference, nativeConversationId, parseLegacyMessageReference, } from '@zhin.js/im-contract';
+import { formatLegacyConversationRef, formatLegacyMessageReference, nativeConversationId, parseLegacyMessageReference, } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { registerDiscordAgentEndpoint } from './discord-agent-deps.js';
 import { connectDiscordGatewayClient, defaultCreateClient, DEFAULT_INTENTS, resolveSenderRole, toMessageCreateOptions, } from './gateway.js';
-import { formatButtonContent, formatButtonSegments, formatInboundContent, formatInboundSegments, formatOutboundBody, senderDisplayName, } from './protocol.js';
+import { discordInboundConversation, formatButtonContent, formatButtonSegments, formatInboundContent, formatInboundSegments, formatOutboundBody, senderDisplayName, } from './protocol.js';
 import { registerDiscordInteractionRoutes } from './webhook.js';
 const DISCORD_API = 'https://discord.com/api/v10';
 /** 出站 HTTP 调用统一 30s 超时。 */
@@ -90,10 +90,11 @@ export class DiscordGatewayEndpoint {
         this.#started = false;
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
-    async send({ target, conversation, payload }) {
+    async send({ conversation, payload }) {
         const body = formatOutboundBody(payload);
-        const channelId = nativeConversationId(target, conversation);
-        const snowflake = await this.#sendBody(channelId, body);
+        // recall 链路仍是本端点编码的 legacy 引用，在边界内部从 conversation 派生 target
+        const target = formatLegacyConversationRef(conversation);
+        const snowflake = await this.#sendBody(conversation.id, body);
         const messageId = formatLegacyMessageReference({ target, messageId: snowflake });
         logger.debug(formatCompact({
             op: 'discord_send',
@@ -123,13 +124,13 @@ export class DiscordGatewayEndpoint {
             return;
         if (msg.authorBot)
             return;
+        const conversation = discordInboundConversation(String(this.#options.id), msg);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target: msg.channelId,
+            conversation,
+            message: { conversation, id: msg.id },
             content: formatInboundContent(msg),
             segments: formatInboundSegments(msg),
             sender: senderDisplayName(msg),
-            id: msg.id,
             metadata: Object.freeze({
                 endpoint: this.#options.config.name,
                 channelKind: msg.channelKind,
@@ -142,7 +143,7 @@ export class DiscordGatewayEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'discord_gateway_receive_failed',
-                target: msg.channelId,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
@@ -151,13 +152,13 @@ export class DiscordGatewayEndpoint {
     admitButton(interaction) {
         if (!this.#open)
             return;
+        const conversation = discordInboundConversation(String(this.#options.id), interaction);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target: interaction.channelId,
+            conversation,
+            message: { conversation, id: interaction.id },
             content: formatButtonContent(interaction),
             segments: formatButtonSegments(interaction),
             sender: interaction.userName,
-            id: interaction.id,
             metadata: Object.freeze({
                 endpoint: this.#options.config.name,
                 eventType: 'button',
@@ -167,7 +168,7 @@ export class DiscordGatewayEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'discord_gateway_receive_failed',
-                target: interaction.channelId,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
@@ -349,9 +350,9 @@ export class DiscordInteractionsEndpoint {
         this.#started = false;
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
-    async send({ target, conversation, payload }) {
+    async send({ conversation, payload }) {
         const body = formatOutboundBody(payload);
-        const channelId = nativeConversationId(target, conversation);
+        const channelId = conversation.id;
         const response = await this.#fetch(`${DISCORD_API}/channels/${channelId}/messages`, {
             method: 'POST',
             headers: {
@@ -367,7 +368,13 @@ export class DiscordInteractionsEndpoint {
         }
         const data = JSON.parse(text);
         const snowflake = data.id ?? '';
-        return snowflake ? formatLegacyMessageReference({ target, messageId: snowflake }) : '';
+        // recall 链路仍是本端点编码的 legacy 引用，在边界内部从 conversation 派生 target
+        return snowflake
+            ? formatLegacyMessageReference({
+                target: formatLegacyConversationRef(conversation),
+                messageId: snowflake,
+            })
+            : '';
     }
     async recallMessage(messageId) {
         if (!messageId)
@@ -390,13 +397,13 @@ export class DiscordInteractionsEndpoint {
     admit(msg) {
         if (!this.#open)
             return;
+        const conversation = discordInboundConversation(String(this.#options.id), msg);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target: msg.channelId,
+            conversation,
+            message: { conversation, id: msg.id },
             content: formatInboundContent(msg),
             segments: formatInboundSegments(msg),
             sender: senderDisplayName(msg),
-            id: msg.id,
             metadata: Object.freeze({
                 endpoint: this.#options.config.name,
                 channelKind: msg.channelKind,
@@ -407,7 +414,7 @@ export class DiscordInteractionsEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'discord_gateway_receive_failed',
-                target: msg.channelId,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });

package/lib/protocol.d.ts

@@ -3,6 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import type { Segment } from '@zhin.js/core/runtime';
+import type { ConversationRef } from '@zhin.js/im-contract';
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface DiscordAdapterConfig {
     readonly name?: string;
@@ -122,6 +123,16 @@ export interface DiscordOutboundBody {
 }
 export declare function resolveDiscordConfig(config?: DiscordAdapterConfig): ResolvedDiscordConfig;
 export declare function resolveChannelKind(channelType: number | string | undefined): 'private' | 'group' | 'channel';
+/**
+ * 入站归一化 → ConversationRef：DM → 'private'；GroupDM → 'group'；
+ * guild 频道 → 'channel' + guild 容器进 parent（guild 是频道容器，kind 'channel'）。
+ * endpoint.adapter = owner PluginId（CapabilityId 以 \0 分隔）。
+ */
+export declare function discordInboundConversation(endpointId: string, msg: {
+    readonly channelId: string;
+    readonly channelKind: 'private' | 'group' | 'channel';
+    readonly guildId?: string;
+}): ConversationRef;
 export declare function senderDisplayName(msg: DiscordInboundMessage): string;
 /** Build inbound text for MessageGateway.receive (gateway owns reply routing). */
 export declare function formatInboundContent(msg: DiscordInboundMessage): string;

package/lib/protocol.js

@@ -59,6 +59,21 @@ export function resolveChannelKind(channelType) {
         return 'group';
     return 'channel';
 }
+/**
+ * 入站归一化 → ConversationRef：DM → 'private'；GroupDM → 'group'；
+ * guild 频道 → 'channel' + guild 容器进 parent（guild 是频道容器，kind 'channel'）。
+ * endpoint.adapter = owner PluginId（CapabilityId 以 \0 分隔）。
+ */
+export function discordInboundConversation(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-discord",
-  "version": "7.0.1",
+  "version": "7.0.3",
   "description": "Zhin.js Discord adapter for Plugin Runtime (Gateway WebSocket)",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,21 +33,21 @@
   },
   "dependencies": {
     "discord.js": "^14.27.0",
-    "@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/im-contract": "1.0.0",
+    "@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.1",
-    "@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 +65,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.1",
-    "@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

@@ -13,6 +13,7 @@ import type {
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import {
+  formatLegacyConversationRef,
   formatLegacyMessageReference,
   nativeConversationId,
   parseLegacyMessageReference,
@@ -30,6 +31,7 @@ import {
   type DiscordClientTransport,
 } from './gateway.js';
 import {
+  discordInboundConversation,
   formatButtonContent,
   formatButtonSegments,
   formatInboundContent,
@@ -145,10 +147,11 @@ export class DiscordGatewayEndpoint implements EndpointInstance {
     logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
   }
 
-  async send({ target, conversation, payload }: EndpointSendRequest): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const body = formatOutboundBody(payload);
-    const channelId = nativeConversationId(target, conversation);
-    const snowflake = await this.#sendBody(channelId, body);
+    // recall 链路仍是本端点编码的 legacy 引用，在边界内部从 conversation 派生 target
+    const target = formatLegacyConversationRef(conversation);
+    const snowflake = await this.#sendBody(conversation.id, body);
     const messageId = formatLegacyMessageReference({ target, messageId: snowflake });
     logger.debug(formatCompact({
       op: 'discord_send',
@@ -175,13 +178,13 @@ export class DiscordGatewayEndpoint implements EndpointInstance {
   admit(msg: DiscordInboundMessage): void {
     if (!this.#open) return;
     if (msg.authorBot) return;
+    const conversation = discordInboundConversation(String(this.#options.id), msg);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target: msg.channelId,
+      conversation,
+      message: { conversation, id: msg.id },
       content: formatInboundContent(msg),
       segments: formatInboundSegments(msg),
       sender: senderDisplayName(msg),
-      id: msg.id,
       metadata: Object.freeze({
         endpoint: this.#options.config.name,
         channelKind: msg.channelKind,
@@ -194,7 +197,7 @@ export class DiscordGatewayEndpoint implements EndpointInstance {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'discord_gateway_receive_failed',
-        target: msg.channelId,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });
@@ -203,13 +206,13 @@ export class DiscordGatewayEndpoint implements EndpointInstance {
   /** Test / internal: admit a button interaction when open. */
   admitButton(interaction: DiscordButtonInbound): void {
     if (!this.#open) return;
+    const conversation = discordInboundConversation(String(this.#options.id), interaction);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target: interaction.channelId,
+      conversation,
+      message: { conversation, id: interaction.id },
       content: formatButtonContent(interaction),
       segments: formatButtonSegments(interaction),
       sender: interaction.userName,
-      id: interaction.id,
       metadata: Object.freeze({
         endpoint: this.#options.config.name,
         eventType: 'button',
@@ -219,7 +222,7 @@ export class DiscordGatewayEndpoint implements EndpointInstance {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'discord_gateway_receive_failed',
-        target: interaction.channelId,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });
@@ -465,9 +468,9 @@ export class DiscordInteractionsEndpoint implements EndpointInstance {
     logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
   }
 
-  async send({ target, conversation, payload }: EndpointSendRequest): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const body = formatOutboundBody(payload);
-    const channelId = nativeConversationId(target, conversation);
+    const channelId = conversation.id;
     const response = await this.#fetch(`${DISCORD_API}/channels/${channelId}/messages`, {
       method: 'POST',
       headers: {
@@ -483,7 +486,13 @@ export class DiscordInteractionsEndpoint implements EndpointInstance {
     }
     const data = JSON.parse(text) as { id?: string };
     const snowflake = data.id ?? '';
-    return snowflake ? formatLegacyMessageReference({ target, messageId: snowflake }) : '';
+    // recall 链路仍是本端点编码的 legacy 引用，在边界内部从 conversation 派生 target
+    return snowflake
+      ? formatLegacyMessageReference({
+        target: formatLegacyConversationRef(conversation),
+        messageId: snowflake,
+      })
+      : '';
   }
 
   async recallMessage(messageId: string): Promise<void> {
@@ -505,13 +514,13 @@ export class DiscordInteractionsEndpoint implements EndpointInstance {
 
   admit(msg: DiscordInboundMessage): void {
     if (!this.#open) return;
+    const conversation = discordInboundConversation(String(this.#options.id), msg);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target: msg.channelId,
+      conversation,
+      message: { conversation, id: msg.id },
       content: formatInboundContent(msg),
       segments: formatInboundSegments(msg),
       sender: senderDisplayName(msg),
-      id: msg.id,
       metadata: Object.freeze({
         endpoint: this.#options.config.name,
         channelKind: msg.channelKind,
@@ -522,7 +531,7 @@ export class DiscordInteractionsEndpoint implements EndpointInstance {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'discord_gateway_receive_failed',
-        target: msg.channelId,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });

package/src/protocol.ts

@@ -6,6 +6,7 @@
 import { createPublicKey, verify as cryptoVerify } from 'node:crypto';
 import { isMediaRef } from '@zhin.js/core';
 import type { Segment } from '@zhin.js/core/runtime';
+import type { ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('discord');
@@ -199,6 +200,29 @@ export function resolveChannelKind(channelType: number | string | undefined): 'p
   return 'channel';
 }
 
+/**
+ * 入站归一化 → ConversationRef：DM → 'private'；GroupDM → 'group'；
+ * guild 频道 → 'channel' + guild 容器进 parent（guild 是频道容器，kind 'channel'）。
+ * endpoint.adapter = owner PluginId（CapabilityId 以 \0 分隔）。
+ */
+export function discordInboundConversation(
+  endpointId: string,
+  msg: {
+    readonly channelId: string;
+    readonly channelKind: 'private' | 'group' | 'channel';
+    readonly guildId?: string;
+  },
+): 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: DiscordInboundMessage): string {
   return msg.authorName || msg.authorId;
 }