agent-discord

Agent Discord

一个 TypeScript CLI 工具，可让 AI Agent 和人类通过简单的命令界面与 Discord 服务交互。支持从 Discord 桌面应用无缝提取令牌（也可回退到浏览器），并支持多个服务。

快速开始

# Get server snapshot (credentials are extracted automatically)
agent-discord snapshot

# Send a message
agent-discord message send <channel-id> "Hello from AI agent!"

# List channels
agent-discord channel list

身份验证

首次使用时，系统会自动从 Discord 桌面应用提取凭据（若不可用，则回退到 Chromium 浏览器）。无需手动设置——只需运行任意命令，身份验证便会在后台静默完成。

在 macOS 上，系统首次可能会提示你输入钥匙串密码（这是解密 Discord 存储的令牌所必需的）。此提示只会出现一次。

获取令牌——有两种方式：

• agent-discord auth qr——推荐：通过 Discord 移动应用扫描 QR 码登录（设置 → 扫描 QR 码）。这是最安全、最可靠的方法——它通过 Discord 官方远程身份验证流程进行身份验证，而非读取磁盘上的凭据，并且无需桌面应用或浏览器。需要用手机扫描，因此无法在无头环境中运行。
• agent-discord auth extract：优先从 Discord 桌面应用提取；如果未安装该应用，则回退到 Chromium 浏览器。适合没有手机可用于扫描的自动化／无头环境。

QR 码登录（推荐）

# Generate a QR code and wait for you to scan it with the Discord mobile app
agent-discord auth qr

# Show protocol details while debugging
agent-discord auth qr --debug

打开 Discord 移动应用 → 设置 → 扫描 QR 码，扫描打印出的 QR 码，并在手机上确认。令牌（以及发现的所有服务）会经过验证并存储，方式与 auth extract 相同。QR 码约在 150 秒后过期——重新运行命令即可生成新的 QR 码。完整流程请参阅 references/authentication.md。

多服务支持

# List all available servers
agent-discord server list

# Switch to a different server
agent-discord server switch <server-id>

# Show current server
agent-discord server current

# Check auth status
agent-discord auth status

记忆

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、snapshot 等）
• 发现有用的频道 ID 和名称后（例如通过 channel list、snapshot 等）
• 发现用户 ID 和名称后（例如通过 user list、user me 等）
• 用户提供别名或偏好后（“把这个叫作开发服务”“我的主频道是 X”）
• 发现频道结构后（分类、语音频道）

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

应存储的内容

• 服务 ID 及其名称
• 频道 ID、名称及其分类
• 用户 ID 及其显示名称
• 用户提供的别名（“开发服务”“公告频道”）
• 常用的线程 ID
• 交互过程中表达的任何用户偏好

不应存储的内容

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

处理过期数据

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

格式／示例

# Agent Messenger Memory

## Discord Servers

- `1234567890123456` — Acme Dev (default)
- `9876543210987654` — Open Source Community

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

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

## Notes

- User prefers --pretty output for snapshots
- Main server is "Acme Dev"

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

命令

身份验证命令

# Extract token from Discord desktop app or browser (usually automatic)
agent-discord auth extract
agent-discord auth extract --debug
agent-discord auth extract --browser-profile ~/browser-data
agent-discord auth extract --browser-profile "$HOME/work-profile,$HOME/personal-profile"

# --browser-profile accepts repeatable or comma-separated Chromium profile/user-data dirs

# Sign in by scanning a QR code with the Discord mobile app (Settings -> Scan QR Code)
agent-discord auth qr
agent-discord auth qr --debug

# Check auth status
agent-discord auth status

# Logout from Discord
agent-discord auth logout

Whoami 命令

# Show current authenticated user
agent-discord whoami
agent-discord whoami --pretty

输出包含已通过身份验证的用户身份信息。

消息命令

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

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

# Get a single message by ID
agent-discord message get <channel-id> <message-id>
agent-discord message get 1234567890123456789 9876543210987654321

# Edit a message
agent-discord message edit <channel-id> <message-id> <content>
agent-discord message edit 1234567890123456789 9876543210987654321 "Updated text"

# Delete a message
agent-discord message delete <channel-id> <message-id> --force

# Acknowledge/mark a message as read
agent-discord message ack <channel-id> <message-id>

# Search messages in current server
agent-discord message search <query>
agent-discord message search "project update" --limit 10
agent-discord message search "hello" --channel <channel-id> --author <user-id>

