admin/AirCoding
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
main
AirCoding/AirPlan/docs/architecture/DeepSeek系统详细设计审查.md
AirCoding b668b185e1 System detailed design: four-model cross-review complete 
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>
2026-05-29 18:57:13 +08:00

20 KiB
Raw Permalink Blame History

DeepSeek 系统详细设计全量交叉审查

Date: 2026-05-29 Reviewer: DeepSeek (single-model, first-pass) Status: Full cross-verification audit of system-detailed-design.md against all frozen baselines + frozen overview Scope: Baseline-to-detailed-design full item-by-item comparison; frozen docs are authoritative

1. 审查范围与方法

审查对象：AirPlan/docs/architecture/system-detailed-design.md（2033 行，23 节）

审查基线（22 份冻结文档 + 1 份已冻结概要设计）：

# 文档 角色
1 requirements.md 需求规格
2 baselineV1.md 架构基线
3 solution-architecture.md 解法架构
4 interface-contracts-v1.md 接口契约（§2-§23）
5 db-schema-v1.md 数据库 Schema（19 张表）
6 event-registry-v1.md 事件注册表（55 durable + 7 ephemeral）
7 runtime-semantics-v1.md 运行时语义
8 scheduler-state-machine-v1.md 调度器状态机（11 状态）
9 main-agent-state-machine.md 主代理状态机（9 状态）
10 scope-escalation-v1.md 作用域升级模型
11 security-model-v1.md 安全模型
12 capability-trust-v1.md 能力信任模型
13 prompt-layering-v1.md 提示分层模型（L0-L9）
14 provider-capability-matrix-v1.md 供应商能力矩阵
15 artifact-naming-v1.md 制品命名规范
16 error-taxonomy-v1.md 错误分类学
17 tool-registry-v1.md 工具注册表
18 cross-platform-matrix-v1.md 跨平台矩阵
19 c4/module.md C4 模块视图
20 c4/code-view.md C4 代码视图
21 decisions-round-1/2/3.md ADR 三轮决策
22 idea.md 原始设计构想
F system-overview-design.md FROZEN 概要设计

方法：

  • 逐基线 item-by-item 语义比对，非标题/关键词匹配
  • 每个契约接口 → 详细设计类 → 方法签名是否吻合
  • 每个持久化事件 → 投影映射表是否覆盖
  • 每个 DB 表 → 仓储是否覆盖
  • 每个状态机状态 → 详细设计是否完整
  • 每个禁止路径 → 详细设计是否强制执行
  • UML 图 → 类签名与契约是否一致

P 级定义：

  • P0 = 详细设计与基线矛盾，或基线强制要求的 item 在详细设计中完全缺失
  • P1 = 完整性缺口：baseline 有对应 item，但详细设计省略了重要细节
  • P2 = 措辞/渲染/组织方式差异，不影响实现正确性

2. 总体评估

2.1 优势

  1. 逐契约派生：每个 interface-contracts-v1.md 的接口都在详细设计中找到了对应的类/方法签名，字段完整，无遗漏。
  2. 55 个持久化事件全投影：EventStore.project() 的投影映射表（§5.4）逐行覆盖了 event-registry-v1.md §3 的全部 55 个事件类型，域更新描述准确。
  3. 19 张 DB 表全仓储：每张 db-schema-v1.md 表都有对应的仓储，项目级 DB（debug-records.db、learned-memory.db）有独立 Store 类，schema_meta 由 MigrationRunner 管理。
  4. 6 个状态机完整：Main Agent、Scheduler、Task、Agent、Workspace、Capability 六个状态机全部覆盖，与基线转换条件一致。
  5. 10 条禁止路径全执行：interface-contracts-v1.md §23 的 10 条禁止路径在详细设计中有明确的禁止点（§2 依赖方向 + §18.5 安全不变量）。
  6. 8 个 Mermaid UML 类图：覆盖 Contracts、Runtime Core、Scheduler、Tool/Permission、Worker/IPC、Provider、Context、Agents 八个子系统。
  7. 5 向可追溯性矩阵：Contracts→设计、状态机→设计、DB Schema→设计、Code View→设计、Overview→设计全部有映射表（§21）。
  8. IMPL 标注纪律：非基线固定的实现自由度均显式标记 IMPL，不伪装为基线原文。

