AirCoding/AirPlan/docs/architecture/opus4.8系统详细设计审查复查.md

# Opus 4.8 系统详细设计与 UML 类图全量审查复查

Date: 2026-06-01
Reviewer: Claude Opus 4.8 (independent full-scope re-audit)
Scope: 全量复查 — 覆盖性 + 内在一致性 + 基线遵守 + 架构合理性 + 内在冲突
Target commit: `af99aed`（R 系列回归修复后）
Inputs:
- 详细设计：`system-detailed-design.md`（2290 行，23 章节，含 §22 8 张 Mermaid 类图）
- 冻结基线：`interface-contracts-v1.md`、`event-registry-v1.md`、`db-schema-v1.md`、
  `runtime-semantics-v1.md`、`scheduler-state-machine-v1.md`、`main-agent-state-machine.md`、
  `prompt-layering-v1.md`、`scope-escalation-v1.md`、`security-model-v1.md`、`tool-registry-v1.md`、
  `capability-trust-v1.md`、`artifact-naming-v1.md`、`error-taxonomy-v1.md`、`baselineV1.md`
- 冻结概要设计：`system-overview-design.md`
- 此前审查：DeepSeek / MIMO 2.5 Pro / GPT-5.5 Pro / Opus 4.8(R4) / Opus 4.7(R5 回归)

---

## 1. 审查方法

本次为**独立全量复查**，不预设此前 5 轮审查已经完备。从零重建以下证据链：

1. **逐行通读 DD 全文**（§0-§23，2290 行）
2. **枚举式覆盖核对**：用脚本从基线提取契约接口名 / 事件名 / DB 表名 / 状态机，再与 DD 逐一比对（`comm -23` / `comm -13` 差集法）
3. **基线遵守抽样核验**：对 DD 中所有 `Class.method()` 形式的引用，回查契约是否真实存在该方法（这正是 R5 发现 `current_profile()` 越界的同类问题，本次扩大到全部点名方法）
4. **架构合理性**：依赖方向、职责分离、事件流时序、跨 DB outbox、FK-off 不变式
5. **UML 逐张审查**：8 张类图的语法、类数、边与正文一致性
6. **内在冲突**：同一概念跨章节是否自洽

---

## 2. 总览结论

| 维度 | 状态 |
|---|---|
| 契约覆盖 | ✅ 100%（23 个契约章节全部映射） |
| 事件覆盖 | ✅ 100%（55 durable + 7 ephemeral，含聚合写法） |
| DB Schema 覆盖 | ✅ 100%（16 张主表 + 2 项目级 DB，schema_meta 归 MigrationRunner） |
| 状态机覆盖 | ✅ 100%（main / scheduler / task / agent / workspace / capability 共 6 个） |
| PromptLayer L0-L9 覆盖 | ✅ 100% |
| 10 条禁止边 | ✅ 100% 显式继承 |
| UML 类图 | ✅ 8/8 存在且语法可解析 |
| R 系列(R1-01~R2-02) 回归修复 | ✅ 5/5 已闭合（本次复验） |
| 架构合理性 | ✅ 无循环依赖，职责分离清晰 |
| **新增 P0** | **0** |
| **新增 P1** | **0** |
| **新增 P2** | **4**（F1/F5 契约方法越界，F2/F3 类图欠完整） |
| 综合判定 | **CONDITIONAL PASS** — 4 项 P2 不阻断实现，建议合并修复 |

---

## 3. 覆盖性矩阵

### 3.1 契约覆盖（interface-contracts-v1 → DD）

`interface-contracts-v1.md` 共 23 个章节（§2-§23），DD §21.1 逐一映射，复验全部命中：

