sanguo/sanguo_moziplus_v2

Fork 0

Files

T

cfdaily 0d7425b88c

Deploy / ci (push) Waiting to run

Details

Deploy / deploy (push) Blocked by required conditions

Details

Deploy / notify-deploy-failure (push) Blocked by required conditions

Details

auto-sync: 2026-06-07 01:35:53

2026-06-07 01:35:53 +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

v2.6 技术方案设计

1. 总体技术架构

1.1 全局架构图

1.2 多用户并发架构

1.3 核心数据流

1.4 交互路径详解

1.5 组件职责矩阵

2. 技术栈与选型权衡

2.1 技术栈总览

2.2 选型权衡分析

3. 项目结构

4. 数据库设计

4.1 数据库架构（per-project）

4.2 表结构

4.3 关键约束

5. Daemon 核心架构

5.1 Tick 循环（30s）

5.2 Agent 调度判据（三级决策树）

5.3 线程模型：纯 asyncio 单线程

5.4 ActiveAgentCounter（课题11）

6.3 反驳权流控

6.4 评审详情 Schema

7. 经验沉淀

7.1 两级蒸馏

7.2 经验注入

8. Skill 体系

8.1 Skill 三层载体

8.2 Skill 目录结构

8.3 Skill 四要素（SKILL.md 格式）

8.4 Skill 生命周期

8.5 Skill 在 Daemon 中的角色

8.6 template_components.yaml

9. API 设计

9.1 黑板 API

9.2 Daemon 控制 API

9.3 SSE 推送

9.4 多项目 API

10. Hook 系统

11. 前端架构

11.1 技术选型

11.2 页面结构（5页）

11.3 实时推送

11.4 构建部署

12. 测试策略

12.1 单元测试

12.2 集成测试

12.3 测试数据库

13. 实现顺序

14. 容量估算

14.1 存储容量

14.2 内存占用

14.3 并发能力

14.4 性能约束

15. 失败模式与可靠性

15.1 进程级故障

15.2 数据级故障

15.3 逻辑级故障

15.4 恢复优先级

16. 演进路径

16.1 已知限制与扩展点

16.2 接口抽象层（为演进预留）

17. 风险

48 KiB

Raw Blame History