Files

T

cfdaily 381a9f2647 auto-sync: 2026-05-28 00:23:03

2026-05-28 00:23:03 +08:00

33 KiB

Raw Blame History

AI Native DevOps Platform 架构设计 v3.0

版本: v3.0（PRD 3.0 对齐 + 代码现状回溯）基于: PRD-v3.0 + architecture-v2.6 + 实际代码作者: 庞统（副军师）🐦 日期: 2026-05-28 状态: 初稿准绳: PRD-v3.0.md 是唯一准绳，设计矛盾以它为准

变更历史

版本	日期	变更
v3.0	2026-05-28	基于 PRD-v3.0 + 代码现状，全面回溯。从 architecture-v2.6 继承并修正

实现状态标记

✅ 已实现 — 代码已落地
⚠️ 部分实现 — 有代码但缺功能
❌ 未实现 — 只有设计没有代码
🔀 矛盾 — 设计和代码/PRD不一致

1. 架构总览

1.1 系统定位

moziplus v2 是 AI Native 的多 Agent 协作 DevOps 平台。核心理念（PRD B1~B4）：

信念	PRD 编号	架构体现
B1: AI 参与每个决策层	PRD §2.1	Agent 自主认领、审查、裁决；Daemon 只投递不决策
B2: 共享意识空间	PRD §2.1	SQLite 黑板 + 全量事件 + @mention + Handoff
B3: 人机协同而非人机对抗	PRD §2.1	Checkpoint/escalated/waiting_human 三级人工介入
B4: 持续学习闭环	PRD §2.1	Experience 沉淀 + Skill 进化

1.2 系统架构图

┌─────────────────────────────────────────────────────────────────────┐
│                        用户层                                        │
│  ┌──────────┐  ┌──────────────┐  ┌──────────────┐                  │
│  │ 前端(React)│  │ OpenClaw CLI │  │ Mail Tab     │                  │
│  │ EdictBoard│  │ blackboard.py│  │ 三栏布局     │                  │
│  └─────┬─────┘  └──────┬───────┘  └──────┬───────┘                  │
│        │HTTP/SSE       │HTTP              │HTTP                       │
├────────┼───────────────┼──────────────────┼──────────────────────────┤
│        ▼               ▼                  ▼                          │
│  ┌──────────────────────────────────────────────────┐               │
│  │              API 层 (FastAPI, port 8083)          │               │
│  │  blackboard_routes / mail_routes / project_routes│               │
│  │  daemon_routes / sse_routes / checkpoint_routes   │               │
│  └──────────────────────┬───────────────────────────┘               │
│                         │SQLite                                      │
├─────────────────────────┼───────────────────────────────────────────┤
│                         ▼                                           │
│  ┌──────────────────────────────────────────────────┐               │
│  │              Blackboard 层                        │               │
│  │  per-project blackboard.db (SQLite WAL)           │               │
│  │  tasks / comments / outputs / decisions /          │               │
│  │  observations / events / reviews / experiences /   │               │
│  │  agents / task_attempts / routing_decisions /      │               │
│  │  checkpoints                                       │               │
│  └──────────────────────┬───────────────────────────┘               │
│                         │                                           │
├─────────────────────────┼───────────────────────────────────────────┤
│                         ▼                                           │
│  ┌──────────────────────────────────────────────────┐               │
│  │              Daemon 层 (PM2: sanguo-moziplus-v2)  │               │
│  │                                                    │               │
│  │  ┌─────────┐  ┌───────────┐  ┌──────────┐        │               │
│  │  │ Ticker  │  │ Dispatcher│  │ Spawner  │        │               │
│  │  │ 30s tick│  │ 任务调度  │  │ 进程管理 │        │               │
│  │  └─────────┘  └───────────┘  └──────────┘        │               │
│  │  ┌─────────┐  ┌───────────┐  ┌──────────┐        │               │
│  │  │ Router  │  │ Counter   │  │ Inbox    │        │               │
│  │  │ 路由    │  │ 并发控制  │  │ JSONL事件│        │               │
│  │  └─────────┘  └───────────┘  └──────────┘        │               │
│  │  ┌──────────────┐  ┌──────────┐  ┌────────┐      │               │
│  │  │ GuardrailEng │  │ ReviewPipe│  │ Health │      │               │
│  │  │ 安全红线     │  │ 产出验证 │  │ 僵尸检测│      │               │
│  │  └──────────────┘  └──────────┘  └────────┘      │               │
│  │  ┌──────────────┐  ┌──────────┐  ┌────────┐      │               │
│  │  │ BootstrapBld │  │ ExpStore │  │ SkillReg│      │               │
│  │  │ 上下文构建   │  │ 经验沉淀 │  │ 技能注册│      │               │
│  │  └──────────────┘  └──────────┘  └────────┘      │               │
│  │  ┌──────────────┐                                  │               │
│  │  │ SSEBroker   │                                  │               │
│  │  │ 实时推送    │                                  │               │
│  │  └──────────────┘                                  │               │
│  └──────────────────────────────────────────────────┘               │
│                         │                                           │
│                         ▼ openclaw agent --agent <id>                │
│  ┌──────────────────────────────────────────────────┐               │
│  │              Agent 层 (OpenClaw Gateway)          │               │
│  │  张飞/关羽/赵云/姜维/司马懿/庞统                   │               │
│  │  每个 Agent 独立 session，通过 API 读写黑板        │               │
│  └──────────────────────────────────────────────────┘               │
└─────────────────────────────────────────────────────────────────────┘

