@zhin.js/adapter-discord 7.0.14 → 8.0.1

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @zhin.js/adapter-discord
 
+## 8.0.1
+
+### Patch Changes
+
+- 1fc78bc: Unify native platform Client access behind the literal `adapter` discriminant. Handlers infer both native events and Clients, while command, inbound/outbound middleware, and both Agent tool authoring surfaces expose the exact operation-scoped Client through a lazy `$client` getter. Definitions without `adapter` keep `$client` typed as `unknown`, and runtime dispatch rejects adapter mismatches before resolving the Client. Bundled platform tools now use this single path instead of model-provided endpoint ids and adapter-specific dependency wrappers. Every adapter registers one Client/EventMap contract, and protocol adapters including NapCat, Milky, OneBot and Satori now produce transport-independent Client objects rather than letting Endpoint instances impersonate Clients.
+- Updated dependencies [e9c6a73]
+- Updated dependencies [4e8117c]
+- Updated dependencies [902fa35]
+- Updated dependencies [54bfd6b]
+- Updated dependencies [12025ee]
+- Updated dependencies [09b14d6]
+- Updated dependencies [1fc78bc]
+  - @zhin.js/agent@1.1.16
+  - @zhin.js/adapter@1.2.1
+  - @zhin.js/core@1.5.14
+  - @zhin.js/host-http@1.0.13
+  - @zhin.js/command@1.0.16
+  - @zhin.js/logger@1.0.77
+  - zhin.js@6.0.14
+  - @zhin.js/feature-kit@1.0.13
+  - @zhin.js/permission@1.0.4
+
+## 8.0.0
+
+### Patch Changes
+
+- f2c532f: Expose exact per-Endpoint message operations through one validated Adapter capability model, route Core control calls through declared active capabilities, and connect existing recall, edit, reaction, and typing implementations across platform adapters.
+- Updated dependencies [b10d058]
+- Updated dependencies [f2c532f]
+- Updated dependencies [3dbf990]
+  - @zhin.js/host-http@1.0.12
+  - @zhin.js/adapter@1.2.0
+  - @zhin.js/core@1.5.13
+  - @zhin.js/agent@1.1.15
+  - zhin.js@6.0.13
+
 ## 7.0.14
 
 ### Patch Changes

package/README.md

@@ -20,7 +20,7 @@ pnpm add @zhin.js/adapter-discord discord.js
 ## Plugin Runtime
 
 - `@zhin.js/adapter` — 约定式 `adapters/discord.ts`（`defineAdapter`）
-- `@zhin.js/core` — `messageGatewayToken` 入站/出站
+- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
 - `zhin.js` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 - **无需** `@zhin.js/host-http` / `@zhin.js/host-router`（Gateway 路径）
@@ -86,6 +86,15 @@ plugins:
 3. 开启 **MESSAGE CONTENT INTENT**
 4. 通过 OAuth2 URL 邀请 Bot 加入服务器
 
+## 故障排查
+
+| 现象 | 排查 |
+| --- | --- |
+| Gateway 反复断线 | 检查 Token、网络代理、Gateway Intents 与应用后台配置 |
+| 能上线但收不到正文 | 启用 Message Content Intent，并给 Bot 频道读取权限 |
+| 能收不能发 | 检查 Send Messages、Embed Links 与附件权限 |
+| `connection: interactions` 启动失败 | 当前生产路径使用 Gateway；改回 `gateway` |
+
 ## 许可证
 
 MIT License

package/adapters/discord.js

