33a76a1ebc
迁移路径: /run/media/airlongdian/EasyU/AirCoding -> /home/airlongdian/DataDevices/AirWorkSpace/AirCoding Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
20 KiB
Executable File
20 KiB
Executable File
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 优势
- 逐契约派生：每个
interface-contracts-v1.md的接口都在详细设计中找到了对应的类/方法签名，字段完整，无遗漏。 - 55 个持久化事件全投影：
EventStore.project()的投影映射表（§5.4）逐行覆盖了event-registry-v1.md§3 的全部 55 个事件类型，域更新描述准确。 - 19 张 DB 表全仓储：每张
db-schema-v1.md表都有对应的仓储，项目级 DB（debug-records.db、learned-memory.db）有独立 Store 类，schema_meta由MigrationRunner管理。 - 6 个状态机完整：Main Agent、Scheduler、Task、Agent、Workspace、Capability 六个状态机全部覆盖，与基线转换条件一致。
- 10 条禁止路径全执行：
interface-contracts-v1.md§23 的 10 条禁止路径在详细设计中有明确的禁止点（§2 依赖方向 + §18.5 安全不变量）。 - 8 个 Mermaid UML 类图：覆盖 Contracts、Runtime Core、Scheduler、Tool/Permission、Worker/IPC、Provider、Context、Agents 八个子系统。
- 5 向可追溯性矩阵：Contracts→设计、状态机→设计、DB Schema→设计、Code View→设计、Overview→设计全部有映射表（§21）。
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 — 详细设计可以进入实现阶段。