AirCoding/AirPlan/docs/architecture/mimo2.5概要设计审查.md

# MIMO v2.5 概要设计全量交叉审查

Date: 2026-05-29
Reviewer: MIMO v2.5
Status: Full traceability audit of `system-overview-design.md` against all 24 frozen baselines
Scope: Baseline-to-overview full item-by-item comparison; frozen docs are authoritative, overview is amendable

---

## 1. 审查范围与方法

审查对象：`AirPlan/docs/architecture/system-overview-design.md`（603 行）

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

额外参考：`gpt5概要设计审查.md`（GPT-5 审查，日期同日）

方法：
- 逐基线 item-by-item 语义比对，非标题/关键词匹配
- 对 GPT5 审查逐项验证，标注误判或遗漏
- 从三个视角分别审查：架构一致性、工程可实现性、需求对齐
- 冻结基线不修改，概要设计标注差异并解决

---

## 2. 总体结论

`system-overview-design.md` 在系统目标、容器视图、运行时组件、事件/投影、执行流、权限、上下文、UI/HUD、Doctor/restore、验证门禁等大方向上与基线一致。全文结构清晰，作为概要设计有良好的整体骨架。

但存在以下系统性缺口：

- **14 份冻结基线未列入源文档**（§1），下游设计无法溯源
- **全局 `~/.air/` 文件系统布局完全缺失**，project_id UUID 未提及
- **执行纪律（Claude Code 原语）未作为系统级约束**
- **权限边界规则不完整**（realpath、`.git/` 保护、build 目录、`~/.air/` 绕过、`sudo` 语义、静态白名单、项目外备份）
- **IPC 退出码与基线矛盾**
- **TaskSpec/WorkerResult 字段族和 failed/blocked 语义未展开**
- **SQLite 消息存储不变量未完整**
- **日志、迁移、扫描器、分发、测试分类、contracts 包文件清单缺失**
- **参考项目影响和边界未说明**
- **技术栈细节缺失**

以下按基线逐项列出缺口、偏差和矛盾。

---

## 3. 逐基线缺口清单

### 3.1 requirements.md（需求规格）

#### 缺口 R-01：FR-009 Claude Code 执行原语未作为系统约束

- 来源：`requirements.md` §3 FR-009
- 现状：概要设计 §10.5 提到了 Architecture Designer gate，但未将 read-before-edit、exact conservative edits、small patches、no unrelated refactors、verification-before-completion 作为系统级约束
- 严重性：P0（影响下游实现质量基准）

#### 缺口 R-02：FR-019 日志和诊断缺失

- 来源：`requirements.md` §3 FR-019
- 现状：概要设计无日志章节
- 严重性：P1

#### 缺口 R-03：FR-020 Release Gate 覆盖不完整

- 来源：`requirements.md` §3 FR-020
- 现状：概要设计 §17 列出了验证命令但未区分 unit/integration/E2E 三层定义
- 严重性：P1

#### 缺口 R-04：约束条件 §5 未完整列出

- 来源：`requirements.md` §5 Constraints
- 现状：TypeScript on Bun、Bun workspaces + Turborepo、OpenTUI/Solid、NDJSON over stdio、SQLite WAL/NORMAL/fk OFF、Anthropic canonical、Python subprocess-only、binary tarball 均未在概要设计中显式说明
- 严重性：P1

#### 缺口 R-05：Acceptance Notes §6 未作为设计目标引用

- 来源：`requirements.md` §6
- 现状：13 条验收标准未映射到概要设计的验证章节
- 严重性：P2

---

### 3.2 baselineV1.md（架构基线）

#### 缺口 B-01：产品定位缺失"Not a plugin/wrapper"声明

- 来源：`baselineV1.md` §1
- 现状：概要设计 §2 说"self-owned, Linux-first, local AI coding runtime"但未明确"not a Claude Code plugin/wrapper"
- 严重性：P1

#### 缺口 B-02：完整编码循环未列出

- 来源：`baselineV1.md` §1 Core loop
- 现状：概要设计未列出完整的 requirement → architecture → code reading → implementation planning → build → static analysis → test → run/debug → evidence analysis → fix → change summary → experience mining 循环
- 严重性：P1

#### 缺口 B-03：参考项目影响和边界缺失

- 来源：`baselineV1.md` §2（OpenCode、Claude Code、Hermes、Codex、Claude Skills、asciinema/Atuin/claude-hud）
- 现状：概要设计未说明参考影响和复用边界
- 严重性：P1

#### 缺口 B-04：技术栈细节缺失

- 来源：`baselineV1.md` §3
- 现状：Bun、Bun workspaces + Turborepo、`@opentui/solid`/`@opentui/core`/`@opentui/keymap`、SQLite per session、NDJSON over stdio、Python subprocess-only、binary tarball 未显式列出
- 严重性：P1

#### 缺口 B-05：未来语言包和 runtime 不依赖 tui 不变量缺失

- 来源：`baselineV1.md` §4
- 现状：`packages/toolchain-python`、`toolchain-rust`、`toolchain-js` 未提及；`runtime must never depend on tui` 未显式说明
- 严重性：P2

#### 缺口 B-06：全局 `~/.air/` 布局完全缺失

- 来源：`baselineV1.md` §5 Global User Directory
- 现状：概要设计 §8.1 只列出项目目录，全局 `~/.air/` 完全缺失（config.yaml、models.yaml、permissions.yaml、compaction-rules.md、project-index.db、cache/、resources/、skills/、logs/）
- 严重性：P0

#### 缺口 B-07：project_id UUID 未提及

- 来源：`baselineV1.md` §5："project_id is a stable UUID generated at initialization and stored in .air/shared/project.json"
- 现状：概要设计未提及
- 严重性：P0

#### 缺口 B-08：`.air/local/` 应 gitignore 未提及

- 来源：`baselineV1.md` §5 Recommended `.gitignore`
- 现状：概要设计未提及
- 严重性：P2

#### 缺口 B-09：Main Agent idle-ready 规则未显式

- 来源：`baselineV1.md` §6 Main Agent："Must remain responsive and idle-ready / Does not perform background work itself"
- 现状：概要设计 §7 表格只说"in runtime process"，未强调 idle-ready 规则
- 严重性：P0

#### 缺口 B-10：Scheduler 详细职责未展开

- 来源：`baselineV1.md` §6 Scheduler："Reads TaskGraph / Computes dependency order, write-area conflicts, waves, retries, workspaces / Spawns child agents / Monitors heartbeat / Handles merge coordination"
- 现状：概要设计 §6 表格只说"TaskGraph, wave planning, retries, workspaces, worker lifecycle"
- 严重性：P1

#### 缺口 B-11：Worker loops 是独立实现未强调

- 来源：`baselineV1.md` §6："Worker loops are independent implementations, not one generic shared loop"
- 现状：概要设计 §7 表格提到各角色但未强调此不变量
- 严重性：P2

#### 缺口 B-12：RuntimeEvent envelope 字段和 route 规则未展开

- 来源：`baselineV1.md` §7 envelope 定义 + route append-only 规则 + EventStore 决定持久化策略 + payload schema 变更需递增 event version
- 现状：概要设计 §9 提到事件流但未展开 envelope 字段和规则
- 严重性：P0

#### 缺口 B-13：IPC envelope 字段和退出码未展开

- 来源：`baselineV1.md` §8（IPC envelope、stdout-only 协议、stderr 致命回退、退出码映射）
- 现状：概要设计 §11 提到了握手和消息类别但未展开 envelope 字段
- 严重性：P0

#### 缺口 B-14：TaskSpec/WorkerResult 字段族和 failed/blocked 语义缺失

- 来源：`baselineV1.md` §9
- 现状：概要设计未展开 TaskSpec 字段族和 WorkerResult 字段族，`failed` vs `blocked` 语义未定义
- 严重性：P0

#### 缺口 B-15：ToolDefinition schema 验证、shell.run 对应 Bash、流式工具规则缺失

- 来源：`baselineV1.md` §10
- 现状：概要设计 §10.4 提到了 ToolRegistry 但未展开这些细节
- 严重性：P1