@@ -3,7 +3,6 @@
  * Convention entry: discover `adapters/discord.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { DiscordGatewayEndpoint, DiscordInteractionsEndpoint, } from "../lib/endpoint.js";
 import { resolveDiscordConfig, } from "../lib/protocol.js";
@@ -11,7 +10,9 @@ import { discordRuntimeStateToken } from "../lib/discord-runtime-state.js";
 export { DiscordGatewayEndpoint, DiscordInteractionsEndpoint, } from "../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
-    operations: ['recall'],
+    operations: (context) => context.config.connection === 'interactions'
+        ? ['recall']
+        : ['recall', 'reaction'],
     // 媒体 url 直发或由 AttachmentBuilder 物化本地文件上传；message components 原生按钮承载交互段。
     segments: {
         outboundMedia: ['url', 'upload'],
@@ -20,8 +21,6 @@ export default defineAdapter({
     },
     create(context) {
         const config = resolveDiscordConfig(context.config);
-        const gateway = context.use(messageGatewayToken);
-        const sideEvents = context.use(sideEventGatewayToken);
         // 注册到插件运行时状态（discord.endpoint list 的"运行中"数据源）
         context.use(discordRuntimeStateToken).endpoints.set(config.id, {
             id: config.id,
@@ -30,16 +29,12 @@ export default defineAdapter({
         if (config.connection === 'interactions') {
             return new DiscordInteractionsEndpoint({
                 id: context.id,
-                gateway,
-                sideEvents,
                 http: context.use(httpHostToken),
                 config,
             });
         }
         return new DiscordGatewayEndpoint({
             id: context.id,
-            gateway,
-            sideEvents,
             config,
         });
     },

package/adapters/discord.ts

@@ -2,7 +2,6 @@
  * Convention entry: discover `adapters/discord.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import {
   DiscordGatewayEndpoint,
@@ -27,7 +26,9 @@ export type {
 
 export default defineAdapter<DiscordAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
-  operations: ['recall'],
+  operations: (context) => context.config.connection === 'interactions'
+    ? ['recall']
+    : ['recall', 'reaction'],
   // 媒体 url 直发或由 AttachmentBuilder 物化本地文件上传；message components 原生按钮承载交互段。
   segments: {
     outboundMedia: ['url', 'upload'],
@@ -36,8 +37,6 @@ export default defineAdapter<DiscordAdapterConfig>({
   },
   create(context) {
     const config = resolveDiscordConfig(context.config);
-    const gateway = context.use(messageGatewayToken);
-    const sideEvents = context.use(sideEventGatewayToken);
     // 注册到插件运行时状态（discord.endpoint list 的"运行中"数据源）
     context.use(discordRuntimeStateToken).endpoints.set(config.id, {
       id: config.id,
@@ -46,16 +45,12 @@ export default defineAdapter<DiscordAdapterConfig>({
     if (config.connection === 'interactions') {
       return new DiscordInteractionsEndpoint({
         id: context.id,
-        gateway,
-        sideEvents,
         http: context.use(httpHostToken),
         config,
       });
     }
     return new DiscordGatewayEndpoint({
       id: context.id,
-      gateway,
-      sideEvents,
       config,
     });
   },

package/agent/tools/add_role.ts

@@ -1,24 +1,26 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
+import { requireDiscordGatewayClient } from '../../src/client.js';
 import { platformPermit } from '../../src/platform-permit.js';
-import { getDiscordAgentDeps } from '../../src/discord-agent-deps.js';
 
-export default defineAgentTool<{ endpoint_id: string; guild_id: string; user_id: string; role_id: string }>({
+export default defineAgentTool<{ guild_id: string; user_id: string; role_id: string }>({
   description: '给成员添加 Discord 角色',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     guild_id: z.string().describe('服务器 ID'),
     user_id: z.string().describe('用户 ID'),
     role_id: z.string().describe('角色 ID'),
   }),
-  platforms: ['discord'],
+  adapter: 'discord',
   tags: ['discord'],
   permissions: [platformPermit('manage_roles')],
-  async execute({ endpoint_id, guild_id, user_id, role_id  }: { endpoint_id: string; guild_id: string; user_id: string; role_id: string }) {
-    const endpoint = getDiscordAgentDeps().getGatewayEndpoint(endpoint_id) as {
-      addRole: (guildId: string, userId: string, roleId: string) => Promise<boolean>;
+  async execute({ guild_id, user_id, role_id  }: { guild_id: string; user_id: string; role_id: string }, context) {
+    const client = requireDiscordGatewayClient(context.$client);
+    const guild = await client.guilds.fetch(guild_id);
+    const member = await guild.members.fetch(user_id) as {
+      roles: { add(id: string): Promise<unknown> };
     };
-    const success = await endpoint.addRole(guild_id, user_id, role_id);
+    await member.roles.add(role_id);
+    const success = true;
     return { success, message: success ? `已给用户 ${user_id} 添加角色` : '操作失败' };
   },
 });

package/agent/tools/create_thread.ts

@@ -1,25 +1,28 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
+import { requireDiscordGatewayClient } from '../../src/client.js';
 import { platformPermit } from '../../src/platform-permit.js';
-import { getDiscordAgentDeps } from '../../src/discord-agent-deps.js';
 
-export default defineAgentTool<{ endpoint_id: string; channel_id: string; name: string; message_id?: string; auto_archive_duration?: number }>({
+export default defineAgentTool<{ channel_id: string; name: string; message_id?: string; auto_archive_duration?: number }>({
   description: '在 Discord 频道中创建帖子/子线程',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     channel_id: z.string().describe('频道 ID'),
     name: z.string().describe('帖子标题'),
     message_id: z.string().optional().describe('基于某条消息创建（可选）'),
     auto_archive_duration: z.number().optional().describe('自动归档时间（分钟：60/1440/4320/10080）'),
   }),
-  platforms: ['discord'],
+  adapter: 'discord',
   tags: ['discord'],
   permissions: [platformPermit('manage_channels')],
-  async execute({ endpoint_id, channel_id, name, message_id, auto_archive_duration  }: { endpoint_id: string; channel_id: string; name: string; message_id?: string; auto_archive_duration?: number }) {
-    const endpoint = getDiscordAgentDeps().getGatewayEndpoint(endpoint_id) as {
-      createThread: (channelId: string, threadName: string, messageId?: string, autoArchiveDuration?: number) => Promise<{ id: string }>;
-    };
-    const thread = await endpoint.createThread(channel_id, name, message_id, auto_archive_duration);
+  async execute({ channel_id, name, message_id, auto_archive_duration  }: { channel_id: string; name: string; message_id?: string; auto_archive_duration?: number }, context) {
+    const client = requireDiscordGatewayClient(context.$client);
+    const channel = await client.channels.fetch(channel_id);
+    if (!channel?.threads) throw new Error(`Channel ${channel_id} 不支持创建帖子`);
+    const thread = await channel.threads.create({
+      name,
+      autoArchiveDuration: auto_archive_duration || 1440,
+      ...(message_id ? { startMessage: message_id } : {}),
+    });
     return { success: true, thread_id: thread.id, message: `帖子 "${name}" 已创建` };
   },
 });

package/agent/tools/forum_post.ts

@@ -1,24 +1,33 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
-import { getDiscordAgentDeps } from '../../src/discord-agent-deps.js';
+import { requireDiscordGatewayClient } from '../../src/client.js';
+import { ChannelType } from 'discord.js';
 
-export default defineAgentTool<{ endpoint_id: string; channel_id: string; name: string; content: string; tags?: string }>({
+export default defineAgentTool<{ channel_id: string; name: string; content: string; tags?: string }>({
   description: '在 Discord 论坛频道中创建帖子',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     channel_id: z.string().describe('论坛频道 ID'),
     name: z.string().describe('帖子标题'),
     content: z.string().describe('帖子内容'),
     tags: z.string().optional().describe('标签名，逗号分隔（可选）'),
   }),
-  platforms: ['discord'],
+  adapter: 'discord',
   tags: ['discord'],
-  async execute({ endpoint_id, channel_id, name, content, tags  }: { endpoint_id: string; channel_id: string; name: string; content: string; tags?: string }) {
-    const endpoint = getDiscordAgentDeps().getGatewayEndpoint(endpoint_id) as {
-      createForumPost: (channelId: string, title: string, body: string, tagNames?: string[]) => Promise<{ id: string }>;
-    };
+  async execute({ channel_id, name, content, tags  }: { channel_id: string; name: string; content: string; tags?: string }, context) {
+    const client = requireDiscordGatewayClient(context.$client);
     const tagList = tags ? tags.split(',').map((t: string) => t.trim()) : undefined;
-    const thread = await endpoint.createForumPost(channel_id, name, content, tagList);
+    const channel = await client.channels.fetch(channel_id);
+    if (!channel?.threads || channel.type !== ChannelType.GuildForum) {
+      throw new Error(`Channel ${channel_id} 不是论坛频道`);
+    }
+    const tagIds = tagList?.length
+      ? channel.availableTags?.filter((tag) => tagList.includes(tag.name)).map((tag) => tag.id)
+      : undefined;
+    const thread = await channel.threads.create({
+      name,
+      message: { content },
+      ...(tagIds?.length ? { appliedTags: tagIds } : {}),
+    });
     return { success: true, thread_id: thread.id, message: `论坛帖 "${name}" 已创建` };
   },
 });

package/agent/tools/list_roles.ts

@@ -1,22 +1,34 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
+import { requireDiscordGatewayClient } from '../../src/client.js';
 import { platformPermit } from '../../src/platform-permit.js';
-import { getDiscordAgentDeps } from '../../src/discord-agent-deps.js';
 
-export default defineAgentTool<{ endpoint_id: string; guild_id: string }>({
+export default defineAgentTool<{ guild_id: string }>({
   description: '获取 Discord 服务器角色列表',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     guild_id: z.string().describe('服务器 ID'),
   }),
-  platforms: ['discord'],
+  adapter: 'discord',
   tags: ['discord'],
   permissions: [platformPermit('manage_roles')],
-  async execute({ endpoint_id, guild_id  }: { endpoint_id: string; guild_id: string }) {
-    const endpoint = getDiscordAgentDeps().getGatewayEndpoint(endpoint_id) as {
-      getRoles: (guildId: string) => Promise<unknown[]>;
-    };
-    const roles = await endpoint.getRoles(guild_id);
+  async execute({ guild_id  }: { guild_id: string }, context) {
+    const client = requireDiscordGatewayClient(context.$client);
+    const guild = await client.guilds.fetch(guild_id);
+    await guild.roles.fetch();
+    const cache = guild.roles.cache as Map<string, {
+      id: string;
+      name: string;
+      hexColor: string;
+      position: number;
+      permissions: { bitfield: bigint };
+    }>;
+    const roles = [...cache.values()].map((role) => ({
+      id: role.id,
+      name: role.name,
+      color: role.hexColor,
+      position: role.position,
+      permissions: role.permissions.bitfield.toString(),
+    }));
     return { roles, count: roles.length };
   },
 });

package/agent/tools/react.ts

@@ -1,22 +1,24 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
-import { getDiscordAgentDeps } from '../../src/discord-agent-deps.js';
+import { requireDiscordGatewayClient } from '../../src/client.js';
 
-export default defineAgentTool<{ endpoint_id: string; channel_id: string; message_id: string; emoji: string }>({
+export default defineAgentTool<{ channel_id: string; message_id: string; emoji: string }>({
   description: '对 Discord 消息添加表情反应',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     channel_id: z.string().describe('频道 ID'),
     message_id: z.string().describe('消息 ID'),
     emoji: z.string().describe('表情（Unicode 表情或自定义表情如 <:name:id>）'),
   }),
-  platforms: ['discord'],
+  adapter: 'discord',
   tags: ['discord'],
-  async execute({ endpoint_id, channel_id, message_id, emoji  }: { endpoint_id: string; channel_id: string; message_id: string; emoji: string }) {
-    const endpoint = getDiscordAgentDeps().getGatewayEndpoint(endpoint_id) as {
-      addReaction: (channelId: string, messageId: string, reaction: string) => Promise<void>;
-    };
-    await endpoint.addReaction(channel_id, message_id, emoji);
+  async execute({ channel_id, message_id, emoji  }: { channel_id: string; message_id: string; emoji: string }, context) {
+    const client = requireDiscordGatewayClient(context.$client);
+    const channel = await client.channels.fetch(channel_id);
+    if (!channel?.isTextBased() || !channel.messages) {
+      throw new Error(`Channel ${channel_id} 不是文本频道`);
+    }
+    const message = await channel.messages.fetch(message_id);
+    await message.react(emoji);
     return { success: true, message: `已添加反应 ${emoji}` };
   },
 });

package/agent/tools/remove_role.ts

@@ -1,24 +1,26 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
+import { requireDiscordGatewayClient } from '../../src/client.js';
 import { platformPermit } from '../../src/platform-permit.js';
-import { getDiscordAgentDeps } from '../../src/discord-agent-deps.js';
 
-export default defineAgentTool<{ endpoint_id: string; guild_id: string; user_id: string; role_id: string }>({
+export default defineAgentTool<{ guild_id: string; user_id: string; role_id: string }>({
   description: '移除成员的 Discord 角色',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     guild_id: z.string().describe('服务器 ID'),
     user_id: z.string().describe('用户 ID'),
     role_id: z.string().describe('角色 ID'),
   }),
-  platforms: ['discord'],
+  adapter: 'discord',
   tags: ['discord'],
   permissions: [platformPermit('manage_roles')],
-  async execute({ endpoint_id, guild_id, user_id, role_id  }: { endpoint_id: string; guild_id: string; user_id: string; role_id: string }) {
-    const endpoint = getDiscordAgentDeps().getGatewayEndpoint(endpoint_id) as {
-      removeRole: (guildId: string, userId: string, roleId: string) => Promise<boolean>;
+  async execute({ guild_id, user_id, role_id  }: { guild_id: string; user_id: string; role_id: string }, context) {
+    const client = requireDiscordGatewayClient(context.$client);
+    const guild = await client.guilds.fetch(guild_id);
+    const member = await guild.members.fetch(user_id) as {
+      roles: { remove(id: string): Promise<unknown> };
     };
-    const success = await endpoint.removeRole(guild_id, user_id, role_id);
+    await member.roles.remove(role_id);
+    const success = true;
     return { success, message: success ? `已移除用户 ${user_id} 的角色` : '操作失败' };
   },
 });

package/agent/tools/send_embed.ts

@@ -1,11 +1,10 @@
 import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
-import { getDiscordAgentDeps } from '../../src/discord-agent-deps.js';
+import { requireDiscordGatewayClient } from '../../src/client.js';
 
-export default defineAgentTool<{ endpoint_id: string; channel_id: string; title?: string; description?: string; color?: number; url?: string; fields?: string }>({
+export default defineAgentTool<{ channel_id: string; title?: string; description?: string; color?: number; url?: string; fields?: string }>({
   description: '发送 Discord 富文本嵌入消息（Embed）',
   inputSchema: z.object({
-    endpoint_id: z.string().describe('Endpoint 名称'),
     channel_id: z.string().describe('频道 ID'),
     title: z.string().optional().describe('Embed 标题'),
     description: z.string().optional().describe('Embed 描述'),
@@ -13,12 +12,10 @@ export default defineAgentTool<{ endpoint_id: string; channel_id: string; title?
     url: z.string().optional().describe('标题链接（可选）'),
     fields: z.string().optional().describe('字段，JSON 格式: [{"name":"k","value":"v","inline":false}]'),
   }),
-  platforms: ['discord'],
+  adapter: 'discord',
   tags: ['discord'],
-  async execute({ endpoint_id, channel_id, title, description, color, url, fields  }: { endpoint_id: string; channel_id: string; title?: string; description?: string; color?: number; url?: string; fields?: string }) {
-    const endpoint = getDiscordAgentDeps().getGatewayEndpoint(endpoint_id) as {
-      sendEmbed: (channelId: string, embed: Record<string, unknown>) => Promise<{ id: string }>;
-    };
+  async execute({ channel_id, title, description, color, url, fields  }: { channel_id: string; title?: string; description?: string; color?: number; url?: string; fields?: string }, context) {
+    const client = requireDiscordGatewayClient(context.$client);
     const embedData: Record<string, unknown> = {};
     if (title) embedData.title = title;
     if (description) embedData.description = description;
@@ -31,7 +28,11 @@ export default defineAgentTool<{ endpoint_id: string; channel_id: string; title?
         return { success: false, message: 'fields 格式错误，应为 JSON 数组' };
       }
     }
-    const msg = await endpoint.sendEmbed(channel_id, embedData);
+    const channel = await client.channels.fetch(channel_id);
+    if (!channel?.isTextBased() || !channel.send) {
+      throw new Error(`Channel ${channel_id} 不是文本频道`);
+    }
+    const msg = await channel.send({ embeds: [embedData] } as never);
     return { success: true, message_id: msg.id, message: 'Embed 已发送' };
   },
 });

package/lib/client.d.ts

@@ -0,0 +1,16 @@
+import type { DiscordRestClient } from './endpoint.js';
+import type { DiscordClientTransport } from './gateway.js';
+/** Exact Client variants produced by the Gateway and Interactions Endpoints. */
+export type DiscordClient = DiscordClientTransport | DiscordRestClient;
+export type DiscordClientEventMap = Record<string, unknown>;
+/** Narrow an adapter Client for Gateway-only SDK operations. */
+export declare function requireDiscordGatewayClient(client: DiscordClient): DiscordClientTransport;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly discord: {
+            readonly client: DiscordClient;
+            readonly events: DiscordClientEventMap;
+        };
+    }
+}
+export declare const discordClient: import("@zhin.js/adapter").EndpointClientToken<DiscordClient, DiscordClientEventMap>;

package/lib/client.js

@@ -0,0 +1,8 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+/** Narrow an adapter Client for Gateway-only SDK operations. */
+export function requireDiscordGatewayClient(client) {
+    if ('guilds' in client && 'channels' in client)
+        return client;
+    throw new Error('This Discord tool requires a Gateway Endpoint Client');
+}
+export const discordClient = defineEndpointClient('discord');

package/lib/discord-endpoint-commands.d.ts

@@ -1 +1 @@
-export declare const discordEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage>>>;
+export declare const discordEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage, string | undefined>>>;

package/lib/endpoint.d.ts

@@ -1,5 +1,5 @@
-import type { EndpointContentPort, EndpointControl, EndpointInstance, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+import { Endpoint } from 'zhin.js/adapter';
+import type { EndpointContentPort, EndpointControl, EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import { type MessageRef } from '@zhin.js/im-contract';
 import type { CapabilityId } from 'zhin.js';
@@ -8,18 +8,18 @@ import { type DiscordButtonInbound, type DiscordInboundMessage, type ResolvedDis
 export type { CreateDiscordClient, DiscordClientTransport, } from './gateway.js';
 export interface DiscordEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly config: ResolvedDiscordGatewayConfig;
     readonly createClient?: CreateDiscordClient;
     readonly fetch?: typeof globalThis.fetch;
 }
-export declare class DiscordGatewayEndpoint implements EndpointInstance {
+export declare class DiscordGatewayEndpoint extends Endpoint<DiscordClientTransport> {
     #private;
     readonly management: EndpointManagement;
     readonly control: EndpointControl;
     readonly content: EndpointContentPort;
     constructor(options: DiscordEndpointOptions);
+    /** The actual discord.js-compatible client used by this connection. */
+    get client(): DiscordClientTransport;
     start(): Promise<void>;
     open(): void;
     close(): void;
@@ -30,37 +30,27 @@ export declare class DiscordGatewayEndpoint implements EndpointInstance {
     admit(msg: DiscordInboundMessage): void;
     /** Test / internal: admit a button interaction when open. */
     admitButton(interaction: DiscordButtonInbound): void;
-    addRole(guildId: string, userId: string, roleId: string): Promise<boolean>;
-    removeRole(guildId: string, userId: string, roleId: string): Promise<boolean>;
-    getRoles(guildId: string): Promise<unknown[]>;
-    createThread(channelId: string, name: string, messageId?: string, autoArchiveDuration?: number): Promise<{
-        id: string;
-    }>;
-    addReaction(channelId: string, messageId: string, emoji: string): Promise<void>;
-    sendEmbed(channelId: string, embedData: Record<string, unknown>): Promise<{
-        id: string;
-    }>;
-    createForumPost(channelId: string, name: string, content: string, tags?: string[]): Promise<{
-        id: string;
-    }>;
-    kickMember(guildId: string, userId: string, reason?: string): Promise<boolean>;
-    banMember(guildId: string, userId: string, reason?: string): Promise<boolean>;
-    unbanMember(guildId: string, userId: string, reason?: string): Promise<boolean>;
-    timeoutMember(guildId: string, userId: string, duration?: number, reason?: string): Promise<boolean>;
-    setNickname(guildId: string, userId: string, nickname: string): Promise<boolean>;
-    getMembers(guildId: string, limit?: number): Promise<unknown[]>;
-    getGuildInfo(guildId: string): Promise<unknown>;
 }
 export interface DiscordInteractionsEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly config: ResolvedDiscordInteractionsConfig;
     readonly fetch?: typeof globalThis.fetch;
 }
-export declare class DiscordInteractionsEndpoint implements EndpointInstance {
+/** Minimal Discord REST client used when Gateway is intentionally disabled. */
+export declare class DiscordRestClient {
+    readonly token: string;
+    readonly fetch: typeof globalThis.fetch;
+    constructor(token: string, fetch?: typeof globalThis.fetch);
+    request<T = unknown>(method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE', path: string, body?: unknown): Promise<T>;
+    createMessage(channelId: string, body: unknown): Promise<{
+        id?: string;
+    }>;
+    deleteMessage(channelId: string, messageId: string): Promise<void>;
+}
+export declare class DiscordInteractionsEndpoint extends Endpoint<DiscordRestClient> {
     #private;
+    readonly client: DiscordRestClient;
     readonly control: EndpointControl;
     readonly content: EndpointContentPort;
     constructor(options: DiscordInteractionsEndpointOptions);
@@ -73,12 +63,10 @@ export declare class DiscordInteractionsEndpoint implements EndpointInstance {
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     recallMessage(message: MessageRef): Promise<void>;
     admit(msg: DiscordInboundMessage): void;
+    admitPlatform(event: Record<string, unknown>): void;
 }
 /**
  * DiscordGatewayEndpoint 的 EndpointManagement 语义端口（参照 qq 的工厂模式）。
  * 数据源为 discord.js SDK 缓存：guilds.cache / guild.channels.cache / guild.members。
  */
-export declare function createDiscordEndpointManagement(endpoint: {
-    getClient(): DiscordClientTransport;
-    getMembers(guildId: string): Promise<unknown[]>;
-}): EndpointManagement;
+export declare function createDiscordEndpointManagement(requireClient: () => DiscordClientTransport): EndpointManagement;