admin/AirCoding
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
main
AirCoding/AirPlan/docs/architecture/opus4.8系统详细设计审查复查.md
AirCoding 2673e49cf8 Detailed design: fix four P2 findings from Opus 4.8 + DeepSeek reviews 
Independent full-scope audits by Opus 4.8 (R6) and DeepSeek V4 Pro (R7)
converged on the same four P2 findings. This commit closes all four:

F1 §10.2: EvidenceStore.list_for_task() → list_for_entity("task", task_id)
  The fictional method list_for_task() was not in contracts §14. Now uses
  the real contract method list_for_entity() with task as entity_type.

F5 §16.1: DoctorService.check_capability() changed from public (+) to
  private (-) with a clarifying comment. Only run() is in contracts §19.

F2 §22.7: Context and Compaction class diagram now shows the internal
  dependency edges ContextAssembler ..> EvidenceStore (L6) and
  ContextAssembler ..> SessionStore (L7/L8), matching §10.2.

F3 §22.4: Tool and Permission class diagram now shows ToolRegistry -->
  ToolDefinition (registers) and ToolRegistry --> ToolExecutor (invokes),
  matching §9.1.

Also adds the two full-scope review reports that identified these findings.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-01 14:23:45 +08:00

16 KiB
Raw Permalink Blame History

Opus 4.8 系统详细设计与 UML 类图全量审查复查

Date: 2026-06-01 Reviewer: Claude Opus 4.8 (independent full-scope re-audit) Scope: 全量复查 — 覆盖性 + 内在一致性 + 基线遵守 + 架构合理性 + 内在冲突 Target commit: af99aed（R 系列回归修复后） Inputs:

  • 详细设计：system-detailed-design.md（2290 行，23 章节，含 §22 8 张 Mermaid 类图）
  • 冻结基线：interface-contracts-v1.md、event-registry-v1.md、db-schema-v1.md、 runtime-semantics-v1.md、scheduler-state-machine-v1.md、main-agent-state-machine.md、 prompt-layering-v1.md、scope-escalation-v1.md、security-model-v1.md、tool-registry-v1.md、 capability-trust-v1.md、artifact-naming-v1.md、error-taxonomy-v1.md、baselineV1.md
  • 冻结概要设计：system-overview-design.md
  • 此前审查：DeepSeek / MIMO 2.5 Pro / GPT-5.5 Pro / Opus 4.8(R4) / Opus 4.7(R5 回归)

1. 审查方法

本次为独立全量复查，不预设此前 5 轮审查已经完备。从零重建以下证据链：

  1. 逐行通读 DD 全文（§0-§23，2290 行）
  2. 枚举式覆盖核对：用脚本从基线提取契约接口名 / 事件名 / DB 表名 / 状态机，再与 DD 逐一比对（comm -23 / comm -13 差集法）
  3. 基线遵守抽样核验：对 DD 中所有 Class.method() 形式的引用，回查契约是否真实存在该方法（这正是 R5 发现 current_profile() 越界的同类问题，本次扩大到全部点名方法）
  4. 架构合理性：依赖方向、职责分离、事件流时序、跨 DB outbox、FK-off 不变式
  5. UML 逐张审查：8 张类图的语法、类数、边与正文一致性
  6. 内在冲突：同一概念跨章节是否自洽

2. 总览结论

维度 状态
契约覆盖 ✅ 100%（23 个契约章节全部映射）
事件覆盖 ✅ 100%（55 durable + 7 ephemeral，含聚合写法）
DB Schema 覆盖 ✅ 100%（16 张主表 + 2 项目级 DB，schema_meta 归 MigrationRunner）
状态机覆盖 ✅ 100%（main / scheduler / task / agent / workspace / capability 共 6 个）
PromptLayer L0-L9 覆盖 ✅ 100%
10 条禁止边 ✅ 100% 显式继承
UML 类图 ✅ 8/8 存在且语法可解析
R 系列(R1-01~R2-02) 回归修复 ✅ 5/5 已闭合（本次复验）
架构合理性 ✅ 无循环依赖，职责分离清晰
新增 P0 0
新增 P1 0
新增 P2 4（F1/F5 契约方法越界，F2/F3 类图欠完整）
综合判定 CONDITIONAL PASS — 4 项 P2 不阻断实现，建议合并修复