#### 缺口 B-16：Doctor first-start/fix 语义不完整

- 来源：`baselineV1.md` §11（first startup always asks before doctor --fix even in high-permission mode）
- 现状：概要设计 §15 未提及此语义
- 严重性：P1

#### 缺口 B-17：权限边界规则不完整

- 来源：`baselineV1.md` §12
- 现状：概要设计 §12 提到了权限评估顺序但缺少以下边界规则：
  - realpath symlink 解析
  - `.git/` 写保护
  - build 目录不受限
  - `~/.air/` 内部绕过 PermissionEngine
  - `sudo` 不自动高危
  - 静态高危白名单 + LLM escape hatch
  - 项目外写入备份到 `.air/local/backups/`
- 严重性：P0

#### 缺口 B-18：Canonical message 存储不变量不完整

- 来源：`baselineV1.md` §13
- 现状：概要设计 §8.2 提到了 messages 表但未说明以下不变量：
  - messages 存储完整 Anthropic canonical content JSON
  - message_drafts 流式完成后删除
  - message_parts 不是源表（V1 不使用）
  - 查询友好列优先于解析 JSON
- 严重性：P0

#### 缺口 B-19：Contracts 包文件清单缺失

- 来源：`baselineV1.md` §14 列出了 packages/contracts/src/ 的文件清单
- 现状：概要设计 §4 表格只说"Shared TypeScript public contracts"
- 严重性：P1

#### 缺口 B-20：Artifact 命名和布局摘要缺失

- 来源：`baselineV1.md` §15
- 现状：概要设计未引用 artifact-naming-v1.md 的 URI/ID 命名规范
- 严重性：P2

#### 缺口 B-21：Context/Compaction 规则格式和位置不完整

- 来源：`baselineV1.md` §15（Compaction rules use Markdown + YAML frontmatter、三个位置、copy-on-write 语义）
- 现状：概要设计 §13 提到了 compaction rules 但未说明格式和位置
- 严重性：P1

#### 缺口 B-22：Memory/Skills 路径和 promotion 策略缺失

- 来源：`baselineV1.md` §16（project rules 路径、skills 路径、promotion 策略、debug sharing 规则）
- 现状：概要设计 §13 提到了 ExperienceMiner 触发但未说明路径和策略
- 严重性：P1

#### 缺口 B-23：Provider 能力矩阵摘要缺失

- 来源：`baselineV1.md` §17（native providers、compatible providers、同提供商切换无格式转换成本、V1 session 选择固定）
- 现状：概要设计 §14 提到了 provider/model 选择固定但未列出 provider 列表
- 严重性：P1

#### 缺口 B-24：OpenCode UI 复用边界缺失

- 来源：`baselineV1.md` §18
- 现状：概要设计未说明 OpenCode 复用的具体 UI 原语列表和不复用 SDK/sync/session 业务状态的规则
- 严重性：P2

#### 缺口 B-25：UI 设计资源能力缺失

- 来源：`baselineV1.md` §19
- 现状：概要设计未提及可选 `ui-design-assets` 能力
- 严重性：P2

#### 缺口 B-26：C++ 工具链细节不完整

- 来源：`baselineV1.md` §20
- 现状：概要设计 §10.6 提到了 cpp workflow 但缺少以下细节：
  - CMake Ninja-first/Make fallback
  - CTest/GoogleTest
  - cppcheck 内置，clang-tidy 后续
  - clangd CLI mode
  - compile_commands.json 按需生成不缓存
  - build-system 冲突展示给用户
  - 内置修复优先然后路由 Debugger
- 严重性：P1

#### 缺口 B-27：项目初始化/扫描器细节缺失

- 来源：`baselineV1.md` §21
- 现状：概要设计 §10.1 提到了"locate or initialize project"但缺少：
  - full metadata-only scanner（完整目录树、无排除、无深度限制）
  - extension stats / special files / git summary
  - LLM ProjectProfile + 用户确认
  - schema path 检测
- 严重性：P1

#### 缺口 B-28：Schema 迁移流程缺失

- 来源：`baselineV1.md` §22
- 现状：概要设计未提及迁移流程（检测 schema 版本、用户确认、备份、失败回滚）
- 严重性：P1

#### 缺口 B-29：日志和 Doctor Bundle 缺失

- 来源：`baselineV1.md` §23
- 现状：概要设计未提及双日志（air.log / air.developer.log）、加密 dev log、7 天保留、doctor bundle 不自动脱敏/不自动上传
- 严重性：P1

#### 缺口 B-30：测试分类缺失

- 来源：`baselineV1.md` §24
- 现状：概要设计 §17 列出了验证命令但未定义 unit/integration/E2E 三层
- 严重性：P1

#### 缺口 B-31：分发细节缺失

- 来源：`baselineV1.md` §25
- 现状：概要设计未提及 tarball 内容（bin/air、resources/、LICENSE）、resources 内容、无 npm/brew/apt/winget 直到稳定
- 严重性：P1

#### 缺口 B-32：冻结基线完整列表不完整

- 来源：`baselineV1.md` §26
- 现状：概要设计 §1 的 source documents 列表只有 11 项，缺少 14 份冻结基线
- 严重性：P0

---

### 3.3 solution-architecture.md（解法架构）

概要设计与解法架构高度一致，因为两者都是同一作者在同一时间段产出。以下为少量差异：

#### 差异 SA-01：容器视图中 `packages/contracts` 依赖方向图略有简化

- 来源：`solution-architecture.md` §4
- 现状：概要设计 §4 的 ASCII 图中 contracts 的位置略有差异但语义一致
- 严重性：无实质差异

---

### 3.4 interface-contracts-v1.md（接口契约）

#### 缺口 IC-01：IPC envelope 完整字段未展开

- 来源：`interface-contracts-v1.md` §10（IpcEnvelope 完整定义）
- 现状：概要设计 §11 只列出了消息类别，未展开 envelope 字段
- 严重性：P0

#### 缺口 IC-02：WorkerResult 契约细节未展开

- 来源：`interface-contracts-v1.md` §11（WorkerResult、ExecutorResult、ReviewerResult、DebuggerResult、CompactorResult、ExperienceMinerResult、BlockerReport）
- 现状：概要设计未展开
- 严重性：P0

#### 缺口 IC-03：ToolRegistry 契约细节未展开

- 来源：`interface-contracts-v1.md` §12（ToolRegistry、ToolExecutor、StreamingToolExecutor、ToolResultEnvelope）
- 现状：概要设计只提到了 ToolRegistry 概念
- 严重性：P1

#### 缺口 IC-04：Projection/UI 契约细节未展开

- 来源：`interface-contracts-v1.md` §17（ProjectionSnapshot 完整定义、ProjectionClient、UiCommandChannel）
- 现状：概要设计 §14 只提到了 ProjectionStore 概念
- 严重性：P2

#### 缺口 IC-05：Capability 契约细节未展开

- 来源：`interface-contracts-v1.md` §18（CapabilityManifestV1 完整定义）
- 现状：概要设计只提到了 CapabilityRegistry 概念
- 严重性：P1

---

### 3.5 db-schema-v1.md（数据库 Schema）

#### 缺口 DB-01：SQLite 运行时设置未完整说明

- 来源：`db-schema-v1.md` §1
- 现状：概要设计 §8.2 提到了 foreign_keys OFF 但未说明 WAL + synchronous NORMAL
- 严重性：P1

#### 缺口 DB-02：schema_meta 表缺失

- 来源：`db-schema-v1.md` §2
- 现状：概要设计 §8.2 的表列表中缺少 `schema_meta`
- 严重性：P1

#### 缺口 DB-03：Canonical message 存储规则未完整

- 来源：`db-schema-v1.md` §4（canonical_format = "anthropic"、content_json）和 §5（draft 删除规则）
- 现状：概要设计 §8.2 未说明这些规则
- 严重性：P0

#### 缺口 DB-04：闭合枚举清单缺失

- 来源：`db-schema-v1.md` §21（完整闭合枚举清单）
- 现状：概要设计未引用
- 严重性：P2

