diff --git a/docs/design/architecture-v2.md b/docs/design/architecture-v2.md index 1e4570c..5fd6199 100644 --- a/docs/design/architecture-v2.md +++ b/docs/design/architecture-v2.md @@ -1849,6 +1849,205 @@ experience: content: "如果是纯模拟数据回测,不需要数据清洗步骤" ``` +### 3.12 中央协调 + Agent 自主(v2.4 核心设计修正) + +> **问题**:v2.3 设计在三轮评审后逐渐妥协了三个 AI native 核心目标: +> 1. Agent 自主协作 → 退化为中央调度 +> 2. 实时共享感知 → 退化为按需查询 +> 3. AI 持续参与 → 退化为完成时通知 +> +> **根因**:遇到技术难点时采纳降级方案,而非在约束下找实现目标的方法。 +> +> **v2.4 修正**:技术栈不变(Daemon + SQLite + `openclaw agent` CLI + 文件系统),变的是**设计理念**—— +> 从“中央控制”变为“中央协调 + Agent 自主”。 +> +> **调研来源**: +> - Edict 朝堂议政:TurnScheduler + phaseMask(Agent 声明在哪些阶段主动发言) +> - Ouroboros:后台意识循环 consciousness.py(任务间主动思考) +> - Network-AI:Blackboard + CRDT(Agent 读黑板、看到变化、自己决定行动) +> - Open Multi-Agent:sharedMemory + delegate_to_agent(Agent 可主动委派) +> - oh-my-claudecode:Team staged pipeline(team-plan → team-prd → team-exec → team-verify → team-fix) +> - Hermes Agent:kanban board + dispatcher(Agent 通过 kanban_* 工具集自主 claim task) +> - Claude Code:Grove(共享项目工作区)、Swarm/Team(hub-spoke 协调) +> - MCP + A2A:MCP 提供上下文共享,A2A 提供 Agent 间直接通信 +> - 学术:Multi-Agent Blackboard System (arXiv:2510.01285) 消除中央协调器先验知识需求 + +#### 3.12.1 三层自主模型 + +``` +┌──────────────────────────────────────────────────────┐ +│ 庞统(中央协调) │ +│ 定方向、定约束、异常干预、持续观察 │ +│ 不微观管理:不指定每一步怎么做 │ +└────────────┬─────────────────────┬───────────────────┘ + │ │ + ┌────────▼────────┐ ┌────────▼────────┐ + │ Agent 自主权 │ │ Agent 自主权 │ + │ 执行方式自主决定 │ │ 执行方式自主决定 │ + │ 可主动发现问题 │ │ 可主动发现问题 │ + │ 可主动建议 │ │ 可主动建议 │ + └────────┬────────┘ └────────┬────────┘ + │ │ + ┌────────▼─────────────────────▼────────┐ + │ 共享意识空间(文件系统) │ + │ status.json → 全局状态实时摘要 │ + │ observations/ → Agent 主动观察 │ + │ moments.jsonl → 原子事件流 │ + │ steps/ → 各步骤产出物 │ + └──────────────────────────────────────┘ +``` + +**与 v2.3 的核心区别**: + +| 维度 | v2.3(妥协版) | v2.4(AI native) | +|------|-------------|----------------| +| 调度模式 | daemon 全权调度 | 庞统定方向,Agent 自主执行 | +| 信息获取 | Agent curl 查 API | Agent 直接 read 共享目录文件 | +| AI 参与 | 步骤完成后通知 | 持续推送执行摘要,庞统主动干预 | +| Agent 主动性 | 无 | observations 目录 + 主动建议机制 | +| 协作方式 | 庞统串行分配 | Agent 可观察其他 Agent 产出并主动调整 | + +#### 3.12.2 Agent 自主执行协议 + +Agent 被调度后,不只是“执行指令”,而是执行一套自主行为协议: + +``` +Agent 收到任务消息后: + +1. 【感知】read artifacts/task-{id}/status.json + → 了解全局:当前 phase、各步骤状态、异常列表 + +2. 【感知】read artifacts/task-{id}/observations/ + → 了解其他 Agent 的观察和建议 + → 特别是前序步骤 Agent 的发现 + +3. 【感知】read artifacts/task-{id}/steps/{前序步骤}/output.json + → 获取前序步骤的具体产出 + +4. 【执行】基于全局信息自主决定执行方式 + → 不需要庞统指定“用什么工具、什么方法” + → 根据任务意图 + 全局上下文自行判断 + +5. 【主动观察】如果执行中发现异常/有价值的发现: + → write artifacts/task-{id}/observations/{agent}-{seq}.md + → 内容:发现的问题、建议的调整、重要的洞察 + → 格式自由(Markdown),由庞统或其他 Agent 读取 + +6. 【回报】完成/失败后回报 daemon API + → POST /api/steps/{id}/complete 或 /fail +``` + +**关键设计**:步骤 1-3(感知)是**强制的**,写入 Agent 的 task-bootstrap Skill。 +这确保每个 Agent 执行前都有全局视野,而不是盲人摸象。 + +#### 3.12.3 Agent 任务消息模板(v2.4 增强) + +调度 Agent 时,消息内容不仅是“执行 X”,还包含: + +```markdown +## 任务:{step_title} + +### 意图 +{step_intent} → 目标状态:{end_state} + +### 全局上下文 +- 任务:{task_title} +- Phase:{current_phase} +- 前序步骤:{completed_steps_summary} +- **请先感知全局**:read artifacts/task-{id}/status.json 和 observations/ + +### 你的自主权 +- 执行方式由你决定(工具、方法、顺序) +- 发现异常请写入 observations/ +- 遇到专业外的问题主动回报,不硬撑 + +### 约束 +- 产出物必须写到 artifacts/task-{id}/steps/{step_id}/ +- 超时 {timeout_minutes} 分钟自动标记 blocked + +### 完成后 +POST /api/steps/{step_id}/complete +body: {artifacts: [...], confidence: 0-1, summary: "...", observations: [...]} +``` + +#### 3.12.4 庞统持续意识机制 + +庞统不是被动的审批节点,而是持续观察的指挥官。 + +**实现方式**:daemon 通过 `openclaw agent` CLI 定期推送执行摘要给庞统。 + +``` +触发时机(不是 cron,是事件驱动): + +1. 步骤完成事件 + → daemon 立即通知庞统 + → 庞统判断:正常→无干预 / 异常→主动发指令 + +2. Agent 写入 observation + → daemon 检测到新文件(inotify/fswatch) + → 推送给庞统:"赵云发现数据异常" + → 庞统决定:加步骤 / 调整方案 / 通知用户 + +3. 定期心跳(每 N 分钟,可配置) + → daemon 推送当前全局摘要 + → 庞统判断是否有异常趋势(如某步骤超时、Agent 连续失败) + → 正常→回"继续" / 异常→主动干预 + +4. AI 质量评估点(Phase 2/3 交界处) + → 庞统审查当前执行计划 vs 实际进展 + → 主动调整步骤、重新分配 Agent、升级问题 +``` + +**Token 消耗控制**(通过质量分级): +- `critical` 任务:每个事件都推送 +- `standard` 任务:步骤完成 + observation 时推送 +- `exploratory` 任务:仅步骤完成时推送 + +#### 3.12.5 文件系统 = 实时共享感知 + +**核心洞察**:文件系统天然就是“实时共享”的——一个 Agent write 了文件,另一个 Agent 立刻可以 read。 +不需要 WebSocket、不需要推送、不需要轮询 API。 + +关键在于让 Agent **知道去读什么**。这就是 `status.json` + `observations/` 的作用: + +- `status.json`:daemon 在每次状态变化后立即更新,Agent read 即可获得全局视野 +- `observations/`:Agent 发现问题时主动写入,其他 Agent read 即可感知 +- `steps/`:前序步骤的产出物就在文件系统里,不需要通过 API 传输 + +**为什么不用 WebSocket/实时推送?** +因为 Agent 的执行是 `openclaw agent` CLI 调用——每次调用是一个独立进程。 +Agent 不需要“订阅”事件流,而是在被调用时通过 read 文件获取全部所需上下文。 +这比实时推送更简单、更可靠(无连接断开问题)。 + +#### 3.12.6 Agent 主动协作场景 + +``` +场景 1:赵云发现数据异常 + → 赵云写入 observations/zhaoyun-001.md + → daemon 检测到 → 通知庞统 + → 庞统判断:需要加清洗步骤 + → 庞统调整计划 → daemon 更新 status.json + plan.json + → 张飞被调度时 read status.json,看到新增的清洗步骤 + → 张飞 read observations/zhaoyun-001.md,了解数据异常详情 + → 张飞自主决定:在策略编码前加入数据清洗逻辑 + +场景 2:张飞主动建议 + → 张飞执行策略编码时,发现更好的技术指标 + → 张飞写入 observations/zhangfei-001.md + → daemon 通知庞统 + → 庞统判断:值得尝试,修改计划允许探索 + → 关羽审核时 read observations/,看到张飞的建议,针对性审查 + +场景 3:关羽主动拦截 + → 关羽审核代码时发现风险 + → 关羽写入 observations/guanyu-001.md(标记为 blocking) + → daemon 立即通知庞统 + → 庞统决定:暂停后续步骤,要求张飞修改 + → 不需要等步骤“完成”才发现问题 +``` + +--- + ## 4. 已决策(全部) | # | 决策 | 结论 | 理由 |