3. 覆盖性矩阵

3.1 契约覆盖（interface-contracts-v1 → DD）

interface-contracts-v1.md 共 23 个章节（§2-§23），DD §21.1 逐一映射，复验全部命中：

契约章节 DD 章节 复验
§2-§4 原语 / 错误 / 实体引用 §3、§18.1 ✓
§6 事务存储 §4、§18.2 ✓
§7 Event Bus/Store/Ingestor §5 ✓ 三接口签名逐字一致
§8 项目/会话 §6 ✓
§9 Task/Scheduler §7 ✓
§10-§11 Worker/IPC/Result §8 ✓ exit code 与 baselineV1 §8 逐行一致
§12-§13 Tool/Permission §9 ✓
§14 Artifact/Evidence §11 ⚠ 见 F1
§15 Provider §12 ✓
§16 Context §10 ✓ PromptLayerLoader 4 方法签名逐字一致
§17 Projection/UI §13 ✓ ProjectionSnapshot 8 个投影字段全覆盖
§18 Capability §9.5 ✓
§19 Doctor §16 ⚠ 见 F5
§20 Debug/Memory §11.3 ✓ lookup_by_signature/by_task 存在
§21 Diagnostic §15 ✓
§22-§23 版本/边界规则 §3、§18.5 ✓ 10 条禁止边全继承

3.2 事件覆盖（event-registry-v1 → DD）

差集法核对（registry §6 索引 55 durable + 7 ephemeral）：

  • DD §5.4 Table A/B 显式列出 46 个事件名；
  • 差集中 12 个"未直接出现"的事件（agent.completed/failed/lost/cancelled、6 个 doctor.*、permission.prompt.requested/resolved）经核查均由 DD 的聚合写法覆盖：
    • | agent.completed/failed/lost/cancelled | update agents.status |（§5.4 L384）
    • | doctor.* | append (+ optional ...) |（§5.4 L409）
    • | permission.prompt.requested/resolved | append |（§5.4 L408）
  • 7 个 ephemeral 全部在 §5.5 与 §13.1 列出（含 command.stdout.delta/command.stderr.delta）。

结论：55 + 7 全覆盖，无遗漏。差集中出现的 agents.status/sessions.status/events_session.db 为投影目标列/库名，非事件名，属正常。

3.3 DB Schema 覆盖（db-schema-v1 → DD repositories）

db-schema §2-§18 共 17 表。DD §4.3 仓库清单覆盖 §3-§18 的 16 张业务表（一一对应），schema_meta（§2）由 MigrationRunner 持有（DD §4.2、§21.3 明确）。两张项目级 DB（debug-records.db/learned-memory.db，§20）由 DebugKnowledgeStore/LearnedMemoryStore 持有（§11.3）。

结论：17/17 表 + 2 项目级 DB 全覆盖。

3.4 状态机覆盖

状态机 基线 DD
Main Agent main-agent-state-machine.md §14.1、§20.1 ✓
Scheduler scheduler-state-machine-v1.md §4 §7、§20.2 ✓（11 状态全列）
Task status db-schema §7 §20.3 ✓
Agent status db-schema §10 §20.4 ✓
Workspace status db-schema §16 §20.5 ✓
Capability lifecycle capability-trust §7 §9.5、§20.6 ✓

6/6 状态机全覆盖。

3.5 需求覆盖（requirements → DD workflows）

  • C++ 全流程（configure/build/test/static-analysis/debug/fix/review）：DD §15 + §19.5 ✓
  • GUI/网络取证工具：通过 capability + tool 注册（§9.5、§15）✓
  • 静态分析（docs/staticanalysis.md）：CppcheckRunner + DiagnosticParser（§15）✓
  • TUI/HUD 投影：§13 ✓
  • Linux tier-1 release gate：§16（Doctor/release）+ overview §15 ✓