#### 缺口 DB-05：project-level DBs Schema 未展开

- 来源：`db-schema-v1.md` §20（debug-records.db、learned-memory.db 的完整 Schema）
- 现状：概要设计 §8.3 只列出了用途
- 严重性：P2

---

### 3.6 event-registry-v1.md（事件注册表）

#### 缺口 ER-01：Event envelope 字段和规则未展开

- 来源：`event-registry-v1.md` §1 和 §2
- 现状：概要设计 §9 只提到了事件流但未展开 envelope 字段、route append-only 规则、EventStore 决定持久化策略、payload schema 变更需递增 event version
- 严重性：P0

#### 缺口 ER-02：持久化和事务规则未完整

- 来源：`event-registry-v1.md` §2（7 条持久化规则）
- 现状：概要设计 §8.2 和 §9 部分覆盖但不完整
- 严重性：P1

#### 缺口 ER-03：V1 事件类型索引未列出

- 来源：`event-registry-v1.md` §6（完整 durable + ephemeral 事件类型索引）
- 现状：概要设计 §9 只列出了事件族名称
- 严重性：P2

---

### 3.7 runtime-semantics-v1.md（运行时语义）

#### 缺口 RS-01：Event Ingestion Boundary 未完整

- 来源：`runtime-semantics-v1.md` §2
- 现状：概要设计 §6 提到了 EventIngestor 但未展开职责
- 严重性：P1

#### 缺口 RS-02：Heartbeat Semantics 未展开

- 来源：`runtime-semantics-v1.md` §4（5 秒合并间隔）
- 现状：概要设计未提及
- 严重性：P2

#### 缺口 RS-03：Command Run Status Semantics 未说明

- 来源：`runtime-semantics-v1.md` §5（派生状态规则）
- 现状：概要设计未提及
- 严重性：P2

#### 缺口 RS-04：Cross-DB 和 File Transaction Semantics 未说明

- 来源：`runtime-semantics-v1.md` §6（session DB first intent + external write + completion/failure event + restart reconciliation）
- 现状：概要设计 §8.3 只提到了"Cross-DB writes use session-DB-first intent"
- 严重性：P1

#### 缺口 RS-05：FK-Off Application Invariants 未展开

- 来源：`runtime-semantics-v1.md` §14（8 条不变量 + 执行规则）
- 现状：概要设计 §8.2 只提到了"foreign_keys = OFF is compensated by repository-level invariant checks and startup orphan scans"
- 严重性：P1

#### 缺口 RS-06：Workspace GC Policy 未说明

- 来源：`runtime-semantics-v1.md` §15（5 条保留规则）
- 现状：概要设计未提及
- 严重性：P2

#### 缺口 RS-07：Direct Mode Semantics 未展开

- 来源：`runtime-semantics-v1.md` §16（6 条规则）
- 现状：概要设计 §10.3 只列出了基本流程
- 严重性：P1

#### 缺口 RS-08：ExperienceMiner Trigger Ownership 未展开

- 来源：`runtime-semantics-v1.md` §17（Scheduler owns trigger creation; ExperienceMiner never self-triggers）
- 现状：概要设计 §13 只列出了触发条件
- 严重性：P1

#### 缺口 RS-09：Doctor Self-Bootstrap 未展开

- 来源：`runtime-semantics-v1.md` §18（5 步自检）
- 现状：概要设计 §15 只列出了检查类别
- 严重性：P2

#### 缺口 RS-10：air restore Semantics 未展开

- 来源：`runtime-semantics-v1.md` §19（三种粒度）
- 现状：概要设计 §15 只列出了三种模式
- 严重性：P2

#### 缺口 RS-11：Execution Primitive Semantics 未展开

- 来源：`runtime-semantics-v1.md` §9（read-before-edit token、exact edit behavior、patch behavior、completion gate）
- 现状：概要设计未展开这些语义
- 严重性：P0

---

### 3.8 c4/module.md（C4 模块视图）

概要设计与 C4 模块视图基本一致。少量差异：

#### 差异 M-01：运行时组件表更详细

- 来源：`c4/module.md` §4
- 现状：概要设计 §6 的组件表基本覆盖了 C4 模块视图的内容
- 严重性：无实质差异

---

### 3.9 c4/code-view.md（C4 代码视图）

#### 缺口 CV-01：Contracts 包文件清单缺失

- 来源：`c4/code-view.md` §3（packages/contracts/src/ 完整文件清单）
- 现状：概要设计未列出
- 严重性：P1

#### 缺口 CV-02：Runtime 包目录结构缺失

- 来源：`c4/code-view.md` §4（packages/runtime/src/ 完整目录结构）
- 现状：概要设计 §18 Open Items 中列为详细设计内容，可接受
- 严重性：N/A

---

### 3.10 main-agent-state-machine.md（主代理状态机）

#### 缺口 MAS-01：Main Agent 状态机未引用

- 来源：`main-agent-state-machine.md`（完整状态机定义）
- 现状：概要设计未引用此文档
- 严重性：P0

#### 缺口 MAS-02：Main Agent Idle Principle 未引用

- 来源：`main-agent-state-machine.md`："Main Agent must remain idle and responsive"
- 现状：概要设计未显式说明
- 严重性：P0

#### 缺口 MAS-03：Direct Mode Rules 未完整

- 来源：`main-agent-state-machine.md` §Direct Mode Rules（6 条规则）
- 现状：概要设计 §10.3 只列出了基本流程
- 严重性：P1

---

### 3.11 scheduler-state-machine-v1.md（调度器状态机）

#### 缺口 SSM-01：Scheduler 状态机未引用

- 来源：`scheduler-state-machine-v1.md`（完整状态机定义）
- 现状：概要设计未引用此文档
- 严重性：P0

#### 缺口 SSM-02：Task Status Model 未展开

- 来源：`scheduler-state-machine-v1.md` §2（7 种状态含义和 Scheduler 动作）
- 现状：概要设计未展开
- 严重性：P1

#### 缺口 SSM-03：Retry Policy 未展开

- 来源：`scheduler-state-machine-v1.md` §5（7 条重试规则）
- 现状：概要设计未展开
- 严重性：P1

#### 缺口 SSM-04：Model Assignment Policy 未展开

- 来源：`scheduler-state-machine-v1.md` §6
- 现状：概要设计未展开
- 严重性：P2

#### 缺口 SSM-05：Resource-Aware Concurrency 未展开

- 来源：`scheduler-state-machine-v1.md` §7（8 种资源约束）
- 现状：概要设计未展开
- 严重性：P2

---

### 3.12 scope-escalation-v1.md（作用域升级模型）

#### 缺口 SE-01：Scope Escalation Model 未引用

- 来源：`scope-escalation-v1.md`（完整升级模型）
- 现状：概要设计 §10.5 的 Architecture Designer gate 部分覆盖了升级规则，但未引用此文档
- 严重性：P0

#### 缺口 SE-02：ScopeImpactLevel 类型未列出

- 来源：`scope-escalation-v1.md` §2（7 种级别）
- 现状：概要设计未列出
- 严重性：P1

#### 缺口 SE-03：Worker Self-Escalation Contract 未说明

- 来源：`scope-escalation-v1.md` §9
- 现状：概要设计未说明
- 严重性：P1

---

### 3.13 security-model-v1.md（安全模型）

#### 缺口 SM-01：安全模型未引用

- 来源：`security-model-v1.md`（完整安全模型）
- 现状：概要设计 §12 部分覆盖但未引用此文档
- 严重性：P0

#### 缺口 SM-02：Permission Profiles 未列出

- 来源：`security-model-v1.md` §3（low/normal/high/developer）
- 现状：概要设计未列出
- 严重性：P1

#### 缺口 SM-03：Path Security 细节不完整

- 来源：`security-model-v1.md` §4（PathRiskCategory 9 种类别、realpath、.git/ 保护、build 目录不受限、项目外备份）
- 现状：概要设计 §12 只列出了评估顺序
- 严重性：P0

#### 缺口 SM-04：Command Security 细节不完整