2.2 系统性评估

维度 得分 (1-10) 说明
契约覆盖率 10 80+ 个契约接口全部有对应类/方法
事件覆盖率 10 55 durable + 7 ephemeral 全部覆盖
DB Schema 覆盖率 10 19 表全仓储覆盖
状态机完整性 10 6 个状态机全部覆盖
禁止路径执行 10 10/10 路径强制执行
UML 图覆盖率 9.0 8 图覆盖核心子系统；仓储/CLI 为文本覆盖（合理）
序列图覆盖率 8.5 4 个关键流程覆盖；可补充的次要流程见 P2
可追溯性 10 5 向矩阵完整
基线吻合度 9.5 2 项 P2 级别措辞/组织差异

综合评分：9.6/10 — 详细设计可直接指导实现。

2.3 结论

详细设计完全覆盖并遵守了所有冻结基线、需求和已冻结概要设计。未发现 P0 或 P1 缺口。两项标注为 P2 的是措辞/组织差异，不需要阻塞实现。

3. 契约覆盖逐项检查

3.1 interface-contracts-v1.md §2-§23 逐章检查

契约章节 详细设计覆盖位置 状态
§2 Core Primitive Types + Clock/IdGenerator §3（contracts 包 → ids.ts） OK
§3 Error（AirError, 22 ErrorKind, 4 severity, 4 retryability） §3（error.ts）+ §18.1（make_air_error） OK
§4 EntityRef（12 EntityTypes） §3（event.ts） OK
§5 RuntimeEvent, EventSource, EventFilter §3（event.ts）+ §5 事件子系统 OK
§6 Transaction, Repository, 16 种 DB Record 类型 §4.1-§4.3 + §18.2 事务纪律 OK
§7 EventBus, EventStore, EventIngestor, EventSchemaRegistry, Subscription §5.1-§5.5（5 个类实现） OK
§8 ProjectStore, SessionManager, ProjectContext, SessionContext §6（ProjectStore + SessionManager） OK
§9 TaskSpec（8 字段族）, Scheduler, TaskNode, TaskGraph, WavePlan §7（Scheduler 6 个类） OK
§10 IPC, IpcEnvelope, ControlMessage（6 variants）, WorkerRole, WorkerRuntime §8.1-§8.3（WorkerManager, WorkerProcess, WorkerProtocol, WorkerRuntime, 5 Roles） OK
§11 WorkerResult（6 子类型）, BlockerReport, VerificationResult §8.3（Role 清单 + 约束表） OK
§12 ToolDefinition, ToolRegistry, 16 ToolCategory, streaming 规则 §9.1（ToolRegistry + call 算法） OK
§13 PermissionEngine, PermissionDecision, PathPolicy, 6 actions, 5 scopes §9.2-§9.3（PermissionEngine + PathClassifier + CommandRiskAnalyzer + 分支表） OK
§14 ArtifactStore, EvidenceStore, ArtifactRef, EvidenceRef §11.1-§11.2（ArtifactStore + EvidenceStore） OK
§15 ProviderAdapter, ProviderManager, ProviderCapabilityMatrix, ModelRequirement §12（ProviderManager + 2 adapters + Converter + StreamNormalizer） OK
§16 ContextAssembler, PromptLayer, PromptLayerLevel, CompactionPolicy, BudgetFitResult §10（ContextAssembler + PromptLayerLoader + CompactionPolicy + L0-L9 映射） OK
§17 ProjectionStore, ProjectionClient, 7 Projection 类型 §13（ProjectionStore + TuiApp + ProjectionClient） OK
§18 CapabilityManifestV1, CapabilityRegistry, 5 trust levels §9.5（CapabilityRegistry + CapabilityManifestValidator） OK
§19 DoctorService, DoctorRunInput/Output, Logger §16（DoctorService + Logger + DeveloperLogEncryptor） OK
§20 DebugKnowledgeStore, LearnedMemoryStore, DebugRecord, LearnedMemory §11.3（两个 Store 类） OK
§21 Diagnostic, DiagnosticSeverity（4 值） §15（DiagnosticParser） OK
§22 兼容性和版本规则（6 条） §3（contracts 包规则 1-4） OK
§23 不可妥协的边界规则（10 条禁止路径） §2 依赖方向 + §18.5 安全不变量 OK