| 契约章节 | DD 章节 | 复验 |
|---|---|---|
| §2-§4 原语 / 错误 / 实体引用 | §3、§18.1 | ✓ |
| §6 事务存储 | §4、§18.2 | ✓ |
| §7 Event Bus/Store/Ingestor | §5 | ✓ 三接口签名逐字一致 |
| §8 项目/会话 | §6 | ✓ |
| §9 Task/Scheduler | §7 | ✓ |
| §10-§11 Worker/IPC/Result | §8 | ✓ exit code 与 baselineV1 §8 逐行一致 |
| §12-§13 Tool/Permission | §9 | ✓ |
| §14 Artifact/Evidence | §11 | ⚠ 见 F1 |
| §15 Provider | §12 | ✓ |
| §16 Context | §10 | ✓ PromptLayerLoader 4 方法签名逐字一致 |
| §17 Projection/UI | §13 | ✓ ProjectionSnapshot 8 个投影字段全覆盖 |
| §18 Capability | §9.5 | ✓ |
| §19 Doctor | §16 | ⚠ 见 F5 |
| §20 Debug/Memory | §11.3 | ✓ lookup_by_signature/by_task 存在 |
| §21 Diagnostic | §15 | ✓ |
| §22-§23 版本/边界规则 | §3、§18.5 | ✓ 10 条禁止边全继承 |

### 3.2 事件覆盖（event-registry-v1 → DD）

差集法核对（registry §6 索引 55 durable + 7 ephemeral）：

- DD §5.4 Table A/B 显式列出 46 个事件名；
- 差集中 12 个"未直接出现"的事件（`agent.completed/failed/lost/cancelled`、6 个 `doctor.*`、`permission.prompt.requested/resolved`）经核查均由 DD 的**聚合写法**覆盖：
  - `| agent.completed/failed/lost/cancelled | update agents.status |`（§5.4 L384）
  - `| doctor.* | append (+ optional ...) |`（§5.4 L409）
  - `| permission.prompt.requested/resolved | append |`（§5.4 L408）
- 7 个 ephemeral 全部在 §5.5 与 §13.1 列出（含 `command.stdout.delta`/`command.stderr.delta`）。

**结论**：55 + 7 全覆盖，无遗漏。差集中出现的 `agents.status`/`sessions.status`/`events_session.db` 为投影目标列/库名，非事件名，属正常。

### 3.3 DB Schema 覆盖（db-schema-v1 → DD repositories）

db-schema §2-§18 共 17 表。DD §4.3 仓库清单覆盖 §3-§18 的 16 张业务表（一一对应），`schema_meta`（§2）由 `MigrationRunner` 持有（DD §4.2、§21.3 明确）。两张项目级 DB（`debug-records.db`/`learned-memory.db`，§20）由 `DebugKnowledgeStore`/`LearnedMemoryStore` 持有（§11.3）。

**结论**：17/17 表 + 2 项目级 DB 全覆盖。

### 3.4 状态机覆盖

| 状态机 | 基线 | DD |
|---|---|---|
| Main Agent | main-agent-state-machine.md | §14.1、§20.1 ✓ |
| Scheduler | scheduler-state-machine-v1.md §4 | §7、§20.2 ✓（11 状态全列） |
| Task status | db-schema §7 | §20.3 ✓ |
| Agent status | db-schema §10 | §20.4 ✓ |
| Workspace status | db-schema §16 | §20.5 ✓ |
| Capability lifecycle | capability-trust §7 | §9.5、§20.6 ✓ |

6/6 状态机全覆盖。

### 3.5 需求覆盖（requirements → DD workflows）

- C++ 全流程（configure/build/test/static-analysis/debug/fix/review）：DD §15 + §19.5 ✓
- GUI/网络取证工具：通过 capability + tool 注册（§9.5、§15）✓
- 静态分析（`docs/staticanalysis.md`）：`CppcheckRunner` + `DiagnosticParser`（§15）✓
- TUI/HUD 投影：§13 ✓
- Linux tier-1 release gate：§16（Doctor/release）+ overview §15 ✓

### 3.6 PromptLayer L0-L9 覆盖

DD §10.2 表 1 将 11 个 `PromptLayerLevel` 枚举值（含 `system_debug`）映射到 L0-L9，与 contracts §16 枚举、prompt-layering-v1 §2 完全对应。表 2 区分 PromptLayerLoader（L0/L1/L3/L5）与 ContextAssembler 内部装配（L2/L4/L6/L7/L8/L9）。✓

### 3.7 UML 类图覆盖（§22.1-§22.8）

