sanguo/sanguo_moziplus_v2
8
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

auto-sync: 2026-05-14 08:46:47

Browse Source
This commit is contained in:
cfdaily
2026-05-14 08:46:47 +08:00
parent 54f223e9bd
commit 20e63c3c86
1 changed files with 222 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/architecture-v2.md
+222 -31
View File
@@ -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
```