agent-discordbot

Agent DiscordBot

一个 TypeScript 命令行工具，可让 AI Agent 和用户使用 Bot 令牌与 Discord 服务端交互。与从桌面应用提取用户令牌的 agent-discord 不同，agent-discordbot 使用标准 Discord Bot 令牌进行服务端和 CI/CD 集成。

核心概念

开始之前，先了解一些 Discord Bot 集成相关事项：

• Bot 令牌 — 在 Discord Developer Portal（discord.com/developers/applications）中签发。Bot 以 Bot 应用的用户身份运行，并拥有自己的 ID 和在线状态。
• 服务端（Guild）首选项 — 一个 Bot 可以加入多个服务端。使用 server switch <id> 设置当前服务端，或在每条命令中传入 --server <id>。
• 特权意图 — MessageContent、GuildMembers 和 GuildPresences 均为特权意图，必须先在 Developer Portal 中启用，SDK 监听器才能使用。
• 权限门控 — Bot 的功能取决于其在每个服务端中的角色权限标志。缺少权限时会返回 403 错误。
• 实时事件 — 可通过 SDK 的 Gateway 监听器获取，无法通过 CLI 获取。
• 频道解析 — 每个 <channel> 参数都接受频道 ID（snowflake）或精确的频道名称（general 或 #general）。使用 ID 可跳过查询，速度更快；名称若没有完全匹配的结果，则会报错 Channel not found。
• 线程定位 — 在 message send 和 file upload 中使用 --thread <id|name> 可将内容发送到线程。数值会作为线程 ID；名称会与该频道的活跃线程匹配（否则返回 thread_not_found / thread_ambiguous）。归档线程必须通过 ID 定位（使用 thread list <channel> --archived 查找）；向归档线程发送内容时会将其取消归档，除非该线程已锁定。
• 输出中的 thread_id 与 channel_id — 在某个线程中发送的消息，其 channel_id 就是线程 ID。只有从该消息启动了线程时才会设置 thread_id；否则为 null。

快速开始

# Set your bot token
agent-discordbot auth set your-bot-token

# Verify authentication
agent-discordbot auth status

# Send a message
agent-discordbot message send 1234567890123456789 "Hello from bot!"

# List channels
agent-discordbot channel list

身份验证

Bot 令牌设置

agent-discordbot 使用在 Discord Developer Portal 中创建的 Discord Bot 令牌：

# Set bot token (validates against Discord API before saving)
agent-discordbot auth set your-bot-token

# Set with a custom bot identifier
agent-discordbot auth set your-bot-token --bot deploy

# Check auth status
agent-discordbot auth status

# Clear stored credentials
agent-discordbot auth clear

关于 Bot 令牌设置、服务端邀请流程、Message Content Intent 和多 Bot 管理，请参阅 references/authentication.md。

记忆

Agent 会将 ~/.config/agent-messenger/MEMORY.md 文件作为跨会话的持久记忆。该文件由 Agent 管理，CLI 不会读取或写入此文件。使用 Read 和 Write 工具管理记忆文件。

读取记忆

在每项任务开始时，使用 Read 工具读取 ~/.config/agent-messenger/MEMORY.md，加载之前发现的服务端 ID、频道 ID、用户 ID 和首选项。

• 如果文件尚不存在，无妨——继续操作，并在首次获得有用信息时创建该文件以便保存。
• 如果无法读取文件（权限或目录缺失），则在不使用记忆的情况下继续操作，不要报错。

写入记忆

发现有用信息后，使用 Write 工具更新 ~/.config/agent-messenger/MEMORY.md。以下情况应触发写入：

• 发现服务端 ID 和名称后（例如通过 server list）
• 发现有用的频道 ID 和名称后（例如通过 channel list）
• 发现用户 ID 和名称后（例如通过 user list）
• 用户提供别名或首选项后（“把这个叫作 alerts bot”、“我的主服务端是 X”）
• 设置 Bot 标识符后（通过 auth list）

