# v2.6 技术方案设计 **版本**: v2.6.2-tech **基于**: architecture-v2.6.md (v2.6.11) **作者**: 庞统（副军师）🐦 **日期**: 2026-05-16 --- ## 1. 总体技术架构 ### 1.1 全局架构图 ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ 用户层 │ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ Agent 对话入口 │ │ Dashboard (8083) │ │ │ │ (OpenClaw Chat) │ │ React + Vite │ │ │ └────────┬─────────┘ └────────┬─────────┘ │ │ │ │ │ │ 自然语言对话 REST API + SSE │ │ │ │ │ └───────────┼───────────────────────┼────────────────────────────────────────┘ ▼ ▼ ┌───────────────────────────────┐ ┌──────────────────────────────────────┐ │ Agent 执行环境（独立进程） │ │ v2 主进程（PM2: sanguo-moziplus-v2） │ │ │ │ asyncio event loop │ │ ┌─────────────────────────┐ │ │ │ │ │ L0 铁律 (OpenClaw Hook) │ │ │ ┌─────────────────────────────────┐ │ │ │ L1 角色 (SOUL/IDENTITY) │ │ │ │ API 层 (FastAPI + uvicorn) │ │ │ │ L2 引擎注入 (bootstrap) │ │ │ │ ┌──────┐ ┌──────┐ ┌────────┐ │ │ │ │ L3 被动参考 (Skill) │ │ │ │ │黑板API│ │项目API│ │SSE推送 │ │ │ │ └─────────────────────────┘ │ │ │ └──┬───┘ └──┬───┘ └───┬────┘ │ │ │ │ │ └─────┼────────┼─────────┼───────┘ │ │ Agent → 黑板 的交互方式： │ │ │ │ │ │ │ ① CLI (blackboard.py) ───────┼──┼──→ 直接操作黑板 DB │ │ ② Inbox JSONL ──────────────┼──┼──→ 秒级事件推送给 Daemon │ │ │ │ │ │ │ │ ┌─────────────────────────────────┐ │ │ │ │ │ Daemon 引擎层（同一 event loop）│ │ │ │ │ │ │ │ │ │ │ │ ticker (30s scan) │ │ │ │ │ │ ┌──────────┐ ┌──────────────┐ │ │ │ │ │ │ │审查流水线 │ │ 依赖推进 │ │ │ │ │ │ │ │(4级分级) │ │ 反驳权/蒸馏 │ │ │ │ │ │ │ └──────────┘ └──────────────┘ │ │ │ │ │ │ ┌──────────┐ ┌──────────────┐ │ │ │ │ │ │ │Agent调度器│ │Bootstrap拼装 │ │ │ │ ← asyncio.create_subprocess │ │ │ └────┬─────┘ └──────────────┘ │ │ │ _exec (spawn 不等返回) │←─┼──┼───────┘ │ │ │ │ │ │ ┌──────────────────────────────┐│ │ │ │ │ │ │ ActiveAgentCounter (并发控制) ││ │ │ │ │ │ └──────────────────────────────┘│ │ │ │ │ └─────────────────────────────────┘ │ │ │ │ │ │ │ │ ┌─────────────────────────────────┐ │ │ │ │ │ 黑板数据层 (per-project SQLite) │ │ │ │ │ │ ┌─────┐ ┌──────┐ ┌──────┐ │ │ │ │ │ │ │tasks│ │outputs│ │reviews│ │ │ │ │ │ │ └─────┘ └──────┘ └──────┘ │ │ │ │ │ │ ┌──────────┐ ┌───────────┐ │ │ │ │ │ │ │comments │ │experiences│ │ │ │ │ │ │ │decisions │ │events │ │ │ │ │ │ │ │observations│ │ │ │ │ │ │ │ └──────────┘ └───────────┘ │ │ │ │ │ └─────────────────────────────────┘ │ └───────────────────────────────┘ └──────────────────────────────────────┘ ┌───────────────────────────────────────────────────────────────────────────┐ │ 配置 & 知识层（文件系统） │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │_registry │ │guardrails │ │review_ │ │prompt_ │ │ │ │.yaml │ │.yaml │ │protocols/ │ │templates/ │ │ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │schemas/ │ │skills/ │ │project.yaml│ (per-project 覆盖) │ │ │(JSON) │ │(builtin+ │ │ │ │ │ │ │ │ custom) │ │ │ │ │ └────────────┘ └────────────┘ └────────────┘ │ └───────────────────────────────────────────────────────────────────────────┘ ``` ### 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 交互路径详解 | 路径 | 方式 | 说明 | |------|------|------| | 用户 → Agent | OpenClaw Chat | 自然语言对话，Agent 自带身份和工具 | | 用户 → Dashboard | 浏览器访问 8083 | REST API 查黑板、SSE 收推送 | | Agent → 黑板 | CLI `blackboard.py` | read/claim/output/comment/decide/observe/create/review | | Agent → Daemon | 写 Inbox JSONL | 秒级事件推送，触发 Daemon 提前 tick | | Agent → Agent | 黑板评论 | comments 表（handoff/rebuttal/debate），替代 Mail | | Daemon → Agent | `asyncio.create_subprocess_exec` | spawn 不等返回，下次 tick 检查产出 | | Daemon → Dashboard | SSE `/api/events` | 任务状态变更、审查结果、通知推送 | | Dashboard → Daemon | REST API | 查状态、手动 tick、项目管理 | ### 1.5 组件职责矩阵 | 层 | 组件 | 职责 | 技术 | |----|------|------|------| | **用户层** | 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. 技术栈与选型权衡 ### 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 | --- ## 3. 项目结构 ``` sanguo_moziplus_v2/ # 项目根目录 ├── src/ │ ├── main.py # FastAPI 入口 + Daemon ticker 启动 │ │ │ ├── blackboard/ # 黑板核心模块 │ │ ├── __init__.py │ │ ├── db.py # SQLite 连接管理（per-project） │ │ ├── models.py # 数据模型 │ │ ├── operations.py # 写操作（task/comment/output/decision/observation/review） │ │ └── queries.py # 读操作（L1/L2/L3 分层） │ │ │ ├── daemon/ # Daemon 核心模块 │ │ ├── __init__.py │ │ ├── ticker.py # Tick 循环主逻辑（30s） │ │ ├── dispatcher.py # Agent 调度判据（Full/Subagent/Daemon 三级） │ │ ├── spawner.py # Agent spawn + session 管理 │ │ ├── inbox.py # Inbox JSONL watcher + truncate │ │ ├── guardrail.py # L1 assert 执行 + L2 subagent 触发 │ │ ├── review_flow.py # 审查流水线（单审/反驳权/辩论） │ │ ├── experience.py # 一级蒸馏触发 + 经验注入 │ │ ├── bootstrap.py # build_bootstrap() L1/L2/L3 消息拼装 │ │ ├── health.py # 健康检查 + 逻辑死循环检测 │ │ ├── counter.py # ActiveAgentCounter 异步计数器 │ │ └── notifier.py # @mention 解析 + Inbox 事件注入 │ │ │ ├── api/ # HTTP API │ │ ├── blackboard_routes.py # 黑板 CRUD API │ │ ├── daemon_routes.py # Daemon 控制 API │ │ ├── sse_routes.py # SSE 推送端点 │ │ └── project_routes.py # 多项目管理 API │ │ │ ├── cli/ # CLI 工具 │ │ ├── blackboard.py # Agent 黑板操作 CLI │ │ └── admin.py # 管理员控制 CLI │ │ │ └── frontend/ # 前端（React + Vite） │ ├── src/ │ │ ├── pages/ # 5 页面 │ │ │ ├── TaskBoard.tsx # 任务看板（核心） │ │ │ ├── GlobalMonitor.tsx # 全局监控 │ │ │ ├── ArtifactVault.tsx # 产出档案 │ │ │ ├── SystemConfig.tsx # 系统配置 │ │ │ └── AIBriefing.tsx # AI Briefing │ │ ├── components/ │ │ │ ├── CheckpointPanel.tsx # Checkpoint 交互 │ │ │ ├── NotificationCenter.tsx # 推送通知中心 │ │ │ └── ProjectSwitcher.tsx # 项目切换器 │ │ ├── store.ts # Zustand 状态管理 │ │ └── api.ts # API 层 │ └── dist/ # 构建产物（8083 直接服务） │ ├── config/ │ ├── default.yaml # 全局默认配置 │ ├── guardrails.yaml # Guardrail 规则（per task_type） │ ├── template_components.yaml # 模板组件库（7组件 + custom） │ └── review_protocols/ # 审查协议 │ ├── plan_review.yaml │ ├── output_review.yaml │ ├── analysis_review.yaml │ └── final_review.yaml │ ├── prompt_templates/ # L2 引擎注入模板 │ ├── executor.md # 执行者操作规范 │ ├── reviewer.md # 审查者操作规范 │ ├── planner.md # 庞统规划操作规范 │ ├── adjudicator.md # 庞统裁决操作规范 │ ├── rebuttal.md # 反驳权操作规范 │ └── plan_checker.md # Plan Checker 验证规范 │ ├── schemas/ # L1 Schema 校验 │ ├── handoff.schema.json │ ├── output.schema.json │ ├── decide.schema.json │ └── observe.schema.json │ ├── projects/ # 多项目目录（课题11） │ └── {project_id}/ │ ├── blackboard.db # per-project SQLite │ ├── config/ # per-project 配置覆盖 │ │ └── project.yaml │ ├── artifacts/ # per-project 产出物 │ ├── experiences/ # per-project 经验库 │ └── skills/ # per-project Skill 覆盖/扩展 │ ├── inbox/ # Inbox JSONL │ └── daemon.jsonl # 跨进程事件推送 │ ├── skills/ # 全局 Skill 库 │ ├── builtins/ # 系统内置 Skill │ │ ├── blackboard_operations/ │ │ ├── code_review/ │ │ └── data_validation/ │ └── custom/ # 蒸馏产出/用户创建 │ └── {skill_id}/ │ ├── SKILL.md # 四要素 │ ├── template.md # 可选详细模板 │ └── meta.yaml # 版本/来源/tag │ ├── tests/ │ ├── unit/ │ └── e2e/ │ ├── pyproject.toml ├── ecosystem.config.cjs # PM2 配置 └── docs/ # 设计文档 ``` --- ## 4. 数据库设计 ### 4.1 数据库架构（per-project） 每个项目独立 SQLite 数据库，物理隔离。路径：`projects/{project_id}/blackboard.db`。 全局注册表：`projects/_registry.yaml`（YAML 文件，人可读可 Git 版本管理，紧急运维可直接编辑）。tick 热路径用内存 dict 缓存，_registry.yaml 只在 CLI 操作时读写（非热路径）。 ### 4.2 表结构 完整 Schema 见 `architecture-v2.6.md §3.2`，此处列出核心表： | 表 | 用途 | 来源课题 | |----|------|---------| | `tasks` | 任务主表（状态机） | 课题1 | | `comments` | 评论/Handoff/辩论论点（含 comment_type） | 课题2/3 | | `outputs` | 产出物（含 attempt_number） | 课题2 | | `decisions` | 决策记录 | 课题1 | | `observations` | 观察/吹哨（severity 分级） | 课题1 | | `events` | 事件流（审计追踪） | 课题2 | | `reviews` | 评审结果（含 confidence/rebuttal_status/debate_round） | 课题3 | | `experiences` | 经验沉淀（含 tags） | 课题6 | | `experience_tags` | 经验标签关联表 | 课题6 | | `checkpoints` | Checkpoint 人工确认（v2.8/M3） | M3 | ### 4.3 关键约束 - WAL 模式 + `busy_timeout=5000` + `PRAGMA foreign_keys=ON` - 所有写操作走 `BEGIN IMMEDIATE` 串行化 - comments 表 `comment_type` CHECK 约束区分 8 种类型 --- ## 5. Daemon 核心架构 ### 5.1 Tick 循环（30s） ```python async def tick(project_id: str): conn = get_connection(project_id) try: # 1. 逻辑健康自检（连续 N tick 无变更 → 告警） health_check(conn) # 2. 处理 Inbox JSONL（即时事件） process_inbox(conn) # 3. 扫描黑板状态 tasks = scan_tasks(conn) # 4. 审查流水线处理 review_flow(conn, tasks) # 5. 依赖推进（已完成任务解锁下游） advance_dependencies(conn, tasks) # 6. 反驳权进度检测（催促通知） check_rebuttal_progress(conn) # 7. Agent 调度 dispatch_pending(conn, tasks) # 8. 一级蒸馏触发 check_distillation(conn) finally: conn.close() ``` **Tick + Inbox 双层事件架构**： - Tick 30s 兜底扫描（Pull） - Inbox JSONL 秒级推送加速（Push） - Inbox 文件用 truncate（清空不删除），避免并发写入时文件不存在 ### 5.2 Agent 调度判据（三级决策树） 详见 `topic3-challenge-review-proposal.md §5.4`。 ```python def dispatch(task, action_type, project_config): registered_agents = project_config.get("agents", []) # Level 1: 纯机械检查 → Daemon 直接执行 if action_type in ("L1_guardrail", "format_check", "file_exists_check"): return execute_locally(task) # Level 2: 有名字的角色 → Full Agent (asyncio.create_subprocess_exec) if task.assignee in registered_agents: if action_type == "adjudication": return spawn_full_agent(task.assignee, new_session=True) return spawn_full_agent(task.assignee) # Level 3: 无名字的一次性任务 → Subagent (sessions_spawn) if DISPATCH_RULES.get(action_type) == "subagent": return spawn_subagent(task_description=action_type) # Level 4: 未知 action_type → 庞统裁决 return spawn_full_agent("pangtong-fujunshi", new_session=True) ``` **spawn 方式**： - Full Agent：`asyncio.create_subprocess_exec`（异步非阻塞），不 await 完成，下次 tick 检查产出 - Subagent：`sessions_spawn`（Gateway API），等返回 ### 5.3 线程模型：纯 asyncio 单线程 整个 Daemon 运行在单个 asyncio event loop 中（与 FastAPI 共享）。 **关键设计决策**：Full Agent spawn 不用 `subprocess.Popen`（同步，会短暂阻塞 event loop），改用 `asyncio.create_subprocess_exec`（异步非阻塞）。这样 API 请求处理、SSE 推送、Daemon tick 三者互不阻塞。 ```python async def spawn_full_agent(agent_id: str, message: str, new_session: bool = False) -> str: """异步非阻塞 spawn，全程 asyncio""" session_id = str(uuid.uuid4()) cmd = ["openclaw", "agent", "--agent", agent_id, "--session-id", session_id, "--message", message, "--json"] proc = await asyncio.create_subprocess_exec( *cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE ) # 不 await proc.wait()，让子进程独立运行 # 下次 tick 通过产出物检查完成状态 _register_session(agent_id, session_id, proc.pid) return session_id ``` **Subagent spawn** 通过 OpenClaw Gateway 内部 API（`sessions_spawn`），天然异步。 ### 5.4 ActiveAgentCounter（课题11） 纯 asyncio 实现（`asyncio.Semaphore`），与线程模型一致： """异步计数器，控制并发""" def __init__(self, max_global=5, max_per_agent=1): self._global = asyncio.Semaphore(max_global) self._per_agent = {} # agent_id → Semaphore(max_per_agent) async def acquire(self, agent_id: str) -> bool: if self._global.locked(): return False agent_sem = self._per_agent.get(agent_id) if agent_sem and agent_sem.locked(): return False await self._global.acquire() if agent_id not in self._per_agent: self._per_agent[agent_id] = asyncio.Semaphore(self._max_per_agent) await self._per_agent[agent_id].acquire() return True def release(self, agent_id: str): self._per_agent[agent_id].release() self._global.release() ``` ### 5.5 build_bootstrap() 四层上下文拼装 详见 `topic4-decomposition-skill-proposal.md D4-7`。 ``` L0 铁律层（~500 tokens） → Hook 注入，不占 bootstrap L1 角色层（~2000 tokens） → SOUL.md / IDENTITY.md（Agent 自带） L2 引擎注入层（~1500 tokens）→ prompt_templates 按 role 拼装 ① 操作规范（executor.md / reviewer.md / planner.md） ② 项目背景（project_context.yaml） ③ 任务上下文（黑板数据） ④ 前序信息（depends_on 产出摘要） ⑤ Guardrail 规则（guardrails.yaml，仅执行者） ⑥ 审查协议（review_protocols/，仅审查者） ⑦ 经验注入（experiences 表按 tag 匹配） L3 被动参考层（按需加载）→ Skill description 四要素 ``` L2 按角色精确注入：执行者注入⑤⑥，审查者注入⑥，庞统注入⑥。 --- ## 6. 审查流水线 ### 6.1 分级审查 | 风险等级 | 流水线 | 方案审查 | 产出审查 | 模式 | max_rounds | |---------|--------|---------|---------|------|-----------| | **high** | 三阶段 | ✅ 对抗辩论 | ✅ 对抗辩论 + Guardrail | debate | 5 | | **standard** | 二阶段 | ✅ 单审 | ✅ 单审 + Guardrail | single_reviewer | 3 | | **low** | 一阶段 | ❌ | ⚡ Guardrail 自动 | auto | 0 | | **research** | 一阶段 | ❌ | ✅ 庞统确认 | single_reviewer | 2 | ### 6.2 Guardrail 执行 ```yaml # config/guardrails.yaml 示例 task_types: coding: output_review: required: true layers: L1: # Daemon 直接执行 - assert: "len(glob('tests/test_*.py')) > 0" message: "缺少测试文件" - assert: "import subprocess; subprocess.run(['python', '-m', 'py_compile', output_path], check=True)" message: "Python 语法检查失败" L2: # Subagent 执行 prompt: "检查代码是否遵循项目规范，重点关注：命名、异常处理、资源释放" deploy: output_review: required: true layers: L1: - assert: "os.path.exists('deploy_log.md')" message: "缺少部署日志" data: output_review: required: false # low 风险，Guardrail 自动 ``` ### 6.3 反驳权流控 审查者 verdict=needs_revision（有 critical/major）→ spawn 原执行者反驳 → 协商轮次 ≤ max_rounds → 不设超时，有催促通知 → 超轮次升级庞统。 详见 `topic3-challenge-review-proposal.md §5.3`。 ### 6.4 评审详情 Schema 评审结果写入 `{task_id}/reviews/{review_id}.json`，包含： - `issues[]`（status/severity/category/location+context/suggestion） - `evidence[]`（file_content/command_output） - `positives[]`、`meta` - category 含：correctness/security/performance/style/scope_deviation/**architecture/robustness** 详见 `topic3-challenge-review-proposal.md §5.2`。 --- ## 7. 经验沉淀 ### 7.1 两级蒸馏 | 级别 | 触发时机 | 产出 | 存储 | |------|---------|------|------| | 一级（实时） | 任务完成后 | 经验条目（key findings/lessons/tags） | experiences 表 | | 二级（周期） | 同 tag 积累 N 条 | Skill 草稿（draft→active→deprecated） | skills/ 目录 | ### 7.2 经验注入 build_bootstrap() 按 tag 检索 experiences 表，格式化后注入 L2 上下文。 详见 `topic6-experience-loop-proposal.md`。 --- ## 8. Skill 体系 ### 8.1 Skill 三层载体 | 载体 | 自由度 | 生命周期 | 产出者 | 存储 | |------|--------|---------|--------|------| | **Memory** | 高（自然语言） | 短期（30天过期） | Agent 自动沉淀 | experiences 表 | | **Skill** | 中（模板+约束） | 中期（版本管理） | 二级蒸馏 / 人工编写 | skills/ 目录 | | **Rule** | 低（脚本/断言） | 长期（代码级稳定） | 人工提炼 | guardrails.yaml | 信息压缩方向：Memory → Skill → Rule（自由度递减，可靠性递增）。 ### 8.2 Skill 目录结构 ``` sanguo_moziplus_v2/ ├── skills/ ← 全局 Skill 库 │ ├── builtins/ ← 系统内置 Skill │ │ ├── blackboard_operations/ ← 黑板操作规范 │ │ ├── code_review/ ← 代码审查标准 │ │ └── data_validation/ ← 数据验证 │ └── custom/ ← 用户/蒸馏产出 Skill │ └── {skill_id}/n │ ├── SKILL.md ← 四要素：description/triggers/actions/constraints │ ├── template.md ← 可选：详细模板 │ └── meta.yaml ← 版本、来源、tag │ ├── projects/{pid}/ │ └── skills/ ← per-project Skill 覆盖/扩展 │ └── {skill_id}/ │ └── project_override.md ``` ### 8.3 Skill 四要素（SKILL.md 格式） ```markdown # {skill_name} ## Description 一句话描述能力。 ## Triggers 自动触发条件（任务类型/关键词/产出类型）。 ## Actions 执行步骤和产出要求。 ## Constraints 硬性约束（必须满足/禁止做）。 ``` ### 8.4 Skill 生命周期 ``` draft（蒸馏产出/人工创建） → active（验证通过，build_bootstrap 可引用） → deprecated（30天无引用/被更好的替代） → deleted（清理） ``` - **draft → active**：二级蒸馏自动标记，或人工在 Dashboard 审批 - **active → deprecated**：`expire_days` 无引用自动降级 - **active → deprecated → deleted**：有新版本替代时 ### 8.5 Skill 在 Daemon 中的角色 ```python # daemon/bootstrap.py 中 Skill 加载逻辑 def load_skills(task, role, project_config) -> list[str]: """L3 被动参考层：按需加载 Skill description""" skills = [] # 1. 按 task_type 匹配 triggers builtin_skills = scan_skills("skills/builtins/", task.task_type) # 2. per-project 覆盖 project_skills = scan_skills(f"projects/{task.project_id}/skills/", task.task_type) # 3. 经验匹配（experiences 表按 tag 检索，注入 L2） # → 这部分在 build_bootstrap() 的 L2 ⑦ 中处理 # 4. 只返回 description（四要素摘要），不加载完整 SKILL.md return [s.description for s in builtin_skills + project_skills if s.status == 'active'] ``` **四层加载**（来源：课题4 D4-6）： | 层 | 加载时机 | 内容 | 占用 | |----|---------|------|------| | Agent 固化 | OpenClaw agent 配置 | SOUL.md/IDENTITY.md/TOOLS.md | L1（Agent 自带） | | OpenClaw 注册 | agent 启动时 | OpenClaw skills/ 目录 | L3（按需） | | moziplus 注入 | build_bootstrap() | prompt_templates + guardrails + review_protocols | L2（精确注入） | | 按需检索 | Agent 执行中主动查询 | Skill SKILL.md 全文 | L3（Agent 自己读） | ### 8.6 template_components.yaml 模板组件库，build_bootstrap() L2 拼装时引用： ```yaml components: - id: executor_ops file: prompt_templates/executor.md inject_to: [executor] - id: reviewer_ops file: prompt_templates/reviewer.md inject_to: [reviewer] - id: planner_ops file: prompt_templates/planner.md inject_to: [planner] - id: guardrails file: config/guardrails.yaml inject_to: [executor] condition: task_type in guardrails - id: review_protocol file: config/review_protocols/{task_type}_review.yaml inject_to: [reviewer, planner] condition: review required - id: experience_injection source: experiences_table inject_to: [executor, reviewer] condition: matching_tags > 0 - id: custom file: null # per-project 自定义 inject_to: [] ``` --- ## 9. API 设计 ### 9.1 黑板 API | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/projects/{pid}/tasks` | 任务列表（支持过滤） | | GET | `/api/projects/{pid}/tasks/{id}` | 任务详情 | | POST | `/api/projects/{pid}/tasks` | 创建任务 | | POST | `/api/projects/{pid}/tasks/{id}/claim` | 认领 | | PATCH | `/api/projects/{pid}/tasks/{id}/status` | 更新状态 | | POST | `/api/projects/{pid}/tasks/{id}/comments` | 添加评论 | | POST | `/api/projects/{pid}/tasks/{id}/outputs` | 写入产出 | | POST | `/api/projects/{pid}/tasks/{id}/decisions` | 记录决策 | | POST | `/api/projects/{pid}/tasks/{id}/observations` | 添加观察 | | POST | `/api/projects/{pid}/tasks/{id}/reviews` | 提交评审 | | POST | `/api/projects/{pid}/tasks/{id}/archive` | 归档/取消归档（v2.8） | | POST | `/api/projects/{pid}/tasks/archive-done` | 一键归档（v2.8） | | GET | `/api/projects/{pid}/tasks/{id}/checkpoints` | Checkpoint 列表（M3） | | POST | `/api/projects/{pid}/tasks/{id}/checkpoints` | 创建 Checkpoint（M3） | | POST | `/api/projects/{pid}/tasks/{id}/checkpoints/{cid}/approve` | Checkpoint 通过（M3） | | POST | `/api/projects/{pid}/tasks/{id}/checkpoints/{cid}/reject` | Checkpoint 驳回（M3） | ### 9.2 Daemon 控制 API | 方法 | 路径 | 说明 | |------|------|------| | POST | `/api/daemon/tick` | 手动触发 tick | | GET | `/api/daemon/status` | Daemon 状态 | | GET | `/api/daemon/sessions` | 活跃 session | ### 9.3 SSE 推送 ``` GET /api/events?project={pid} → SSE 流，事件类型： task_created / task_status_changed / review_submitted / rebuttal_added notification（4级：🔴🟡🟢🔵） ``` ### 9.4 多项目 API | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/projects` | 项目列表 | | POST | `/api/projects` | 创建项目 | | GET | `/api/projects/{pid}` | 项目详情 | | DELETE | `/api/projects/{pid}` | 归档项目（安全流程） | --- ## 10. Hook 系统 双重 Hook 架构： | Hook | 所属 | 触发时机 | 用途 | |------|------|---------|------| | `agent_turn_prepare` | OpenClaw Plugin | Agent 接收消息前 | 注入铁律（L0） | | `agent_turn_complete` | OpenClaw Plugin | Agent 完成后 | 触发 lint/test（工具链集成点） | | `pre_task_claim` | moziplus HookRegistry | Agent claim 前 | 权限检查 | | `post_output_write` | moziplus HookRegistry | 产出写入后 | 触发 Guardrail 检查 | | `post_review_submit` | moziplus HookRegistry | 评审提交后 | 触发反驳权流程 | --- ## 11. 前端架构 ### 11.1 技术选型 复用 v1.0 前端框架（React + Vite + TypeScript），重设计页面结构。 ### 11.2 页面结构（5页） | 页面 | 内容 | 来源 | |------|------|------| | **任务看板** | 任务卡片、Checkpoint 交互、状态流转 | 课题7+9 | | **全局监控** | Agent 状态、系统健康、资源使用 | 课题9 | | **产出档案** | 产出物预览/下载、评审详情 | 课题9 | | **系统配置** | 项目管理、Agent 配置、Guardrail 编辑 | 课题9 | | **AI Briefing** | 日报/周报自动生成 | 课题9 | ### 11.3 实时推送 SSE 端点 `/api/events`，前端 EventSource 监听。4 级推送（🔴🟡🟢🔵）。降级：SSE 不可用时 30s 轮询。 ### 11.4 构建部署 ```bash cd src/frontend && npm run build # 产物在 src/frontend/dist/ # FastAPI 直接托管静态文件（port 8083） ``` 详见 `topic9-dashboard-design.md`（课题9 Dashboard 前后端完整设计方案）。 --- ## 12. 测试策略 ### 12.1 单元测试 | 测试文件 | 覆盖 | |---------|------| | test_blackboard.py | operations 全函数（claim CAS、状态机、comment_type、review CRUD） | | test_daemon_tick.py | tick 流程（Inbox 处理、依赖推进、反驳权进度检测） | | test_dispatcher.py | 三级调度判据 + fallback | | test_guardrail.py | L1 assert 执行 + L2 prompt 触发 | | test_review_flow.py | 审查流水线（分级审查、反驳权、升级） | | test_experience.py | 一级蒸馏 + tag 检索 | | test_bootstrap.py | 四层上下文拼装（按 role 精确注入） | | test_counter.py | ActiveAgentCounter 并发控制 | ### 12.2 集成测试 - 创建任务 → 调度执行 → Guardrail → 审查 → 反驳 → 完成 闭环 - 多项目并发：两个项目同时 tick，互不影响 - 竞态测试：两个 Agent 同时 claim + 同时写 inbox ### 12.3 测试数据库 per-project 测试用 `:memory:` SQLite。全局注册表测试用临时文件。 --- ## 13. 实现顺序 | Phase | 内容 | 估计时间 | |-------|------|---------| | **P1** | 黑板 + Daemon + CLI + API + 多项目 | ~20-25h（含调试 buffer） | | **P2** | 审查流水线 + Guardrail + 反驳权 + build_bootstrap | ~12h | | **P3** | 前端重设计 + SSE 推送 + AI Briefing | ~10h | | **P4** | 经验沉淀 + Skill 进化 + 工具链集成 | ~8h | --- ## 14. 容量估算 ### 14.1 存储容量 | 组件 | 单项目估算 | 说明 | |------|-----------|------| | blackboard.db | 2-10 MB / 100 任务 | tasks + comments(5-20行/任务) + outputs + reviews + events(5-10行/任务) + experiences，含索引和 WAL overhead | | artifacts/ | 10-50 MB / 100 任务 | 代码文件、分析报告、数据文件 | | experiences/ | < 1 MB | 经验条目轻量，文本为主 | | Inbox JSONL | < 100 KB | 持续 truncate，不累积 | | _registry.yaml | < 10 KB | 项目元信息，轻量 | **总磁盘预估（10 项目，1000 任务）**：~1-2 GB，完全在 Mac mini 容量范围内。 ### 14.2 内存占用 | 组件 | 占用估算 | 说明 | |------|---------|------| | Daemon + FastAPI | 50-100 MB | Python 进程基础 + asyncio event loop | | 每个 Agent spawn | 100-300 MB | openclaw agent CLI 进程，执行期间临时占用 | | SQLite 连接池 | < 10 MB | per-project 连接，用完释放 | | 前端 dist 静态服务 | < 5 MB | 内存映射 | **峰值内存（max_global=5，5 个 Agent 同时执行）**：~1-1.5 GB，16GB Mac mini 无压力。 ### 14.3 并发能力 | 维度 | 设计上限 | 瓶颈分析 | |------|---------|----------| | 同时活跃项目 | 无硬限（10+） | tick 30s 扫全部项目，每项目 tick 耗时 < 100ms，10 项目 < 1s | | 并发 Agent | 5 (max_global) | ActiveAgentCounter 控制，超出排队 | | SSE 连接 | 10-20 | 单机场景足够，FastAPI SSE 无硬限 | | Inbox 吞吐 | 200+ 写/秒 | truncate 模式，实测无丢失 | | API QPS | 100+ | FastAPI 单进程足够，无 LB 瓶颈 | ### 14.4 性能约束 | 场景 | 延迟 | 说明 | |------|------|------| | 用户提需求 → 任务写入黑板 | < 5s | Agent 对话 + CLI 写入 | | 任务 pending → Agent 开始执行 | 30s 内 | 最坏等一轮 tick；Inbox 触发可秒级 | | Agent 完成 → 下游任务 pending | 30s 内 | tick 扫描依赖推进 | | SSE 事件推送延迟 | < 1s | event loop 内直接推送 | | 审查 → 反驳权启动 | 30s 内 | tick 扫描 review 状态 | --- ## 15. 失败模式与可靠性 ### 15.1 进程级故障 | 故障 | 检测 | 恢复 | |------|------|------| | Daemon 进程崩溃 | PM2 auto restart | PM2 5s 内自动拉起，tick 恢复扫描 | | Agent spawn 子进程僵死 | health.py 僵尸检测 | 连续 20 tick 无变更 → observation 告警 + reclaim 释放 semaphore | | Agent spawn 失败（CLI 错误） | spawner 异常捕获 | 标记任务 failed，写入 events 表，不阻塞其他任务 | | FastAPI 进程异常 | PM2 restart | 与 Daemon 同进程，PM2 统一管理 | ### 15.2 数据级故障 | 故障 | 检测 | 恢复 | |------|------|------| | SQLite 写入冲突 | busy_timeout=5s 等待 + WAL 模式 | WAL 允许并发读写；超时后 raise，tick 下次重试 | | SQLite DB 损坏 | 连接时 PRAGMA integrity_check | per-project 隔离，单 DB 损坏不影响其他项目；从最新 Git 备份恢复 | | Inbox JSONL 损坏 | JSON 解析异常 | truncate 清空重置，Agent 重发事件 | | _registry.yaml 损坏 | YAML 解析异常 | Git 版本管理，`git checkout` 恢复 | ### 15.3 逻辑级故障 | 故障 | 检测 | 恢复 | |------|------|------| | Agent 无限循环 | 连续 20 tick 无状态变更 | observation 告警 + 通知用户 + reclaim | | 反驳权无限协商 | max_rounds 兜底 | 超轮次自动升级庞统裁决 | | 任务卡在 blocked | tick 依赖推进检查 | 每轮 tick 重算依赖，不依赖缓存 | | Guardrail 误杀 | L1 assert 可能误判 | L2 subagent 二次确认；用户可在 Dashboard 手动 override | ### 15.4 恢复优先级 ``` P0: Daemon 进程 → PM2 auto restart P1: 数据完整性 → SQLite WAL + Git 备份 P2: 任务进度 → tick 全量扫描自动恢复 P3: 经验数据 → experiences 表 + skills/ 目录 Git 版本管理 ``` --- ## 16. 演进路径 ### 16.1 已知限制与扩展点 | 当前限制 | 触发条件 | 演进方向 | |---------|---------|--------| | SQLite 单机 | 项目 > 20 或 DB > 100MB | 迁移 PostgreSQL（per-project schema），代码层只改 db.py | | max_global=5 | Agent 并发不够 | 调整 ActiveAgentCounter 参数；引入优先级队列 | | 单机部署 | 需要多节点 | Agent spawn 改为远程调度（Windows-Test-Node 已可远程执行） | | SSE 单进程 | SSE 连接 > 50 | 引入 Redis pub/sub + 多 worker | | 无用户认证 | 多用户协作需求 | 引入 API token + per-project 权限（project.yaml 扩展） | ### 16.2 接口抽象层（为演进预留） 关键接口已做抽象，替换底层不影响上层逻辑： | 接口 | 当前实现 | 替换时影响范围 | |------|---------|--------------| | `blackboard.db.py` | SQLite | 只改 db.py，operations/queries 不变 | | `daemon.spawner.py` | asyncio.create_subprocess_exec | 只改 spawner.py，dispatcher 不变 | | `daemon.counter.py` | asyncio.Semaphore | 只改 counter.py，dispatcher 不变 | | `api.sse_routes.py` | FastAPI SSE | 只改 sse_routes.py，前端不变 | --- ## 17. 风险 | 风险 | 概率 | 影响 | 缓解 | |------|------|------|------| | per-project SQLite 并发 tick | 中 | 中 | WAL + busy_timeout + per-project asyncio.Lock | | Agent spawn 子进程回收 | 中 | 中 | health.py 僵尸检测 + reclaim | | Inbox JSONL 并发写入 | 低 | 低 | truncate（不删除），实测 200 并发 0 丢失 | | 前端 v1→v2 迁移 | 低 | 低 | v1(8082) 和 v2(8083) 独立运行，渐进替换 | | Daemon 逻辑死循环 | 低 | 中 | 连续 20 tick 无变更 → observation 告警 + 通知用户 | | 反驳权无限协商 | 低 | 低 | max_rounds 兜底 + 超轮次升级庞统 | | 上下文窗口膨胀 | 中 | 中 | L0-L3 四层分级 + 产出写入黑板不累积 | | 经验注入噪声 | 低 | 低 | 只注入 matching tag 的经验；N 条阈值可控 | | Guardrail 误杀 | 低 | 中 | L1+L2 双层验证；用户可 Dashboard override |