@zhin.js/adapter-discord 1.0.87 → 1.1.0

package/README.md

@@ -1,15 +1,15 @@
 # @zhin.js/adapter-discord
 
-Zhin.js Discord 适配器，支持 Discord 机器人的消息收发和服务器管理。
+Zhin.js Discord 适配器（Plugin Runtime），默认通过 **Gateway WebSocket**（discord.js）收发消息（无需 host-router / host-http）。
 
-## 功能特性
+## 功能
 
-- 📦 **单一适配器**：`context: discord`，通过 `connection` 选择连接方式
-- 🌐 **Gateway**（`connection: gateway`）：WebSocket 网关，支持群管、消息、斜杠命令等
-- 📮 **Interactions**（`connection: interactions`）：HTTP 交互端点，斜杠命令等
-- 可配置 Intents 和默认活动状态
-- 服务器管理 AI 工具（仅 Gateway 支持）
-- 基于 discord.js 库
+- Gateway WebSocket 入站（默认；无需公网 HTTPS / host）
+- 解析 text / mention / attachment / embed / sticker / button
+- 支持私聊、群组与服务器频道
+- 出站 `send({ conversation, payload })` → Discord channel message（Markdown content / media / embed / keyboard）
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
+- Interactions HTTP webhook 延期（需 `httpHostToken`）；配置 `connection: interactions` 会明确报错
 
 ## 安装
 
@@ -17,89 +17,83 @@ Zhin.js Discord 适配器，支持 Discord 机器人的消息收发和服务器
 pnpm add @zhin.js/adapter-discord discord.js
 ```
 
-Interactions 模式需同时启用 `@zhin.js/http`。
+## Plugin Runtime
 
-## 配置
+- `@zhin.js/adapter` — 约定式 `adapters/discord.ts`（`defineAdapter`）
+- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
+- `zhin.js` — `plugin.ts`（`definePlugin`）
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
+- **无需** `@zhin.js/host-http` / `@zhin.js/host-router`（Gateway 路径）
 
-所有 Bot 使用 **同一 context：`discord`**，通过 **`connection`** 区分连接方式。
+入站：`gateway.receive({ conversation, message, content: text, sender, metadata })`（`conversation` 为 `ConversationRef`，guild 频道带 `parent` guild 容器）  
+出站：`send({ conversation, payload })` → discord.js channel.send
 
-### Gateway（connection: gateway，默认）
+### 平台权限（platform permit）
 
-```yaml
-plugins:
-  - "@zhin.js/adapter-discord"
-
-bots:
-  - context: discord
-    connection: gateway
-    name: my-discord-bot
-    token: "${DISCORD_BOT_TOKEN}"
-    # 可选: intents, enableSlashCommands, defaultActivity, slashCommands
-```
-
-### Interactions（connection: interactions）
-
-```yaml
-plugins:
-  - "@zhin.js/http"
-  - "@zhin.js/adapter-discord"
-
-bots:
-  - context: discord
-    connection: interactions
-    name: my-discord-bot
-    token: "${DISCORD_BOT_TOKEN}"
-    applicationId: "${DISCORD_APP_ID}"
-    publicKey: "${DISCORD_PUBLIC_KEY}"
-    interactionsPath: "/discord/interactions"
-```
+- sender role 已恢复：Gateway 入站 `metadata.role` / `metadata.permissions`（来自 member 权限位与 guild owner 判定，见 `src/gateway.ts` `resolveSenderRole`）。
+- `plugin.ts` 在 generation setup 注册 checker，并在 dispose 注销；Plugin Runtime CapabilityIngress 与 ToolSystem 统一经 Core `canAccessTool()` 消费 `permissions`。
 
-未写 `connection` 时默认为 `gateway`。
+## 前置条件
 
-## 使用示例
+| 要求 | 说明 |
+|------|------|
+| **Bot Token** | [Discord Developer Portal](https://discord.com/developers/applications) 创建应用并获取 Token |
+| **MESSAGE CONTENT INTENT** | 需开启才能读取消息正文 |
+| **Gateway（默认）** | 本地/生产均可；discord.js 连接 Gateway，无需公网 HTTPS |
+| **host-http** | Gateway **不需要**；Interactions webhook 延期至下一棒 |
 
-### 注册命令
+必填字段（`endpoints[i]`）：`name`、`token`。
 
-```typescript
-import { usePlugin, MessageCommand } from 'zhin.js'
+## 最小配置
 
