@zhin.js/adapter-discord 1.0.87 → 1.1.2

package/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/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,82 @@ Zhin.js Discord 适配器，支持 Discord 机器人的消息收发和服务器
 pnpm add @zhin.js/adapter-discord discord.js
 ```
 
-Interactions 模式需同时启用 `@zhin.js/http`。
+## Plugin Runtime
 
-## 配置
+- `@zhin.js/adapter` — 约定式 `adapters/discord/index.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]`）：`id`、`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:
+      - id: 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` | YAML 示例中 `token` 引用的 Bot Token |
 
-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 词汇 | `PERMITS.md` |
+| 平台工具（7 个） | `agents/discord/skills/discord/tools/`（Skill 激活后披露 `discord_*`：角色、Embed、反应等） |
+| 技能说明 | `agents/discord/skills/discord/SKILL.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/index.js

@@ -0,0 +1,41 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/discord/index.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/index.ts

@@ -0,0 +1,57 @@
+/**
+ * Convention entry: discover `adapters/discord/index.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 DiscordEndpointConfig,
+} 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<DiscordEndpointConfig>({
+  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/agents/discord/agent.json

@@ -0,0 +1,20 @@
+{
+  "name": "DISCORD Platform Agent",
+  "version": "1.0.0",
+  "description": "Handles discord platform-specific operations and progressively loads only the required platform Skill.",
+  "trigger_rules": {
+    "file_patterns": [],
+    "keywords": [
+      "discord",
+      "adapter:discord"
+    ]
+  },
+  "entry_points": [
+    "system.md",
+    "boundaries.md",
+    "conventions.md"
+  ],
+  "platforms": [
+    "discord"
+  ]
+}

package/agents/discord/boundaries.md

@@ -0,0 +1,3 @@
+# Boundaries
+
+Operate only on the active discord endpoint and authenticated conversation context. Respect every Tool permission and approval policy. Do not infer identifiers, roles, or authorization from display names.

package/agents/discord/conventions.md

@@ -0,0 +1,3 @@
+# Conventions
+
+Use stable platform identifiers from the current turn or directory queries. Load one task-specific Skill at a time, and use the unified reply and outbound message path.

package/agents/discord/skills/discord/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: discord
+platforms: [discord]
+description: Discord 角色、线程、论坛帖子、反应和 Embed 操作能力。
+keywords: [discord, role, thread, forum, reaction, embed]
+tags: [adapter, community]
+tools:
+  - add_role
+  - remove_role
+  - list_roles
+  - create_thread
+  - react
+  - send_embed
+  - forum_post
+---
+
+# Discord
+
+按“先查询、后修改”执行：授予或移除角色前先用 `list_roles` 找到角色 ID；创建线程或论坛帖子时使用当前频道上下文；发送结构化内容时使用 `send_embed`；表情回应使用 `react`。
+
+当前 Agent Tool 不提供踢人、封禁、禁言、改昵称或成员列表操作，不要声称已经执行这些动作。

package/agents/discord/skills/discord/tools/add_role/index.js

@@ -0,0 +1,24 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    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: [platformPermission('discord', 'manage_roles')],
+    async execute({ guild_id, user_id, role_id }, context) {
+        const client = requireDiscordGatewayClient(context.$client);
+        const guild = await client.guilds.fetch(guild_id);
+        const member = await guild.members.fetch(user_id);
+        await member.roles.add(role_id);
+        const success = true;
+        return { success, message: success ? `已给用户 ${user_id} 添加角色` : '操作失败' };
+    },
+});

package/agents/discord/skills/discord/tools/add_role/index.ts

@@ -0,0 +1,26 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
+import { platformPermission } from '@zhin.js/permission';
+
+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: [platformPermission('discord', '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/agents/discord/skills/discord/tools/create_thread/index.js

@@ -0,0 +1,29 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    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: [platformPermission('discord', 'manage_channels')],
+    async execute({ channel_id, name, message_id, auto_archive_duration }, 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/agents/discord/skills/discord/tools/create_thread/index.ts

@@ -0,0 +1,28 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
+import { platformPermission } from '@zhin.js/permission';
+
+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: [platformPermission('discord', '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/agents/discord/skills/discord/tools/forum_post/index.js

@@ -0,0 +1,33 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
+import { ChannelType } from 'discord.js';
+export default defineAgentTool({
+    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 }, context) {
+        const client = requireDiscordGatewayClient(context.$client);
+        const tagList = tags ? tags.split(',').map((t) => 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/agents/discord/skills/discord/tools/forum_post/index.ts

@@ -0,0 +1,33 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
+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/agents/discord/skills/discord/tools/list_roles/index.js

@@ -0,0 +1,28 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    description: '获取 Discord 服务器角色列表',
+    inputSchema: z.object({
+        guild_id: z.string().describe('服务器 ID'),
+    }),
+    adapter: 'discord',
+    tags: ['discord'],
+    permissions: [platformPermission('discord', 'manage_roles')],
+    async execute({ guild_id }, context) {
+        const client = requireDiscordGatewayClient(context.$client);
+        const guild = await client.guilds.fetch(guild_id);
+        await guild.roles.fetch();
+        const cache = guild.roles.cache;
+        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/agents/discord/skills/discord/tools/list_roles/index.ts

@@ -0,0 +1,34 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
+import { platformPermission } from '@zhin.js/permission';
+
+export default defineAgentTool<{ guild_id: string }>({
+  description: '获取 Discord 服务器角色列表',
+  inputSchema: z.object({
+    guild_id: z.string().describe('服务器 ID'),
+  }),
+  adapter: 'discord',
+  tags: ['discord'],
+  permissions: [platformPermission('discord', '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/agents/discord/skills/discord/tools/react/index.js

@@ -0,0 +1,24 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
+export default defineAgentTool({
+    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 }, 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/agents/discord/skills/discord/tools/react/index.ts

@@ -0,0 +1,24 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { requireDiscordGatewayClient } from '@zhin.js/adapter-discord';
+
+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}` };
+  },
+});