Hermes 多端消息网关——Telegram、微信与可靠投递

1.1 CLI Agent#

CLI Agent 的典型路径是：

1
用户终端
2
   │ stdin / keyboard
3
   ▼
4
本地 Agent 进程
5
   ├── 模型 API
6
   ├── 本地文件系统
7
   ├── Shell / 工具
8
   └── stdout / TUI

它的几个基本假设是：

1. 用户与 Agent 进程处在同一个交互生命周期中。 终端关闭、进程退出，交互通常就结束。

2. 用户输入与输出通道天然一一对应。 当前 stdin 的输入，通常就回到当前 stdout。

3. 身份问题相对简单。 操作系统用户、当前工作目录和本地配置往往已经构成主要信任边界。

4. 审批可以同步进行。 Agent 请求执行危险命令时，可以直接在终端弹出确认。

5. 结果交付通常不需要独立持久化。 模型完成后打印到终端即可；若进程在打印前崩溃，常被视为任务失败，而不是“任务完成但最后一公里未送达”。

CLI Agent 的网络层重点是模型链路和工具链路，而不是消息平台的路由与投递。

1.2 IDE Agent#

IDE Agent 通常拆成多个进程或组件：

1
Webview / Chat Panel
2
        │
3
Extension Host
4
        │
5
Agent Runtime
6
   ├── Model Provider
7
   ├── MCP / Tools
8
   └── Workspace

与 CLI 相比，它多出几类状态：

• Webview 与 Extension Host 的 IPC；
• 编辑器窗口、Workspace、选中文件和 Diff 状态；
• IDE 重载后的会话恢复；
• UI 面板中的渐进式输出和审批交互；
• 插件进程与本地工具进程的生命周期。

但 IDE Agent 仍然大多依附于用户当前打开的 IDE。它面对的主要是“本地交互界面”和“编辑器状态”问题，而不是长期在线的跨平台消息交付。

1.3 长期运行的消息 Gateway#

Hermes 的拓扑不同：

Gateway 拓扑改变了系统的基本约束：

• 进程长期存在：即使没有用户输入，也要保持平台连接、执行 Cron、清理会话和处理恢复。
• 多来源输入：同一进程接收多个平台、多个 Chat、多个线程和多个用户的事件。
• 异步交互：用户可以在 Agent 执行过程中离线，任务仍然继续。
• 身份与路由是第一等状态：每条消息必须知道来自哪个平台、哪个 Chat、哪个 Thread、哪个用户，最终也必须回到正确位置。
• 执行完成与投递完成分离：Agent 生成了最终结果，不代表用户已经收到。
• 平台能力不对称：有的平台支持编辑、Typing、Thread 和语音；有的平台只支持一次性发送文本。
• 崩溃恢复必须跨进程：会话、待投递消息和恢复边界不能只放在内存里。

可以把三种架构的关注点概括为：

Hermes 官方开发文档给出的统一链路是：

1
User ↔ Messaging Platform ↔ Platform Adapter ↔ Gateway Runner ↔ AIAgent

Adapter 负责适配外部平台，Gateway Runner 负责授权、会话和调度，AIAgent 负责实际推理与工具执行。²

2.1 Platform Adapter#

所有平台 Adapter 都继承统一的 BasePlatformAdapter，至少实现：

• connect()：建立长连接、启动 Long Poll、启动 HTTP Server，或初始化 SDK；
• disconnect()：清理连接和后台任务；
• send()：向目标 Chat 发送文本；
• send_typing()：可选，发送 Typing Indicator；
• get_chat_info()：可选，补充 Chat 元数据；
• handle_message(event)：把归一化事件交给 Gateway Runner。²

Adapter 的职责不是简单封装一个 SDK。它至少承担六类转换：

1. 连接转换 把 Telegram Long Poll、Discord Gateway、Slack Socket Mode、WeCom WebSocket、Webhook 等不同接入方式统一为“收到 MessageEvent”。

2. 身份转换 从平台原始事件中抽取 User ID、Chat ID、Thread ID、Message ID、Workspace/Guild Scope。

3. 内容转换 把文本、图片、语音、文件、Reply、Mention 转成统一字段。

4. 授权前置检查 某些平台会在 Adapter 层就检查用户或群组策略，减少未授权事件进入核心 Gateway。

5. 输出格式转换 将统一的文本、Markdown、附件和 Thread 元数据翻译成平台 API 参数。

6. 平台故障分类 区分网络瞬时失败、认证失败、限流、不可恢复配置错误和平台拒绝。

平台 Adapter 的设计目标是：上层 Gateway 不应知道 Telegram 的 message_thread_id、Slack 的 thread_ts 或 Weixin 的 context_token 如何工作，只需要处理统一的消息与交付结果。

2.2 Per-chat Session Store#

Hermes 使用 SessionSource 描述一条消息从哪里来，主要字段包括：

1
platform
2
chat_id
3
chat_type
4
user_id
5
thread_id
6
message_id
7
scope_id
8
parent_chat_id
9
profile