| 图 | 类数 | 状态 |
|---|---|---|
| §22.1 契约包 | 9 | ✓ |
| §22.2 运行时核心服务 | 9 | ✓ |
| §22.3 Scheduler | 7 | ✓ |
| §22.4 Tool/Permission | 5 | ⚠ F3 |
| §22.5 Worker/IPC | 9 | ✓ 5 个 Role 继承齐全 |
| §22.6 Provider | 6 | ✓ |
| §22.7 Context/Compaction | 4 | ⚠ F2 |
| §22.8 Agents | 2 | ✓ |

8/8 存在且语法可解析。两处欠完整见 §7。

---

## 4. 基线遵守审查

抽取 DD 中所有 `ClassName.method()` 形式引用，回查契约真实性：

| DD 引用 | 契约真实性 | 判定 |
|---|---|---|
| `PromptLayerLoader.load_role()` | contracts §16 存在 | ✓ |
| `EvidenceStore.list_for_task()` | contracts §14 **只有** `list_for_entity()` | ✗ **F1** |
| `EventBus.publish()` | contracts §7 存在 | ✓ |
| `ContextAssembler.load_layers()` | DD 内部私有方法（`-`），非契约 | ✓ |
| `SessionStore.referential_check()` | SessionStore 是 DD 内部聚合，非契约接口 | ✓ |
| `ProjectLocator.locate()` / `ProjectInitializer.scaffold()` | DD 标记 `IMPL` 辅助类 | ✓ |
| `DoctorService.check_capability()` | contracts §19 **只有** `run()` | ✗ **F5** |
| `current_profile()`（R5 旧问题） | DD 中已 0 处、契约 0 处 | ✓ R1-01 已闭合 |

R 系列复验：`overview §10.3`（R2-01）、`agent.started 单状态 + §20.4`（R1-02）、`无 phase 字段`（R1-03）、`16 mandatory files`（R2-02）均已正确落地。

---

## 5. 架构合理性审查

### 5.1 依赖方向与无循环

DD §2 复述 c4/module.md 的允许导入图：`contracts ← llm/toolchain-cpp/tui/runtime ← cli`，`workers` 仅依赖 contracts + WorkerRuntime IPC。无逆向边、无环。✓

### 5.2 职责分离

- **Scheduler vs WorkspaceManager**（§7.5）：策略归 Scheduler、机制归 WorkspaceManager，9 行职责矩阵清晰，无泄漏。✓
- **EventStore vs 领域服务**（§5.1、§5.3）：EventStore 只做事务投影，不创建 task/permission/memory；follow-up 由 owning service 发出。✓
- **ToolRegistry / PermissionEngine / CapabilityRegistry**（§9）：所有副作用经 PermissionEngine；capability 永不绕过。✓

### 5.3 事件流一致性

producer → EventIngestor → (durable: EventStore tx + projection + post-commit publish | ephemeral: EventBus) 在 §5.1、§5.3、§18.2 三处描述一致；"publish AFTER commit"（contracts §7 rule 3）一致。✓

### 5.4 跨 DB outbox 一致性

§18.4 经 R1-03 修复后，采用"owning store 先外部写 → 成功后 ingest 单个完成态事件"模型；与 runtime-semantics §6.3-§6.4、event-registry §3 payload（无 phase 字段）一致；§5.4 Table B 与之呼应。✓ 无残留矛盾。

### 5.5 FK-off 应用层不变式

§18.3 列出 8 条不变式，与 runtime-semantics §14 逐条对应；`SessionStore.referential_check()` 在启动/周期运行。✓

---

## 6. 内在一致性与冲突审查

| 检查点 | 结果 |
|---|---|
| §5.3 EventStore 正文 vs §22.2 类图 | ✓ 一致（append/append_many/query + publish-after-commit 边） |
| §20.4 Agent 状态机 vs §5.4 `agent.started` 投影 | ✓ R1-02 修复后自洽（单状态 + §20.4 过渡） |
| §10.3 Compaction 时序 vs §19.3 序列图 | ✓ 一致（仅 summary.created 插行） |
| §4.4 derive_command_status vs contracts §17 CommandRunProjection.status | ✓ 五值一致 |
| §17 CLI 命令清单 vs overview §14 catalog | ✓ DD 含 6 个 catalog 命令 + 5 个基础命令(run/init/doctor/e2e/release)，后者在 overview §4/§15 有据，属合理超集 |
| §8.1 exit code vs baselineV1 §8 | ✓ 6 个 code 逐行一致 |

