@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
• 支持私聊、群组与服务器频道
• 出站 send({ conversation, payload }) → Discord channel message（Markdown content / media / embed / keyboard）
• 约定式 defineAdapter / definePlugin（无需 usePlugin）
• Interactions HTTP webhook 延期（需 httpHostToken）；配置 connection: interactions 会明确报错

安装

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

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 路径）

入站：gateway.receive({ conversation, message, content: text, sender, metadata })（conversation 为 ConversationRef，guild 频道带 parent guild 容器）
出站：send({ conversation, payload }) → discord.js channel.send

平台权限（platform permit）

• 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。

前置条件

| 要求 | 说明 | |------|------| | Bot Token | Discord Developer Portal 创建应用并获取 Token | | MESSAGE CONTENT INTENT | 需开启才能读取消息正文 | | Gateway（默认） | 本地/生产均可；discord.js 连接 Gateway，无需公网 HTTPS | | host-http | Gateway 不需要；Interactions webhook 延期至下一棒 |

必填字段（endpoints[i]）：name、token。

最小配置

# 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）。

环境变量

| 变量 | 说明 | |------|------| | DISCORD_BOT_TOKEN | Bot Token | | DISCORD_BOT_NAME | 可选，默认 endpoint 名 |

Interactions（HTTP）

connection: interactions 经 httpHostToken 注册 POST 路由（默认 /discord/interactions），Ed25519 验签后处理 PING 与 slash command；出站走 Discord REST channels/.../messages。需配置 applicationId 与 publicKey。

AI 工具（Skill）

| 类别 | 路径 | |------|------| | Permit 词汇 | agent/PERMITS.md | | 平台工具（7 个） | agent/tools/（discord_*：角色、Embed、反应等） | | 技能说明 | agent/skills/discord.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 加入服务器

故障排查

| 现象 | 排查 | | --- | --- | | Gateway 反复断线 | 检查 Token、网络代理、Gateway Intents 与应用后台配置 | | 能上线但收不到正文 | 启用 Message Content Intent，并给 Bot 频道读取权限 | | 能收不能发 | 检查 Send Messages、Embed Links 与附件权限 | | connection: interactions 启动失败 | 当前生产路径使用 Gateway；改回 gateway |

许可证

MIT License