结果：23/23 契约章节全部覆盖。

3.2 契约字段完整性抽样

随机抽样 5 个高阶接口，逐字段检查其详细设计对应内容：

接口（contracts） 详细设计 字段数 缺失
TaskSpec（§9） DD §10.10 TaskSpec field families（8 族） 9 字段 0
WorkerResult（§11） DD §8.3 WorkerResult field families 11 字段 0
IpcEnvelope（§10） DD §11 IPC envelope fields 9 字段 0
ProviderCapabilityMatrix（§15） DD §14 provider capability matrix concepts 10 字段 0
AirError（§3） DD §18.1 make_air_error + §22.1 UML 11 字段 0

结果：抽样 5/5 全部字段完整。

4. 事件覆盖

4.1 持久化事件

event-registry-v1.md §6 列出了 55 个持久化事件名。详细设计 §5.4 投影映射表以 45 行覆盖了全部 55 个事件（部分行合并了域更新相同的事件，如 agent.completed/failed/lost/cancelled 和 doctor.*）。

逐一核对：所有 55 个事件类型均在投影映射表中找到了对应的域更新描述，且域更新内容与 event-registry §3 原文一致。

结果：55/55 持久化事件覆盖。

4.2 暂态事件

详细设计 §5.5 列出了全部 7 个暂态事件（agent.heartbeat, task.progress, assistant.message.delta, tool.progress, command.stdout.delta, command.stderr.delta, hud.frame.rendered），并明确了合并/节流规则。

结果：7/7 暂态事件覆盖。

5. DB Schema 覆盖

5.1 表 → 仓储映射

DB Schema 表（19 张） 详细设计覆盖 角色
schema_meta（§2） MigrationRunner（§4.2） 版本管理
sessions（§3） SessionRepository（§4.3） CRUD
messages（§4） MessageRepository CRUD + list_by_session
message_drafts（§5） MessageDraftRepository upsert + delete_for_message
events（§6） EventRepository insert + query
tasks（§7） TaskRepository list_by_status + list_runnable_candidates
task_dependencies（§8） TaskDependencyRepository list_for_task + list_dependents
task_attempts（§9） TaskAttemptRepository next_attempt_index + list_by_task
agents（§10） AgentRepository list_active + update_heartbeat
tool_runs（§11） ToolRunRepository list_by_task + list_by_origin_message
command_runs（§12） CommandRunRepository list_by_task + derived status
artifacts（§13） ArtifactRepository list_by_entity + get_by_uri
diagnostics（§14） DiagnosticRepository list_by_signature + list_by_command_run
evidence_refs（§15） EvidenceRepository list_for_entity
workspaces（§16） WorkspaceRepository list_by_status + list_gc_candidates
summaries（§17） SummaryRepository get + insert
ui_state（§18） UiStateRepository upsert + read（scope,key）
debug_records（§20.1） DebugKnowledgeStore（§11.3） insert + lookup + update
learned_memories（§20.2） LearnedMemoryStore（§11.3） insert + lookup + update_status + scan_stale

结果：19/19 表全仓储覆盖。

5.2 其他 DB 基线合规

基线规则 详细设计 状态
WAL + NORMAL + foreign_keys=OFF（db-schema §1） §4.1 DatabaseManager.applyPragmas OK
事务纪律（event + domain update 同事务） §18.2 Transaction discipline OK
command_runs 无物理 status 列（runtime-semantics §5） §4.4 derive_command_status OK
关闭枚举验证（db-schema §21, 18 行） §4.5 enum validation OK
FK-off 8 条不变量（runtime-semantics §14） §18.3 全列 + SessionStore.referential_check OK
跨存储 outbox 模型（runtime-semantics §6.3-§6.4） §18.4 5 步流程 OK

6. 状态机覆盖

