@zhin.js/adapter-discord 5.0.1 → 5.0.3

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @zhin.js/adapter-discord
 
+## 5.0.3
+
+### Patch Changes
+
+- cc5c94d: 约定式插件运行时迁移（breaking）：插件与适配器由 `usePlugin()` / `extends Adapter` 迁移为 `definePlugin` / `defineAdapter` + `plugin.ts` + 约定目录（`adapters/`、`commands/`、`components/`、`tools/` 等）。
+
+  - 新增约定式运行时包：`@zhin.js/plugin-runtime`、`@zhin.js/adapter`、`@zhin.js/runtime`、`@zhin.js/host-http`（首版 1.0.0 走 init-publish，不在本 changeset 内 bump）。
+  - 全部 20 个平台适配器改为约定式 `defineAdapter`，旧 `usePlugin` / `extends Adapter` / `segment-mapper` 生产入口已删除；onebot11 反向 WSS、onebot12 webhook/wss、milky sse/webhook/wss、satori webhook、kook webhook、qq webhook/middleware 等 slice 1 推迟的连接模式已补齐。
+  - 游戏 / 工具 / 服务插件同步迁移到约定目录结构。
+  - CLI 增加 plugin-runtime host installer（http/database/outbound/schedule/console 等）。
+
+  后续加固（同批）：
+
+  - CLI：`zhin runtime start --daemon`（pidfile/崩溃拉起/风暴保护），orphan watchdog 防僵尸进程；legacy `zhin dev` / `zhin start` 已移除（含 `zhin restart`），`zhin stop` 兼容新 daemon。
+  - 安全：builtin 工具统一走 `security/policy-facade.ts` 的 `runToolPolicies`（声明式策略表，deny 优先）；审计日志 close flush + 背压队列；`splitCompoundCommand` 引号感知、`extractCommandName` 去引号堵绕过。
+  - 日志：Logger 双堆栈修复、本地时区、`getLogger` 挂树（`setLevel` 递归生效）、第三方库（log4js/discord）桥接、启动人读总结。
+  - 结构：`plugins/games/shared` 迁为 `packages/game-kit`（`@zhin.js/game-kit`）；死目录 `plugins/adapters/common` 删除。
+  - 脚手架：`create-zhin-app` / `zhin new` / scaffold-wizard 生成物改为 Plugin Runtime 形态（minimal-bot 同构，新配置格式）。
+  - Console：endpoint.list 真实名称与 phase、schema:get-all 按 instanceKey 映射、db:\* 接 DatabaseHost。
+
+  注：按仓库发布惯例（见 1bb345dd2），本次 breaking 迁移统一使用 patch，避免 zhin.js 5.0 级联。
+
+- 447f3e2: 迁移缺口修复（legacy 功能对齐）：
+
+  - html 段出站规范化：经 `@zhin.js/html-renderer` 渲染为 image 段（sandbox 豁免、无渲染器时降级文本），修复真实平台 `[object Object]`。
+  - 群聊 @ 触发 AI：适配器入站标注 `metadata.mentioned`（icqq/qq/slack/onebot11/onebot12/napcat/milky/discord/telegram/kook/dingtalk/satori），`matchAiTrigger` 补齐 ignorePrefixes/respondToAt/respondToPrivate/keywords（默认值与 legacy 对齐）。
+  - im_transcripts 全量流水恢复写入（chat_history 工具可用）；群聊旁听上下文回迁。
+  - `ai.trigger.timeout/thinkingMessage/errorTemplate` 生效；masters/trusted 角色解析对齐 legacy。
+  - `Message.sender` 统一为用户 ID（onebot11/12、napcat、milky 原误传显示名）；quote_id 经 metadata 接入 AI 引用上下文。
+
+- Updated dependencies [16ec4e8]
+- Updated dependencies [cc5c94d]
+- Updated dependencies [447f3e2]
+  - @zhin.js/core@1.3.5
+  - @zhin.js/agent@1.0.4
+  - @zhin.js/host-http@1.0.1
+  - zhin.js@4.1.3
+  - @zhin.js/logger@1.0.75
+  - @zhin.js/plugin-runtime@1.0.1
+  - @zhin.js/adapter@1.0.1
+
+## 5.0.2
+
+### Patch Changes
+
+- 872c583: fix: 代码格式优化
+- Updated dependencies [872c583]
+- Updated dependencies [872c583]
+  - @zhin.js/agent@1.0.3
+  - @zhin.js/client@2.0.5
+  - @zhin.js/contract@1.0.3
+  - @zhin.js/host-api@2.0.5
+  - @zhin.js/host-router@2.0.3
+  - zhin.js@4.1.2
+
 ## 5.0.1
 
 ### Patch Changes

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({ target, payload })` → Discord channel message（text / media / embed / keyboard）
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
+- Interactions HTTP webhook 延期（需 `httpHostToken`）；配置 `connection: interactions` 会明确报错
 
 ## 安装
 
@@ -17,98 +17,73 @@ Zhin.js Discord 适配器，支持 Discord 机器人的消息收发和服务器
 pnpm add @zhin.js/adapter-discord discord.js
 ```
 