这些字段共同参与路由、隔离和上下文注入。³

Session Store 不直接把“用户 ID”当作唯一会话键，而是生成一个确定性的 Session Key：

1
agent:main:{platform}:{chat_type}[:{chat_id}][:{thread_id}][:{participant_id}]

这样做有几个直接效果：

• Telegram 私聊 A 与私聊 B 不共享上下文；
• 同一群组中的不同 Topic 可以独立；
• Discord Guild、Slack Workspace 可以通过 scope_id 形成更高层隔离；
• 同一个用户在 Telegram 与微信上的对话默认不合并；
• 同一 Chat 内是否按用户隔离，可以通过策略控制；
• Gateway 重启后，可以根据 Session Key 找回原有 Session ID 和 Transcript。

Hermes 的 Session Store 同时维护：

• Session Key 到 Session ID 的映射；
• 会话起止时间和最近活跃时间；
• 消息 Transcript；
• Token 和成本统计；
• suspended、resume_pending 等恢复标记；
• 会话来源和结果投递路由。

官方 Session Lifecycle 文档指出，SQLite 是消息 Transcript 的规范存储，sessions.json 保留 Session Key 到 Session ID 的映射和元数据；当会话因重启中断时，resume_pending 可以保留原 Session ID，而 /stop 或强制挂起产生的 suspended 则会在下次访问时强制创建新会话。⁴

2.3 AIAgent Runtime#

Gateway 本身不负责推理。它在确认授权、找到 Session、准备平台上下文后，把消息交给 AIAgent。

AIAgent Runtime 仍然负责传统 Agent 的工作：

• 构造模型上下文；
• 调用模型；
• 解析 Tool Call；
• 执行 Shell、GitHub、MCP 等工具；
• 回填 Tool Result；
• 多轮迭代；
• 生成最终答案。

Gateway 为 Runtime 增加的是外部上下文：

• 当前平台；
• Chat 类型；
• 用户与群组信息；
• Thread 信息；
• 可用的发送渠道；
• 当前 Session ID；
• Approval Channel；
• 平台能力，例如能否编辑消息、发送语音或显示按钮。

这使模型不仅知道“任务是什么”，也知道“结果最终要交付到什么地方”。

2.4 Cron Scheduler#

Gateway 不只响应用户输入，还要运行定时任务。官方架构文档显示，Cron Scheduler 与 Session Store 和 Adapter 共享 Gateway 进程，按固定周期检查到期任务，并将结果投递到配置的 Home Channel。Messaging Gateway 文档当前描述的默认 Tick 周期是 60 秒。¹

Cron 带来一个重要语义差异：

• 普通消息是“用户输入驱动”；
• Cron 是“时间驱动”；
• 后台任务是“任务完成驱动”。

三者最终都通过 Delivery 层发消息，但不应强行写入同一个用户聊天 Transcript。Hermes 明确规定，Cron 交付保留在自己的 Cron Session 中，不镜像回普通 Gateway 会话，以避免对话角色交替被破坏。⁵

2.5 Delivery Ledger#

Delivery Ledger 是 Hermes 区别于普通 Bot Demo 的关键部件。

当 Agent 已经生成最终回复时，这段回复可能只存在于 Python 局部变量中。若 Gateway 在以下时刻崩溃：

1
Agent 完成
2
   ↓
3
开始调用平台 send()
4
   ↓
5
平台已收到，但 ACK 尚未返回
6
   ↓
7
Gateway 崩溃

系统无法知道用户是否已收到消息。若不持久化：

• 不重发：可能永久丢失结果；
• 直接重发：可能产生静默重复；
• 重跑 Agent：可能重复修改仓库、重复创建 PR、再次消耗模型 Token。

Hermes 因此把最终回复先记录为一个持久化“交付义务”，再执行平台发送。具体状态为：

1
pending → attempting → delivered
2
                    ↘ failed
3
                    ↘ abandoned

这部分将在第 9 节深入分析。

3.1 Telegram Bot API#

Telegram Bot API 基于 HTTPS。Bot 接收更新有两种互斥方式：

• getUpdates Long Poll；
• setWebhook 注册的 HTTPS Webhook。

同一个 Bot 不能同时使用两者。Telegram 使用单调递增的 update_id 帮助客户端确认和去重；未获取的 Update 最多在服务端保留 24 小时。⁶

Hermes 的 Telegram Adapter 基于 python-telegram-bot，负责：

• 接收私聊、群聊、Topic 和命令；
• 发送文本、图片、文件和语音；
• Typing Indicator；
• 消息编辑和渐进式输出；
• Reply 与 Thread 路由；
• 网络超时、初始化失败和代理处理。⁷

Telegram 接入的工程重点不是 HTTP 请求本身，而是：

