文档同步
本页由 plugins/adapters/discord/README.md 自动生成。请修改包内 README 后运行 pnpm sync:adapter-docs。
@zhin.js/adapter-discord
Zhin.js Discord 适配器(Plugin Runtime),默认通过 Gateway WebSocket(discord.js)收发消息(无需 host-router / host-http)。
功能
- Gateway WebSocket 入站(默认;无需公网 HTTPS / host)
- 解析 text / mention / attachment / embed / sticker / button
- 支持私聊、群组与服务器频道
listChannels会过滤带CHANNEL_OBFUSCATED(1 << 17)的混淆频道:自 2026-11-16 起,机器人缺少VIEW_CHANNEL时 Gateway 仍会下发这些频道(名字常为___hidden___),HTTP 频道列表则不会返回它们。- 出站
send({ conversation, payload })→ Discord channel message(Markdown content / media / embed / keyboard) - 约定式
defineAdapter/definePlugin(无需usePlugin) - Interactions HTTP webhook(需
httpHostToken),支持验签、PING 与 slash command
安装
pnpm add @zhin.js/adapter-discord discord.jsPlugin Runtime
@zhin.js/adapter— 约定式adapters/discord/index.ts(defineAdapter)@zhin.js/core—endpoint[endpointSpec].events入站、outboundMessageToken出站zhin.js—plugin.ts(definePlugin)- 配置经插件
schema.json落到顶层<instanceKey> - 无需
@zhin.js/host-http/@zhin.js/host-router(Gateway 路径)
入站:endpoint[endpointSpec].events.emit('message.receive', { conversation, message, content: text, sender, metadata })(conversation 为 ConversationRef,guild 频道带 parent guild 容器)
出站:send({ conversation, payload }) → discord.js channel.send
平台权限(platform permit)
- 成员身份:服务器频道消息上报
sender.platform(见下文「成员身份」);metadata.role/metadata.permissions仅为兼容保留。 plugin.ts在 generation setup 注册 checker,并在 dispose 注销;Plugin Runtime CapabilityIngress 与 ToolSystem 统一经 CorecanAccessTool()消费permissions。
前置条件
| 要求 | 说明 |
|---|---|
| Bot Token | Discord Developer Portal 创建应用并获取 Token |
| MESSAGE CONTENT INTENT | 需开启才能读取消息正文 |
| Gateway(默认) | 本地/生产均可;discord.js 连接 Gateway,无需公网 HTTPS |
| host-http | Gateway 不需要;Interactions webhook 需要 |
必填字段(endpoints[i]):id、token。
最小配置
configVersion: 2
# zhin.config.yml(Plugin Runtime)
plugins:
discord: "@zhin.js/adapter-discord"
discord:
# connection: gateway # 默认
endpoints:
- id: my-discord-bot
token: ${DISCORD_BOT_TOKEN}主配置 plugins 映射需引用 @zhin.js/adapter-discord(instanceKey: discord)。
环境变量
| 变量 | 说明 |
|---|---|
DISCORD_BOT_TOKEN | YAML 示例中 token 引用的 Bot Token |
Interactions(HTTP)
connection: interactions 经 httpHostToken 注册 POST 路由(默认 /discord/interactions),Ed25519 验签后处理 PING 与 slash command;出站走 Discord REST channels/.../messages。需配置 applicationId 与 publicKey。
AI 工具(Skill)
| 类别 | 路径 |
|---|---|
| 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 开发者配置
- 前往 Discord Developer Portal
- 创建应用并获取 Bot Token
- 开启 MESSAGE CONTENT INTENT
- 通过 OAuth2 URL 邀请 Bot 加入服务器
Console 页面
启动后打开 Console 的「Discord」页(地址 /discord),可以:
- 查看运行中的连接、点「测试连接」做连通性诊断;
- 在账号库保存、修改、启动、停止、替换或删除该 Adapter 的账号;新增仅保存,不创建 SDK Client,需手动启动;
- 如果适配器要求登录,页面会显示 LoginAssist 的扫码 / 滑块 / 设备确认待办;
读取需要 discord:read(read 级别,内置角色 viewer 及以上都有);增删改账号等写操作需要 discord:write(operate 级别,operator 及以上都有,绑定到本适配器的角色也算),首次迁移还需管理员身份;全局所有者不受限,见插件权限的级别。页面里的「添加 endpoint」等价于原来的 discord endpoint add。
首次修改启动配置里的既有账号前,管理员必须核对清单并确认一次迁移。原 canonical 身份与历史保留,完整账号配置加密进入 Host 数据库;此后账号管理只写数据库,不修改启动文件或 .env,不重启进程。没有持久化账号端口的环境可使用静态配置连接,动态写操作明确不可用。
启停意图在进程重启后恢复。停止或删除会取消并关闭目标账号的在途操作,其他账号继续运行;删除保留历史。已启动账号的连接配置更新先关闭旧 incarnation,再仅重连该账号;平台身份变化按替换处理,分配新内部身份、保留旧历史,新账号不继承旧 Session、个人设置或启动意图。提交结果未知时先刷新核实,不自动重复 CAS 或平台操作。
Discord 的 token / publicKey 更新通过只读 GET /applications/@me 核验真实应用 ID 与 verify_key;Interactions 模式必须与配置的 applicationId / publicKey 一致。HTTP 入站先验签,再核对必填 application_id,错误应用、缺失身份或验证失败都不能进入任何平台或业务事件。
故障排查
| 现象 | 排查 |
|---|---|
| Gateway 反复断线 | 检查 Token、网络代理、Gateway Intents 与应用后台配置 |
| 能上线但收不到正文 | 启用 Message Content Intent,并给 Bot 频道读取权限 |
| 能收不能发 | 检查 Send Messages、Embed Links 与附件权限 |
connection: interactions 启动失败 | 检查 HTTP Host、applicationId、publicKey 与交互回调地址 |
许可证
MIT License
受控 Gateway 故障验收可为单个测试 endpoint 设置 gatewayFaultProxyUrl: ws://127.0.0.1:18090/。 只接受此格式的 loopback origin;REST API 仍走 SDK 默认路径。入口通过正式 ws.buildStrategy 使用已验证的 @discordjs/ws 1.2.3,SDK 继续负责心跳、Identify 和 Resume,初连及平台返回的 区域 resume_gateway_url 均转到本地代理。Endpoint 的启动、停止和失败复位统一使用 createEndpointLifecycle,SDK 断线恢复状态由 isReady() 投影为 reconnecting。
代理启动、切断与恢复见仓库 scripts/platform-acceptance/FAULT-PROXY.md。 本地 SDK 测试不能替代真实 Discord 消息及断线恢复验收。
出站失败与重试边界
Gateway 客户端的 REST 设置 retries: 0 并以 rejectOnRateLimit 拒绝后台 429 排队,二者分别覆盖网络/5xx 重试与限流重发。真实 SDK HTTP fixture 验证连接丢失、500、429、403 各只有一个 POST。已有 Gateway 代理不控制 Discord REST,不能据此宣称出站 API 故障验收通过。API 专用入口需通过正式 REST agent/dispatcher 保留 discord.com HTTPS 身份和证书校验,仅把测试实例 TCP 路由固定到 loopback。验收项目已提供独立 restApiProxy / DISCORD_REST_API_PROXY_PORT。SDK合同见 RESTOptions。
REST 专用 TLS 故障验收
Gateway 实例可选 restApiProxy: { port: 18570 },默认关闭。正式 RESTOptions.agent 使用 Undici Dispatcher,只允许真实 https://discord.com:443,保留原API URL、SNI和证书链/域名校验,TCP固定到 127.0.0.1:18570。错误目的地拒绝且不回退直连。与 gatewayFaultProxyUrl 分开;不要同时cut两条链路。SDK REST 的 Gateway discovery 等 API 也经过此代理,启动时必须先forwarding。正式 WebSocket连接不经过此REST Dispatcher;Gateway正常运行中API断开不能被记为入站WSS已重连。
node scripts/platform-acceptance/tcp-fault-proxy.mjs --upstream-host discord.com --upstream-port 443 --port 18570 --control-port 18571
DISCORD_REST_API_PROXY_PORT=18570 pnpm --filter platform-acceptance-bot dev:discordforwarding 下以新sample确认真实消息基线;control POST /cut 后另发新sample,出站结果须失败/unknown且无自动POST重发;POST /recover 后先确认旧sample未补发,再新sample确认恢复。检查平台可见消息与报告回执,不重发未知sample。此模式仅Gateway REST、JSON消息能力;Interactions Endpoint 与其他CDN目的地不适用,配置Interactions会明确拒绝。本地真实SDK TLS fixture覆盖服务收到POST后切断、可信CA但SAN不匹配拒绝、默认直连与手动恢复,不能当成实机结果。停止/连接失败会销毁专用Dispatcher,并取消尚未完成TLS握手。
公开扩展点参考:Discord RESTOptions.agent、Undici 6.28 Agent。
当前账号资料
Gateway 和 Interactions 模式均通过资料端口暴露当前认证账号的用户名(nickname)及头像。Gateway 使用原生 ClientUser;Interactions 使用 GET/PATCH /users/@me。修改沿用 Agent 身份类审批及当前账号生命周期,与服务器内的成员昵称分开处理。
支持修改昵称和头像;其他资料字段没有对应适配器操作时不声明可写。平台响应提供有效头像资料时返回其 CDN URL;若仅确认修改成功,则不返回未确认的资料。图片字节只在请求内部使用,不返回模型;Agent 解析图片沿用现有本地图片和网络权限。
nickname / profile 配置仅补足平台缺失字段,Endpoint 配置优先于适配器默认值。接口依据 discord.js ClientUser。
成员身份
服务器频道消息上报 sender.platform:服务器所有者 → owner;拥有 Administrator 或 ModerateMembers → admin;其余 → member。roles 为成员持有的身份组(不含 @everyone,Gateway 消息带名称、斜杠命令只有 id);permissions 为成员的服务器权限位,按 snake_case 命名(ban_members、manage_roles …)。私信不上报。能力画像:channel.scene.platformStanding = { standing: true, roles: true, permissions: true }。详见 ADR 0056 §1。