- 来源：`security-model-v1.md` §5（CommandRisk 10 种类别、sudo 语义、destructive examples）
- 现状：概要设计未展开
- 严重性：P1

#### 缺口 SM-05：Credential Handling 未展开

- 来源：`security-model-v1.md` §7（6 条规则）
- 现状：概要设计只提到了"credentials are referenced by auth_ref"
- 严重性：P1

---

### 3.14 capability-trust-v1.md（能力信任模型）

#### 缺口 CT-01：Capability Trust Model 未引用

- 来源：`capability-trust-v1.md`（完整信任模型）
- 现状：概要设计只提到了 CapabilityRegistry 概念
- 严重性：P1

#### 缺口 CT-02：Trust Levels 未列出

- 来源：`capability-trust-v1.md` §6（5 种信任级别）
- 现状：概要设计未列出
- 严重性：P1

#### 缺口 CT-03：Capability Lifecycle 未展开

- 来源：`capability-trust-v1.md` §7（discovered → validated → doctor_checked → enabled → registered → active）
- 现状：概要设计未展开
- 严重性：P1

---

### 3.15 provider-capability-matrix-v1.md（供应商能力矩阵）

#### 缺口 PCM-01：Provider Capability Matrix 未引用

- 来源：`provider-capability-matrix-v1.md`（完整能力矩阵）
- 现状：概要设计未引用此文档
- 严重性：P1

#### 缺口 PCM-02：Provider 列表缺失

- 来源：`provider-capability-matrix-v1.md` §2（7 种 ProviderKind）
- 现状：概要设计未列出
- 严重性：P1

#### 缺口 PCM-03：Conversion Loss Handling 未说明

- 来源：`provider-capability-matrix-v1.md` §8
- 现状：概要设计未说明
- 严重性：P2

---

### 3.16 prompt-layering-v1.md（提示分层模型）

#### 缺口 PL-01：Prompt Layering Model 未引用

- 来源：`prompt-layering-v1.md`（完整分层模型）
- 现状：概要设计 §13 列出了 prompt layers 但未引用此文档
- 严重性：P1

#### 缺口 PL-02：Agent-Specific Context Profiles 未展开

- 来源：`prompt-layering-v1.md` §4（8 种 agent profile）
- 现状：概要设计未展开
- 严重性：P2

#### 缺口 PL-03：Prompt Asset Locations 未列出

- 来源：`prompt-layering-v1.md` §7
- 现状：概要设计未列出
- 严重性：P2

---

### 3.17 artifact-naming-v1.md（制品命名规范）

#### 缺口 AN-01：Artifact Naming and Layout 未引用

- 来源：`artifact-naming-v1.md`（完整命名规范）
- 现状：概要设计未引用此文档
- 严重性：P1

#### 缺口 AN-02：Artifact URI/ID 格式未列出

- 来源：`artifact-naming-v1.md` §3 和 §4
- 现状：概要设计未列出
- 严重性：P2

---

### 3.18 error-taxonomy-v1.md（错误分类学）

#### 缺口 ET-01：Error Taxonomy 未引用

- 来源：`error-taxonomy-v1.md`（完整错误分类学）
- 现状：概要设计未引用此文档
- 严重性：P1

#### 缺口 ET-02：AirError 契约未列出

- 来源：`error-taxonomy-v1.md` §2
- 现状：概要设计未列出
- 严重性：P2

---

### 3.19 tool-registry-v1.md（工具注册表）

#### 缺口 TR-01：Tool Registry 未引用

- 来源：`tool-registry-v1.md`（完整工具注册表）
- 现状：概要设计未引用此文档
- 严重性：P1

#### 缺口 TR-02：MVP Required Tool Index 未列出

- 来源：`tool-registry-v1.md` §11（28 个工具）
- 现状：概要设计未列出
- 严重性：P1

---

### 3.20 cross-platform-matrix-v1.md（跨平台矩阵）

#### 缺口 CPM-01：Cross-Platform Matrix 未引用

- 来源：`cross-platform-matrix-v1.md`（完整平台矩阵）
- 现状：概要设计未引用此文档
- 严重性：P1

#### 缺口 CPM-02：Platform Support Levels 未列出

- 来源：`cross-platform-matrix-v1.md` §2
- 现状：概要设计未列出
- 严重性：P2

---

### 3.21 decisions-round-1.md（ADR 第一轮）

#### 缺口 DR1-01：D-014 与 runtime-semantics-v1.md §12 的关系未说明

- 来源：`decisions-round-1.md` D-014（LLM-based diagnostic parsing）vs `runtime-semantics-v1.md` §12（deterministic extraction in toolchain-cpp）
- 现状：概要设计未说明 D-014 已被后续基线覆盖
- 严重性：P2（需明确注明）

---

### 3.22 decisions-round-2.md（ADR 第二轮）

#### 缺口 DR2-01：D-025/D-037 与 D-047 的 compaction rules 格式冲突未说明

- 来源：`decisions-round-2.md` D-025/D-037（YAML compaction rules）vs `decisions-round-3.md` D-047（Markdown + YAML frontmatter）
- 现状：概要设计未说明 round-3 取代 round-2
- 严重性：P2（需明确注明）

---

### 3.23 decisions-round-3.md（ADR 第三轮）

概要设计与 round-3 决策基本一致。以下为少量差异：

#### 差异 DR3-01：IPC 退出码定义矛盾

- 来源：`decisions-round-3.md` D-039 退出码：
  ```
  0 = protocol-level completion, including task completed/blocked/failed
  1 = uncaught exception
  2 = startup/protocol error
  3 = permission error
  4 = parent cancelled
  5 = hard timeout killed
  ```
- 概要设计 §11 未列出退出码
- `baselineV1.md` §8 退出码与 D-039 一致
- 严重性：需在概要设计中补充

---

### 3.24 idea.md（原始设计构想）

#### 缺口 IDEA-01：核心定位"not a Claude Code plugin/wrapper"未在概要设计中重复

- 来源：`idea.md` §2
- 现状：概要设计未明确
- 严重性：P1

#### 缺口 IDEA-02：Scanner 策略细节（15 秒超时、增量扫描）缺失

- 来源：`idea.md` §7.2
- 现状：概要设计未提及
- 严重性：P2

---

## 4. 与 GPT5 审查的交叉验证

### 4.1 GPT5 审查验证结果

| GPT5 编号 | GPT5 发现 | 验证结果 | 说明 |
|---|---|---|---|
| 3.1 | 产品定位缺失 | 正确 | 与 B-01 一致 |
| 3.2 | 参考项目边界缺失 | 正确 | 与 B-03 一致 |
| 3.3 | 技术栈细节缺失 | 正确 | 与 B-04 一致 |
| 3.4 | 未来语言包缺失 | 正确 | 与 B-05 一致 |
| 3.5 | 全局 ~/.air/ 缺失 | 正确 | 与 B-06 一致 |
| 3.6 | Main Agent idle-ready、Scheduler 详细职责、worker 独立角色循环 | 正确 | 与 B-09/B-10/B-11 一致 |
| 3.7 | RuntimeEvent envelope 缺失 | 正确 | 与 B-12 一致 |
| 3.8 | IPC envelope 和退出码缺失 | 正确 | 与 B-13 一致 |
| 3.9 | TaskSpec/WorkerResult 字段族缺失 | 正确 | 与 B-14 一致 |
| 3.10 | 工具和能力系统缺失 | 正确 | 与 B-15 一致 |
| 3.11 | Claude Code 执行原语缺失 | 正确 | 与 R-01 一致 |
| 3.12 | 权限边界规则缺失 | 正确 | 与 B-17 一致 |
| 3.13 | SQLite 消息存储不变量缺失 | 正确 | 与 B-18/DB-03 一致 |
| 3.14 | Contracts 包文件清单缺失 | 正确 | 与 B-19/CV-01 一致 |
| 3.15 | Artifact 命名布局缺失 | 正确 | 与 B-20/AN-01 一致 |
| 3.16 | Context/Compaction 规则位置缺失 | 正确 | 与 B-21 一致 |
| 3.17 | Memory/Skills 路径和 promotion 策略缺失 | 正确 | 与 B-22 一致 |
| 3.18 | Provider 能力矩阵缺失 | 正确 | 与 B-23/PCM-01 一致 |
| 3.19 | OpenCode UI 复用边界缺失 | 正确 | 与 B-24 一致 |
| 3.20 | UI 设计资源能力缺失 | 正确 | 与 B-25 一致 |
| 3.21 | C++ 工具链细节缺失 | 正确 | 与 B-26 一致 |
| 3.22 | 项目初始化/扫描器缺失 | 正确 | 与 B-27 一致 |
| 3.23 | Schema 迁移缺失 | 正确 | 与 B-28 一致 |
| 3.24 | 日志和 Bundle 缺失 | 正确 | 与 B-29/R-02 一致 |
| 3.25 | 测试分类缺失 | 正确 | 与 B-30/R-03 一致 |
| 3.26 | 分发缺失 | 正确 | 与 B-31 一致 |
| 3.27 | 冻结基线完整列表不完整 | 正确 | 与 B-32 一致 |
| 5.1 | D-014 vs runtime-semantics 冲突 | 正确，已解决 | 与 DR1-01 一致 |
| 5.2 | D-025/D-037 vs D-047 冲突 | 正确，已解决 | 与 DR2-01 一致 |