写入时，请包含完整的文件内容——Write 工具会覆盖整个文件。

存储内容

• 服务端 ID 及名称
• 频道 ID、名称和分类
• 用户 ID 及显示名称
• Bot 标识符及其用途
• 用户提供的别名（“alerts bot”、“announcements channel”）
• 交互过程中表达的任何用户首选项

不要存储的内容

绝不要存储机器人令牌、凭据或任何敏感数据。绝不要存储完整消息内容（仅存储 ID 和频道上下文）。绝不要存储文件上传内容。

处理过期数据

如果记忆中的 ID 返回错误（找不到频道、找不到服务器），请将其从 MEMORY.md 中删除。不要盲目信任记忆中的数据——发现异常时请进行验证。与其使用可能已过期的记忆 ID，不如重新列出。

格式 / 示例

# Agent Messenger Memory

## Discord Servers (Bot)

- `1234567890123456` — Acme Dev

## Bots (Acme Dev)

- `deploy` — Deploy Bot (active)
- `alert` — Alert Bot

## Channels (Acme Dev)

- `1111111111111111` — #general (General category)
- `2222222222222222` — #engineering (Engineering category)
- `3333333333333333` — #deploys (Engineering category)

## Users (Acme Dev)

- `4444444444444444` — Alice (server owner)
- `5555555555555555` — Bob

## Aliases

