@zhin.js/adapter-discord 7.0.2 → 7.0.5

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # @zhin.js/adapter-discord
 
+## 7.0.5
+
+### Patch Changes
+
+- 51015d6: refactor(adapters): migrate platform-permit to PermissionSubject
+
+  All adapter platform-permit checkers now accept PermissionSubject
+  (duck-typed from Message/CommandSession) instead of Message directly.
+  registerPlatformPermitChecker is replaced by host.registerPlatform in
+  the adapter plugin setup. activity-feedback service updated for new
+  PermissionHost integration.
+
+- Updated dependencies [6f9c366]
+- Updated dependencies [373a56b]
+- Updated dependencies [0de46a8]
+- Updated dependencies [c106ecc]
+- Updated dependencies [ca92e03]
+- Updated dependencies [b0f37ae]
+- Updated dependencies [ba08a2f]
+- Updated dependencies [b08f7fe]
+- Updated dependencies [daffd4c]
+- Updated dependencies [36c7400]
+- Updated dependencies [a9fa72e]
+- Updated dependencies [c8de3ef]
+- Updated dependencies [60f0fc8]
+- Updated dependencies [574c990]
+- Updated dependencies [d096f16]
+- Updated dependencies [3f29623]
+- Updated dependencies [2916852]
+- Updated dependencies [d047869]
+- Updated dependencies [162fa34]
+- Updated dependencies [e62561e]
+- Updated dependencies [3eeeb46]
+- Updated dependencies [85d0f82]
+- Updated dependencies [61bfc1c]
+- Updated dependencies [04bad47]
+- Updated dependencies [e40b048]
+- Updated dependencies [5a5b1bb]
+- Updated dependencies [f1708c3]
+- Updated dependencies [d254a81]
+- Updated dependencies [7123c47]
+- Updated dependencies [05befc1]
+- Updated dependencies [0663b6a]
+- Updated dependencies [f28f9b3]
+- Updated dependencies [9f340f7]
+- Updated dependencies [e53444f]
+- Updated dependencies [5eedd26]
+- Updated dependencies [92b0dd7]
+- Updated dependencies [f919b6f]
+- Updated dependencies [098e411]
+- Updated dependencies [e1b7c01]
+- Updated dependencies [9b94f87]
+- Updated dependencies [a7df753]
+  - @zhin.js/agent@1.1.5
+  - @zhin.js/host-http@1.0.8
+  - @zhin.js/permission@1.0.1
+  - @zhin.js/im-contract@1.0.3
+  - @zhin.js/adapter@1.1.7
+  - @zhin.js/plugin-runtime@1.1.5
+  - @zhin.js/command@1.0.9
+  - @zhin.js/core@1.5.4
+  - zhin.js@6.0.4
+
+## 7.0.4
+
+### Patch Changes
+
+- f8c7a54: fix: im
+- Updated dependencies [f8c7a54]
+  - @zhin.js/logger@1.0.76
+  - @zhin.js/host-http@1.0.7
+  - @zhin.js/adapter@1.1.6
+  - @zhin.js/agent@1.1.4
+  - @zhin.js/command@1.0.8
+  - @zhin.js/core@1.5.3
+  - @zhin.js/im-contract@1.0.2
+  - @zhin.js/plugin-runtime@1.1.4
+  - zhin.js@6.0.3
+
+## 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 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/adapters/discord.js

