discordbot

我们使用 curl + jq，并通过 $DISCORDBOT_TOKEN 中用户的 bot 令牌调用 Discord API。 身份验证标头为 Authorization: Bot $DISCORDBOT_TOKEN——注意字面前缀 Bot （不是 Bearer）。基础 URL 为 https://discord.com/api/v10。

这会以用户已注册的 bot 身份运行，因此它只能查看和操作已邀请其加入且它拥有相关权限（查看频道／发送消息／读取消息历史记录）的服务器（guild）。403 Forbidden（代码 50001“Missing Access”／50013“Missing Permissions”）几乎总是表示 bot 不在该服务器中或缺少相应权限——应告知用户邀请 bot 或授予相应权限，而不是重试。

错误采用 JSON 格式：{"code": <n>, "message": "<reason>"}。401 表示 bot 令牌错误或已重置——请用户在 studio.acedata.cloud/console/connectors 重新粘贴令牌。429 会包含 retry_after（秒）——等待相应时长后再重试；绝不要并行执行。

发送安全须知

• 发送前，先与用户确认准确的目标位置和最终内容。发送后无法撤回。
• 必须由收件人发起私信，例如收件人回复公开告知的关键词，向 bot 索取详细信息。加入服务器、拥有公开个人资料或出现在成员列表中，都不代表同意。
• 每次调用只能发送给一位收件人。绝不要枚举成员、循环创建私信频道，或发送未经请求／批量消息。
• 对于无人值守的定时运行，仅当任务定义已包含唯一且准确的 recipient_id、consent_channel_id、consent_message_id、consent_keyword 和已批准的 content 时才发送。缺少任何一项，都应返回草稿而不发送。
• 除非收件人回复，否则不要跟进。将 stop、unsubscribe 或同等含义的拒绝视为永久退订。

操作示例

验证 bot（始终先运行）

curl -sS -H "Authorization: Bot $DISCORDBOT_TOKEN" \
  "https://discord.com/api/v10/users/@me" \
  | jq '{id, username, bot}'

列出 bot 所在的服务器（guild）

curl -sS -H "Authorization: Bot $DISCORDBOT_TOKEN" \
  "https://discord.com/api/v10/users/@me/guilds" \
  | jq 'map({id, name})'

列出服务器中的文字频道

频道 type 0 = 文字，5 = 公告；2 = 语音，4 = 分类（发送消息时跳过这些频道）。需要使用上方调用结果中的 guild id。

GUILD_ID="123456789012345678"
curl -sS -H "Authorization: Bot $DISCORDBOT_TOKEN" \
  "https://discord.com/api/v10/guilds/$GUILD_ID/channels" \
  | jq 'map(select(.type==0 or .type==5) | {id, name, type})'

读取频道中的近期消息

读取消息内容需要在 bot 上启用 Message Content Intent（Developer Portal → Bot → Privileged Gateway Intents）。未启用时，对于未提及 bot 的消息，返回的 content 为空。该频道中还需要 Read Message History 权限。

CHANNEL_ID="123456789012345678"
curl -sS -H "Authorization: Bot $DISCORDBOT_TOKEN" \
  "https://discord.com/api/v10/channels/$CHANNEL_ID/messages?limit=20" \
  | jq 'map({id, author_id: .author.id, author: .author.username, author_bot: .author.bot, ts: .timestamp, content})'

向频道发送消息

CHANNEL_ID="123456789012345678"
curl -sS -X POST \
  -H "Authorization: Bot $DISCORDBOT_TOKEN" \
  -H "Content-Type: application/json" \
  "https://discord.com/api/v10/channels/$CHANNEL_ID/messages" \
  -d "$(jq -nc --arg c "Hello from the bot." '{content: $c}')"

回复特定消息

CHANNEL_ID="123456789012345678"; MESSAGE_ID="987654321098765432"
curl -sS -X POST \
  -H "Authorization: Bot $DISCORDBOT_TOKEN" \
  -H "Content-Type: application/json" \
  "https://discord.com/api/v10/channels/$CHANNEL_ID/messages" \
  -d "$(jq -nc --arg c "On it!" --arg m "$MESSAGE_ID" \
        '{content: $c, message_reference: {message_id: $m}}')"

发送一条用户主动同意的私信

仅在遵循发送安全须知中的所有规则后使用。该辅助程序会从 Discord 获取源消息，并验证非 bot 作者是否与 RECIPIENT_ID 一致，以及消息全文是否与 CONSENT_KEYWORD 一致。不要直接调用 Create DM 端点。匹配时不区分大小写，并会折叠首尾空白和重复空白。

RECIPIENT_ID="123456789012345678"
CONSENT_CHANNEL_ID="223456789012345678"
CONSENT_MESSAGE_ID="323456789012345678"
CONSENT_KEYWORD="details"

python3 "$SKILL_DIR/scripts/discordbot.py" send-opt-in-dm \
  --recipient-id "$RECIPIENT_ID" \
  --consent-channel-id "$CONSENT_CHANNEL_ID" \
  --consent-message-id "$CONSENT_MESSAGE_ID" \
  --consent-keyword "$CONSENT_KEYWORD" \
  --content "Here are the details you requested."

除非最后一个参数为 --confirm，否则该命令仅进行试运行。在预先授权的定时任务中，改用最后一个参数 --unattended-confirm。该辅助程序会验证所有 ID、核实用户主动同意的消息，并跳过私信历史记录中已存在的相同消息。Discord 可能会阻止或限制频繁创建私信的 bot；不要改为向其他账号发送并重试。

注意事项

• UI 中的“服务器”在 API 中称为“公会”；消息位于公会内的频道中。务必按以下顺序操作：列出公会 → 列出该公会的频道 → 对频道 ID 执行操作。不要编造 ID。
• 机器人只能看到受邀加入的服务器。添加方法：Developer Portal → OAuth2 → URL Generator → 选择所需的 bot 范围和权限 → 打开 URL → 选择一个服务器（用户需要拥有该服务器的 Manage Server 权限）。
• 这是一个机器人，不是用户的账号——它无法读取用户的私信或用户的完整服务器列表，只能访问机器人自身有权限访问的内容。
• 机器人可以与一位同意的用户开启自己的私信频道；这不会授予它访问所连接用户个人私信的权限。
• 提及：<@USER_ID> 会提醒用户，<#CHANNEL_ID> 会链接到频道。普通消息使用纯文本即可。