discord

使用 discord_cli.py 自动化 Discord

一个封装 Discord REST API v10 的内置 Python 脚本。零外部依赖——仅使用 Python 标准库（urllib、json、argparse）。

调用方式：python3 <path-to-skill>/scripts/discord_cli.py <command> <subcommand> [args]

设置

1. 创建 Discord 机器人

1. 前往 Discord Developer Portal → New Application
2. 点击侧边栏中的 Bot → 点击 Reset Token → 复制令牌
3. 重要：向下滚动到 Privileged Gateway Intents，启用 Message Content Intent——否则 API 响应中的消息内容将为空
4. 可选：启用 Server Members Intent（user list 需要此权限）

2. 将机器人添加到服务器

1. 点击侧边栏中的 OAuth2 → 向下滚动到 OAuth2 URL Generator
2. 勾选范围：bot + applications.commands
3. 在 Bot Permissions 下，勾选：查看频道、发送消息、读取消息历史记录、添加反应、附加文件
4. 复制生成的 URL → 在浏览器中打开 → 选择服务器 → Authorize

如果知道客户端 ID，也可以使用快捷方式：

https://discord.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&scope=bot+applications.commands&permissions=274877975552

3. 设置机器人令牌

export DISCORD_BOT_TOKEN="your_token_here"

4. 验证

python3 <path-to-skill>/scripts/discord_cli.py auth test

预期输出：

{"ok": true, "user": "your-bot-name", "id": "...", "discriminator": "..."}

命令

身份验证

python3 <path-to-skill>/scripts/discord_cli.py auth test

服务器

python3 <path-to-skill>/scripts/discord_cli.py server list
python3 <path-to-skill>/scripts/discord_cli.py server info <server-id>

频道

python3 <path-to-skill>/scripts/discord_cli.py channel list <server-id>

返回按类别和位置排序的文本、公告和论坛频道。每个频道包含 id、name、type、category 和 topic。

消息

# List recent messages (default 25, chronological order)
python3 <path-to-skill>/scripts/discord_cli.py message list <channel-id>
python3 <path-to-skill>/scripts/discord_cli.py message list <channel-id> --limit 50

# Get a single message
python3 <path-to-skill>/scripts/discord_cli.py message get <channel-id> <message-id>

# Send a message
python3 <path-to-skill>/scripts/discord_cli.py message send <channel-id> "Hello from the agent!"

# Edit a message (bot can only edit its own messages)
python3 <path-to-skill>/scripts/discord_cli.py message edit <channel-id> <message-id> "Updated text"

# Delete a message
python3 <path-to-skill>/scripts/discord_cli.py message delete <channel-id> <message-id>

# Search messages in a server
python3 <path-to-skill>/scripts/discord_cli.py message search <server-id> "query"
python3 <path-to-skill>/scripts/discord_cli.py message search <server-id> "query" --channel-id <id> --author-id <id> --limit 10

反应

python3 <path-to-skill>/scripts/discord_cli.py reaction add <channel-id> <message-id> 👍
python3 <path-to-skill>/scripts/discord_cli.py reaction remove <channel-id> <message-id> 👍
python3 <path-to-skill>/scripts/discord_cli.py reaction list <channel-id> <message-id>

主题帖

# Create a new thread in a channel
python3 <path-to-skill>/scripts/discord_cli.py thread create <channel-id> "Discussion Topic"

# Create a thread from a specific message
python3 <path-to-skill>/scripts/discord_cli.py thread create <channel-id> "Bug Triage" --message-id <id>

置顶消息

python3 <path-to-skill>/scripts/discord_cli.py pin list <channel-id>
python3 <path-to-skill>/scripts/discord_cli.py pin add <channel-id> <message-id>
python3 <path-to-skill>/scripts/discord_cli.py pin remove <channel-id> <message-id>

用户

python3 <path-to-skill>/scripts/discord_cli.py user list <server-id>
python3 <path-to-skill>/scripts/discord_cli.py user list <server-id> --limit 200
python3 <path-to-skill>/scripts/discord_cli.py user info <user-id>

在消息中使用 <@USER_ID> 提及用户。

输出格式

所有命令都会将 JSON 输出到 stdout。错误会输出到 stderr，并包含 error 字段和 HTTP status 代码。

消息对象包含：id、author、author_id、content、timestamp，以及可选的 thread_id、attachments（包含 filename 和 url）和 reactions（包含 emoji 和 count）。空值和空字段会被移除。

故障排除

消息内容为空

尚未启用 Message Content Intent。前往 Developer Portal → Bot → Privileged Gateway Intents → 开启 Message Content Intent。

user list 返回空结果或不完整结果

尚未启用 Server Members Intent。在同一意图设置区域中将其开启。

403 / 缺少访问权限错误

机器人没有该频道的权限。请检查 Discord 服务器设置中的机器人角色权限，或使用正确的权限重新授权。

令牌错误

如果机器人令牌已轮换，请使用新值更新 DISCORD_BOT_TOKEN。

备注

• Discord 对所有标识符都使用 Snowflake IDs（类似 1161736244074659893 的大数值）。不能直接使用频道名称——请先使用 channel list <server-id> 查找 ID。
• 机器人只能访问已邀请它加入的服务器，以及它有权限访问的频道。
• 机器人令牌身份验证使用官方 Discord API——不提取用户令牌，不存在违反服务条款的风险。
• 消息按时间顺序返回（最早的在前）。