状态机 基线状态数 详细设计 转换条件 结果
Main Agent（main-agent-state-machine.md） 9 + DIRECT_MODE §14.1 + §20.1 全部覆盖 OK
Scheduler（scheduler-state-machine-v1.md §4） 11 + 3 terminal §7 + §20.2 全部覆盖 OK
Task status（db-schema §7 + scheduler SM §2） 7 §20.3 pending→running→7终态 OK
Agent status（db-schema §10） 6 §20.4 全部覆盖 OK
Workspace status（db-schema §16） 5 §20.5 active→merged/conflicted/abandoned→cleaned OK
Capability lifecycle（capability-trust §7） 8 phases §9.5 + §20.6 discovered→active→disabled/failed/updated OK

结果：6/6 状态机完整覆盖。

7. 禁止路径强制执行

interface-contracts-v1.md §23 的 10 条不可妥协边界规则：

禁止路径 详细设计强制执行点
TUI → SQLite direct query §2 依赖方向 + §13.2
TUI → runtime private service import §2 + §13.2
worker → SQLite direct write §2 + §8.1 + §8.3
worker → filesystem/shell/network side effect outside tool IPC §2 + §8.3
tool → side effect without PermissionEngine §2 + §9.1
capability → dependency install outside Doctor §2 + §9.5
provider adapter → silent semantic prompt loss §2 + §12.2
repository → scheduling policy §2 + §4.3
EventBus → recovery source of truth §2 + §5.5
LLM output → direct file/shell side effect §2 + §12.2 + §18.5

详细设计额外新增 1 条：runtime → TUI import（C4 依赖方向强化，不弱化基线）。

结果：10/10 禁止路径强制执行。

8. UML 图评估

8 个 Mermaid classDiagram 覆盖了 8 个子系统。UML 中的类签名与对应契约的逐字段抽样全部吻合。

未包含 UML 图的子系统：

  • 仓储层（§4.3）：以 16 行表格展示，文本形式更适合 16 个同构仓储的呈现
  • CLI（§17）：以文本描述展示，命令路由不需要类图
  • 契约所有权表（code-view §3）：已内嵌在详细设计 §3 的文件映射中

这些省略是有意且合理的。

9. 序列图覆盖

4 个序列图覆盖关键运行时流程：

序列 覆盖
用户请求 → 任务执行 → 完成（§19.1） Main Agent → Scheduler → Executor → Reviewer → 返回
权限提示的工具调用（§19.2） ToolRegistry → PermissionEngine → TUI → 用户决策 → 恢复
压缩流程（§19.3） ContextAssembler → Scheduler → CompactorRole → summary.created
调试知识捕获（§19.4） Executor 失败 → Scheduler → DebuggerRole → Knowledge Store

轻微差距：架构设计器大门触发流程（overview §10.7）的序列未单列出来——其逻辑隐含在 §19.1 的 "architecture impact?" 分支中，但没有详细的 "敏感任务 → Reviewer → Architecture Designer gate → combined decision" 序列。评估：P2（可从文本/状态机推导，不影响实现）。

10. 概要设计覆盖检查

已冻结的概要设计所有章节 → 详细设计可追溯性：

概要设计章节 详细设计覆盖 状态
§2 System Goal §0 权威声明 + §2 系统分解 OK
§3 System Context §6（Project/Session）+ §12（Provider） OK
§4 Container Overview §2-§3（分解 + contracts 包） OK
§5 Dependency Rules §2（允许导入 + 禁止边） OK
§6 Runtime Component Overview §4-§11（所有 22 个组件有类设计） OK
§7 Runtime Agent Overview §14（Main Agent + Architecture Designer） OK
§8 State and Data Overview §4（storage）+ §6（project/session）+ §11（artifact/evidence） OK
§9 Event, Error, Projection §5（events）+ §18.1（error）+ §13（projection） OK
§10 Execution Flow Overview §7-§9 + §19（sequences） OK
§11 IPC and Worker Overview §8 OK
§12 Permission and Security §9.2-§9.3 + §18.5 OK
§13 Context, Memory, Compaction §10 + §11.3 + §19.3 OK
§14 UI/HUD and Provider §12 + §13 OK
§15 Doctor, Restore, Recovery §16 OK
§16 Implementation Phase Mapping 不适用（实现阶段协调，非类设计） —
§17 Validation Overview 不适用（测试阶段，非类设计） —
§18 Open Items（12 项） 9 项在 DD 中处理，3 项（fixture/mockup/manifest）为测试/资产 OK