2. 数据模型

2.1 实际 DB Schema（代码现状）

✅ 已实现 — 14 张表

表名	代码位置	用途
`tasks`	db.py:239	核心任务表
`comments`	db.py:274	评论/讨论/@mention
`outputs`	db.py:288	Agent 产出物
`decisions`	db.py:303	决策记录
`observations`	db.py:315	风险/异常观察
`events`	db.py:327	事件日志
`agents`	db.py:339	Agent 注册信息
`task_attempts`	db.py:349	任务尝试记录
`reviews`	db.py:365	评审结果
`experiences`	db.py:384	经验沉淀
`experience_tags`	db.py:402	经验标签
`routing_decisions`	db.py:410	路由决策记录
`checkpoints`	db.py:117,433	Checkpoint 数据（两处定义）
`tasks_v28`	db.py:70	v2.8 迁移临时表
`registry` (全局)	registry.py	Project 注册表（独立 DB）

tasks 表字段（实际）：

id, title, description, status, assignee, assigned_by,
depends_on, parent_task, priority, task_type,
created_at, updated_at, claimed_at, started_at, completed_at,
deadline, retry_count, max_retries, must_haves, risk_level,
estimated_duration_minutes, escalated,  -- ⚠️ 布尔字段，已被 escalated 状态取代
current_agent, previous_agent, next_capability,  -- v2.6.1 路由扩展
stage, stages_json,  -- v2.7 SubTask
resumed_from,  -- v3.1 暂停恢复
archived, archived_at  -- v2.8 归档（models.py 有，db.py DDL 无）

状态枚举（实际）：

pending, claimed, working, review, paused, escalated,
waiting_human, done, failed, blocked, cancelled

2.2 设计差异

#	差异	PRD/设计	代码实际	标记
D1	archived 字段	v2.8 设计要求	models.py 有，db.py CREATE TABLE 无（需迁移脚本添加）	⚠️ 部分
D2	tasks_v28 临时表	不应存在于正式 schema	db.py:70 有 CREATE TABLE tasks_v28	🔀 遗留
D3	checkpoints 表	两处定义	db.py:117 和 db.py:433 重复定义	⚠️ 冗余
D4	verification_commands	architecture-v2.6 §15.1 借鉴1	tasks 表无此字段	❌ 未实现
D5	max_ticks	architecture-v2.6 §15.1 借鉴3 Runaway Guard	tasks 表无此字段	❌ 未实现
D6	scope_declaration	architecture-v2.6 §9.3 方案审查	decisions 表可承载但无专门 schema	⚠️ 部分
D7	handoff schema	architecture-v2.6 §5.1	comments 表无 handoff 类型校验	⚠️ 部分
D8	parent_task 聚合	v2.7 设计 §2.2	ticker.py _refresh_parent_statuses 已实现	✅

2.3 Project Registry

✅ 已实现 — ProjectRegistry（registry.py）

独立 registry.db（全局，非 per-project）
自动扫描 ~/.openclaw/sanguo_projects/sanguo_*
CRUD + archive + discover + migrate_from_yaml

3. Daemon 设计

3.1 Ticker ✅ 已实现