-const { addCommand } = usePlugin()
-
-addCommand(
-  new MessageCommand('ping')
-    .desc('测试延迟')
-    .action(() => 'Pong!')
-)
+```yaml
+# zhin.config.yml（Plugin Runtime）
+plugins:
+  discord:
+    # connection: gateway   # 默认
+    endpoints:
+      - name: my-discord-bot
+        token: ${DISCORD_BOT_TOKEN}
 ```
 
-### 消息中间件
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-discord`（`instanceKey: discord`）。
 
-```typescript
-import { usePlugin } from 'zhin.js'
+## 环境变量
 
-const { addMiddleware } = usePlugin()
+| 变量 | 说明 |
+|------|------|
+| `DISCORD_BOT_TOKEN` | Bot Token |
+| `DISCORD_BOT_NAME` | 可选，默认 endpoint 名 |
 
-addMiddleware(async (message, next) => {
-  if (message.$adapter === 'discord') {
-    console.log('Discord 消息:', message.$content)
-  }
-  await next()
-})
-```
+## Interactions（HTTP）
+
+`connection: interactions` 经 `httpHostToken` 注册 POST 路由（默认 `/discord/interactions`），Ed25519 验签后处理 PING 与 slash command；出站走 Discord REST `channels/.../messages`。需配置 `applicationId` 与 `publicKey`。
 
 ## AI 工具（Skill）
 
-适配器内置 Discord 服务器管理 Skill，工具供 AI 调用。
+| 类别 | 路径 |
+|------|------|
+| Permit 词汇 | `agent/PERMITS.md` |
+| 平台工具（7 个） | `agent/tools/`（`discord_*`：角色、Embed、反应等） |
+| 技能说明 | `agent/skills/discord.md` |
 
-> 工具使用 Discord 的 Snowflake ID 格式标识 `guild_id`、`user_id`、`channel_id`。
+工具使用 Discord Snowflake ID 标识 `guild_id`、`user_id`、`channel_id`。
 
 ## Discord 开发者配置
 
 1. 前往 [Discord Developer Portal](https://discord.com/developers/applications)
 2. 创建应用并获取 Bot Token
-3. 开启 **MESSAGE CONTENT INTENT**（需要读取消息内容）
+3. 开启 **MESSAGE CONTENT INTENT**
 4. 通过 OAuth2 URL 邀请 Bot 加入服务器
-5. Interactions 模式还需配置 Interactions Endpoint URL
+
+## 故障排查
+
+| 现象 | 排查 |
+| --- | --- |
+| Gateway 反复断线 | 检查 Token、网络代理、Gateway Intents 与应用后台配置 |
+| 能上线但收不到正文 | 启用 Message Content Intent，并给 Bot 频道读取权限 |
+| 能收不能发 | 检查 Send Messages、Embed Links 与附件权限 |
+| `connection: interactions` 启动失败 | 当前生产路径使用 Gateway；改回 `gateway` |
 
 ## 许可证
 

package/adapters/discord.js

@@ -0,0 +1,41 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/discord.ts` → defineAdapter.
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { DiscordGatewayEndpoint, DiscordInteractionsEndpoint, } from "../lib/endpoint.js";
+import { resolveDiscordConfig, } from "../lib/protocol.js";
+import { discordRuntimeStateToken } from "../lib/discord-runtime-state.js";
+export { DiscordGatewayEndpoint, DiscordInteractionsEndpoint, } from "../lib/endpoint.js";
+export default defineAdapter({
+    capabilities: ['inbound', 'outbound'],
+    operations: (context) => context.config.connection === 'interactions'
+        ? ['recall']
+        : ['recall', 'reaction'],
+    // 媒体 url 直发或由 AttachmentBuilder 物化本地文件上传；message components 原生按钮承载交互段。
+    segments: {
+        outboundMedia: ['url', 'upload'],
+        interactive: 'native',
+        markdown: 'native',
+    },
+    create(context) {
+        const config = resolveDiscordConfig(context.config);
+        // 注册到插件运行时状态（discord.endpoint list 的"运行中"数据源）
+        context.use(discordRuntimeStateToken).endpoints.set(config.id, {
+            id: config.id,
+            mode: config.connection,
+        });
+        if (config.connection === 'interactions') {
+            return new DiscordInteractionsEndpoint({
+                id: context.id,
+                http: context.use(httpHostToken),
+                config,
+            });
+        }
+        return new DiscordGatewayEndpoint({
+            id: context.id,
+            config,
+        });
+    },
+});