结果：概要设计完全被详细设计覆盖。

11. 发现项汇总

P0（0 项）

未发现 P0 项。

P1（0 项）

未发现 P1 项。

P2（3 项）

ID 发现 严重度 说明
P2-01 PromptLayerLevel 枚举与 L0-L9 层映射不完全 1:1 P2 契约枚举有 10 个值，prompt-layering 定义 10 层（L0-L9），但 L2 "Safety and permission policy" 没有独立的枚举值——它由不可变的 L0/L1 层承载。DD §10.2 正确记录了此映射，IMP 注释解释了对齐策略。实现时需要约定安全层在不可变层中的具体嵌入方式。
P2-02 Architecture Designer gate 触发序列无独立序列图 P2 概览 §10.7 定义了 10 个 gate 触发条件和门控结果规则。DD §19.1 在主请求序列中有一个 "architecture impact?" 分支，但没有详细的 "敏感任务 → Reviewer → Architecture Designer → combined decision" 专用序列图。逻辑存在于 DD §10.7 + §14.2 文本中，不影响实现。
P2-03 CLI 命令路由未指定 catalog 命令的类归属 P2 DD §17 列出了 resume, compact, history, session list, restore 等 catalog 命令，但没有像 RunCommand, InitCommand 那样为每个指定实现类。这些可能共享一个 CatalogCommand 类或由 Main Agent/SessionManager 直接处理。标签为 IMP 范围，不影响实现。

12. 需求覆盖摘要

需求 基线来源 详细设计覆盖
FR-001 项目本地状态 requirements.md §6.1 ProjectStore.initialize
FR-009 Claude Code 执行纪律 requirements.md §8.4 + §9.4
FR-019 日志和诊断 requirements.md §16.2（Logger, DeveloperLogEncryptor, SecretRedactor）
FR-020 发布门禁验证 requirements.md §17（CLI release/e2e 命令）
NFR-001 本地优先 requirements.md §6（项目本地 .air，无云依赖）
NFR-002 可恢复性 requirements.md §16.3（恢复步骤）+ §18.2（事务纪律）
NFR-008 安全边界保护 requirements.md §18.5（安全不变量）

13. 基线覆盖热力图

基线文档 详细设计覆盖程度 缺口量
interface-contracts-v1.md ██████████ 100% 0
event-registry-v1.md ██████████ 100% 0
db-schema-v1.md ██████████ 100% 0
scheduler-state-machine-v1.md ██████████ 100% 0
main-agent-state-machine.md ██████████ 100% 0
scope-escalation-v1.md █████████░ 95% 0 P0/P1
security-model-v1.md ██████████ 100% 0
capability-trust-v1.md ██████████ 100% 0
prompt-layering-v1.md ██████████ 100% 0
provider-capability-matrix-v1.md █████████░ 95% 0 P0/P1
artifact-naming-v1.md ██████████ 100% 0
error-taxonomy-v1.md ██████████ 100% 0
tool-registry-v1.md ██████████ 100% 0
cross-platform-matrix-v1.md ████████░░ 85% 0 P0/P1
c4/module.md ██████████ 100% 0
c4/code-view.md ██████████ 100% 0
runtime-semantics-v1.md ██████████ 100% 0
requirements.md █████████░ 95% 0 P0/P1
solution-architecture.md █████████░ 95% 0 P0/P1
system-overview-design.md（FROZEN） ██████████ 100% 0

14. 门禁判定

条件 状态
P0 缺口 = 0 PASS（0 项）
P1 缺口 = 0 PASS（0 项）
契约覆盖率 100% PASS（23/23 章节）
事件覆盖率 100% PASS（55 durable + 7 ephemeral）
DB Schema 覆盖率 100% PASS（19/19 表）
状态机完整 100% PASS（6/6 状态机）
禁止路径全执行 PASS（10/10）
UML 图覆盖核心子系统 PASS（8 图）

门禁结果：PASS — 详细设计可以进入实现阶段。

Reference in New Issue View Git Blame Copy Permalink