Skip to content

文档同步

本页由 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

安装 ​

bash
pnpm add @zhin.js/adapter-discord discord.js

Plugin 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 统一经 Core canAccessTool() 消费 permissions。

前置条件 ​

要求说明
Bot TokenDiscord Developer Portal 创建应用并获取 Token
MESSAGE CONTENT INTENT需开启才能读取消息正文
Gateway(默认)本地/生产均可;discord.js 连接 Gateway,无需公网 HTTPS
host-httpGateway 不需要;Interactions webhook 需要

必填字段(endpoints[i]):id、token。

最小配置 ​

yaml
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_TOKENYAML 示例中 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 开发者配置 ​

  1. 前往 Discord Developer Portal
  2. 创建应用并获取 Bot Token
  3. 开启 MESSAGE CONTENT INTENT
  4. 通过 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已重连。

bash
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:discord

forwarding 下以新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。