跳到主要内容

Discord

Discord 集成可将你的 Discord 服务器连接到 Almirant，以执行代理命令、接收项目事件通知，并直接从聊天中控制工作会话。

工作原理​

Almirant 通过一个使用 OAuth2 连接到你的服务器的机器人与 Discord 集成。该机器人可以：

  • 执行斜杠命令 -- 使用 /implement 和 /plan 等命令从 Discord 启动代理任务。
  • 发送通知 -- Almirant 通过 Discord 通知相关事件（工作项、冲刺、PR、CI/CD）。
  • 控制会话 -- 使用交互式按钮停止、暂停代理，或回答代理的问题。
  • 自动创建主题 -- 每个代理任务都会创建一个专用主题以跟踪进度。

配置 Discord 集成​

1. 通过 OAuth 连接​

与其他机器人不同，Discord 使用 OAuth2 实现安全连接：

  1. 前往 设置 > 集成 > Discord。
  2. 点击 连接 Discord。
  3. Discord 会要求你选择一个拥有管理员权限的服务器。
  4. 授予所请求的权限（发送消息、创建主题、使用斜杠命令）。
  5. Almirant 会自动在你的服务器中注册斜杠命令。

2. 配置默认频道​

连接后：

  1. 前往 设置 > 集成 > Discord。
  2. 选择机器人发送通知的默认频道。
  3. 保存配置。

3. 验证连接​

  1. 在 Discord 设置中，点击 发送测试消息。
  2. 确认消息出现在所选频道中。

斜杠命令​

Discord 机器人支持使用斜杠命令与 Almirant 交互：

命令描述
/implement [work_item_id]为指定工作项启动实现任务
/plan [work_item_id]为指定工作项启动规划任务
/status显示活跃任务（queued、running、waiting_for_input）
/status [job_id]显示指定任务的详细状态

命令选项​

/implement 和 /plan 命令接受额外选项：

选项描述
work_item_id（必填）工作项的 ID（例如：A-123）
provider（可选）代理提供商：claude-code、codex 或 zipu

使用示例​

/implement work_item_id:A-1189
/implement work_item_id:A-1189 provider:claude-code
/plan work_item_id:A-1190
/status job_id:abc123-def456

自动主题​

执行斜杠命令时，机器人会自动为该任务创建一个私密主题：

  • 主题名称会标明任务类型和任务 ID
  • 所有代理进度消息都会发送到该主题
  • 控制按钮（Stop、Shutdown）会显示在主题中
  • 主题会在 24 小时无活动后自动归档

交互式按钮​

任务执行期间，机器人会显示用于控制会话的按钮：

按钮操作
Stop停止当前任务，但保留状态
Shutdown完全停止并关闭会话

当代理有问题时，选项会显示为按钮或选择菜单。选择所需选项即可作答。

通知​

配置希望通过 Discord 接收通知的项目事件：

事件描述
创建工作项创建了新的工作项
移动工作项工作项在看板中变更列
分配工作项工作项被分配给某人
完成工作项工作项被标记为 done
启动/关闭冲刺冲刺开始或结束
完成里程碑里程碑完成
打开/合并 PR拉取请求被打开或合并
CI 失败CI 构建失败
代理任务完成/失败代理任务结束

配置通知：

  1. 前往 设置 > 集成 > Discord。
  2. 点击 配置通知。
  3. 启用或禁用所需事件。
  4. 保存更改。

将项目关联到频道​

你可以为不同项目配置特定频道：

  1. 前往项目设置。
  2. 在 Discord 部分中，选择目标频道。
  3. 该项目的通知和主题将发送到已配置的频道。

如果没有特定频道，则使用组织的默认频道。

断开 Discord​

断开机器人：

  1. 前往 设置 > 集成 > Discord。
  2. 点击 断开连接。
  3. 确认断开连接。
注意

断开机器人会停止通过 Discord 的斜杠命令和通知。正在进行的任务不会自动取消。

开发者指南

集成架构​

Discord 集成由两条主要路由组成：

  • OAuth 路由（/api/integrations/discord）：处理 OAuth2 流程、连接管理、频道和通知偏好。
  • 交互 webhook（/webhooks/discord/interactions）：接收并处理斜杠命令、按钮和选择菜单。

OAuth 流程​

Usuario --> GET /authorize --> Discord OAuth --> GET /callback
                                                      |
                                    +------------ Token exchange
                                    |
                            Create connection + Register slash commands

交互流程​

Discord --> POST /webhooks/discord/interactions --> Verify signature
                                                         |
                              +--------------------------+
                              |           |              |
                            PING     Command        Component
                              |           |              |
                           PONG    Queue job      Process action

已注册的斜杠命令​

命令会在 OAuth 期间自动注册到 guild：

  • implement：启动实现任务
  • plan：启动规划任务
  • status：查询任务状态

签名验证​

所有交互均使用 Discord 公钥（DISCORD_PUBLIC_KEY）通过 Ed25519 验证。这可确保请求来自 Discord。

环境变量​

变量描述
DISCORD_CLIENT_IDDiscord 应用的 ID
DISCORD_CLIENT_SECRET应用密钥
DISCORD_PUBLIC_KEY用于验证签名的公钥
DISCORD_BOT_TOKEN用于发送消息的机器人令牌
DISCORD_APPLICATION_ID应用 ID（用于斜杠命令）
DISCORD_OAUTH_REDIRECT_URIOAuth 回调 URI