From 20e63c3c86ba3ee01d2dd9603533e8b391b0463c Mon Sep 17 00:00:00 2001 From: cfdaily Date: Thu, 14 May 2026 08:46:47 +0800 Subject: [PATCH] auto-sync: 2026-05-14 08:46:47 --- docs/design/architecture-v2.md | 253 +++++++++++++++++++++++++++++---- 1 file changed, 222 insertions(+), 31 deletions(-) diff --git a/docs/design/architecture-v2.md b/docs/design/architecture-v2.md index 8bdf28e..b47c93f 100644 --- a/docs/design/architecture-v2.md +++ b/docs/design/architecture-v2.md @@ -1,10 +1,11 @@ # moziplus v2.0 — AI 原生多Agent编排平台 架构设计 -**版本**: v2.0 +**版本**: v2.1（技术架构修订） **日期**: 2026-05-14 **作者**: 庞统（副军师） **状态**: 草案，待用户确认 -**调研基础**: `docs/research/shared-consciousness-research.md` +**调研基础**: `docs/research/shared-consciousness-research.md` +**变更记录**: v2.1 修正了 Agent 调度方式（放弃 sessions_send/sessions_spawn，改用主 session + Daemon API） --- @@ -748,51 +749,241 @@ class TokenBudget: --- -## 3. 技术实现方案 +## 3. 技术实现方案（v2.1 修订） + +> ⚠️ v2.1 关键修正： +> - ❌ 废弃 sessions_send（不稳定、timeout） +> - ❌ 废弃 sessions_spawn（sub-agent 大爆炸、session 文件堆积） +> - ❌ 废弃 cron wake（不稳定） +> - ✅ 采用自建 Daemon HTTP API + SQLite（v1.0 已验证可靠） +> - ✅ Agent 复用主 session，通过 Daemon API 回报 +> - ✅ 所有状态/流转/事件类型从配置文件加载，不硬编码 ### 3.1 技术栈 | 层级 | 技术 | 说明 | |------|------|------| -| Agent 运行时 | **OpenClaw Gateway** | 已有的 session 管理、agent 调度、工具执行 | -| Agent 通信 | **Blackboard 文件系统** | JSON/JSONL/Markdown，git 可追踪 | -| 指挥官 | **庞统 persistent session** | OpenClaw session + cron wake | -| Agent 调度 | **sessions_send / sessions_spawn** | OpenClaw 原生能力 | +| 编排引擎 | **自建 Daemon** (FastAPI + uvicorn) | HTTP API + 事件循环，PM2 管理 | +| 数据存储 | **SQLite** (WAL mode) | 任务/计划/事件/Agent状态/经验 | +| 文件存储 | **文件系统** (artifacts) | 产出物（代码/数据/文档），git 可追踪 | +| Agent 运行时 | **OpenClaw Gateway** | Agent 的主 session 管理 | +| Agent 通信 | **Daemon HTTP API** | Agent 回报结果、查询黑板 | +| Agent 调度 | **Gateway WS API → 主 session** | 发消息到 Agent 主 session（不创建 sub-agent） | +| 庞统通信 | **Gateway WS API** | Daemon → 庞统主 session 注入 systemEvent | +| 配置管理 | **YAML/JSON 配置文件** | 状态/流转/事件/模板全部配置化 | | 文件锁 | **fcntl / O_EXCL** | 零依赖，跨进程安全 | -| 事件驱动 | **cron 扫描 + wake** | OpenClaw 原生能力 | -| 前端 | **OpenClaw Control Center + 自定义 UI** | 对话式入口 | -| 数据存储 | **文件系统** | 不引入数据库，保持简单 | -| 经验检索 | **ripgrep** | 文本搜索，无额外依赖 | +| 前端 | **OpenClaw Control Center** | 对话式入口（庞统主 session） | +| 经验检索 | **ripgrep + SQLite FTS** | 文本搜索 | | 同步 | **sanguo_git_sync** | 已有的三端 Git 同步 | -### 3.2 核心代码模块 +### 3.2 为什么不用 OpenClaw 原生调度？ + +| 方案 | 问题 | 结论 | +|------|------|------| +| sessions_send | 不稳定，经常 timeout | ❌ 废弃 | +| cron wake | 各种问题，不可靠 | ❌ 废弃 | +| sessions_spawn | 每次创建新 session，文件堆积（庞统 296个/354MB），sub-agent 缺少 SOUL.md | ❌ 废弃 | +| **自建 Daemon HTTP API** | v1.0 已验证（FastAPI + SQLite + PM2），可靠 | ✅ 采用 | + +### 3.3 Agent 调度方式：主 session + HTTP 回报 + +**核心原则：不创建 sub-agent，复用 Agent 主 session。** + +``` +Daemon 需要调度张飞执行编码任务： + +1. Daemon 通过 Gateway WS API 发消息到 agent:zhangfei-dev:main + - 消息内容：step intent + end_state + constraints + - 张飞在自己的主 session 里收到消息 + +2. 张飞执行任务 + - 读取 daemon API 获取需要的上下文 + - 在自己的 workspace 里工作 + +3. 张飞通过 daemon HTTP API 回报结果 + - curl POST http://localhost:8080/api/step/{id}/complete + - body: { artifacts: [...], confidence: 0.9, summary: "..." } + - daemon 做幻觉门控（验证文件存在） + - daemon 更新 SQLite 状态 + - daemon 触发下一步 + +4. daemon 通过 Gateway WS API 通知庞统进展 + - 庞统在主 session 收到 systemEvent + - 庞统决定下一步操作 +``` + +**为什么不用 sub-agent？** +- 每个 sub-agent 产生 3-5 个磁盘文件（.jsonl + .trajectory + .path） +- 庞统已有 296 个 session 文件 354MB，姜维 227 个 1.4GB +- sub-agent 没有 SOUL.md/IDENTITY.md，行为不够可控 +- cleanup: delete 只是从 UI 隐藏，文件仍然在磁盘上 + +**主 session 的上下文膨胀怎么办？** +- Agent 每完成一个任务步骤后，daemon 发 systemEvent 触发 reset +- OpenClaw 的 reset 会压缩历史，释放上下文空间 +- 或者：每 N 个步骤后自动 reset 一次 + +### 3.4 用户查看进展的流程 + +``` +用户: "任务进展如何？" + │ + ▼ +庞统主 session 收到消息 + │ + ▼ +庞统调用 Daemon API: + GET http://localhost:8080/api/task/{task_id}/status + │ + ▼ +Daemon 返回: + { + "task": { "title": "...", "state": "executing", "phase": 3 }, + "plan": { "steps": [...], "completed": 3, "total": 5 }, + "current_step": { + "agent": "zhangfei", + "status": "executing", + "started_at": "...", + "progress": "正在编码策略逻辑" + }, + "recent_moments": [ + { "type": "agent_completed", "agent": "zhaoyun", "summary": "数据获取完成" }, + { "type": "plan_adjusted", "reason": "发现数据质量问题" } + ], + "anomalies": [], + "token_budget": { "used": 120000, "total": 500000 } + } + │ + ▼ +庞统用 AI 生成人类可读的进展汇报，回复用户 +``` + +**关键设计：庞统是无状态的** +- 所有任务状态在 Daemon 的 SQLite 里 +- 庞统 session 不保存任务状态 +- 每次被问到进展，实时查询 Daemon API +- 这比 v1.0 好：v1.0 庞统需要在 session 里记住所有任务，上下文很快就爆了 + +### 3.5 配置化（零硬编码） + +``` +config/ +├── states.yaml # 任务状态定义 + 合法流转 +├── step-states.yaml # 步骤状态定义 + 合法流转 +├── events.yaml # 事件类型定义 +├── agent-registry.json # Agent 能力画像 +├── templates/ # 任务模板 +│ ├── backtest.yaml +│ ├── strategy-research.yaml +│ └── deployment.yaml +└── settings.yaml # 全局设置 +``` + +**states.yaml**: +```yaml +# 任务级状态定义 +# Daemon 启动时加载，代码里不允许出现硬编码的状态名 +states: + - name: exploring + description: "需求探索中" + phase: 1 + transitions_to: [planning, cancelled] + + - name: planning + description: "动态规划中" + phase: 2 + transitions_to: [executing, planning, cancelled] + + - name: executing + description: "自主执行中" + phase: 3 + transitions_to: [reviewing, executing, cancelled] + + - name: reviewing + description: "验收中" + phase: 4 + transitions_to: [completed, executing, cancelled] + + - name: completed + description: "任务完成" + transitions_to: [] # 终态 + + - name: cancelled + description: "已取消" + transitions_to: [] # 终态 +``` + +**step-states.yaml**: +```yaml +# 步骤级状态定义 +step_states: + - name: pending + transitions_to: [assigned, cancelled] + - name: assigned + transitions_to: [executing, cancelled] + - name: executing + transitions_to: [completed, failed, blocked, cancelled] + - name: completed + transitions_to: [] + - name: failed + transitions_to: [pending] # 可重试 + max_retries: 3 + - name: blocked + transitions_to: [pending, cancelled] +``` + +**代码中禁止出现硬编码状态名**： +```python +# ❌ 禁止 +if task.state == "executing": + +# ✅ 正确 +EXECUTING = config.get_state("executing") +if task.state == EXECUTING: +``` + +### 3.6 核心代码模块 ``` sanguo_moziplus_v2/ -├── blackboard/ # 共享意识空间（数据目录，git 追踪） ├── daemon/ # 守护进程 -│ ├── main.py # 入口 -│ ├── blackboard.py # Blackboard 读写 API +│ ├── main.py # FastAPI 入口 +│ ├── api/ # HTTP API 路由 +│ │ ├── tasks.py # 任务 CRUD +│ │ ├── steps.py # 步骤 CRUD + 回报 +│ │ ├── board.py # 黑板查询 +│ │ ├── moments.py # 事件查询 +│ │ └── agents.py # Agent 状态/心跳 +│ ├── engine/ # 编排引擎 +│ │ ├── orchestrator.py # 编排主循环（事件驱动） +│ │ ├── planner.py # 动态规划 +│ │ ├── selector.py # Agent 选择 +│ │ ├── validator.py # 产出验证（幻觉门控） +│ │ └── experience.py # 经验沉淀引擎 +│ ├── gateway_client.py # Gateway WS API 客户端 +│ ├── db.py # SQLite 数据层 │ ├── lock.py # 文件锁实现 -│ ├── health.py # 健康检查 +│ ├── health.py # 健康检查（daemon 内部定时） │ ├── budget.py # Token 预算管理 -│ ├── experience.py # 经验沉淀引擎 -│ └── scanner.py # 黑板变化扫描器 -├── skills/ # Skill 包 -│ ├── control-unit/ # 庞统指挥官 Skill -│ │ └── SKILL.md # 四相循环 prompt + 路由逻辑 -│ ├── agent-bootstrap/ # Agent 引导 Skill -│ │ └── SKILL.md # Boids 规则 + 元认知 + Auftragstaktik 注入 -│ └── wiki-query/ # 复用已有 wiki 查询 Skill -├── config/ -│ ├── agent-registry.json # Agent 能力画像 -│ └── settings.json # 全局配置 +│ └── config_loader.py # YAML/JSON 配置加载 +├── config/ # 配置文件 +│ ├── states.yaml +│ ├── step-states.yaml +│ ├── events.yaml +│ ├── agent-registry.json +│ ├── templates/ +│ └── settings.yaml +├── artifacts/ # 产出物目录（git 追踪） +├── skills/ # Skill 包（供 Agent 加载） +│ ├── task-bootstrap/ # Agent 任务引导 Skill +│ │ └── SKILL.md # Boids + 元认知 + Auftragstaktik +│ └── wiki-query/ # 复用已有 ├── docs/ -│ ├── design/ # 设计文档 -│ └── research/ # 调研报告 +│ ├── design/ +│ └── research/ ├── scripts/ -│ ├── create-task.py # CLI: 创建任务 -│ ├── status.py # CLI: 查看状态 +│ ├── create-task.sh # CLI: 创建任务 +│ ├── status.sh # CLI: 查看状态 │ └── bootstrap.sh # 初始化脚本 └── README.md ```