企业官网建设流程全解析

Archon Discord 社区适配器接入指南：从 Bot 创建到线程会话与用户白名单

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon

Archon 是一套开源的 AI 编程 Harness 构建工具，其社区适配器体系允许你将 AI 编程助手接入 Telegram、Slack、Discord 等消息平台。本文以 Discord 适配器文档 为骨架，结合仓库内 adapter.ts 与 server 集成代码 的源码实现，完整讲解如何在 Discord 服务器或私信中与 AI 编程助手交互——读完你将掌握从创建 Bot、获取 Token、开启 Message Content Intent、邀请入群，到配置用户白名单、流式模式与 @提及开关的完整实战流程，并能理解线程会话、2000 字符分片发送等底层行为。

注意：Discord 是一个社区适配器（community adapter），由社区贡献与维护，其说明与源码位于 packages/adapters/src/community/chat/discord/ 目录。

前置条件

接入 Discord 前，请确保满足以下条件：

• Archon 服务器已启动运行（参见 Getting Started 总览）；
• 拥有一个 Discord 账号；
• 在目标 Discord 服务器上拥有“Manage Server”（管理服务器）权限，才能把 Bot 添加进服务器。

创建 Discord Bot

1. 打开 Discord 开发者门户（Discord Developer Portal）；
2. 点击“New Application”（新建应用）→ 输入应用名称 → 点击“Create”（创建）；
3. 在左侧边栏进入“Bot”标签页；
4. 点击“Add Bot”（添加 Bot）→ 确认操作。

获取 Bot Token

1. 在 Bot 标签页中点击“Reset Token”（重置令牌）；
2. 复制生成的 Token（一长串字母数字字符串）；
3. 务必安全保存——Token 只在重置时展示一次，之后无法再次查看。

从源码角度看，这个 Token 最终会通过环境变量DISCORD_BOT_TOKEN传入DiscordAdapter构造器，并用于client.login(token)建立 WebSocket 连接（见 adapter.ts）。Token 本质上是 Bot 的身份凭证，泄漏等于将 Bot 的完整控制权交给他人。

开启 Message Content Intent（必做）

1. 滚动到“Privileged Gateway Intents”（特权网关意图）区域；
2. 开启“Message Content Intent”（消息内容意图）——Bot 读取消息内容所必需；
3. 保存更改。

这是最容易踩坑的一步。源码中DiscordAdapter构造器声明了GatewayIntentBits.MessageContent意图（adapter.ts），如果 Discord 侧没有开启该意图，登录时会因使用被禁止的意图（Used disallowed intents）而被拒绝连接。

:::caution 跳过此步骤会导致 Discord 以Used disallowed intents拒绝 Bot 连接。Archon 会记录discord.start_failed_continuing_without_adapter日志并保持服务器其余部分正常运行，但 Discord 适配器将不可用，直到开启该意图并重启服务器。 :::

这个“降级不崩溃”的行为在 server/src/index.ts 中有明确实现：discord.start()抛出的错误被捕获后，会区分“特权意图缺失”与“Token 无效”两种情形给出不同的修复提示，随后将discord置为null，服务器其余平台照常运行——也就是说，Discord 配置错误不会拖垮整个 Archon 服务。

邀请 Bot 到服务器

1. 进入“OAuth2” → “URL Generator”（URL 生成器）；
2. 在“Scopes”（作用域）下勾选：bot；
3. 在“Bot Permissions”（Bot 权限）下勾选：
   • Send Messages（发送消息）
   • Read Message History（读取消息历史）
   • Create Public Threads（创建公开线程，可选，用于线程支持）
   • Send Messages in Threads（在线程中发送消息，可选，用于线程支持）
4. 复制底部的授权 URL；
5. 在浏览器中打开该 URL，选择目标服务器；
6. 点击“Authorize”（授权）。

提示：添加 Bot 需要 “Manage Server” 权限。

线程相关权限（Create Public Threads / Send Messages in Threads）并非强制，但强烈建议开启——因为 Archon 的 Discord 适配器在服务器频道中会自动创建线程来组织会话（详见下文“线程会话机制”）。

设置环境变量

DISCORD_BOT_TOKEN=your_bot_token_here

设置完成后启动（或重启）Archon 服务器，日志中应出现discord.bot_logged_in与discord.bot_started，同时平台列表中会加入Discord。若未设置该变量，则日志记录discord_adapter_skipped，适配器静默跳过（server/src/index.ts）。

配置用户白名单（可选）

默认情况下，任何能向 Bot 发消息的人都可以使用（开放访问模式）。若要限制 Bot 仅服务于特定用户，可按以下步骤操作：

1. 在 Discord 用户设置 → 高级（Advanced）中开启“开发者模式”（Developer Mode）；
2. 右键点击目标用户 → 复制用户 ID（Copy User ID）；
3. 将 ID 写入环境变量（多个 ID 用英文逗号分隔）：

DISCORD_ALLOWED_USER_IDS=123456789012345678,987654321098765432

白名单的解析逻辑见 auth.ts：环境变量按逗号切分、逐个 trim，并过滤掉非纯数字的条目（Discord 用户 ID 是 snowflake，即纯数字字符串）。白名单为空数组时即“开放访问”，任何用户都可触发 Bot（auth.ts）。

在适配器启动时，会依据白名单是否生效记录discord.whitelist_enabled（含用户数量）或discord.whitelist_disabled日志（adapter.ts）。未被授权的用户发消息会被静默拒绝（discord.unauthorized_message日志会对用户 ID 做脱敏，仅保留前 4 位，如1234***），不会收到任何提示（adapter.ts）。

