核心用法
ai-collab 是一套多 Agent 自主协作框架，专为需要并行处理能力的场景设计。系统采用双 Agent 架构：
- Agent A（主 Agent）：运行
claude code的交互式会话，负责浏览器操作、复杂任务和用户交互 - Agent B（守护进程）：运行
claude --print的轻量级子进程，处理后台任务、监控和快速查询
两者通过共享 chat.log 日志和 inbox/ 文件系统队列进行异步通信，实现无阻塞的并行协作。
部署流程
1. 配置环境变量（Agent 名称、模型选择、路径等）
2. 创建协作工作区和 inbox 目录
3. 在 tmux 会话中启动 Agent B 守护进程
4. 配置 cron 轮询脚本实现 B→A 的消息路由
5. 使用 send.sh 脚本从 A 向 B 发送任务
通信协议
所有消息采用结构化标签格式，强制闭环设计：
| 标签 | 作用 |
|------|------|
| `[TASK:name]` | 任务分配 |
| `[ACK:name]` | 确认接收 |
| `[DONE:name]` | 任务完成 + 结果 |
| `[BLOCKED:name]` | 阻塞 + 原因 |
| `[HANDOFF:name]` | 任务完全移交 |
| `[QUESTION:topic]` | 信息请求 |
关键约束：必须先回答问题才能提问，必须先关闭任务才能开启新任务，禁止开放式语句如 "let me know"。
显著优点
1. 真正的并行执行：主 Agent 处理用户交互时，守护 Agent 可在后台独立完成数据获取、监控等任务，无阻塞等待
2. 模型优化配置：Agent B 默认使用 claude-haiku-4-5-20251001，成本极低且响应快，适合高频后台任务
3. 健壮的原子写入：采用 mktemp + mv 模式防止 inotifywait 读取不完整消息
4. 完善的金融安全门控：三级金额阈值（<$20/$20-50/>$50）配合强制授权标签，防止自主资金操作风险
5. 任务接管机制：主 Agent 同一任务阻塞两次后，守护 Agent 自动接管执行，避免无限等待
6. 跨模型兼容：支持 Claude↔Claude、Claude↔GPT、GPT↔GPT 多种组合
潜在缺点与局限性
1. 部署复杂度较高：需要手动配置 tmux、cron、环境变量、文件权限等多处环节，对新手不友好
2. 状态同步依赖文件系统：chat.log 和 inbox 的单点故障可能导致消息丢失或重复处理
3. 无原生持久化队列：inotifywait + 文件轮询方案在高并发场景下存在 race condition 风险
4. 模型成本不透明：Agent B 的 API 调用频率若未加限制，可能产生意外费用（虽有 rate governor 但需手动配置）
5. 调试困难：守护进程运行在无头 tmux 会话中，错误诊断依赖 /tmp/clawdy_last_err 等间接手段
6. Telegram 桥接为可选功能：完整的生产级消息路由需要额外部署和维护
适合人群
- 高级 CLI 用户：熟悉 tmux、cron、环境变量管理和 shell 脚本调试
- 多任务并行需求场景：如一边写代码一边让后台 Agent 监控价格、抓取数据
- 成本敏感型自动化：愿意用配置复杂度换取 Haiku 级别的低 API 成本
- 安全意识较强的用户：能接受金融门控等手动审批流程
不适合：期望开箱即用、图形界面配置、或完全无代码部署的普通用户。
常规风险
| 风险类别 | 具体表现 | 缓解措施 |
|----------|----------|----------|
| 资金损失 | Agent 自主执行未经审批的金融操作 | 严格执行 Tier 3 授权标签，定期审计 chat.log |
| 消息丢失 | 文件系统竞争或进程崩溃导致 inbox 消息未处理 | 使用原子写入模式，部署 watchdog 监控 |
| API 费用失控 | 守护进程陷入循环调用 | 启用 rate governor，设置预算告警 |
| 权限提升 | .env 文件权限配置错误导致密钥泄露 | `chmod 600`，禁止日志记录敏感信息 |
| 任务死锁 | 双方同时等待对方响应 | 强制 ACK/DONE 协议，设置超时接管机制 |
特别提醒：文档中多次出现的 claude --print 调用涉及向 Anthropic API 发送数据，需确保 AGENT_B_MODEL 和 prompts 不包含敏感信息。