Files

AirCoding 33a76a1ebc Move project from external drive to local NVMe

迁移路径: /run/media/airlongdian/EasyU/AirCoding -> /home/airlongdian/DataDevices/AirWorkSpace/AirCoding

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-06-02 09:51:49 +08:00

57 KiB

Executable File

Raw Blame History

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 份冻结文档）：

requirements.md（需求规格）
baselineV1.md（架构基线）
solution-architecture.md（解法架构）
interface-contracts-v1.md（接口契约）
db-schema-v1.md（数据库 Schema）
event-registry-v1.md（事件注册表）
runtime-semantics-v1.md（运行时语义）
c4/module.md（C4 模块视图）
c4/code-view.md（C4 代码视图）
main-agent-state-machine.md（主代理状态机）
scheduler-state-machine-v1.md（调度器状态机）
scope-escalation-v1.md（作用域升级模型）
security-model-v1.md（安全模型）
capability-trust-v1.md（能力信任模型）
provider-capability-matrix-v1.md（供应商能力矩阵）
prompt-layering-v1.md（提示分层模型）
artifact-naming-v1.md（制品命名规范）
error-taxonomy-v1.md（错误分类学）
tool-registry-v1.md（工具注册表）
cross-platform-matrix-v1.md（跨平台矩阵）
decisions-round-1.md（ADR 第一轮 D-001~D-020）
decisions-round-2.md（ADR 第二轮 D-021~D-037）
decisions-round-3.md（ADR 第三轮 D-038~D-059）
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 已列入）：

scheduler-state-machine-v1.md
scope-escalation-v1.md
security-model-v1.md
capability-trust-v1.md
provider-capability-matrix-v1.md
prompt-layering-v1.md
artifact-naming-v1.md
error-taxonomy-v1.md
tool-registry-v1.md
cross-platform-matrix-v1.md
decisions-round-1.md
decisions-round-2.md
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 列表后追加：

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

## 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

## 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 表格后追加：

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 后追加：

### 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 后追加：

### 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 后追加：

### 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 后追加：

### 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 后追加：

### 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 后追加：

### 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 后补充技术栈细节

## 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 包文件清单

## 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 后补充参考项目影响

## 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++ 工具链细节

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 规则位置

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 策略

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 后补充项目初始化/扫描器

## 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 迁移

## 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 后补充日志

## 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 能力矩阵摘要

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 补充测试分类

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 后补充分发

## 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 复用边界

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 设计资源能力

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 补充未来语言包

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

Invariant: runtime must never import tui.

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

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. 进入详细设计的结论

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

理由：

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

建议行动：

先应用所有 P0 补丁（10 项），预计工作量 2-3 小时
再应用 P1 补丁（12 项），预计工作量 3-4 小时
补丁完成后重新审查，确认 P0 全部关闭
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 分钟。

57 KiB Executable File Raw Blame History Unescape Escape