3.6 PromptLayer L0-L9 覆盖

DD §10.2 表 1 将 11 个 PromptLayerLevel 枚举值（含 system_debug）映射到 L0-L9，与 contracts §16 枚举、prompt-layering-v1 §2 完全对应。表 2 区分 PromptLayerLoader（L0/L1/L3/L5）与 ContextAssembler 内部装配（L2/L4/L6/L7/L8/L9）。✓

3.7 UML 类图覆盖（§22.1-§22.8）

图 类数 状态
§22.1 契约包 9 ✓
§22.2 运行时核心服务 9 ✓
§22.3 Scheduler 7 ✓
§22.4 Tool/Permission 5 ⚠ F3
§22.5 Worker/IPC 9 ✓ 5 个 Role 继承齐全
§22.6 Provider 6 ✓
§22.7 Context/Compaction 4 ⚠ F2
§22.8 Agents 2 ✓

8/8 存在且语法可解析。两处欠完整见 §7。

4. 基线遵守审查

抽取 DD 中所有 ClassName.method() 形式引用，回查契约真实性：

DD 引用 契约真实性 判定
PromptLayerLoader.load_role() contracts §16 存在 ✓
EvidenceStore.list_for_task() contracts §14 只有 list_for_entity() ✗ F1
EventBus.publish() contracts §7 存在 ✓
ContextAssembler.load_layers() DD 内部私有方法（-），非契约 ✓
SessionStore.referential_check() SessionStore 是 DD 内部聚合，非契约接口 ✓
ProjectLocator.locate() / ProjectInitializer.scaffold() DD 标记 IMPL 辅助类 ✓
DoctorService.check_capability() contracts §19 只有 run() ✗ F5
current_profile()（R5 旧问题） DD 中已 0 处、契约 0 处 ✓ R1-01 已闭合

R 系列复验：overview §10.3（R2-01）、agent.started 单状态 + §20.4（R1-02）、无 phase 字段（R1-03）、16 mandatory files（R2-02）均已正确落地。

5. 架构合理性审查

5.1 依赖方向与无循环

DD §2 复述 c4/module.md 的允许导入图：contracts ← llm/toolchain-cpp/tui/runtime ← cli，workers 仅依赖 contracts + WorkerRuntime IPC。无逆向边、无环。✓

5.2 职责分离

  • Scheduler vs WorkspaceManager（§7.5）：策略归 Scheduler、机制归 WorkspaceManager，9 行职责矩阵清晰，无泄漏。✓
  • EventStore vs 领域服务（§5.1、§5.3）：EventStore 只做事务投影，不创建 task/permission/memory；follow-up 由 owning service 发出。✓
  • ToolRegistry / PermissionEngine / CapabilityRegistry（§9）：所有副作用经 PermissionEngine；capability 永不绕过。✓

5.3 事件流一致性

producer → EventIngestor → (durable: EventStore tx + projection + post-commit publish | ephemeral: EventBus) 在 §5.1、§5.3、§18.2 三处描述一致；"publish AFTER commit"（contracts §7 rule 3）一致。✓

5.4 跨 DB outbox 一致性

§18.4 经 R1-03 修复后，采用"owning store 先外部写 → 成功后 ingest 单个完成态事件"模型；与 runtime-semantics §6.3-§6.4、event-registry §3 payload（无 phase 字段）一致；§5.4 Table B 与之呼应。✓ 无残留矛盾。

5.5 FK-off 应用层不变式

§18.3 列出 8 条不变式，与 runtime-semantics §14 逐条对应；SessionStore.referential_check() 在启动/周期运行。✓

6. 内在一致性与冲突审查