频道命令

# List channels in current server
# Includes text, announcement, voice/stage (voice channels carry text chat),
# forum, media, and directory channels. Categories and threads are excluded.
agent-discord channel list

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

# Get channel history (alias for message list)
agent-discord channel history <channel-id> --limit 100

服务器命令

# List all servers
agent-discord server list

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

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

# Show current server
agent-discord server current

server info 还会报告加成等级、专属表情和贴纸数量，以及该等级下剩余的可用名额。

用户命令

# List server members
agent-discord user list

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

# Get current user
agent-discord user me

私信命令

# List DM channels
agent-discord dm list

# Create a DM channel with a user
agent-discord dm create <user-id>

# List unread DM and group-DM channels, newest first
agent-discord dm unread
agent-discord dm unread --limit 10

dm unread 可以处理 mention unread 无法覆盖的情况：Discord 的提及历史只记录服务器提及，因此普通私信无论有多少条未读消息，都不会出现在其中。此命令会比较每个私信频道的 last_message_id 与其已读标记。

unread_count 是 Discord 自己的徽标计数，在私信中统计的是所有消息，而不只是提及。如果频道没有已读状态条目（计数未知），该值为 null——此时仍会报告该频道，因为有消息但没有标记的私信更可能是从未打开过，而不是已读；如果私信已静音但确实有未读消息，该值为 0。count 和 total_unread 描述找到的所有未读私信，因此即使 --limit 限制了返回列表，它们仍会保持准确；total_unread 只累加已知计数。

如果 Discord 返回的已读状态不完整，complete 为 false。只有在集合完整时，缺少已读状态条目才表示“从未打开”；因此，如果载荷不完整，这些频道会被省略而不是报告，列表也可能较短。

请注意，此命令会打开一个短暂的网关连接，因为 Discord 只通过网关的 READY 载荷公开已读状态。预计需要几秒钟，这与 dm list 不同。

提及命令

# List recent mentions
agent-discord mention list
agent-discord mention list --limit 50
agent-discord mention list --guild <server-id>

# List only unread mentions (the app's unread-mention badge)
agent-discord mention unread
agent-discord mention unread --guild <server-id>
agent-discord mention unread --limit 200

mention unread 会将你最近的提及历史（过去 7 天）与 Discord 的各频道已读状态进行关联，只返回晚于各频道已读标记的提及。输出包含 count（枚举出的未读提及）、badge_count（Discord 自己的账户级未读提及徽标总数——不会受 --guild 限制），以及 complete（扫描是否已到达 7 天时间窗口内历史记录的末尾）。如果有未读提及超出 7 天时间窗口，badge_count 可能大于 count。

好友命令

# List all relationships (friends, blocked, pending requests)
agent-discord friend list
agent-discord friend list --pretty

备注命令

# Get note for a user
agent-discord note get <user-id>

# Set note for a user
agent-discord note set <user-id> "Note content"

个人资料命令

# Get detailed user profile
agent-discord profile get <user-id>

成员命令

# Search guild members
agent-discord member search <guild-id> <query>
agent-discord member search 1234567890123456789 "john" --limit 20

# Get your own membership and roles in a guild
agent-discord member me
agent-discord member me 1234567890123456789

讨论串命令

# Create a thread in a channel
agent-discord thread create <channel-id> <name>
agent-discord thread create 1234567890123456789 "Discussion" --auto-archive-duration 1440

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

表情回应命令

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

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

# List reactions on a message
agent-discord reaction list <channel-id> <message-id>

文件命令

# Upload file
agent-discord file upload <channel-id> <path>
agent-discord file upload 1234567890123456789 ./report.pdf

# List files in channel
agent-discord file list <channel-id>

# Get file info
agent-discord file info <channel-id> <file-id>

表情命令

创建需要 CREATE_GUILD_EXPRESSIONS 权限；删除他人的表情需要 MANAGE_GUILD_EXPRESSIONS 权限；列出表情则不需要权限。名称只能包含字母、数字和下划线，长度为 2–32 个字符。图片最大为 256KB。

# List custom emoji
agent-discord emoji list <server-id>

# Upload (name defaults to the filename without extension)
agent-discord emoji create <server-id> <path>
agent-discord emoji create 1234567890123456789 ./potato.png --name potato