文件: ticker.py（40399 bytes）

核心职责：

30s 周期 tick
扫描任务状态 → 依赖推进 → 超时检测 → 调度 pending → 调度 review
父 Task 状态聚合（_refresh_parent_statuses）
广播认领（_build_claim_prompt）
僵尸/超时处理（claimed 5min → pending，working 30min → failed）
Mail 检查回复（_mail_check_reply）

设计差异：

#	设计	代码实际	标记
T1	Tick 30s + Inbox JSONL 加速	只实现 Tick，Inbox Watcher 已实现但未与 Ticker 集成加速	⚠️
T2	连续 N tick 无变更告警	`_check_timeouts` 有但无全局逻辑健康自检	⚠️
T3	Shadow Checkpoint（git commit）	无	❌
T4	暂停任务不参与调度/聚合	已实现（paused 跳过）	✅

3.2 Dispatcher ⚠️ 部分实现

文件: dispatcher.py（27278 bytes）

核心职责：

任务调度决策（decide() → 分配 agent + spawn message）
支持 claim / retry / review / delegate / broadcast 五种模式
Mail 任务特殊处理（auto_working / auto_complete）

设计差异：

#	设计	代码实际	标记
D1	"Agent 自主认领"	`_dispatch_pending` 仍走 Router 决定 → 强制 claimed → spawn	🔀 v3.0-router-refactor.md 指出问题
D2	广播认领路径	`_build_claim_prompt` 已存在但未被主路径调用	⚠️
D3	确定性交接路径	next_capability / retry 已实现	✅
D4	Mail inform 自动完成	`_mail_auto_complete` 已实现	✅

3.3 Spawner ✅ 已实现

文件: spawner.py（52812 bytes，最大文件）

核心职责：

spawn Full Agent（openclaw agent --agent <id> --session-id <uuid>）
进程监控（stdout 解析 + 超时处理 + 退出分类）
Session 注册/清理
Counter 集成（并发控制）
假死复活术（_revive_session）
spawn 前检查（_check_session_state）
产出写入黑板（_record_attempt）

设计差异：

#	设计	代码实际	标记
S1	Session 归档到 artifacts/{task}/archive	`_register_session` + `cleanup_session` 但归档逻辑简化	⚠️
S2	per-task 重试上限	retry_count + max_retries 已实现	✅
S3	on_complete 回调	已实现（lambda 释放 counter）	✅
S4	stdout JSON 解析	`_parse_stdout_json` 已实现	✅
S5	进程超时分类	`_classify_outcome` 已实现	✅

3.4 Router ⚠️ 部分实现

文件: router.py（7240 bytes）

核心职责：

Agent 路由决策（route() → 返回 agent_id + mode）
能力匹配（_resolve_by_capability）
fallback 到庞统

关键问题（v3.0-router-refactor.md 已指出）：

~~LLMDriver 类用独立 OpenAI 客户端直连 API~~ 已移除（config 注释 "v3.0: routing 配置已移除"）
仍使用 _legacy_decide（Router 决定分配）而非广播认领

3.5 Counter ✅ 已实现

文件: counter.py（5668 bytes）

核心职责：

三层并发控制（global / per-agent / per-session-key）
冷却期（is_cooling_down / set_cooldown）
信号量实现

配置：max_global=5, max_per_session=1, max_concurrent_sessions=3

3.6 Inbox ✅ 已实现

文件: inbox.py（10696 bytes）

核心职责：

JSONL 文件事件监听（InboxWatcher）
事件类型：agent_claim / agent_done / agent_spawned / output_written 等
异步回调（default_inbox_callback）

设计差异：

#	设计	代码实际	标记
I1	Inbox 加速 Ticker（即时 mini-tick）	InboxWatcher 已实现但未与 Ticker tick 集成	⚠️

3.7 Health ✅ 已实现

文件: health.py（9590 bytes）

核心职责：

僵尸任务检测（zombie_threshold=20）
告警写入黑板（_write_alert）
自动修复（_write_resolution）

3.8 SSE ✅ 已实现

文件: sse.py（9205 bytes）

核心职责：

SSE 事件推送（SSEBroker）
pub/sub 模式
前端 EventSource 对接

4. Agent 交互设计

4.1 三层执行模型 ✅ 已实现