@@ -21,8 +21,8 @@ export default defineAdapter({
         const config = resolveDiscordConfig(context.config);
         const gateway = context.use(messageGatewayToken);
         // 注册到插件运行时状态（discord.endpoint list 的"运行中"数据源）
-        context.use(discordRuntimeStateToken).endpoints.set(config.name, {
-            name: config.name,
+        context.use(discordRuntimeStateToken).endpoints.set(config.id, {
+            id: config.id,
             mode: config.connection,
         });
         if (config.connection === 'interactions') {

package/adapters/discord.ts

@@ -37,8 +37,8 @@ export default defineAdapter<DiscordAdapterConfig>({
     const config = resolveDiscordConfig(context.config);
     const gateway = context.use(messageGatewayToken);
     // 注册到插件运行时状态（discord.endpoint list 的"运行中"数据源）
-    context.use(discordRuntimeStateToken).endpoints.set(config.name, {
-      name: config.name,
+    context.use(discordRuntimeStateToken).endpoints.set(config.id, {
+      id: config.id,
       mode: config.connection,
     });
     if (config.connection === 'interactions') {

package/lib/discord-agent-deps.d.ts

@@ -25,11 +25,11 @@ export interface DiscordAgentEndpoint {
     getGuildInfo(guildId: string): Promise<unknown>;
 }
 export interface DiscordAgentDeps {
-    getEndpoint: (endpointId: string) => DiscordAgentEndpoint;
+    getEndpoint: (endpointKey: string) => DiscordAgentEndpoint;
     /** Alias kept for existing agent/tools that call getGatewayEndpoint. */
-    getGatewayEndpoint: (endpointId: string) => DiscordAgentEndpoint;
+    getGatewayEndpoint: (endpointKey: string) => DiscordAgentEndpoint;
 }
-export declare function registerDiscordAgentEndpoint(endpointId: string, endpoint: DiscordAgentEndpoint): () => void;
+export declare function registerDiscordAgentEndpoint(endpointKey: string, endpoint: DiscordAgentEndpoint): () => void;
 /** Optional override used by tests / transitional callers. Pass `null` to clear. */
 export declare function setDiscordAgentDeps(deps: DiscordAgentDeps | null): void;
 export declare function getDiscordAgentDeps(): DiscordAgentDeps;

package/lib/discord-agent-deps.js

@@ -4,11 +4,11 @@
  */
 const endpoints = new Map();
 let override = null;
-export function registerDiscordAgentEndpoint(endpointId, endpoint) {
-    endpoints.set(endpointId, endpoint);
+export function registerDiscordAgentEndpoint(endpointKey, endpoint) {
+    endpoints.set(endpointKey, endpoint);
     return () => {
-        if (endpoints.get(endpointId) === endpoint) {
-            endpoints.delete(endpointId);
+        if (endpoints.get(endpointKey) === endpoint) {
+            endpoints.delete(endpointKey);
         }
     };
 }
@@ -16,10 +16,10 @@ export function registerDiscordAgentEndpoint(endpointId, endpoint) {
 export function setDiscordAgentDeps(deps) {
     override = deps;
 }
-function lookup(endpointId) {
-    const registered = endpoints.get(endpointId);
+function lookup(endpointKey) {
+    const registered = endpoints.get(endpointKey);
     if (!registered)
-        throw new Error(`Endpoint ${endpointId} 不存在`);
+        throw new Error(`Endpoint ${endpointKey} 不存在`);
     return registered;
 }
 export function getDiscordAgentDeps() {

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,17 +2,17 @@
  * 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 { formatCompact, getLogger } from '@zhin.js/logger';
+import { formatLegacyConversationRef, formatLegacyMessageRef, nativeConversationId, parseLegacyMessageReference, } from '@zhin.js/im-contract';
+import { formatCompact, getAdapterLogger } 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 超时。 */
 const OUTBOUND_TIMEOUT_MS = 30_000;
-const logger = getLogger('discord');
 export class DiscordGatewayEndpoint {
+    #logger;
     #options;
     #createClient;
     #client = null;
@@ -37,6 +37,7 @@ export class DiscordGatewayEndpoint {
         },
     });
     constructor(options) {
+        this.#logger = getAdapterLogger('discord', options.config.id);
         this.#options = options;
         this.#createClient = options.createClient ?? defaultCreateClient;
     }
@@ -45,7 +46,7 @@ export class DiscordGatewayEndpoint {
             return;
         this.#started = true;
         try {
-            this.#unregisterAgent = registerDiscordAgentEndpoint(this.#options.config.name, this);
+            this.#unregisterAgent = registerDiscordAgentEndpoint(this.#options.config.id, this);
             const intents = this.#options.config.intents?.length
                 ? [...this.#options.config.intents]
                 : DEFAULT_INTENTS;
@@ -54,16 +55,16 @@ export class DiscordGatewayEndpoint {
                 onMessage: (msg) => this.admit(msg),
                 onButton: (interaction) => this.admitButton(interaction),
             });
-            logger.info(formatCompact({
+            this.#logger.info(formatCompact({
                 op: 'connect',
-                endpoint: this.#options.config.name,
+                endpoint: this.#options.config.id,
                 mode: 'gateway',
                 user: this.#client.user?.tag,
             }));
         }
         catch (error) {
             await this.stop();
-            logger.error('Failed to connect Discord gateway:', error);
+            this.#logger.error('Failed to connect Discord gateway:', error);
             throw error;
         }
     }
@@ -88,17 +89,17 @@ export class DiscordGatewayEndpoint {
             this.#client = null;
         }
         this.#started = false;
-        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
-    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);
-        const messageId = formatLegacyMessageReference({ target, messageId: snowflake });
-        logger.debug(formatCompact({
+        // recall 链路仍是本端点编码的 legacy 引用，在边界内部从 conversation 派生
+        const snowflake = await this.#sendBody(conversation.id, body);
+        const messageId = formatLegacyMessageRef({ conversation, id: snowflake });
+        this.#logger.debug(formatCompact({
             op: 'discord_send',
-            endpoint: this.#options.config.name,
-            target,
+            endpoint: this.#options.config.id,
+            target: formatLegacyConversationRef(conversation),
             messageId,
         }));
         return messageId;
@@ -123,26 +124,30 @@ 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,
+            sender: {
+                id: msg.authorId,
+                name: senderDisplayName(msg) || undefined,
+                ...(resolveSenderRole(msg) ? { roles: [resolveSenderRole(msg)] } : {}),
+            },
+            endpointId: this.#options.config.id,
+            ...(msg.mentionedBot ? { mentioned: true } : {}),
             metadata: Object.freeze({
-                endpoint: this.#options.config.name,
                 channelKind: msg.channelKind,
                 userId: msg.authorId,
                 guildId: msg.guildId,
                 permissions: msg.permissionTokens,
                 role: resolveSenderRole(msg),
-                ...(msg.mentionedBot ? { mentioned: true } : {}),
             }),
         }).catch((err) => {
-            logger.warn(formatCompact({
+            this.#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,23 +156,23 @@ 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,
+            sender: { id: interaction.userId, name: interaction.userName },
+            endpointId: this.#options.config.id,
             metadata: Object.freeze({
-                endpoint: this.#options.config.name,
                 eventType: 'button',
                 payload: interaction.customId,
                 sourceMessageId: interaction.sourceMessageId,
             }),
         }).catch((err) => {
-            logger.warn(formatCompact({
+            this.#logger.warn(formatCompact({
                 op: 'discord_gateway_receive_failed',
-                target: interaction.channelId,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
@@ -306,6 +311,7 @@ export class DiscordGatewayEndpoint {
     }
 }
 export class DiscordInteractionsEndpoint {
+    #logger;
     #options;
     #fetch;
     #routeReleases = [];
@@ -315,6 +321,7 @@ export class DiscordInteractionsEndpoint {
         recall: (messageId) => this.recallMessage(messageId),
     });
     constructor(options) {
+        this.#logger = getAdapterLogger('discord', options.config.id);
         this.#options = options;
         this.#fetch = options.fetch ?? globalThis.fetch;
     }
@@ -329,9 +336,9 @@ export class DiscordInteractionsEndpoint {
             return;
         this.#started = true;
         this.#routeReleases.push(...registerDiscordInteractionRoutes(this.#options.http, this));
-        logger.info(formatCompact({
+        this.#logger.info(formatCompact({
             op: 'connect',
-            endpoint: this.#options.config.name,
+            endpoint: this.#options.config.id,
             mode: 'interactions',
             path: this.#options.config.interactionsPath,
         }));
@@ -347,11 +354,11 @@ export class DiscordInteractionsEndpoint {
         for (const release of this.#routeReleases.splice(0))
             release();
         this.#started = false;
-        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
-    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 +374,8 @@ export class DiscordInteractionsEndpoint {
         }
         const data = JSON.parse(text);
         const snowflake = data.id ?? '';
-        return snowflake ? formatLegacyMessageReference({ target, messageId: snowflake }) : '';
+        // recall 链路仍是本端点编码的 legacy 引用，在边界内部从 conversation 派生
+        return snowflake ? formatLegacyMessageRef({ conversation, id: snowflake }) : '';
     }
     async recallMessage(messageId) {
         if (!messageId)
@@ -390,24 +398,28 @@ 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,
+            sender: {
+                id: msg.authorId,
+                name: senderDisplayName(msg) || undefined,
+                ...(resolveSenderRole(msg) ? { roles: [resolveSenderRole(msg)] } : {}),
+            },
+            endpointId: this.#options.config.id,
             metadata: Object.freeze({
-                endpoint: this.#options.config.name,
                 channelKind: msg.channelKind,
                 userId: msg.authorId,
                 guildId: msg.guildId,
                 eventType: 'application_command',
             }),
         }).catch((err) => {
-            logger.warn(formatCompact({
+            this.#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/index.d.ts

@@ -1,6 +1,6 @@
 export { activityTypeCode, formatButtonContent, formatInboundContent, formatOutboundBody, resolveChannelKind, resolveDiscordConfig, senderDisplayName, type DiscordAdapterConfig, type DiscordButtonInbound, type DiscordInboundAttachment, type DiscordInboundMessage, type DiscordOutboundBody, type DiscordWireSegment, type ResolvedDiscordConfig, type ResolvedDiscordGatewayConfig, type ResolvedDiscordInteractionsConfig, } from './protocol.js';
 export { getDiscordAgentDeps, registerDiscordAgentEndpoint, setDiscordAgentDeps, type DiscordAgentDeps, type DiscordAgentEndpoint, } from './discord-agent-deps.js';
-export { checkDiscordPlatformPermit, discordGroupPermitResolver, normalizeDiscordSenderForPermit, platformPermit, registerDiscordPlatformPermitChecker, } from './platform-permit.js';
+export { checkDiscordPlatformPermit, discordGroupPermitResolver, normalizeDiscordSenderForPermit, platformPermit, } from './platform-permit.js';
 export { DiscordGatewayEndpoint, DiscordInteractionsEndpoint, type CreateDiscordClient, type DiscordClientTransport, type DiscordEndpointOptions, type DiscordInteractionsEndpointOptions, } from './endpoint.js';
 export { connectDiscordGatewayClient, defaultCreateClient, normalizeDiscordMessage, resolveSenderRole, toMessageCreateOptions, type DiscordGatewayConnectHandlers, } from './gateway.js';
 export { handleDiscordInteractionRequest, registerDiscordInteractionRoutes, type DiscordInteractionsHandler, } from './webhook.js';

package/lib/index.js

@@ -1,6 +1,6 @@
 export { activityTypeCode, formatButtonContent, formatInboundContent, formatOutboundBody, resolveChannelKind, resolveDiscordConfig, senderDisplayName, } from './protocol.js';
 export { getDiscordAgentDeps, registerDiscordAgentEndpoint, setDiscordAgentDeps, } from './discord-agent-deps.js';
-export { checkDiscordPlatformPermit, discordGroupPermitResolver, normalizeDiscordSenderForPermit, platformPermit, registerDiscordPlatformPermitChecker, } from './platform-permit.js';
+export { checkDiscordPlatformPermit, discordGroupPermitResolver, normalizeDiscordSenderForPermit, platformPermit, } from './platform-permit.js';
 export { DiscordGatewayEndpoint, DiscordInteractionsEndpoint, } from './endpoint.js';
 export { connectDiscordGatewayClient, defaultCreateClient, normalizeDiscordMessage, resolveSenderRole, toMessageCreateOptions, } from './gateway.js';
 export { handleDiscordInteractionRequest, registerDiscordInteractionRoutes, } from './webhook.js';

package/lib/platform-permit.d.ts

@@ -1,7 +1,7 @@
 /**
  * Discord platform permit — Guild 权限位
  */
-import { type Message } from '@zhin.js/core';
+import type { PermissionSubject } from '@zhin.js/permission';
 export declare function platformPermit(perm: string): string;
 export declare function discordGroupPermitResolver(logicalPerm: string): string;
 export declare function normalizeDiscordSenderForPermit(input: {
@@ -11,5 +11,4 @@ export declare function normalizeDiscordSenderForPermit(input: {
     role?: string;
     permissions?: string[];
 };
-export declare function checkDiscordPlatformPermit(perm: string, message: Message<any>): boolean;
-export declare function registerDiscordPlatformPermitChecker(): () => void;
+export declare function checkDiscordPlatformPermit(perm: string, subject: PermissionSubject): boolean;

package/lib/platform-permit.js

@@ -1,7 +1,3 @@
-/**
- * Discord platform permit — Guild 权限位
- */
-import { registerPlatformPermitChecker } from '@zhin.js/core';
 const ADAPTER = 'discord';
 export function platformPermit(perm) {
     return `platform(${ADAPTER},${perm})`;
@@ -27,12 +23,9 @@ export function normalizeDiscordSenderForPermit(input) {
     }
     return { role: 'member', permissions };
 }
-function senderPermits(message) {
-    const sender = message.$sender;
-    return { role: sender.role, permissions: sender.permissions ?? [] };
-}
-export function checkDiscordPlatformPermit(perm, message) {
-    const { role, permissions } = senderPermits(message);
+export function checkDiscordPlatformPermit(perm, subject) {
+    const role = subject.sender?.role?.[0];
+    const permissions = subject.sender?.permissions ?? [];
     const has = (t) => permissions.includes(t);
     switch (perm) {
         case 'guild_owner':
@@ -47,6 +40,3 @@ export function checkDiscordPlatformPermit(perm, message) {
             return false;
     }
 }
-export function registerDiscordPlatformPermitChecker() {
-    return registerPlatformPermitChecker(ADAPTER, checkDiscordPlatformPermit);
-}

package/lib/protocol.d.ts

@@ -3,9 +3,10 @@
  * 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;
+    readonly id?: string;
     readonly token?: string;
     /** Default `gateway`. `interactions` uses httpHostToken POST + Ed25519 verify. */
     readonly connection?: 'gateway' | 'interactions';
@@ -25,7 +26,7 @@ export interface DiscordAdapterConfig {
     /** Transitional: legacy root `endpoints[]` with `context: discord`. */
     readonly endpoints?: ReadonlyArray<{
         readonly context?: string;
-        readonly name?: string;
+        readonly id?: string;
         readonly token?: string;
         readonly connection?: 'gateway' | 'interactions';
         readonly intents?: readonly number[];
@@ -41,7 +42,7 @@ export interface DiscordAdapterConfig {
 export interface ResolvedDiscordGatewayConfig {
     readonly context: 'discord';
     readonly connection: 'gateway';
-    readonly name: string;
+    readonly id: string;
     readonly token: string;
     readonly intents?: readonly number[];
     readonly enableSlashCommands: boolean;
@@ -52,7 +53,7 @@ export interface ResolvedDiscordGatewayConfig {
 export interface ResolvedDiscordInteractionsConfig {
     readonly context: 'discord';
     readonly connection: 'interactions';
-    readonly name: string;
+    readonly id: string;
     readonly token: string;
     readonly applicationId: string;
     readonly publicKey: 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(endpointKey: 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

@@ -15,8 +15,8 @@ export function resolveDiscordConfig(config = {}) {
     if (!token) {
         throw new TypeError('Discord adapter requires token (plugins.<key>.token or endpoints with context: discord)');
     }
-    const name = (typeof config.name === 'string' && config.name)
-        || (typeof entry?.name === 'string' && entry.name)
+    const id = (typeof config.id === 'string' && config.id)
+        || (typeof entry?.id === 'string' && entry.id)
         || process.env.DISCORD_BOT_NAME
         || 'discord-bot';
     const connection = config.connection
@@ -31,7 +31,7 @@ export function resolveDiscordConfig(config = {}) {
         return {
             context: 'discord',
             connection: 'interactions',
-            name,
+            id,
             token,
             applicationId,
             publicKey,
@@ -41,7 +41,7 @@ export function resolveDiscordConfig(config = {}) {
     return {
         context: 'discord',
         connection: 'gateway',
-        name,
+        id,
         token,
         intents: config.intents ?? entry?.intents,
         enableSlashCommands: config.enableSlashCommands === true
@@ -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(endpointKey, msg) {
+    return {
+        endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+        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.2",
+  "version": "7.0.5",
   "description": "Zhin.js Discord adapter for Plugin Runtime (Gateway WebSocket)",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,21 +33,22 @@
   },
   "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/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.2"
+    "@zhin.js/adapter": "1.1.7",
+    "@zhin.js/command": "1.0.9",
+    "@zhin.js/core": "1.5.4",
+    "@zhin.js/host-http": "1.0.8",
+    "@zhin.js/im-contract": "1.0.3",
+    "@zhin.js/logger": "1.0.76",
+    "@zhin.js/permission": "1.0.1",
+    "@zhin.js/plugin-runtime": "1.1.5"
   },
   "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.7",
+    "@zhin.js/agent": "1.1.5",
+    "@zhin.js/core": "1.5.4",
+    "@zhin.js/plugin-runtime": "1.1.5",
+    "zhin.js": "6.0.4"
   },
   "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.5",
+    "@zhin.js/host-http": "1.0.8",
+    "zhin.js": "6.0.4"
   },
   "files": [
     "adapters",

package/plugin.js

@@ -1,7 +1,8 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { createEndpointRuntimeState } from '@zhin.js/adapter';
 import { definePlugin } from '@zhin.js/plugin-runtime';
-import { registerDiscordPlatformPermitChecker } from "./lib/platform-permit.js";
+import { permissionHostToken } from '@zhin.js/permission';
+import { checkDiscordPlatformPermit } from "./lib/platform-permit.js";
 import { discordRuntimeStateToken } from "./lib/discord-runtime-state.js";
 export default definePlugin({
     name: 'discord',
@@ -9,9 +10,10 @@ export default definePlugin({
         displayName: 'Discord Gateway Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表（discord.endpoint list 的"运行中"数据源）
         context.resources.provide(discordRuntimeStateToken, createEndpointRuntimeState());
-        // 平台权限门禁：guild_owner / moderate_members 等（agent 工具 platformPermit）
-        return registerDiscordPlatformPermitChecker();
+        if (context.resources.has(permissionHostToken)) {
+            const host = context.resources.use(permissionHostToken);
+            return host.registerPlatform('discord', checkDiscordPlatformPermit);
+        }
     },
 });

package/schema.json

@@ -71,24 +71,60 @@
       "default": "/discord/interactions",
       "description": "POST path on httpHostToken when connection is interactions."
     },
+    "master": {
+      "type": [
+        "string",
+        "number"
+      ],
+      "description": "框架 master（Discord user snowflake；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖"
+    },
+    "trusted": {
+      "type": "array",
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ],
+        "description": "Trusted Discord user snowflake"
+      },
+      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加"
+    },
     "endpoints": {
       "type": "array",
-      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
       "items": {
         "type": "object",
         "additionalProperties": true,
         "properties": {
-          "name": {
-            "type": "string",
-            "description": "Discord bot name"
+          "master": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "本 endpoint 的框架 master（Discord user snowflake）；覆盖顶层 master"
+          },
+          "trusted": {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Trusted Discord user snowflake"
+            },
+            "description": "本 endpoint 的 trusted 列表"
           },
           "token": {
             "type": "string",
             "description": "Discord bot token"
+          },
+          "id": {
+            "type": "string",
+            "description": "Discord bot name"
           }
         },
         "required": [
-          "name",
+          "id",
           "token"
         ]
       }

package/src/discord-agent-deps.ts

@@ -39,22 +39,22 @@ export interface DiscordAgentEndpoint {
 }
 
 export interface DiscordAgentDeps {
-  getEndpoint: (endpointId: string) => DiscordAgentEndpoint;
+  getEndpoint: (endpointKey: string) => DiscordAgentEndpoint;
   /** Alias kept for existing agent/tools that call getGatewayEndpoint. */
-  getGatewayEndpoint: (endpointId: string) => DiscordAgentEndpoint;
+  getGatewayEndpoint: (endpointKey: string) => DiscordAgentEndpoint;
 }
 
 const endpoints = new Map<string, DiscordAgentEndpoint>();
 let override: DiscordAgentDeps | null = null;
 
 export function registerDiscordAgentEndpoint(
-  endpointId: string,
+  endpointKey: string,
   endpoint: DiscordAgentEndpoint,
 ): () => void {
-  endpoints.set(endpointId, endpoint);
+  endpoints.set(endpointKey, endpoint);
   return () => {
-    if (endpoints.get(endpointId) === endpoint) {
-      endpoints.delete(endpointId);
+    if (endpoints.get(endpointKey) === endpoint) {
+      endpoints.delete(endpointKey);
     }
   };
 }
@@ -64,9 +64,9 @@ export function setDiscordAgentDeps(deps: DiscordAgentDeps | null): void {
   override = deps;
 }
 
-function lookup(endpointId: string): DiscordAgentEndpoint {
-  const registered = endpoints.get(endpointId);
-  if (!registered) throw new Error(`Endpoint ${endpointId} 不存在`);
+function lookup(endpointKey: string): DiscordAgentEndpoint {
+  const registered = endpoints.get(endpointKey);
+  if (!registered) throw new Error(`Endpoint ${endpointKey} 不存在`);
   return registered;
 }
 

package/src/endpoint.ts

@@ -13,11 +13,12 @@ import type {
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import {
-  formatLegacyMessageReference,
+  formatLegacyConversationRef,
+  formatLegacyMessageRef,
   nativeConversationId,
   parseLegacyMessageReference,
 } from '@zhin.js/im-contract';
-import { formatCompact, getLogger } from '@zhin.js/logger';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { registerDiscordAgentEndpoint } from './discord-agent-deps.js';
 import {
@@ -30,6 +31,7 @@ import {
   type DiscordClientTransport,
 } from './gateway.js';
 import {
+  discordInboundConversation,
   formatButtonContent,
   formatButtonSegments,
   formatInboundContent,
@@ -47,8 +49,6 @@ import { registerDiscordInteractionRoutes } from './webhook.js';
 const DISCORD_API = 'https://discord.com/api/v10';
 /** 出站 HTTP 调用统一 30s 超时。 */
 const OUTBOUND_TIMEOUT_MS = 30_000;
-const logger = getLogger('discord');
-
 export type {
   CreateDiscordClient,
   DiscordClientTransport,
@@ -62,6 +62,8 @@ export interface DiscordEndpointOptions {
 }
 
 export class DiscordGatewayEndpoint implements EndpointInstance {
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
   readonly #options: DiscordEndpointOptions;
   readonly #createClient: CreateDiscordClient;
   #client: DiscordClientTransport | null = null;
@@ -90,6 +92,7 @@ export class DiscordGatewayEndpoint implements EndpointInstance {
   });
 
   constructor(options: DiscordEndpointOptions) {
+    this.#logger = getAdapterLogger('discord', options.config.id);
     this.#options = options;
     this.#createClient = options.createClient ?? defaultCreateClient;
   }
@@ -98,7 +101,7 @@ export class DiscordGatewayEndpoint implements EndpointInstance {
     if (this.#started) return;
     this.#started = true;
     try {
-      this.#unregisterAgent = registerDiscordAgentEndpoint(this.#options.config.name, this);
+      this.#unregisterAgent = registerDiscordAgentEndpoint(this.#options.config.id, this);
       const intents = this.#options.config.intents?.length
         ? [...this.#options.config.intents]
         : DEFAULT_INTENTS;
@@ -107,15 +110,15 @@ export class DiscordGatewayEndpoint implements EndpointInstance {
         onMessage: (msg) => this.admit(msg),
         onButton: (interaction) => this.admitButton(interaction),
       });
-      logger.info(formatCompact({
+      this.#logger.info(formatCompact({
         op: 'connect',
-        endpoint: this.#options.config.name,
+        endpoint: this.#options.config.id,
         mode: 'gateway',
         user: this.#client.user?.tag,
       }));
     } catch (error) {
       await this.stop();
-      logger.error('Failed to connect Discord gateway:', error);
+      this.#logger.error('Failed to connect Discord gateway:', error);
       throw error;
     }
   }
@@ -142,18 +145,18 @@ export class DiscordGatewayEndpoint implements EndpointInstance {
       this.#client = null;
     }
     this.#started = false;
-    logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
-  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);
-    const messageId = formatLegacyMessageReference({ target, messageId: snowflake });
-    logger.debug(formatCompact({
+    // recall 链路仍是本端点编码的 legacy 引用，在边界内部从 conversation 派生
+    const snowflake = await this.#sendBody(conversation.id, body);
+    const messageId = formatLegacyMessageRef({ conversation, id: snowflake });
+    this.#logger.debug(formatCompact({
       op: 'discord_send',
-      endpoint: this.#options.config.name,
-      target,
+      endpoint: this.#options.config.id,
+      target: formatLegacyConversationRef(conversation),
       messageId,
     }));
     return messageId;
@@ -175,26 +178,30 @@ 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,
+      sender: {
+        id: msg.authorId,
+        name: senderDisplayName(msg) || undefined,
+        ...(resolveSenderRole(msg) ? { roles: [resolveSenderRole(msg)!] } : {}),
+      },
+      endpointId: this.#options.config.id,
+      ...(msg.mentionedBot ? { mentioned: true } : {}),
       metadata: Object.freeze({
-        endpoint: this.#options.config.name,
         channelKind: msg.channelKind,
         userId: msg.authorId,
         guildId: msg.guildId,
         permissions: msg.permissionTokens,
         role: resolveSenderRole(msg),
-        ...(msg.mentionedBot ? { mentioned: true } : {}),
       }),
     }).catch((err) => {
-      logger.warn(formatCompact({
+      this.#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,23 +210,23 @@ 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,
+      sender: { id: interaction.userId, name: interaction.userName },
+      endpointId: this.#options.config.id,
       metadata: Object.freeze({
-        endpoint: this.#options.config.name,
         eventType: 'button',
         payload: interaction.customId,
         sourceMessageId: interaction.sourceMessageId,
       }),
     }).catch((err) => {
-      logger.warn(formatCompact({
+      this.#logger.warn(formatCompact({
         op: 'discord_gateway_receive_failed',
-        target: interaction.channelId,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });
@@ -416,6 +423,8 @@ export interface DiscordInteractionsEndpointOptions {
 }
 
 export class DiscordInteractionsEndpoint implements EndpointInstance {
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
   readonly #options: DiscordInteractionsEndpointOptions;
   readonly #fetch: typeof globalThis.fetch;
   #routeReleases: HttpRouteRegistration[] = [];
@@ -426,6 +435,7 @@ export class DiscordInteractionsEndpoint implements EndpointInstance {
   });
 
   constructor(options: DiscordInteractionsEndpointOptions) {
+    this.#logger = getAdapterLogger('discord', options.config.id);
     this.#options = options;
     this.#fetch = options.fetch ?? globalThis.fetch;
   }
@@ -442,9 +452,9 @@ export class DiscordInteractionsEndpoint implements EndpointInstance {
     if (this.#started) return;
     this.#started = true;
     this.#routeReleases.push(...registerDiscordInteractionRoutes(this.#options.http, this));
-    logger.info(formatCompact({
+    this.#logger.info(formatCompact({
       op: 'connect',
-      endpoint: this.#options.config.name,
+      endpoint: this.#options.config.id,
       mode: 'interactions',
       path: this.#options.config.interactionsPath,
     }));
@@ -462,12 +472,12 @@ export class DiscordInteractionsEndpoint implements EndpointInstance {
     this.#open = false;
     for (const release of this.#routeReleases.splice(0)) release();
     this.#started = false;
-    logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
-  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 +493,8 @@ 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 派生
+    return snowflake ? formatLegacyMessageRef({ conversation, id: snowflake }) : '';
   }
 
   async recallMessage(messageId: string): Promise<void> {
@@ -505,24 +516,28 @@ 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,
+      sender: {
+        id: msg.authorId,
+        name: senderDisplayName(msg) || undefined,
+        ...(resolveSenderRole(msg) ? { roles: [resolveSenderRole(msg)!] } : {}),
+      },
+      endpointId: this.#options.config.id,
       metadata: Object.freeze({
-        endpoint: this.#options.config.name,
         channelKind: msg.channelKind,
         userId: msg.authorId,
         guildId: msg.guildId,
         eventType: 'application_command',
       }),
     }).catch((err) => {
-      logger.warn(formatCompact({
+      this.#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/index.ts

@@ -30,7 +30,6 @@ export {
   discordGroupPermitResolver,
   normalizeDiscordSenderForPermit,
   platformPermit,
-  registerDiscordPlatformPermitChecker,
 } from './platform-permit.js';
 
 export {

package/src/platform-permit.ts

@@ -1,7 +1,7 @@
 /**
  * Discord platform permit — Guild 权限位
  */
-import { registerPlatformPermitChecker, type Message } from '@zhin.js/core';
+import type { PermissionSubject } from '@zhin.js/permission';
 
 const ADAPTER = 'discord';
 
@@ -36,13 +36,9 @@ export function normalizeDiscordSenderForPermit(input: {
   return { role: 'member', permissions };
 }
 
-function senderPermits(message: Message<any>): { role?: string; permissions: string[] } {
-  const sender = message.$sender as { role?: string; permissions?: string[] };
-  return { role: sender.role, permissions: sender.permissions ?? [] };
-}
-
-export function checkDiscordPlatformPermit(perm: string, message: Message<any>): boolean {
-  const { role, permissions } = senderPermits(message);
+export function checkDiscordPlatformPermit(perm: string, subject: PermissionSubject): boolean {
+  const role = subject.sender?.role?.[0];
+  const permissions = subject.sender?.permissions ?? [];
   const has = (t: string) => permissions.includes(t);
 
   switch (perm) {
@@ -59,6 +55,3 @@ export function checkDiscordPlatformPermit(perm: string, message: Message<any>):
   }
 }
 
-export function registerDiscordPlatformPermitChecker(): () => void {
-  return registerPlatformPermitChecker(ADAPTER, checkDiscordPlatformPermit);
-}

package/src/protocol.ts

@@ -6,13 +6,14 @@
 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');
 
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface DiscordAdapterConfig {
-  readonly name?: string;
+  readonly id?: string;
   readonly token?: string;
   /** Default `gateway`. `interactions` uses httpHostToken POST + Ed25519 verify. */
   readonly connection?: 'gateway' | 'interactions';
@@ -32,7 +33,7 @@ export interface DiscordAdapterConfig {
   /** Transitional: legacy root `endpoints[]` with `context: discord`. */
   readonly endpoints?: ReadonlyArray<{
     readonly context?: string;
-    readonly name?: string;
+    readonly id?: string;
     readonly token?: string;
     readonly connection?: 'gateway' | 'interactions';
     readonly intents?: readonly number[];
@@ -49,7 +50,7 @@ export interface DiscordAdapterConfig {
 export interface ResolvedDiscordGatewayConfig {
   readonly context: 'discord';
   readonly connection: 'gateway';
-  readonly name: string;
+  readonly id: string;
   readonly token: string;
   readonly intents?: readonly number[];
   readonly enableSlashCommands: boolean;
@@ -61,7 +62,7 @@ export interface ResolvedDiscordGatewayConfig {
 export interface ResolvedDiscordInteractionsConfig {
   readonly context: 'discord';
   readonly connection: 'interactions';
-  readonly name: string;
+  readonly id: string;
   readonly token: string;
   readonly applicationId: string;
   readonly publicKey: string;
@@ -151,8 +152,8 @@ export function resolveDiscordConfig(config: DiscordAdapterConfig = {}): Resolve
       'Discord adapter requires token (plugins.<key>.token or endpoints with context: discord)',
     );
   }
-  const name = (typeof config.name === 'string' && config.name)
-    || (typeof entry?.name === 'string' && entry.name)
+  const id = (typeof config.id === 'string' && config.id)
+    || (typeof entry?.id === 'string' && entry.id)
     || process.env.DISCORD_BOT_NAME
     || 'discord-bot';
   const connection = config.connection
@@ -170,7 +171,7 @@ export function resolveDiscordConfig(config: DiscordAdapterConfig = {}): Resolve
     return {
       context: 'discord',
       connection: 'interactions',
-      name,
+      id,
       token,
       applicationId,
       publicKey,
@@ -181,7 +182,7 @@ export function resolveDiscordConfig(config: DiscordAdapterConfig = {}): Resolve
   return {
     context: 'discord',
     connection: 'gateway',
-    name,
+    id,
     token,
     intents: config.intents ?? entry?.intents,
     enableSlashCommands: config.enableSlashCommands === true
@@ -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(
+  endpointKey: string,
+  msg: {
+    readonly channelId: string;
+    readonly channelKind: 'private' | 'group' | 'channel';
+    readonly guildId?: string;
+  },
+): ConversationRef {
+  return {
+    endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+    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;
 }