未发现跨章节概念冲突或时序矛盾。

---

## 7. UML 类图详细审查（§22.1-§22.8 逐张）

- **§22.1 契约包**：`EventSource.kind` 枚举与 §2 runtime-role 表协同；`RuntimeEvent → EventSource`、`WorkerResult → Artifact/Evidence`、`AirError → EntityRef` 边正确。✓
- **§22.2 核心服务**：`EventStore → EventBus : publishes after commit`、`ProjectionStore → EventBus : subscribes` 准确反映事件流。✓
- **§22.3 Scheduler**：6 个被组合类（TaskGraph/WavePlanner/RetryPlanner/WorkspaceManager/AgentMonitor/WorkerManager）齐全。建议旁注 "Scheduler owns policy; WorkspaceManager owns mechanism"（与 §7.5 呼应），非必须。
- **§22.4 Tool/Permission** — **F3**：图中 `ToolRegistry` 缺少到 `ToolDefinition` / `ToolExecutor` 的关系边；正文 §9.1 明确 ToolRegistry 注册/调用这两者。建议补 `ToolRegistry --> ToolDefinition : registers` 与 `ToolRegistry --> ToolExecutor : invokes`。
- **§22.5 Worker/IPC**：5 个 Role 实现 `WorkerRole` 继承齐全；`docs` TaskType 复用 ExecutorRole 无需新增节点，与 §8.3 一致。✓
- **§22.6 Provider**：双 adapter 继承 + converter + normalizer 边正确。✓
- **§22.7 Context/Compaction** — **F2**：图中 `ContextAssembler` 仅连 `PromptLayerLoader`/`CompactionPolicy`，但 §10.2 表 2 明确 ContextAssembler 内部装配 L2/L6/L7/L8 需读 `EvidenceStore`、`SessionStore.messages/tool_runs/command_runs`。类图低估了实际耦合。建议补 `ContextAssembler --> EvidenceStore`、`ContextAssembler --> SessionStore`（依赖型虚线即可）。
- **§22.8 Agents**：`MainAgent`/`ArchitectureDesigner` → Scheduler/ContextAssembler/ProviderManager/EventIngestor 边正确；与 §2 "runtime role 不走 load_role" 决策一致。✓

---

## 8. 新发现（P0 / P1 / P2 分类）

### F1 [P2] `EvidenceStore.list_for_task()` 不在契约

- **位置**：DD §10.2 表 2，L6 Evidence 行（L932）
- **问题**：引用 `EvidenceStore.list_for_task()`，但 contracts §14 `EvidenceStore` 仅声明 `create()` 与 `list_for_entity(entity_type, entity_id)`。
- **根因**：与 R5 的 `current_profile()` 同类——为给 L6 找一个明确来源，点名了不存在的方法。
- **影响**：实现 ContextAssembler 时找不到 `list_for_task()`；轻微，因为 `list_for_entity("task", task_id)` 即可替代。
- **建议**：改为 `EvidenceStore.list_for_entity("task", task_id)`（契约真实方法）。
- **工作量**：2 分钟

### F5 [P2] `DoctorService.check_capability()` 不在契约

- **位置**：DD §16.1（L1201）
- **问题**：`DoctorService` 类列出 `+check_capability(capability): Promise<DoctorIssue[]>`（public `+`），但 contracts §19 `DoctorService` 仅声明 `run(input): Promise<DoctorRunOutput>`。
- **根因**：把内部分解步骤当成公共契约方法暴露。
- **影响**：与 §0 "不引入新公共契约" 约束冲突；轻微。
- **建议**：改为私有 `-check_capability(...)`（与同段 `-self_bootstrap()` 一致风格），或并入 `run()` 内部说明。
- **工作量**：1 分钟

### F2 [P2] §22.7 类图缺 ContextAssembler 内部装配依赖边