层级	方式	代码	用途
L1 Daemon 直接操作	SQLite/文件	ticker/dispatcher	状态更新、机械验证
L2 spawn sub	隔离 session	spawner._spawn_sub	轻量检查
L3 run agent	完整参与者	spawner.spawn_full_agent	编码/审查/策略

4.2 Agent 工具集 ✅ 已实现

CLI（blackboard.py）：read / create / claim / output / comment / decide / observe / review

API（blackboard_routes.py）：完整 CRUD + claim + status + archive + events + summary

4.3 Agent 交互流程 ⚠️ 部分实现

设计（architecture-v2.6 §5.1 五步）：

✅ 读黑板（API + CLI）
⚠️ 想自主决策 — 广播认领未完全启用
✅ 执行任务
✅ 写回黑板
⚠️ Handoff Comment — comments 表可承载但无 schema 校验

4.4 Handoff Comment ❌ 未实现

设计：结构化交接评论，CLI 校验 schemas/handoff.schema.json。

代码实际：schemas/ 目录不存在。comments 表有 comment_type 字段但无 handoff 专用校验。

5. 路由与调度

5.1 当前实现 ⚠️ 与设计有差距

v3.0-router-refactor.md 指出的问题：

~~LLMDriver 已移除~~ ✅
_dispatch_pending 绕过认领机制 — 仍存在
Daemon 替 Agent 做决策 — 仍存在

当前流程：

pending → Router 决定 agent → 强制 claimed + spawn → Agent 被动执行

设计目标流程（v3.0-router-refactor.md）：

pending → 确定性路径?(retry/handoff/assignee) → 直接 spawn
       → 否 → 广播认领 → Agent 自主 claim

5.2 调度模式

模式	设计	代码	标记
确定性交接（retry/handoff）	✅ 设计	✅ 实现	✅
广播认领	✅ 设计	⚠️ `_build_claim_prompt` 存在但未被主路径调用	⚠️
庞统兜底（delegate）	✅ 设计	✅ 实现	✅
无人认领→escalated	✅ 设计	✅ retry_count >= 3 逻辑	✅
用户介入链路	✅ 设计	✅ SSE + 前端按钮	✅

6. 质量门控/审查体系

6.1 分级审查流水线 ⚠️ 部分实现

设计（architecture-v2.6 §9.2）：

风险等级	流水线	实际
high	三阶段（方案+Guardrail+产出）	❌ 无方案审查，ReviewPipeline 存在但简化
standard	二阶段（方案+产出）	⚠️ ReviewPipeline 存在，但无方案审查
low	一阶段（Guardrail 自动）	⚠️ ReviewPipeline 简化版
research	一阶段（庞统确认）	❌ 无专门处理

6.2 Review Pipeline ✅ 已实现（简化版）

文件: review.py（10335 bytes）

实际流程：

✅ 产出物存在性检查（_check_existence）
✅ 格式合规检查（_check_format）
✅ 内容质量检查（_check_quality）
✅ Guardrail 门控（_determine_gate）
✅ 综合评分

缺失：

❌ Investigation Protocol（五阶段）
❌ 多视角矩阵
❌ 对抗性指令

6.3 Rebuttal Manager ✅ 已实现

文件: review.py RebuttalManager

submit_rebuttal() — 反驳提交
审查 → 反驳 → 再审查流转

6.4 审查协议注册表 ❌ 未实现

设计（architecture-v2.6 §9.4）：

review_protocols/ 目录（plan_review.yaml / output_review.yaml 等）
四维定义（审查维度/方法/多视角/对抗性指令）

代码实际：review_protocols/ 目录不存在。

6.5 反驳权 ⚠️ 部分实现

设计：分级触发（critical/major → spawn 反驳；minor → 自然修改；approved → 跳过）。

代码实际：RebuttalManager 存在但跳过条件/触发条件的分级逻辑未完整。

7. 上下文管理

7.1 Bootstrap Builder ✅ 已实现

文件: bootstrap.py（7631 bytes）

实际 L2 层结构：