### 4.2 GPT5 审查遗漏项

以下为 GPT5 审查未覆盖但本审查发现的额外缺口：

| 编号 | 缺口 | 来源 | 严重性 |
|---|---|---|---|
| M-01 | Main Agent 状态机文档未引用 | main-agent-state-machine.md | P0 |
| M-02 | Scheduler 状态机文档未引用 | scheduler-state-machine-v1.md | P0 |
| M-03 | Scope Escalation Model 文档未引用 | scope-escalation-v1.md | P0 |
| M-04 | Security Model 文档未引用 | security-model-v1.md | P0 |
| M-05 | schema_meta 表缺失 | db-schema-v1.md §2 | P1 |
| M-06 | Heartbeat 5 秒合并间隔未说明 | runtime-semantics-v1.md §4 | P2 |
| M-07 | Command Run Status 派生状态规则未说明 | runtime-semantics-v1.md §5 | P2 |
| M-08 | Workspace GC Policy 未说明 | runtime-semantics-v1.md §15 | P2 |
| M-09 | 闭合枚举清单未引用 | db-schema-v1.md §21 | P2 |
| M-10 | 执行纪律中 read-before-edit token 机制未展开 | runtime-semantics-v1.md §9.1 | P0 |

### 4.3 GPT5 审查误判项

GPT5 审查没有发现误判。所有发现均正确。

---

## 5. 三视角审查

### 5.1 架构一致性视角

#### 5.1.1 架构边界违反

无发现。概要设计的容器视图、依赖方向、禁止路径与基线一致。

#### 5.1.2 架构不变量缺失

| 不变量 | 来源 | 现状 |
|---|---|---|
| runtime must never depend on tui | baselineV1.md §4 | 未显式说明 |
| tui must consume ProjectionStore, not raw DB/EventBus | baselineV1.md §4 | §14 已覆盖 |
| EventBus is never recovery source of truth | baselineV1.md §7 | §9 已覆盖 |
| workers never write SQLite directly | baselineV1.md §8 | §11 已覆盖 |
| LLM output is untrusted until validated | security-model-v1.md §2 | §12 已覆盖 |
| Main Agent must remain idle-ready | baselineV1.md §6 | 未显式说明 |
| Worker loops are independent, not generic | baselineV1.md §6 | 未显式说明 |
| EventStore decides durability, not producer | baselineV1.md §7 | 未显式说明 |

#### 5.1.3 架构文档引用链断裂

概要设计 §1 列出了 11 份源文档，但冻结基线共 24 份。缺失 13 份（不含 idea.md 和 todo.md 已列入）：

1. `scheduler-state-machine-v1.md`
2. `scope-escalation-v1.md`
3. `security-model-v1.md`
4. `capability-trust-v1.md`
5. `provider-capability-matrix-v1.md`
6. `prompt-layering-v1.md`
7. `artifact-naming-v1.md`
8. `error-taxonomy-v1.md`
9. `tool-registry-v1.md`
10. `cross-platform-matrix-v1.md`
11. `decisions-round-1.md`
12. `decisions-round-2.md`
13. `decisions-round-3.md`

---

### 5.2 工程可实现性视角

#### 5.2.1 可实现性缺口

| 缺口 | 影响 |
|---|---|
| 技术栈细节缺失 | 实现者无法确定 Bun/SQLite/NDJSON 等技术选型 |
| Contracts 包文件清单缺失 | 实现者无法确定 packages/contracts/src/ 的文件结构 |
| IPC 退出码未列出 | 实现者无法确定退出码语义 |
| TaskSpec/WorkerResult 字段族未展开 | 实现者无法确定数据结构 |
| SQLite 运行时设置不完整 | 实现者无法确定 WAL/NORMAL/fk OFF 设置 |
| 工具注册表未引用 | 实现者无法确定 MVP 工具清单 |

#### 5.2.2 可实现性风险

| 风险 | 概率 | 影响 | 缓解 |
|---|---|---|---|
| 实现者误解 Claude Code 执行原语 | 高 | 代码质量下降 | 补充 §10.8 |
| 实现者误解权限边界 | 高 | 安全漏洞 | 补充 §12 |
| 实现者遗漏 SQLite 不变量 | 中 | 数据一致性问题 | 补充 §8.2 |
| 实现者误解 IPC 退出码 | 中 | 进程管理错误 | 补充 §11 |

---

### 5.3 需求对齐视角

#### 5.3.1 FR 覆盖矩阵

| FR | 来源 | 覆盖状态 | 缺口 |
|---|---|---|---|
| FR-001 CLI Startup | requirements.md §3 | 已覆盖 | 全局 ~/.air/ 缺失 |
| FR-002 Project-Local State | requirements.md §3 | 已覆盖 | project_id UUID 缺失 |
| FR-003 Session Persistence | requirements.md §3 | 部分覆盖 | WAL/NORMAL、canonical message JSON、draft 删除、no message_parts 缺失 |
| FR-004 Event-Driven Runtime | requirements.md §3 | 部分覆盖 | envelope/route/version 规则缺失 |
| FR-005 Main Agent | requirements.md §3 | 已覆盖 | idle-ready 规则未显式 |
| FR-006 Architecture Designer | requirements.md §3 | 已覆盖 | — |
| FR-007 Scheduler | requirements.md §3 | 部分覆盖 | dependency/write-area/timeout/retry/concurrency 细节不足 |
| FR-008 Worker Agents | requirements.md §3 | 已覆盖 | 独立角色循环未强调 |
| FR-009 Claude Code Primitives | requirements.md §3 | 缺失 | read-before-edit、exact edit、verification-before-completion 未作为系统约束 |
| FR-010 Built-In Tools | requirements.md §3 | 部分覆盖 | 工具清单不完整 |
| FR-011 Permission/Security | requirements.md §3 | 部分覆盖 | 边界规则缺失 |
| FR-012 Capability Foundation | requirements.md §3 | 部分覆盖 | source/trust/namespaced registration 需明确 |
| FR-013 Provider Layer | requirements.md §3 | 部分覆盖 | provider 列表/兼容矩阵缺失 |
| FR-014 Context/Compaction | requirements.md §3 | 部分覆盖 | omissions、Anthropic canonical output、rule locations 缺失 |
| FR-015 Artifact/Evidence | requirements.md §3 | 已覆盖 | — |
| FR-016 TUI/HUD | requirements.md §3 | 已覆盖 | OpenCode UI 复用边界缺失 |
| FR-017 C++ Workflow | requirements.md §3 | 部分覆盖 | Ninja/Make、compile_commands、clangd 细节缺失 |
| FR-018 Doctor | requirements.md §3 | 已覆盖 | first-start/fix nuance 部分缺失 |
| FR-019 Logging | requirements.md §3 | 缺失 | 双日志、加密 dev log、7 天保留 |
| FR-020 Release Gate | requirements.md §3 | 已覆盖 | 测试三层定义缺失 |