- 见 §7。建议补 `ContextAssembler --> EvidenceStore` / `--> SessionStore` 虚线依赖。
- **工作量**：3 分钟

### F3 [P2] §22.4 类图缺 ToolRegistry → ToolDefinition/ToolExecutor 边

- 见 §7。建议补两条注册/调用关系边。
- **工作量**：3 分钟

无 P0、无 P1。F1/F5 是契约边界的两处"点名了不存在的方法"，与本轮独立抽样法直接相关；F2/F3 是类图完整度问题，不影响正文设计正确性。

---

## 9. 门禁判定

| 条件 | 状态 |
|---|---|
| P0 = 0 | **PASS** |
| 契约覆盖 100% | **PASS** |
| 事件覆盖 100% | **PASS** |
| DB Schema 覆盖 100% | **PASS** |
| 状态机覆盖 100% | **PASS** |
| L0-L9 覆盖 | **PASS** |
| 禁止路径全继承 | **PASS** |
| 架构无循环依赖 | **PASS** |
| 职责分离无泄漏 | **PASS** |
| R 系列(R1/R2)修复已闭合 | **PASS** |
| 契约/payload 不变性（无越界方法/字段） | **FAIL**（F1 + F5 两处契约方法越界） |
| UML 类图完整度 | **CONDITIONAL**（F2 + F3 欠边，不影响正确性） |

**门禁结果：CONDITIONAL PASS** — 覆盖性、架构、状态机全部 PASS；4 项 P2 不阻断实现，但建议在冻结前一并修复以保持契约纯净。

---

## 10. 多轮累积视角

| 轮次 | 模型 | 主要贡献 | P0 | P1 | P2 |
|---|---|---|---|---|---|
| R1 | DeepSeek | 全量覆盖性 | 0 | 0 | 3 |
| R2 | MIMO 2.5 Pro | 内在一致性 | 0 | 2 | 5 |
| R3 | GPT-5.5 Pro | 基线冲突检测 | 0 | 2 | 4 |
| R4 | Opus 4.8 | 验证 + 根因 | 0 | 2 | 5 |
| R5 | Opus 4.7 | 修复回归引入检测 | 0 | 3 | 2 |
| R5-fix | — | R1-01~R2-02 闭合（commit af99aed） | — | — | — |
| **R6** | **Opus 4.8（本次全量复查）** | **契约方法越界抽样 + 类图完整度** | **0** | **0** | **4** |

**累积说明**：R1-R5 的 P1×4 + P2×9 + R 系列 5 项均已闭合。R6 在更系统的"点名方法 vs 契约"抽样下浮出 F1/F5（与 R5 的 `current_profile()` 同型，说明此类问题需要一次性全表扫描），以及两处类图欠边 F2/F3。无新增 P0/P1。

---

## 11. 最终结论与建议

### 11.1 设计成熟度

详细设计在**覆盖性、架构合理性、状态机一致性、基线遵守（主体）**四个维度均达标。事件 / 表 / 契约 / 状态机 / 禁止边 / L0-L9 / UML 七类对象 100% 覆盖，依赖无环，职责分离干净，跨 DB outbox 与 FK-off 不变式自洽。

### 11.2 剩余问题

仅剩 4 项 P2，全部为局部精修：
- **F1 / F5**：两处"点名了不存在的契约方法"（`EvidenceStore.list_for_task`、`DoctorService.check_capability`），合计 3 分钟可改为真实方法 / 改私有。
- **F2 / F3**：两张类图欠依赖边，合计 6 分钟补全。

### 11.3 建议

**总工作量约 9 分钟**即可收束全部 4 项 P2。这些不阻断进入实现阶段，但建议在正式冻结前一并修复，使契约纯净度与类图完整度达到 100%，避免实现者在 ContextAssembler / DoctorService 处遇到与 R5 同型的"找不到方法"困惑。

### 11.4 最终判定

**CONDITIONAL PASS (R6)** — 详细设计满足全量覆盖与结构正确性，R 系列回归修复全部闭合；本轮新增 4 项 P2（2 契约方法越界 + 2 类图欠边），均为分钟级修复，不阻断实现。

---

End of full-scope re-audit.