1. Long Poll 连接需要持续续期；
2. update_id 必须去重；
3. Bot Token 缺失属于不可恢复配置错误，网络抖动属于可恢复错误；
4. Topic 和私聊 Topic 的 Reply Anchor 语义不同；
5. 文本长度按 UTF-16 Code Unit 计算，而不是 Python 字符数；
6. 流式编辑过快会触发 Flood Control；
7. Telegram 返回的文件 URL 会过期，需要及时下载到本地缓存。

3.2 Weixin 与 WeCom#

“微信”在 Hermes 中对应两条不同链路。

3.3 Discord Gateway#

Discord Gateway 是持久 WebSocket 协议。客户端建立连接后：

1. 服务端发送 Hello，包含 Heartbeat Interval；
2. 客户端按周期发送 Heartbeat；
3. 服务端回 Heartbeat ACK；
4. 事件带序列号 s；
5. 断线后可通过 session_id、resume_gateway_url 和最后序列号发送 Resume；
6. 服务端可能重放断线期间遗漏的事件。¹⁰

Hermes 的 Discord Adapter 使用 discord.py，额外处理：

• Guild、Channel、Thread 和 DM；
• Slash Command；
• 自动 Thread；
• Mention 与 Reply；
• Message Component 字段的 UTF-16 长度；
• 附件下载和 SSRF Redirect Guard；
• 启动 Ready 超时；
• WebSocket 关闭超时后的底层 Transport Abort。¹¹

Discord 的恢复重点是：重连不等于新会话。Gateway 可以恢复平台 WebSocket，而 Hermes Session 仍然保持不变。

3.4 Slack Socket Mode#

Slack Socket Mode 允许 App 主动建立 WebSocket，而无需公开 Webhook Endpoint。连接 URL 通过 apps.connections.open 获取，Slack 会定期要求刷新连接。每个事件包含 envelope_id，客户端必须 ACK；Slack 支持同时维护多条 Socket 连接以提高可用性。¹²

Hermes 的 Slack Adapter 使用 slack-bolt 和 AsyncSocketModeHandler，支持：

• Channel 和 DM；
• Slash Command；
• Thread；
• Workspace 隔离；
• Web API 出站发送；
• Thread Context 获取；
• Markdown 到 Slack mrkdwn 的转换；
• 多用户并发 Slash Command 的 ContextVar 隔离。¹³

Slack 的关键路由字段不只有 Channel ID，还包括：

• Team/Workspace ID；
• Thread TS；
• User ID；
• Envelope ID；
• Slash Command 的 response_url。

其中 Workspace ID 属于持久路由状态，必须跨流式、异步和恢复边界保留，不能在发送时退回“默认 Workspace”。

3.5 Webhook#

Webhook 模式中，平台通过 HTTP POST 把事件推给 Gateway。正确实现至少要处理：

• Endpoint 身份验证；
• 签名校验；
• 时间戳和重放窗口；
• Event ID 去重；
• 快速 ACK；
• 异步执行长任务；
• 出站 API 与入站 Webhook 分离；
• 重试造成的重复事件。

Webhook 的核心语义是：

平台收到 2xx，只代表 Gateway 接收了事件，不代表 Agent 已完成任务。

因此 Webhook Handler 不应同步等待几分钟的 Agent Turn。更稳妥的做法是：

1. 验证并持久化入站事件；
2. 立即返回 ACK；
3. 在后台交给 Session Queue；
4. 最终通过独立出站 API 交付结果。

3.6 轮询型平台#

Long Poll 的抽象流程是：

1
cursor = last_confirmed_cursor
2

3
loop:
4
    events, next_cursor = poll(cursor, timeout)
5
    for event in events:
6
        if not deduplicated(event.id):
7
            normalize_and_dispatch(event)
8
    persist(next_cursor)

可靠的轮询 Adapter 需要：

• 持久化 Cursor/Offset；
• 允许重复获取同一批事件；
• 使用 Event ID 去重；
• 对空结果正常续轮；
• 对超时快速重建请求；
• 对 429 和服务端错误使用退避；
• 避免并发启动两条 Poll Loop；
• 在断开时关闭旧连接池。

Weixin 和 Telegram Long Poll 都属于这种模式，但它们的 Cursor、Session 和回复约束不同，不能共享平台实现，只能共享抽象原则。

4.1 User ID#

User ID 的用途不只是显示用户名，还包括：

• Allowlist；
• DM Pairing；
• Per-user Session Isolation；
• 审批权限；
• 审计；
• 消息归属；
• 防止 Bot/Webhook 冒充用户。

需要注意：

1. 不同平台的 User ID 不可直接比较；
2. 某些平台同时有短期 ID 和稳定 Alt ID；
3. 显示名称不是身份标识；
4. 日志中应按平台策略做哈希或脱敏；
5. 跨平台“同一个人”不能凭昵称自动合并。

Hermes 的 SessionSource 同时保留 user_id 与 user_id_alt，就是为了处理 Signal UUID、Feishu Union ID 等稳定身份差异。³

4.2 Chat ID#

Chat ID 表示交付目的地，是最重要的路由字段。

它可能代表：