检查点 结果
§5.3 EventStore 正文 vs §22.2 类图 ✓ 一致（append/append_many/query + publish-after-commit 边）
§20.4 Agent 状态机 vs §5.4 agent.started 投影 ✓ R1-02 修复后自洽（单状态 + §20.4 过渡）
§10.3 Compaction 时序 vs §19.3 序列图 ✓ 一致（仅 summary.created 插行）
§4.4 derive_command_status vs contracts §17 CommandRunProjection.status ✓ 五值一致
§17 CLI 命令清单 vs overview §14 catalog ✓ DD 含 6 个 catalog 命令 + 5 个基础命令(run/init/doctor/e2e/release)，后者在 overview §4/§15 有据，属合理超集
§8.1 exit code vs baselineV1 §8 ✓ 6 个 code 逐行一致

未发现跨章节概念冲突或时序矛盾。

7. UML 类图详细审查（§22.1-§22.8 逐张）

  • §22.1 契约包：EventSource.kind 枚举与 §2 runtime-role 表协同；RuntimeEvent → EventSource、WorkerResult → Artifact/Evidence、AirError → EntityRef 边正确。✓
  • §22.2 核心服务：EventStore → EventBus : publishes after commit、ProjectionStore → EventBus : subscribes 准确反映事件流。✓
  • §22.3 Scheduler：6 个被组合类（TaskGraph/WavePlanner/RetryPlanner/WorkspaceManager/AgentMonitor/WorkerManager）齐全。建议旁注 "Scheduler owns policy; WorkspaceManager owns mechanism"（与 §7.5 呼应），非必须。
  • §22.4 Tool/Permission — F3：图中 ToolRegistry 缺少到 ToolDefinition / ToolExecutor 的关系边；正文 §9.1 明确 ToolRegistry 注册/调用这两者。建议补 ToolRegistry --> ToolDefinition : registers 与 ToolRegistry --> ToolExecutor : invokes。
  • §22.5 Worker/IPC：5 个 Role 实现 WorkerRole 继承齐全；docs TaskType 复用 ExecutorRole 无需新增节点，与 §8.3 一致。✓
  • §22.6 Provider：双 adapter 继承 + converter + normalizer 边正确。✓
  • §22.7 Context/Compaction — F2：图中 ContextAssembler 仅连 PromptLayerLoader/CompactionPolicy，但 §10.2 表 2 明确 ContextAssembler 内部装配 L2/L6/L7/L8 需读 EvidenceStore、SessionStore.messages/tool_runs/command_runs。类图低估了实际耦合。建议补 ContextAssembler --> EvidenceStore、ContextAssembler --> SessionStore（依赖型虚线即可）。
  • §22.8 Agents：MainAgent/ArchitectureDesigner → Scheduler/ContextAssembler/ProviderManager/EventIngestor 边正确；与 §2 "runtime role 不走 load_role" 决策一致。✓

8. 新发现（P0 / P1 / P2 分类）

F1 [P2] EvidenceStore.list_for_task() 不在契约

  • 位置：DD §10.2 表 2，L6 Evidence 行（L932）
  • 问题：引用 EvidenceStore.list_for_task()，但 contracts §14 EvidenceStore 仅声明 create() 与 list_for_entity(entity_type, entity_id)。
  • 根因：与 R5 的 current_profile() 同类——为给 L6 找一个明确来源，点名了不存在的方法。
  • 影响：实现 ContextAssembler 时找不到 list_for_task()；轻微，因为 list_for_entity("task", task_id) 即可替代。
  • 建议：改为 EvidenceStore.list_for_entity("task", task_id)（契约真实方法）。
  • 工作量：2 分钟

F5 [P2] DoctorService.check_capability() 不在契约

  • 位置：DD §16.1（L1201）
  • 问题：DoctorService 类列出 +check_capability(capability): Promise<DoctorIssue[]>（public +），但 contracts §19 DoctorService 仅声明 run(input): Promise<DoctorRunOutput>。
  • 根因：把内部分解步骤当成公共契约方法暴露。
  • 影响：与 §0 "不引入新公共契约" 约束冲突；轻微。
  • 建议：改为私有 -check_capability(...)（与同段 -self_bootstrap() 一致风格），或并入 run() 内部说明。
  • 工作量：1 分钟

