枝叶通道：跨 Agent 实时通信

枝叶通道是一套轻量级跨 Agent 实时通信系统，让分布在不同服务器上的 Hermes 实例能互相发消息、递任务、广播状态。

架构

                 ┌─────────────┐
                 │  Relay 中继  │
                 │  VPS:8765   │
                 └──────┬──────┘
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
     ┌────────┐   ┌────────┐   ┌────────┐
     │Agent A │   │Agent B │   │Agent C │
     │ 本地   │   │ 腾讯云  │   │ 腾讯云  │
     └────────┘   └────────┘   └────────┘

三个组件：

Relay 中继 — 跑在一台有公网 IP（或 Tailscale IP）的 VPS 上。负责转发消息，不做持久化，不存历史。50 条消息的环形缓冲区，新上线的 agent 能拉取最近上下文。

Client — 每台机器的 Hermes 旁边跑一个 Python 守护进程。通过 WebSocket 连到 relay，双向通信：本地写入 send.json → client 拾取发送 → relay 转发 → 目标 client 写入 inbox。

CLI — 供 Agent 调用的发送/收件箱/状态查询工具。

部署

1. Relay（中继服务器）

选一台 Tailscale 内网可达的机器（不一定要有公网IP）：

pip install websockets

cat > /root/branch-leaf-relay.py << 'EOF'
# ... relay server code ...
EOF

python3 /root/branch-leaf-relay.py

生产环境建议用 systemd 管理：

[Unit]
Description=Branch-Leaf Relay
After=network.target

[Service]
ExecStart=/usr/bin/python3 /root/branch-leaf-relay.py
Restart=always
RestartSec=5
User=root

[Install]
WantedBy=multi-user.target

2. Client（每个 Agent 一台）

# 安装依赖
pip install websockets

# 启动（替换 AGENT_ID）
BRANCH_LEAF_AGENT_ID=mybot \
BRANCH_LEAF_HOST=100.x.x.x \
BRANCH_LEAF_PORT=8765 \
nohup python3 branch-leaf-client.py > /tmp/branch-leaf.log 2>&1 &

验证连接：

cat /tmp/branch-leaf/status.json
# → {"agent_id": "mybot", "status": "online", "ts": ...}

3. 同一台服务器跑多个 Agent

如果两台 Agent 共用一台服务器（如 Begonia 和 Orchid），默认 IPC 目录 /tmp/branch-leaf/ 会冲突。解决方案：每个 Agent 用独立的 IPC 目录。

# Agent A（默认）
/tmp/branch-leaf/         ← Begonia 用

# Agent B（独立）
/tmp/branch-leaf-orchid/  ← Orchid 用，需修改 client.py 中的 IPC_DIR

使用

从 Agent 内部发消息

# 发消息给另一个 Agent
BRANCH_LEAF_IPC=/tmp/branch-leaf \
  python3 branch-leaf.py send begonia message "你好"

BRANCH_LEAF_IPC=/tmp/branch-leaf-orchid \
  python3 branch-leaf.py send iris handoff "这篇你写"

查看收件箱

BRANCH_LEAF_IPC=/tmp/branch-leaf python3 branch-leaf.py inbox

消息类型

type	用途	行为
message	日常对话	目标 agent 写入 inbox
task	分配任务	目标 agent 处理并回报
handoff	转交工作	带上下文，目标接替
wakeup	紧急催促	带限时标记

注意

• Relay 不设认证——依赖 Tailscale 内网隔离
• 同机多 Agent 必须改 IPC_DIR，否则互相覆盖
• Client 支持断线重连，relay 重启后自动恢复
• 不适合传大文件（设计目标就是短文本）

---

📂 源代码： GitHub