• Telegram 私聊；
• Telegram Group；
• Discord Channel；
• Slack Channel；
• Weixin Peer；
• WeCom Group；
• Webhook 的逻辑 Channel。

Chat ID 必须带 Platform Namespace 使用。裸字符串 12345 不足以构成全局唯一键：

1
telegram:dm:12345
2
discord:channel:12345
3
weixin:dm:12345

4.3 Thread ID#

Thread ID 把一个 Chat 进一步拆成多条会话 Lane。

典型例子：

• Telegram Forum Topic；
• Telegram DM Topic；
• Discord Thread；
• Slack thread_ts；
• Feishu Thread。

Thread ID 的关键不是“显示在哪个 UI 里”，而是决定：

• Session 是否独立；
• 回复发送到哪里；
• 是否继承父 Channel 的 Model/System Prompt Override；
• /stop 应取消当前 Thread 还是整个 Chat；
• 结果恢复时回到哪个 Lane。

Hermes 默认让 Group Session 按用户隔离，而 Thread 默认共享；这些规则可配置。⁴

4.4 Message ID#

Message ID 用于：

• Reply Anchor；
• 去重；
• 编辑；
• Reaction；
• Pin；
• 生成 Delivery Obligation ID；
• 区分同一 Session 中的不同 Turn。

入站事件可能被平台重复推送，因此不能把“成功收到一次 HTTP 请求”当作唯一性保证。Adapter 应对 Message ID、Update ID 或 Envelope ID 建立去重窗口。

4.5 Reply Anchor#

“回复这条消息”在不同平台里并不是同一件事：

• Telegram 普通群聊可使用 Reply ID；
• Telegram Forum Topic 更依赖 message_thread_id；
• Telegram 私聊 Topic 可能同时需要 Topic ID 和触发消息 ID；
• Slack Thread 使用 Thread TS；
• Discord Thread 通常通过 Channel/Thread 本身路由；
• 某些跨频道 Handoff 必须刻意发送为顶层消息，不能误用 Reply Anchor。

Hermes 的 Base Adapter 专门生成平台感知的 Thread Metadata，并对 Telegram 私聊 Topic、群组 Topic、Slack Thread Handoff 等路径做不同处理。¹⁴

这说明 Reply Anchor 不是 UI 装饰，而是交付地址的一部分。

4.6 文件、图片和语音#

媒体归一化通常包含两步：

1. Adapter 从平台下载内容；
2. Gateway 缓存为本地文件，让 Agent Tool 使用本地路径。

这样做的原因包括：

• 平台文件 URL 会过期；
• 后续 Vision/STT Tool 需要本地文件；
• 重试时不应再次依赖平台临时 URL；
• 需要统一做大小限制和 MIME 校验；
• 需要防止 SSRF 和恶意 Redirect；
• 需要在不同平台格式之间转换。

Hermes Base Adapter 对入站媒体设置统一大小上限，默认 128 MiB，可配置；还会校验图片 Magic Bytes、限制下载流量，并对 Redirect 重新执行 SSRF 检查。¹⁵

语音处理还要处理容器格式差异。例如 Telegram 的普通 Audio 与 Voice Bubble 支持的格式不同；Hermes 会根据平台和文件扩展名决定使用原生 Voice、Audio 还是普通 Document。

5.1 一个 Chat 对应一个 Session#

最简单的规则是：

1
Session Key = Platform + Chat Type + Chat ID

这保证一个 Chat 的多条消息共享上下文，同时不同 Chat 隔离。

但真实平台还需要 Thread、Participant、Scope 和 Profile：

1
agent:main:{profile}:{platform}:{scope}:{chat_type}:{chat_id}:{thread_id}:{participant_id}

其中有些字段按需省略。Hermes 官方实现使用确定性 Key，而不是每次创建随机会话；这样 Gateway 重启后仍能重新找到原 Session。⁴

5.2 群聊和私聊隔离#

私聊通常天然一人一会话：

1
telegram:dm:alice
2
telegram:dm:bob

群聊则有两种策略：

1
telegram:group:team-chat

1
telegram:group:team-chat:user-alice
2
telegram:group:team-chat:user-bob

5.3 Thread 继承#

Thread 既要独立，又需要继承父级策略。

可继承的内容包括：

• 平台与 Workspace Scope；
• 父 Channel Allowlist；
• Channel Model Override；
• System Prompt Override；
• Home Channel；
• 代理与凭证；
• 格式和消息长度能力。

不应继承的内容包括：

• 父 Channel 的完整对话 Transcript；
• 其他 Thread 的 Pending Tool State；
• 其他 Thread 的 /stop 信号；
• 其他 Thread 的 Delivery ID。

合理的路由方式是：

1
父级提供策略
2
Thread 提供会话边界
3
Message 提供当前 Turn Anchor

5.4 用户权限和 Allowlist#

Hermes Gateway 默认拒绝未在 Allowlist 中、也未完成 DM Pairing 的用户。官方授权顺序为：

