sanguo/sanguo_moziplus_v2

Fork 0

Files

T

cfdaily fb20b19def auto-sync: 2026-05-16 23:25:56

2026-05-16 23:25:56 +08:00

23 KiB

Raw Blame History

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                   # 跨进程事件推送
│
├── 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/                              # 设计文档

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）

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。

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）

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 执行

# 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. Skill 体系

7.1 Skill 三层载体

载体	自由度	生命周期	产出者	存储
Memory	高（自然语言）	短期（30天过期）	Agent 自动沉淀	experiences 表
Skill	中（模板+约束）	中期（版本管理）	二级蒸馏 / 人工编写	skills/ 目录
Rule	低（脚本/断言）	长期（代码级稳定）	人工提炼	guardrails.yaml

信息压缩方向：Memory → Skill → Rule（自由度递减，可靠性递增）。

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

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

# {skill_name}

## Description
一句话描述能力。

## Triggers
自动触发条件（任务类型/关键词/产出类型）。

## Actions
执行步骤和产出要求。

## Constraints
硬性约束（必须满足/禁止做）。

7.4 Skill 生命周期

draft（蒸馏产出/人工创建）
  → active（验证通过，build_bootstrap 可引用）
  → deprecated（30天无引用/被更好的替代）
  → deleted（清理）

draft → active：二级蒸馏自动标记，或人工在 Dashboard 审批
active → deprecated：expire_days 无引用自动降级
active → deprecated → deleted：有新版本替代时

7.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 自己读）

7.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: []

8. 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}`	归档项目（安全流程）

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

10. 前端架构

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

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

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

11. 测试策略

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。全局注册表测试用临时文件。

12. 实现顺序

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

13. 风险

风险	缓解
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 兜底 + 超轮次升级庞统

23 KiB Raw Blame History Unescape Escape