核心用法
AgentRelay 是一套专为多 Agent 环境设计的通信协议，主要解决 sessions_send 传输大 payload 时的超时限制问题（通常 >30 字符易超时）。其核心机制是将实际数据写入共享文件，仅通过极短的消息指针（CSV 格式）在 Agent 间传递，实现"大文件 + 短消息"的分离式传输。
标准使用流程：
1. 发送方：调用 agentrelay_send() 将数据写入共享文件，生成带 AgentRelay: 前缀的 CSV 消息（如 REQ,r1_r,s/r1_r.json,,），通过 sessions_send 发送
2. 接收方：识别关键词触发 Skill，执行 receive 命令解析消息、读取文件内容，获取 content 任务数据和 secret 验证码
3. 执行与确认：完成处理后，执行 update 更新结果文件，再调用 ack 生成 ACK 消息返回发送方，发送方验证 Secret 匹配即确认通信完成
关键命令：receive <csv_message>（解析消息读文件）、update <event_id> <json_updates>（更新结果）、ack <event_id> <secret>（生成确认）
显著优点
- 突破消息大小限制：通过文件中转，可传输任意大小的 JSON 数据，彻底解决 sessions_send 超时问题
- 可靠传输机制：内置 Secret Code（6 位随机码）验证，确保接收方真实读取文件；可选 Burn-on-read 读取后自动销毁，保护敏感数据
- 完整状态追踪：每笔交易记录到日志文件，支持 REQ → CMP → ACK 的完整生命周期管理
- 多跳接力支持：原生支持跨多 Agent 的链式通信（已测试 5 跳、10 跳场景）
- 低侵入设计：仅需识别
AgentRelay:前缀即可触发，与现有 Agent 架构兼容
潜在缺点与局限性
- 文件系统依赖：依赖共享文件系统或网络存储，单机多 Agent 场景外需要额外存储同步机制
- 延迟增加：相比直接消息传递，增加了文件 I/O 操作，延迟从毫秒级升至百毫秒级
- Secret 泄露风险：Secret Code 在 ACK 消息中明文传输，若消息通道被截获可被重放攻击（建议结合 TLS/加密通道使用）
- TTL 管理复杂：默认 24 小时文件保留，大量通信场景需关注磁盘清理与存储膨胀
- 错误恢复有限：NACK 机制较简单，缺乏自动重试、幂等性保证等生产级容错设计
适合人群
- 需要突破消息大小限制的多 Agent 系统开发者
- 构建Agent 流水线/工作流（如诗歌接力、多步骤分析）的场景
- 对传输可靠性有要求、愿意用延迟换可靠性的场景
- 同构 Agent 环境（文件系统共享方便），异构/分布式环境需额外适配
常规风险
| 风险类型 | 描述 | 缓解建议 |
|---------|------|---------|
| 文件权限泄露 | 共享目录若权限配置不当，其他用户可读敏感数据 | 使用 700 权限目录，启用 burn_on_read |
| Secret 重放攻击 | ACK 消息被截获后可重放，伪造完成确认 | 结合消息签名、时间戳或 TLS 加密通道 |
| 存储 DoS | 大量未清理文件占满磁盘 | 监控 TTL，设置定时清理任务 |
| 路径遍历 | 若 ptr 参数未严格校验，可能读取任意文件 | 限制 ptr 格式为 `s/[a-z0-9_]+\.json` |