# v2.6 技术方案设计

**版本**: v2.6.2-tech
**基于**: architecture-v2.6.md (v2.6.11)
**作者**: 庞统（副军师）🐦
**日期**: 2026-05-16

---

## 1. 技术栈

| 组件 | 选型 | 版本 | 理由 |
|------|------|------|------|
| 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. 项目结构

```
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 经验库
│
├── inbox/                             # Inbox JSONL
│   └── daemon.jsonl                   # 跨进程事件推送
│
├── tests/
│   ├── unit/
│   └── e2e/
│
├── pyproject.toml
├── ecosystem.config.cjs               # PM2 配置
└── docs/                              # 设计文档
```

---

## 3. 数据库设计

### 3.1 数据库架构（per-project）

每个项目独立 SQLite 数据库，物理隔离。路径：`projects/{project_id}/blackboard.db`。

全局注册表：`projects/registry.db`（存储项目列表和元数据）。

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

### 3.3 关键约束

- WAL 模式 + `busy_timeout=5000` + `PRAGMA foreign_keys=ON`
- 所有写操作走 `BEGIN IMMEDIATE` 串行化
- comments 表 `comment_type` CHECK 约束区分 8 种类型

---

## 4. Daemon 核心架构

### 4.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（清空不删除），避免并发写入时文件不存在

### 4.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 (Popen 非阻塞)
    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：`subprocess.Popen`（非阻塞），不等返回，下次 tick 检查产出
- Subagent：`sessions_spawn`（Gateway API），等返回

### 4.3 ActiveAgentCounter（课题11）

```python
class ActiveAgentCounter:
    """异步计数器，控制并发"""
    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()
```

### 4.4 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 按角色精确注入：执行者注入⑤⑥，审查者注入⑥，庞统注入⑥。

---

## 5. 审查流水线

### 5.1 分级审查

| 风险等级 | 流水线 | 方案审查 | 产出审查 | 模式 | max_rounds |
|---------|--------|---------|---------|------|-----------|
| **high** | 三阶段 | ✅ 对抗辩论 | ✅ 对抗辩论 + Guardrail | debate | 5 |
| **standard** | 二阶段 | ✅ 单审 | ✅ 单审 + Guardrail | single_reviewer | 3 |
| **low** | 一阶段 | ❌ | ⚡ Guardrail 自动 | auto | 0 |
| **research** | 一阶段 | ❌ | ✅ 庞统确认 | single_reviewer | 2 |

### 5.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 自动
```

### 5.3 反驳权流控

审查者 verdict=needs_revision（有 critical/major）→ spawn 原执行者反驳 → 协商轮次 ≤ max_rounds → 不设超时，有催促通知 → 超轮次升级庞统。

详见 `topic3-challenge-review-proposal.md §5.3`。

### 5.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`。

---

## 6. 经验沉淀

### 6.1 两级蒸馏

| 级别 | 触发时机 | 产出 | 存储 |
|------|---------|------|------|
| 一级（实时） | 任务完成后 | 经验条目（key findings/lessons/tags） | experiences 表 |
| 二级（周期） | 同 tag 积累 N 条 | Skill 草稿（draft→active→deprecated） | skills/ 目录 |

### 6.2 经验注入

build_bootstrap() 按 tag 检索 experiences 表，格式化后注入 L2 上下文。

详见 `topic6-experience-loop-proposal.md`。

---

## 7. API 设计

### 7.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` | 提交评审 |

### 7.2 Daemon 控制 API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/daemon/tick` | 手动触发 tick |
| GET | `/api/daemon/status` | Daemon 状态 |
| GET | `/api/daemon/sessions` | 活跃 session |

### 7.3 SSE 推送

```
GET /api/events?project={pid}
→ SSE 流，事件类型：
  task_created / task_status_changed / review_submitted / rebuttal_added
  notification（4级：🔴🟡🟢🔵）
```

### 7.4 多项目 API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/projects` | 项目列表 |
| POST | `/api/projects` | 创建项目 |
| GET | `/api/projects/{pid}` | 项目详情 |
| DELETE | `/api/projects/{pid}` | 归档项目（安全流程） |

---

## 8. 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 | 评审提交后 | 触发反驳权流程 |

---

## 9. 前端架构

### 9.1 技术选型

复用 v1.0 前端框架（React + Vite + TypeScript），重设计页面结构。

### 9.2 页面结构（5页）

| 页面 | 内容 | 来源 |
|------|------|------|
| **任务看板** | 任务卡片、Checkpoint 交互、状态流转 | 课题7+9 |
| **全局监控** | Agent 状态、系统健康、资源使用 | 课题9 |
| **产出档案** | 产出物预览/下载、评审详情 | 课题9 |
| **系统配置** | 项目管理、Agent 配置、Guardrail 编辑 | 课题9 |
| **AI Briefing** | 日报/周报自动生成 | 课题9 |

### 9.3 实时推送

SSE 端点 `/api/events`，前端 EventSource 监听。4 级推送（🔴🟡🟢🔵）。降级：SSE 不可用时 30s 轮询。

### 9.4 构建部署

```bash
cd src/frontend && npm run build
# 产物在 src/frontend/dist/
# FastAPI 直接托管静态文件（port 8083）
```

详见 `topic7-9-interaction-dashboard-proposal.md`。

---

## 10. 测试策略

### 10.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 并发控制 |

### 10.2 集成测试

- 创建任务 → 调度执行 → Guardrail → 审查 → 反驳 → 完成 闭环
- 多项目并发：两个项目同时 tick，互不影响
- 竞态测试：两个 Agent 同时 claim + 同时写 inbox

### 10.3 测试数据库

per-project 测试用 `:memory:` SQLite。全局注册表测试用临时文件。

---

## 11. 实现顺序

| Phase | 内容 | 估计时间 |
|-------|------|---------|
| **P1** | 黑板 + Daemon + CLI + API + 多项目 | ~15h |
| **P2** | 审查流水线 + Guardrail + 反驳权 + build_bootstrap | ~12h |
| **P3** | 前端重设计 + SSE 推送 + AI Briefing | ~10h |
| **P4** | 经验沉淀 + Skill 进化 + 工具链集成 | ~8h |

---

## 12. 风险

| 风险 | 缓解 |
|------|------|
| per-project SQLite 并发 tick | WAL + busy_timeout + per-project asyncio.Lock |
| Agent spawn 子进程回收 | health.py 僵尸检测 + reclaim |
| Inbox JSONL 并发写入 | truncate（不删除），实测 200 并发 0 丢失 |
| 前端 v1→v2 迁移 | v1 Tab 全保留，渐进替换 |
| Daemon 逻辑死循环 | 连续 N tick（默认 20）无变更 → observation 告警 + 通知用户 |
| 反驳权无限协商 | max_rounds 兜底 + 超轮次升级庞统 |