# Delete
agent-discord emoji delete <server-id> <emoji-id>

贴纸命令

权限要求与表情相同。支持 PNG、APNG、GIF 或 Lottie JSON，最大为 512KB。名称长度为 2–30 个字符。Lottie 需要 VERIFIED 或 PARTNERED 服务器。Discord 文档要求尺寸为 320x320，但实际接受了 408x408 的 PNG，因此 CLI 不会强制检查尺寸——它会根据文件字节而非扩展名检查格式。

# List custom stickers
agent-discord sticker list <server-id>

# Upload — --tags is the unicode emoji the sticker relates to
agent-discord sticker create <server-id> <path> --tags <emoji>
agent-discord sticker create 1234567890123456789 ./potato.png --tags 🥔 --name potato

# Delete
agent-discord sticker delete <server-id> <sticker-id>

媒体类型根据文件字节而非扩展名读取，并且每条命令只接受其对应端点支持的格式——表情接受 PNG、GIF、JPEG 和 WebP；贴纸接受 PNG、APNG、GIF，以及用于 Lottie 的 JSON 文档。任何其他格式都会在本地失败并给出明确的错误信息，不会发送请求，因此批量处理时会指出哪个文件有误，而不是只返回一个 Invalid Asset。

批量上传前请检查剩余名额——agent-discord server info <server-id> 会报告加成等级、数量和可用名额。Discord 会随着加成等级提高这两类上限：静态表情为 50/100/150/250，贴纸为 5/15/30/60，对应等级 0–3。

Snapshot 命令

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

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

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

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

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

默认返回简要 JSON，包含：

• 服务器元数据（id、name）
• 频道（id、name）——所有可列出的频道（文本、公告、语音/舞台、论坛、媒体、目录；不包括分类和帖子串）
• 后续命令提示

并非所有列出的频道都支持直接使用 message list。论坛、媒体和目录频道是容器或中心视图，没有直接的消息时间线——它们的消息位于子帖子/帖子串中。请对文本、公告、语音或舞台频道使用 message list。

使用 --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": "username",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Pretty（人类可读）

使用 --pretty 标志进行格式化输出：

agent-discord channel list --pretty

与 Slack 的主要区别

特性	Discord	Slack
服务器术语	服务器	工作区
频道标识符	Snowflake ID	频道名称或 ID
消息标识符	Snowflake ID	时间戳（ts）
帖子串	帖子串 ID 字段	帖子串时间戳
提及	<@user_id>	<@USER_ID>

重要提示：Discord 的所有标识符均使用 Snowflake ID（如 1234567890123456789 这样的长数字）。不能直接使用频道名称——请先使用 channel list 查找 ID。

常见模式

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

模板

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

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

错误处理

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

{
  "error": "Not authenticated. Run \"auth extract\" first."
}

常见错误：

• Not authenticated：没有有效令牌（自动提取失败——运行 auth qr 登录，或参阅故障排查）
• No current server set：请先运行 server switch <id>
• Message not found：消息 ID 无效
• Unknown Channel：频道 ID 无效
• File is not one of ...：文件字节不符合此端点支持的任何格式。请求在本地被拒绝——请求从未发送，因此重试没有意义。
• File is a <format>; this endpoint takes ...：文件是真实图像，但不是此端点接受的格式——例如 JPEG 或 WebP 贴纸，或 JSON 表情符号。请转换格式；此请求同样在本地被拒绝。
• Emoji name may only contain ... / ... name must be at least 2 characters：名称不符合 Discord 规则，因此在本地被拒绝。除非指定 --name，否则名称取自文件名，因此 potato-13.png 会因包含连字符而失败。
• JSON file is not a Lottie animation (no layers array) / ... is not valid JSON / ... is not valid UTF-8：此 JSON 贴纸无法作为动画使用。每条错误都会指出具体问题，因为文件即使包含 layers 数组，也仍可能损坏。这三种情况都会在本地被拒绝；Discord 对此类文件会返回单独的 Invalid Asset。
• Invalid Asset（来自 Discord）：格式在本地通过验证，但 Discord 拒绝了文件内容本身——图像可能已截断或损坏。
• Maximum number of stickers reached (N)（来自 Discord）：没有剩余名额。批量操作前，请通过 server info 检查当前等级的额度。

配置

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

SDK：编程使用

DiscordClient 可作为 TypeScript SDK 使用，用于构建脚本和自动化流程。

