b668b185e1
Add system-detailed-design.md (2033 lines, 23 sections) derived from frozen baselines and overview. Complete four-model cross-review: - DeepSeek: baseline coverage audit (PASS, 9.6/10) - MIMO 2.5 Pro: internal consistency (PASS, 9.4/10) - GPT-5.5 Pro: baseline conflict detection (Requires repair) - Opus 4.8: validation + root cause analysis (CONDITIONAL PASS, 9.1/10) Key findings requiring resolution before freeze: - P1-01: Worker exit code semantic conflict (baselineV1 vs overview) - P1-02: PromptLayerLevel enum vs L0-L9 layer name mismatch - P1-03: EventStore.project() error handling undefined - P1-04: PromptLayerLoader interface incomplete for 10 layers Coverage verified: 100% contracts, events, DB schema, state machines. Architecture validated: no circular dependencies, proper separation. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
303 lines
9.9 KiB
Markdown
303 lines
9.9 KiB
Markdown
# 多模型系统详细设计交叉审查汇总
|
||
|
||
Date: 2026-05-29
|
||
Status: Multi-model cross-review synthesis
|
||
Scope: `system-detailed-design.md` against all frozen baselines, frozen overview, and internal consistency
|
||
|
||
---
|
||
|
||
## 1. 审查概览
|
||
|
||
### 1.1 参与模型
|
||
|
||
| 模型 | 审查轮次 | 审查重点 |
|
||
|---|---|---|
|
||
| DeepSeek | 第 1 轮 | 基线覆盖性全量核对 |
|
||
| MIMO 2.5 Pro | 第 2 轮 | 内在一致性 + 架构合理性 |
|
||
| GPT-5.5 Pro | 第 3 轮 | 基线间冲突检测 |
|
||
| Claude Opus 4.8 | 第 4 轮 | 前轮验证 + 根因分析 + 修复建议 |
|
||
|
||
### 1.2 审查输入
|
||
|
||
- 22 份冻结基线文档
|
||
- 1 份已冻结概要设计 (`system-overview-design.md`)
|
||
- 详细设计文档 (`system-detailed-design.md`, 2033 行, 23 节)
|
||
|
||
---
|
||
|
||
## 2. 各模型审查结论
|
||
|
||
| 模型 | 结论 | P0 | P1 | P2 | 综合评分 |
|
||
|---|---|---|---|---|---|
|
||
| DeepSeek | **PASS** | 0 | 0 | 3 | 9.6/10 |
|
||
| MIMO 2.5 Pro | **PASS (附修复建议)** | 0 | 2 | 5 | 9.4/10 |
|
||
| GPT-5.5 Pro | **Requires repair** | 0 | 2 | 4 | — |
|
||
| Opus 4.8 | **CONDITIONAL PASS** | 0 | 2 | 5 | 9.1/10 |
|
||
|
||
---
|
||
|
||
## 3. 覆盖性共识
|
||
|
||
四轮审查在覆盖性上达成完全共识：
|
||
|
||
| 维度 | 基线要求 | DD 覆盖 | 共识 |
|
||
|---|---|---|---|
|
||
| 契约接口 | 23 章节, 80+ 接口 | 100% | ✓ 全覆盖 |
|
||
| 持久化事件 | 55 个 | 100% | ✓ 全覆盖 |
|
||
| 暂态事件 | 7 个 | 100% | ✓ 全覆盖 |
|
||
| DB Schema 表 | 19 张 | 100% | ✓ 全覆盖 |
|
||
| 状态机 | 6 个 | 100% | ✓ 全覆盖 |
|
||
| 禁止路径 | 10 条 | 100% | ✓ 全覆盖 |
|
||
| UML 类图 | 8 个子系统 | 100% | ✓ 全覆盖 |
|
||
| 序列图 | 4 个关键流程 | 100% | ✓ 全覆盖 |
|
||
|
||
**结论：详细设计在覆盖性上完全通过。**
|
||
|
||
---
|
||
|
||
## 4. 发现汇总
|
||
|
||
### 4.1 P0 发现
|
||
|
||
**无 P0 发现。** 四轮审查均未发现详细设计与基线的直接矛盾或强制要求的完全缺失。
|
||
|
||
### 4.2 P1 发现（需要在冻结前解决）
|
||
|
||
| ID | 发现 | 发现者 | 验证者 | 根因 |
|
||
|---|---|---|---|---|
|
||
| **P1-01** | Worker exit code 语义冲突 | GPT-5.5 Pro | Opus 4.8 | baselineV1 §8 与 overview §11 定义了两套不同的 exit code 语义 |
|
||
| **P1-02** | PromptLayerLevel 枚举与 L0-L9 层名结构性不对齐 | DeepSeek (P2) → MIMO (P1) | Opus 4.8 | contracts §16 的 10 个枚举值与 prompt-layering §2 的 10 层不完全对应 |
|
||
| **P1-03** | EventStore.project() 错误处理未定义 | MIMO 2.5 Pro | Opus 4.8 | DD 未描述 project() 内部异常的错误语义和事务回滚行为 |
|
||
| **P1-04** | PromptLayerLoader 接口与 prompt-layering 层定义不匹配 | Opus 4.8 | — | 接口只有 4 个方法，但需要加载 10 层 |
|
||
|
||
### 4.3 P2 发现（不阻塞实现，建议修复）
|
||
|
||
| ID | 发现 | 发现者 |
|
||
|---|---|---|
|
||
| P2-01 | Architecture Designer gate 无独立序列图 | DeepSeek |
|
||
| P2-02 | CLI catalog 命令类归属未指定 | DeepSeek |
|
||
| P2-03 | `agent.started` 投影映射措辞含糊 | MIMO 2.5 Pro |
|
||
| P2-04 | WorkspaceManager/Scheduler 职责边界隐含但未显式标注 | MIMO 2.5 Pro |
|
||
| P2-05 | EventStore.project 职责边界措辞问题 | GPT-5.5 Pro → Opus 4.8 (澄清) |
|
||
| P2-06 | `memory.promoted` outbox 阶段语义不清 | GPT-5.5 Pro |
|
||
| P2-07 | `docs` task 类型进入 contracts/DB 但事件与 worker output 未闭合 | GPT-5.5 Pro |
|
||
| P2-08 | AgentType 不覆盖 runtime roles (main/architecture/scheduler) | GPT-5.5 Pro, Opus 4.8 |
|
||
| P2-09 | contracts 包文件集仍有两套命名 (code-view vs overview) | GPT-5.5 Pro |
|
||
|
||
---
|
||
|
||
## 5. P1 发现详细分析
|
||
|
||
### 5.1 P1-01: Worker exit code 语义冲突
|
||
|
||
**问题**
|
||
|
||
`baselineV1.md` §8 定义：
|
||
|
||
```text
|
||
0 protocol-level completion, including task failed/blocked
|
||
1 uncaught exception
|
||
2 startup/protocol error
|
||
3 permission error
|
||
4 parent cancelled
|
||
5 hard timeout killed
|
||
```
|
||
|
||
`system-overview-design.md` §11 和 `system-detailed-design.md` §8.1 定义：
|
||
|
||
```text
|
||
0 success
|
||
1 task failed
|
||
2 crashed
|
||
3 protocol error
|
||
4 cancelled
|
||
5 permission/policy blocked
|
||
```
|
||
|
||
**关键冲突点**
|
||
|
||
| Exit code | baselineV1 | overview/DD | 冲突 |
|
||
|---|---|---|---|
|
||
| 0 | 包括 task failed/blocked | 仅 success | task failed 是 0 还是 1？ |
|
||
| 1 | uncaught exception | task failed | 业务失败 vs 进程异常 |
|
||
| 3 | permission error | protocol error | 互换 |
|
||
| 5 | hard timeout killed | permission/policy blocked | 互换 |
|
||
|
||
**影响**
|
||
|
||
WorkerManager 实现时无法确定 Scheduler 的 retry/blocked/failed/lost 判定逻辑。
|
||
|
||
**建议处理**
|
||
|
||
发布 ADR 明确：
|
||
1. baselineV1 §8 被 overview §11 取代，或
|
||
2. 修复 overview/DD 以符合 baselineV1
|
||
|
||
---
|
||
|
||
### 5.2 P1-02: PromptLayerLevel 枚举与 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 | `project_rules` | ✓ |
|
||
| L4 | Architecture baseline | `architecture` | ✓ |
|
||
| L5 | Task specification | `task_spec` | ✓ |
|
||
| L6 | Relevant code/artifacts | `evidence` | ✓ |
|
||
| L7 | Conversation context | `conversation` | ✓ |
|
||
| L8 | Tool result history | `tool_output` | ✓ |
|
||
| L9 | Immediate instruction | `user_override` (名字不同) | △ |
|
||
| — | （无对应层） | `system_debug` | ✗ |
|
||
|
||
**影响**
|
||
|
||
ContextAssembler 实现时需要 10 个加载点，但 PromptLayerLoader 接口只有 4 个方法。
|
||
|
||
**建议处理**
|
||
|
||
在 DD 中明确记录设计决策：
|
||
- L2 Safety 由 PermissionEngine 提供
|
||
- L4-L9 由 ContextAssembler 内部组装
|
||
- 或扩展 PromptLayerLoader 接口
|
||
|
||
---
|
||
|
||
### 5.3 P1-03: EventStore.project() 错误处理未定义
|
||
|
||
**问题**
|
||
|
||
DD §5.3 描述了 `EventStore.append()` 在事务内执行 `project(event, tx)`，但未描述：
|
||
- `project()` 抛出异常时的行为
|
||
- FK-off 不一致导致的失败如何传播
|
||
- 是否有部分失败的恢复逻辑
|
||
|
||
**建议处理**
|
||
|
||
在 DD §5.3 或 §18.2 补充：
|
||
|
||
```text
|
||
project() 异常 → 事务回滚 → EventBus.publish() 不执行 → 返回 AirError{kind: "system_error"}
|
||
如果是 FK-off 不一致导致，记录到 developer log 并触发 referential_check()
|
||
```
|
||
|
||
---
|
||
|
||
### 5.4 P1-04: PromptLayerLoader 接口不完整
|
||
|
||
**问题**
|
||
|
||
`PromptLayerLoader` 接口只有 4 个方法：
|
||
|
||
```ts
|
||
load_runtime_invariant(): PromptLayer // L0
|
||
load_role(role: AgentType): PromptLayer // L1
|
||
load_project_rules(project): PromptLayer[] // L3
|
||
load_task_context(spec, refs): PromptLayer[] // L5
|
||
```
|
||
|
||
缺失 L2, L4, L6, L7, L8, L9 的加载方法。
|
||
|
||
**建议处理**
|
||
|
||
在 DD §10.2 明确记录：
|
||
|
||
```text
|
||
PromptLayerLoader 只覆盖需要外部配置/数据的层（L0, L1, L3, L5）。
|
||
其他层由 ContextAssembler 内部组装：
|
||
- L2 Safety: 从 PermissionEngine 获取
|
||
- L4 Architecture: 从 TaskSpec.context_refs.arc_ref 加载
|
||
- L6 Evidence: 从 TaskSpec.context_refs.artifacts 加载
|
||
- L7 Conversation: 从 SessionStore.messages 加载
|
||
- L8 Tool output: 从 SessionStore.tool_runs/command_runs 加载
|
||
- L9 Immediate: 从 TaskSpec.description/acceptance_criteria 构建
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 架构合理性共识
|
||
|
||
四轮审查在架构合理性上达成共识：
|
||
|
||
| 维度 | 评估 | 共识 |
|
||
|---|---|---|
|
||
| 依赖方向 | contracts → (none), cli → runtime/tui/llm/toolchain-cpp | ✓ 正确，无循环依赖 |
|
||
| 职责分离 | EventIngestor/EventStore/EventBus/Scheduler/ToolRegistry/PermissionEngine | ✓ 边界清晰 |
|
||
| 事务语义 | durable event + domain update 同事务，EventBus publish 在 commit 后 | ✓ 正确 |
|
||
| 状态机交互 | Main Agent ↔ Scheduler ↔ Worker ↔ Architecture Designer | ✓ 无死锁 |
|
||
|
||
**结论：架构设计合理，无内在冲突。**
|
||
|
||
---
|
||
|
||
## 7. 门禁判定
|
||
|
||
| 条件 | 状态 |
|
||
|---|---|
|
||
| P0 = 0 | **PASS** |
|
||
| 契约覆盖 100% | **PASS** |
|
||
| 事件覆盖 100% | **PASS** |
|
||
| DB Schema 覆盖 100% | **PASS** |
|
||
| 状态机覆盖 100% | **PASS** |
|
||
| 禁止路径全执行 | **PASS** |
|
||
| 架构无循环依赖 | **PASS** |
|
||
| 职责分离无泄漏 | **PASS** |
|
||
| 基线间冲突已收束 | **FAIL** (4 处 P1 未收束) |
|
||
|
||
**门禁结果：CONDITIONAL PASS**
|
||
|
||
详细设计在覆盖性和架构合理性上通过，但存在 4 处 P1 级问题需要在冻结前解决。
|
||
|
||
---
|
||
|
||
## 8. 修复建议优先级
|
||
|
||
| 优先级 | Finding | 建议处理 | 预计工作量 |
|
||
|---|---|---|---|
|
||
| **P0** | P1-01 Worker exit code 冲突 | 发布 ADR 明确权威定义 | 0.5h |
|
||
| **P1** | P1-02 PromptLayerLevel 不对齐 | 在 DD §10.2 记录设计决策 | 0.5h |
|
||
| **P1** | P1-03 EventStore.project 错误处理 | 在 DD §5.3 补充错误语义 | 0.5h |
|
||
| **P1** | P1-04 PromptLayerLoader 接口 | 在 DD §10.2 明确加载方式 | 0.5h |
|
||
| **P2** | P2-05 EventStore.project 措辞 | 拆分 DD §5.4 为两个表 | 1h |
|
||
| **P2** | P2-06 memory.promoted outbox | 明确 intent/completion 区分 | 0.5h |
|
||
| **P2** | P2-07 docs task 类型 | 决定是正式 task type 还是移除 | 0.5h |
|
||
| **P2** | P2-08 AgentType 不覆盖 runtime roles | 在 DD 中明确 runtime roles 处理 | 0.5h |
|
||
| **P2** | P2-09 contracts 包文件集命名 | 冻结唯一文件树 | 0.5h |
|
||
|
||
**总预计工作量：5-6 小时**
|
||
|
||
---
|
||
|
||
## 9. 最终结论
|
||
|
||
### 9.1 多模型审查一致性
|
||
|
||
四轮审查在以下方面达成一致：
|
||
- 覆盖性：100% 通过
|
||
- 架构合理性：通过
|
||
- 存在基线间冲突：需要修复
|
||
|
||
### 9.2 审查深度递进
|
||
|
||
| 轮次 | 模型 | 贡献 |
|
||
|---|---|---|
|
||
| 1 | DeepSeek | 建立覆盖性基线，确认无 P0 |
|
||
| 2 | MIMO 2.5 Pro | 发现内在一致性问题，升级 PromptLayer 为 P1 |
|
||
| 3 | GPT-5.5 Pro | 发现基线间冲突（Worker exit code） |
|
||
| 4 | Opus 4.8 | 验证前轮发现，根因分析，提供修复建议 |
|
||
|
||
### 9.3 建议
|
||
|
||
1. **立即处理**：P1-01 Worker exit code 冲突（发布 ADR）
|
||
2. **冻结前处理**：P1-02, P1-03, P1-04（在 DD 中补充设计决策）
|
||
3. **实现阶段处理**：P2 级问题（不阻塞冻结）
|
||
|
||
### 9.4 最终判定
|
||
|
||
**CONDITIONAL PASS — 详细设计可以进入实现阶段，但需要先解决 4 处 P1 级问题。**
|
||
|
||
预计修复工作量：2-3 小时（P1 级）+ 3-4 小时（P2 级）= 5-7 小时。
|