diff --git a/docs/design/architecture-v3.0.md b/docs/design/architecture-v3.0.md new file mode 100644 index 0000000..801ba5c --- /dev/null +++ b/docs/design/architecture-v3.0.md @@ -0,0 +1,802 @@ +# 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 │ +│ ┌──────────────────────────────────────────────────┐ │ +│ │ 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 表字段（实际）**： + +```sql +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 --session-id `） +- 进程监控（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 五步）： +1. ✅ 读黑板（API + CLI） +2. ⚠️ 想自主决策 — 广播认领未完全启用 +3. ✅ 执行任务 +4. ✅ 写回黑板 +5. ⚠️ 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 指出的问题**： +1. ~~LLMDriver 已移除~~ ✅ +2. `_dispatch_pending` 绕过认领机制 — **仍存在** +3. 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） + +**实际流程**： +1. ✅ 产出物存在性检查（`_check_existence`） +2. ✅ 格式合规检查（`_check_format`） +3. ✅ 内容质量检查（`_check_quality`） +4. ✅ Guardrail 门控（`_determine_gate`） +5. ✅ 综合评分 + +**缺失**： +- ❌ 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`）： + +```python +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 |