层	设计	代码	标记
L2a 操作规范	role template	`_load_template(f"{role}.md")`	⚠️ prompt_templates 目录不存在
L2b 项目背景	project_context	`_format_project_context`	✅
L2c 任务上下文	task_context	`_format_task_context`	✅
L2d 前序产出	depends_on outputs	`_format_depends_on`	✅
L2e Guardrail 规则	guardrails.yaml	代码有传入参数但调用方未注入	⚠️
L2f 审查协议	review_protocols/	代码有传入参数但目录不存在	❌
L2g 经验注入	experiences 表	`_format_experiences`	⚠️ 未接入自动沉淀
L3 Skill descriptions	skills/*.json	`_format_skills`	⚠️ skills 目录为空

7.2 Context 预算

设计（architecture-v2.6 §11.3）：总计 35K~60K tokens。

代码实际：max_tokens=4096（远小于设计预算）。

7.3 prompt_templates 目录 ❌ 未实现

设计：每个 role 一个模板（executor.md / reviewer.md / planner.md / pangtong.md）。

代码实际：prompt_templates/ 目录不存在。_load_template 返回 None。

7.4 Agent spawn 消息

实际消息构建：spawner.build_spawn_message() — 拼装黑板 API 信息 + Mail prompt。

缺失：未使用 BootstrapBuilder.build() 的完整四层构建。

8. 前端

8.1 已实现组件 ✅

组件	文件	状态
EdictBoard（任务看板）	EdictBoard.tsx	✅
TaskModal（任务详情）	TaskModal.tsx	✅
MailPanel（飞鸽传书）	MailPanel.tsx	✅
CourtCeremony（朝堂议政）	CourtCeremony.tsx	✅
MonitorPanel（监控面板）	MonitorPanel.tsx	✅
MorningPanel（晨会）	MorningPanel.tsx	✅
NotificationCenter	NotificationCenter.tsx	✅
GlobalSearch	GlobalSearch.tsx	✅
Toaster	Toaster.tsx	✅
SettingsPanel	SettingsPanel.tsx	✅
SessionsPanel	SessionsPanel.tsx	✅
SkillsConfig	SkillsConfig.tsx	✅
ConfirmDialog	ConfirmDialog.tsx	✅

8.2 已实现但代码已回滚的组件

组件	文件	状态
ArtifactPanel	ArtifactPanel.tsx	⚠️ 文件存在但 M3 未集成
CheckpointPanel	CheckpointPanel.tsx	⚠️ 文件存在但 M3 未集成

8.3 前端架构

React + TypeScript + Vite
Zustand 状态管理（store.ts）
Tailwind CSS
SSE 实时推送

8.4 v2.8 设计要求 vs 实际

设计要求	实际	标记
筛选栏两行布局	部分实现	⚠️
卡片快捷按钮	已实现	✅
项目下拉移入筛选栏	已实现	✅
状态筛选全覆盖（11 状态）	已实现	✅
归档机制	前端有，后端 DDL 缺字段	⚠️

9. Mail 系统

9.1 Mail Tab ✅ 已实现

后端（mail_routes.py）：

GET "" — 列表（支持 from/status/unread 过滤）
GET /agents/list — Agent 列表
GET /summary — 未读/总数
GET /{mail_id} — 详情
POST "" — 发送
PATCH /{mail_id} — 更新（标记已读等）

前端（MailPanel.tsx）：三栏布局。

9.2 Mail 设计模式

Mail = _mail 虚拟 Project
每封 Mail = 一个 Task（must_haves JSON 存 from/type/is_read/conversation_id）
inform 类型自动标记 done

9.3 已知问题

问题	标记
list_mail from 过滤在内存层（量大时性能）	⚠️ OBS-22
send_mail from 字段冗余（assigned_by + must_haves.from）	⚠️ OBS-25
polling 不刷新 Mail	⚠️ OBS-26
inform 类型邮件超时重试	⚠️ MEMORY 记录

10. 经验沉淀

10.1 Experience Store ✅ 已实现

文件: experience.py（9590 bytes）

功能：

✅ CRUD（add / get / list_all / search / delete / count）
✅ 分类（ExperienceCategory）
✅ 标签（experience_tags 表）
✅ JSON 文件持久化

10.2 经验闭环 ⚠️ 部分实现

设计（课题6 DISCOVER→DISTILL→APPLY→IMPROVE）：

阶段	设计	代码	标记
DISCOVER	任务完成后自动提取经验	❌ 无自动触发	❌
DISTILL	经验蒸馏（阈值触发）	⚠️ Store 存在但无蒸馏逻辑	❌
APPLY	Bootstrap 注入经验	✅ `_format_experiences`	⚠️
IMPROVE	Skill 升级	❌	❌

11. Guardrail 体系

11.1 Guardrail Engine ✅ 已实现

文件: guardrails.py（5165 bytes）+ guardrails.yaml

六条安全红线：

规则	严重级别	动作	标记
实盘交易拦截	critical	block_and_notify	✅
数据删除拦截	critical	block_and_notify	✅
系统配置变更拦截	critical	block_and_notify	✅
大额 Token 消耗	warning	pause_and_notify	✅
Agent 不受控行为	critical	terminate_and_escalate	⚠️ TODO
连续失败	warning	pause_and_escalate	✅

代码实现：

✅ check_task() — 任务级模式匹配
✅ check_token_usage() — Token 阈值
✅ check_consecutive_failure() — 连续失败

11.2 设计差异

设计	代码	标记
L1 机械+脚本验证	只有基础存在性检查，无 verification_commands	⚠️
L2 AI 轻量检查	无 subagent 检查	❌
L3 安全红线	GuardrailEngine 已实现	✅
review_protocols/ YAML	目录不存在	❌
输出型 guardrails（per task_type）	guardrails.yaml 只有全局红线	⚠️

12. 事件驱动

12.1 Inbox JSONL ✅ 已实现

文件: inbox.py

✅ 文件监听 + JSONL 格式
✅ 多事件类型
✅ 异步回调

12.2 事件类型 ✅ 已实现

events 表记录所有状态变更。

SSE 推送实时通知前端。

12.3 设计 vs 实际

设计	实际	标记
Inbox 加速 Ticker（mini-tick）	InboxWatcher 运行但未与 Ticker 集成	⚠️
启动全量扫描	Ticker 首次 tick 扫描所有任务	✅
NODE_AFTER_EXECUTE Hook	不存在 Hook 机制	❌
Shadow Checkpoint Hook	无	❌

13. 多项目支持

13.1 Project Registry ✅ 已实现

✅ 自动扫描 sanguo_* 目录
✅ per-project blackboard.db
✅ registry.db 全局索引
✅ CRUD + archive + discover

13.2 设计差异

设计（课题11）	实际	标记
per-project 线程并发	Ticker 串行 tick 所有 project	❌
全局 LLM 信号量	Counter 有全局限制但无信号量	⚠️
per-agent 互斥锁	Counter per-agent 限制	✅
跨项目 bootstrap 注入	build_for_task 不支持跨项目	❌
Worktree 物理隔离	无	❌

14. 状态机

14.1 完整状态定义 ✅ 已实现

11 个状态：pending, claimed, working, review, paused, escalated, waiting_human, done, failed, blocked, cancelled

14.2 状态转换矩阵

代码实际（db.py VALID_TRANSITIONS）：

VALID_TRANSITIONS = {
    "pending":       {"claimed", "cancelled"},
    "claimed":       {"working", "paused", "pending", "cancelled"},
    "working":       {"review", "blocked", "failed", "paused", "escalated", "waiting_human", "cancelled"},
    "paused":        {"working", "cancelled"},
    "review":        {"done", "pending", "failed", "escalated", "waiting_human", "cancelled"},
    "blocked":       {"pending", "escalated", "cancelled"},
    "failed":        {"pending", "escalated", "cancelled"},
    "escalated":     {"working", "pending", "cancelled"},
    "waiting_human": {"working", "done", "cancelled"},
    "done":          set(),  # 终态
    "cancelled":     set(),  # 终态
}

14.3 差异

设计（v3.0-router-refactor §5.6）	代码实际	标记
cancelled 可重启动(→pending)	cancelled 是终态，无出口	🔀
review 可暂停	review 转换无 paused	⚠️
paused 恢复到暂停前状态	`resumed_from` 字段存在	⚠️

15. 待实现项汇总（原则 2/3）

15.1 原则 2：PRD ✅ + 代码 ❌ + 设计 ❌

#	PRD 条目	说明
P2-1	PRD §10.1 六条红线之"Agent 不受控行为"	guardrails.yaml 有定义但代码 TODO
P2-2	PRD B4 持续学习闭环	经验沉淀闭环四阶段只实现存储

15.2 原则 3：设计 ✅ + PRD ✅ + 代码 ❌

#	设计文档	功能	来源
P3-1	v3.0-router-refactor	广播认领路径替代 Daemon 决策	§3
P3-2	architecture-v2.6 §9.4	审查协议注册表（review_protocols/）	§9.4
P3-3	architecture-v2.6 §15.1	Verification Commands（L1 脚本验证）	借鉴1
P3-4	architecture-v2.6 §15.1	Runaway Guard（max_ticks）	借鉴3
P3-5	architecture-v2.6 §15.1	Shadow Checkpoint（产出 git commit）	借鉴5
P3-6	architecture-v2.6 §9.9	对抗辩论模式（high 风险任务）	§9.10
P3-7	v2.7-subtask-model	跨项目 bootstrap 注入	§2.4
P3-8	architecture-v2.6 §11	SkillRouter 检索	§12 待推进
P3-9	architecture-v2.6 §12	课题11 多项目线程并发	topic11
P3-10	v2.8-executor-prompt-design	prompt_templates 四层注入	全文
P3-11	v2.8-state-enhancement	Checkpoint 三种类型	§4
P3-12	v2.8-state-enhancement	Artifact 成果物面板	§5
P3-13	architecture-v2.6 §5.1	Handoff Comment schema 校验	§5.1
P3-14	architecture-v2.6 §9.4	Investigation Protocol 五阶段	§9.4

16. PRD 新增建议（原则 4/5）

16.1 原则 4：调研有但 PRD 没有

#	调研来源	功能	建议
R4-1	pipeline-architecture-research.md	Pipeline 多执行模式（parallel/loop/saga/interactive）	PRD 3.1 新增 Pipeline 执行模式条目
R4-2	spawner-monitor-design.md	spawn 前检查 + 假死复活术	PRD 3.1 补充进程管理策略
R4-3	counter-lifecycle-fix v2.1	per (agent, session) 粒度三层控制	PRD 3.1 补充并发控制模型

16.2 原则 5：代码有但 PRD/设计没有

#	代码位置	功能	判断
G5-1	mail_routes.py	Mail 系统（PRD §2.6 有"通信"但无 Mail 专属条目）	PRD 3.1 新增 Mail 条目
G5-2	sse.py	SSE 实时推送	设计有（topic9），PRD 未明确
G5-3	checkpoint_routes.py	Checkpoint API 路由	设计有（M3），PRD 未明确
G5-4	task_attempts 表	任务尝试记录	设计无专门条目，补充 PRD

17. 设计矛盾记录（原则 6）

6.1 广播认领 vs 强制分配

PRD B1："AI 参与每个决策层" → Agent 自主认领
v3.0-router-refactor：明确指出 _dispatch_pending 违背"Agent 决策"原则
代码实际：仍走 Router 决定 → 强制 claimed
结论：以 PRD 为准，v3.0 需实施广播认领

6.2 escalated 字段 vs 状态

v2.8-state-enhancement：escalated 应为独立状态，废弃布尔字段
代码实际：tasks 表有 escalated INTEGER DEFAULT 0（布尔）+ status='escalated'（状态）共存
结论：以 v2.8 设计为准，布尔字段做向后兼容

6.3 Bootstrap 4096 vs 设计预算 35K~60K

设计（§11.3）：上下文预算 35K~60K tokens
代码实际：max_tokens=4096
结论：4096 偏小，需调大。但实际 BootstrapBuilder 未被主路径调用，差距暂无影响

6.4 cancelled 终态 vs 可重启

v3.0-router-refactor §5.6：cancelled 可重启动（→pending）
代码实际：cancelled 是终态（set()）
结论：需确认 PRD 立场。当前代码 cancelled 不可逆

6.5 Mail 完全退役 vs Mail Tab 存在

architecture-v2.6 §8："Sanguo Mail: 退役"
代码实际：Mail Tab 完整实现（mail_routes.py + MailPanel.tsx）
结论：Mail 在 v2.7 后重新引入为"飞鸽传书"功能，与 v2.6 的"退役"不矛盾（v2.6 指的是旧版 Sanguo Mail 服务，新版是黑板内的 Mail Tab）

18. 技术选型

需求	方案	来源
共享状态	SQLite WAL + per-project DB	Hermes / Network-AI
事件驱动	Tick 30s + Inbox JSONL	open-multi-agent
上下文传递	L0~L3 四层注入	Claude Code / GSD
进程管理	openclaw agent + subprocess.Popen	OpenClaw 原生
并发控制	Counter 三层信号量	自研
前端	React + TypeScript + Vite + Tailwind + Zustand	v1.0 技术栈
实时推送	SSE (EventSource)	v2.0 新增
配置	YAML (default.yaml + guardrails.yaml)	简单可靠
安全红线	GuardrailEngine + YAML 规则	PRD §10.1

19. 代码规模统计

模块	文件数	总行数（约）
daemon/	14	~2500
blackboard/	5	~1400
api/	6	~800
cli/	2	~500
frontend/src/	~28	~5000
config/	2	~120
总计	~57	~10320

20. 关键决策记录

决策	结论	来源
Card 层去留	回滚，用 Task 自引用	v2.7-subtask-model
SubTask 表	不建，复用 parent_task	v2.7-subtask-model
路由方式	广播认领（待实施）	v3.0-router-refactor
LLMDriver	已移除	v3.0-router-refactor
Mail	重新引入为 Tab	v2.7-subtask-model
Checkpoint	设计完成，代码回滚待重新实施	v2.8-state-enhancement
Bootstrap	四层构建器存在但未接入主路径	v2.8-executor-prompt-design

33 KiB Raw Blame History Unescape Escape

AI Native DevOps Platform 架构设计 v3.0

变更历史

实现状态标记

1. 架构总览

1.1 系统定位

1.2 系统架构图

2. 数据模型

2.1 实际 DB Schema（代码现状）

2.2 设计差异

2.3 Project Registry

3. Daemon 设计

3.1 Ticker ✅ 已实现

3.2 Dispatcher ⚠️ 部分实现

3.3 Spawner ✅ 已实现

3.4 Router ⚠️ 部分实现

3.5 Counter ✅ 已实现

3.6 Inbox ✅ 已实现

3.7 Health ✅ 已实现

3.8 SSE ✅ 已实现

4. Agent 交互设计

4.1 三层执行模型 ✅ 已实现

4.2 Agent 工具集 ✅ 已实现

4.3 Agent 交互流程 ⚠️ 部分实现

4.4 Handoff Comment ❌ 未实现

5. 路由与调度

5.1 当前实现 ⚠️ 与设计有差距

5.2 调度模式

6. 质量门控/审查体系

6.1 分级审查流水线 ⚠️ 部分实现

6.2 Review Pipeline ✅ 已实现（简化版）

6.3 Rebuttal Manager ✅ 已实现

6.4 审查协议注册表 ❌ 未实现

6.5 反驳权 ⚠️ 部分实现

7. 上下文管理

7.1 Bootstrap Builder ✅ 已实现

7.2 Context 预算

7.3 prompt_templates 目录 ❌ 未实现

7.4 Agent spawn 消息

8. 前端

8.1 已实现组件 ✅

8.2 已实现但代码已回滚的组件

8.3 前端架构

8.4 v2.8 设计要求 vs 实际

9. Mail 系统

9.1 Mail Tab ✅ 已实现

9.2 Mail 设计模式

9.3 已知问题

10. 经验沉淀

10.1 Experience Store ✅ 已实现

10.2 经验闭环 ⚠️ 部分实现

11. Guardrail 体系

11.1 Guardrail Engine ✅ 已实现

11.2 设计差异

12. 事件驱动

12.1 Inbox JSONL ✅ 已实现

12.2 事件类型 ✅ 已实现

12.3 设计 vs 实际

13. 多项目支持

13.1 Project Registry ✅ 已实现

13.2 设计差异

14. 状态机

14.1 完整状态定义 ✅ 已实现

14.2 状态转换矩阵

14.3 差异

15. 待实现项汇总（原则 2/3）

15.1 原则 2：PRD ✅ + 代码 ❌ + 设计 ❌

15.2 原则 3：设计 ✅ + PRD ✅ + 代码 ❌

16. PRD 新增建议（原则 4/5）

16.1 原则 4：调研有但 PRD 没有

16.2 原则 5：代码有但 PRD/设计没有

17. 设计矛盾记录（原则 6）

6.1 广播认领 vs 强制分配

6.2 escalated 字段 vs 状态

6.3 Bootstrap 4096 vs 设计预算 35K~60K

6.4 cancelled 终态 vs 可重启

6.5 Mail 完全退役 vs Mail Tab 存在

18. 技术选型

19. 代码规模统计

20. 关键决策记录

33 KiB

Raw Blame History