1. 平台级 Allow-all；
2. 平台 Allowlist；
3. DM Pairing；
4. 全局 Allow-all；
5. 默认拒绝。⁵

这是必要的，因为 Gateway 背后的 Agent 可能拥有：

• Shell；
• GitHub；
• 文件系统；
• 浏览器；
• 企业 API；
• 通知能力。

一个普通聊天 Bot 的未授权消息最多造成垃圾回复；一个带 Shell 的 Agent 则可能执行真实副作用。

权限判断至少应绑定：

1
Platform
2
Scope / Workspace / Guild
3
Chat
4
User
5
Role
6
Command
7
Tool Risk

Hermes 还提供 /approve、/deny，让危险工具的审批可以在移动端完成。审批命令需要绕过“当前 Agent 正在运行”的普通消息 Guard，直接到达等待中的权限请求，否则会形成死锁。⁵

5.5 跨平台会话边界#

默认情况下，Telegram 上的 Alice 与微信上的 Alice 是两个不同身份、两个不同 Session。

跨平台自动合并会产生严重问题：

• 昵称可能相同但不是同一个人；
• 一个平台的认证强度可能低于另一个；
• 群聊上下文可能被带入私聊；
• Delivery 路由可能错发；
• 审批权限可能被跨平台提升。

因此，跨平台会话合并必须是显式能力，至少需要：

• 账户绑定；
• 双向验证；
• 明确的 Canonical User ID；
• 可撤销映射；
• 审计日志；
• 来源标记；
• 权限取交集而非并集。

Hermes 支持跨平台发送，但这不等于跨平台会话自动合并。Cross-platform Delivery 应被视为一个显式工具动作，而不是隐式 Session 共享。⁵

6.1 Typing Indicator#

Typing Indicator 的目的不是装饰，而是填补 Time to First Visible Feedback。

一个完整回复可能经历：

1
用户发送消息
2
→ Gateway 路由
3
→ Agent 构造上下文
4
→ 模型首 Token
5
→ 多轮工具执行
6
→ 最终回复

若没有 Typing Indicator，用户会把几秒到几分钟的等待误认为 Bot 离线。

但 Typing Indicator 也有生命周期：

• 周期刷新；
• Turn 完成后停止；
• /stop 后立即停止；
• Gateway 重启后不恢复旧 Indicator；
• 平台不支持时静默降级；
• 不应因 Typing 失败影响主任务。

Weixin 有专门的 sendtyping API；Telegram、Discord、Slack 也有各自的 Typing/Presence 机制，但支持范围和持续时间不同。

6.2 Progressive Message Edit#

支持消息编辑的平台，可以先发送一条 Preview，再逐步编辑：

1
send("正在分析… ▌") → message_id
2
edit(message_id, "已读取仓库… ▌")
3
edit(message_id, "发现问题位于… ▌")
4
edit(message_id, "最终答案")

相比连续发送几十条消息，这种方式：

• 减少消息噪声；
• 保持上下文集中；
• 更接近 CLI 流式体验；
• 降低通知数量。

但必须控制编辑频率。Hermes Stream Consumer 使用：

• Edit Interval；
• Buffer Threshold；
• Cursor；
• Flood-control Strikes；
• Adaptive Backoff；
• Final Fresh Message；
• Draft/Edit/Off Transport 切换。¹⁶

当连续编辑多次触发 Flood Control 时，系统会停止渐进编辑，保留最终发送，避免为了“看起来实时”而丢失真正结果。

6.3 文本分段#

消息平台有长度限制。Gateway 不能简单用 text[:limit] 截断，因为会破坏：

• Unicode；
• Markdown；
• Code Fence；
• 表格；
• 链接；
• Tool Result；
• 语义段落。

更合理的分段顺序是：

1. 按完整消息块；
2. 按段落；
3. 按换行；
4. 按句子；
5. 按空格；
6. 最后按平台字符计量单位硬切。

分段还需要记录 Continuation Message ID。若流式输出超过单条消息上限，后续 Edit 不能继续编辑第一条，而要创建新的消息段，并确保 Finalization 不重复发送已经展示的前缀。

6.4 平台长度限制#

不同平台的“字符数”定义也不同。

例如 Telegram 的单条文本上限是 4096 个 UTF-16 Code Unit。一个 Emoji 或某些扩展汉字可能占两个 Unit，因此 Python len(text) 不能直接作为上限。Hermes 专门实现 UTF-16 长度和安全前缀切割。¹⁴

WeCom Adapter 当前设置 4000 字符上限，并会对接近上限的连续输入进行批处理，以识别客户端拆分。⁹

因此，Gateway 的统一输出接口应提供：

1
adapter.measure_text(text)
2
adapter.max_message_length
3
adapter.split_message(text)

而不是在核心层写死一个通用数字。

6.5 Markdown 转换#

模型输出通常接近 CommonMark/GFM，但平台格式并不兼容：

