sanguo/sanguo_moziplus_v2

Fork 0

Files

T

cfdaily 5b4ca01b46 auto-sync: 2026-05-18 23:02:45

2026-05-18 23:02:45 +08:00

48 KiB

Raw Blame History

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 任务是否可解锁

关键循环路径（非直线流程）：

Guardrail 失败循环：产出写完 → Guardrail 检查 → 失败 → 回 working → Agent 重新执行
审查-反驳循环：审查不通过 → 反驳权协商（≤ max_rounds 轮）→ 超轮次庞统裁决
依赖解锁循环：任务完成 → 检查下游 blocked 任务 → 依赖满足 → 下游变 pending → 调度
经验闭环：任务完成 → 一级蒸馏 → 经验注入 → 下次 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）

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。

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 三者互不阻塞。

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 格式）

# {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 中的角色

# 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 拼装时引用：

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 构建部署

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

48 KiB Raw Blame History Unescape Escape