diff --git a/docs/design/technical-design-v2.6.md b/docs/design/technical-design-v2.6.md index d654744..7335a1f 100644 --- a/docs/design/technical-design-v2.6.md +++ b/docs/design/technical-design-v2.6.md @@ -81,7 +81,98 @@ └───────────────────────────────────────────────────────────────────────────┘ ``` -### 1.2 交互路径详解 +### 1.2 多用户并发架构 + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ 多用户并发入口 │ +│ │ +│ 用户A ──→ OpenClaw Chat ──→ 庞统 Agent ──→ 项目X 任务A1, A2 │ +│ 用户B ──→ OpenClaw Chat ──→ 庞统 Agent ──→ 项目Y 任务B1 │ +│ 用户C ──→ Dashboard ─────→ REST API ────→ 项目X 任务C1 │ +│ │ +│ 所有用户的请求汇聚到同一个 Daemon ticker（30s 扫描全部项目） │ +│ 并发由 ActiveAgentCounter 控制（max_global=5, max_per_agent=1） │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +**多用户设计要点**： + +| 维度 | 机制 | 说明 | +|------|------|------| +| 项目隔离 | per-project blackboard.db | 不同项目的任务、产出、评论完全隔离 | +| 并发控制 | ActiveAgentCounter | 全局 max_global=5 同时最多 5 个 Agent，per-agent max=1 串行执行 | +| 资源竞争 | Agent 池排队 | 张飞正在执行任务A，任务B 排队等张飞释放 | +| tick 调度 | 30s 扫全部项目 | 每轮 tick 按 project_id 轮询，每项目独立 tick | +| 事件驱动 | 共享 Inbox JSONL | 任何项目的 Agent 完成都秒级触发 Daemon | +| 前端隔离 | URL path `/api/projects/{pid}/` | Dashboard 切换项目，SSE 按 pid 过滤 | + +**当前规模定位**：单机部署（Mac mini M4, 16GB），3-5 个活跃项目，同时 ≤5 个 Agent 并发。超出此规模需要架构演进（见 §15.3）。 + +### 1.3 核心数据流 + +``` + ┌──────────┐ + │ 用户需求 │ + └────┬─────┘ + │ + 庞统规划+拆解 + │ + ┌────▼─────┐ + │ 任务写入 │ + │ 黑板 │ + └────┬─────┘ + │ + ┌──────────┼──────────┐ + ▼ ▼ ▼ + pending in_review blocked + │ │ │ + │ │ ┌────┘ + │ │ ▼ + 调度Agent 审查流水线 依赖满足 + (受Counter (分级处理) │ + 控制)│ │ → pending + │ │ + ▼ │ + ┌──────────────┐ │ + │ Agent 执行 │ │ + │ (独立进程) │ │ + └───┬──────┬───┘ │ + │ │ │ + 写产出 写评论 │ + │ │ │ + ▼ │ │ + Guardrail │ │ + 检查 ───────┤ │ + │ │ │ + ┌────┘ │ │ + ▼ │ │ + 通过 → 触发审查 │ │ + 失败 → 回 working │ │ + │ │ │ + │ ┌─────┘ │ + │ ▼ │ + │ 通过 → done ───────┤──→ 一级蒸馏 → 经验注入 + │ │ │ + │ 不通过 → 反驳权 │ + │ │ ↕ 协商 │ + │ │ max_rounds │ + │ │ ↓ 超轮次 │ + │ 庞统裁决 │ + │ │ │ + │ ├→ done/revision│ + │ └───────────────┘ + │ + └──→ 完成后检查：下游 blocked 任务是否可解锁 +``` + +**关键循环路径**（非直线流程）： +1. **Guardrail 失败循环**：产出写完 → Guardrail 检查 → 失败 → 回 working → Agent 重新执行 +2. **审查-反驳循环**：审查不通过 → 反驳权协商（≤ max_rounds 轮）→ 超轮次庞统裁决 +3. **依赖解锁循环**：任务完成 → 检查下游 blocked 任务 → 依赖满足 → 下游变 pending → 调度 +4. **经验闭环**：任务完成 → 一级蒸馏 → 经验注入 → 下次 build_bootstrap 复用 + +### 1.4 交互路径详解 | 路径 | 方式 | 说明 | |------|------|------| @@ -94,7 +185,7 @@ | Daemon → Dashboard | SSE `/api/events` | 任务状态变更、审查结果、通知推送 | | Dashboard → Daemon | REST API | 查状态、手动 tick、项目管理 | -### 1.3 组件职责矩阵 +### 1.5 组件职责矩阵 | 层 | 组件 | 职责 | 技术 | |----|------|------|------| @@ -119,21 +210,34 @@ --- -## 2. 技术栈 +## 2. 技术栈与选型权衡 -| 组件 | 选型 | 版本 | 理由 | -|------|------|------|------| -| Daemon 进程管理 | PM2 | 6.0.14 | 独立进程 sanguo-moziplus-v2 | -| Daemon 框架 | Python + asyncio | 3.9+ | tick 循环 + FastAPI 共存 | -| 黑板存储 | SQLite（per-project） | 3.51+ | WAL 模式，物理隔离 | -| HTTP API | FastAPI + uvicorn | 独立安装 | 端口 8083 | -| Agent 调度 | openclaw CLI / sessions_spawn | 2026.5.7 | Full Agent / Subagent 双路径 | -| 前端 | React + Vite + TypeScript | 复用 v1.0 | 5页面 Dashboard | -| 实时推送 | SSE (Server-Sent Events) | FastAPI 内置 | 降级轮询兜底 | -| Git | gitee + gitea | 双远程 | 开发→安装同步 | -| 配置 | YAML (PyYAML) | — | guardrails / review_protocols / template_components | +### 2.1 技术栈总览 -**不加重型新依赖。** 所有组件基于已有环境。 +| 组件 | 选型 | 版本 | +|------|------|------| +| Daemon 进程管理 | PM2 | 6.0.14 | +| Daemon 框架 | Python + asyncio | 3.9+ | +| 黑板存储 | SQLite (per-project) | 3.51+ | +| HTTP API | FastAPI + uvicorn | 独立安装 | +| Agent 调度 | openclaw CLI / sessions_spawn | 2026.5.7 | +| 前端 | React + Vite + TypeScript | 复用 v1.0 | +| 实时推送 | SSE | FastAPI 内置 | +| 配置 | YAML (PyYAML) | — | + +### 2.2 选型权衡分析 + +**每个关键技术选型都遵循"不加重型新依赖"原则，基于已有环境。** + +| 决策 | 选择 | 备选 | 选择理由 | 备选缺陷 | +|------|------|------|---------|---------| +| HTTP 框架 | **FastAPI** | Starlette / Litestar / Flask | 2025-2026 AI Agent 编排系统事实标准（Agno AgentOS、OpenAI Agents SDK 均用 FastAPI）；内置 OpenAPI + SSE + async；团队已有 v1 经验 | Starlette 需自己拼 Auth/SSE/DI；Litestar 太新生态小；Flask 不原生 async | +| 黑板存储 | **SQLite** | PostgreSQL / JSON 文件 | per-project 物理隔离（单项目故障不影响其他）；零运维（无 DB server）；WAL 模式足够应对单机并发；团队已有 WAL+busy_timeout 经验 | PostgreSQL 需额外 DB server 运维，对单机场景过重；JSON 文件无事务、无并发保护 | +| 实时推送 | **SSE** | WebSocket / 轮询 | 单向推送足够（Daemon→Dashboard）；FastAPI 原生支持；自动重连；降级轮询简单 | WebSocket 双向能力多余，增加复杂度；纯轮询延迟高 | +| 并发模型 | **纯 asyncio 单线程** | threading / multiprocessing | 与 FastAPI event loop 共存；Agent spawn 用 create_subprocess_exec 非阻塞；无锁竞争问题 | threading 引入 GIL + 锁复杂度；multiprocessing 进程间通信代价大 | +| 配置格式 | **YAML** | TOML / JSON / Python | guardrails/review_protocols 需要人可读可编辑；YAML 支持 multiline string（prompt 模板）；紧急运维可直接编辑 | TOML multiline 不便；JSON 无注释；Python 有安全风险 | +| 进程管理 | **PM2** | systemd / supervisord | 已有 10 个 PM2 进程运行；log management + auto restart + 开机自启；ecosystem.config.cjs 统一管理 | systemd 需 root 权限；supisord 不如 PM2 对 Node.js 友好 | +| Agent spawn | **asyncio.create_subprocess_exec** | subprocess.Popen / sessions_spawn | Full Agent 需要独立进程+独立 session；async 版本不阻塞 event loop；下次 tick 检查产出而非等待返回 | Popen 同步阻塞 event loop；sessions_spawn 仅适用无身份 Subagent | ---