cfdaily
999 lines
48 KiB
Markdown
999 lines
48 KiB
Markdown
# v2.6 技术方案设计
|
||
|
||
**版本**: v2.6.2-tech
|
||
**基于**: architecture-v2.6.md (v2.6.11)
|
||
**作者**: 庞统（副军师）🐦
|
||
**日期**: 2026-05-16
|
||
|
||
---
|
||
|
||
## 1. 总体技术架构
|
||
|
||
### 1.1 全局架构图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ 用户层 │
|
||
│ ┌──────────────────┐ ┌──────────────────┐ │
|
||
│ │ Agent 对话入口 │ │ Dashboard (8083) │ │
|
||
│ │ (OpenClaw Chat) │ │ React + Vite │ │
|
||
│ └────────┬─────────┘ └────────┬─────────┘ │
|
||
│ │ │ │
|
||
│ 自然语言对话 REST API + SSE │
|
||
│ │ │ │
|
||
└───────────┼───────────────────────┼────────────────────────────────────────┘
|
||
▼ ▼
|
||
┌───────────────────────────────┐ ┌──────────────────────────────────────┐
|
||
│ Agent 执行环境（独立进程） │ │ v2 主进程（PM2: sanguo-moziplus-v2） │
|
||
│ │ │ asyncio event loop │
|
||
│ ┌─────────────────────────┐ │ │ │
|
||
│ │ L0 铁律 (OpenClaw Hook) │ │ │ ┌─────────────────────────────────┐ │
|
||
│ │ L1 角色 (SOUL/IDENTITY) │ │ │ │ API 层 (FastAPI + uvicorn) │ │
|
||
│ │ L2 引擎注入 (bootstrap) │ │ │ │ ┌──────┐ ┌──────┐ ┌────────┐ │ │
|
||
│ │ L3 被动参考 (Skill) │ │ │ │ │黑板API│ │项目API│ │SSE推送 │ │ │
|
||
│ └─────────────────────────┘ │ │ │ └──┬───┘ └──┬───┘ └───┬────┘ │ │
|
||
│ │ │ └─────┼────────┼─────────┼───────┘ │
|
||
│ Agent → 黑板 的交互方式： │ │ │ │ │ │
|
||
│ ① CLI (blackboard.py) ───────┼──┼──→ 直接操作黑板 DB │
|
||
│ ② Inbox JSONL ──────────────┼──┼──→ 秒级事件推送给 Daemon │
|
||
│ │ │ │
|
||
│ │ │ ┌─────────────────────────────────┐ │
|
||
│ │ │ │ Daemon 引擎层（同一 event loop）│ │
|
||
│ │ │ │ │ │
|
||
│ │ │ │ ticker (30s scan) │ │
|
||
│ │ │ │ ┌──────────┐ ┌──────────────┐ │ │
|
||
│ │ │ │ │审查流水线 │ │ 依赖推进 │ │ │
|
||
│ │ │ │ │(4级分级) │ │ 反驳权/蒸馏 │ │ │
|
||
│ │ │ │ └──────────┘ └──────────────┘ │ │
|
||
│ │ │ │ ┌──────────┐ ┌──────────────┐ │ │
|
||
│ │ │ │ │Agent调度器│ │Bootstrap拼装 │ │ │
|
||
│ ← asyncio.create_subprocess │ │ │ └────┬─────┘ └──────────────┘ │ │
|
||
│ _exec (spawn 不等返回) │←─┼──┼───────┘ │ │
|
||
│ │ │ │ ┌──────────────────────────────┐│ │
|
||
│ │ │ │ │ ActiveAgentCounter (并发控制) ││ │
|
||
│ │ │ │ └──────────────────────────────┘│ │
|
||
│ │ │ └─────────────────────────────────┘ │
|
||
│ │ │ │
|
||
│ │ │ ┌─────────────────────────────────┐ │
|
||
│ │ │ │ 黑板数据层 (per-project SQLite) │ │
|
||
│ │ │ │ ┌─────┐ ┌──────┐ ┌──────┐ │ │
|
||
│ │ │ │ │tasks│ │outputs│ │reviews│ │ │
|
||
│ │ │ │ └─────┘ └──────┘ └──────┘ │ │
|
||
│ │ │ │ ┌──────────┐ ┌───────────┐ │ │
|
||
│ │ │ │ │comments │ │experiences│ │ │
|
||
│ │ │ │ │decisions │ │events │ │ │
|
||
│ │ │ │ │observations│ │ │ │
|
||
│ │ │ │ └──────────┘ └───────────┘ │ │
|
||
│ │ │ └─────────────────────────────────┘ │
|
||
└───────────────────────────────┘ └──────────────────────────────────────┘
|
||
|
||
┌───────────────────────────────────────────────────────────────────────────┐
|
||
│ 配置 & 知识层（文件系统） │
|
||
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
|
||
│ │_registry │ │guardrails │ │review_ │ │prompt_ │ │
|
||
│ │.yaml │ │.yaml │ │protocols/ │ │templates/ │ │
|
||
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │
|
||
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
|
||
│ │schemas/ │ │skills/ │ │project.yaml│ (per-project 覆盖) │
|
||
│ │(JSON) │ │(builtin+ │ │ │ │
|
||
│ │ │ │ custom) │ │ │ │
|
||
│ └────────────┘ └────────────┘ └────────────┘ │
|
||
└───────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 1.2 多用户并发架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ 多用户并发入口 │
|
||
│ │
|
||
│ 用户A ──→ OpenClaw Chat ──→ 庞统 Agent ──→ 项目X 任务A1, A2 │
|
||
│ 用户B ──→ OpenClaw Chat ──→ 庞统 Agent ──→ 项目Y 任务B1 │
|
||
│ 用户C ──→ Dashboard ─────→ REST API ────→ 项目X 任务C1 │
|
||
│ │
|
||
│ 所有用户的请求汇聚到同一个 Daemon ticker（30s 扫描全部项目） │
|
||
│ 并发由 ActiveAgentCounter 控制（max_global=5, max_per_agent=1） │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**多用户设计要点**：
|
||
|
||
| 维度 | 机制 | 说明 |
|
||
|------|------|------|
|
||
| 项目隔离 | per-project blackboard.db | 不同项目的任务、产出、评论完全隔离 |
|
||
| 并发控制 | ActiveAgentCounter | 全局 max_global=5 同时最多 5 个 Agent，per-agent max=1 串行执行 |
|
||
| 资源竞争 | Agent 池排队 | 张飞正在执行任务A，任务B 排队等张飞释放 |
|
||
| tick 调度 | 30s 扫全部项目 | 每轮 tick 按 project_id 轮询，每项目独立 tick |
|
||
| 事件驱动 | 共享 Inbox JSONL | 任何项目的 Agent 完成都秒级触发 Daemon |
|
||
| 前端隔离 | URL path `/api/projects/{pid}/` | Dashboard 切换项目，SSE 按 pid 过滤 |
|
||
|
||
**当前规模定位**：单机部署（Mac mini M4, 16GB），3-5 个活跃项目，同时 ≤5 个 Agent 并发。超出此规模需要架构演进（见 §15.3）。
|
||
|
||
### 1.3 核心数据流
|
||
|
||
```
|
||
┌──────────┐
|
||
│ 用户需求 │
|
||
└────┬─────┘
|
||
│
|
||
庞统规划+拆解
|
||
│
|
||
┌────▼─────┐
|
||
│ 任务写入 │
|
||
│ 黑板 │
|
||
└────┬─────┘
|
||
│
|
||
┌──────────┼──────────┐
|
||
▼ ▼ ▼
|
||
pending in_review blocked
|
||
│ │ │
|
||
│ │ ┌────┘
|
||
│ │ ▼
|
||
调度Agent 审查流水线 依赖满足
|
||
(受Counter (分级处理) │
|
||
控制)│ │ → pending
|
||
│ │
|
||
▼ │
|
||
┌──────────────┐ │
|
||
│ Agent 执行 │ │
|
||
│ (独立进程) │ │
|
||
└───┬──────┬───┘ │
|
||
│ │ │
|
||
写产出 写评论 │
|
||
│ │ │
|
||
▼ │ │
|
||
Guardrail │ │
|
||
检查 ───────┤ │
|
||
│ │ │
|
||
┌────┘ │ │
|
||
▼ │ │
|
||
通过 → 触发审查 │ │
|
||
失败 → 回 working │ │
|
||
│ │ │
|
||
│ ┌─────┘ │
|
||
│ ▼ │
|
||
│ 通过 → done ───────┤──→ 一级蒸馏 → 经验注入
|
||
│ │ │
|
||
│ 不通过 → 反驳权 │
|
||
│ │ ↕ 协商 │
|
||
│ │ max_rounds │
|
||
│ │ ↓ 超轮次 │
|
||
│ 庞统裁决 │
|
||
│ │ │
|
||
│ ├→ done/revision│
|
||
│ └───────────────┘
|
||
│
|
||
└──→ 完成后检查：下游 blocked 任务是否可解锁
|
||
```
|
||
|
||
**关键循环路径**（非直线流程）：
|
||
1. **Guardrail 失败循环**：产出写完 → Guardrail 检查 → 失败 → 回 working → Agent 重新执行
|
||
2. **审查-反驳循环**：审查不通过 → 反驳权协商（≤ max_rounds 轮）→ 超轮次庞统裁决
|
||
3. **依赖解锁循环**：任务完成 → 检查下游 blocked 任务 → 依赖满足 → 下游变 pending → 调度
|
||
4. **经验闭环**：任务完成 → 一级蒸馏 → 经验注入 → 下次 build_bootstrap 复用
|
||
|
||
### 1.4 交互路径详解
|
||
|
||
| 路径 | 方式 | 说明 |
|
||
|------|------|------|
|
||
| 用户 → Agent | OpenClaw Chat | 自然语言对话，Agent 自带身份和工具 |
|
||
| 用户 → Dashboard | 浏览器访问 8083 | REST API 查黑板、SSE 收推送 |
|
||
| Agent → 黑板 | CLI `blackboard.py` | read/claim/output/comment/decide/observe/create/review |
|
||
| Agent → Daemon | 写 Inbox JSONL | 秒级事件推送，触发 Daemon 提前 tick |
|
||
| Agent → Agent | 黑板评论 | comments 表（handoff/rebuttal/debate），替代 Mail |
|
||
| Daemon → Agent | `asyncio.create_subprocess_exec` | spawn 不等返回，下次 tick 检查产出 |
|
||
| Daemon → Dashboard | SSE `/api/events` | 任务状态变更、审查结果、通知推送 |
|
||
| Dashboard → Daemon | REST API | 查状态、手动 tick、项目管理 |
|
||
|
||
### 1.5 组件职责矩阵
|
||
|
||
| 层 | 组件 | 职责 | 技术 |
|
||
|----|------|------|------|
|
||
| **用户层** | Agent 对话 | 自然语言交互入口 | OpenClaw Chat |
|
||
| | Dashboard | 可视化监控/配置/Checkpoint | React + Vite (8083) |
|
||
| **API 层** | FastAPI | REST API + SSE + 静态文件 | uvicorn |
|
||
| **引擎层** | Daemon ticker | 30s 状态扫描 + 事件驱动 | asyncio background task |
|
||
| | 调度器 | 三级调度 (Daemon/Full/Sub) | DISPATCH_RULES 配置表 |
|
||
| | 审查流水线 | 分级审查 + 反驳权 + 辩论 | review_flow.py |
|
||
| | Bootstrap 拼装 | 四层上下文 L0-L3 | prompt_templates + YAML |
|
||
| | Inbox watcher | JSONL 秒级事件推送 | asyncio 1s 轮询 |
|
||
| | 健康自检 | 逻辑死循环检测 | 连续 N tick 无变更告警 |
|
||
| **Agent 层** | Full Agent | 有身份角色的任务执行 | openclaw agent CLI |
|
||
| | Subagent | 无身份一次性检查 | sessions_spawn API |
|
||
| **数据层** | 黑板 DB | 任务/评论/产出/审查/经验 | SQLite per-project |
|
||
| | Inbox | 跨进程事件队列 | JSONL + truncate |
|
||
| | _registry.yaml | 项目注册表 | YAML (人可读) |
|
||
| **配置层** | guardrails.yaml | L1/L2 检查规则 | YAML |
|
||
| | review_protocols/ | 审查协议 | YAML |
|
||
| | skills/ | 三层载体 (Memory/Skill/Rule) | SKILL.md + meta.yaml |
|
||
| | project.yaml | per-project 配置覆盖 | YAML |
|
||
|
||
---
|
||
|
||
## 2. 技术栈与选型权衡
|
||
|
||
### 2.1 技术栈总览
|
||
|
||
| 组件 | 选型 | 版本 |
|
||
|------|------|------|
|
||
| Daemon 进程管理 | PM2 | 6.0.14 |
|
||
| Daemon 框架 | Python + asyncio | 3.9+ |
|
||
| 黑板存储 | SQLite (per-project) | 3.51+ |
|
||
| HTTP API | FastAPI + uvicorn | 独立安装 |
|
||
| Agent 调度 | openclaw CLI / sessions_spawn | 2026.5.7 |
|
||
| 前端 | React + Vite + TypeScript | 复用 v1.0 |
|
||
| 实时推送 | SSE | FastAPI 内置 |
|
||
| 配置 | YAML (PyYAML) | — |
|
||
|
||
### 2.2 选型权衡分析
|
||
|
||
**每个关键技术选型都遵循"不加重型新依赖"原则，基于已有环境。**
|
||
|
||
| 决策 | 选择 | 备选 | 选择理由 | 备选缺陷 |
|
||
|------|------|------|---------|---------|
|
||
| HTTP 框架 | **FastAPI** | Starlette / Litestar / Flask | 2025-2026 AI Agent 编排系统事实标准（Agno AgentOS、OpenAI Agents SDK 均用 FastAPI）；内置 OpenAPI + SSE + async；团队已有 v1 经验 | Starlette 需自己拼 Auth/SSE/DI；Litestar 太新生态小；Flask 不原生 async |
|
||
| 黑板存储 | **SQLite** | PostgreSQL / JSON 文件 | per-project 物理隔离（单项目故障不影响其他）；零运维（无 DB server）；WAL 模式足够应对单机并发；团队已有 WAL+busy_timeout 经验 | PostgreSQL 需额外 DB server 运维，对单机场景过重；JSON 文件无事务、无并发保护 |
|
||
| 实时推送 | **SSE** | WebSocket / 轮询 | 单向推送足够（Daemon→Dashboard）；FastAPI 原生支持；自动重连；降级轮询简单 | WebSocket 双向能力多余，增加复杂度；纯轮询延迟高 |
|
||
| 并发模型 | **纯 asyncio 单线程** | threading / multiprocessing | 与 FastAPI event loop 共存；Agent spawn 用 create_subprocess_exec 非阻塞；无锁竞争问题 | threading 引入 GIL + 锁复杂度；multiprocessing 进程间通信代价大 |
|
||
| 配置格式 | **YAML** | TOML / JSON / Python | guardrails/review_protocols 需要人可读可编辑；YAML 支持 multiline string（prompt 模板）；紧急运维可直接编辑 | TOML multiline 不便；JSON 无注释；Python 有安全风险 |
|
||
| 进程管理 | **PM2** | systemd / supervisord | 已有 10 个 PM2 进程运行；log management + auto restart + 开机自启；ecosystem.config.cjs 统一管理 | systemd 需 root 权限；supisord 不如 PM2 对 Node.js 友好 |
|
||
| Agent spawn | **asyncio.create_subprocess_exec** | subprocess.Popen / sessions_spawn | Full Agent 需要独立进程+独立 session；async 版本不阻塞 event loop；下次 tick 检查产出而非等待返回 | Popen 同步阻塞 event loop；sessions_spawn 仅适用无身份 Subagent |
|
||
|
||
---
|
||
|
||
## 3. 项目结构
|
||
|
||
```
|
||
sanguo_moziplus_v2/ # 项目根目录
|
||
├── src/
|
||
│ ├── main.py # FastAPI 入口 + Daemon ticker 启动
|
||
│ │
|
||
│ ├── blackboard/ # 黑板核心模块
|
||
│ │ ├── __init__.py
|
||
│ │ ├── db.py # SQLite 连接管理（per-project）
|
||
│ │ ├── models.py # 数据模型
|
||
│ │ ├── operations.py # 写操作（task/comment/output/decision/observation/review）
|
||
│ │ └── queries.py # 读操作（L1/L2/L3 分层）
|
||
│ │
|
||
│ ├── daemon/ # Daemon 核心模块
|
||
│ │ ├── __init__.py
|
||
│ │ ├── ticker.py # Tick 循环主逻辑（30s）
|
||
│ │ ├── dispatcher.py # Agent 调度判据（Full/Subagent/Daemon 三级）
|
||
│ │ ├── spawner.py # Agent spawn + session 管理
|
||
│ │ ├── inbox.py # Inbox JSONL watcher + truncate
|
||
│ │ ├── guardrail.py # L1 assert 执行 + L2 subagent 触发
|
||
│ │ ├── review_flow.py # 审查流水线（单审/反驳权/辩论）
|
||
│ │ ├── experience.py # 一级蒸馏触发 + 经验注入
|
||
│ │ ├── bootstrap.py # build_bootstrap() L1/L2/L3 消息拼装
|
||
│ │ ├── health.py # 健康检查 + 逻辑死循环检测
|
||
│ │ ├── counter.py # ActiveAgentCounter 异步计数器
|
||
│ │ └── notifier.py # @mention 解析 + Inbox 事件注入
|
||
│ │
|
||
│ ├── api/ # HTTP API
|
||
│ │ ├── blackboard_routes.py # 黑板 CRUD API
|
||
│ │ ├── daemon_routes.py # Daemon 控制 API
|
||
│ │ ├── sse_routes.py # SSE 推送端点
|
||
│ │ └── project_routes.py # 多项目管理 API
|
||
│ │
|
||
│ ├── cli/ # CLI 工具
|
||
│ │ ├── blackboard.py # Agent 黑板操作 CLI
|
||
│ │ └── admin.py # 管理员控制 CLI
|
||
│ │
|
||
│ └── frontend/ # 前端（React + Vite）
|
||
│ ├── src/
|
||
│ │ ├── pages/ # 5 页面
|
||
│ │ │ ├── TaskBoard.tsx # 任务看板（核心）
|
||
│ │ │ ├── GlobalMonitor.tsx # 全局监控
|
||
│ │ │ ├── ArtifactVault.tsx # 产出档案
|
||
│ │ │ ├── SystemConfig.tsx # 系统配置
|
||
│ │ │ └── AIBriefing.tsx # AI Briefing
|
||
│ │ ├── components/
|
||
│ │ │ ├── CheckpointPanel.tsx # Checkpoint 交互
|
||
│ │ │ ├── NotificationCenter.tsx # 推送通知中心
|
||
│ │ │ └── ProjectSwitcher.tsx # 项目切换器
|
||
│ │ ├── store.ts # Zustand 状态管理
|
||
│ │ └── api.ts # API 层
|
||
│ └── dist/ # 构建产物（8083 直接服务）
|
||
│
|
||
├── config/
|
||
│ ├── default.yaml # 全局默认配置
|
||
│ ├── guardrails.yaml # Guardrail 规则（per task_type）
|
||
│ ├── template_components.yaml # 模板组件库（7组件 + custom）
|
||
│ └── review_protocols/ # 审查协议
|
||
│ ├── plan_review.yaml
|
||
│ ├── output_review.yaml
|
||
│ ├── analysis_review.yaml
|
||
│ └── final_review.yaml
|
||
│
|
||
├── prompt_templates/ # L2 引擎注入模板
|
||
│ ├── executor.md # 执行者操作规范
|
||
│ ├── reviewer.md # 审查者操作规范
|
||
│ ├── planner.md # 庞统规划操作规范
|
||
│ ├── adjudicator.md # 庞统裁决操作规范
|
||
│ ├── rebuttal.md # 反驳权操作规范
|
||
│ └── plan_checker.md # Plan Checker 验证规范
|
||
│
|
||
├── schemas/ # L1 Schema 校验
|
||
│ ├── handoff.schema.json
|
||
│ ├── output.schema.json
|
||
│ ├── decide.schema.json
|
||
│ └── observe.schema.json
|
||
│
|
||
├── projects/ # 多项目目录（课题11）
|
||
│ └── {project_id}/
|
||
│ ├── blackboard.db # per-project SQLite
|
||
│ ├── config/ # per-project 配置覆盖
|
||
│ │ └── project.yaml
|
||
│ ├── artifacts/ # per-project 产出物
|
||
│ ├── experiences/ # per-project 经验库
|
||
│ └── skills/ # per-project Skill 覆盖/扩展
|
||
│
|
||
├── inbox/ # Inbox JSONL
|
||
│ └── daemon.jsonl # 跨进程事件推送
|
||
│
|
||
├── skills/ # 全局 Skill 库
|
||
│ ├── builtins/ # 系统内置 Skill
|
||
│ │ ├── blackboard_operations/
|
||
│ │ ├── code_review/
|
||
│ │ └── data_validation/
|
||
│ └── custom/ # 蒸馏产出/用户创建
|
||
│ └── {skill_id}/
|
||
│ ├── SKILL.md # 四要素
|
||
│ ├── template.md # 可选详细模板
|
||
│ └── meta.yaml # 版本/来源/tag
|
||
│
|
||
├── tests/
|
||
│ ├── unit/
|
||
│ └── e2e/
|
||
│
|
||
├── pyproject.toml
|
||
├── ecosystem.config.cjs # PM2 配置
|
||
└── docs/ # 设计文档
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 数据库设计
|
||
|
||
### 4.1 数据库架构（per-project）
|
||
|
||
每个项目独立 SQLite 数据库，物理隔离。路径：`projects/{project_id}/blackboard.db`。
|
||
|
||
全局注册表：`projects/_registry.yaml`（YAML 文件，人可读可 Git 版本管理，紧急运维可直接编辑）。tick 热路径用内存 dict 缓存，_registry.yaml 只在 CLI 操作时读写（非热路径）。
|
||
|
||
### 4.2 表结构
|
||
|
||
完整 Schema 见 `architecture-v2.6.md §3.2`，此处列出核心表：
|
||
|
||
| 表 | 用途 | 来源课题 |
|
||
|----|------|---------|
|
||
| `tasks` | 任务主表（状态机） | 课题1 |
|
||
| `comments` | 评论/Handoff/辩论论点（含 comment_type） | 课题2/3 |
|
||
| `outputs` | 产出物（含 attempt_number） | 课题2 |
|
||
| `decisions` | 决策记录 | 课题1 |
|
||
| `observations` | 观察/吹哨（severity 分级） | 课题1 |
|
||
| `events` | 事件流（审计追踪） | 课题2 |
|
||
| `reviews` | 评审结果（含 confidence/rebuttal_status/debate_round） | 课题3 |
|
||
| `experiences` | 经验沉淀（含 tags） | 课题6 |
|
||
| `experience_tags` | 经验标签关联表 | 课题6 |
|
||
| `checkpoints` | Checkpoint 人工确认（v2.8/M3） | M3 |
|
||
|
||
### 4.3 关键约束
|
||
|
||
- WAL 模式 + `busy_timeout=5000` + `PRAGMA foreign_keys=ON`
|
||
- 所有写操作走 `BEGIN IMMEDIATE` 串行化
|
||
- comments 表 `comment_type` CHECK 约束区分 8 种类型
|
||
|
||
---
|
||
|
||
## 5. Daemon 核心架构
|
||
|
||
### 5.1 Tick 循环（30s）
|
||
|
||
```python
|
||
async def tick(project_id: str):
|
||
conn = get_connection(project_id)
|
||
try:
|
||
# 1. 逻辑健康自检（连续 N tick 无变更 → 告警）
|
||
health_check(conn)
|
||
|
||
# 2. 处理 Inbox JSONL（即时事件）
|
||
process_inbox(conn)
|
||
|
||
# 3. 扫描黑板状态
|
||
tasks = scan_tasks(conn)
|
||
|
||
# 4. 审查流水线处理
|
||
review_flow(conn, tasks)
|
||
|
||
# 5. 依赖推进（已完成任务解锁下游）
|
||
advance_dependencies(conn, tasks)
|
||
|
||
# 6. 反驳权进度检测（催促通知）
|
||
check_rebuttal_progress(conn)
|
||
|
||
# 7. Agent 调度
|
||
dispatch_pending(conn, tasks)
|
||
|
||
# 8. 一级蒸馏触发
|
||
check_distillation(conn)
|
||
|
||
finally:
|
||
conn.close()
|
||
```
|
||
|
||
**Tick + Inbox 双层事件架构**：
|
||
- Tick 30s 兜底扫描（Pull）
|
||
- Inbox JSONL 秒级推送加速（Push）
|
||
- Inbox 文件用 truncate（清空不删除），避免并发写入时文件不存在
|
||
|
||
### 5.2 Agent 调度判据（三级决策树）
|
||
|
||
详见 `topic3-challenge-review-proposal.md §5.4`。
|
||
|
||
```python
|
||
def dispatch(task, action_type, project_config):
|
||
registered_agents = project_config.get("agents", [])
|
||
|
||
# Level 1: 纯机械检查 → Daemon 直接执行
|
||
if action_type in ("L1_guardrail", "format_check", "file_exists_check"):
|
||
return execute_locally(task)
|
||
|
||
# Level 2: 有名字的角色 → Full Agent (asyncio.create_subprocess_exec)
|
||
if task.assignee in registered_agents:
|
||
if action_type == "adjudication":
|
||
return spawn_full_agent(task.assignee, new_session=True)
|
||
return spawn_full_agent(task.assignee)
|
||
|
||
# Level 3: 无名字的一次性任务 → Subagent (sessions_spawn)
|
||
if DISPATCH_RULES.get(action_type) == "subagent":
|
||
return spawn_subagent(task_description=action_type)
|
||
|
||
# Level 4: 未知 action_type → 庞统裁决
|
||
return spawn_full_agent("pangtong-fujunshi", new_session=True)
|
||
```
|
||
|
||
**spawn 方式**：
|
||
- Full Agent：`asyncio.create_subprocess_exec`（异步非阻塞），不 await 完成，下次 tick 检查产出
|
||
- Subagent：`sessions_spawn`（Gateway API），等返回
|
||
|
||
### 5.3 线程模型：纯 asyncio 单线程
|
||
|
||
整个 Daemon 运行在单个 asyncio event loop 中（与 FastAPI 共享）。
|
||
|
||
**关键设计决策**：Full Agent spawn 不用 `subprocess.Popen`（同步，会短暂阻塞 event loop），改用 `asyncio.create_subprocess_exec`（异步非阻塞）。这样 API 请求处理、SSE 推送、Daemon tick 三者互不阻塞。
|
||
|
||
```python
|
||
async def spawn_full_agent(agent_id: str, message: str, new_session: bool = False) -> str:
|
||
"""异步非阻塞 spawn，全程 asyncio"""
|
||
session_id = str(uuid.uuid4())
|
||
cmd = ["openclaw", "agent", "--agent", agent_id,
|
||
"--session-id", session_id, "--message", message, "--json"]
|
||
|
||
proc = await asyncio.create_subprocess_exec(
|
||
*cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
|
||
)
|
||
# 不 await proc.wait()，让子进程独立运行
|
||
# 下次 tick 通过产出物检查完成状态
|
||
_register_session(agent_id, session_id, proc.pid)
|
||
return session_id
|
||
```
|
||
|
||
**Subagent spawn** 通过 OpenClaw Gateway 内部 API（`sessions_spawn`），天然异步。
|
||
|
||
### 5.4 ActiveAgentCounter（课题11）
|
||
|
||
纯 asyncio 实现（`asyncio.Semaphore`），与线程模型一致：
|
||
"""异步计数器，控制并发"""
|
||
def __init__(self, max_global=5, max_per_agent=1):
|
||
self._global = asyncio.Semaphore(max_global)
|
||
self._per_agent = {} # agent_id → Semaphore(max_per_agent)
|
||
|
||
async def acquire(self, agent_id: str) -> bool:
|
||
if self._global.locked():
|
||
return False
|
||
agent_sem = self._per_agent.get(agent_id)
|
||
if agent_sem and agent_sem.locked():
|
||
return False
|
||
await self._global.acquire()
|
||
if agent_id not in self._per_agent:
|
||
self._per_agent[agent_id] = asyncio.Semaphore(self._max_per_agent)
|
||
await self._per_agent[agent_id].acquire()
|
||
return True
|
||
|
||
def release(self, agent_id: str):
|
||
self._per_agent[agent_id].release()
|
||
self._global.release()
|
||
```
|
||
|
||
### 5.5 build_bootstrap() 四层上下文拼装
|
||
|
||
详见 `topic4-decomposition-skill-proposal.md D4-7`。
|
||
|
||
```
|
||
L0 铁律层（~500 tokens） → Hook 注入，不占 bootstrap
|
||
L1 角色层（~2000 tokens） → SOUL.md / IDENTITY.md（Agent 自带）
|
||
L2 引擎注入层（~1500 tokens）→ prompt_templates 按 role 拼装
|
||
① 操作规范（executor.md / reviewer.md / planner.md）
|
||
② 项目背景（project_context.yaml）
|
||
③ 任务上下文（黑板数据）
|
||
④ 前序信息（depends_on 产出摘要）
|
||
⑤ Guardrail 规则（guardrails.yaml，仅执行者）
|
||
⑥ 审查协议（review_protocols/，仅审查者）
|
||
⑦ 经验注入（experiences 表按 tag 匹配）
|
||
L3 被动参考层（按需加载）→ Skill description 四要素
|
||
```
|
||
|
||
L2 按角色精确注入：执行者注入⑤⑥，审查者注入⑥，庞统注入⑥。
|
||
|
||
---
|
||
|
||
## 6. 审查流水线
|
||
|
||
### 6.1 分级审查
|
||
|
||
| 风险等级 | 流水线 | 方案审查 | 产出审查 | 模式 | max_rounds |
|
||
|---------|--------|---------|---------|------|-----------|
|
||
| **high** | 三阶段 | ✅ 对抗辩论 | ✅ 对抗辩论 + Guardrail | debate | 5 |
|
||
| **standard** | 二阶段 | ✅ 单审 | ✅ 单审 + Guardrail | single_reviewer | 3 |
|
||
| **low** | 一阶段 | ❌ | ⚡ Guardrail 自动 | auto | 0 |
|
||
| **research** | 一阶段 | ❌ | ✅ 庞统确认 | single_reviewer | 2 |
|
||
|
||
### 6.2 Guardrail 执行
|
||
|
||
```yaml
|
||
# config/guardrails.yaml 示例
|
||
task_types:
|
||
coding:
|
||
output_review:
|
||
required: true
|
||
layers:
|
||
L1: # Daemon 直接执行
|
||
- assert: "len(glob('tests/test_*.py')) > 0"
|
||
message: "缺少测试文件"
|
||
- assert: "import subprocess; subprocess.run(['python', '-m', 'py_compile', output_path], check=True)"
|
||
message: "Python 语法检查失败"
|
||
L2: # Subagent 执行
|
||
prompt: "检查代码是否遵循项目规范，重点关注：命名、异常处理、资源释放"
|
||
deploy:
|
||
output_review:
|
||
required: true
|
||
layers:
|
||
L1:
|
||
- assert: "os.path.exists('deploy_log.md')"
|
||
message: "缺少部署日志"
|
||
data:
|
||
output_review:
|
||
required: false # low 风险，Guardrail 自动
|
||
```
|
||
|
||
### 6.3 反驳权流控
|
||
|
||
审查者 verdict=needs_revision（有 critical/major）→ spawn 原执行者反驳 → 协商轮次 ≤ max_rounds → 不设超时，有催促通知 → 超轮次升级庞统。
|
||
|
||
详见 `topic3-challenge-review-proposal.md §5.3`。
|
||
|
||
### 6.4 评审详情 Schema
|
||
|
||
评审结果写入 `{task_id}/reviews/{review_id}.json`，包含：
|
||
- `issues[]`（status/severity/category/location+context/suggestion）
|
||
- `evidence[]`（file_content/command_output）
|
||
- `positives[]`、`meta`
|
||
- category 含：correctness/security/performance/style/scope_deviation/**architecture/robustness**
|
||
|
||
详见 `topic3-challenge-review-proposal.md §5.2`。
|
||
|
||
---
|
||
|
||
## 7. 经验沉淀
|
||
|
||
### 7.1 两级蒸馏
|
||
|
||
| 级别 | 触发时机 | 产出 | 存储 |
|
||
|------|---------|------|------|
|
||
| 一级（实时） | 任务完成后 | 经验条目（key findings/lessons/tags） | experiences 表 |
|
||
| 二级（周期） | 同 tag 积累 N 条 | Skill 草稿（draft→active→deprecated） | skills/ 目录 |
|
||
|
||
### 7.2 经验注入
|
||
|
||
build_bootstrap() 按 tag 检索 experiences 表，格式化后注入 L2 上下文。
|
||
|
||
详见 `topic6-experience-loop-proposal.md`。
|
||
|
||
---
|
||
|
||
## 8. Skill 体系
|
||
|
||
### 8.1 Skill 三层载体
|
||
|
||
| 载体 | 自由度 | 生命周期 | 产出者 | 存储 |
|
||
|------|--------|---------|--------|------|
|
||
| **Memory** | 高（自然语言） | 短期（30天过期） | Agent 自动沉淀 | experiences 表 |
|
||
| **Skill** | 中（模板+约束） | 中期（版本管理） | 二级蒸馏 / 人工编写 | skills/ 目录 |
|
||
| **Rule** | 低（脚本/断言） | 长期（代码级稳定） | 人工提炼 | guardrails.yaml |
|
||
|
||
信息压缩方向：Memory → Skill → Rule（自由度递减，可靠性递增）。
|
||
|
||
### 8.2 Skill 目录结构
|
||
|
||
```
|
||
sanguo_moziplus_v2/
|
||
├── skills/ ← 全局 Skill 库
|
||
│ ├── builtins/ ← 系统内置 Skill
|
||
│ │ ├── blackboard_operations/ ← 黑板操作规范
|
||
│ │ ├── code_review/ ← 代码审查标准
|
||
│ │ └── data_validation/ ← 数据验证
|
||
│ └── custom/ ← 用户/蒸馏产出 Skill
|
||
│ └── {skill_id}/n │ ├── SKILL.md ← 四要素：description/triggers/actions/constraints
|
||
│ ├── template.md ← 可选：详细模板
|
||
│ └── meta.yaml ← 版本、来源、tag
|
||
│
|
||
├── projects/{pid}/
|
||
│ └── skills/ ← per-project Skill 覆盖/扩展
|
||
│ └── {skill_id}/
|
||
│ └── project_override.md
|
||
```
|
||
|
||
### 8.3 Skill 四要素（SKILL.md 格式）
|
||
|
||
```markdown
|
||
# {skill_name}
|
||
|
||
## Description
|
||
一句话描述能力。
|
||
|
||
## Triggers
|
||
自动触发条件（任务类型/关键词/产出类型）。
|
||
|
||
## Actions
|
||
执行步骤和产出要求。
|
||
|
||
## Constraints
|
||
硬性约束（必须满足/禁止做）。
|
||
```
|
||
|
||
### 8.4 Skill 生命周期
|
||
|
||
```
|
||
draft（蒸馏产出/人工创建）
|
||
→ active（验证通过，build_bootstrap 可引用）
|
||
→ deprecated（30天无引用/被更好的替代）
|
||
→ deleted（清理）
|
||
```
|
||
|
||
- **draft → active**：二级蒸馏自动标记，或人工在 Dashboard 审批
|
||
- **active → deprecated**：`expire_days` 无引用自动降级
|
||
- **active → deprecated → deleted**：有新版本替代时
|
||
|
||
### 8.5 Skill 在 Daemon 中的角色
|
||
|
||
```python
|
||
# daemon/bootstrap.py 中 Skill 加载逻辑
|
||
|
||
def load_skills(task, role, project_config) -> list[str]:
|
||
"""L3 被动参考层：按需加载 Skill description"""
|
||
skills = []
|
||
|
||
# 1. 按 task_type 匹配 triggers
|
||
builtin_skills = scan_skills("skills/builtins/", task.task_type)
|
||
|
||
# 2. per-project 覆盖
|
||
project_skills = scan_skills(f"projects/{task.project_id}/skills/", task.task_type)
|
||
|
||
# 3. 经验匹配（experiences 表按 tag 检索，注入 L2）
|
||
# → 这部分在 build_bootstrap() 的 L2 ⑦ 中处理
|
||
|
||
# 4. 只返回 description（四要素摘要），不加载完整 SKILL.md
|
||
return [s.description for s in builtin_skills + project_skills if s.status == 'active']
|
||
```
|
||
|
||
**四层加载**（来源：课题4 D4-6）：
|
||
|
||
| 层 | 加载时机 | 内容 | 占用 |
|
||
|----|---------|------|------|
|
||
| Agent 固化 | OpenClaw agent 配置 | SOUL.md/IDENTITY.md/TOOLS.md | L1（Agent 自带） |
|
||
| OpenClaw 注册 | agent 启动时 | OpenClaw skills/ 目录 | L3（按需） |
|
||
| moziplus 注入 | build_bootstrap() | prompt_templates + guardrails + review_protocols | L2（精确注入） |
|
||
| 按需检索 | Agent 执行中主动查询 | Skill SKILL.md 全文 | L3（Agent 自己读） |
|
||
|
||
### 8.6 template_components.yaml
|
||
|
||
模板组件库，build_bootstrap() L2 拼装时引用：
|
||
|
||
```yaml
|
||
components:
|
||
- id: executor_ops
|
||
file: prompt_templates/executor.md
|
||
inject_to: [executor]
|
||
|
||
- id: reviewer_ops
|
||
file: prompt_templates/reviewer.md
|
||
inject_to: [reviewer]
|
||
|
||
- id: planner_ops
|
||
file: prompt_templates/planner.md
|
||
inject_to: [planner]
|
||
|
||
- id: guardrails
|
||
file: config/guardrails.yaml
|
||
inject_to: [executor]
|
||
condition: task_type in guardrails
|
||
|
||
- id: review_protocol
|
||
file: config/review_protocols/{task_type}_review.yaml
|
||
inject_to: [reviewer, planner]
|
||
condition: review required
|
||
|
||
- id: experience_injection
|
||
source: experiences_table
|
||
inject_to: [executor, reviewer]
|
||
condition: matching_tags > 0
|
||
|
||
- id: custom
|
||
file: null # per-project 自定义
|
||
inject_to: []
|
||
```
|
||
|
||
---
|
||
|
||
## 9. API 设计
|
||
|
||
### 9.1 黑板 API
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/projects/{pid}/tasks` | 任务列表（支持过滤） |
|
||
| GET | `/api/projects/{pid}/tasks/{id}` | 任务详情 |
|
||
| POST | `/api/projects/{pid}/tasks` | 创建任务 |
|
||
| POST | `/api/projects/{pid}/tasks/{id}/claim` | 认领 |
|
||
| PATCH | `/api/projects/{pid}/tasks/{id}/status` | 更新状态 |
|
||
| POST | `/api/projects/{pid}/tasks/{id}/comments` | 添加评论 |
|
||
| POST | `/api/projects/{pid}/tasks/{id}/outputs` | 写入产出 |
|
||
| POST | `/api/projects/{pid}/tasks/{id}/decisions` | 记录决策 |
|
||
| POST | `/api/projects/{pid}/tasks/{id}/observations` | 添加观察 |
|
||
| POST | `/api/projects/{pid}/tasks/{id}/reviews` | 提交评审 |
|
||
| POST | `/api/projects/{pid}/tasks/{id}/archive` | 归档/取消归档（v2.8） |
|
||
| POST | `/api/projects/{pid}/tasks/archive-done` | 一键归档（v2.8） |
|
||
| GET | `/api/projects/{pid}/tasks/{id}/checkpoints` | Checkpoint 列表（M3） |
|
||
| POST | `/api/projects/{pid}/tasks/{id}/checkpoints` | 创建 Checkpoint（M3） |
|
||
| POST | `/api/projects/{pid}/tasks/{id}/checkpoints/{cid}/approve` | Checkpoint 通过（M3） |
|
||
| POST | `/api/projects/{pid}/tasks/{id}/checkpoints/{cid}/reject` | Checkpoint 驳回（M3） |
|
||
|
||
### 9.2 Daemon 控制 API
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/api/daemon/tick` | 手动触发 tick |
|
||
| GET | `/api/daemon/status` | Daemon 状态 |
|
||
| GET | `/api/daemon/sessions` | 活跃 session |
|
||
|
||
### 9.3 SSE 推送
|
||
|
||
```
|
||
GET /api/events?project={pid}
|
||
→ SSE 流，事件类型：
|
||
task_created / task_status_changed / review_submitted / rebuttal_added
|
||
notification（4级：🔴🟡🟢🔵）
|
||
```
|
||
|
||
### 9.4 多项目 API
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/projects` | 项目列表 |
|
||
| POST | `/api/projects` | 创建项目 |
|
||
| GET | `/api/projects/{pid}` | 项目详情 |
|
||
| DELETE | `/api/projects/{pid}` | 归档项目（安全流程） |
|
||
|
||
---
|
||
|
||
## 10. Hook 系统
|
||
|
||
双重 Hook 架构：
|
||
|
||
| Hook | 所属 | 触发时机 | 用途 |
|
||
|------|------|---------|------|
|
||
| `agent_turn_prepare` | OpenClaw Plugin | Agent 接收消息前 | 注入铁律（L0） |
|
||
| `agent_turn_complete` | OpenClaw Plugin | Agent 完成后 | 触发 lint/test（工具链集成点） |
|
||
| `pre_task_claim` | moziplus HookRegistry | Agent claim 前 | 权限检查 |
|
||
| `post_output_write` | moziplus HookRegistry | 产出写入后 | 触发 Guardrail 检查 |
|
||
| `post_review_submit` | moziplus HookRegistry | 评审提交后 | 触发反驳权流程 |
|
||
|
||
---
|
||
|
||
## 11. 前端架构
|
||
|
||
### 11.1 技术选型
|
||
|
||
复用 v1.0 前端框架（React + Vite + TypeScript），重设计页面结构。
|
||
|
||
### 11.2 页面结构（5页）
|
||
|
||
| 页面 | 内容 | 来源 |
|
||
|------|------|------|
|
||
| **任务看板** | 任务卡片、Checkpoint 交互、状态流转 | 课题7+9 |
|
||
| **全局监控** | Agent 状态、系统健康、资源使用 | 课题9 |
|
||
| **产出档案** | 产出物预览/下载、评审详情 | 课题9 |
|
||
| **系统配置** | 项目管理、Agent 配置、Guardrail 编辑 | 课题9 |
|
||
| **AI Briefing** | 日报/周报自动生成 | 课题9 |
|
||
|
||
### 11.3 实时推送
|
||
|
||
SSE 端点 `/api/events`，前端 EventSource 监听。4 级推送（🔴🟡🟢🔵）。降级：SSE 不可用时 30s 轮询。
|
||
|
||
### 11.4 构建部署
|
||
|
||
```bash
|
||
cd src/frontend && npm run build
|
||
# 产物在 src/frontend/dist/
|
||
# FastAPI 直接托管静态文件（port 8083）
|
||
```
|
||
|
||
详见 `topic9-dashboard-design.md`（课题9 Dashboard 前后端完整设计方案）。
|
||
|
||
---
|
||
|
||
## 12. 测试策略
|
||
|
||
### 12.1 单元测试
|
||
|
||
| 测试文件 | 覆盖 |
|
||
|---------|------|
|
||
| test_blackboard.py | operations 全函数（claim CAS、状态机、comment_type、review CRUD） |
|
||
| test_daemon_tick.py | tick 流程（Inbox 处理、依赖推进、反驳权进度检测） |
|
||
| test_dispatcher.py | 三级调度判据 + fallback |
|
||
| test_guardrail.py | L1 assert 执行 + L2 prompt 触发 |
|
||
| test_review_flow.py | 审查流水线（分级审查、反驳权、升级） |
|
||
| test_experience.py | 一级蒸馏 + tag 检索 |
|
||
| test_bootstrap.py | 四层上下文拼装（按 role 精确注入） |
|
||
| test_counter.py | ActiveAgentCounter 并发控制 |
|
||
|
||
### 12.2 集成测试
|
||
|
||
- 创建任务 → 调度执行 → Guardrail → 审查 → 反驳 → 完成 闭环
|
||
- 多项目并发：两个项目同时 tick，互不影响
|
||
- 竞态测试：两个 Agent 同时 claim + 同时写 inbox
|
||
|
||
### 12.3 测试数据库
|
||
|
||
per-project 测试用 `:memory:` SQLite。全局注册表测试用临时文件。
|
||
|
||
---
|
||
|
||
## 13. 实现顺序
|
||
|
||
| Phase | 内容 | 估计时间 |
|
||
|-------|------|---------|
|
||
| **P1** | 黑板 + Daemon + CLI + API + 多项目 | ~20-25h（含调试 buffer） |
|
||
| **P2** | 审查流水线 + Guardrail + 反驳权 + build_bootstrap | ~12h |
|
||
| **P3** | 前端重设计 + SSE 推送 + AI Briefing | ~10h |
|
||
| **P4** | 经验沉淀 + Skill 进化 + 工具链集成 | ~8h |
|
||
|
||
---
|
||
|
||
## 14. 容量估算
|
||
|
||
### 14.1 存储容量
|
||
|
||
| 组件 | 单项目估算 | 说明 |
|
||
|------|-----------|------|
|
||
| blackboard.db | 2-10 MB / 100 任务 | tasks + comments(5-20行/任务) + outputs + reviews + events(5-10行/任务) + experiences，含索引和 WAL overhead |
|
||
| artifacts/ | 10-50 MB / 100 任务 | 代码文件、分析报告、数据文件 |
|
||
| experiences/ | < 1 MB | 经验条目轻量，文本为主 |
|
||
| Inbox JSONL | < 100 KB | 持续 truncate，不累积 |
|
||
| _registry.yaml | < 10 KB | 项目元信息，轻量 |
|
||
|
||
**总磁盘预估（10 项目，1000 任务）**：~1-2 GB，完全在 Mac mini 容量范围内。
|
||
|
||
### 14.2 内存占用
|
||
|
||
| 组件 | 占用估算 | 说明 |
|
||
|------|---------|------|
|
||
| Daemon + FastAPI | 50-100 MB | Python 进程基础 + asyncio event loop |
|
||
| 每个 Agent spawn | 100-300 MB | openclaw agent CLI 进程，执行期间临时占用 |
|
||
| SQLite 连接池 | < 10 MB | per-project 连接，用完释放 |
|
||
| 前端 dist 静态服务 | < 5 MB | 内存映射 |
|
||
|
||
**峰值内存（max_global=5，5 个 Agent 同时执行）**：~1-1.5 GB，16GB Mac mini 无压力。
|
||
|
||
### 14.3 并发能力
|
||
|
||
| 维度 | 设计上限 | 瓶颈分析 |
|
||
|------|---------|----------|
|
||
| 同时活跃项目 | 无硬限（10+） | tick 30s 扫全部项目，每项目 tick 耗时 < 100ms，10 项目 < 1s |
|
||
| 并发 Agent | 5 (max_global) | ActiveAgentCounter 控制，超出排队 |
|
||
| SSE 连接 | 10-20 | 单机场景足够，FastAPI SSE 无硬限 |
|
||
| Inbox 吞吐 | 200+ 写/秒 | truncate 模式，实测无丢失 |
|
||
| API QPS | 100+ | FastAPI 单进程足够，无 LB 瓶颈 |
|
||
|
||
### 14.4 性能约束
|
||
|
||
| 场景 | 延迟 | 说明 |
|
||
|------|------|------|
|
||
| 用户提需求 → 任务写入黑板 | < 5s | Agent 对话 + CLI 写入 |
|
||
| 任务 pending → Agent 开始执行 | 30s 内 | 最坏等一轮 tick；Inbox 触发可秒级 |
|
||
| Agent 完成 → 下游任务 pending | 30s 内 | tick 扫描依赖推进 |
|
||
| SSE 事件推送延迟 | < 1s | event loop 内直接推送 |
|
||
| 审查 → 反驳权启动 | 30s 内 | tick 扫描 review 状态 |
|
||
|
||
---
|
||
|
||
## 15. 失败模式与可靠性
|
||
|
||
### 15.1 进程级故障
|
||
|
||
| 故障 | 检测 | 恢复 |
|
||
|------|------|------|
|
||
| Daemon 进程崩溃 | PM2 auto restart | PM2 5s 内自动拉起，tick 恢复扫描 |
|
||
| Agent spawn 子进程僵死 | health.py 僵尸检测 | 连续 20 tick 无变更 → observation 告警 + reclaim 释放 semaphore |
|
||
| Agent spawn 失败（CLI 错误） | spawner 异常捕获 | 标记任务 failed，写入 events 表，不阻塞其他任务 |
|
||
| FastAPI 进程异常 | PM2 restart | 与 Daemon 同进程，PM2 统一管理 |
|
||
|
||
### 15.2 数据级故障
|
||
|
||
| 故障 | 检测 | 恢复 |
|
||
|------|------|------|
|
||
| SQLite 写入冲突 | busy_timeout=5s 等待 + WAL 模式 | WAL 允许并发读写；超时后 raise，tick 下次重试 |
|
||
| SQLite DB 损坏 | 连接时 PRAGMA integrity_check | per-project 隔离，单 DB 损坏不影响其他项目；从最新 Git 备份恢复 |
|
||
| Inbox JSONL 损坏 | JSON 解析异常 | truncate 清空重置，Agent 重发事件 |
|
||
| _registry.yaml 损坏 | YAML 解析异常 | Git 版本管理，`git checkout` 恢复 |
|
||
|
||
### 15.3 逻辑级故障
|
||
|
||
| 故障 | 检测 | 恢复 |
|
||
|------|------|------|
|
||
| Agent 无限循环 | 连续 20 tick 无状态变更 | observation 告警 + 通知用户 + reclaim |
|
||
| 反驳权无限协商 | max_rounds 兜底 | 超轮次自动升级庞统裁决 |
|
||
| 任务卡在 blocked | tick 依赖推进检查 | 每轮 tick 重算依赖，不依赖缓存 |
|
||
| Guardrail 误杀 | L1 assert 可能误判 | L2 subagent 二次确认；用户可在 Dashboard 手动 override |
|
||
|
||
### 15.4 恢复优先级
|
||
|
||
```
|
||
P0: Daemon 进程 → PM2 auto restart
|
||
P1: 数据完整性 → SQLite WAL + Git 备份
|
||
P2: 任务进度 → tick 全量扫描自动恢复
|
||
P3: 经验数据 → experiences 表 + skills/ 目录 Git 版本管理
|
||
```
|
||
|
||
---
|
||
|
||
## 16. 演进路径
|
||
|
||
### 16.1 已知限制与扩展点
|
||
|
||
| 当前限制 | 触发条件 | 演进方向 |
|
||
|---------|---------|--------|
|
||
| SQLite 单机 | 项目 > 20 或 DB > 100MB | 迁移 PostgreSQL（per-project schema），代码层只改 db.py |
|
||
| max_global=5 | Agent 并发不够 | 调整 ActiveAgentCounter 参数；引入优先级队列 |
|
||
| 单机部署 | 需要多节点 | Agent spawn 改为远程调度（Windows-Test-Node 已可远程执行） |
|
||
| SSE 单进程 | SSE 连接 > 50 | 引入 Redis pub/sub + 多 worker |
|
||
| 无用户认证 | 多用户协作需求 | 引入 API token + per-project 权限（project.yaml 扩展） |
|
||
|
||
### 16.2 接口抽象层（为演进预留）
|
||
|
||
关键接口已做抽象，替换底层不影响上层逻辑：
|
||
|
||
| 接口 | 当前实现 | 替换时影响范围 |
|
||
|------|---------|--------------|
|
||
| `blackboard.db.py` | SQLite | 只改 db.py，operations/queries 不变 |
|
||
| `daemon.spawner.py` | asyncio.create_subprocess_exec | 只改 spawner.py，dispatcher 不变 |
|
||
| `daemon.counter.py` | asyncio.Semaphore | 只改 counter.py，dispatcher 不变 |
|
||
| `api.sse_routes.py` | FastAPI SSE | 只改 sse_routes.py，前端不变 |
|
||
|
||
---
|
||
|
||
## 17. 风险
|
||
|
||
| 风险 | 概率 | 影响 | 缓解 |
|
||
|------|------|------|------|
|
||
| per-project SQLite 并发 tick | 中 | 中 | WAL + busy_timeout + per-project asyncio.Lock |
|
||
| Agent spawn 子进程回收 | 中 | 中 | health.py 僵尸检测 + reclaim |
|
||
| Inbox JSONL 并发写入 | 低 | 低 | truncate（不删除），实测 200 并发 0 丢失 |
|
||
| 前端 v1→v2 迁移 | 低 | 低 | v1(8082) 和 v2(8083) 独立运行，渐进替换 |
|
||
| Daemon 逻辑死循环 | 低 | 中 | 连续 20 tick 无变更 → observation 告警 + 通知用户 |
|
||
| 反驳权无限协商 | 低 | 低 | max_rounds 兜底 + 超轮次升级庞统 |
|
||
| 上下文窗口膨胀 | 中 | 中 | L0-L3 四层分级 + 产出写入黑板不累积 |
|
||
| 经验注入噪声 | 低 | 低 | 只注入 matching tag 的经验；N 条阈值可控 |
|
||
| Guardrail 误杀 | 低 | 中 | L1+L2 双层验证；用户可 Dashboard override |
|