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：

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 的类型，例如：

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 包文件集为：

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 期望另一套文件集：

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