diff --git a/docs/design/deployment-v2.6.md b/docs/design/deployment-v2.6.md index c52e48b..e951173 100644 --- a/docs/design/deployment-v2.6.md +++ b/docs/design/deployment-v2.6.md @@ -41,16 +41,17 @@ PM2 (进程管理器) 进程内部结构： sanguo-moziplus-v2 -├── uvicorn (FastAPI) +├── uvicorn (FastAPI) — asyncio event loop │ ├── API 路由（黑板/Daemon/SSE/项目） │ ├── 静态文件服务（frontend/dist/） │ └── SSE 推送端点（/api/events） ├── asyncio background task: Daemon ticker（30s） ├── asyncio background task: Inbox watcher（1s 轮询） -└── ActiveAgentCounter（异步信号量） +├── Agent spawn: asyncio.create_subprocess_exec（异步非阻塞） +└── ActiveAgentCounter（asyncio.Semaphore） ``` -**关键：v2 是单进程。** Daemon ticker 和 API 在同一个 asyncio event loop 中。不新增 PM2 进程。 +**纯 asyncio 单线程。** Daemon ticker、API、SSE、Agent spawn 全部在同一个 asyncio event loop 中，无同步阻塞调用。Full Agent spawn 用 `asyncio.create_subprocess_exec`（不 await 完成），Subagent 用 Gateway 内部 API。不新增 PM2 进程。 --- @@ -376,9 +377,9 @@ Phase 4: v1 下线 ├── v2 可选接管 8082 └── v1 代码和数据库保留只读（历史归档） -Phase 5: Mail 逐步下线 - ├── 黑板评论替代 Mail 协作 - ├── 逐个 Agent 关闭 Mail poller +Phase 5: Mail 逐步下线（远期目标，与黑板评论长期共存） + ├── v2 上线后 Mail 和黑板评论并行 + ├── 所有 Agent 的 Skill 更新支持黑板评论后逐步关闭 Mail poller └── 最终只保留 Mail 作为外部通知通道 ``` diff --git a/docs/design/technical-design-v2.6.md b/docs/design/technical-design-v2.6.md index e2f148b..ebde9f2 100644 --- a/docs/design/technical-design-v2.6.md +++ b/docs/design/technical-design-v2.6.md @@ -7,7 +7,160 @@ --- -## 1. 技术栈 +## 1. 总体技术架构 + +### 1.1 全局架构图 + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 用户层 │ +│ ┌──────────────────┐ ┌──────────────────┐ │ +│ │ Agent 对话入口 │ │ Dashboard (8083) │ │ +│ │ (OpenClaw Chat) │ │ React + Vite │ │ +│ └────────┬─────────┘ └────────┬─────────┘ │ +│ │ │ │ +└───────────┼───────────────────────┼────────────────────────────────────────┘ + │ │ SSE + │ CLI / sessions_send │ REST API + ▼ ▼ +┌───────────────────────────────────────────────────────────────────────────┐ +│ API 层 (FastAPI) │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ 黑板 API │ │ Daemon │ │ SSE 推送 │ │ 项目管理 │ │ +│ │ CRUD │ │ 控制API │ │ /events │ │ API │ │ +│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ +└───────┼────────────┼────────────┼────────────┼────────────────────────────┘ + │ │ │ │ +┌───────┼────────────┼────────────┼────────────┼────────────────────────────┐ +│ │ Daemon 引擎层 (asyncio event loop) │ +│ │ │ │ │ │ +│ ┌────▼────────────▼────────────▼────────────▼─────┐ │ +│ │ Daemon ticker (30s) │ │ +│ │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │ +│ │ │ Inbox │ │ 审查流水线│ │ 依赖推进/反驳权 │ │ │ +│ │ │ JSONL │ │ (4级分级) │ │ /蒸馏/健康自检 │ │ │ +│ │ └──────────┘ └──────────┘ └──────────────────┘ │ │ +│ │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │ +│ │ │ Agent │ │ Bootstrap│ │ ActiveAgent │ │ │ +│ │ │ 调度器 │ │ 拼装器 │ │ Counter │ │ │ +│ │ └────┬─────┘ └──────────┘ └──────────────────┘ │ │ +│ └───────┼─────────────────────────────────────────┘ │ +│ │ 3级调度: Daemon直接 / Full Agent / Subagent │ +│ │ │ +│ ┌───────▼─────────────────────────────────────────┐ │ +│ │ Agent Spawn 层 │ │ +│ │ asyncio.create_subprocess_exec │ │ +│ │ ┌──────────────┐ ┌──────────────┐ │ │ +│ │ │ Full Agent │ │ Subagent │ │ │ +│ │ │ (openclaw │ │ (sessions_ │ │ │ +│ │ │ agent CLI) │ │ spawn API) │ │ │ +│ │ └──────┬───────┘ └──────┬───────┘ │ │ +│ └─────────┼───────────────────┼───────────────────┘ │ +│ │ │ │ +│ ┌─────────▼───────────────────▼───────────────────┐ │ +│ │ Agent 执行环境 │ │ +│ │ SOUL.md + IDENTITY.md + Skills + 工具集 │ │ +│ │ ┌──────────────────────────────────────┐ │ │ +│ │ │ L0 铁律 (Hook注入) │ │ │ +│ │ │ L1 角色 (Agent自带) │ │ │ +│ │ │ L2 引擎注入 (操作规范+背景+上下文) │ │ │ +│ │ │ L3 被动参考 (Skill按需加载) │ │ │ +│ │ └──────────────────────────────────────┘ │ │ +│ └──────────────┬──────────────────────────────────┘ │ +│ │ 产出写入/评论/决策/观察 │ +│ ▼ │ +│ ┌──────────────────────────────────────────────────┐ │ +│ │ 黑板数据层 (per-project SQLite) │ │ +│ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │ +│ │ │tasks │ │comments│ │outputs│ │reviews│ │events│ │ │ +│ │ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │ │ +│ │ ┌──────┐ ┌──────┐ ┌──────────────┐ │ │ +│ │ │decisions│ │observations│ │experiences│ │ │ +│ │ └──────┘ └──────┘ └──────────────┘ │ │ +│ └──────────────────────────────────────────────────┘ │ +│ │ │ +│ ┌──────────────▼──────────────────────────────────┐ │ +│ │ 配置 & 知识层 │ │ +│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ +│ │ │ _registry │ │ guardrails │ │ review_ │ │ │ +│ │ │ .yaml │ │ .yaml │ │ protocols/ │ │ │ +│ │ └────────────┘ └────────────┘ └────────────┘ │ │ +│ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ +│ │ │ prompt_ │ │ schemas/ │ │ skills/ │ │ │ +│ │ │ templates/ │ │ (JSON) │ │ (builtin+ │ │ │ +│ │ │ │ │ │ │ custom) │ │ │ +│ │ └────────────┘ └────────────┘ └────────────┘ │ │ +│ │ ┌────────────┐ │ │ +│ │ │ project.yaml│ (per-project 覆盖) │ │ +│ │ └────────────┘ │ │ +│ └─────────────────────────────────────────────────┘ │ +│ │ +│ 全部运行在单一 asyncio event loop 中（与 FastAPI 共享） │ +└───────────────────────────────────────────────────────────────────────────┘ +``` + +### 1.2 核心数据流 + +``` +用户需求 → 庞统规划 → 任务拆解 → 写入黑板 + │ + ┌───────────────┘ + ▼ + Daemon tick 扫描 + │ + ┌───────────┼───────────┐ + ▼ ▼ ▼ + pending任务 review任务 blocked任务 + 调度Agent执行 处理审查流水线 检查依赖推进 + │ │ + ▼ ▼ + Agent执行 ┌─────────────┐ + (Full/Sub) │ 审查分级 │ + │ │ high→辩论 │ + ▼ │ standard→单审│ + 写入产出 │ low→Guardrail│ + 到黑板 └──────┬──────┘ + │ │ + │ ┌──────┴──────┐ + │ ▼ ▼ + │ 通过→done 不通过→反驳权 + │ │ + │ max_rounds + │ │ + │ 超轮次→庞统裁决 + │ │ + └───────────────────┘ + │ + ▼ + 任务完成 → 一级蒸馏 → 经验注入 +``` + +### 1.3 组件职责矩阵 + +| 层 | 组件 | 职责 | 技术 | +|----|------|------|------| +| **用户层** | Agent 对话 | 自然语言交互入口 | OpenClaw Chat | +| | Dashboard | 可视化监控/配置/Checkpoint | React + Vite (8083) | +| **API 层** | FastAPI | REST API + SSE + 静态文件 | uvicorn | +| **引擎层** | Daemon ticker | 30s 状态扫描 + 事件驱动 | asyncio background task | +| | 调度器 | 三级调度 (Daemon/Full/Sub) | DISPATCH_RULES 配置表 | +| | 审查流水线 | 分级审查 + 反驳权 + 辩论 | review_flow.py | +| | Bootstrap 拼装 | 四层上下文 L0-L3 | prompt_templates + YAML | +| | Inbox watcher | JSONL 秒级事件推送 | asyncio 1s 轮询 | +| | 健康自检 | 逻辑死循环检测 | 连续 N tick 无变更告警 | +| **Agent 层** | Full Agent | 有身份角色的任务执行 | openclaw agent CLI | +| | Subagent | 无身份一次性检查 | sessions_spawn API | +| **数据层** | 黑板 DB | 任务/评论/产出/审查/经验 | SQLite per-project | +| | Inbox | 跨进程事件队列 | JSONL + truncate | +| | _registry.yaml | 项目注册表 | YAML (人可读) | +| **配置层** | guardrails.yaml | L1/L2 检查规则 | YAML | +| | review_protocols/ | 审查协议 | YAML | +| | skills/ | 三层载体 (Memory/Skill/Rule) | SKILL.md + meta.yaml | +| | project.yaml | per-project 配置覆盖 | YAML | + +--- + +## 2. 技术栈 | 组件 | 选型 | 版本 | 理由 | |------|------|------|------|