#### 5.3.2 NFR 覆盖矩阵

| NFR | 来源 | 覆盖状态 | 缺口 |
|---|---|---|---|
| NFR-001 Local-First | requirements.md §4 | 已覆盖 | — |
| NFR-002 Recoverability | requirements.md §4 | 已覆盖 | — |
| NFR-003 Extensibility | requirements.md §4 | 已覆盖 | — |
| NFR-004 Provider Flexibility | requirements.md §4 | 部分覆盖 | 跨 provider 稳定性列表不明确 |
| NFR-005 UI Responsiveness | requirements.md §4 | 部分覆盖 | Main Agent/TUI 保持响应需显式说明 |
| NFR-006 Evidence-Based Completion | requirements.md §4 | 已覆盖 | — |
| NFR-007 Linux-First | requirements.md §4 | 部分覆盖 | tier-1/tier-2/experimental 平台矩阵不完整 |
| NFR-008 Security Boundary | requirements.md §4 | 已覆盖 | — |

---

## 6. 矛盾清单

### 矛盾 C-01：IPC 退出码未列出

- 概要设计 §11 未列出退出码
- `baselineV1.md` §8 和 `decisions-round-3.md` D-039 定义了退出码
- 严重性：P0（实现者可能误解退出码语义）

### 矛盾 C-02：D-014 与 runtime-semantics-v1.md §12 的关系未说明

- `decisions-round-1.md` D-014 要求所有 compiler/linker 输出由 LLM 解析
- `runtime-semantics-v1.md` §12 明确规定 deterministic extraction in toolchain-cpp, LLM interpretation in Debugger/Reviewer
- 概要设计未说明此覆盖关系
- 严重性：P2（需明确注明 round-3 取代 round-1）

### 矛盾 C-03：D-025/D-037 与 D-047 的 compaction rules 格式冲突未说明

- `decisions-round-2.md` D-025/D-037 提到 YAML compaction rules
- `decisions-round-3.md` D-047 改为 Markdown + YAML frontmatter
- 概要设计未说明 round-3 取代 round-2
- 严重性：P2（需明确注明）

---

## 7. 修复建议（附补丁文本）

### P0 — 必须补充（影响下游设计/实现）

#### 补丁 P0-01：更新 §1 Source Documents

在概要设计 §1 的 source documents 列表后追加：

```md
Source documents (frozen baselines):

1. `AirPlan/docs/analysis/requirements.md`
2. `AirPlan/docs/architecture/solution-architecture.md`
3. `AirPlan/docs/architecture/baselineV1.md`
4. `AirPlan/docs/architecture/interface-contracts-v1.md`
5. `AirPlan/docs/architecture/db-schema-v1.md`
6. `AirPlan/docs/architecture/event-registry-v1.md`
7. `AirPlan/docs/architecture/runtime-semantics-v1.md`
8. `AirPlan/docs/architecture/c4/module.md`
9. `AirPlan/docs/architecture/c4/code-view.md`
10. `AirPlan/docs/architecture/main-agent-state-machine.md`
11. `AirPlan/docs/architecture/scheduler-state-machine-v1.md`
12. `AirPlan/docs/architecture/scope-escalation-v1.md`
13. `AirPlan/docs/architecture/security-model-v1.md`
14. `AirPlan/docs/architecture/capability-trust-v1.md`
15. `AirPlan/docs/architecture/provider-capability-matrix-v1.md`
16. `AirPlan/docs/architecture/prompt-layering-v1.md`
17. `AirPlan/docs/architecture/artifact-naming-v1.md`
18. `AirPlan/docs/architecture/error-taxonomy-v1.md`
19. `AirPlan/docs/architecture/tool-registry-v1.md`
20. `AirPlan/docs/architecture/cross-platform-matrix-v1.md`
21. `AirPlan/docs/architecture/decisions-round-1.md`
22. `AirPlan/docs/architecture/decisions-round-2.md`
23. `AirPlan/docs/architecture/decisions-round-3.md`
24. `AirPlan/todo.md`

Where decision rounds conflict, later rounds supersede earlier rounds for V1.0.0 Alpha
unless a frozen architecture baseline explicitly says otherwise.

Note: D-014 (round-1 LLM-parsed diagnostics) is superseded by runtime-semantics §12:
deterministic extraction in toolchain-cpp, LLM interpretation in Debugger/Reviewer context.
D-025/D-037 (round-2 YAML compaction rules) is superseded by D-047 (round-3 Markdown + YAML frontmatter).
```

#### 补丁 P0-02：在 §2 后新增 §2.1 Product Positioning

```md
## 2.1 Product Positioning

AirCoding is a self-owned local AI coding runtime, not a Claude Code plugin/wrapper.

Canonical V1 loop:
requirement → architecture/interface design → code reading → implementation planning
  → build → static analysis → test → run/debug → crash/log/network/GUI evidence analysis
  → fix → change summary → experience mining
```

#### 补丁 P0-03：在 §8 前新增 §7.0 Global Filesystem Layout

```md
## 7.0 Global Filesystem Layout

Global user directory:

~/.air/
  config.yaml
  models.yaml
  permissions.yaml
  compaction-rules.md
  project-index.db
  cache/{plugins,providers,lsp,downloads}/
  resources/versions/<version>/
  skills/
  logs/{air.log,air.developer.log}

`project_id` is a stable UUID generated at initialization and stored in `.air/shared/project.json`.
It is not derived from the absolute path.

`.air/local/` should be gitignored by default.
```

#### 补丁 P0-04：在 §7 表格后补充 Main Agent 不变量

在 §7 Runtime Agent Overview 表格后追加：

```md
Key invariants:

- Main Agent must remain idle-ready and never perform long-running background work.
  Background tasks (ExperienceMiner, DebugKnowledge indexing) are dispatched to sub-agents
  via Scheduler, never run on Main Agent's thread/loop.
- Each worker is an independent role loop (Executor/Reviewer/Debugger/Compactor/ExperienceMiner),
  not a single generic worker loop.
```

#### 补丁 P0-05：在 §9 后补充 RuntimeEvent Envelope

在 §9 Event and Projection Overview 后追加：

```md
### 9.1 RuntimeEvent Envelope

RuntimeEvent envelope fields: id, type, version, timestamp, session_id, project_id?, source, route[], payload.

`route` is append-only: producers append their segment, never rewrite earlier entries.
EventStore decides durable vs ephemeral persistence by event type; producers must not decide ad hoc.
Payload schema changes require incrementing the event `version` for that event type.
```

#### 补丁 P0-06：在 §11 后补充 IPC Envelope 和退出码

在 §11 IPC and Worker Overview 后追加：

```md
### 11.1 IPC Envelope

IPC envelope fields: id, direction, kind, timestamp, session_id, agent_id, correlation_id?, protocol_version, payload.

Worker stdout is for NDJSON protocol only; stderr is for fatal fallback/logging.

Exit codes:

0 = protocol-level completion, including task completed/blocked/failed
1 = uncaught exception
2 = startup/protocol error
3 = permission error
4 = parent cancelled
5 = hard timeout killed
```

#### 补丁 P0-07：在 §6 后补充 TaskSpec 和 WorkerResult 概览

在 §6 Runtime Component Overview 后追加：

```md
### 6.1 TaskSpec and WorkerResult Overview

TaskSpec required field families: type, title, description, acceptance_criteria, scope, dependencies,
verification, constraints, context_refs, output_contract.

WorkerResult required outputs: task_id, agent_id, agent_type, status, summary, changed_files,
artifacts, verification[], risks[], follow_up_tasks[], evidence_refs[], result.

- `failed`: task goal not achieved but Scheduler may decide retry/skip.
- `blocked`: higher-level decision or external condition required.
- `cancelled`: explicitly stopped.
```

#### 补丁 P0-08：在 §10 后补充 Execution Discipline

在 §10.6 C++ workflow 后追加：

