AirCoding/AirPlan/docs/architecture/Mimo2.5pro系统详细设计审查.md

# MIMO 2.5 Pro 系统详细设计全量交叉审查

Date: 2026-05-29
Reviewer: MIMO 2.5 Pro (single-model, independent pass)
Status: Full cross-verification of `system-detailed-design.md` against all frozen baselines, frozen overview, and internal architectural consistency
Scope: Coverage + consistency + architecture soundness audit

---

## 1. 审查方法

审查对象：`AirPlan/docs/architecture/system-detailed-design.md`（2033 行，23 节）

审查三维度：

1. **覆盖性**：基线/概要设计的每个 item 是否在详细设计中有对应项
2. **一致性**：详细设计内部是否存在矛盾、基线引用是否准确
3. **架构合理性**：类职责划分、依赖方向、边界执行是否合理，是否存在内在冲突

审查输入：

| 文档 | 角色 |
|---|---|
| `interface-contracts-v1.md` (23 节) | 接口契约 |
| `event-registry-v1.md` (55 durable + 7 ephemeral) | 事件注册表 |
| `db-schema-v1.md` (19 表, 18 个关闭枚举) | 数据库 Schema |
| `runtime-semantics-v1.md` (19 节) | 运行时语义 |
| `scheduler-state-machine-v1.md` (11 节) | 调度器状态机 |
| `main-agent-state-machine.md` | 主代理状态机 |
| `prompt-layering-v1.md` (L0-L9) | 提示分层 |
| `scope-escalation-v1.md` (13 节) | 作用域升级 |
| `security-model-v1.md` (8 PathRisk + 10 CommandRisk) | 安全模型 |
| `capability-trust-v1.md` | 能力信任 |
| `system-overview-design.md` (FROZEN, 1222 行) | 概要设计 |
| `DeepSeek系统详细设计审查.md` | 前一轮审查报告 |

方法：
- 逐契约接口字段比对
- 逐事件投影映射核对
- 逐表仓储核对
- 逐状态机转换核对
- PromptLayer 三方比对（contracts / prompt-layering / overview）
- 依赖方向一致性验证
- 内在冲突检测

---

## 2. 总体评估

### 2.1 评分

| 维度 | 得分 | 说明 |
|---|---|---|
| 契约覆盖 | 9.5/10 | 接口字段全覆盖，1 处 PromptLayerLevel 枚举与层名不完全对齐 |
| 事件覆盖 | 10/10 | 55 durable + 7 ephemeral 全覆盖 |
| DB Schema 覆盖 | 10/10 | 19 表全仓储 |
| 状态机覆盖 | 10/10 | 6 个状态机全覆盖 |
| 内在一致性 | 8.5/10 | 1 处真实内部矛盾（PromptLayer），1 处架构弱点（EventStore 错误隔离） |
| 架构合理性 | 9.5/10 | 边界清晰、职责分离良好、依赖方向正确 |
| 序列图覆盖 | 8.0/10 | 4 个关键序列覆盖，2 个可补充 |
| 可实现性 | 9.5/10 | 方法签名可直接编码，无歧义 |

**综合评分：9.4/10**

### 2.2 结论

详细设计是一个高质量的实现导向文档。架构边界清晰，依赖方向正确，类职责分离良好。发现了 **1 处真实内部矛盾** 和 **1 处架构弱点** 需要解决，但均不阻塞实现阶段——可以通过明确的设计决策澄清来修复。

---

## 3. P0 发现（0 项）

未发现 P0 项。

---

## 4. P1 发现（2 项）

### P1-01: PromptLayerLevel 枚举与 L0-L9 层名结构性不对齐

**严重度**：P1（真实内部矛盾，影响实现一致性）

**问题**：`interface-contracts-v1.md` §16 定义了 10 个 `PromptLayerLevel` 枚举值，`prompt-layering-v1.md` §2 定义了 L0-L9 共 10 个层名。概要设计 §13 已将 L0-L9 逐层与基线对齐。但三方存在结构性不匹配：

| L# | prompt-layering-v1 §2 | contracts §16 枚举值 | 对齐状态 |
|---|---|---|---|
| L0 | Runtime invariant | `runtime_invariant` | ✓ |
| L1 | Role / agent mode | `role` | ✓ |
| L2 | Safety and permission policy | **（无对应枚举值）** | ✗ |
| L3 | Project rules and user preferences | `project_rules` | ✓ |
| L4 | Architecture baseline and current plan | `architecture` | ✓ |
| L5 | Task specification and acceptance criteria | `task_spec` | ✓ |
| L6 | Relevant code / artifacts / evidence | `evidence` | ✓ |
| L7 | Recent conversation and decision context | `conversation` | ✓ |
| L8 | Tool result history / diagnostics | `tool_output` | ✓ |
| L9 | Immediate instruction | `user_override`（名字不同） | △ |
| — | （无对应层） | `system_debug` | ✗ |