-Interactions 模式需同时启用 `@zhin.js/host-router`。
+## Plugin Runtime
 
-## 配置
+- `@zhin.js/adapter` — 约定式 `adapters/discord.ts`（`defineAdapter`）
+- `@zhin.js/core` — `messageGatewayToken` 入站/出站
+- `@zhin.js/plugin-runtime` — `plugin.ts`（`definePlugin`）
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
+- **无需** `@zhin.js/host-http` / `@zhin.js/host-router`（Gateway 路径）
 
-所有 Endpoint 使用 **同一 context：`discord`**，通过 **`connection`** 区分连接方式。
+入站：`gateway.receive({ adapter, target: channelId, content: text, sender, metadata })`  
+出站：`send({ target, payload })` → discord.js channel.send
 
-### Gateway（connection: gateway，默认）
+### 平台权限（platform permit）
 
-```yaml
-plugins:
-  - "@zhin.js/adapter-discord"
+- 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`。
 
-endpoints:
-  - context: discord
-    connection: gateway
-    name: my-discord-bot
-    token: "${DISCORD_BOT_TOKEN}"
-    # 可选: intents, enableSlashCommands, defaultActivity, slashCommands
-```
+## 前置条件
+
+| 要求 | 说明 |
+|------|------|
+| **Bot Token** | [Discord Developer Portal](https://discord.com/developers/applications) 创建应用并获取 Token |
+| **MESSAGE CONTENT INTENT** | 需开启才能读取消息正文 |
+| **Gateway（默认）** | 本地/生产均可；discord.js 连接 Gateway，无需公网 HTTPS |
+| **host-http** | Gateway **不需要**；Interactions webhook 延期至下一棒 |
 
-### Interactions（connection: interactions）
+必填字段：`token`。
+
+## 最小配置
 
 ```yaml
+# zhin.config.yml（Plugin Runtime）
 plugins:
-  - "@zhin.js/host-router"
-  - "@zhin.js/adapter-discord"
-
-endpoints:
-  - context: discord
-    connection: interactions
+  discord:
     name: my-discord-bot
-    token: "${DISCORD_BOT_TOKEN}"
-    applicationId: "${DISCORD_APP_ID}"
-    publicKey: "${DISCORD_PUBLIC_KEY}"
-    interactionsPath: "/discord/interactions"
+    token: ${DISCORD_BOT_TOKEN}
+    # connection: gateway   # 默认
 ```
 
-未写 `connection` 时默认为 `gateway`。
-
-### 如何选择 connection
-
-| 模式 | 适用场景 | 依赖 |
-|------|----------|------|
-| **gateway** | 常规 Bot：读消息、群管、Gateway 事件 | Endpoint Token + Intents |
-| **interactions** | 仅需斜杠命令 / 交互组件，或 Gateway 与 HTTP 并存 | `@zhin.js/host-router` + Application ID + Public Key |
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-discord`（`instanceKey: discord`）。
 
-Gateway 需开启 **MESSAGE CONTENT INTENT**；Interactions 须在 Developer Portal 配置 **Interactions Endpoint URL**（指向 `interactionsPath`）。
+## 环境变量
 
-## 使用示例
+| 变量 | 说明 |
+|------|------|
+| `DISCORD_BOT_TOKEN` | Bot Token |
+| `DISCORD_BOT_NAME` | 可选，默认 endpoint 名 |
 
-### 注册命令
+## Interactions（HTTP）
 
