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

# 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 核心实现，应优先处理。