**矛盾点**：
1. L2 "Safety and permission policy" 没有对应的 `PromptLayerLevel` 枚举值——但它是 prompt-layering-v1 定义的独立层
2. `user_override` 映射到 L9，但概要设计 §13 说 L9 = "Immediate instruction"，名字不一致
3. `system_debug` 枚举值没有对应的 L 层——DD §10.2 说"applied within L9 when present"，但这是一个缩写而非结构映射

**影响**：实现时 `ContextAssembler.load_layers()` 需要 10 个加载点，但 `PromptLayerLoader` 接口只有 4 个方法（`load_runtime_invariant`, `load_role`, `load_project_rules`, `load_task_context`）。L2 safety、L4 architecture、L6 evidence、L7 conversation、L8 tool_output、L9 immediate instruction 都没有明确的 loader 方法。

**修复建议**（需要设计决策）：
- 选项 A：在 contracts §16 添加 `safety_permission` 枚举值，将 `user_override` 改名为 `immediate_instruction`，删除 `system_debug` 或并入 L9
- 选项 B：保持枚举不变，在实现层将 L2 映射到 `runtime_invariant`（immutable=true），L9 由 `user_override` + `system_debug` 合并
- 选项 C：扩展 `PromptLayerLoader` 接口添加 L2/L4-L9 的显式加载方法

无论选哪个，需要一个明确的设计决策记录。

---

### P1-02: EventStore.project() 错误处理未定义

**严重度**：P1（架构弱点，影响运行时鲁棒性）

**问题**：DD §5.3 `EventStore.append()` 在事务内执行 `EventRepository.insert()` 和 `project(event, tx)`。但 `project()` 执行的是多行 domain update（如 `task.started` 需要更新 `tasks` 表 + 插入 `task_attempts` 行）。如果 `project()` 中间步骤失败，事务会回滚——但此时 `EventBus.publish()` 不会执行（正确行为），然而 **没有描述 `project()` 内部的错误语义**：

- 如果 `project()` 抛出异常，是整个 `append()` 回滚？（应该）
- 如果 domain update 因 FK-off 不一致失败（如引用了不存在的 `tasks.id`），错误如何传播？
- `project()` 是否有部分失败的恢复逻辑？

**影响**：在高并发或重启恢复场景下，如果 `project()` 的某一步 domain update 失败（如引用的 task 已被删除），整个事件追加会回滚——这是正确的原子行为，但 DD 没有显式描述这个错误路径。

**修复建议**：在 DD §5.3 或 §18.2 添加：`project()` 异常 → 事务回滚 → `EventBus.publish()` 不执行 → 返回 `AirError{kind: "system_error"}`。如果是因为 FK-off 不一致导致，记录到 developer log 并触发 `referential_check()`。

---

## 5. P2 发现（5 项）

### P2-01: DeepSeek 审查报告中的 3 项 P2 已验证

DeepSeek 审查报告的 3 项 P2 均确认属实：

| ID | DeepSeek 发现 | MIMO 验证 |
|---|---|---|
| DeepSeek P2-01 | PromptLayerLevel 枚举与 L0-L9 不完全 1:1 | 确认（已升级为 MIMO P1-01） |
| DeepSeek P2-02 | Architecture Designer gate 无独立序列图 | 确认，P2 |
| DeepSeek P2-03 | CLI catalog 命令类归属未指定 | 确认，P2 |

### P2-04: `agent.started` 投影映射措辞

DD §5.4 投影映射表中 `agent.started` 的域更新描述为 "insert `agents` (starting/running)"。这暗示 `project()` 可能选择 `starting` 或 `running`，但 event-registry §3.3 固定为 "insert `agents` row with `status = running` or `starting`"——具体选择哪个取决于调度器上下文（spawn 前 vs 握手后）。

建议：DD 应明确 `starting` 是初始状态，`running` 是握手完成后的状态（与 db-schema §10 agent status 一致）。当前描述可接受但含糊。

### P2-05: `WorkspaceManager` 与 `Scheduler` 状态机 MERGING 阶段的职责边界

DD §7.5 `WorkspaceManager.merge_workspace()` 和 DD §20.2 Scheduler 的 MERGING 状态都描述了合并逻辑。但 Scheduler 状态机的 MERGING 包含了冲突处理路由（trivial → repair/debugger, semantic → Reviewer/Architecture Designer, architecture → block, user → Main Agent）——这些是 Scheduler 级别的决策，而 `WorkspaceManager` 只负责 git 操作。

建议：明确 `WorkspaceManager` 返回 `MergeResult{status: success|conflict, conflict_files?, conflict_type?}`，Scheduler 根据 `conflict_type` 做路由决策。当前描述隐含了这个分工但没有显式标注。

---

## 6. 架构合理性分析

