name: discord description: 构建和自动化Discord集成（机器人、webhooks、斜杠命令和REST API工作流）。当用户提到Discord、Discord服务器/公会、频道、webhooks、机器人令牌、斜杠命令/应用命令、discord.js或discord.py时使用。 triggers:

discord
discord api
discord bot
discord webhook
discord.js
discord.py

Discord

当实现或自动化Discord集成时使用此技能。

选择正确的方法

传入webhooks（最适合单向发布）
- 适用于CI通知、警报、构建状态等。
- 不需要机器人用户。
- 参见：https://discord.com/developers/docs/resources/webhook#execute-webhook
机器人令牌 + REST API（双向/更丰富的自动化）
- 当需要以机器人身份发布、管理频道、读取历史、审核等时使用。
- REST API基础：https://discord.com/api/v10
- 大多数REST调用使用Authorization: Bot <token>。
交互/斜杠命令（用户调用的命令）
- 使用应用命令和交互webhooks。
- 通常需要运行Web服务器以接收交互并快速响应。

密钥与安全

切勿硬编码令牌。使用环境变量：
- DISCORD_WEBHOOK_URL 用于传入webhooks
- DISCORD_BOT_TOKEN 用于机器人REST API调用
将webhook URL视为秘密（它们包含令牌）。
不要自动化普通用户账户（“自机器人”）。使用官方机器人/OAuth流程。

注意事项/安全说明（请阅读此部分）

Webhook URL是秘密（令牌嵌入在URL中）。不要将其粘贴到问题、日志、CI输出或聊天中。
提及默认是危险的：总是将allowed_mentions设置为严格的设置（这些示例使用{"parse": []}）以避免意外ping @everyone/角色。
注意意外秘密日志：
- 如果您构建自己的脚本，避免在异常消息中包含完整的webhook URL。
- 捆绑的脚本在错误输出中清理webhook URL，但您仍应避免自己打印URL。
速率限制：使用retry_after/Retry-After处理HTTP 429，不要无限重试。

快速配方

通过传入webhook发布消息（推荐）

Discord要求至少包含content、embeds、components、file或poll中的一个。

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  -d '{"content":"Hello from OpenHands","allowed_mentions":{"parse":[]}}' \
  "$DISCORD_WEBHOOK_URL"

使用机器人令牌向频道发布消息

端点：POST /channels/{channel_id}/messages（创建消息）

CHANNEL_ID="..."

curl -sS -X POST "https://discord.com/api/v10/channels/${CHANNEL_ID}/messages" \
  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"content":"Hello from my bot","allowed_mentions":{"parse":[]}}'

文档：https://discord.com/developers/docs/resources/channel#create-message

自动化脚本（捆绑）

这些脚本是自包含的，仅使用Python标准库。

发布到webhook：

python3 -m skills.discord.scripts.post_webhook --content "Build finished" --wait

使用机器人令牌发布到频道：

python3 -m skills.discord.scripts.send_message --channel-id "$CHANNEL_ID" --content "Hello"

速率限制

不要硬编码限制。当存在时，使用Discord的Retry-After / retry_after和速率限制头部。
在HTTP 429上，等待提供的延迟（限制在合理最大值，添加小抖动），然后重试。

文档：https://discord.com/developers/docs/topics/rate-limits

斜杠命令/应用命令

使用公会命令进行快速迭代（即时更新）。
准备就绪时使用全局命令；传播可能需要更长时间。

文档：https://discord.com/developers/docs/interactions/application-commands

参考

更多细节（OAuth2流程、命令注册端点、故障排除），请参见：

references/REFERENCE.md