- "deploys" → `3333333333333333` (#deploys in Acme Dev)

## Notes

- Deploy Bot is used for CI/CD notifications
- Alert Bot is used for error monitoring

记忆可以帮你跳过重复的 channel list 和 server list 调用。如果你已经在之前的会话中知道某个 ID，就直接使用它。

命令

身份验证命令

# Set bot token
agent-discordbot auth set <token>
agent-discordbot auth set <token> --bot deploy

# Check auth status
agent-discordbot auth status

# Clear all credentials
agent-discordbot auth clear

# List stored bots
agent-discordbot auth list

# Switch active bot
agent-discordbot auth use <bot-id>

# Remove a stored bot
agent-discordbot auth remove <bot-id>

Whoami 命令

# Show current authenticated bot
agent-discordbot whoami
agent-discordbot whoami --pretty
agent-discordbot whoami --bot <bot-id>

服务器命令

# List servers the bot is in
agent-discordbot server list

# Show current server
agent-discordbot server current

# Switch active server
agent-discordbot server switch <server-id>

# Get server info
agent-discordbot server info <server-id>

消息命令

# Send a message
agent-discordbot message send <channel-id> <content>
agent-discordbot message send 1234567890123456789 "Hello world"

# Reply to a message
agent-discordbot message send <channel-id> <content> --reply <message-id>
agent-discordbot message send 1234567890123456789 "On it!" --reply 9876543210987654321

# Send a message into a thread (by ID or by active-thread name); the returned channel_id equals the thread ID
agent-discordbot message send <channel-id> <content> --thread <thread-id|thread-name>
agent-discordbot message send 1234567890123456789 "Hello world" --thread 9876543210987654321
agent-discordbot message send 1234567890123456789 "Hello world" --thread "Deployment Progress"

# Sending directly to a thread ID also works (a thread is a channel)
agent-discordbot message send 9876543210987654321 "Hello thread"

# List messages
agent-discordbot message list <channel-id>
agent-discordbot message list 1234567890123456789 --limit 50

# Get a single message by ID
agent-discordbot message get <channel-id> <message-id>

# Get thread replies
agent-discordbot message replies <channel-id> <message-id>
agent-discordbot message replies 1234567890123456789 9876543210987654321 --limit 50

# Edit a message (bot's own messages only)
agent-discordbot message edit <channel-id> <message-id> <new-content>

# Delete a message (bot's own messages only)
agent-discordbot message delete <channel-id> <message-id> --force

频道命令

# List channels in current server
agent-discordbot channel list

# Get channel info
agent-discordbot channel info <channel-id>
agent-discordbot channel info 1234567890123456789

用户命令

# List server members
agent-discordbot user list

# Get user info
agent-discordbot user info <user-id>

表情回应命令

# Add reaction (use emoji name without colons)
agent-discordbot reaction add <channel-id> <message-id> <emoji>
agent-discordbot reaction add 1234567890123456789 9876543210987654321 thumbsup

# Remove reaction
agent-discordbot reaction remove <channel-id> <message-id> <emoji>

# List reactions on a message: [{ emoji: {id, name}, count, me }]
agent-discordbot reaction list <channel-id> <message-id>

文件命令

# Upload one or more files (max 10) to a channel, optionally with text
agent-discordbot file upload <channel-id> <path...> [--text <text>] [--thread <id|name>] [--reply <message-id>] [--filename <name>]
agent-discordbot file upload 1234567890123456789 ./report.pdf
agent-discordbot file upload 1234567890123456789 ./report.pdf ./chart.png --text "Weekly numbers"

# Upload into a thread, or as a reply
agent-discordbot file upload 1234567890123456789 ./log.txt --thread 9876543210987654321
agent-discordbot file upload 1234567890123456789 ./log.txt --text "Full log attached" --reply 9876543210987654321

# Override the stored filename (single file only)
agent-discordbot file upload 1234567890123456789 ./tmp-8x1.txt --filename build.log

# List files in channel (attachments of the latest 100 messages, one request)
agent-discordbot file list <channel-id>

# Get info for one attachment (id, filename, size, url, content_type)
# Searches back through the latest 1,000 messages and stops at the first match
agent-discordbot file info <channel-id> <file-id>

file upload 返回 { success, file, files, message_id, channel_id }。file 是第一个附件，files 包含所有附件；使用 --thread 时，channel_id 是线程 ID。每种消息读取路径（message send|list|get|replies）都会包含 attachments: [{ id, filename, size, url, content_type }]；如果没有附件，则为 []。CLI 没有固定的大小限制；限制由 Discord 按服务器决定，文件过大时会报告 40005（或 http_413）。

线程命令

# Create a thread from a message
agent-discordbot thread create <channel-id> <name>
agent-discordbot thread create 1234567890123456789 "Discussion" --auto-archive-duration 1440

# List active threads (whole server, or one channel's threads)
agent-discordbot thread list
agent-discordbot thread list <channel-id>

# List archived threads of a channel (100 most recently archived; has_more tells you if there are older ones)
agent-discordbot thread list <channel-id> --archived

# Archive a thread
agent-discordbot thread archive <thread-id>

thread list 返回 { threads: [{ id, name, type, parent_id, archived }], has_more }。--archived 需要提供频道参数（否则会返回 parent_required）。

快照命令

获取服务器概览，供 AI Agent 使用（默认简要）：

# Brief snapshot (default) — fast, minimal API calls
agent-discordbot snapshot

# Full snapshot — includes messages and members (slow, large output)
agent-discordbot snapshot --full

# Filtered full snapshots
agent-discordbot snapshot --full --channels-only
agent-discordbot snapshot --full --users-only

# Limit messages per channel (only with --full)
agent-discordbot snapshot --full --limit 10

默认返回简要 JSON，包含：

• 服务器 ID
• 频道（id、name）——仅文本频道
• 后续命令提示

使用 --full 时，会返回完整 JSON，包含：

• 服务器元数据（id、name）
• 频道（id、name、type、topic）
• 最近的消息（id、content、author、timestamp）
• 成员（id、username、global_name）

输出格式

JSON（默认）

所有命令默认输出 JSON，供 AI 使用：

{
  "id": "1234567890123456789",
  "content": "Hello world",
  "author": "bot-username",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Pretty（便于阅读）

使用 --pretty 标志以格式化形式输出：

agent-discordbot channel list --pretty

全局选项

选项	说明
--pretty	输出便于阅读的内容，而非 JSON
--bot <id>	为此命令指定机器人
--server <id>	为此命令指定服务器

常见模式

典型的 AI Agent 工作流请参见 references/common-patterns.md。

模板

可运行示例请参见 templates/ 目录：

• post-message.sh - 发送消息并处理错误
• monitor-channel.sh - 监控频道中的新消息
• server-summary.sh - 生成服务器摘要

错误处理

所有命令都会返回统一的错误格式：

{
  "error": "No credentials. Run \"auth set\" first."
}

常见错误：missing_token、invalid_token、Missing Access、Unknown Channel、Missing Permissions。

与发送文件和指定线程相关的错误：

• empty_message：file upload 至少需要一个文件，或同时提供 --text。
• too_many_files：一次上传的文件超过 10 个。
• invalid_filename：--filename 为空、为 . 或 ..，或包含路径分隔符。
• thread_not_found：--thread <name> 未在该频道中匹配到活动线程。运行 thread list <channel>（若要查找已归档线程，请添加 --archived），或传入线程 ID。
• thread_ambiguous：多个活动线程具有相同名称；消息中会列出它们的 ID。请使用 ID。
• parent_required：调用 thread list --archived 时未提供频道。
• 40005 / http_413：Discord 拒绝了上传，文件超出该服务器的大小限制。错误消息会说明原因；CLI 不会预先检查大小。

配置

凭据存储在 ~/.config/agent-messenger/discordbot-credentials.json 中（权限为 0600）。格式和安全详情请参见 references/authentication.md。

与 agent-discord 的主要区别

功能	agent-discord	agent-discordbot
令牌类型	用户令牌	Bot 令牌
令牌来源	从桌面应用自动提取	从开发者门户手动获取
消息搜索	是	否
私信	是	否
提及	是	否
好友／备注	是	否
编辑／删除消息	任何消息	仅限 Bot 自己发送的消息
文件上传	是	是（文本、线程、回复）
线程列表	否	是（活跃和已归档）
表情回应列表	是	是
快照	是	是
适合 CI/CD	需要桌面应用	是（只需设置令牌）

限制

• 命令行中不支持实时事件（SDK 支持实时 Gateway 事件——import { DiscordBotListener } from 'agent-messenger/discordbot'）
• 不支持语音频道
• 不支持服务器管理（创建／删除频道、角色）
• 不支持斜杠命令
• 不支持 Webhook
• 不支持消息搜索
• 不支持私信或好友管理
• Bot 只能编辑／删除自己发送的消息
• 必须将 Bot 邀请到服务器，并授予适当的权限
• 已验证的 Bot（100 个以上服务器）需要启用 Message Content 意图
• 仅支持纯文本消息（v1 不支持嵌入内容）
• 线程名称仅能解析到活跃线程；已归档的线程需要使用其 ID
• thread list --archived 仅返回一页（100 个线程），并带有 has_more；不支持进一步分页
• 不支持下载或删除文件

故障排除

agent-discordbot: command not found

agent-discordbot 不是 npm 包名。 npm 包名是 agent-messenger。

如果已全局安装此包，请直接使用 agent-discordbot：

agent-discordbot message send 1234567890123456789 "Hello"

如果尚未安装此包，默认使用 npx -y。不要询问用户要使用哪种包运行器——直接运行：

npx -y agent-messenger discordbot message send 1234567890123456789 "Hello"
bunx agent-messenger discordbot message send 1234567890123456789 "Hello"
pnpm dlx agent-messenger discordbot message send 1234567890123456789 "Hello"

如果你已知用户偏好的包运行器（例如，bunx、pnpm dlx），请改用该运行器。

切勿运行 npx agent-discordbot、bunx agent-discordbot 或 pnpm dlx agent-discordbot——这会失败或安装错误的包，因为 agent-discordbot 不是 npm 包名。

有关其他故障排除内容（权限、令牌问题、Message Content 意图），请参阅 references/authentication.md。

参考资料

• 身份验证指南
• 常见模式