### 6.1 依赖方向

```text
contracts → (none)
llm → contracts
toolchain-cpp → contracts
tui → contracts
runtime → contracts, llm (facade only)
cli → contracts, runtime, tui, llm, toolchain-cpp
workers → contracts + WorkerRuntime IPC (no direct runtime import)
```

**评估**：完全正确。`contracts` 是叶节点，`cli` 是根节点，`runtime` 依赖 `llm` 但仅通过 facade（`ProviderManager` 接口），`workers` 通过 IPC 间接依赖 `runtime`（不直接 import）。这个依赖方向避免了循环依赖，允许各包独立编译。

### 6.2 职责分离

| 组件 | 职责 | 边界 | 评估 |
|---|---|---|---|
| EventIngestor | 事件入口 | 不创建 scheduler/permission/memory 决策 | ✓ 正确隔离 |
| EventStore | 持久化事件 + 投影 | 不直接暴露 EventBus | ✓ 正确（投影在事务内，发布在事务后） |
| EventBus | 实时发布/订阅 | 不是恢复源 | ✓ 正确 |
| SessionStore | 聚合所有仓储 | 不含调度/权限/投影策略 | ✓ 正确（code-view §9） |
| Scheduler | 编排服务 | 不是编码代理 | ✓ 正确（scheduler-state-machine §intro） |
| ToolRegistry | 工具调用 | 所有 side effect 必须经过 PermissionEngine | ✓ 正确（contracts §23） |
| PermissionEngine | 权限决策 | 不绕过 credential/system-sensitive override | ✓ 正确 |
| TUI | UI 渲染 | 只依赖 ProjectionClient/contracts | ✓ 正确（contracts §23） |
| ContextAssembler | 上下文组装 | 不自行压缩 | ✓ 正确（概要设计 §13） |

**评估**：所有组件的职责边界与基线一致。没有发现职责泄漏或边界违反。

### 6.3 状态机一致性

6 个状态机之间的交互路径：

| 源状态机 | 目标状态机 | 事件/数据流 | 一致性 |
|---|---|---|---|
| Main Agent → Scheduler | DELEGATING → SCHEDULING | `task.created` | ✓ |
| Scheduler → Worker | DISPATCHING → worker spawn | `agent.start` IPC | ✓ |
| Worker → Scheduler | worker.return → COLLECTING_RESULTS | `worker.result` IPC | ✓ |
| Scheduler → Architecture Designer | architecture-sensitive review | `architecture.impact.completed` | ✓ |
| Architecture Designer → Scheduler | impact assessment done | Scheduler consumes impact | ✓ |
| Main Agent ← Scheduler | progress/blocked/complete | `task.progress/blocked/completed` events | ✓ |
| EventBus → ProjectionStore | all events | subscribe/apply | ✓ |
| ContextAssembler → Scheduler | `compaction_requested` | Scheduler creates compact task | ✓ |

**评估**：所有状态机交互路径的事件名称、方向和触发条件一致。没有发现状态机之间的死锁或悬空事件路径。

### 6.4 事务语义一致性

关键事务边界：

| 操作 | 事务范围 | 后置操作 | 一致性 |
|---|---|---|---|
| EventStore.append | event insert + domain projection | EventBus.publish (after commit) | ✓ |
| ArtifactStore.create | temp→rename→DB record | event ingest | ✓ |
| Task.start | task.started event + tasks update + task_attempts insert | agent.started event | ✓ |
| Compaction | summary.created event + summaries insert | context.compaction.completed | ✓ |
| Cross-DB write (outbox) | session event → external DB → completion event | recovery on restart | ✓ |

**评估**：所有事务边界遵循 runtime-semantics §3 规则（durable event + domain update 同事务，EventBus 发布在事务后）。

---

## 7. 与 DeepSeek 审查的交叉验证

| 发现 | DeepSeek 判定 | MIMO 判定 | 差异 |
|---|---|---|---|
| PromptLayerLevel 结构性不对齐 | P2 | **P1** | MIMO 升级：这不是"措辞差异"而是真实内部矛盾，影响实现一致性 |
| Architecture gate 无独立序列图 | P2 | P2 | 一致 |
| CLI catalog 类归属 | P2 | P2 | 一致 |
| EventStore.project() 错误处理 | **未报告** | **P1** | MIMO 独立发现 |
| agent.started 投影措辞 | **未报告** | P2 | MIMO 独立发现 |
| WorkspaceManager/Scheduler 职责边界 | **未报告** | P2 | MIMO 独立发现 |

**差异分析**：DeepSeek 将 PromptLayer 问题标记为 P2，理由是"DD §10.2 正确记录了此映射"。MIMO 认为这是 P1，因为虽然 DD 记录了差异，但没有给出明确的解决决策——实现时仍然面临"枚举值和层名不完全对应"的问题，而这个差异发生在两个已冻结的基线之间（contracts 和 prompt-layering），属于需要明确澄清的架构级问题。