• Telegram MarkdownV2 有严格转义；
• Discord 支持一部分 Markdown；
• Slack 使用 mrkdwn，不原生渲染 GFM Table；
• WeCom 使用自己的 Markdown 子集；
• Weixin 可能需要转换为纯文本块；
• Code Fence 未闭合会污染整个后续消息。

Hermes 的 Slack Adapter 会识别 GFM Pipe Table，把表格转成等宽 Code Block，并按 CJK 显示宽度补齐列；Stream Consumer 会在最终发送前补齐未闭合的三反引号和 Inline Backtick，防止整条消息渲染错误。¹³¹⁶

Markdown 转换的正确位置是 Platform Adapter 或 Render Layer，而不是修改 Agent 原始答案。这样可以同时保留：

• 原始语义内容；
• 平台渲染结果；
• Delivery Ledger 中可重放的规范内容；
• 审计和故障定位能力。

6.6 图片、文件和语音回复#

多模态交付至少包含三类路径：

1
{
2
  "success": true,
3
  "message_id": "...",
4
  "media_ids": ["..."],
5
  "platform": "telegram",
6
  "chat_id": "...",
7
  "thread_id": "...",
8
  "delivered_at": "..."
9
}

7.1 同一会话串行#

Hermes 使用两级 Running-agent Guard：

1. Base Adapter 在事件进入 Gateway Runner 前检查 Session 是否活跃；
2. Gateway Runner 再检查当前 Session 是否已有 Agent 在运行。⁵

当同一 Session 正在运行时，普通消息可以：

• 入队；
• 触发 Interrupt；
• 被 /queue 显式排队；
• 根据 Busy Mode 合并；
• 等待当前 Turn 结束。

不能直接启动第二个 AIAgent 共用同一 Transcript，否则会出现：

1
Turn A 读取历史 H
2
Turn B 也读取历史 H
3
Turn A 写入 Tool Result A
4
Turn B 写入 Tool Result B
5
最终历史顺序不确定

这会破坏模型上下文、工具副作用和消息角色交替。

7.2 不同会话并行#

不同 Session 可以并行运行，但要受全局上限约束：

1
max_concurrent_sessions

当活跃 Session 达到上限时，新 Session 会收到明确的容量提示，而 /status 等轻量控制命令仍可绕过限制。Hermes 的测试明确验证了这一行为。¹⁷

合理的并发策略应至少区分：

• 活跃前台 Session；
• 后台任务；
• Cron；
• 消息投递；
• Typing Refresh；
• Platform Reconnect；
• Media Download。

不能用一个 Semaphore 把所有任务粗暴锁死，否则长 Agent Turn 可能阻止平台心跳，最终造成全局断线。

7.3 /stop 与任务取消#

/stop 不是普通消息。它必须：

1. 绕过当前 Session 的排队；
2. 找到正在运行的 AIAgent；
3. 触发 Cancellation/Interrupt；
4. 终止或标记当前工具；
5. 停止流式编辑和 Typing；
6. 清理 Pending Approval；
7. 更新 Session 状态；
8. 防止旧的异步 Delta 在新 Session 中继续发送。

Gateway Runner 对 /stop、/approve、/deny 等命令执行 Inline Dispatch，就是为了避免它们被正在等待的 Agent 自己阻塞。⁵

取消的正确语义是：

停止当前执行，不等于删除历史；停止旧 Turn，也不允许旧回调继续污染新 Turn。

7.4 后台任务#

/background <prompt> 把任务放入独立后台 Session，而不是继续占用当前 Chat 的前台 Turn。

后台任务需要独立维护：

• Session ID；
• Cancel Token；
• Tool Process；
• Completion Notification；
• Result Delivery Target；
• 资源预算；
• 重启后的处理策略。

若后台任务与当前 Chat 共享同一 Session，后续用户输入会与后台 Tool Result 交错，造成上下文污染。

7.5 Gateway 重启后的 Session 恢复#

Gateway 重启后有两类状态：

8.1 长连接断开#

不同平台的长连接恢复机制不同：

1
Platform Connection: disconnected / connecting / ready
2
Agent Session: active / idle / resume_pending / suspended
3
Delivery: pending / attempting / delivered / failed

8.2 Webhook 重复事件#

Webhook 重复是正常现象，不是异常。

平台可能因为：

• ACK 超时；
• 网络抖动；
• 服务端重试；
• Gateway 重启；
• 负载均衡切换；

再次发送同一事件。

正确的入站去重键通常是：

1
Platform + Scope + Event ID

如果平台没有 Event ID，可退化到：

1
Platform + Chat ID + Message ID + Event Type

去重记录必须有 TTL，避免无限增长；但 TTL 不能短到平台正常重试窗口内失效。Weixin 当前使用 300 秒去重 TTL；WeCom 使用有界 Message Deduplicator。⁸⁹

8.3 平台 API 429#

平台 429 与模型 429 类似，但恢复动作不同：

• Telegram Flood Control 可能要求等待指定秒数；
• Discord/Slack API 有 Method/Route/Workspace 级限流；
• Weixin 有平台特定 Rate-limit Error Code；
• 媒体上传与普通文本可能使用不同 Bucket；
• 编辑消息与发送新消息可能分别限流。

