cfdaily
492 lines
18 KiB
Markdown
492 lines
18 KiB
Markdown
# v2.6 技术方案设计
|
||
|
||
**版本**: v2.6.2-tech
|
||
**基于**: architecture-v2.6.md (v2.6.11)
|
||
**作者**: 庞统（副军师）🐦
|
||
**日期**: 2026-05-16
|
||
|
||
---
|
||
|
||
## 1. 技术栈
|
||
|
||
| 组件 | 选型 | 版本 | 理由 |
|
||
|------|------|------|------|
|
||
| Daemon 进程管理 | PM2 | 6.0.14 | 独立进程 sanguo-moziplus-v2 |
|
||
| Daemon 框架 | Python + asyncio | 3.9+ | tick 循环 + FastAPI 共存 |
|
||
| 黑板存储 | SQLite（per-project） | 3.51+ | WAL 模式，物理隔离 |
|
||
| HTTP API | FastAPI + uvicorn | 独立安装 | 端口 8083 |
|
||
| Agent 调度 | openclaw CLI / sessions_spawn | 2026.5.7 | Full Agent / Subagent 双路径 |
|
||
| 前端 | React + Vite + TypeScript | 复用 v1.0 | 5页面 Dashboard |
|
||
| 实时推送 | SSE (Server-Sent Events) | FastAPI 内置 | 降级轮询兜底 |
|
||
| Git | gitee + gitea | 双远程 | 开发→安装同步 |
|
||
| 配置 | YAML (PyYAML) | — | guardrails / review_protocols / template_components |
|
||
|
||
**不加重型新依赖。** 所有组件基于已有环境。
|
||
|
||
---
|
||
|
||
## 2. 项目结构
|
||
|
||
```
|
||
sanguo_moziplus_v2/ # 项目根目录
|
||
├── src/
|
||
│ ├── main.py # FastAPI 入口 + Daemon ticker 启动
|
||
│ │
|
||
│ ├── blackboard/ # 黑板核心模块
|
||
│ │ ├── __init__.py
|
||
│ │ ├── db.py # SQLite 连接管理（per-project）
|
||
│ │ ├── models.py # 数据模型
|
||
│ │ ├── operations.py # 写操作（task/comment/output/decision/observation/review）
|
||
│ │ └── queries.py # 读操作（L1/L2/L3 分层）
|
||
│ │
|
||
│ ├── daemon/ # Daemon 核心模块
|
||
│ │ ├── __init__.py
|
||
│ │ ├── ticker.py # Tick 循环主逻辑（30s）
|
||
│ │ ├── dispatcher.py # Agent 调度判据（Full/Subagent/Daemon 三级）
|
||
│ │ ├── spawner.py # Agent spawn + session 管理
|
||
│ │ ├── inbox.py # Inbox JSONL watcher + truncate
|
||
│ │ ├── guardrail.py # L1 assert 执行 + L2 subagent 触发
|
||
│ │ ├── review_flow.py # 审查流水线（单审/反驳权/辩论）
|
||
│ │ ├── experience.py # 一级蒸馏触发 + 经验注入
|
||
│ │ ├── bootstrap.py # build_bootstrap() L1/L2/L3 消息拼装
|
||
│ │ ├── health.py # 健康检查 + 逻辑死循环检测
|
||
│ │ ├── counter.py # ActiveAgentCounter 异步计数器
|
||
│ │ └── notifier.py # @mention 解析 + Inbox 事件注入
|
||
│ │
|
||
│ ├── api/ # HTTP API
|
||
│ │ ├── blackboard_routes.py # 黑板 CRUD API
|
||
│ │ ├── daemon_routes.py # Daemon 控制 API
|
||
│ │ ├── sse_routes.py # SSE 推送端点
|
||
│ │ └── project_routes.py # 多项目管理 API
|
||
│ │
|
||
│ ├── cli/ # CLI 工具
|
||
│ │ ├── blackboard.py # Agent 黑板操作 CLI
|
||
│ │ └── admin.py # 管理员控制 CLI
|
||
│ │
|
||
│ └── frontend/ # 前端（React + Vite）
|
||
│ ├── src/
|
||
│ │ ├── pages/ # 5 页面
|
||
│ │ │ ├── TaskBoard.tsx # 任务看板（核心）
|
||
│ │ │ ├── GlobalMonitor.tsx # 全局监控
|
||
│ │ │ ├── ArtifactVault.tsx # 产出档案
|
||
│ │ │ ├── SystemConfig.tsx # 系统配置
|
||
│ │ │ └── AIBriefing.tsx # AI Briefing
|
||
│ │ ├── components/
|
||
│ │ │ ├── CheckpointPanel.tsx # Checkpoint 交互
|
||
│ │ │ ├── NotificationCenter.tsx # 推送通知中心
|
||
│ │ │ └── ProjectSwitcher.tsx # 项目切换器
|
||
│ │ ├── store.ts # Zustand 状态管理
|
||
│ │ └── api.ts # API 层
|
||
│ └── dist/ # 构建产物（8083 直接服务）
|
||
│
|
||
├── config/
|
||
│ ├── default.yaml # 全局默认配置
|
||
│ ├── guardrails.yaml # Guardrail 规则（per task_type）
|
||
│ ├── template_components.yaml # 模板组件库（7组件 + custom）
|
||
│ └── review_protocols/ # 审查协议
|
||
│ ├── plan_review.yaml
|
||
│ ├── output_review.yaml
|
||
│ ├── analysis_review.yaml
|
||
│ └── final_review.yaml
|
||
│
|
||
├── prompt_templates/ # L2 引擎注入模板
|
||
│ ├── executor.md # 执行者操作规范
|
||
│ ├── reviewer.md # 审查者操作规范
|
||
│ ├── planner.md # 庞统规划操作规范
|
||
│ ├── adjudicator.md # 庞统裁决操作规范
|
||
│ ├── rebuttal.md # 反驳权操作规范
|
||
│ └── plan_checker.md # Plan Checker 验证规范
|
||
│
|
||
├── schemas/ # L1 Schema 校验
|
||
│ ├── handoff.schema.json
|
||
│ ├── output.schema.json
|
||
│ ├── decide.schema.json
|
||
│ └── observe.schema.json
|
||
│
|
||
├── projects/ # 多项目目录（课题11）
|
||
│ └── {project_id}/
|
||
│ ├── blackboard.db # per-project SQLite
|
||
│ ├── config/ # per-project 配置覆盖
|
||
│ │ └── project.yaml
|
||
│ ├── artifacts/ # per-project 产出物
|
||
│ └── experiences/ # per-project 经验库
|
||
│
|
||
├── inbox/ # Inbox JSONL
|
||
│ └── daemon.jsonl # 跨进程事件推送
|
||
│
|
||
├── tests/
|
||
│ ├── unit/
|
||
│ └── e2e/
|
||
│
|
||
├── pyproject.toml
|
||
├── ecosystem.config.cjs # PM2 配置
|
||
└── docs/ # 设计文档
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 数据库设计
|
||
|
||
### 3.1 数据库架构（per-project）
|
||
|
||
每个项目独立 SQLite 数据库，物理隔离。路径：`projects/{project_id}/blackboard.db`。
|
||
|
||
全局注册表：`projects/registry.db`（存储项目列表和元数据）。
|
||
|
||
### 3.2 表结构
|
||
|
||
完整 Schema 见 `architecture-v2.6.md §3.2`，此处列出核心表：
|
||
|
||
| 表 | 用途 | 来源课题 |
|
||
|----|------|---------|
|
||
| `tasks` | 任务主表（状态机） | 课题1 |
|
||
| `comments` | 评论/Handoff/辩论论点（含 comment_type） | 课题2/3 |
|
||
| `outputs` | 产出物（含 attempt_number） | 课题2 |
|
||
| `decisions` | 决策记录 | 课题1 |
|
||
| `observations` | 观察/吹哨（severity 分级） | 课题1 |
|
||
| `events` | 事件流（审计追踪） | 课题2 |
|
||
| `reviews` | 评审结果（含 confidence/rebuttal_status/debate_round） | 课题3 |
|
||
| `experiences` | 经验沉淀（含 tags） | 课题6 |
|
||
| `experience_tags` | 经验标签关联表 | 课题6 |
|
||
|
||
### 3.3 关键约束
|
||
|
||
- WAL 模式 + `busy_timeout=5000` + `PRAGMA foreign_keys=ON`
|
||
- 所有写操作走 `BEGIN IMMEDIATE` 串行化
|
||
- comments 表 `comment_type` CHECK 约束区分 8 种类型
|
||
|
||
---
|
||
|
||
## 4. Daemon 核心架构
|
||
|
||
### 4.1 Tick 循环（30s）
|
||
|
||
```python
|
||
async def tick(project_id: str):
|
||
conn = get_connection(project_id)
|
||
try:
|
||
# 1. 逻辑健康自检（连续 N tick 无变更 → 告警）
|
||
health_check(conn)
|
||
|
||
# 2. 处理 Inbox JSONL（即时事件）
|
||
process_inbox(conn)
|
||
|
||
# 3. 扫描黑板状态
|
||
tasks = scan_tasks(conn)
|
||
|
||
# 4. 审查流水线处理
|
||
review_flow(conn, tasks)
|
||
|
||
# 5. 依赖推进（已完成任务解锁下游）
|
||
advance_dependencies(conn, tasks)
|
||
|
||
# 6. 反驳权进度检测（催促通知）
|
||
check_rebuttal_progress(conn)
|
||
|
||
# 7. Agent 调度
|
||
dispatch_pending(conn, tasks)
|
||
|
||
# 8. 一级蒸馏触发
|
||
check_distillation(conn)
|
||
|
||
finally:
|
||
conn.close()
|
||
```
|
||
|
||
**Tick + Inbox 双层事件架构**：
|
||
- Tick 30s 兜底扫描（Pull）
|
||
- Inbox JSONL 秒级推送加速（Push）
|
||
- Inbox 文件用 truncate（清空不删除），避免并发写入时文件不存在
|
||
|
||
### 4.2 Agent 调度判据（三级决策树）
|
||
|
||
详见 `topic3-challenge-review-proposal.md §5.4`。
|
||
|
||
```python
|
||
def dispatch(task, action_type, project_config):
|
||
registered_agents = project_config.get("agents", [])
|
||
|
||
# Level 1: 纯机械检查 → Daemon 直接执行
|
||
if action_type in ("L1_guardrail", "format_check", "file_exists_check"):
|
||
return execute_locally(task)
|
||
|
||
# Level 2: 有名字的角色 → Full Agent (Popen 非阻塞)
|
||
if task.assignee in registered_agents:
|
||
if action_type == "adjudication":
|
||
return spawn_full_agent(task.assignee, new_session=True)
|
||
return spawn_full_agent(task.assignee)
|
||
|
||
# Level 3: 无名字的一次性任务 → Subagent (sessions_spawn)
|
||
if DISPATCH_RULES.get(action_type) == "subagent":
|
||
return spawn_subagent(task_description=action_type)
|
||
|
||
# Level 4: 未知 action_type → 庞统裁决
|
||
return spawn_full_agent("pangtong-fujunshi", new_session=True)
|
||
```
|
||
|
||
**spawn 方式**：
|
||
- Full Agent：`subprocess.Popen`（非阻塞），不等返回，下次 tick 检查产出
|
||
- Subagent：`sessions_spawn`（Gateway API），等返回
|
||
|
||
### 4.3 ActiveAgentCounter（课题11）
|
||
|
||
```python
|
||
class ActiveAgentCounter:
|
||
"""异步计数器，控制并发"""
|
||
def __init__(self, max_global=5, max_per_agent=1):
|
||
self._global = asyncio.Semaphore(max_global)
|
||
self._per_agent = {} # agent_id → Semaphore(max_per_agent)
|
||
|
||
async def acquire(self, agent_id: str) -> bool:
|
||
if self._global.locked():
|
||
return False
|
||
agent_sem = self._per_agent.get(agent_id)
|
||
if agent_sem and agent_sem.locked():
|
||
return False
|
||
await self._global.acquire()
|
||
if agent_id not in self._per_agent:
|
||
self._per_agent[agent_id] = asyncio.Semaphore(self._max_per_agent)
|
||
await self._per_agent[agent_id].acquire()
|
||
return True
|
||
|
||
def release(self, agent_id: str):
|
||
self._per_agent[agent_id].release()
|
||
self._global.release()
|
||
```
|
||
|
||
### 4.4 build_bootstrap() 四层上下文拼装
|
||
|
||
详见 `topic4-decomposition-skill-proposal.md D4-7`。
|
||
|
||
```
|
||
L0 铁律层（~500 tokens） → Hook 注入，不占 bootstrap
|
||
L1 角色层（~2000 tokens） → SOUL.md / IDENTITY.md（Agent 自带）
|
||
L2 引擎注入层（~1500 tokens）→ prompt_templates 按 role 拼装
|
||
① 操作规范（executor.md / reviewer.md / planner.md）
|
||
② 项目背景（project_context.yaml）
|
||
③ 任务上下文（黑板数据）
|
||
④ 前序信息（depends_on 产出摘要）
|
||
⑤ Guardrail 规则（guardrails.yaml，仅执行者）
|
||
⑥ 审查协议（review_protocols/，仅审查者）
|
||
⑦ 经验注入（experiences 表按 tag 匹配）
|
||
L3 被动参考层（按需加载）→ Skill description 四要素
|
||
```
|
||
|
||
L2 按角色精确注入：执行者注入⑤⑥，审查者注入⑥，庞统注入⑥。
|
||
|
||
---
|
||
|
||
## 5. 审查流水线
|
||
|
||
### 5.1 分级审查
|
||
|
||
| 风险等级 | 流水线 | 方案审查 | 产出审查 | 模式 | max_rounds |
|
||
|---------|--------|---------|---------|------|-----------|
|
||
| **high** | 三阶段 | ✅ 对抗辩论 | ✅ 对抗辩论 + Guardrail | debate | 5 |
|
||
| **standard** | 二阶段 | ✅ 单审 | ✅ 单审 + Guardrail | single_reviewer | 3 |
|
||
| **low** | 一阶段 | ❌ | ⚡ Guardrail 自动 | auto | 0 |
|
||
| **research** | 一阶段 | ❌ | ✅ 庞统确认 | single_reviewer | 2 |
|
||
|
||
### 5.2 Guardrail 执行
|
||
|
||
```yaml
|
||
# config/guardrails.yaml 示例
|
||
task_types:
|
||
coding:
|
||
output_review:
|
||
required: true
|
||
layers:
|
||
L1: # Daemon 直接执行
|
||
- assert: "len(glob('tests/test_*.py')) > 0"
|
||
message: "缺少测试文件"
|
||
- assert: "import subprocess; subprocess.run(['python', '-m', 'py_compile', output_path], check=True)"
|
||
message: "Python 语法检查失败"
|
||
L2: # Subagent 执行
|
||
prompt: "检查代码是否遵循项目规范，重点关注：命名、异常处理、资源释放"
|
||
deploy:
|
||
output_review:
|
||
required: true
|
||
layers:
|
||
L1:
|
||
- assert: "os.path.exists('deploy_log.md')"
|
||
message: "缺少部署日志"
|
||
data:
|
||
output_review:
|
||
required: false # low 风险，Guardrail 自动
|
||
```
|
||
|
||
### 5.3 反驳权流控
|
||
|
||
审查者 verdict=needs_revision（有 critical/major）→ spawn 原执行者反驳 → 协商轮次 ≤ max_rounds → 不设超时，有催促通知 → 超轮次升级庞统。
|
||
|
||
详见 `topic3-challenge-review-proposal.md §5.3`。
|
||
|
||
### 5.4 评审详情 Schema
|
||
|
||
评审结果写入 `{task_id}/reviews/{review_id}.json`，包含：
|
||
- `issues[]`（status/severity/category/location+context/suggestion）
|
||
- `evidence[]`（file_content/command_output）
|
||
- `positives[]`、`meta`
|
||
- category 含：correctness/security/performance/style/scope_deviation/**architecture/robustness**
|
||
|
||
详见 `topic3-challenge-review-proposal.md §5.2`。
|
||
|
||
---
|
||
|
||
## 6. 经验沉淀
|
||
|
||
### 6.1 两级蒸馏
|
||
|
||
| 级别 | 触发时机 | 产出 | 存储 |
|
||
|------|---------|------|------|
|
||
| 一级（实时） | 任务完成后 | 经验条目（key findings/lessons/tags） | experiences 表 |
|
||
| 二级（周期） | 同 tag 积累 N 条 | Skill 草稿（draft→active→deprecated） | skills/ 目录 |
|
||
|
||
### 6.2 经验注入
|
||
|
||
build_bootstrap() 按 tag 检索 experiences 表，格式化后注入 L2 上下文。
|
||
|
||
详见 `topic6-experience-loop-proposal.md`。
|
||
|
||
---
|
||
|
||
## 7. API 设计
|
||
|
||
### 7.1 黑板 API
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/projects/{pid}/tasks` | 任务列表（支持过滤） |
|
||
| GET | `/api/projects/{pid}/tasks/{id}` | 任务详情 |
|
||
| POST | `/api/projects/{pid}/tasks` | 创建任务 |
|
||
| POST | `/api/projects/{pid}/tasks/{id}/claim` | 认领 |
|
||
| PATCH | `/api/projects/{pid}/tasks/{id}/status` | 更新状态 |
|
||
| POST | `/api/projects/{pid}/tasks/{id}/comments` | 添加评论 |
|
||
| POST | `/api/projects/{pid}/tasks/{id}/outputs` | 写入产出 |
|
||
| POST | `/api/projects/{pid}/tasks/{id}/decisions` | 记录决策 |
|
||
| POST | `/api/projects/{pid}/tasks/{id}/observations` | 添加观察 |
|
||
| POST | `/api/projects/{pid}/tasks/{id}/reviews` | 提交评审 |
|
||
|
||
### 7.2 Daemon 控制 API
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/api/daemon/tick` | 手动触发 tick |
|
||
| GET | `/api/daemon/status` | Daemon 状态 |
|
||
| GET | `/api/daemon/sessions` | 活跃 session |
|
||
|
||
### 7.3 SSE 推送
|
||
|
||
```
|
||
GET /api/events?project={pid}
|
||
→ SSE 流，事件类型：
|
||
task_created / task_status_changed / review_submitted / rebuttal_added
|
||
notification（4级：🔴🟡🟢🔵）
|
||
```
|
||
|
||
### 7.4 多项目 API
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/api/projects` | 项目列表 |
|
||
| POST | `/api/projects` | 创建项目 |
|
||
| GET | `/api/projects/{pid}` | 项目详情 |
|
||
| DELETE | `/api/projects/{pid}` | 归档项目（安全流程） |
|
||
|
||
---
|
||
|
||
## 8. Hook 系统
|
||
|
||
双重 Hook 架构：
|
||
|
||
| Hook | 所属 | 触发时机 | 用途 |
|
||
|------|------|---------|------|
|
||
| `agent_turn_prepare` | OpenClaw Plugin | Agent 接收消息前 | 注入铁律（L0） |
|
||
| `agent_turn_complete` | OpenClaw Plugin | Agent 完成后 | 触发 lint/test（工具链集成点） |
|
||
| `pre_task_claim` | moziplus HookRegistry | Agent claim 前 | 权限检查 |
|
||
| `post_output_write` | moziplus HookRegistry | 产出写入后 | 触发 Guardrail 检查 |
|
||
| `post_review_submit` | moziplus HookRegistry | 评审提交后 | 触发反驳权流程 |
|
||
|
||
---
|
||
|
||
## 9. 前端架构
|
||
|
||
### 9.1 技术选型
|
||
|
||
复用 v1.0 前端框架（React + Vite + TypeScript），重设计页面结构。
|
||
|
||
### 9.2 页面结构（5页）
|
||
|
||
| 页面 | 内容 | 来源 |
|
||
|------|------|------|
|
||
| **任务看板** | 任务卡片、Checkpoint 交互、状态流转 | 课题7+9 |
|
||
| **全局监控** | Agent 状态、系统健康、资源使用 | 课题9 |
|
||
| **产出档案** | 产出物预览/下载、评审详情 | 课题9 |
|
||
| **系统配置** | 项目管理、Agent 配置、Guardrail 编辑 | 课题9 |
|
||
| **AI Briefing** | 日报/周报自动生成 | 课题9 |
|
||
|
||
### 9.3 实时推送
|
||
|
||
SSE 端点 `/api/events`，前端 EventSource 监听。4 级推送（🔴🟡🟢🔵）。降级：SSE 不可用时 30s 轮询。
|
||
|
||
### 9.4 构建部署
|
||
|
||
```bash
|
||
cd src/frontend && npm run build
|
||
# 产物在 src/frontend/dist/
|
||
# FastAPI 直接托管静态文件（port 8083）
|
||
```
|
||
|
||
详见 `topic7-9-interaction-dashboard-proposal.md`。
|
||
|
||
---
|
||
|
||
## 10. 测试策略
|
||
|
||
### 10.1 单元测试
|
||
|
||
| 测试文件 | 覆盖 |
|
||
|---------|------|
|
||
| test_blackboard.py | operations 全函数（claim CAS、状态机、comment_type、review CRUD） |
|
||
| test_daemon_tick.py | tick 流程（Inbox 处理、依赖推进、反驳权进度检测） |
|
||
| test_dispatcher.py | 三级调度判据 + fallback |
|
||
| test_guardrail.py | L1 assert 执行 + L2 prompt 触发 |
|
||
| test_review_flow.py | 审查流水线（分级审查、反驳权、升级） |
|
||
| test_experience.py | 一级蒸馏 + tag 检索 |
|
||
| test_bootstrap.py | 四层上下文拼装（按 role 精确注入） |
|
||
| test_counter.py | ActiveAgentCounter 并发控制 |
|
||
|
||
### 10.2 集成测试
|
||
|
||
- 创建任务 → 调度执行 → Guardrail → 审查 → 反驳 → 完成 闭环
|
||
- 多项目并发：两个项目同时 tick，互不影响
|
||
- 竞态测试：两个 Agent 同时 claim + 同时写 inbox
|
||
|
||
### 10.3 测试数据库
|
||
|
||
per-project 测试用 `:memory:` SQLite。全局注册表测试用临时文件。
|
||
|
||
---
|
||
|
||
## 11. 实现顺序
|
||
|
||
| Phase | 内容 | 估计时间 |
|
||
|-------|------|---------|
|
||
| **P1** | 黑板 + Daemon + CLI + API + 多项目 | ~15h |
|
||
| **P2** | 审查流水线 + Guardrail + 反驳权 + build_bootstrap | ~12h |
|
||
| **P3** | 前端重设计 + SSE 推送 + AI Briefing | ~10h |
|
||
| **P4** | 经验沉淀 + Skill 进化 + 工具链集成 | ~8h |
|
||
|
||
---
|
||
|
||
## 12. 风险
|
||
|
||
| 风险 | 缓解 |
|
||
|------|------|
|
||
| per-project SQLite 并发 tick | WAL + busy_timeout + per-project asyncio.Lock |
|
||
| Agent spawn 子进程回收 | health.py 僵尸检测 + reclaim |
|
||
| Inbox JSONL 并发写入 | truncate（不删除），实测 200 并发 0 丢失 |
|
||
| 前端 v1→v2 迁移 | v1 Tab 全保留，渐进替换 |
|
||
| Daemon 逻辑死循环 | 连续 N tick（默认 20）无变更 → observation 告警 + 通知用户 |
|
||
| 反驳权无限协商 | max_rounds 兜底 + 超轮次升级庞统 |
|