---

## 8. 覆盖性检查

### 8.1 契约接口字段抽样

| 接口 | 基线字段数 | DD 覆盖数 | 缺失 |
|---|---|---|---|
| TaskSpec | 9 fields | 9 | 0 |
| WorkerResult<T> | 12 fields | 12 | 0 |
| IpcEnvelope<T> | 9 fields | 9 | 0 |
| PermissionDecision | 7 fields | 7 | 0 |
| AirError | 11 fields | 11 | 0 |
| ProviderCapabilityMatrix | 10 fields | 10 | 0 |
| CapabilityManifestV1 | 13 fields | 13 | 0 |
| DebugRecord | 10 fields | 10 | 0 |
| LearnedMemory | 9 fields | 9 | 0 |
| Diagnostic | 14 fields | 14 | 0 |

**10/10 接口字段完整性抽样全部通过。**

### 8.2 事件投影映射核对

55 个持久化事件逐一对比 event-registry §3 的 Domain update 描述。全部 55/55 覆盖且域更新描述准确。

### 8.3 DB Schema 表核对

19 张表（db-schema §2-§18 + §20.1-§20.2）逐一对比 DD §4.3 仓储清单 + §11.3 项目级 DB Store。19/19 全覆盖。

### 8.4 禁止路径核对

10 条 contracts §23 禁止路径逐一对比 DD §2 + §18.5。10/10 全覆盖。DD 额外添加 1 条 C4 规则（runtime → TUI import）。

---

## 9. 与前轮审查的一致性

| 维度 | DeepSeek | MIMO 2.5 Pro |
|---|---|---|
| P0 | 0 | 0 |
| P1 | 0 | 2 |
| P2 | 3 | 5 |
| 综合评分 | 9.6/10 | 9.4/10 |
| 新发现 | — | P1-02, P2-04, P2-05 |

**一致性结论**：两轮审查在 P0 层面一致（0 项）。MIMO 发现了 DeepSeek 未报告的 P1 级 EventStore 错误处理问题，并将 PromptLayer 结构性矛盾从 P2 升级为 P1。

---

## 10. 门禁判定

| 条件 | 状态 |
|---|---|
| P0 = 0 | PASS |
| P1 ≤ 2（均有明确修复路径）| PASS |
| 契约覆盖 100% | PASS |
| 事件覆盖 100% | PASS |
| DB Schema 覆盖 100% | PASS |
| 状态机覆盖 100% | PASS |
| 禁止路径全执行 | PASS |
| 架构无循环依赖 | PASS |
| 职责分离无泄漏 | PASS |
| 状态机交互无死锁 | PASS |
| 事务语义一致 | PASS |

**门禁结果：PASS（附 2 项 P1 修复建议）**

详细设计可以进入实现阶段，但建议在实现开始前明确 P1-01（PromptLayer 设计决策）和 P1-02（EventStore 错误路径文档化）。

---

## 11. P1 修复建议

### P1-01 修复路径

需要一个设计决策（ADR 或详细设计补充）：

**推荐方案 B**：保持枚举不变，在实现层建立映射：

```text
L0 → runtime_invariant (immutable=true)
L1 → role (immutable=true)
L2 → (safety layer loaded by ContextAssembler as a runtime_invariant variant with immutable=true, 
      source from ~/.air/permissions.yaml + project permissions)
L3 → project_rules
L4 → architecture (loaded from plan/todo/ADR context)
L5 → task_spec
L6 → evidence (loaded from artifacts/diagnostics/evidence_refs)
L7 → conversation (loaded from messages/summaries)
L8 → tool_output (loaded from recent tool_runs/command_runs/diagnostics)
L9 → user_override + system_debug (merged, highest priority non-immutable layer)
```

PromptLayerLoader 接口扩展为：

```text
load_safety_policy(): PromptLayer        // L2
load_architecture_context(refs): PromptLayer[]  // L4
load_evidence_context(refs): PromptLayer[]      // L6
load_conversation(session_id): PromptLayer[]    // L7
load_tool_output(recent_runs): PromptLayer[]    // L8
load_immediate_instruction(): PromptLayer       // L9
```

### P1-02 修复路径

在 DD §5.3 或 §18.2 补充：

```text
EventStore.append error semantics:
  - project() 内部异常 → 整个事务回滚
  - EventBus.publish() 不执行（正确：post-commit only）
  - 返回 AirError{kind: "system_error", message: "event projection failed"}
  - 如果是因为 FK-off 不一致（如引用不存在的 task_id）：
    - 记录到 developer log
    - 触发 SessionStore.referential_check()
    - Scheduler 将受影响的 task 标记为 interrupted/blocked
  - 不会部分投影：SQLite 事务保证原子性
```