Adapter 应把平台错误规范化为：

1
retryable
2
retry_after
3
scope
4
operation
5
platform_error_code
6
message

Outbound Queue 再按这些字段安排重试。不能在每个发送调用里各自 sleep()，否则同一 Chat 的多个消息会乱序。

8.4 消息编辑频率限制#

模型可能每几十毫秒产生一个 Delta，但平台不允许同样频率的 Edit。

Gateway 需要把 Token 流重整为较低频率的 UI 更新：

1
高频 Token Delta
2
      ↓
3
字符阈值 + 时间阈值
4
      ↓
5
每 0.x ～数秒一次 Edit
6
      ↓
7
遇到 429 增大间隔
8
      ↓
9
连续失败后关闭 Progressive Edit
10
      ↓
11
最终消息必须保留

Hermes Stream Consumer 记录 Flood Strike，并动态提高 Edit Interval；达到阈值后禁用本轮渐进编辑，转而保证最终发送。¹⁶

这里的优先级应始终是：

1
最终结果送达 > 渐进展示完整 > 实时性

8.5 代理和网络切换#

Gateway 是长期进程，网络环境可能变化：

• 企业代理切换；
• VPN 启停；
• DNS 污染；
• 代理凭证过期；
• NO_PROXY 改变；
• SOCKS 连接重建；
• TLS CA 更新；
• 平台域名解析变化。

Hermes Base Adapter 的代理解析顺序为：

1. 平台专用代理变量；
2. HTTPS_PROXY / HTTP_PROXY / ALL_PROXY；
3. macOS 系统代理；
4. NO_PROXY 匹配则绕过代理。¹⁸

SOCKS 路径使用 Remote DNS，以避免本地 DNS 污染。网络切换后的正确处理不是重启所有 Agent Session，而是：

• 重建 Adapter 连接；
• 清理旧连接池；
• 保留 Session Store；
• 保留 Delivery Ledger；
• 对未确认出站消息进入恢复流程。

9.1 回复发送前持久化#

在任何平台 Send 之前，Gateway 先写入：

1
obligation_id
2
session_key
3
platform
4
chat_id
5
thread_id
6
content
7
state = pending
8
attempts = 0
9
owner_pid
10
owner_started_at
11
created_at

obligation_id 由：

1
session_key + inbound message_ref + content

哈希生成。同一个 Turn、同一内容重复记录，会得到同一个 ID，从而具备记录层幂等性。¹⁹

关键顺序是：

1
先 record_obligation()
2
再调用平台 send()

如果反过来，进程可能在 Send 成功后、写 Ledger 前崩溃，恢复系统将完全不知道这条回复存在。

9.2 平台确认后完成#

完整状态迁移是：

delivered 只能在 Adapter 返回明确成功后设置。HTTP 请求发出、Socket Write 成功、平台返回 2xx，分别代表不同层次，Adapter 必须把“平台已接受”转成统一 SendResult.success。

9.3 Gateway 崩溃后的重新投递#

Gateway 启动时执行 sweep_recoverable()：

1. 扫描 pending、attempting、failed；
2. 检查原 Owner PID 和进程启动时间；
3. 若原进程仍存活，不抢占；
4. 若原进程已死亡，原子 Claim；
5. Attempts 加一；
6. 仅 Claim 当前启动中有可用 Adapter 的平台；
7. 返回待重投记录；
8. Adapter 重新发送。¹⁹

这种 Owner Stamp 不只检查 PID，还检查 Process Start Time，避免操作系统复用 PID 后误判旧进程仍存活。

9.4 At-least-once 语义#

Hermes 选择的是“诚实的 At-least-once”：

9.5 可能重复时显式提示#

对于 attempting 或 failed，Hermes 在重投内容前加可见前缀：

1
♻️ Recovered reply — the gateway restarted during delivery,
2
so this may be a duplicate:

这比静默重复更诚实。

分布式系统中的不确定性无法总被消除，但可以被：

• 记录；
• 限定；
• 暴露；
• 审计。

Hermes 当前限制：

• 最多 3 次重投；
• 最长 24 小时有效；
• Delivered/Abandoned 记录保留 7 天；
• 总行数有上限。¹⁹

9.6 为什么不重新运行整个 Agent Turn#

重新运行整个 Agent Turn 是最危险的恢复方式，因为原 Turn 可能已经：

• 修改文件；
• Push Branch；
• 创建 Pull Request；
• 发送外部通知；
• 调用付费 API；
• 写数据库；
• 消耗大量 Token。

Delivery Ledger 已经保存最终文本。恢复的目标只是“把这段结果交付给用户”，不是“重新计算一次结果”。

正确边界是：

1
Agent Execution State          Delivery State
2
已完成                         未确认

因此恢复动作应是：

1
重投最终消息

而不是：

1
重新执行用户任务

