name: using-agent-relay description: 用于实时协调多个AI代理 - 通过tmux包装器（亚5毫秒延迟）或基于文件的团队收件箱提供代理间消息传递，适用于异步工作流
使用代理中继
概述
实时代理到代理消息传递。两种模式：tmux包装器（实时，亚5毫秒）和基于文件的团队（异步，更简单）。
何时使用
- 多个代理在共享代码库上协调
- 回合制交互（游戏、评审、任务交接）
- 并行任务分发
- 实时Claude/Codex/Gemini协作
不要使用： 单个代理、跨主机网络、需要保证交付的场景。
快速参考
| 模式 | 描述 |
|---|---|
->relay:名称 <<<…>>> |
默认格式 - 始终使用围栏格式 |
->relay:* <<<…>>> |
广播给所有代理 |
[[RELAY]]{"to":"名称","body":"消息"}[[/RELAY]] |
结构化JSON |
\->relay: |
转义（字面输出） |
relay read <id> |
读取截断的消息 |
CLI命令
relay -f # 启动守护进程 + 仪表板
relay --status # 检查守护进程
relay --stop # 停止守护进程
relay wrap -n Alice claude # 用消息传递包装代理
relay read abc123 # 读取截断的消息
团队命令（基于文件）
relay team send -n 你 -t 接收者 -m "消息"
relay team send -n 你 -t "*" -m "广播"
relay team check -n 你 --no-wait # 非阻塞
relay team check -n 你 --clear # 读取后清除
relay team status # 显示团队
发送消息（Tmux模式）
直接输出模式 - 不要使用bash命令。始终使用围栏格式：
->relay:BlueLake <<<
我已经完成了API重构。>>>
->relay:* <<<
状态：开始认证模块。>>>
围栏格式（默认）
围栏格式是所有消息的默认格式：
->relay:评审员 <<<
评审请求：认证模块
请检查：
- src/auth/login.ts
- src/auth/session.ts
关键变更：
1. 添加了JWT验证
2. 修复了会话过期>>>
关键： 始终在内容最后一行的末尾以>>>结束！<<<打开，>>>关闭。
限制： 围栏消息最多200行。对于更长的内容，发送带有引用ID的摘要。
回退： 如果忘记>>>，消息会在双空行处自动关闭。
模式规则
模式必须在行首（允许空格/前缀）：
->relay:名称 消息 # 有效
->relay:名称 消息 # 有效
- ->relay:名称 消息 # 有效
某些文本 ->relay:名称 消息 # 无效
接收消息
消息显示为：
来自Alice的中继消息 [abc123]：消息内容
截断的消息
长消息显示[截断...]。读取完整内容：
relay read abc123
规则： 如果消息突然结束，在回复前始终读取完整消息。
协调模式
# 任务分配
->relay:开发人员 <<<
任务：实现 /api/register>>>
# 状态广播
->relay:* <<<
状态：开始认证模块>>>
->relay:* <<<
完成：认证完成>>>
# 评审请求
->relay:评审员 <<<
评审：src/auth/*.ts>>>
# 问题
->relay:架构师 <<<
问题：JWT还是会话？>>>
# 阻塞
->relay:* <<<
阻塞：需要数据库凭证>>>
生成代理
任何代理都可以生成工作代理来委派任务：
# 生成工作代理
->relay:spawn 工作代理名称 cli "任务描述"
# 示例
->relay:spawn 开发1 claude "实现登录端点"
->relay:spawn 测试员 claude "为认证模块编写单元测试"
# 完成后释放
->relay:release 工作代理名称
工作代理在单独的tmux窗口中运行，可以通过->relay:模式进行通信。
多项目桥接
# 桥接多个项目
relay bridge ~/auth ~/frontend ~/api
# 跨项目消息传递
@relay:项目ID:代理 消息
@relay:*:负责人 广播给负责人
常见错误
| 错误 | 修复方法 |
|---|---|
| 使用bash发送实时消息 | 直接以文本形式输出->relay: |
| 消息未发送 | 使用relay --status检查守护进程 |
| 不完整的消息内容 | 使用relay read <id>获取完整文本 |
| 模式不在行首 | 将->relay:移到开头 |
| 忘记清空收件箱 | 使用--clear标志 |
故障排除
relay --status # 检查守护进程
relay --stop && relay -f # 重启
ls -la /tmp/agent-relay.sock # 验证套接字