package/adapters/discord.ts

@@ -0,0 +1,57 @@
+/**
+ * Convention entry: discover `adapters/discord.ts` → defineAdapter.
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import {
+  DiscordGatewayEndpoint,
+  DiscordInteractionsEndpoint,
+} from '../src/endpoint.js';
+import {
+  resolveDiscordConfig,
+  type DiscordAdapterConfig,
+} from '../src/protocol.js';
+import { discordRuntimeStateToken } from '../src/discord-runtime-state.js';
+
+export {
+  DiscordGatewayEndpoint,
+  DiscordInteractionsEndpoint,
+} from '../src/endpoint.js';
+export type {
+  CreateDiscordClient,
+  DiscordClientTransport,
+  DiscordEndpointOptions,
+  DiscordInteractionsEndpointOptions,
+} from '../src/endpoint.js';
+
+export default defineAdapter<DiscordAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  operations: (context) => context.config.connection === 'interactions'
+    ? ['recall']
+    : ['recall', 'reaction'],
+  // 媒体 url 直发或由 AttachmentBuilder 物化本地文件上传；message components 原生按钮承载交互段。
+  segments: {
+    outboundMedia: ['url', 'upload'],
+    interactive: 'native',
+    markdown: 'native',
+  },
+  create(context) {
+    const config = resolveDiscordConfig(context.config);
+    // 注册到插件运行时状态（discord.endpoint list 的"运行中"数据源）
+    context.use(discordRuntimeStateToken).endpoints.set(config.id, {
+      id: config.id,
+      mode: config.connection,
+    });
+    if (config.connection === 'interactions') {
+      return new DiscordInteractionsEndpoint({
+        id: context.id,
+        http: context.use(httpHostToken),
+        config,
+      });
+    }
+    return new DiscordGatewayEndpoint({
+      id: context.id,
+      config,
+    });
+  },
+});

package/agent/PERMITS.md

@@ -0,0 +1,25 @@
+# Discord Platform Permits
+
+## 入站字段
+
+Guild 频道消息从 `msg.member.permissions` bitfield 解析：
+
+| 字段 | 取值 |
+|------|------|
+| `$sender.role` | `owner`（`guild.ownerId === author.id`）· `member` |
+| `$sender.permissions` | `guild_owner` · `ADMINISTRATOR` · `MANAGE_ROLES` · `MODERATE_MEMBERS` · `MANAGE_CHANNELS` · … |
+
+需 `GuildMembers` intent；缺失时 checker 保守拒绝。
+
+## Permit 词汇表
+
+| `platform(discord,…)` | 含义 |
+|-----------------------|------|
+| `guild_owner` | 服务器主 |
+| `moderate_members` | 踢人/禁言 |
+| `manage_roles` | 管理身份组 |
+| `manage_channels` | 管理频道/线程 |
+
+## 工厂映射
+
+`scene_admin` → `moderate_members` · `scene_owner` → `guild_owner`

package/{skills/discord/SKILL.md → agent/skills/discord.md}

@@ -101,4 +101,4 @@ Discord 中几乎所有权限都由角色控制。用户说「给他管理员」
 1. **Discord 昵称是服务器级别的**，一个用户在不同服务器可以有不同昵称。
 2. **角色操作需要角色 ID**，不能用角色名直接操作。先 `list_roles` 查。
 3. **Embed 消息不是普通文本**，它有固定结构（title/description/color/fields），用于发送富文本格式的消息。
-4. **Bot 只能操作低于自身角色的成员**。如果目标用户的最高角色高于 Bot 的角色，操作会失败。
+4. **Bot 只能操作低于自身角色的成员**。如果目标用户的最高角色高于 Endpoint 的角色，操作会失败。

package/agent/tools/add_role.ts

@@ -0,0 +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';
+
+export default defineAgentTool<{ guild_id: string; user_id: string; role_id: string }>({
+  description: '给成员添加 Discord 角色',
+  inputSchema: z.object({
+    guild_id: z.string().describe('服务器 ID'),
+    user_id: z.string().describe('用户 ID'),
+    role_id: z.string().describe('角色 ID'),
+  }),
+  adapter: 'discord',
+  tags: ['discord'],
+  permissions: [platformPermit('manage_roles')],
+  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> };
+    };
+    await member.roles.add(role_id);
+    const success = true;
+    return { success, message: success ? `已给用户 ${user_id} 添加角色` : '操作失败' };
+  },
+});

package/agent/tools/create_thread.ts

@@ -0,0 +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';
+
+export default defineAgentTool<{ channel_id: string; name: string; message_id?: string; auto_archive_duration?: number }>({
+  description: '在 Discord 频道中创建帖子/子线程',
+  inputSchema: z.object({
+    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）'),
+  }),
+  adapter: 'discord',
+  tags: ['discord'],
+  permissions: [platformPermit('manage_channels')],
+  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

@@ -0,0 +1,33 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { requireDiscordGatewayClient } from '../../src/client.js';
+import { ChannelType } from 'discord.js';
+
+export default defineAgentTool<{ channel_id: string; name: string; content: string; tags?: string }>({
+  description: '在 Discord 论坛频道中创建帖子',
+  inputSchema: z.object({
+    channel_id: z.string().describe('论坛频道 ID'),
+    name: z.string().describe('帖子标题'),
+    content: z.string().describe('帖子内容'),
+    tags: z.string().optional().describe('标签名，逗号分隔（可选）'),
+  }),
+  adapter: 'discord',
+  tags: ['discord'],
+  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 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

@@ -0,0 +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';
+
+export default defineAgentTool<{ guild_id: string }>({
+  description: '获取 Discord 服务器角色列表',
+  inputSchema: z.object({
+    guild_id: z.string().describe('服务器 ID'),
+  }),
+  adapter: 'discord',
+  tags: ['discord'],
+  permissions: [platformPermit('manage_roles')],
+  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

@@ -0,0 +1,24 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { requireDiscordGatewayClient } from '../../src/client.js';
+
+export default defineAgentTool<{ channel_id: string; message_id: string; emoji: string }>({
+  description: '对 Discord 消息添加表情反应',
+  inputSchema: z.object({
+    channel_id: z.string().describe('频道 ID'),
+    message_id: z.string().describe('消息 ID'),
+    emoji: z.string().describe('表情（Unicode 表情或自定义表情如 <:name:id>）'),
+  }),
+  adapter: 'discord',
+  tags: ['discord'],
+  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

@@ -0,0 +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';
+
+export default defineAgentTool<{ guild_id: string; user_id: string; role_id: string }>({
+  description: '移除成员的 Discord 角色',
+  inputSchema: z.object({
+    guild_id: z.string().describe('服务器 ID'),
+    user_id: z.string().describe('用户 ID'),
+    role_id: z.string().describe('角色 ID'),
+  }),
+  adapter: 'discord',
+  tags: ['discord'],
+  permissions: [platformPermit('manage_roles')],
+  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> };
+    };
+    await member.roles.remove(role_id);
+    const success = true;
+    return { success, message: success ? `已移除用户 ${user_id} 的角色` : '操作失败' };
+  },
+});

package/agent/tools/send_embed.ts

@@ -0,0 +1,38 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { requireDiscordGatewayClient } from '../../src/client.js';
+
+export default defineAgentTool<{ channel_id: string; title?: string; description?: string; color?: number; url?: string; fields?: string }>({
+  description: '发送 Discord 富文本嵌入消息（Embed）',
+  inputSchema: z.object({
+    channel_id: z.string().describe('频道 ID'),
+    title: z.string().optional().describe('Embed 标题'),
+    description: z.string().optional().describe('Embed 描述'),
+    color: z.number().optional().describe('颜色值（十进制，如 0x00ff00 = 65280）'),
+    url: z.string().optional().describe('标题链接（可选）'),
+    fields: z.string().optional().describe('字段，JSON 格式: [{"name":"k","value":"v","inline":false}]'),
+  }),
+  adapter: 'discord',
+  tags: ['discord'],
+  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;
+    if (color) embedData.color = color;
+    if (url) embedData.url = url;
+    if (fields) {
+      try {
+        embedData.fields = JSON.parse(fields);
+      } catch {
+        return { success: false, message: 'fields 格式错误，应为 JSON 数组' };
+      }
+    }
+    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/commands/endpoint/add/[id].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { discordEndpointCommands } from "../../../lib/discord-endpoint-commands.js";
+export default discordEndpointCommands.add;

package/commands/endpoint/add/[id].ts

@@ -0,0 +1,3 @@
+import { discordEndpointCommands } from '../../../src/discord-endpoint-commands.js';
+
+export default discordEndpointCommands.add;

package/commands/endpoint/list.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { discordEndpointCommands } from "../../lib/discord-endpoint-commands.js";
+export default discordEndpointCommands.list;

package/commands/endpoint/list.ts

@@ -0,0 +1,3 @@
+import { discordEndpointCommands } from '../../src/discord-endpoint-commands.js';
+
+export default discordEndpointCommands.list;

package/commands/endpoint/remove/[id].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { discordEndpointCommands } from "../../../lib/discord-endpoint-commands.js";
+export default discordEndpointCommands.remove;

package/commands/endpoint/remove/[id].ts

@@ -0,0 +1,3 @@
+import { discordEndpointCommands } from '../../../src/discord-endpoint-commands.js';
+
+export default discordEndpointCommands.remove;

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

@@ -0,0 +1 @@
+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/discord-endpoint-commands.js

@@ -0,0 +1,18 @@
+/**
+ * `discord.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ * 注：applicationId / publicKey 为顶层共享字段（slash commands / interactions 用），
+ * endpoints[i] 仅需 name + token（见 schema.json），故 add 只录入 token。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { discordRuntimeStateToken } from './discord-runtime-state.js';
+export const discordEndpointCommands = createEndpointCommands({
+    adapterKey: 'discord',
+    adapterDisplayName: 'Discord',
+    fields: [
+        { key: 'token', required: true, env: true, description: 'Discord bot token' },
+    ],
+    running: (use) => use(discordRuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => `token: ${String(entry.token)}`,
+}, defineCommand);

package/lib/discord-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare const discordRuntimeStateToken: import("zhin.js").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/discord-runtime-state.js

@@ -0,0 +1,6 @@
+/**
+ * Discord 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `discord.endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
+export const discordRuntimeStateToken = defineEndpointRuntimeStateToken('discord');