Delivery Ledger 本质上把“计算结果”和“结果交付”拆成两个独立事务。

11.1 Platform Adapter#

统一接口：

1
class PlatformAdapter:
2
    async def connect(self) -> bool: ...
3
    async def disconnect(self) -> None: ...
4
    async def send(
5
        self,
6
        chat_id: str,
7
        content: str,
8
        reply_to: str | None,
9
        metadata: dict | None
10
    ) -> SendResult: ...
11
    async def send_typing(self, chat_id: str) -> None: ...
12
    async def edit_message(
13
        self,
14
        chat_id: str,
15
        message_id: str,
16
        content: str
17
    ) -> SendResult: ...

Adapter 还应声明能力：

1
{
2
  "supports_threads": true,
3
  "supports_editing": true,
4
  "supports_typing": true,
5
  "supports_images": true,
6
  "supports_files": true,
7
  "supports_voice": false,
8
  "max_message_length": 4096,
9
  "length_unit": "utf16"
10
}

11.2 Normalized Message#

统一消息必须稳定表达：

• 来源 Platform；
• Scope；
• User；
• Chat；
• Thread；
• Message；
• Reply；
• 文本；
• 媒体；
• Update/Event ID；
• 授权上下文；
• 原始 Payload；
• 时间戳。

核心不变量：

1
Raw Platform Event
2
    ↓ Adapter
3
Normalized Message
4
    ↓ Gateway Core
5
任何平台走同一授权、会话和调度流程

11.3 Per-chat Session#

Session Key 至少包含：

1
Profile
2
Platform
3
Scope
4
Chat Type
5
Chat ID
6
Thread ID
7
Participant ID（按策略）

Session Store 需要：

• Transcript；
• Session ID；
• Origin；
• Reset Policy；
• Resume State；
• Token/Cost；
• Last Activity；
• Pending Background State。

11.4 Outbound Delivery Queue#

出站 Queue 负责：

• 同一 Chat 保序；
• 平台独立速率限制；
• Progressive Edit 节流；
• 文本分段；
• 媒体上传；
• Retry-After；
• 优先级；
• Final Message 优先；
• 连接不可用时等待。

合理的优先级可设为：

1
P0：Approval / Deny / Stop
2
P1：最终结果
3
P2：错误与状态
4
P3：Progressive Edit
5
P4：Typing Refresh

在资源紧张时，应先丢弃低优先级的 Typing 和 Edit，而不是最终结果。

11.5 Delivery Ledger#

Ledger 的最小字段：

1
delivery_id
2
session_key
3
platform
4
chat_id
5
thread_id
6
content_hash
7
content
8
state
9
attempts
10
owner
11
created_at
12
updated_at
13
last_error

状态机：

1
pending → attempting → delivered
2
                    ↘ failed
3
                    ↘ abandoned

核心不变量：

最终结果必须先持久化，再开始平台发送。

11.6 Rate Limit Adapter#

不同平台应提供统一限流结果：

1
@dataclass
2
class RateLimitDecision:
3
    retryable: bool
4
    retry_after: float | None
5
    bucket: str | None
6
    global_limit: bool
7
    operation: str

这样 Outbound Queue 可以统一调度，而不把 Telegram FloodWait、Discord Route Bucket、Slack Retry-After 和 Weixin Error Code 散落在业务逻辑中。

11.7 Approval Channel#

移动端 Approval 需要：

• Approval ID；
• Session Key；
• Tool Call ID；
• 操作摘要；
• 风险级别；
• 过期时间；
• Approve/Deny；
• 防重放；
• 授权用户校验。

Approval 必须绕过普通 Session Queue，直接唤醒等待中的 Agent。否则 Agent 等审批，审批消息又排在 Agent 后面，形成永久死锁。

11.8 Gateway Health Watchdog#

Health Watchdog 至少监控三层：

1. 会话状态#

1
用户是谁
2
来自哪个 Chat / Thread
3
历史上下文是什么
4
重启后是否继续同一个 Session

2. Agent 执行状态#

1
当前 Turn 是否运行
2
正在等待哪个 Tool
3
是否被 /stop
4
后台任务是否仍存活

3. 消息交付状态#

1
最终文本是否已生成
2
平台发送是否开始
3
平台是否确认
4
是否需要重投
5
是否可能重复

这三个状态的生命周期不同，也必须由不同组件负责：

一套生产级多端 Agent Gateway 应遵循五条原则：

1. 平台差异终止在 Adapter 边界。
2. Session Key 必须显式编码平台、Chat、Thread 和身份隔离。
3. 同一 Session 保序，不同 Session 有界并行。
4. 实时展示可以降级，最终结果不能丢失。
5. 执行完成不等于交付完成；未知交付结果必须诚实地采用 At-least-once。

这也是 Hermes 与普通 CLI Agent 最根本的区别：它不仅要让 Agent“完成任务”，还要在用户离线、平台限流、连接断开和 Gateway 重启的情况下，确保正确的用户最终能在正确的会话里收到结果。