```md
### 10.7 Execution Discipline

Execution-layer tools enforce Claude Code-quality discipline:

- read-before-edit: fs.edit/fs.patch require prior read observation for the target file
- exact conservative edits: old_string must match exactly, no guessing
- small patches: no broad rewrites unless explicitly fs.write
- no unrelated refactors: changes stay within task scope
- schema-validated tool I/O at all boundaries
- root-cause diagnosis before random retries
- verification-before-completion: code-changing tasks cannot complete without build/test/debug
  evidence or an explicit skipped-gate report
```

#### 补丁 P0-09：在 §12 后补充权限边界规则

在 §12 Permission and Security Overview 后追加：

```md
### 12.1 Permission Edge Rules

Permission edge rules:

- Path policy resolves symlinks with `realpath` before risk classification.
- `.git/` writes require confirmation unless project policy overrides.
- Build/output directories are unrestricted for C++ workflows.
- `~/.air/` internal operations bypass PermissionEngine.
- `sudo` alone is not high-risk; system-sensitive paths still require confirmation.
- High-risk detection: static system path whitelist + LLM escape hatch only when
  static classification is inconclusive.
- Project-outside writes are backed up to `.air/local/backups/` git history before modification.
```

#### 补丁 P0-10：在 §8.2 后补充 SQLite 不变量

在 §8.2 Session DB 后追加：

```md
### 8.2.1 SQLite Invariants

Session DB uses WAL + synchronous NORMAL + foreign_keys OFF with application-level
referential invariant checks and startup orphan scans.

Messages store complete Anthropic canonical content JSON. Query-heavy relations
are extracted into domain tables and indexes.

`message_drafts` exist only during streaming/incomplete assistant output and are
deleted after the completed message is written.

`message_parts` is not a source-of-truth table in V1.0.0 Alpha.

`ui_state` is not source of truth for runtime state; it is flushed periodically and on exit.
```

---

### P1 — 应补充（影响设计完整性）

#### 补丁 P1-01：在 §3 后补充技术栈细节

```md
## 3.1 Technology Baseline

Technology baseline:

- Runtime: TypeScript on Bun
- Monorepo: Bun workspaces + Turborepo
- TUI: `@opentui/solid`, `@opentui/core`, `@opentui/keymap`
- Storage: SQLite per session, project-local
- IPC: NDJSON over stdio
- Python: subprocess-only helper layer for existing scripts/libraries, not core runtime
- Distribution: binary tarball before public package channels
```

#### 补丁 P1-02：在 §4 后补充 Contracts 包文件清单

```md
## 4.1 Contracts Package Baseline

Expected contracts package structure:

packages/contracts/src/
  index.ts, 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, capability.ts, platform.ts
```

#### 补丁 P1-03：在 §5 后补充参考项目影响

```md
## 5.1 Reference Influence

Reference influences for V1.0.0 Alpha:

- Claude Code: primary execution-layer quality benchmark (read-before-edit, exact conservative edits,
  small patches, no unrelated refactors, verification-before-completion, evidence-backed closure).
- OpenCode: UI visual patterns and OpenTUI primitives only; no SDK/sync/session business-state reuse.
- Hermes Agent: experience mining, Nudge Engine triggers, Curator daemon, self-patch, SKILL.md format.
- OpenAI Codex: shell/patch/test loop and tool orchestration ideas.
- Anthropic Claude Skills: SKILL.md structure, skill directory layout, trigger descriptions.
- asciinema / Atuin / claude-hud: PTY capture, command history indexing, HUD/statusline layout.
```

#### 补丁 P1-04：在 §10.6 补充 C++ 工具链细节

```md
C++ toolchain details:

- Build: CMake built-in, Ninja first then Make fallback.
- Test: CTest + GoogleTest first.
- Static analysis: cppcheck built-in; clang-tidy later.
- Code intelligence: clangd CLI mode.
- compile_commands.json: generated on demand, not persisted as cache.
- Build-system conflicts shown to the user.
- BuildTool attempts built-in repair first; unresolved failures route to Debugger.
- DiagnosticParser: deterministic extraction in toolchain-cpp; LLM interpretation in Debugger/Reviewer.
```

#### 补丁 P1-05：在 §13 补充 Context/Compaction 规则位置

```md
ContextAssembler outputs Anthropic canonical messages and records omissions.
Compaction rules use Markdown + YAML frontmatter at:
- built-in default
- ~/.air/compaction-rules.md
- <project>/.air/shared/compaction-rules.md

Compaction uses copy-on-write: snapshot messages, async Compactor produces summary,
original messages preserved for backtracking.
```

#### 补丁 P1-06：在 §13 补充 Memory/Skills 路径和 promotion 策略

```md
Project rules: <project>/.air/shared/rules/{project-rules.md,toolchain-rules.md}
Skills: ~/.air/skills/<skill-name>/SKILL.md

Non-debug memories require repeated occurrence (N=3) plus user confirmation before promotion.
Debug experience confidence comes from verified evidence, not numeric scoring.
Debug knowledge sharing requires redaction, preview, and explicit authorization.
```

#### 补丁 P1-07：在 §15 后补充项目初始化/扫描器

```md
## 15.1 Project Initialization

Project initialization uses a full metadata-only scanner:
- complete directory tree, no directory exclusions, no depth limit
- file extension statistics, special file types, git summary
- no file content reading during tree scan
- symlink targets recorded, permission errors as error metadata

Scanner output is interpreted by Main Agent/LLM into a ProjectProfile.
User confirms or corrects the profile.
```

#### 补丁 P1-08：在 §15 后补充 Schema 迁移

```md
## 15.2 Schema Migration

Schema migration flow:

1. detect schema_meta.schema_version on session open
2. if older than current, display migration plan
3. require user confirmation (even in high-permission mode)
4. backup .air/ to .air/local/backups/migrations/<timestamp>/
5. apply migration
6. on failure, rollback to backup
```

#### 补丁 P1-09：在 §15 后补充日志

```md
## 15.3 Logging

LoggingService writes:
- air.log: user-readable, startup/config/environment failures
- air.developer.log: full debug/performance log, encrypted with development-team public key

Default retention: 7 days, auto-rotated.

Doctor bundles are local artifacts containing full diagnostics.
Bundles are never auto-uploaded and are not necessarily auto-redacted.
Doctor bundle channel is separate from Debug Knowledge sharing/redaction flow.
```

#### 补丁 P1-10：在 §6 补充 Provider 能力矩阵摘要

```md
Provider support:
- Native: Anthropic, OpenAI
- Compatible: OpenRouter, ollama, custom Anthropic/OpenAI-compatible endpoints

Same-provider model switching has no format conversion cost, but V1 session selection
is fixed after startup (provider/model immutability rule).

Provider conversion reports track omissions/warnings/required_confirmation for lossy translation.
```

#### 补丁 P1-11：在 §17 补充测试分类

```md
Testing taxonomy:

- Unit: bun test, CI per push, <30s, no LLM calls
- Integration: CI per push, <1min, recorded LLM fixture replay
- E2E: release gate, real LLM calls, must pass before release

Validation references cross-platform matrix (Linux x86_64 tier 1, arm64/WSL2 tier 2).
```

#### 补丁 P1-12：在 §17 后补充分发

```md
## 17.1 Distribution

Binary tarball contains: bin/air, resources/, LICENSE

Resources include: compaction rule templates, HUD presets, prompt assets,
Python helper scripts, toolchain resources.

No public package channels (npm, brew, apt, winget) until stable.
```

---

### P2 — 可选补充

#### 补丁 P2-01：在 §14 补充 OpenCode UI 复用边界

```md
OpenCode UI primitive reuse: theme system, dialog/modal/toast patterns, keymap wrapper,
layout style, spinner/border/error components, markdown/code/diff rendering patterns.

No reuse of OpenCode SDK/sync/session business layer.
```

#### 补丁 P2-02：在 §2 补充 UI 设计资源能力

```md
Optional `ui-design-assets` capability for V1.0.0 Alpha:
ASCII/wireframe mockups, design specs, SVG icons, screenshot design analysis,
prompts for external image generators.

Generated design assets are artifacts first and must be shown to the user
before being written into project files. Production bitmap generation is post-Alpha.
```

