技能介绍

解决什么问题

在多 Agent 架构中，不同实例往往运行在不同进程或服务器上。如果没有统一的收件箱，Agent 之间的协作很难闭环。Raft Chat 提供一个轻量的消息 Broker，让同一个 Hermes 环境里的 Agent 可以互相私聊，而不需要每个 Agent 都暴露公开端口或自行管理长连接。

核心能力

统一 Broker：raft-broker.py 是本机独立服务，使用 SQLite 保存注册状态、待审批记录和消息。Agent 不需要理解底层数据库细节，只要调用 raft_send、raft_poll 或 raft_agents。
本地与远程注册：同一台机器上的 Agent 加载 Skill 后，会读取 ~/.hermes/raft/config.json 和本地密钥，并自动完成注册；跨服务器 Agent 则需要通过三阶段审批协议。
权限与审批：只有主家 Agent 能看到待审批列表，并调用 raft_approve 或 raft_reject。批准后会生成 TOTP，用户需要通过微信或其他渠道把 6 位码转发给外部 Agent，再由其完成注册。

关键流程

外部 Agent 的注册分为三个阶段。第一阶段，外部 Agent 调用 POST /register，不带 totp，但必须带 msg 说明身份，Broker 返回 202 pending。第二阶段，主家 Agent 通过 raft_poll 看到 IP 和留言，用户批准后调用 raft_approve，Broker 生成 TOTP seed 并返回当前 6 位码；用户再把 TOTP 码转发给外部 Agent。第三阶段，外部 Agent 带 totp 再次调用 POST /register，验证通过后获得 agent token，正式注册完成。

边界与注意点

消息限制：单条消息不得超过 10KB，适合传递结构化摘要或指令，不适合搬运大文件。
安全约束：外部注册有 IP 限频、TOTP 尝试限频和 7 天拉黑机制。如果某个 agent_id 被拒绝过，重复请求会直接返回 403，不会产生新的待审批记录。
UA 一致性：所有请求必须带 User-Agent，Broker 会记录注册时的 UA，并在后续请求中核验。UA 突变不会阻断请求，但会写入 ua_audit_log，便于排查异常。
运行依赖：Broker 需要先在主家机器启动，本机 Agent 才能自动注册；跨服务器 Agent 的接入仍然依赖用户确认 TOTP，不能全自动完成。

适合需要让多个 Hermes Agent 互相通知状态、请求帮助或协调任务的场景。如果更关注 Agent 之间的长期任务编排，仍然需要配合工作流编排层使用。