F2 [P2] §22.7 类图缺 ContextAssembler 内部装配依赖边

  • 见 §7。建议补 ContextAssembler --> EvidenceStore / --> SessionStore 虚线依赖。
  • 工作量：3 分钟

F3 [P2] §22.4 类图缺 ToolRegistry → ToolDefinition/ToolExecutor 边

  • 见 §7。建议补两条注册/调用关系边。
  • 工作量：3 分钟

无 P0、无 P1。F1/F5 是契约边界的两处"点名了不存在的方法"，与本轮独立抽样法直接相关；F2/F3 是类图完整度问题，不影响正文设计正确性。

9. 门禁判定

条件 状态
P0 = 0 PASS
契约覆盖 100% PASS
事件覆盖 100% PASS
DB Schema 覆盖 100% PASS
状态机覆盖 100% PASS
L0-L9 覆盖 PASS
禁止路径全继承 PASS
架构无循环依赖 PASS
职责分离无泄漏 PASS
R 系列(R1/R2)修复已闭合 PASS
契约/payload 不变性（无越界方法/字段） FAIL（F1 + F5 两处契约方法越界）
UML 类图完整度 CONDITIONAL（F2 + F3 欠边，不影响正确性）

门禁结果：CONDITIONAL PASS — 覆盖性、架构、状态机全部 PASS；4 项 P2 不阻断实现，但建议在冻结前一并修复以保持契约纯净。

10. 多轮累积视角

轮次 模型 主要贡献 P0 P1 P2
R1 DeepSeek 全量覆盖性 0 0 3
R2 MIMO 2.5 Pro 内在一致性 0 2 5
R3 GPT-5.5 Pro 基线冲突检测 0 2 4
R4 Opus 4.8 验证 + 根因 0 2 5
R5 Opus 4.7 修复回归引入检测 0 3 2
R5-fix — R1-01~R2-02 闭合（commit af99aed） — — —
R6 Opus 4.8（本次全量复查） 契约方法越界抽样 + 类图完整度 0 0 4

累积说明：R1-R5 的 P1×4 + P2×9 + R 系列 5 项均已闭合。R6 在更系统的"点名方法 vs 契约"抽样下浮出 F1/F5（与 R5 的 current_profile() 同型，说明此类问题需要一次性全表扫描），以及两处类图欠边 F2/F3。无新增 P0/P1。

11. 最终结论与建议

11.1 设计成熟度

详细设计在**覆盖性、架构合理性、状态机一致性、基线遵守（主体）**四个维度均达标。事件 / 表 / 契约 / 状态机 / 禁止边 / L0-L9 / UML 七类对象 100% 覆盖，依赖无环，职责分离干净，跨 DB outbox 与 FK-off 不变式自洽。

11.2 剩余问题

仅剩 4 项 P2，全部为局部精修：

  • F1 / F5：两处"点名了不存在的契约方法"（EvidenceStore.list_for_task、DoctorService.check_capability），合计 3 分钟可改为真实方法 / 改私有。
  • F2 / F3：两张类图欠依赖边，合计 6 分钟补全。

11.3 建议

总工作量约 9 分钟即可收束全部 4 项 P2。这些不阻断进入实现阶段，但建议在正式冻结前一并修复，使契约纯净度与类图完整度达到 100%，避免实现者在 ContextAssembler / DoctorService 处遇到与 R5 同型的"找不到方法"困惑。

11.4 最终判定

CONDITIONAL PASS (R6) — 详细设计满足全量覆盖与结构正确性，R 系列回归修复全部闭合；本轮新增 4 项 P2（2 契约方法越界 + 2 类图欠边），均为分钟级修复，不阻断实现。

End of full-scope re-audit.

Reference in New Issue View Git Blame Copy Permalink