时间：2026-02-22
任务描述：对多 Agent 架构方案 v1.8 进行全面审计，重点做 fact-check。
方案文件：/root/.openclaw/workspace/memory/docs/multi-agent-plan.md（v1.8）
本次为架构方案审计，不是代码审查。请切换到方案审计模式。
重点 1：Fact-Check（必须使用 web_search 工具）
对以下技术声明用搜索工具验证正确性：
1. OpenClaw Hook 系统的 message:received 事件 —— 方案说"hook 不能直接调用 agent runner"，是否准确？
2. 方案说"hook 应保持轻量"，文档是否真的有此限制？
3. 方案中 sessions_send(timeoutSeconds=0) 的行为描述 —— 是否真的是异步非阻塞？
4. flock 文件锁在 Linux 上的 append 操作 —— 方案说"串行通知保证无并发"，这个假设是否成立？
5. 任何其他你认为需要验证的技术声明
本地文档路径参考（可直接 read）：
- /usr/lib/node_modules/openclaw/docs/automation/hooks.md
- /usr/lib/node_modules/openclaw/docs/tools/multi-agent-sandbox-tools.md
重点 2：逻辑一致性审查
检查以下问题：
1. 通知格式（第八节）要求 [Inter-session message] 前缀，但 SOUL.md 规则（第十节）说"判断来源：消息来自 agent:xxx:main 格式的 session"—— 两者是否冲突？��式前缀 vs 来源判断，哪个才是真正的触发条件？
2. 第九节说 Hook 只能"辅助预警"，但没有说明爱衣收到 Hook 推送的预警后如何处理 —— 方案是否完整？
3. session.md 格式里 rejectCount 字段 —— 是由哪个 Agent 负责更新？方案是否明确？
4. 超轮次后"以先写入 session.md 的为准"—— 在无文件锁的情况下，两个 Agent 同时写入如何保证"先写入"的原子性？
5. 爱衣派发任务前"先 sessions_list 检查目标 session 是否存在"—— 如果 session 存在但 Agent 已崩溃，怎么办？
重点 3：遗漏检查
active.json 有维护责任说明，但是否有写入失败的处理方案？审计输出格式：
请在本文件末尾追加审计报告，格式：
## [reviewer] 审计报告
时间：xxx，currentRound → 2
### Fact-Check 结果
（每项声明：✅ 准确 / ❌ 错误（正确说法：xxx）/ ⚠️ 部分准确（补充：xxx））
### 逻辑问题
（编号列表，每项：严重程度 + 问题描述 + 建议修复）
### 遗漏项
（编号列表）
### 总体评价
（方案是否可以进入执行阶段，或需要先修复哪些问题）
完成后 sessions_send 通知爱衣：
[Inter-session message] 审计完成 ✅ task_id=task-arch-review-001 结果路径=/root/.openclaw/workspace/tasks/task-arch-review-001/session.md
下一步：通知 reviewer 执行审计
时间：2026-02-22 22:25，currentRound → 2
审计模式说明：本次为架构方案审计，不是代码审查。评估标准：逻辑自洽性、技术声明准确性、流程完整性，而非代码风格。
Fact-Check 方法说明：web_search 因无 Brave API key 不可用，已通过以下替代手段完成验证：
- 读取本地文档：/usr/lib/node_modules/openclaw/docs/automation/hooks.md
- 读取本地文档：/usr/lib/node_modules/openclaw/docs/tools/multi-agent-sandbox-tools.md
- 读取本地文档：/usr/lib/node_modules/openclaw/docs/tools/index.md（含 sessions_send 规范）
- 在线访问：https://docs.openclaw.ai/automation/hooks.md（内容与本地一致）
1. Hook 系统：「hook 不能直接调用 agent runner」
✅ 准确
文档明确：Hook 是事件处理函数（HookHandler），只能：
- 向 event.messages 推送消息
- 执行自定义逻辑（写文件、调 API）
文档无任何 hook → 调用 agent runner 的 API。Boot-md hook 是特例（gateway:startup 时运行 BOOT.md 内容），不是 message:received 场景。方案结论「Hook 不能替代 SOUL.md 规则」成立。
2. Hook「应保持轻量」——文档是否真的有此限制？
✅ 准确，但有重要补充
文档 Best Practices 写明：
"Hooks run during command processing. Keep them lightweight."
"✗ Bad - blocks command processing:await slowDatabaseQuery(event)"
补充：文档同时提供了绕过阻塞的模式——void processInBackground(event) (fire and forget)。换言之，"保持轻量"的精确含义是"不阻塞 handler 返回"，而非禁止所有异步操作。如果 Hook 在后台执行，可以做较重的工作。
方案说"不能执行复杂逻辑"略有误导，更准确表述是"不能同步阻塞"。对当前审计范围（仅用于辅助预警/日志）无实际影响。
3. sessions_send(timeoutSeconds=0) 是否真的是异步非阻塞？
✅ 准确
文档明确：
sessions_send:timeoutSeconds?(0 = fire-and-forget)
sessions_sendwaits for final completion whentimeoutSeconds > 0.
timeoutSeconds=0 即 fire-and-forget，调用方不等待目标 agent 完成即返回。这正是方案所需的非阻塞通知语义。
4. flock 文件锁 + append 操作保证串行
⚠️ 部分准确（当前阶段无问题，第三阶段方案需注意）
第一阶段方案（串行通知）：✅ 完全准确。coder 完成写入后才通知 reviewer，天然无并发。
第三阶段 flock 方案（并行 Agent 时）：方案的 flock 示例使用 cat >> session.md，分析如下：
- Linux flock 对文件级写锁是有效的，能防止并发损坏
- flock ... bash -c 'cat >> ...' 模式中，cat 是原子持锁写入，语义正确
- 潜在问题：示例中 flock 锁的作用域仅覆盖 cat 命令，若 Agent 是多步写入（先读后写），flock 无法防止 check-then-act 竞态
当前第一阶段不涉及并行，此问题影响第三阶段。建议在第三阶段设计时明确：Agent 读取 + 写入必须在同一 flock 持锁范围内完成。
5. 其他技术声明：message:received 事件可监听 Agent → Agent 的 sessions_send
⚠️ 存疑，方案未提及，但值得确认
文档对 message:received 的 from 字段描述为"Sender identifier (phone number, user ID, etc.)"，定位为外部渠道消息。sessions_send 是内部 inter-session 消息，是否触发 message:received 事件，文档未明确说明。若 Hook 无法捕获 sessions_send 通知，第九节的 Hook 辅助预警方案将失效。建议在实施前实测验证。
问题 1：通知格式 vs 来源判断的双重触发条件存在潜在歧义
- 严重程度：低（当前无 bug，但规则表述冗余）
- 描述：第八节说触发条件是格式标记（[Inter-session message] + task_id=）；第十节说触发条件是来源判断（agent:xxx:main）。两者在实践中同时为真，但理论上可以分离：如果 Agent 通知没有标准前缀，或来自非 agent:xxx:main 的 session 但带有前缀，规则会冲突。
- 建议修复：明确哪个是主要触发条件，另一个作为辅助验证。推荐：来源（agent:xxx:main）为主，格式为辅（用于爱衣质检流程的进一步判断）。
问题 2：Hook 辅助预警收到后，爱衣如何处理未定义
- 严重程度：中（流程不完整）
- 描述：第九节说 Hook 可以"向用户推送'已收到 Agent 通知，爱衣正在处理'的确认消息"，但没有说明爱衣在收到这个 Hook 推送后的处理流程。如果爱衣已经正常处理了通知，Hook 推送会造成重复消息；如果爱衣漏掉了，Hook 推送又如何确保补救？这个机制的容错逻辑未说明。
- 建议修复：若实施 Hook 辅助预警，明确：Hook 只负责日志记录，不做用户推送；用户推送的职责保留在爱衣 SOUL.md 规则中。
问题 3：rejectCount 更新责任未明确
- 严重程度：低（不影响第一阶段，但需在执行前明确）
- 描述：session.md 格式（第三节）定义了 rejectCount 字段，但未指定由哪个 Agent 在哪个时机负责 +1。第一节说"爱衣打回次数"，暗示是爱衣打回时递增，但未在流程图或规则中明确。
- 建议修复：在爱衣 SOUL.md 的质检流程中加一步：打回时：session.md rejectCount +1（爱衣负责）。
问题 4：超轮次「以先写入 session.md 的为准」的原子性问题
- 严重程度：低（第一阶段串行无此问题；第三阶段并行前需解决）
- 描述：方案说"两个 Agent 同时发现超轮次，以先写入 session.md 的为准"。在没有文件锁的情况下，"先写入"本身是竞态操作，无法保证原子性。两个 Agent 可能同时追加超轮次标记，导致重复通知爱衣。
- 建议修复：在超轮次检测场景中，建议使用 flock 实现 check-then-write 的原子操作；或简化规则为"允许重复通知爱衣，爱衣自行去重"。
问题 5：sessions_list 检查 session 存在，但 Agent 崩溃情形未处理
- 严重程度：低（极端情形）
- 描述：第十三节说"爱衣在派发任务前先 sessions_list 检查目标 session 是否存在；若不存在，message 通知主人"。但若 session 存在而 Agent 崩溃（响应超时、无回复），当前方案依赖 heartbeat 30 分钟超时检测，响应较慢。
- 建议修复：可接受。heartbeat 检测已足够，无需强化。或者可将 sessions_send timeoutSeconds 设为 30 秒（非 0）作为快速失败检测，但这会改变通知语义，需权衡。
1. coder Agent workspace 创建步骤未细化
第十三节只写"创建 workspace-coder/"，但未说明：
- 哪些文件需要预置（SOUL.md、AGENTS.md、HEARTBEAT.md 等）
- SOUL.md 的初始内容从哪里来（从现有 reviewer 复制并修改？）
- openclaw.json 注册时 agentDir 路径
影响：执行时可能出现漏配。建议在执行计划中补充 coder 创建 checklist。
2. active.json 写入失败无处理方案
第六节说明了维护责任，但未考虑写入失败场景（磁盘满、权限错误等）。当前阶段风险低，但若 active.json 损坏，heartbeat 扫描会失效。建议：active.json 写入时做简单的 try/catch + 日志，失败时 message 通知主人。
3. 测试用例未设计
第十四节标注"第一阶段测试用例设计 - 未开始 - 优先级高"。在方案进入执行前，建议至少明确以下场景：
- 正常链路：coder → reviewer → 爱衣（无争议，一轮通过）
- 驳回场景：reviewer 提意见 → coder 驳回 → reviewer 接受/坚持
- 超轮次：模拟 currentRound 超过 maxRound
- 通知黑洞测试：故意让一个 Agent 静默，验证 heartbeat 能否在 30 分钟内检测到
4. coder SOUL.md 中"驳回后 reviewer 处理"的镜像规则缺失
reviewer SOUL.md（第十节）详细描述了驳回流程，但 coder 的 SOUL.md 规则未在方案中出现。执行时需同步撰写 coder SOUL.md，确保两者角色规则互补。
方案整体质量：高。可进入执行阶段，但建议先修复 2 项问题。
必须修复后再执行（阻塞项）：
- 无真正的阻塞项。
建议执行前修复（影响后续迭代）：
1. 问题 3（rejectCount 更新责任）：在爱衣 SOUL.md 补充 rejectCount +1 的明确操作步骤，避免执行时遗忘
2. 遗漏项 1（coder workspace 创建 checklist）：列出需预置的文件，防止漏配
可推迟到第二/三阶段解决：
- 问题 1（通知触发条件歧义）：当前无 bug，低优先级
- 问题 2（Hook 辅助预警逻辑）：第二阶段再决策
- 问题 4（超轮次原子性）：第三阶段引入并行时解决
- 问题 5（session 崩溃检测）：heartbeat 已覆盖，可接受
特别说明 — Hook 辅助通知方案评估：
技术上可行，但价值有限。核心问题是：message:received 是否能捕获 sessions_send 触发的内部 inter-session 消息，文档未明确，需实测。若可捕获，Hook 做日志记录有价值；若不可捕获，方案失效。建议：暂不实施，在第二阶段用一个简单测试验证可行性后再决定。