配置流式模式（可选）

DISCORD_STREAMING_MODE=batch # batch（默认） | stream

• batch（默认）：整段响应完成后一次性发送；
• stream：响应边生成边发送，体验更接近打字机效果。

该变量在 server/src/index.ts 中被读取，并以'stream' | 'batch'类型传入DiscordAdapter构造器，通过getStreamingMode()方法供上层查询（adapter.ts）。测试用例 adapter.test.ts 验证了三种情形：不传参数时默认stream，显式传入batch或stream时分别返回对应值。完整的流式配置说明可参考 Configuration 文档。

配置 @提及要求（可选）

默认情况下，Bot只在服务器频道中被 @提及 时才会响应（私信 DM 除外）。在单人使用或私有服务器上，可以关闭该限制，让 Bot 响应任意已授权消息：

DISCORD_REQUIRE_MENTION=false # true（默认） | false

这个开关的实现非常严谨，值得注意两个细节（server/src/discord-mention.ts）：

• 只有字面量false才能关闭 @提及要求：实现为env.DISCORD_REQUIRE_MENTION !== 'false'，即true、FALSE、0、空字符串等任何其他取值都会保持开启状态（对应测试 discord-mention.test.ts）；
• 提及剥离是无条件的：即使DISCORD_REQUIRE_MENTION=false，消息中已经存在的 @提及仍然会被从消息内容中剥离。

server 侧的处理流程（server/src/index.ts）为：私信（!message.guild）永远不需要提及；服务器消息则需要isDiscordMentionRequired()与isBotMentioned(message)同时成立才会继续处理。

使用方式

Bot 支持三种交互场景：

• 私信（Direct Messages）：直接发送消息即可，无需 @提及；
• 服务器频道：@提及 Bot 后再发送指令（如@YourBotName help me with this code）——或在DISCORD_REQUIRE_MENTION=false时直接发送任意已授权消息；
• 线程（Threads）：Bot 在线程中维持上下文，可进行多轮连续对话。

深入理解：适配器的底层实现机制

文档之外，仓库源码揭示了几个值得了解的实现细节，帮助你更好地理解它的行为边界。

线程会话机制：频道消息自动开线程

这是适配器最有特色的行为。当用户在服务器频道（非线程、非私信）中触发 Bot 时，ensureThread()会自动从该消息创建一个线程，后续响应都在线程内进行（adapter.ts）：

• 线程名取自消息内容的前 100 个字符（Discord 名称上限），超过 97 字符时截断并追加...，空白符会被归一化为单个空格，纯提及消息会得到默认名Bot Response（generateThreadName）；
• 线程自动归档时间设为1 天（ThreadAutoArchiveDuration.OneDay，即 1440 分钟），reason 为Bot response thread；
• 并发去重：多个并发消息触发时，通过pendingThreadsMap 按频道ID:消息ID去重，保证同一消息只创建一次线程（adapter.test.ts）；
• 失败降级：线程创建失败（如权限不足）时回退到原频道 ID，不影响消息处理；
• 会话 ID 取message.channelId：线程消息的 channelId 即线程 ID，因此每个线程天然拥有独立的对话上下文（getConversationId）。

server 侧还会在线程内拉取最近最多 100 条消息历史作为上下文（fetchThreadHistory，按时间正序、Bot 消息标注[Bot]前缀），并关联父频道 ID 以继承上下文（server/src/index.ts、adapter.ts）。消息处理统一由lockManager.acquireLock(conversationId, ...)串行化，避免同一会话并发冲突。

2000 字符上限与段落分片

Discord 单条消息上限为 2000 字符。适配器的sendMessage会先检查长度：不超过 2000 直接发送；超过则调用splitIntoParagraphChunks(message, 1900)进行两遍分片（adapter.ts）：

1. 第一遍按段落（\n\n）切分，逐段累积到接近上限；
2. 第二遍兜底：仍超长的块再按单行（\n）切分（message-splitting.ts）。

对应的 adapter.test.ts 验证了 1500+1500 字符的拼接消息会被拆成多条发送。这样长代码输出、长文档摘要都不会被 Discord 截断。

消息过滤与提及剥离

start()注册的MessageCreate事件处理器做了三层过滤（adapter.ts）：

1. 无作者的（系统消息、partials、webhook）直接忽略；
2. Bot 自身消息忽略，防止自我触发死循环；
3. 白名单校验（见上文）。

stripBotMention使用正则<@!?BOT_ID>\s*全局移除提及（兼容<@ID>与带昵称的<@!ID>两种格式），测试覆盖了多次提及、混合格式、提及在句尾、提及后无空格等边界情况（adapter.test.ts）。

平台无关的消息上下文

适配器通过 types.ts 中的DiscordMessageContext向 server 传递规范化数据（message、platformUserId、displayName），server 无需了解 discord.js 内部结构；随后通过resolveUserId('discord', platformUserId, displayName)将 Discord snowflake 映射为 Archon 用户 UUID（首次出现时自动创建用户，server/src/index.ts）。

故障排查速查表

进一步阅读

• Configuration 环境变量总览
• 社区 Chat 适配器开发指南（接口与注册示例）
• Discord 适配器源码与测试：adapter.ts、auth.ts、types.ts、adapter.test.ts
• 消息分片工具：message-splitting.ts

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon