# 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 |