设置

import { DiscordClient } from 'agent-messenger/discord'

const client = await new DiscordClient().login()

或手动管理凭据：

import { DiscordClient, DiscordCredentialManager } from 'agent-messenger/discord'

const manager = new DiscordCredentialManager()
const token = await manager.getToken()
if (!token) {
  throw new Error('Discord token not found. Run auth extract first.')
}
const client = await new DiscordClient().login({ token })

QR 码登录（推荐）

loginWithRemoteAuth 通过使用 Discord 移动应用扫描 QR 码来登录，无需桌面应用或提取令牌。它会运行 Discord 的 Remote Auth 协议，并提供一个 QR URL 供你显示；用户在手机上扫描并确认后，你就会收到用户令牌。

import { DiscordClient, loginWithRemoteAuth } from 'agent-messenger/discord'

const session = await loginWithRemoteAuth({
  onQrUrl: (url) => {
    // Render this URL as a QR code (e.g. with the `qrcode` package)
    console.log('Scan this with the Discord mobile app:', url)
  },
})

const client = await new DiscordClient().login({ token: session.token })

session 的结构为 { token, user }。如果网关跳过了用户负载，user 可能为 null；如果你需要用户身份，请在登录后调用 await client.testAuth()。如果 Discord 在最终令牌交换时要求完成验证码验证，该调用会以代码为 remote_auth_captcha 的 DiscordError 拒绝；此时请改用 auth extract。此功能需要安装了 Discord 应用的手机，因此无法在无头环境中运行。

示例

// Send a message
const msg = await client.sendMessage(channelId, 'Hello from SDK!')

// React to it
await client.addReaction(channelId, msg.id, '👋')

// Search messages
const { results } = await client.searchMessages(serverId, 'deployment', {
  sortBy: 'timestamp',
  sortOrder: 'desc',
  limit: 5,
})

// Get your own membership and the server's role definitions
const member = await client.getMyGuildMember(serverId)
const roles = await client.listRoles(serverId)

// List unread mentions (correlates mention history with per-channel read state)
const { mentions, count, badgeCount, complete } = await client.getUnreadMentions()
// count = enumerated unread mentions; badgeCount = account-wide badge total;
// complete = true when all available mentions (7-day window) were scanned,
// false when the scan stopped early at the limit or a non-advancing cursor

// Create a thread
const thread = await client.createThread(channelId, 'Discussion Topic')
await client.sendMessage(thread.id, 'First message in thread')

实时事件（SDK）

DiscordListener 会连接到 Discord 的 Gateway WebSocket，即时流式传输事件：

import { DiscordClient, DiscordListener } from 'agent-messenger/discord'

const client = await new DiscordClient().login()
const listener = new DiscordListener(client)

listener.on('message_create', (event) => {
  console.log(`${event.author.username}: ${event.content}`)
})

listener.on('error', (err) => console.error(err))

await listener.start()
// listener.stop()

可用事件：message_create、message_update、message_delete、message_reaction_add、message_reaction_remove、guild_member_add、guild_member_remove、typing_start、presence_update、channel_create、channel_update、channel_delete、discord_event（捕获所有事件）、connected、disconnected、error。

注意：MessageContent、GuildMembers 和 GuildPresences 是特权意图，需通过 options.intents 显式传入。

完整 API 参考

有关完整的方法签名、类型、架构和示例，请参阅 Discord SDK 文档。

限制

• 不支持语音音频（会列出语音频道和舞台频道，也可以读取其中嵌入的文字聊天，但不支持加入语音频道或传输音频）
• 不支持服务器管理（创建／删除频道、角色）
• 不支持斜杠命令
• 不支持 Webhook
• 仅支持纯文本消息（v1 不支持嵌入内容）
• 仅支持用户令牌（不支持机器人令牌）

故障排除

agent-discord: command not found

agent-discord 不是 npm 包名称。 npm 包名为 agent-messenger。

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

agent-discord server list

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

npx -y agent-messenger discord server list
bunx agent-messenger discord server list
pnpm dlx agent-messenger discord server list

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

切勿运行 npx agent-discord、bunx agent-discord 或 pnpm dlx agent-discord——由于 agent-discord 不是 npm 包名称，这些命令会失败或安装错误的包。

关于其他故障排除（身份验证提取、令牌问题、权限），请参阅 references/authentication.md。

参考资料

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