admin/AirCoding
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

System detailed design: four-model cross-review complete

Browse Source 
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>
This commit is contained in:
AirCoding
2026-05-29 18:57:13 +08:00
parent 8d9c4208fa
commit b668b185e1
11 changed files with 4323 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

320
AirPlan/docs/architecture/gpt5.5pro系统详细设计审查.md Normal file
View File

@@ -0,0 +1,320 @@
# GPT-5.5 Pro 系统详细设计审查
Date: 2026-05-29
Status: Requires repair before freeze
Auditor: GPT-5.5 Pro
Scope: `system-detailed-design.md` against frozen baselines, contracts, registry, runtime semantics, code view, and frozen overview.
本报告只记录本轮审查发现的合同级、语义级不一致，供后续统一处理。未对原有审计报告做修改。
---
## 1. Overall Verdict
`system-detailed-design.md` 当前还不能作为一致、可实施的详细设计冻结版。
主要问题不是章节缺失，而是几处上游冻结文档之间的语义冲突没有被详细设计收束，且其中两处在详细设计中被继续放大：
1. Worker 退出码语义冲突。
2. EventStore 投影职责越界。
3. `memory.promoted` / outbox 阶段语义自相矛盾。
4. `docs` task 类型未闭合。
5. Prompt role/profile 类型覆盖不完整。
6. contracts 包文件集仍有两套命名。
建议先修复这些合同级裂缝，再继续冻结详细设计。
---
## 2. Findings
### Finding 1 — High — Worker exit code 语义冲突
**问题**
Worker 退出码在不同权威文档中定义不一致。
`baselineV1.md` 定义：
- `0` = protocol-level completion, including task failed/blocked
- `1` = uncaught exception
- `2` = startup/protocol error
- `3` = permission error
- `5` = hard timeout killed
但 `system-overview-design.md` 和 `system-detailed-design.md` 采用另一套语义：
- `1` = task failed
- `2` = crashed
- `3` = protocol error
- `5` = permission/policy blocked
**证据**
- `baselineV1.md:351`
- `system-overview-design.md:856`
- `system-detailed-design.md:566`
**影响**
实现 `WorkerManager` 时，父进程会无法稳定区分：
- 任务失败但协议正常
- worker 崩溃
- 启动/协议错误
- 权限阻断
- 硬超时 kill
这会直接影响 Scheduler 的 retry、blocked、failed、lost 判定。
**建议处理**
统一以一份权威退出码表为准，并在详细设计中明确：
- task failed / blocked 是否仍通过 exit code `0` 返回 WorkerResult。
- 非零 exit code 只表示 worker/process/protocol 层异常，还是也表示业务任务失败。
- permission blocked 应归入 WorkerResult 还是进程退出码。
---
### Finding 2 — High — EventStore.project 职责越界
**问题**
`runtime-semantics-v1.md` 明确要求 EventStore 不应创建 scheduler tasks、permission decisions、memory promotions、doctor fixes 等策略动作。
但 `system-detailed-design.md` 的 durable projection map 中，仍把部分跨服务/跨存储行为写进 `EventStore.project`：
- `context.compaction.requested` -> insert compaction task if accepted
- `memory.promoted` -> append + write rules/skill/learned-memory.db
- `debug.record.created` -> insert/update debug-records.db
**证据**
- `runtime-semantics-v1.md:38`
- `runtime-semantics-v1.md:43`
- `system-detailed-design.md:350`
- `system-detailed-design.md:367`
**影响**
这会把 Scheduler、ExperienceMiner/Curator、DebugKnowledgeStore 等 owning service 的职责错误塞进 EventStore，并破坏 runtime-semantics 对事务边界的要求。
特别是：
- session DB event/domain projection 应在同一 SQLite transaction 内完成。
- 外部 DB/file side effect 应走 cross-store semantics/outbox/recovery 规则。
- EventStore 不应隐藏调度策略或 promotion 策略。
**建议处理**
将 `EventStore.project(event, tx)` 严格限制为 session DB domain table projection。
需要移出 EventStore 的行为：
- compaction task 创建：由 Scheduler 或 Context/Scheduler 协调服务处理。
- memory/rule/skill 写入：由 ExperienceMiner/Curator owning service 处理。
- debug-records.db 写入：由 DebugKnowledgeStore/Debugger flow 处理。
详细设计的 projection map 应只描述 event -> session DB domain row update，不描述跨 DB/文件副作用。
---
### Finding 3 — Medium — `memory.promoted` outbox 阶段语义自相矛盾
**问题**
`runtime-semantics-v1.md` 说明 `memory.promoted` 表示 promotion 已完成，并记录 target ref：
```text
candidate was approved/promoted by owning service
rule/skill/learned-memory write is performed by ExperienceMiner/Curator service
session event records completed promotion and target ref
```
如果文件/DB 写失败，应发 failure event，并让 candidate 保持未 promoted 或 pending repair。
但 `system-detailed-design.md` §18.4 又把 `memory.promoted` 同时当作：
1. step 1 intent/event
2. step 4 completion evidence
**证据**
- `runtime-semantics-v1.md:145`
- `runtime-semantics-v1.md:153`
- `system-detailed-design.md:1161`
**影响**
同一个 event 同时表示“准备 promotion”和“已经 promotion 成功”，会导致 recovery、dedupe、UI 状态、candidate 状态无法可靠判断。
**建议处理**
拆清事件阶段：
- 如果需要 intent：新增或使用明确的 request/intent event。
- `memory.promoted` 只表示 completed promotion + target ref。
- 写入失败时发 `memory.promotion.failed` 或对应 failure event，并保持 candidate 未完成或 pending repair。
---
### Finding 4 — Medium — `docs` task 类型进入 contracts/DB，但事件与 worker output 未闭合
**问题**
`TaskType` 和 DB enum 都包含 `docs`，但事件 registry 和 worker output contract 没有闭合这一路径。
已包含 `docs` 的位置：
- `TaskType`
- DB closed enum / task type
未包含 `docs` 的位置：
- `TaskCreatedPayload.type` 只允许五类 worker task，不含 `docs`。
- `WorkerOutputContract` 没有 docs result 类型。
- `system-detailed-design.md` 没有说明 `ArchitectureDesigner.update_architecture_docs` 是非 task service，还是 `docs` task 的正式执行路径。
**证据**
- `interface-contracts-v1.md:222`
- `db-schema-v1.md:666`
- `event-registry-v1.md:296`
- `interface-contracts-v1.md:435`
- `system-detailed-design.md:992`
**影响**
如果实现时按 DB/contracts 创建 `docs` task，则 event validation 和 worker result contract 会断裂；如果 `docs` 不是 task，则 DB/contracts 中的 task type 会误导实现。
**建议处理**
二选一收束：
1. `docs` 是正式 task type：补齐 event registry、worker output/result、Scheduler dispatch 规则。
2. `docs` 不是 task type：从 TaskType/DB enum 中移除或标注为非 worker internal type，并明确 ArchitectureDesigner 直接服务路径。
---
### Finding 5 — Medium — Prompt role/profile 类型覆盖不完整
**问题**
`prompt-layering-v1.md` 要求内置 role 覆盖：
- `main`
- `architecture`
- `scheduler`
- `executor`
- `reviewer`
- `debugger`
- `compactor`
- `experience_miner`
但 `interface-contracts-v1.md` 的 `AgentType` 只覆盖 worker role。`PromptLayerLoader.load_role(role: AgentType)` 因而无法类型化加载 main/architecture/scheduler role。
`system-detailed-design.md` 沿用了该接口，但没有补一个 `PromptRole` / `RuntimeRole` union 来承接非 worker role。
**证据**
- `prompt-layering-v1.md:71`
- `interface-contracts-v1.md:142`
- `interface-contracts-v1.md:1049`
- `system-detailed-design.md:769`
**影响**
Main Agent、Architecture Designer、Scheduler 的 prompt role/profile 在设计上没有类型入口，实现时可能被迫用 string escape hatch，削弱 prompt layering 的冻结语义。
**建议处理**
补一个覆盖所有 prompt profile 的类型，例如：
```ts
export type PromptRole =
| "main"
| "architecture"
| "scheduler"
| WorkerRole
```
并将 `PromptLayerLoader.load_role` 参数从 `AgentType` 调整为完整 prompt role 类型，或明确 `AgentType` 扩展为包含 runtime roles。
---
### Finding 6 — Low — contracts 包文件集仍有两套命名
**问题**
`c4/code-view.md` 期望 contracts 包文件集为：
```text
ids.ts
runtime.ts
event.ts
ipc.ts
task.ts
worker-result.ts
tool.ts
artifact.ts
evidence.ts
project.ts
provider.ts
permission.ts
ui.ts
error.ts
```
但 `system-overview-design.md` 期望另一套文件集：
```text
types.ts
errors.ts
events.ts
storage.ts
project.ts
scheduler.ts
workers.ts
tools.ts
permissions.ts
artifacts.ts
providers.ts
context.ts
projection.ts
capabilities.ts
doctor.ts
knowledge.ts
```
`system-detailed-design.md` 引用 code-view，但没有明确最终文件树如何处理这两套命名。
**证据**
- `c4/code-view.md:67`
- `system-overview-design.md:196`
**影响**
后续脚手架可能出现重复文件、错位 re-export、或者实现者不知道哪份文件树是冻结目标。
**建议处理**
在详细设计中冻结唯一 contracts package file tree，并明确另一套命名是：
- 已废弃；或
- overview-level logical grouping；或
- code-view 需要更新的旧版本。
---
## 3. Recommended Repair Order
1. 统一 Worker exit code 语义。
2. 重写 EventStore durable projection map，移除所有跨服务/跨存储副作用。
3. 拆清 `memory.promoted` 的 intent/completion 事件阶段。
4. 决定 `docs` 是否为正式 task type，并补齐或移除相关 contracts。
5. 补齐 prompt role/profile 类型模型。
6. 冻结 contracts 包唯一文件树。
前三项会直接影响 runtime 核心实现，应优先处理。