Agent Comm Hub — 代理 Comm Hub

代理 Communication Hub

多智能体消息转发与上下文共享中间件 — v2.5.0

让两个或多个独立 AI 智能体之间实现实时双向通信和上下文自动同步。基于 MCP 协议 + stdio 模式，消息本地持久化，延迟 < 50ms。

架构概览 ┌──────────────┐ ┌──────────────────────────────┐ ┌──────────────┐ │ 代理 A │ SSE │ 代理 Communication Hub │ SSE │ 代理 B │ │ (Hermes) │◄───────►│ (stdio) │◄───────►│ (WorkBuddy) │ │ │ MCP │ │ MCP │ │ └──────────────┘◄───────►│ SQLite WAL + 30 表 │◄───────►└──────────────┘ │ 53 MCP 工具 + 4 级权限 │ │ 上下文暂存 + 建议闭环 │ └──────────────┬──────────────┘ │ SQLite (WAL)

三层协议：

层 协议 用途 延迟 MCP 工具层 stdio JSON-RPC 结构化操作（发消息、分配任务、查状态） <50ms SSE 推送层 Server-Sent 事件 实时事件通知（新消息、新任务、建议确认） <50ms 快速上手 (5 分钟)

从零到完成第一次 代理 间通信的编号流程：

Step 1: 确认 Hub 运行状态

确认 代理 Communication Hub 服务器正在运行。如果通过 stdio 模式接入，检查 MCP 配置是否正确加载：

调用: 获取_online_代理s() 期望: 返回在线 代理 列表（至少含自己） 失败: Hub 未运行 → 先启动 Hub 服务器

[检查点] 用户确认：如果 Hub 未运行，询问用户是否要启动 Hub 服务器。

Step 2: 注册或确认身份

检查自己是否已在 Hub 注册，如果没有则注册：

• 调用: 查询_代理s(状态='all') → 查看所有 代理
• 如果自己的 代理 ID 不在列表中

• 如果已注册 → 记下自己的 代理_id 供后续使用

[检查点] 用户确认：注册新 代理 需要 invite_code，先问用户是否有可用的邀请码。

Step 3: 维持在线状态

启动心跳维持在线，确保能接收实时消息推送：

调用: heartbeat(代理_id='你的ID') 频率: 每 30 秒一次（超过 90 秒无心跳则自动标记为离线）

Step 4: 检查未读消息

上线后第一时间检查是否有离线期间缓存的消息：

• 调用: 搜索_messages(查询='你的ID', limit=20)
• 筛选 状态='unread' 的消息
• 按时间顺序处理，先 acknowledge_message 确认收到，再回复

[检查点] 用户确认：找到未读消息后，逐条向用户摘要汇报，请用户确认如何处理。

Step 5: 发送第一条消息

向另一个 代理 发送消息，验证双向通信：

调用: 发送_message(from='你的ID', to='目标代理ID', content='通信链路确认畅通') 检查返回: delivered_realtime — true=对方在线, false=对方离线

[检查点] 用户确认：发送前向用户确认消息内容和目标 代理。broadcast_message 必须逐条确认。

完整闭环示例 场景：Hub 在线 → 检查 WorkBuddy 是否有未读消息 → 处理并回复

• 获取_online_代理s() # 确认自己和对方在线
• 搜索_messages(limit=10) # 查最近消息
• acknowledge_message(msg_id, 代理_id) # 标记已读
• 发送_message(to='workbuddy', content='已收到，正在处理') # 回复
• mark_consumed(resource=msg_id, action='replied') # 消费水位线

核心能力 53 个 MCP 工具（v2.4.0） 身份 身份 (6) 工具 功能 register_代理 注册新 代理，需提供 HUB_KEY 认证 heartbeat 代理 心跳上报，维持在线状态，每 3 次连续心跳记录 +1 查询_代理s 查询 代理 列表，支持状态/角色筛选 获取_online_代理s 获取当前在线 代理 列表 Message 消息 (5) 工具 功能 发送_message 代理 间点对点消息，支持 Markdown，自动去重（sha256） broadcast_message (需逐条确认后发送) acknowledge_message 确认已读消息，防止重复出现 搜索_messages 全文搜索消息历史 batch_acknowledge_messages 批量确认消息（1-500 条/次），用于清理消息积压 File 文件 (3) 工具 功能 发送_file 发送文件附件（Base64，10MB 限制），关联到消息 接收_file 接收附件，返回 Base64 编码内容 列出_attachments 列出附件，支持按消息/代理 筛选 Task 任务 (3) 工具 功能 as签名_task 创建并分配任务，支持上下文传递 更新_task_状态 更新任务状态（inbox→as签名ed→in_进度→completed/fAIled） 获取_task_状态 查询任务详情，含依赖、流水线、交接信息 上下文 上下文暂存 (5) 工具 功能 store_memory 临时暂存当前任务参考信息 recall_memory 检索已暂存的上下文 列出_memories 列出当前 代理 的暂存条目 删除_memory 删除暂存条目（仅 创建器） 搜索_memories 检索当前 代理 的暂存内容 经验记录

