Pi-Discord

通过 Discord Bot（discord.js Gateway 长连接），将 Discord 作为聊天渠道远程控制 Pi Agent。

在 Discord 中给 Bot 发消息，Pi 自动接收并处理，响应实时回传到 Discord。

功能

• 使用 discord.js（Gateway WebSocket 长连接），内置自动重连
• 工具执行进度实时推送：每次工具调用在 Discord 中显示一条可编辑的进度消息
• 中间文本推送：assistant 思考过程中的每一步文本都推送到 Discord，不只是最终回复
• Typing 输入指示：处理中显示打字指示，失败在用户消息上加 ❌
• 媒体收发：图片、文件自动下载/上传，支持双向传递
• Pi LLM 可主动发送文本、图片、文件到 Discord（通过注册的工具）
• 消息去重（轻量，防 Gateway 偶发重投）
• 支持多频道/多用户同时与 Bot 对话
• 支持服务器频道（Guild）和私信（DM）

安装

pi install npm:@xingchen89/pi-discord

配置

创建 Bot 并获取凭证

1. 打开 Discord Developer Portal，创建 Application。
2. 进入 Bot 页，点击 Reset Token 获取 Bot Token。
3. 在 Bot 页开启 Privileged Gateway Intents → MESSAGE CONTENT INTENT（必须，否则收到的消息内容为空）。
4. 进入 OAuth2 → URL Generator，勾选 bot scope 与所需权限（至少 Send Messages、Read Message History、Add Reactions、Attach Files、Create Public Threads、Send Messages in Threads），用生成的链接把 Bot 邀请进你的服务器。

配置方式

支持三种配置方式，优先级从高到低：

1. CLI 标志

pi --discord-token=xxx

2. 环境变量

export DISCORD_BOT_TOKEN="xxx"

3. Pi settings.json（推荐）

在 .pi/settings.json（项目级）或 ~/.pi/agent/settings.json（全局）中添加：

{
  "discord": {
    "token": "xxx",
    "appId": "",
    "requireMention": true,
    "mentionPatterns": [],
    "useThread": true
  }
}

字段名支持 camelCase（appId）和 snake_case（app_id）两种写法。项目级配置覆盖全局配置。

配置项说明

字段	环境变量	CLI 标志	必需	默认
Bot Token	DISCORD_BOT_TOKEN	--discord-token	是	—
App ID	DISCORD_APP_ID	--discord-app-id	否	—
频道需 @机器人	DISCORD_REQUIRE_MENTION	—	否	true
触发正则	—	—	否	空
进度放入 thread	DISCORD_USE_THREAD	—	否	true

触发方式（重要）

为避免在服务器频道里对每一条消息都响应，Bot 的触发规则为：

• 私信（DM）：始终响应，无需 @机器人。
• 服务器频道（Guild）：默认只在被触发时响应。以下任一情况算被触发：
  1. 消息中 @机器人；
  2. **回复（reply）**机器人发出的某条消息；
  3. 命中 mentionPatterns 中任一正则（如 ["^pi[\\s,:]"] 让以 pi 开头的消息也能触发）。

若某个频道由机器人独占、希望它响应所有消息，把 requireMention 设为 false（或 DISCORD_REQUIRE_MENTION=false）。此项不影响 DM。

工具进度与 Thread

当一次回答涉及工具调用时，Bot 会在服务器频道里针对该条用户消息开一个 thread，把工具进度卡片（⏳→✅/❌，原地编辑更新）放进 thread，主频道只保留干净的「问题 + 中间文本 + 最终回复」。

• 仅在首次出现工具调用时才创建 thread，纯文本问答不会生成空 thread。
• thread 名取用户消息前 80 字，60 分钟无活动自动归档。
• 以下情况自动回退到「频道内直接发进度卡片」：DM（私信没有 thread）、消息本身已在某个 thread 内、频道类型不支持、或缺少建 thread 权限。
• 不想用 thread：把 useThread 设为 false（或 DISCORD_USE_THREAD=false）。

启动

pi

Pi 启动时会自动加载 pi-discord 扩展并连接 Discord Gateway。在 Discord 中给 Bot 发消息（或在服务器频道 @Bot）即可开始使用。

管理命令

在 Pi 终端中使用 /discord 命令管理连接：

命令	说明
/discord start	启动 Discord Bot 连接
/discord stop	断开连接
/discord status	查看连接状态
/discord config	查看当前配置
/discord help	显示帮助

在 Discord 聊天中可用的斜杠命令（由扩展直接处理，不发给 LLM）：

命令	说明
/new	新建会话（重置上下文）
/stop	中断当前处理，清空排队
/queue	查看排队状态
/compact	压缩上下文
/status	查看 Pi 状态
/help	显示帮助

事件映射

Pi 事件	Discord 动作
入站消息	显示 Typing + 转发给 Pi
tool_execution_start	在 thread 内创建/更新进度消息（见「工具进度与 Thread」）
tool_execution_end	更新进度消息（标记完成/失败）
turn_end（含工具调用）	发送中间文本（回复模式）
turn_end（纯文本）	发送最终回复（新消息）
agent_end	停止 Typing

注册的 Pi 工具

Pi LLM 可以主动调用以下工具向 Discord 发送内容：

工具名	说明
send_to_discord	发送文本消息到 Discord
send_image_to_discord	上传并发送图片到 Discord
send_file_to_discord	上传并发送文件到 Discord

架构

+---------------------+   Gateway (discord.js)   +--------------------+
|   Discord 网关       | <----------------------> |  Pi Extension      |
|   discord.com       |       messageCreate      |  (discord-client)  |
+---------------------+                          +---------+----------+
                                                           |
                                                           | sendUserMessage()
                                                           | on("turn_end")
                                                           | on("tool_execution_*")
                                                           v
                                                  +--------------------+
                                                  |  Pi Agent Core     |
                                                  |  (LLM + Tools)     |
                                                  +--------------------+

项目结构

pi-discord/
+-- src/
|   +-- index.ts           # Pi 扩展主入口，事件处理，工具注册
|   +-- discord-client.ts  # Discord Gateway 客户端封装
|   +-- types.ts           # 类型定义
+-- package.json
+-- README.md

开发

npm install
npm run typecheck
pi -e ./src/index.ts --discord-token=YOUR_TOKEN

注意事项

1. Bot Token 请妥善保管，不要提交到版本控制
2. 必须在 Developer Portal 开启 MESSAGE CONTENT INTENT，否则消息内容为空
3. 单条消息最大 2000 字符（Discord 限制），长消息自动分块
4. 媒体文件下载到系统临时目录（/tmp/discord-media/）
5. 收私信（DM）需要 Bot 与用户有共同服务器或用户主动发起 DM

License

MIT