33a76a1ebc
迁移路径: /run/media/airlongdian/EasyU/AirCoding -> /home/airlongdian/DataDevices/AirWorkSpace/AirCoding Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
321 lines
9.0 KiB
Markdown
Executable File
321 lines
9.0 KiB
Markdown
Executable File
# 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 核心实现，应优先处理。
|