经验记录和策略管理需特定权限配置。

任务协同 工具 功能 添加_dependency 添加任务依赖关系（依赖检查） 移除_dependency 删除任务依赖关系 获取_task_dependencies 查询任务上下游依赖 创建_parallel_group 创建并行任务组（2-10 个任务） 请求_handoff 请求任务交接 accept_handoff 接受任务交接 reject_handoff 拒绝任务交接（含理由） 添加_质量_gate 在 流水线 中添加质量门 evaluate_质量_gate 评估质量门（passed/fAIled） recalculate_trust_scores 按调度执行分数维护 创建_流水线 创建 流水线 流水线 获取_流水线 查询 流水线 详情 列出_流水线s 列出 流水线 添加_task_to_流水线 向 流水线 添加任务 运维工具 (4) 工具 功能 获取_db_stats 数据库统计信息（表行数、大小、代理 数等） 归档_data 数据维护工具 （其余 2 个内部工具） 权限验证与控制 （其余 2 个内部工具） 权限验证与控制 消费水位线 (2) 工具 功能 mark_consumed 标记任务/消息为已消费，防止重复处理 检查_consumed 查询资源是否已被消费

所有工具内置 try-catch + 3 次指数退避重试（100ms → 200ms → 400ms）。v2.4.0 统一错误格式：HubError 错误码 + mcpError()/mcpFAIl() 标准返回。检查_consumed 查询失败时降级返回 consumed=false（不阻塞业务）。

任务状态机 inbox → as签名ed → [wAIting] → in_进度 → completed / fAIled / cancelled

用户确认检查点

以下操作必须在执行前暂停，向用户摘要说明并等待确认：

# 操作 检查点说明 风险 1 broadcast_message 广播消息会发送给多个 代理，逐条确认内容和接收列表 高 2 as签名_task 分配任务前确认：描述是否清晰、目标 代理 是否合适、Priority 正确 中 3 batch_acknowledge_messages 批量确认会一次性标记多条消息为已处理，确认不会遗漏重要信息 中 4 创建_流水线 创建流水线前确认任务顺序、质量门设置、参与 代理 中 5 添加_质量_gate 质量门失败会阻塞后续任务，确认评估标准合理 高 6 请求_handoff 交接任务前确认目标 代理 有能力接手、理由充分 中 7 归档_data 归档操作会移动数据到归档表，确认归档范围和天数 高 8 store_memory(scope='group') 写入组内共享记忆前确认内容适当，不会泄露敏感信息 中 9 propose_strategy 提议策略前确认内容准确、分类正确、有实际价值 低 10 reject_handoff 拒绝交接需提供理由，确认不会导致任务阻塞 中

规则：LLM 遇到上表操作时，先向用户输出摘要说明，明确询问"是否继续？"，得到肯定答复后再执行。用户可随时跳过检查点。

数据隔离与安全边界 边界 实现方式 接收方校验 发送_message/as签名_task 中的 to_代理 必须为已注册 代理，未注册 代理 被拒绝 Per-代理 数据隔离 每个 代理 仅可见自身消息、任务和暂存条目；跨 代理 查询受 4 级权限控制 暂存内容保护 store_memory 创建的条目仅 创建器 可检索和删除，不会自动暴露给其他 代理 经验记录审批 分享_experience 提交的记录需经 full 权限确认后才对其他 代理 可见 接入配置（stdio 模式）

在 MCP 配置文件中添加 Hub 为 stdio 服务器，提供 HUB_KEY 环境变量进行认证。Hub 通过 stdio 传输 MCP 协议，代理 的