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

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 调度、工具执行 |
+| 编排引擎 | **自建 Daemon** (FastAPI + uvicorn) | HTTP API + 事件循环，PM2 管理 |
-| Agent 通信 | **Blackboard 文件系统** | JSON/JSONL/Markdown，git 可追踪 |
+| 数据存储 | **SQLite** (WAL mode) | 任务/计划/事件/Agent状态/经验 |
-| 指挥官 | **庞统 persistent session** | OpenClaw session + cron wake |
+| 文件存储 | **文件系统** (artifacts) | 产出物（代码/数据/文档），git 可追踪 |
-| Agent 调度 | **sessions_send / sessions_spawn** | OpenClaw 原生能力 |
+| 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** | 对话式入口（庞统主 session） |
-| 前端 | **OpenClaw Control Center + 自定义 UI** | 对话式入口 |
+| 经验检索 | **ripgrep + SQLite FTS** | 文本搜索 |
-| 数据存储 | **文件系统** | 不引入数据库，保持简单 |
-| 经验检索 | **ripgrep** | 文本搜索，无额外依赖 |
 | 同步 | **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                    # 入口
+│   ├── main.py                    # FastAPI 入口
-│   ├── blackboard.py              # Blackboard 读写 API
+│   ├── 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              # 经验沉淀引擎
+│   └── config_loader.py           # YAML/JSON 配置加载
-│   └── scanner.py                 # 黑板变化扫描器
+├── config/                        # 配置文件
-├── skills/                        # Skill 包
+│   ├── states.yaml
-│   ├── control-unit/              # 庞统指挥官 Skill
+│   ├── step-states.yaml
-│   │   └── SKILL.md               # 四相循环 prompt + 路由逻辑
+│   ├── events.yaml
-│   ├── agent-bootstrap/           # Agent 引导 Skill
+│   ├── agent-registry.json
-│   │   └── SKILL.md               # Boids 规则 + 元认知 + Auftragstaktik 注入
+│   ├── templates/
-│   └── wiki-query/                # 复用已有 wiki 查询 Skill
+│   └── settings.yaml
-├── config/
+├── artifacts/                     # 产出物目录（git 追踪）
-│   ├── agent-registry.json        # Agent 能力画像
+├── skills/                        # Skill 包（供 Agent 加载）
-│   └── settings.json              # 全局配置
+│   ├── task-bootstrap/            # Agent 任务引导 Skill
+│   │   └── SKILL.md               # Boids + 元认知 + Auftragstaktik
+│   └── wiki-query/                # 复用已有
 ├── docs/
-│   ├── design/                    # 设计文档
+│   ├── design/
-│   └── research/                  # 调研报告
+│   └── research/
 ├── scripts/
-│   ├── create-task.py             # CLI: 创建任务
+│   ├── create-task.sh             # CLI: 创建任务
-│   ├── status.py                  # CLI: 查看状态
+│   ├── status.sh                  # CLI: 查看状态
 │   └── bootstrap.sh               # 初始化脚本
 └── README.md
 ```