-```typescript
-import { usePlugin, MessageCommand } from 'zhin.js'
-
-const { addCommand } = usePlugin()
-
-addCommand(
-  new MessageCommand('ping')
-    .desc('测试延迟')
-    .action(() => 'Pong!')
-)
-```
-
-### 消息中间件
-
-```typescript
-import { usePlugin } from 'zhin.js'
-
-const { root } = usePlugin()
-
-root.addMiddleware(async (message, next) => {
-  if (message.$adapter === 'discord') {
-    console.log('Discord 消息:', message.$content)
-  }
-  await next()
-})
-```
+`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. 创建应用并获取 Endpoint Token
-3. 开启 **MESSAGE CONTENT INTENT**（需要读取消息内容）
-4. 通过 OAuth2 URL 邀请 Endpoint 加入服务器
-5. Interactions 模式还需配置 Interactions Endpoint URL
+2. 创建应用并获取 Bot Token
+3. 开启 **MESSAGE CONTENT INTENT**
+4. 通过 OAuth2 URL 邀请 Bot 加入服务器
 
 ## 许可证
 

package/adapters/discord.ts

@@ -0,0 +1,46 @@
+/**
+ * Convention entry: discover `adapters/discord.ts` → defineAdapter.
+ */
+import { defineAdapter } from '@zhin.js/adapter';
+import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { httpHostToken } from '@zhin.js/host-http';
+import {
+  DiscordGatewayEndpoint,
+  DiscordInteractionsEndpoint,
+} from '../src/endpoint.js';
+import {
+  resolveDiscordConfig,
+  type DiscordAdapterConfig,
+} from '../src/protocol.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'],
+  create(context) {
+    const config = resolveDiscordConfig(context.config);
+    const gateway = context.use(messageGatewayToken);
+    if (config.connection === 'interactions') {
+      return new DiscordInteractionsEndpoint({
+        id: context.id,
+        gateway,
+        http: context.use(httpHostToken),
+        config,
+      });
+    }
+    return new DiscordGatewayEndpoint({
+      id: context.id,
+      gateway,
+      config,
+    });
+  },
+});

package/agent/tools/add_role.ts

@@ -0,0 +1,24 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+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 }>({
+  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'],
+  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>;
+    };
+    const success = await endpoint.addRole(guild_id, user_id, role_id);
+    return { success, message: success ? `已给用户 ${user_id} 添加角色` : '操作失败' };
+  },
+});

package/agent/tools/create_thread.ts

@@ -0,0 +1,25 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+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 }>({
+  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'],
+  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);
+    return { success: true, thread_id: thread.id, message: `帖子 "${name}" 已创建` };
+  },
+});

package/agent/tools/forum_post.ts

@@ -0,0 +1,24 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getDiscordAgentDeps } from '../../src/discord-agent-deps.js';
+
+export default defineAgentTool<{ endpoint_id: string; 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'],
+  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 }>;
+    };
+    const tagList = tags ? tags.split(',').map((t: string) => t.trim()) : undefined;
+    const thread = await endpoint.createForumPost(channel_id, name, content, tagList);
+    return { success: true, thread_id: thread.id, message: `论坛帖 "${name}" 已创建` };
+  },
+});

package/agent/tools/list_roles.ts

@@ -0,0 +1,22 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { platformPermit } from '../../src/platform-permit.js';
+import { getDiscordAgentDeps } from '../../src/discord-agent-deps.js';
+
+export default defineAgentTool<{ endpoint_id: string; guild_id: string }>({
+  description: '获取 Discord 服务器角色列表',
+  inputSchema: z.object({
+    endpoint_id: z.string().describe('Endpoint 名称'),
+    guild_id: z.string().describe('服务器 ID'),
+  }),
+  platforms: ['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);
+    return { roles, count: roles.length };
+  },
+});

package/agent/tools/react.ts

@@ -0,0 +1,22 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getDiscordAgentDeps } from '../../src/discord-agent-deps.js';
+
+export default defineAgentTool<{ endpoint_id: string; 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'],
+  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);
+    return { success: true, message: `已添加反应 ${emoji}` };
+  },
+});

package/agent/tools/remove_role.ts

@@ -0,0 +1,24 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+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 }>({
+  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'],
+  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>;
+    };
+    const success = await endpoint.removeRole(guild_id, user_id, role_id);
+    return { success, message: success ? `已移除用户 ${user_id} 的角色` : '操作失败' };
+  },
+});

package/agent/tools/send_embed.ts

@@ -0,0 +1,37 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getDiscordAgentDeps } from '../../src/discord-agent-deps.js';
+
+export default defineAgentTool<{ endpoint_id: string; 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 描述'),
+    color: z.number().optional().describe('颜色值（十进制，如 0x00ff00 = 65280）'),
+    url: z.string().optional().describe('标题链接（可选）'),
+    fields: z.string().optional().describe('字段，JSON 格式: [{"name":"k","value":"v","inline":false}]'),
+  }),
+  platforms: ['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 }>;
+    };
+    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 msg = await endpoint.sendEmbed(channel_id, embedData);
+    return { success: true, message_id: msg.id, message: 'Embed 已发送' };
+  },
+});

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

@@ -0,0 +1,35 @@
+/**
+ * Agent tool deps for discord.
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
+ */
+export interface DiscordAgentEndpoint {
+    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 DiscordAgentDeps {
+    getEndpoint: (endpointId: string) => DiscordAgentEndpoint;
+    /** Alias kept for existing agent/tools that call getGatewayEndpoint. */
+    getGatewayEndpoint: (endpointId: string) => DiscordAgentEndpoint;
+}
+export declare function registerDiscordAgentEndpoint(endpointId: 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

@@ -0,0 +1,32 @@
+/**
+ * Agent tool deps for discord.
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
+ */
+const endpoints = new Map();
+let override = null;
+export function registerDiscordAgentEndpoint(endpointId, endpoint) {
+    endpoints.set(endpointId, endpoint);
+    return () => {
+        if (endpoints.get(endpointId) === endpoint) {
+            endpoints.delete(endpointId);
+        }
+    };
+}
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export function setDiscordAgentDeps(deps) {
+    override = deps;
+}
+function lookup(endpointId) {
+    const registered = endpoints.get(endpointId);
+    if (!registered)
+        throw new Error(`Endpoint ${endpointId} 不存在`);
+    return registered;
+}
+export function getDiscordAgentDeps() {
+    if (override)
+        return override;
+    return {
+        getEndpoint: lookup,
+        getGatewayEndpoint: lookup,
+    };
+}