#### 补丁 P2-03：在 §5 补充未来语言包

```md
Future language packages:
- packages/toolchain-python
- packages/toolchain-rust
- packages/toolchain-js

Invariant: runtime must never import tui.
```

#### 补丁 P2-04：在 §8.2 补充 Artifact 命名摘要

```md
Artifacts use canonical URI/ID naming with ULID, temp-write → hash/size → atomic rename → DB record.
Evidence links reference artifact IDs for claim traceability.
Artifact naming/layout rules are defined in the frozen artifact-naming-v1.md.
```

---

## 8. FR/NFR 覆盖矩阵（完整版）

### 8.1 Functional Requirements

| FR | 覆盖状态 | 缺口 | 补丁 |
|---|---|---|---|
| FR-001 CLI Startup | 已覆盖 | 全局 ~/.air/ 缺失 | P0-03 |
| FR-002 Project-Local State | 已覆盖 | project_id UUID 缺失 | P0-03 |
| FR-003 Session Persistence | 部分覆盖 | WAL/NORMAL、canonical message JSON、draft 删除、no message_parts 缺失 | P0-10 |
| FR-004 Event-Driven Runtime | 部分覆盖 | envelope/route/version 规则缺失 | P0-05 |
| FR-005 Main Agent | 已覆盖 | idle-ready 规则未显式 | P0-04 |
| FR-006 Architecture Designer | 已覆盖 | — | — |
| FR-007 Scheduler | 部分覆盖 | dependency/write-area/timeout/retry/concurrency 细节不足 | P0-07 |
| FR-008 Worker Agents | 已覆盖 | 独立角色循环未强调 | P0-04 |
| FR-009 Claude Code Primitives | 缺失 | read-before-edit、exact edit、verification-before-completion 未作为系统约束 | P0-08 |
| FR-010 Built-In Tools | 部分覆盖 | 工具清单不完整 | P1-04 |
| FR-011 Permission/Security | 部分覆盖 | 边界规则缺失 | P0-09 |
| FR-012 Capability Foundation | 部分覆盖 | source/trust/namespaced registration 需明确 | P1-10 |
| FR-013 Provider Layer | 部分覆盖 | provider 列表/兼容矩阵缺失 | P1-10 |
| FR-014 Context/Compaction | 部分覆盖 | omissions、Anthropic canonical output、rule locations 缺失 | P1-05 |
| FR-015 Artifact/Evidence | 已覆盖 | — | — |
| FR-016 TUI/HUD | 已覆盖 | OpenCode UI 复用边界缺失 | P2-01 |
| FR-017 C++ Workflow | 部分覆盖 | Ninja/Make、compile_commands、clangd 细节缺失 | P1-04 |
| FR-018 Doctor | 已覆盖 | first-start/fix nuance 部分缺失 | P1-09 |
| FR-019 Logging | 缺失 | 双日志、加密 dev log、7 天保留 | P1-09 |
| FR-020 Release Gate | 已覆盖 | 测试三层定义缺失 | P1-11 |

### 8.2 Non-Functional Requirements

| NFR | 覆盖状态 | 缺口 | 补丁 |
|---|---|---|---|
| NFR-001 Local-First | 已覆盖 | — | — |
| NFR-002 Recoverability | 已覆盖 | — | — |
| NFR-003 Extensibility | 已覆盖 | — | — |
| NFR-004 Provider Flexibility | 部分覆盖 | 跨 provider 稳定性列表不明确 | P1-10 |
| NFR-005 UI Responsiveness | 部分覆盖 | Main Agent/TUI 保持响应需显式说明 | P0-04 |
| NFR-006 Evidence-Based Completion | 已覆盖 | — | — |
| NFR-007 Linux-First | 部分覆盖 | tier-1/tier-2/experimental 平台矩阵不完整 | P1-12 |
| NFR-008 Security Boundary | 已覆盖 | — | — |

---

## 9. 总体评分

### 评分维度

| 维度 | 分数 (1-10) | 说明 |
|---|---|---|
| 架构一致性 | 7 | 大方向一致，但 4 份关键架构文档未引用（状态机、升级模型、安全模型） |
| 工程可实现性 | 6 | 骨架清晰但关键实现细节缺失（IPC 退出码、TaskSpec 字段、SQLite 不变量、执行纪律） |
| 需求对齐 | 6 | 20 条 FR 中 4 条缺失/严重不足，8 条 NFR 中 3 条部分覆盖 |
| 文档完整性 | 5 | 24 份基线中 14 份未列入源文档，多个章节缺失 |
| 基线溯源性 | 4 | 大量基线规则未在概要设计中体现或引用 |

### 总分：5.6 / 10

---

## 10. 进入详细设计的结论

**结论：暂不建议直接进入详细设计 / 类图冻结。**

理由：

1. **P0 缺口有 10 项**，其中多项直接影响下游实现（执行纪律、权限边界、IPC 退出码、TaskSpec/WorkerResult 字段、SQLite 不变量、全局文件系统布局、Main Agent 不变量）
2. **14 份冻结基线未列入源文档**，下游设计无法溯源
3. **4 份关键架构文档未引用**（main-agent-state-machine.md、scheduler-state-machine-v1.md、scope-escalation-v1.md、security-model-v1.md）

**建议行动**：

1. 先应用所有 P0 补丁（10 项），预计工作量 2-3 小时
2. 再应用 P1 补丁（12 项），预计工作量 3-4 小时
3. 补丁完成后重新审查，确认 P0 全部关闭
4. P0 全部关闭后可进入详细设计

**如果时间紧迫的最小可行方案**：

仅应用 P0 补丁（10 项），P1 补丁在详细设计阶段作为设计输入补充。此方案下可进入详细设计但需在详细设计文档开头注明概要设计的已知缺口。

---

## 11. 补丁优先级汇总

| 优先级 | 补丁编号 | 描述 | 工作量 |
|---|---|---|---|
| P0 | P0-01 | 更新 §1 Source Documents | 10 min |
| P0 | P0-02 | 新增 §2.1 Product Positioning | 5 min |
| P0 | P0-03 | 新增 §7.0 Global Filesystem Layout | 10 min |
| P0 | P0-04 | 补充 Main Agent 不变量 | 5 min |
| P0 | P0-05 | 补充 RuntimeEvent Envelope | 10 min |
| P0 | P0-06 | 补充 IPC Envelope 和退出码 | 10 min |
| P0 | P0-07 | 补充 TaskSpec 和 WorkerResult 概览 | 10 min |
| P0 | P0-08 | 补充 Execution Discipline | 10 min |
| P0 | P0-09 | 补充权限边界规则 | 10 min |
| P0 | P0-10 | 补充 SQLite 不变量 | 10 min |
| P1 | P1-01 | 补充技术栈细节 | 5 min |
| P1 | P1-02 | 补充 Contracts 包文件清单 | 5 min |
| P1 | P1-03 | 补充参考项目影响 | 5 min |
| P1 | P1-04 | 补充 C++ 工具链细节 | 10 min |
| P1 | P1-05 | 补充 Context/Compaction 规则位置 | 5 min |
| P1 | P1-06 | 补充 Memory/Skills 路径和 promotion 策略 | 5 min |
| P1 | P1-07 | 补充项目初始化/扫描器 | 10 min |
| P1 | P1-08 | 补充 Schema 迁移 | 10 min |
| P1 | P1-09 | 补充日志 | 10 min |
| P1 | P1-10 | 补充 Provider 能力矩阵摘要 | 5 min |
| P1 | P1-11 | 补充测试分类 | 5 min |
| P1 | P1-12 | 补充分发 | 5 min |
| P2 | P2-01 | 补充 OpenCode UI 复用边界 | 5 min |
| P2 | P2-02 | 补充 UI 设计资源能力 | 5 min |
| P2 | P2-03 | 补充未来语言包 | 5 min |
| P2 | P2-04 | 补充 Artifact 命名摘要 | 5 min |

总工作量：P0 约 90 分钟，P1 约 90 分钟，P2 约 20 分钟。