auto-sync: 2026-05-14 09:52:44

docs/design/architecture-v2.md

@@ -1321,22 +1321,81 @@ sub-agent 完成后，archiver 自动把 transcript 归档到任务目录。
 3. 追加 Moment: user_steer + plan_adjusted
 ```
 
-### 3.8 与 OpenClaw 的集成点
+### 3.8 与 OpenClaw 的集成点（v2.3 修正）
+
+> ⚠️ v2.3 关键修正（司马懿第二轮评审反馈）：
+> - ❌ 废弃自建 Gateway WS Client（不稳定、需维护长连接）
+> - ✅ 改用 `openclaw agent` CLI 命令（Gateway 原生、有超时和 fallback、零连接管理）
+> - ✅ 全程推送式事件链路，零轮询零 cron
 
 | v2.0 功能 | 实现方式 | 说明 |
 |-----------|---------|------|
 | 庞统对话 | 庞统主 session (webchat) | 用户通过 Control Center 对话 |
 | 庞统查进展 | curl GET daemon API | 实时查询 SQLite，AI 生成汇报 |
 | 庞统操作任务 | curl POST daemon API | 创建/规划/启动/暂停/恢复任务 |
-| Agent 调度 | Gateway WS API → Agent 主 session | 简单步骤发到主 session |
+| **Daemon 调度 Agent** | **`openclaw agent` CLI** | daemon 调用 CLI 发消息到 Agent 主 session |
 | Agent 调度(复杂) | sessions_spawn + cleanup=delete | 复杂步骤用 sub-agent 隔离 |
 | Agent 回报 | curl POST daemon API | 完成/失败/进度上报 |
 | Agent 查黑板 | curl GET daemon API | 查询任务上下文/计划/产出物 |
-| Daemon 通知庞统 | Gateway WS API systemEvent | 步骤完成/异常/需要裁决时 |
+| **Daemon 通知庞统** | **`openclaw agent` CLI** | daemon 调用 CLI 注入消息到庞统 session |
 | Agent 上下文管理 | Gateway reset | 定期 reset Agent 主 session 防止膨胀 |
 | 知识检索 | wiki-query skill (Agent 侧) | Agent 需要时可调用 |
 | 数据持久化 | SQLite (daemon) + 文件系统 (artifacts) | 状态在 SQLite，产出物在文件系统 |
-| 执行历史归档 | daemon archiver | sub-agent 完成后 transcript 复制到任务目录 |
+| 执行历史归档 | daemon archiver | 归档后物理删除原始 session 文件 |
+
+#### 3.8.1 Agent 调度的具体实现
+
+```bash
+# Daemon 调度 Agent（简单步骤：主 session）
+openclaw agent --agent zhangfei-dev \
+  --message "执行步骤 s2: 编码均线策略逻辑。上下文见 http://localhost:8080/api/steps/s2" \
+  --json
+
+# Daemon 通知庞统
+openclaw agent --agent pangtong-fujunshi \
+  --message "[systemEvent] 步骤 s1 完成，zhaoyun 回报：数据获取成功" \
+  --json
+```
+
+**并行调度**：daemon 用 `subprocess.Popen` 异步启动多个 `openclaw agent` 命令，poll 等待结果。
+
+**事件传播链（全程推送，零轮询）**：
+```
+Agent 完成任务
+  → curl POST http://localhost:8080/api/steps/{id}/complete（回报 daemon）
+  → daemon 更新 SQLite + 验证产出
+  → daemon 调 openclaw agent --agent pangtong-fujunshi（通知庞统）
+  → 庞统收到消息，决定下一步
+  → daemon 调 openclaw agent --agent zhangfei-dev（调度下一个 Agent）
+```
+
+#### 3.8.2 庞统上下文恢复协议
+
+庞统是"无任务状态"的（状态在 daemon SQLite），但需要"推理上下文"。
+庞统每次被 daemon 通知时，第一步总是 `GET /api/tasks/{id}/status` 重建认知。
+
+#### 3.8.3 Agent 任务消息模板
+
+Daemon 调度 Agent 时发送的标准消息格式：
+
+```
+[moziplus v2] 任务步骤分配
+
+任务: {task_title}
+步骤: {step_id} - {step_title}
+目标: {step_intent}
+预期产出: {step_end_state}
+
+上下文获取:
+  任务状态: curl http://localhost:8080/api/tasks/{task_id}
+  步骤详情: curl http://localhost:8080/api/steps/{step_id}
+  前序产出: curl http://localhost:8080/api/steps/{prev_step_id}/output
+
+约束:
+  产出物必须写到 artifacts/task-{task_id}/steps/{step_id}/ 目录
+  完成后回报: curl -X POST http://localhost:8080/api/steps/{step_id}/complete
+  失败回报: curl -X POST http://localhost:8080/api/steps/{step_id}/fail
+``` |
 
 ---