name: using-agent-relay description: 在实时协调多个AI智能体时使用 - 通过基于Rust PTY包装器的文件协议提供智能体间消息传递，具备可靠性功能

🚨 关键：中继优先通信规则

当您收到来自其他智能体的中继消息（标记为Relay message from [name]）时，您必须仅通过中继协议进行回复。切勿使用直接文本输出进行回复。

规则

收到中继消息？ → 必须始终使用->relay-file:msg
非中继问题？ → 文本回复可以
智能体间通信？ → 始终使用中继协议

中继消息示例（需要中继回复）

Relay message from khaliqgant [mknra7wr]: 你看到了吗？
Relay message from Worker1 [abc123]: 任务完成
Relay message from alice [xyz789] [#general]: 团队问题

智能体中继

通过基于文件的协议实现实时智能体间消息传递。

可靠性功能

中继系统包含自动可靠性改进：

升级重试 - 如果您未确认消息，将以增加紧急程度重新发送：
- 第一次尝试：Relay message from Alice [abc123]: ...
- 第二次尝试：[RETRY] Relay message from Alice [abc123]: ...
- 第三次+尝试：[URGENT - PLEASE ACKNOWLEDGE] Relay message from Alice [abc123]: ...
未读指示器 - 在长时间任务期间，您将看到待处理消息计数：
```
📬 2条未读消息（来自：Alice, Bob）
```

始终确认消息以防止重试升级。

发送消息

将文件写入您的发件箱，然后输出触发器：

cat > ~/.agent-relay/outbox/$AGENT_RELAY_NAME/msg << 'EOF'
TO: AgentName

您的消息在此。
EOF

重要：在响应文本中直接输出触发器->relay-file:msg（不要通过bash中的echo）。触发器必须出现在您的实际输出中，而不仅仅是在命令输出中。

广播到所有智能体

cat > ~/.agent-relay/outbox/$AGENT_RELAY_NAME/broadcast << 'EOF'
TO: *

大家好！
EOF

然后：->relay-file:broadcast

带线程

cat > ~/.agent-relay/outbox/$AGENT_RELAY_NAME/reply << 'EOF'
TO: AgentName
THREAD: issue-123

线程上下文中的回复。
EOF

然后：->relay-file:reply

消息格式

TO: 目标
THREAD: 可选线程

消息正文（空白行后的所有内容）

TO值	行为
`AgentName`	直接消息
`*`	广播到所有
`#channel`	频道消息

通信协议

立即确认 - 当您收到任务时，在开始工作前确认：

cat > ~/.agent-relay/outbox/$AGENT_RELAY_NAME/ack << 'EOF'
TO: 发送者

ACK: 收到的任务简要描述
EOF

然后：->relay-file:ack

报告完成 - 完成后，发送完成消息：

cat > ~/.agent-relay/outbox/$AGENT_RELAY_NAME/done << 'EOF'
TO: 发送者

DONE: 完成内容的简要总结
EOF

然后：->relay-file:done

优先级处理 - 如果您看到[RETRY]或[URGENT]标签，请立即响应。

接收消息

消息显示为：

Relay message from Alice [abc123]: 内容在此

带重试升级的消息：

[RETRY] Relay message from Alice [abc123]: 你收到我的消息了吗？
[URGENT - PLEASE ACKNOWLEDGE] Relay message from Alice [abc123]: 请回复！

频道路由（重要！）

来自#general（广播频道）的消息包含[#general]指示器：

Relay message from Alice [abc123] [#general]: 大家好！

当您看到[#general]时：回复到*（广播），而不是直接回复发送者。

生成和释放智能体

重要：文件名始终是spawn（不是spawn-agentname），触发器始终是->relay-file:spawn。按顺序逐个生成智能体。

生成工作器

cat > ~/.agent-relay/outbox/$AGENT_RELAY_NAME/spawn << 'EOF'
KIND: spawn
NAME: WorkerName
CLI: claude

任务描述在此。
EOF

然后：->relay-file:spawn

在特定目录中生成

使用CWD在多仓库工作区中的特定仓库中生成智能体：

cat > ~/.agent-relay/outbox/$AGENT_RELAY_NAME/spawn << 'EOF'
KIND: spawn
NAME: RepoWorker
CLI: claude
CWD: relay

在中继仓库上工作。
EOF

然后：->relay-file:spawn

释放工作器

cat > ~/.agent-relay/outbox/$AGENT_RELAY_NAME/release << 'EOF'
KIND: release
NAME: WorkerName
EOF

然后：->relay-file:release

头部参考

头部	必需	描述
TO	是（消息）	目标智能体/频道
KIND	否	`message`（默认），`spawn`，`release`
NAME	是（spawn/release）	智能体名称
CLI	是（spawn）	使用的CLI
CWD	否	生成智能体的工作目录（例如，多仓库工作区中的仓库名称）
THREAD	否	线程标识符

状态更新

将状态更新发送给您的领导，而不是广播：

# 正确 - 仅向领导发送状态
cat > ~/.agent-relay/outbox/$AGENT_RELAY_NAME/status << 'EOF'
TO: Lead

STATUS: 正在处理认证模块
EOF

然后：->relay-file:status

CLI命令

agent-relay status              # 检查守护进程状态
agent-relay agents              # 列出活动智能体
agent-relay agents:logs <name>  # 查看智能体输出
agent-relay agents:kill <name>  # 终止生成的智能体
agent-relay read <id>           # 读取截断的消息
agent-relay history             # 显示最近的消息历史

查看消息历史

使用agent-relay history查看先前消息：

agent-relay history                    # 最近50条消息
agent-relay history -n 20              # 最近20条消息
agent-relay history -f Lead            # 来自Lead的消息
agent-relay history -t Worker1         # 发送给Worker1的消息
agent-relay history --thread task-123  # 线程中的消息
agent-relay history --since 1h         # 最近一小时的消息
agent-relay history --json             # JSON输出用于解析

同步消息传递

默认情况下，消息是即发即弃的。添加[await]以在收件人确认前阻塞：

->relay:AgentB [await] 请确认

自定义超时（秒或分钟）：

->relay:AgentB [await:30s] 请确认
->relay:AgentB [await:5m] 请确认

当存在相关ID时，收件人在处理后自动确认。

故障排除

agent-relay status                    # 检查守护进程
agent-relay agents                    # 列出连接的智能体
ls -la /tmp/agent-relay.sock          # 验证套接字
ls -la ~/.agent-relay/outbox/             # 检查发件箱目录

常见错误

错误	修复
使用bash发送消息	将文件写入发件箱，然后输出`->relay-file:ID`
消息未发送	检查`agent-relay status`和发件箱目录是否存在
不完整的消息内容	`agent-relay read <id>`获取完整文本
缺少触发器	写入文件后必须输出`->relay-file:<filename>`
错误的发件箱路径	使用`~/.agent-relay/outbox/$AGENT_RELAY_NAME/`