（4056期）miab-broker – 异步智能体协同回调栈

异步智能体协同回调栈 专为LYRA智能体网络设计的文件级异步回调系统，通过LIFO栈结构实现零轮询的任务委托与唤醒，消除CPU空转，提升多智能体协作效率。 使用说明 核心用法 MIAB Broker 是一套面向多智能体系统的异步回调协调框架，核心解决"智能体委托任务后空转等待"的低效问题。其设计哲学是：调用方创建任务后立即结束会话，被委托智能体完成后通过回调机制唤醒上游。 整个生命周期遵循 register → create → forward → return → resolve 五阶段协议： register：为智能体注册唤醒路径，建立功能ID到可路由句柄的映射 create：调用方打包恢复上下文（任务摘要、执行步骤、预期结果、集成方式），创建"瓶中消息"并立即结束回合 forward：中间智能体需进一步委托时，将自身恢复帧压入栈顶，形成LIFO调用链 return：执行完毕的智能体弹出当前帧，唤醒上一层栈帧持有者 resolve：根智能体确认整体完成，归档并清理瓶子 CLI工具 claw-callback.py 是所有操作的单一入口，每个命令输出明确的 next_step 指引下一步操作。 显著优点 零轮询架构：彻底消除传统多智能体协调中的"完成了吗"循环查询，显著降低token消耗和计算资源浪费 LIFO语义清晰：栈结构天然匹配函数调用语义，支持任意深度的任务嵌套委托， unwind过程自动且可预测 状态持久化：基于文件的轻量级存储，无需外部数据库依赖，适合单主机智能体集群部署 恢复上下文完整：每个帧携带完整的恢复指令集（summary/steps/expects/integrate），唤醒后可无缝接续工作 审计能力：ledger.jsonl 提供不可变的操作日志，支持事后追溯与故障分析 垃圾回收机制：reap-callbacks.sh 自动清理孤儿瓶子，防止状态无限膨胀 潜在缺点与局限性 无并发安全保证：信封写入无锁保护，双智能体同时修改同一瓶子可能导致损坏 身份验证缺失：--from 参数为未验证声明，恶意或故障智能体可能伪造身份弹出他人帧或解析非所属链 无完整性保护：信封为纯文本JSON，无签名机制，本地进程可篡改唤醒目标或执行指令 单主机限制：安全模型假设 $CLAW_HOME 下所有进程可信，未加固多租户场景 状态明文持久化：任务内容、结果、工件路径永久留存ledger，敏感信息存在泄露风险 无自动重试：唤醒消息无送达确认，失败需手动重新触发 适合的目标群体 多智能体系统开发者：需要协调2-10个 Specialist Agent 完成复杂流水线任务的开发团队 LYRA生态用户：直接使用参考部署（LYRA/SPECTRE/Cinder等角色）的智能体网络运营者 资源敏感型场景：对token成本和API调用次数有严格预算控制的自动化工作流 单主机/开发机部署：适合个人开发者工作站或隔离的CI/CD runner，而非共享生产集群 使用风险 数据残留风险：所有操作记录永久写入ledger，需建立定期清理策略避免敏感信息累积 TTL配置风险：回调清理器的默认120分钟阈值可能误删长周期任务，必须经过 --dry-run 观察期调优 注册表漂移：功能ID与显示名称混用将导致唤醒失败，需严格遵循 agent-registry.json 契约 文件权限依赖：启动时强制检查 $CLAW_HOME 为0700，与某些容器/共享存储方案不兼容 扩展性天花板：文件级状态在智能体数量>20或QPS>1时可能成为瓶颈，长期需迁移至消息队列后端 原始说明 Operate the Message-in-a-Bottle (MIAB) LIFO callback stack — the async inter-agent transport that lets agents delegate work, yield their turn, and get woken when results return instead of CPU-idling on poll loops. Use when registering wake paths, creating/forwarding/returning/resolving callbacks, or invoking the callback reaper.