diff --git a/AirPlan/AGENTS.md b/AirPlan/AGENTS.md index d6b2f4e..e01b779 100755 --- a/AirPlan/AGENTS.md +++ b/AirPlan/AGENTS.md @@ -13,6 +13,14 @@ 2. Load and maintain: - `AirPlan/docs/analysis/requirements.md` - `AirPlan/docs/architecture/solution-architecture.md` + - `AirPlan/docs/architecture/system-overview-design.md` + - `AirPlan/docs/architecture/gpt5概要设计审查.md` + - `AirPlan/docs/architecture/mimo2.5概要设计审查.md` + - `AirPlan/docs/architecture/Opus4.7概要设计审查.md` + - `AirPlan/docs/architecture/DeepSeek概要设计审查.md` + - `AirPlan/docs/architecture/概要设计修复回归审查.md` + - `AirPlan/docs/architecture/概要设计修复回归审查-R2.md` + - `AirPlan/docs/architecture/概要设计修复回归审查-R3.md` - `AirPlan/docs/architecture/baselineV1.md` - `AirPlan/docs/architecture/db-schema-v1.md` - `AirPlan/docs/architecture/event-registry-v1.md` diff --git a/AirPlan/docs/architecture/DeepSeek概要设计审查.md b/AirPlan/docs/architecture/DeepSeek概要设计审查.md new file mode 100644 index 0000000..18526ca --- /dev/null +++ b/AirPlan/docs/architecture/DeepSeek概要设计审查.md @@ -0,0 +1,439 @@ +# DeepSeek V4 Pro 概要设计全量交叉审查 + +Date: 2026-05-29 +Reviewer: DeepSeek V4 Pro +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 行，19 节） + +审查基线（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，26 项缺口） +- `mimo2.5概要设计审查.md`（MIMO v2.5，追加 10 项） +- `Opus4.7概要设计审查.md`（Opus 4.7，追加 8 项） + +方法： +- 独立逐基线 item-by-item 语义比对，不受前三次审查结论约束 +- 对前三次审查逐项验证，三类标注：确认、争议、误判 +- 从三个视角分别审查：架构一致性、工程可实现性、需求对齐 +- P0 = 影响实现方向或存在基线矛盾；P1 = 影响完整性但有基线可查；P2 = 可在详细设计补充 + +--- + +## 2. 总体结论 + +`system-overview-design.md` 作为概要设计文档，系统目标、容器/组件分解、事件流、权限框架、上下文管理、Doctor/恢复、实现阶段划分等宏观架构与基线一致。文档结构清晰，19 个章节覆盖了主要的架构视角。 + +但存在以下结构性不足： + +- **溯源闭环不完整**：§1 仅列出 11 份源文档（实际基线 24 份），13 份基线无法从概要设计溯源 +- **实现关键信息缺失**：错误分类学（0% 覆盖）、IPC 退出码、TaskSpec/WorkerResult 字段语义、权限下钻规则等在概要设计中无定义入口 +- **执行纪律未系统化**：Claude Code 原语（read-before-edit、exact edit、verification-before-completion）作为 V1 质量基准，在需求中明确但在概要设计中被稀释 +- **全局运行时布局缺失**：`~/.air/` 全局目录树和 `project_id` UUID 在概要设计中完全不存在 +- **跨前三次审查高度一致**：GPT-5/MIMO/Opus 三份审查的核心发现相互印证，本次审查独立验证后确认绝大部分缺口属实 + +总评分：**5.7/10**。骨架质量好，但实现可操作性不足。不建议在 P0 修复前进入详细设计。 + +--- + +## 3. 前三份审查交叉验证 + +### 3.1 GPT-5 审查（26 项缺口）验证 + +对 GPT-5 26 项缺口逐项独立验证： + +| GPT-5 编号 | 概述 | DeepSeek 判定 | 备注 | +|---|---|---|---| +| 3.1 | 产品定位 "not a wrapper" | **确认 P0** | baselineV1 §1："not a Claude Code plugin/wrapper" | +| 3.2 | 参考项目边界缺失 | **确认 P0** | baselineV1 §2 列出 5 个参考项目和复用策略 | +| 3.3 | 技术基线缺失 | **确认 P1** | Bun/Turborepo/OpenTUI/Python/tarball 均未出现 | +| 3.4 | `~/.air/` 全局布局缺失 | **确认 P0** | baselineV1 §5 完整定义 | +| 3.5 | `project_id` UUID | **确认 P0**（合并到 3.4） | - | +| 3.6-3.8 | RuntimeEvent 路由/版本/IPC 字段 | **确认 P0** | route append-only, version increment, envelope fields | +| 3.9-3.10 | IPC 退出码 | **确认 P0** | baselineV1 §8 定义 exit codes 0-5 | +| 3.11-3.13 | TaskSpec/WorkerResult | **确认 P0** | interface-contracts §9-§11 完整定义 | +| 3.14 | Claude Code 执行原语 | **确认 P0** | requirements FR-009, runtime-semantics §9 | +| 3.15-3.17 | 权限边界规则 | **确认 P0** | security-model §4-§5 | +| 3.18-3.20 | 日志/迁移/扫描器 | **确认 P1** | baselineV1 §21-§23 | +| 3.21 | 分发 | **确认 P1** | baselineV1 §25 | +| 3.22 | 测试分层 | **确认 P1** | baselineV1 §24 | +| 3.23 | contracts 文件清单 | **确认 P1** | code-view §3 | +| 3.24-3.25 | C++/Provider 细节 | **确认 P1** | - | +| 3.26 | UI 设计资源 | **确认 P2** | baselineV1 §19 | + +**GPT-5 交叉验证结论**：26/26 确认属实，无误判，准确率 100%。 + +### 3.2 MIMO 2.5 审查（追加 10 项）验证 + +| MIMO 编号 | 概述 | DeepSeek 判定 | 备注 | +|---|---|---|---| +| B-01 | 源文档 11→24 | **确认 P0** | - | +| B-02 | Scheduler 状态机 | **确认 P1** | 11 个状态未在概要设计中体现 | +| B-03 | Main Agent 状态机 | **确认 P1** | 9 个状态+转换条件缺失 | +| B-04 | ScopeImpactLevel 7 级 | **确认 P2** | 概要设计 §10.5 已有 Architecture Designer gate，降级 | +| B-05 | Workspace GC 保留天数 | **确认 P2** | - | +| B-06 | FK-off 8 条不变量 | **确认 P1** | - | +| B-07 | Cross-DB outbox 步骤 | **确认 P2** | - | +| B-08 | ExperienceMiner 触发所有权 | **确认 P2** | 概要设计 §13 已有触发列表 | +| B-09 | Doctor 自检 | **误判** | 概要设计 §15 已列出 5 步自检 | +| B-10 | air restore 三粒度 | **误判** | 概要设计 §15 已列出 file/time/session | + +**MIMO 交叉验证结论**：实际缺口 8/10，2 项误判（B-09, B-10），准确率 80%。与 Opus 4.7 判定一致。 + +### 3.3 Opus 4.7 审查（追加 8 项）验证 + +| Opus 编号 | 概述 | DeepSeek 判定 | 备注 | +|---|---|---|---| +| G-01 | 错误分类学完全缺失 | **确认 P0** | error-taxonomy-v1.md 301 行，覆盖率 0%，前两份均遗漏 | +| G-02 | Capability Trust 生命周期 | **确认 P1** | trust level + lifecycle 缺失 | +| G-03 | Artifact URI/ID/文件名规范 | **确认 P1** | artifact-naming-v1 完整定义 | +| G-04 | Provider 运行时不可变规则溯源 | **确认 P2** | 为设计阶段新增决策，应追加 ADR | +| G-05 | PromptLayer L0-L9 不一致 | **确认 P2** | 9 层 vs 10 层，L2 safety 缺失 | +| G-06 | Event route 追加规则 | **确认 P2** | - | +| G-07 | EventBus handler 错误行为 | **确认 P2** | - | +| G-08 | command_runs 状态派生 | **确认 P2** | - | + +**Opus 4.7 交叉验证结论**：8/8 确认属实，无误判，准确率 100%。G-01 错误分类学是三份审查中最重要的独立发现。 + +### 3.4 三份审查整体准确性 + +| 审查方 | 总缺口 | 误判 | 准确率 | 独有发现力 | +|---|---|---|---|---| +| GPT-5 | 26 | 0 | 100% | 全面但漏掉错误分类学、capability trust、artifact naming | +| MIMO 2.5 | 10 (追加) | 2 (B-09, B-10) | 80% | 补充了调度器/主代理状态机、FK-off 等结构缺口 | +| Opus 4.7 | 8 (追加) | 0 | 100% | 首次发现错误分类学 0% 覆盖，是最大独有贡献 | + +三份审查形成互补： +- GPT-5 覆盖面最广但粒度不均有遗漏 +- MIMO 2.5 补充了结构/状态机层面但有两项误判 +- Opus 4.7 补上了错误分类学、capability trust、artifact naming 等前三方均遗漏的专项基线 + +--- + +## 4. DeepSeek 独立发现 + +以下为前三份审查均未报告的额外缺口： + +### D-01 C4 模块视图中的服务依赖图未被概要设计反映（P1） + +来源：`c4/module.md` §4 的 Mermaid 依赖图定义了 packages/ 间精确的导入方向（contracts ← runtime, contracts ← llm, contracts ← toolchain-cpp, contracts ← tui, contracts ← cli），并标注了禁止路径（tui → runtime, llm → toolchain-cpp 等）。 + +现状：概要设计 §4-§6 文字描述了各 package 的职责和依赖，但缺少可视化的依赖拓扑图。C4 module.md 的核心产物（依赖图）未在概要设计中体现。 + +建议：可在 §4 末尾加入 module.md 依赖图的文字总结或直接引用。 + +### D-02 solution-architecture.md 解法架构的四个关键设计决策未被显式引用（P1） + +来源：`solution-architecture.md` §4 定义了四个核心设计决策： +1. 事件驱动 + SQLite 恢复（Event-driven with SQLite recovery） +2. 工具注册 + 权限引擎（ToolRegistry + PermissionEngine for all side effects） +3. Anthropic 规范内格式 + 供应商适配器边界（Anthropic canonical internal + provider boundary） +4. Bun 子进程工作池 + NDJSON IPC（Bun worker pool with NDJSON IPC） + +现状：概要设计 §2 描述了系统为 "self-owned local AI coding runtime"，§9 描述了事件流，§12 描述了权限，§14 描述了供应商适配器。这四个决策分散在概要设计中，但从未被明确定义为 "框架层决策" 或引用 solution-architecture.md。 + +建议：§2 末尾或新增摘要段落，以 "V1 Architecture Design Decisions" 形式列出四个决策及其基线来源。 + +### D-03 decisions-round-1/2/3.md 关键 ADR 在概要设计中无交叉引用（P2） + +来源：三轮 ADR 共 59 条决策（D-001~D-020, D-021~D-037, D-038~D-059），涵盖 monorepo 结构、IPC 选择、权限模板、医生 fix 模式等实现级决策。 + +现状：概要设计仅 §1 中列出了 `adr/` 目录路径，未在任何章节中引用具体的核心 ADR 编号。 + +建议：在各相关章节末尾添加 "Key ADR references" 短列表，例如 §11 IPC 可引用 ADR-0005、§12 权限可引用 ADR-0007 等。此建议为 P2，可在详细设计阶段补充。 + +### D-04 DB 关闭枚举清单未被概要设计反映（P2） + +来源：`db-schema-v1.md` §21 "Closed Enum Inventory" 表列出了 18 行 × 3 列的枚举值清单（status enums, type enums, dependency types 等）。 + +现状：概要设计 §8.2 描述了 session/task/agent/tool 等表，但未提及关闭枚举清单的存在或重要性。Enum 变化是 DB 迁移的核心触发条件之一。 + +建议：§8.2 末尾添加对 db-schema §21 Closed Enum Inventory 的引用。 + +### D-05 session.db 物理路径和存储周期未描述（P2） + +来源：baselineV1 §11 定义了 session DB 存放于 `.air/local/sessions//session.db`，session 之间共享只读 `debug-records.db` 和 `learned-memory.db`（baselineV1 §12）。 + +现状：概要设计 §8.1 描述了项目级 `.air/local/` 和 `.air/shared/` 下的子目录结构，但未描述 session DB 的具体路径和 session 间的数据库共享拓扑。 + +### D-06 OpenCode UI 复用边界中 do-not-reuse list 的隐患（P2） + +来源：baselineV1 §18 明确列出了可复用（theme, dialog, modal, toast, keymap, layout, spinner, border, error, markdown, code, diff）和不可复用（SDK, sync, session）的 OpenCode UI 组件。 + +现状：概要设计 §14 描述了 TUI 基于 OpenTUI/Solid 构建，mention 了 "OpenCode UI reusable components"，但未区分 reuse list 和 do-not-reuse list。不区分可能导致实现阶段意外引入 OpenCode session/sync 逻辑。 + +### D-07 idea.md 原始愿景中的 "zero-config C++ workflow" 未被提及（P2） + +来源：idea.md §2 将 "zero-config C++ developer experience" 列为核心理念。 + +现状：概要设计 §10.6 描述了 C++ 工作流，但未提及 "zero-config" 理念。这影响 UX 验收标准（用户不需要手动写 CMakeLists 或 .airconfig 即可开始）。 + +--- + +## 5. 全量缺口汇总 + +### P0 — 必须修复才能安全进入详细设计 + +| ID | 缺口 | 基线来源 | 发现方 | 概要设计位置 | +|---|---|---|---|---| +| P0-01 | 源文档清单仅 11/24 | 全部 24 份基线 | GPT-5, MIMO, Opus | §1 | +| P0-02 | 产品定位 "not a wrapper" + 规范循环 | baselineV1 §1, idea.md | GPT-5 | §2 | +| P0-03 | Global `~/.air/` layout + project_id UUID | baselineV1 §5 | GPT-5 | §8.1 | +| P0-04 | Claude Code 执行原语系统约束 | requirements FR-009, baselineV1 §2, runtime-semantics §9 | GPT-5 | 新增或 §10 | +| P0-05 | 权限边界细则（PathRisk 8 种、CommandRisk 10 种、7 rules） | security-model §4-§5 | GPT-5 | §12 | +| P0-06 | IPC 退出码 0-5 + envelope 必需字段 | baselineV1 §8, interface-contracts §10 | GPT-5 | §11 | +| P0-07 | TaskSpec/WorkerResult 字段族 + failed vs blocked 语义 | baselineV1 §9, interface-contracts §9-§11 | GPT-5 | §10 | +| P0-08 | 错误分类学（ErrorKind/severity/retryability/semantic signature） | error-taxonomy-v1 全文 | **Opus 4.7** | 新增 | +| P0-09 | RuntimeEvent route append-only + version increment + route_text 派生 | baselineV1 §7, event-registry §2 | GPT-5, Opus | §9 | +| P0-10 | SQLite 消息存储不变量（canonical format, drafts 删除, message_parts 非 V1） | baselineV1 §13, db-schema §4-§5 | GPT-5 | §8.2 | + +共 10 项 P0，与前三次审查收敛一致。 + +### P1 — 影响完整性，建议在概要设计补充 + +| ID | 缺口 | 基线来源 | 发现方 | +|---|---|---|---| +| P1-01 | 参考项目影响和复用边界 | baselineV1 §2 | GPT-5 | +| P1-02 | 技术栈约束条目（Bun/Turborepo/OpenTUI/Python/tarball） | baselineV1 §3, requirements §5 | GPT-5 | +| P1-03 | Scheduler 状态机（11 states） | scheduler-state-machine §2-§4 | MIMO | +| P1-04 | Main Agent 状态机（9 states） | main-agent-state-machine 全文 | MIMO | +| P1-05 | FK-off 8 条不变量 | runtime-semantics §14 | MIMO | +| P1-06 | 日志架构（air.log + dev log + 7d retention） | baselineV1 §23, requirements FR-019 | GPT-5 | +| P1-07 | 迁移架构 | baselineV1 §22 | GPT-5 | +| P1-08 | 扫描器语义（无排除、无深度限制） | runtime-semantics §10 | GPT-5 | +| P1-09 | 分发章节（tarball 内容） | baselineV1 §25, cross-platform §9 | GPT-5 | +| P1-10 | 测试分层（unit/integration fixture replay/E2E real LLM） | baselineV1 §24 | GPT-5 | +| P1-11 | contracts 包文件清单（16 files） | code-view §3 | GPT-5 | +| P1-12 | C++ Ninja-first/Make-fallback/clangd CLI mode | baselineV1 §20, tool-registry §7 | GPT-5 | +| P1-13 | Provider 能力矩阵摘要（quality/cost tier） | provider-capability-matrix 全文 | GPT-5 | +| P1-14 | Capability Trust 生命周期和 trust level 5 级 | capability-trust §6-§7 | Opus | +| P1-15 | Artifact URI/ID/文件名规范 | artifact-naming §3-§5 | Opus | +| P1-16 | C4 module 依赖图可视化 | c4/module.md §4 | **DeepSeek** | +| P1-17 | Solution Architecture 四个核心设计决策显式引用 | solution-architecture.md §4 | **DeepSeek** | + +共 17 项 P1，其中 D-01 和 D-02 为 DeepSeek 独立发现。 + +### P2 — 可在详细设计补充 + +| ID | 缺口 | 基线来源 | 发现方 | +|---|---|---|---| +| P2-01 | ScopeImpactLevel 7 级分类 | scope-escalation §2 | MIMO | +| P2-02 | Workspace GC 保留天数 | runtime-semantics §15 | MIMO | +| P2-03 | Cross-DB outbox 5 步流程 | runtime-semantics §6 | MIMO | +| P2-04 | ExperienceMiner 触发所有权 | runtime-semantics §17 | MIMO | +| P2-05 | PromptLayer L0-L9 一致性（L2 safety 缺失，层数 9 vs 10） | prompt-layering §2 | Opus | +| P2-06 | EventBus handler 异常处理 | interface-contracts §7 | Opus | +| P2-07 | command_runs 状态派生语义 | runtime-semantics §5 | Opus | +| P2-08 | Provider 运行时不可变规则 ADR 溯源 | 设计阶段决策 | Opus | +| P2-09 | OpenCode UI 复用边界（reuse + do-not-reuse list） | baselineV1 §18 | GPT-5 部分, DeepSeek | +| P2-10 | UI 设计资源能力 | baselineV1 §19 | GPT-5 | +| P2-11 | ADR 关键决策在概要设计中交叉引用 | decisions-round-1/2/3 | **DeepSeek** | +| P2-12 | DB 关闭枚举清单引用 | db-schema §21 | **DeepSeek** | +| P2-13 | session.db 物理路径和 DB 共享拓扑 | baselineV1 §11-§12 | **DeepSeek** | +| P2-14 | "zero-config C++ workflow" 理念 | idea.md §2 | **DeepSeek** | + +共 14 项 P2，其中 D-03~D-07 共 5 项为 DeepSeek 独立发现。 + +--- + +## 6. 三视角评估 + +### 6.1 架构一致性（7.0/10） + +容器边界、组件职责、依赖方向、事件分类（durable/ephemeral）、权限层级、上下文分层等核心架构决策在概要设计中得到了忠实反映。扣分点： +- 错误分类学是事件/工具/Scheduler 的语义基础，缺失导致架构图中的错误流无法推导（-1.5） +- 调度器和主代理状态机是两个关键运行时状态模型，缺失使架构运行时的行为无法从概要设计完整理解（-1.0） +- C4 模块依赖图未可视化反映（-0.5） + +### 6.2 工程可实现性（5.0/10） + +工程师拿到概要设计后，可以理解系统由哪些 package 组成，但无法直接开始实现。主要原因： +- IPC 退出码、envelope 字段、握手协议细节缺失（-1.5） +- TaskSpec/WorkerResult 字段族语义缺失，failed/blocked 行为无定义入口（-1.0） +- 错误分类学缺失，工具/worker/事件层面的错误如何传播和路由无定义（-1.5） +- 权限 PathRisk/CommandRisk 分类细节缺失，PathPolicy 实现无下钻依据（-0.5） +- FK-off 不变量、cross-DB outbox 步骤缺失（-0.5） + +### 6.3 需求对齐（5.5/10） + +FR-001~FR-018 在概要设计中可追溯或可推导。主要差距： +- FR-009 Claude Code 执行原语没有作为系统级约束（-1.5） +- FR-019 日志诊断缺失（-0.5） +- FR-020 测试分层缺失（-0.5） +- 约束条件 §5（Bun/Turborepo/tarball 等）未在技术基线中说明（-1.0） +- idea.md zero-config 理念未落地（-0.5） + +--- + +## 7. 四份审查对比矩阵 + +| 维度 | GPT-5 | MIMO 2.5 | Opus 4.7 | DeepSeek V4 Pro | +|---|---|---|---|---| +| 总评分 | 未给分 | 5.6 | 5.9 | **5.7** | +| P0 | ~10 | 10 | 10 | **10** | +| P1 | ~12 | 12 | 16 | **17** | +| P2 | ~4 | 未细分 | 10 | **14** | +| 独立新发现 | 26 | +10 | +8 | **+7 (D-01~D-07)** | +| 误判 | 0 | 2 | 0 | **0** | +| 最独特贡献 | 首次全覆盖 | 结构/状态机补充 | 首次发现错误分类学缺失 | Cap Trust + C4 依赖图 + solution decisions + zero-config | + +### 7.1 四份审查的各自优势视角 + +| 审查方 | 优势视角 | +|---|---| +| GPT-5 | 广度优先：首次扫出了最多缺口，覆盖了需求到分发的全范围 | +| MIMO 2.5 | 结构优先：补充了调度器/主代理状态机、FK-off、GC 等结构级遗漏 | +| Opus 4.7 | 深度优先：发现了错误分类学（P0）、capability trust、artifact naming 等专项基线的零覆盖问题 | +| DeepSeek V4 Pro | 设计溯源优先：发现了 C4 依赖图、solution architecture 四决策、ADR 交叉引用、zero-config 理念等 "设计决策→概要设计" 的溯源链断裂 | + +### 7.2 P0 缺口跨审查稳定性 + +10 项 P0 缺口中，GPT-5 首次报告了 9 项，Opus 4.7 追加了 1 项（错误分类学）。四份审查在 P0 层面高度一致，无实质性分歧。 + +**P0 缺口已高度稳定**，可以确信这 10 项是所有审查方认同的必须修复项。 + +--- + +## 8. 修复方案 + +### 8.1 推荐策略 + +**仅修复 P0（10 项），P1 在详细设计文档中作为前置参考清单列出。** + +### 8.2 P0 修复映射 + +| P0 ID | 概要设计修改 | 增量行数 | 参考基线 | +|---|---|---|---| +| P0-01 | 补全 §1 源文档至 24 份 | +25 | 全部 | +| P0-02 | 补入 §2 "not a wrapper" + canonical V1 loop | +10 | baselineV1 §1 | +| P0-03 | 新增 §8.1.1 Global ~/.air/ layout + project_id UUID | +25 | baselineV1 §5 | +| P0-04 | 新增 §10.7 Claude Code Execution Discipline | +15 | requirements FR-009, runtime-semantics §9 | +| P0-05 | 扩展 §12 补充 PathRisk/CommandRisk 分类和 7 条规则 | +30 | security-model §4-§5 | +| P0-06 | 扩展 §11 补充 IPC exit codes 0-5 + envelope 核心字段表 | +15 | baselineV1 §8, interface-contracts §10 | +| P0-07 | 新增 §10.8 TaskSpec/WorkerResult 字段族概要 | +20 | baselineV1 §9, interface-contracts §9-§11 | +| P0-08 | 新增 §9.5 Error Taxonomy Overview | +25 | error-taxonomy-v1 | +| P0-09 | 扩展 §9 补充 route append-only/version/route_text | +10 | baselineV1 §7, event-registry §2 | +| P0-10 | 扩展 §8.2 补充 message storage invariants | +10 | baselineV1 §13, db-schema §4-§5 | + +预计总增量：约 185 行，概要设计从 603 行增至约 788 行。 + +修复工作量估计：30-45 分钟。 + +--- + +## 9. 门禁判定 + +| 条件 | 当前 | 目标 | +|---|---|---| +| P0 缺口数为 0 | ❌ (10) | ✅ | +| 架构一致性 ≥ 7.5/10 | ❌ (7.0) | ✅ | +| 工程可实现性 ≥ 7.0/10 | ❌ (5.0) | 需 P0 修复 | +| 需求对齐 ≥ 7.0/10 | ❌ (5.5) | 需 P0 修复 | + +**结论：不建议在 P0 修复前进入详细设计。** + +P0 修复后将满足门禁条件：架构一致性预计升至 8.5，工程可实现性升至 7.0，需求对齐升至 7.0。 + +--- + +## 10. DeepSeek 与前三次审查的主要分歧 + +### 10.1 分歧点 + +| 问题 | DeepSeek 立场 | 对比方 | +|---|---|---| +| 参考项目边界应列为 P0 还是 P1 | **P1**：参考项目边界影响技术选型理解但不影响实现方向，工程师不读 reference projects 仍可实现核心功能 | GPT-5 判为 P0 | +| ScopeImpactLevel 应列为 P1 还是 P2 | **P2**：概要设计 §10.5 已有 Architecture Designer gate 规则，7 级 impact level 在 scope-escalation 基线可查，不影响概要设计整体结构 | MIMO 判为 P1 | +| C4 依赖图缺失是否为 P1 | **P1**：依赖图是 C4 module.md 的核心产物，映射到 packages/ 的实现禁止路径是防止架构退化的重要约束，应在概要设计层面明确 | DeepSeek 独立发现 | + +### 10.2 分歧分析 + +GPT-5 将参考项目边界判为 P0，DeepSeek 判为 P1。理由：P0 的定义是 "影响实现方向或基线矛盾"。参考项目边界缺失不会导致实现者走错方向（因为概要设计已经定义了组件的职责和边界），只是缺少 "为什么不重复造轮子" 的背景。工程师可以从概要设计的组件定义直接开工，参考项目边界是补充理解而非必要条件。 + +MIMO 将 ScopeImpactLevel 判为 P1，DeepSeek 判为 P2。理由：概要设计 §10.5 已经覆盖了 Architecture Designer gate 的 10 条触发规则和 3 种 gate 组合（architecture-sensitive/phase-complete/final consistency），这些规则隐含了对 impact level 的判断逻辑。7 级分类的枚举补充属于详细设计阶段的细化工作。 + +--- + +## 附录 A：基线覆盖热力图 + +| 基线文档 | 概要设计覆盖 | 缺口严重度 | +|---|---|---| +| requirements.md | ▓▓▓▓▓▓▓░░░ 70% | P0×2, P1×1, P2×1 | +| baselineV1.md | ▓▓▓▓▓░░░░░ 50% | P0×4, P1×4, P2×2 | +| solution-architecture.md | ▓▓▓▓▓▓▓▓░░ 80% | P1×1 | +| interface-contracts-v1.md | ▓▓▓▓▓▓░░░░ 60% | P0×2, P1×0, P2×1 | +| db-schema-v1.md | ▓▓▓▓▓▓▓░░░ 70% | P0×1, P2×1 | +| event-registry-v1.md | ▓▓▓▓▓▓▓▓░░ 80% | P0×1, P2×1 | +| runtime-semantics-v1.md | ▓▓▓▓▓▓░░░░ 60% | P0×1, P1×1, P2×3 | +| c4/module.md | ▓▓▓▓▓▓▓▓▓░ 90% | P1×1 | +| c4/code-view.md | ▓▓▓▓▓▓░░░░ 60% | P1×1 | +| main-agent-state-machine.md | ▓▓▓▓▓░░░░░ 50% | P1×1 | +| scheduler-state-machine-v1.md | ▓▓▓░░░░░░░ 30% | P1×1 | +| scope-escalation-v1.md | ▓▓▓▓▓▓▓▓░░ 80% | P2×1 | +| security-model-v1.md | ▓▓▓▓░░░░░░ 40% | P0×1 | +| capability-trust-v1.md | ▓▓▓░░░░░░░ 30% | P1×1 | +| provider-capability-matrix-v1.md | ▓▓▓░░░░░░░ 30% | P1×1 | +| prompt-layering-v1.md | ▓▓▓▓▓▓▓░░░ 70% | P2×1 | +| artifact-naming-v1.md | ▓▓░░░░░░░░ 20% | P1×1 | +| error-taxonomy-v1.md | ░░░░░░░░░░ **0%** | **P0×1** | +| tool-registry-v1.md | ▓▓▓▓▓▓░░░░ 60% | P1×1 | +| cross-platform-matrix-v1.md | ▓▓▓▓▓░░░░░ 50% | P1×1 | +| decisions-round-1/2/3.md | ▓▓▓▓░░░░░░ 40% | P2×1 | +| idea.md | ▓▓▓▓▓▓░░░░ 60% | P2×1 | + +--- + +## 附录 B：全量缺口索引（按概要设计章节） + +| 章节 | 缺口 ID | 严重度 | +|---|---|---| +| §1 源文档 | P0-01 | P0 | +| §2 系统目标 | P0-02, D-02 | P0, P1 | +| §2 技术基线 | P1-02 | P1 | +| §2 参考项目 | P1-01 | P1 | +| §4-§6 Package | P1-11, P1-16, D-02 | P1×3 | +| §6 Capability | P1-14 | P1 | +| §8.1 项目布局 | P0-03, D-05 | P0, P2 | +| §8.2 存储 | P0-10, P1-05, P1-15, D-04, D-05 | P0, P1×2, P2×2 | +| §9 事件/投影 | P0-08, P0-09, P2-03, P2-06, P2-07 | P0×2, P2×3 | +| §10 执行流 | P0-04, P0-07, P1-03, P1-04, P1-12, P2-01, P2-14 | P0×2, P1×3, P2×2 | +| §11 IPC | P0-06 | P0 | +| §12 权限 | P0-05, P2-04 | P0, P2 | +| §13 上下文/记忆 | P2-05, P2-04 | P2×2 | +| §14 UI/Provider | P1-13, P2-08, P2-09, P2-10 | P1, P2×3 | +| §15 Doctor/Restore | P2-02 | P2 | +| §17 验证 | P1-10 | P1 | +| 无对应章节 | P1-06, P1-07, P1-08, P1-09, P1-17, P2-11, P2-12, P2-13 | P1×5, P2×3 | diff --git a/AirPlan/docs/architecture/Opus4.7概要设计审查.md b/AirPlan/docs/architecture/Opus4.7概要设计审查.md new file mode 100644 index 0000000..4bde2cc --- /dev/null +++ b/AirPlan/docs/architecture/Opus4.7概要设计审查.md @@ -0,0 +1,401 @@ +# Opus 4.7 概要设计全量交叉审查 + +Date: 2026-05-29 +Reviewer: Claude Opus 4.7 +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 行，19 节） + +审查基线（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 第一轮 | +| 22 | `decisions-round-2.md` | ADR 第二轮 | +| 23 | `decisions-round-3.md` | ADR 第三轮 | +| 24 | `idea.md` | 原始设计构想 | + +额外参考： +- `gpt5概要设计审查.md`（GPT-5 审查，同日） +- `mimo2.5概要设计审查.md`（MIMO v2.5 审查，同日） + +方法： +- 逐基线 item-by-item 语义比对，非标题/关键词匹配 +- 对 GPT-5 和 MIMO 2.5 审查逐项交叉验证，标注确认、误判或遗漏 +- 从三个独立视角审查：架构一致性、工程可实现性、需求/基线对齐 +- 冻结基线不修改，概要设计标注差异并解决 +- P0 = 影响实现方向或基线矛盾，P1 = 影响完整性但有基线可查，P2 = 可在详细设计补充 + +--- + +## 2. 总体评估 + +### 2.1 概要设计优势 + +1. **容器/组件视图完整**：§4-§6 覆盖了全部 6 个 package 的职责、依赖和产出，与 c4/module.md 一致。 +2. **事件/投影流清晰**：§9 的 durable/ephemeral 分类和 ProjectionStore 规则与 event-registry-v1.md 一致。 +3. **执行流覆盖面广**：§10.1-§10.6 涵盖 startup、normal request、direct mode、tool call、review gate、C++ workflow 六条路径。 +4. **Architecture Designer gate 设计完善**：§10.5 的 10 条触发规则和 gate 组合规则与 scope-escalation-v1.md 一致。 +5. **权限层级正确**：§12 的 6 层评估顺序与 security-model-v1.md 和 runtime-semantics-v1.md §8 一致。 +6. **上下文/压缩/经验挖掘**：§13 覆盖了 PromptLayer 顺序、Compaction 语义和 ExperienceMiner 触发，与 prompt-layering-v1.md 和 runtime-semantics-v1.md §7/§11/§17 一致。 +7. **Doctor/Restore/Recovery**：§15 覆盖了 Doctor 自检引导、三粒度 restore、DB/workspace 恢复。 +8. **实现阶段映射**：§16 的 Phase 0-8 和关键串行约束与 todo.md T-001~T-037 对应。 + +### 2.2 系统性缺口 + +| 缺口类别 | 涉及基线 | 影响 | +|---|---|---| +| 源文档清单不完整（11/24） | 全部 | 下游设计无法溯源 | +| 全局 `~/.air/` 布局缺失 | baselineV1 §5 | project_id UUID 和全局配置无定义 | +| Claude Code 执行原语未系统化 | requirements FR-009, baselineV1 §2 | 下游工具实现无质量基准 | +| 权限边界细则缺失 | security-model-v1 §4-§5 | realpath/`.git/`/build/sudo/project-outside-backup 规则缺失 | +| TaskSpec/WorkerResult 字段语义缺失 | baselineV1 §9, interface-contracts §9-§11 | failed vs blocked 语义、summary 用途无定义 | +| IPC 退出码和 envelope 字段缺失 | baselineV1 §8, interface-contracts §10 | 工程实现无依据 | +| 错误分类学完全缺失 | error-taxonomy-v1 全文 | ErrorKind/severity/retryability/semantic signature 无定义 | +| 日志/迁移/扫描器/分发章节缺失 | baselineV1 §21-§25, requirements FR-019 | 4 个子系统无概要设计入口 | +| 参考项目影响和技术栈约束缺失 | baselineV1 §2-§3 | 执行纪律和复用边界不清 | +| 调度器状态机语义缺失 | scheduler-state-machine-v1 全文 | 11 个状态和转换条件无概要 | + +### 2.3 综合评分 + +| 维度 | 得分 (1-10) | 说明 | +|---|---|---| +| 架构一致性 | 7.5 | 容器/组件/事件/权限/上下文大方向一致，但错误分类学、调度器状态机、执行原语系统化缺失 | +| 需求覆盖 | 6.0 | FR-001~FR-018 覆盖良好，FR-009 执行原语、FR-019 日志、FR-020 测试分层、约束条件 §5 缺失 | +| 工程可实现性 | 5.5 | 缺少 IPC 退出码、TaskSpec 字段族、错误分类学、权限细则等实现必需信息 | +| 基线溯源 | 4.5 | 源文档仅列 11/24，无法回溯 13 份冻结基线 | +| 总分 | **5.9/10** | 骨架良好但实现可操作性不足 | + +--- + +## 3. GPT-5 审查交叉验证 + +对 GPT-5 审查报告的 26 项缺口逐一交叉验证： + +| GPT-5 编号 | GPT-5 缺口摘要 | Opus 4.7 判定 | 理由 | +|---|---|---|---| +| 3.1 | 产品定位 "not wrapper" 和完整循环缺失 | **确认 P0** | baselineV1 §1 明确定义，概要设计 §2 虽说"self-owned"但未明确"不是 wrapper"，循环缺失 | +| 3.2 | 参考项目边界缺失 | **确认 P1** | baselineV1 §2 定义了 5 个参考项目和复用边界，概要设计完全未提及 | +| 3.3 | 技术基线缺失 | **确认 P1** | Bun/Turborepo/OpenTUI 包名/Python/tarball 均未出现 | +| 3.4 | `~/.air/` 全局布局缺失 | **确认 P0** | baselineV1 §5 定义了 config.yaml/models.yaml/project-index.db/cache/skills/logs 等，概要设计仅有项目级 | +| 3.5 | `project_id` UUID 缺失 | **确认 P0**（合并到 3.4） | baselineV1 §5 明确 "stable UUID generated at initialization" | +| 3.6-3.10 | RuntimeEvent 路由/版本/IPC 字段/退出码 | **确认 P0** | IPC 退出码 0-5 在 baselineV1 §8 明确定义，概要设计 §11 完全缺失 | +| 3.11-3.13 | TaskSpec/WorkerResult 字段族 | **确认 P0** | failed vs blocked 语义、summary 用途、output_contract 在 baselineV1 §9 明确，概要设计无展开 | +| 3.14 | Claude Code 执行原语缺失 | **确认 P0** | requirements FR-009 和 baselineV1 §2 将此列为核心质量基准 | +| 3.15-3.17 | 权限边界 7 条规则缺失 | **确认 P0** | security-model §4 的 8 个 PathRiskCategory 和 §5 的 10 个 CommandRisk 均未反映 | +| 3.18-3.20 | 日志/迁移/扫描器缺失 | **确认 P1** | baselineV1 §21-§23 和 runtime-semantics §10 有完整定义 | +| 3.21 | 分发章节缺失 | **确认 P1** | baselineV1 §25 和 cross-platform-matrix §9 定义了 tarball 内容 | +| 3.22 | 测试分层缺失 | **确认 P1** | baselineV1 §24 区分了 unit/integration/E2E 三层 | +| 3.23 | contracts 包文件清单缺失 | **确认 P1** | code-view §3 列出了 16 个预期文件 | +| 3.24-3.25 | C++ 细节/Provider 矩阵摘要 | **确认 P1** | Ninja/Make 优先级、compile_commands 策略、quality/cost tier 概念缺失 | +| 3.26 | UI 设计资源能力缺失 | **确认 P2** | baselineV1 §19 定义了 ui-design-assets capability | + +**GPT-5 审查准确率：26/26 = 100%**。无误判。所有缺口经 Opus 4.7 逐基线验证确认存在。 + +--- + +## 4. MIMO 2.5 审查交叉验证 + +MIMO 2.5 在 GPT-5 基础上增加了 10 项缺口（标记为 baseline gap list B-01~B-10）： + +| MIMO 编号 | MIMO 缺口摘要 | Opus 4.7 判定 | 理由 | +|---|---|---|---| +| B-01 | 源文档 11/24 → 应补全至 24 | **确认 P0** | 概要设计 §1 仅列 11 份，无法溯源 scope-escalation、security-model、error-taxonomy 等 13 份 | +| B-02 | Scheduler 状态机语义缺失 | **确认 P1** | scheduler-state-machine §4 定义了 11 个状态和转换条件，概要设计仅有 "Scheduler computes runnable wave" 一句 | +| B-03 | Main Agent 状态机缺失 | **确认 P1** | main-agent-state-machine.md 定义了 IDLE→CLASSIFYING→ANSWERING/DELEGATING/DIRECT_MODE 等 9 个状态，概要设计仅描述了 3 个流程 | +| B-04 | ScopeImpactLevel 全分类未引用 | **确认 P1** | scope-escalation §2 定义了 7 级 impact level，概要设计 §10.5 只覆盖了 Architecture Designer gate 触发规则 | +| B-05 | Workspace GC 保留规则缺失 | **确认 P2** | runtime-semantics §15 定义了具体保留天数（merged 7d, abandoned 3d），概要设计 §15 仅提"retention policy" | +| B-06 | FK-off 8 条不变量缺失 | **确认 P1** | runtime-semantics §14 列出 8 条应用层强制规则，概要设计 §8.2 仅提"repository-level invariant checks" | +| B-07 | Cross-DB outbox 具体步骤缺失 | **确认 P2** | runtime-semantics §6 定义了 session-DB-first 5 步流程，概要设计 §8.3 仅提"session-DB-first intent + external write + completion/failure event" | +| B-08 | ExperienceMiner 触发所有权缺失 | **降级 P2** | 概要设计 §13 已列出 4 条触发，但未明确"Scheduler owns trigger creation; ExperienceMiner never self-triggers"（runtime-semantics §17），影响有限 | +| B-09 | Doctor 自检引导步骤 | **已覆盖** | 概要设计 §15 列出了 5 步 Doctor 自检，与 runtime-semantics §18 一致 | +| B-10 | `air restore` 三粒度 | **已覆盖** | 概要设计 §15 列出了 file/time/session 三粒度，与 runtime-semantics §19 一致 | + +**MIMO 2.5 审查准确率：8/10 = 80%**。B-09 和 B-10 为误判（概要设计已覆盖）。 + +--- + +## 5. Opus 4.7 独立发现 + +以下为 GPT-5 和 MIMO 2.5 均未报告的额外缺口： + +### G-01 错误分类学完全缺失（P0） + +来源：`error-taxonomy-v1.md` 全文（301 行） + +现状：概要设计从 §1 到 §19 完全没有提及 `ErrorKind`、`ErrorSeverity`、`Retryability`、`AirError`、`semantic_signature`。错误分类学定义了 21 种 ErrorKind、4 种 severity、4 种 retryability、failure signature 格式和 Scheduler 路由规则。这是工具/事件/Worker/Scheduler 实现的核心依赖。 + +建议：新增 §12.5 或 §9.5 Error Taxonomy Overview，至少覆盖： +- AirError 作为统一错误契约 +- ErrorKind 主要分类和路由规则 +- semantic_signature 格式和用途 +- Retryability 与 Scheduler 路由映射 + +### G-02 Capability Trust 生命周期缺失（P1） + +来源：`capability-trust-v1.md` §7 定义了 discovered→validated→doctor_checked→enabled→registered→active→disabled|failed|updated 完整生命周期 + +现状：概要设计 §6 提到 CapabilityRegistry 但仅描述 "manifest discovery/validation/enable"。未描述 trust level（built_in/project_local/user_installed/verified_publisher/untrusted）和生命周期阶段。 + +### G-03 Artifact 命名和 URI 规范缺失（P1） + +来源：`artifact-naming-v1.md` 定义了 URI 格式 `artifact://project//session//`、ID 格式 `art_`、文件名格式 `--`、类型到目录映射表。 + +现状：概要设计 §8.2 提到"artifact files use temp-write → hash → rename → DB record"但未引用 URI/ID/filename 规范。 + +### G-04 Provider 运行时不可变规则的语义不足（P1） + +来源：概要设计 §14 说"runtime provider/model selection is fixed for a running session and must not be changed" + +现状：此规则在概要设计中表述正确，但缺少基线支撑 — baselineV1 §17 仅描述了 provider layer 一般架构，并未明确定义运行时不可变约束。此规则是在多模型审查阶段新增的设计决策，应追加 ADR 记录或在概要设计中标注来源为"设计阶段决策，非基线原文"。 + +### G-05 PromptLayer 分层命名不一致（P2） + +来源：`prompt-layering-v1.md` §2 定义了 L0-L9 共 10 层，每层有明确名称（L0 Runtime invariant, L1 Role/agent mode, L2 Safety and permission policy, ...L9 Immediate instruction） + +现状：概要设计 §13 列出了层名但缩写了（"runtime invariant; role; project rules; task spec; architecture context; evidence/tool output; conversation; user override; debug context"）。L2 "safety and permission policy" 被省略为未出现，L9 "immediate instruction" 未列出。层数仅 9 项而基线为 10 层。 + +### G-06 Event 路由追加规则缺失（P2） + +来源：baselineV1 §7 "route is an append-only structured route chain"；event-registry §2 rule 5 "route is append-only. Forwarders append their route segment; they never rewrite earlier route entries" + +现状：概要设计 §9 未提及 `route` 的 append-only 语义和 `route_text = route.join("/")` 派生规则。 + +### G-07 EventBus handler 错误行为缺失（P2） + +来源：interface-contracts-v1.md §7 rule 5 "If a subscribe handler throws, the error is caught, logged to developer log, and does not propagate to the publisher. The subscription remains active." + +现状：概要设计 §9 的 EventBus 描述未提及 handler 异常处理规则。 + +### G-08 command_runs 状态派生规则缺失（P2） + +来源：runtime-semantics-v1.md §5 定义了 command_runs 无物理 status 列，运行时从 completed_at/exit_code/cancellation metadata 派生 running/ok/error/cancelled/unknown 状态。 + +现状：概要设计未提及 command_runs 状态派生语义。 + +--- + +## 6. 全量缺口汇总与 P 级分类 + +### P0 — 影响实现方向或存在基线矛盾（必须修复才能进入详细设计） + +| ID | 缺口 | 涉及基线 | 概要设计位置 | +|---|---|---|---| +| P0-01 | 源文档清单 11→24 | 全部 24 份 | §1 | +| P0-02 | 产品定位 "not wrapper" + 规范循环 | baselineV1 §1 | §2 | +| P0-03 | 全局 `~/.air/` 布局 + project_id UUID | baselineV1 §5 | §8.1 | +| P0-04 | Claude Code 执行原语系统约束 | requirements FR-009, baselineV1 §2, runtime-semantics §9 | 新增或 §10 | +| P0-05 | 权限边界细则（7 rules） | security-model §4-§5 | §12 | +| P0-06 | IPC 退出码（0-5）和 envelope 字段 | baselineV1 §8, interface-contracts §10 | §11 | +| P0-07 | TaskSpec/WorkerResult 字段族 + failed/blocked 语义 | baselineV1 §9, interface-contracts §9-§11 | §10 或新增 | +| P0-08 | 错误分类学（ErrorKind/severity/retryability/signature） | error-taxonomy-v1 全文 | 新增 | +| P0-09 | RuntimeEvent 路由 append-only 和版本语义 | baselineV1 §7, event-registry §2 | §9 | +| P0-10 | SQLite 消息存储不变量（canonical format, drafts, message_parts） | baselineV1 §13, db-schema §4-§5 | §8.2 | + +### P1 — 影响完整性但有基线可查（建议在概要设计补充，否则须在详细设计开头注明） + +| ID | 缺口 | 涉及基线 | 概要设计位置 | +|---|---|---|---| +| P1-01 | 参考项目影响和复用边界 | baselineV1 §2 | 新增 | +| P1-02 | 技术栈约束条目 | baselineV1 §3, requirements §5 | §2 或新增 | +| P1-03 | Scheduler 状态机摘要（11 states） | scheduler-state-machine §2-§4 | §10.2 | +| P1-04 | Main Agent 状态机摘要（9 states） | main-agent-state-machine 全文 | §10.2 | +| P1-05 | ScopeImpactLevel 7 级分类 | scope-escalation §2 | §10.5 | +| P1-06 | FK-off 应用层 8 条不变量 | runtime-semantics §14 | §8.2 | +| P1-07 | 日志架构（air.log + encrypted dev log + 7d retention） | baselineV1 §23, requirements FR-019 | 新增 | +| P1-08 | 迁移架构（schema 检测、计划、确认、备份、回滚） | baselineV1 §22 | 新增 | +| P1-09 | 扫描器语义（无排除、无深度限制、symlink/error 处理） | runtime-semantics §10 | 新增 | +| P1-10 | 分发章节（tarball 内容 bin/air + resources + LICENSE） | baselineV1 §25, cross-platform §9 | 新增 | +| P1-11 | 测试分层定义（unit/integration fixture replay/E2E real LLM） | baselineV1 §24 | §17 | +| P1-12 | contracts 包文件清单（16 files） | code-view §3 | §4 | +| P1-13 | C++ 细节：Ninja-first/Make-fallback、compile_commands 按需、clangd CLI mode | baselineV1 §20, tool-registry §7 | §10.6 | +| P1-14 | Provider 能力矩阵摘要（quality/cost tier, conversion report） | provider-capability-matrix 全文 | §14 | +| P1-15 | Capability Trust 生命周期和 trust level | capability-trust §6-§7 | §6 | +| P1-16 | Artifact URI/ID/filename 规范引用 | artifact-naming §3-§5 | §8.2 | + +### P2 — 可在详细设计阶段补充 + +| ID | 缺口 | 涉及基线 | +|---|---|---| +| P2-01 | OpenCode UI 复用边界（reuse list + do-not-reuse list） | baselineV1 §18 | +| P2-02 | UI 设计资源能力（ASCII/wireframe/SVG/screenshot analysis） | baselineV1 §19 | +| P2-03 | Workspace GC 具体保留天数 | runtime-semantics §15 | +| P2-04 | Cross-DB outbox 具体 5 步流程 | runtime-semantics §6 | +| P2-05 | ExperienceMiner 触发所有权（Scheduler owns, never self-triggers） | runtime-semantics §17 | +| P2-06 | PromptLayer L0-L9 全名一致性（L2 safety 缺失，层数 9→10） | prompt-layering §2 | +| P2-07 | event route append-only 和 route_text 派生 | event-registry §2 | +| P2-08 | EventBus handler 异常处理 | interface-contracts §7 | +| P2-09 | command_runs 状态派生语义 | runtime-semantics §5 | +| P2-10 | Provider 运行时不可变规则 ADR 溯源 | 设计阶段决策 | + +--- + +## 7. 三视角联合评估 + +### 7.1 架构师视角 + +概要设计的容器边界、组件职责划分、依赖方向和禁止路径均与 C4 module/code-view 一致，这是最大的优势。Architecture Designer gate 规则完备。但缺少错误分类学意味着 Scheduler 路由决策和 Worker 失败语义在概要设计层面没有定义入口，详细设计无法直接从概要设计推导错误处理流程。 + +### 7.2 工程师视角 + +IPC 退出码、TaskSpec 字段族、PermissionEngine 具体分类规则、错误签名格式等是工程实现的直接依据。概要设计省略这些意味着实现者必须同时查阅 5+ 份基线文档才能开工。P0 级别的缺口直接影响 Phase 0-1 的 contracts 包和 storage 实现。 + +### 7.3 需求验证视角 + +FR-001~FR-018 在概要设计中有对应描述或可推导。FR-009（执行原语）、FR-019（日志）、FR-020（测试分层）和约束条件 §5 缺失。NFR-001~NFR-008 中 NFR-001 local-first、NFR-002 recoverability、NFR-005 UI responsiveness 覆盖良好，但 NFR-008 security boundary preservation 的细节在概要设计中不足（缺少 PathRiskCategory 和 CommandRisk 分类定义）。 + +--- + +## 8. 与先前审查的一致性对比 + +| 维度 | GPT-5 | MIMO 2.5 | Opus 4.7 | +|---|---|---|---| +| 总分 | 未给分 | 5.6/10 | 5.9/10 | +| P0 缺口数 | ~10 | 10 | 10 | +| P1 缺口数 | ~12 | 12 | 16 | +| P2 缺口数 | ~4 | 未细分 | 10 | +| 独立发现 | 26 items | +10 items | +8 items (G-01~G-08) | +| 误判率 | 0% | 20% (B-09, B-10) | N/A | +| 最关键遗漏 | 错误分类学未报告 | 错误分类学未报告 | 错误分类学 P0 报告 | + +三份审查的核心结论一致：概要设计骨架良好，但实现可操作性不足，P0 缺口必须修复才能安全进入详细设计。 + +**GPT-5 和 MIMO 2.5 共同遗漏的最大缺口**是错误分类学（error-taxonomy-v1.md），该文件 301 行定义了整个运行时的错误传播和路由基础，概要设计完全未引用。 + +--- + +## 9. 修复建议 + +### 9.1 推荐修复策略 + +仅应用 P0 补丁（10 项），P1/P2 在详细设计阶段作为设计输入补充。此方案下可进入详细设计，但需在详细设计文档开头注明概要设计的已知缺口。 + +### 9.2 P0 补丁清单 + +| P0 ID | 修改位置 | 修改内容 | 预计行数 | +|---|---|---|---| +| P0-01 | §1 Source documents | 补全 24 份源文档 | +30 | +| P0-02 | §2 System Goal | 补入 "not a wrapper"、canonical V1 loop | +8 | +| P0-03 | §8.1 Project layout | 新增 Global `~/.air/` layout + project_id UUID | +25 | +| P0-04 | §10 (新增 §10.7) | Claude Code execution discipline 系统约束 | +15 | +| P0-05 | §12 | 补充 PathRiskCategory 8 种、CommandRisk 10 种、7 条规则 | +30 | +| P0-06 | §11 | 补充 IPC exit codes 0-5、envelope 必需字段 | +15 | +| P0-07 | §10 (新增 §10.8) | TaskSpec/WorkerResult 字段族概要 + failed/blocked 语义 | +20 | +| P0-08 | 新增 §12.5 或 §9.5 | Error Taxonomy Overview | +25 | +| P0-09 | §9 | 补充 route append-only、version increment、route_text 派生 | +8 | +| P0-10 | §8.2 | 补充 canonical format = anthropic JSON、drafts 删除规则、message_parts 非 V1 表 | +8 | + +预计总增量：约 184 行，概要设计从 603 行增至约 787 行。 + +### 9.3 P1 处理建议 + +在详细设计文档（或 class diagram freeze 文档）开头附录中列出 16 条 P1 缺口及其基线引用，确保实现者知道需要查阅哪些基线。 + +--- + +## 10. 进入详细设计的门禁判定 + +| 条件 | 状态 | +|---|---| +| P0 缺口全部修复 | **未满足**（10 项待修复） | +| P1 缺口有溯源路径 | 满足（基线可查） | +| 架构一致性 > 7/10 | 满足（7.5） | +| 需求覆盖 > 7/10 | **未满足**（6.0） | + +**结论：不建议在 P0 修复前进入详细设计。** + +P0 修复预计工作量约 30-45 分钟（184 行概要设计补丁），修复后可立即进入详细设计 / class diagram freeze。 + +--- + +## 附录 A：三份审查缺口交叉索引 + +| 概要设计位置 | GPT-5 | MIMO 2.5 | Opus 4.7 | P 级 | +|---|---|---|---|---| +| §1 源文档 | 3.1 提及 | B-01 | P0-01 | P0 | +| §2 产品定位 | 3.1 | R-01 | P0-02 | P0 | +| §2 参考项目 | 3.2 | - | P1-01 | P1 | +| §2 技术栈 | 3.3 | R-04 | P1-02 | P1 | +| §8.1 ~/.air/ | 3.4+3.5 | B-01 partial | P0-03 | P0 | +| §8.2 SQL 消息 | - | - | P0-10 | P0 | +| §8.2 FK-off | - | B-06 | P1-06 | P1 | +| §9 事件路由 | 3.6-3.8 | - | P0-09 | P0 | +| §9.5 错误分类 | **未报告** | **未报告** | G-01/P0-08 | **P0** | +| §10 执行原语 | 3.14 | R-01 | P0-04 | P0 | +| §10.2 TaskSpec/WR | 3.11-3.13 | - | P0-07 | P0 | +| §10.2 Scheduler SM | - | B-02 | P1-03 | P1 | +| §10.2 Main Agent SM | - | B-03 | P1-04 | P1 | +| §10.5 ScopeImpact | - | B-04 | P1-05 | P1 | +| §11 IPC 退出码 | 3.9-3.10 | - | P0-06 | P0 | +| §12 权限细则 | 3.15-3.17 | - | P0-05 | P0 | +| §13 PromptLayer | - | - | P2-06 | P2 | +| §13 ExperienceMiner | - | B-08 | P2-05 | P2 | +| §14 Provider | 3.25 | - | P1-14 | P1 | +| §14 UI 复用 | - | - | P2-01 | P2 | +| §15 Workspace GC | - | B-05 | P2-03 | P2 | +| 日志 | 3.18 | R-02 | P1-07 | P1 | +| 迁移 | 3.19 | - | P1-08 | P1 | +| 扫描器 | 3.20 | - | P1-09 | P1 | +| 分发 | 3.21 | - | P1-10 | P1 | +| 测试分层 | 3.22 | R-03 | P1-11 | P1 | +| contracts 清单 | 3.23 | - | P1-12 | P1 | +| C++ 细节 | 3.24 | - | P1-13 | P1 | +| Capability 生命周期 | - | - | G-02/P1-15 | P1 | +| Artifact 命名 | - | - | G-03/P1-16 | P1 | +| UI 设计资源 | 3.26 | - | P2-02 | P2 | + +--- + +## 附录 B：基线覆盖热力图 + +| 基线文档 | 概要设计覆盖程度 | 缺口数 | +|---|---|---| +| requirements.md | ▓▓▓▓▓▓▓░░░ 70% | 4 | +| baselineV1.md | ▓▓▓▓▓░░░░░ 50% | 10 | +| solution-architecture.md | ▓▓▓▓▓▓▓▓░░ 80% | 1 | +| interface-contracts-v1.md | ▓▓▓▓▓▓░░░░ 60% | 4 | +| db-schema-v1.md | ▓▓▓▓▓▓▓░░░ 70% | 2 | +| event-registry-v1.md | ▓▓▓▓▓▓▓▓░░ 80% | 2 | +| runtime-semantics-v1.md | ▓▓▓▓▓▓░░░░ 60% | 5 | +| c4/module.md | ▓▓▓▓▓▓▓▓▓░ 90% | 0 | +| c4/code-view.md | ▓▓▓▓▓▓░░░░ 60% | 1 | +| main-agent-state-machine.md | ▓▓▓▓▓░░░░░ 50% | 1 | +| scheduler-state-machine-v1.md | ▓▓▓░░░░░░░ 30% | 1 | +| scope-escalation-v1.md | ▓▓▓▓▓▓▓▓░░ 80% | 1 | +| security-model-v1.md | ▓▓▓▓░░░░░░ 40% | 2 | +| capability-trust-v1.md | ▓▓▓░░░░░░░ 30% | 1 | +| provider-capability-matrix-v1.md | ▓▓▓░░░░░░░ 30% | 1 | +| prompt-layering-v1.md | ▓▓▓▓▓▓▓░░░ 70% | 1 | +| artifact-naming-v1.md | ▓▓░░░░░░░░ 20% | 1 | +| error-taxonomy-v1.md | ░░░░░░░░░░ **0%** | **1** | +| tool-registry-v1.md | ▓▓▓▓▓▓░░░░ 60% | 1 | +| cross-platform-matrix-v1.md | ▓▓▓▓▓░░░░░ 50% | 1 | +| decisions-round-1/2/3.md | ▓▓▓▓░░░░░░ 40% | 0 | +| idea.md | ▓▓▓▓▓▓░░░░ 60% | 0 | + +**覆盖最差基线**：error-taxonomy-v1.md（0%）、artifact-naming-v1.md（20%）、capability-trust-v1.md（30%）、scheduler-state-machine-v1.md（30%）、provider-capability-matrix-v1.md（30%）。 diff --git a/AirPlan/docs/architecture/gpt5概要设计审查.md b/AirPlan/docs/architecture/gpt5概要设计审查.md new file mode 100644 index 0000000..0ebcb68 --- /dev/null +++ b/AirPlan/docs/architecture/gpt5概要设计审查.md @@ -0,0 +1,648 @@ +# GPT-5 概要设计审查 + +Date: 2026-05-29 +Status: Traceability audit of `system-overview-design.md` against 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` + +审查基线（冻结，不修改）： + +1. `AirPlan/docs/analysis/requirements.md` +2. `AirPlan/docs/architecture/baselineV1.md` +3. `AirPlan/docs/architecture/solution-architecture.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. `idea.md` + +原则：冻结基线不再修改。概要设计在基线之上补充设计决策，不修改基线原文。基线与概要设计冲突时以基线为准，概要设计标注差异并解决。 + +--- + +## 2. 总体结论 + +`system-overview-design.md` 在容器、运行时组件、事件/投影、执行流、权限、上下文、UI/HUD、Doctor/restore、验证门禁等大方向上与基线一致。主要缺口集中在： + +- 参考项目边界和执行层质量基准未明确 +- 技术栈细节（Bun/Turborepo/OpenTUI 包名/Python/分发）缺失 +- 全局 `~/.air/` 布局和 `project_id` UUID 未提及 +- 事件 envelope/路由/版本规则、IPC 字段/退出码未展开 +- TaskSpec/WorkerResult 字段族和 failed vs blocked 语义缺失 +- Claude Code 执行原语（read-before-edit、exact edit、verification-before-completion）未明确 +- 权限边界规则（realpath、`.git/` 保护、build 目录不受限、`~/.air/` 内部绕过、`sudo` 不自动高危、项目外写入备份）未完整 +- 日志、迁移、扫描器/初始化、分发、测试分类、contracts 包文件清单缺失 +- C++ 工具链细节（Ninja/Make 优先级、compile_commands 按需生成、clangd CLI 模式、DiagnosticParser 所有权已解决但需确认）不完整 +- Provider 能力矩阵摘要、OpenCode UI 复用边界、UI 设计资源能力缺失 + +以下按基线章节逐项列出缺口和建议补充内容。 + +--- + +## 3. 逐项缺口清单 + +### 3.1 产品定位（baseline §1） + +缺口：概要设计未明确"not a Claude Code plugin/wrapper"；未列出完整编码循环（requirement → architecture → code reading → implementation → build → static analysis → test → run/debug → evidence → fix → summary → mining）。 + +建议补入概要设计 §2： + +```md +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 +``` + +### 3.2 参考项目与边界（baseline §2） + +缺口：概要设计未说明参考影响和复用边界。 + +建议新增 §2.1 Reference Influence： + +```md +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. +``` + +### 3.3 技术基线（baseline §3） + +缺口：概要设计未明确 Bun、Bun workspaces + Turborepo、OpenTUI 包名、SQLite、NDJSON、Python subprocess-only、binary tarball。 + +建议补入 §3 或新增 §3.1 Technology Baseline： + +```md +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 +``` + +### 3.4 包集与未来扩展（baseline §4） + +缺口：未来 `toolchain-python`、`toolchain-rust`、`toolchain-js` 未提及；`runtime must never depend on tui` 未显式说明。 + +建议补入 §4 或 §5： + +```md +Future language packages: +- packages/toolchain-python +- packages/toolchain-rust +- packages/toolchain-js + +Invariant: runtime must never import tui. +``` + +### 3.5 全局目录与 project_id（baseline §5） + +缺口：全局 `~/.air/` 布局完全缺失；`project_id` 是稳定 UUID 未提及；`.air/local/` 应 gitignore 未提及。 + +建议新增 §8.0 Global Filesystem Layout： + +```md +Global user directory: + +~/.air/ + config.yaml + models.yaml + permissions.yaml + compaction-rules.md + project-index.db + cache/{plugins,providers,lsp,downloads}/ + resources/versions// + 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. +``` + +### 3.6 运行时架构细节（baseline §6） + +缺口：Main Agent 保持 idle-ready、不执行后台工作的规则未显式；Scheduler 详细职责（TaskGraph、waves、conflicts、retries、workspaces、heartbeat、merge、restart recovery）未展开；worker 是独立角色循环而非通用循环未说明。 + +建议补入 §6 或 §7： + +```md +Main Agent must remain idle-ready and never perform long-running background work. + +Scheduler owns: TaskGraph loading, dependency resolution, write-area conflict handling, +wave planning, retry budgets, child worker dispatch, heartbeat monitoring, workspace +merge coordination, and restart recovery. + +Each worker is an independent role loop (Executor/Reviewer/Debugger/Compactor/ExperienceMiner), +not a single generic worker loop. +``` + +### 3.7 RuntimeEvent envelope（baseline §7） + +缺口：envelope 字段、`route` append-only 规则、EventStore 决定持久化策略、payload schema 变更需递增 event version 未展开。 + +建议补入 §9： + +```md +RuntimeEvent envelope: 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. +``` + +### 3.8 IPC 协议细节（baseline §8） + +缺口：Bun 子进程、IPC envelope 字段、stdout-only 协议、stderr 致命回退、退出码映射未展开。 + +建议补入 §11： + +```md +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 = success +1 = task failed +2 = worker crashed +3 = protocol error +4 = timeout +5 = cancelled +``` + +### 3.9 TaskSpec / WorkerResult（baseline §9） + +缺口：TaskSpec 字段族（type、scope、deps、verification、constraints、refs、output_contract）和 WorkerResult 字段族（status、changed_files、artifacts、verification、risks、follow_up_tasks、evidence）未展开；`failed` vs `blocked` 语义未定义。 + +建议新增 §10.7 TaskSpec and WorkerResult Overview： + +```md +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. +``` + +### 3.10 工具与能力系统（baseline §10） + +缺口：ToolDefinition schema 验证规则、`shell.run` 对应 Bash 命令、流式工具最终结果规则、能力 manifest/trust/dependency 生命周期未展开。 + +建议补入 §10.4 或 §12： + +```md +ToolDefinition uses schema-validated input/output at registration and dispatch. +Shell commands run through `shell.run` tool. +Streaming tools emit progress events and must end with exactly one final `tool.result`. + +Capability lifecycle: +- manifest load → validation → enable/disable → namespaced tool registration +- dependencies checked/installed by Doctor, not by arbitrary plugin scripts +- trust metadata: built_in | project_local | user_installed | verified_publisher | untrusted +``` + +### 3.11 Claude Code 执行原语（FR-009） + +缺口：read-before-edit、exact conservative edits、small patches、no unrelated refactors、verification-before-completion 未作为系统级约束。 + +建议新增 §10.8 Execution Discipline： + +```md +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 +``` + +### 3.12 权限边界规则（baseline §11-12, security-model） + +缺口：realpath symlink 解析、`.git/` 写保护、build 目录不受限、`~/.air/` 内部绕过 PermissionEngine、`sudo` 不自动高危、静态高危白名单 + LLM escape hatch、项目外写入需先备份到 `.air/local/backups/`。 + +建议补入 §12： + +```md +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. +``` + +### 3.13 SQLite / 消息存储（baseline §13） + +缺口：WAL/NORMAL 设置、`foreign_keys = OFF` + 应用层不变量、Anthropic canonical content JSON 存储、draft 删除规则、`message_parts` 不作为源表、查询友好列、`ui_state` 定期/退出时刷新未说明。 + +建议补入 §8.2 或 §13： + +```md +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. + +`ui_state` is not source of truth for runtime state; it is flushed periodically and on exit. +``` + +### 3.14 Contracts 包文件清单（baseline §14） + +缺口：`packages/contracts/src/` 的文件清单（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）未列出。 + +建议补入 §4 或新增 §4.1 Contracts Package Baseline： + +```md +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 +``` + +### 3.15 Artifact 命名与布局（baseline §15a） + +缺口：artifact URI/ID 命名规范、目录映射、压缩规则、metadata 记录、evidence 链接 artifact ID 未展开。 + +建议补入 §8.2 或 §6： + +```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. +``` + +### 3.16 Context / Compaction（baseline §15b） + +缺口：ContextAssembler 输出 Anthropic canonical messages、记录 token 预算 omissions、`context.compaction.requested`、compaction rules 文件格式（Markdown + YAML frontmatter）、位置（built-in / `~/.air/compaction-rules.md` / `/.air/shared/compaction-rules.md`）、copy-on-write 语义未完整。 + +建议补入 §13： + +```md +ContextAssembler outputs Anthropic canonical messages and records omissions. +Compaction rules use Markdown + YAML frontmatter at: +- built-in default +- ~/.air/compaction-rules.md +- /.air/shared/compaction-rules.md + +Compaction uses copy-on-write: snapshot messages, async Compactor produces summary, +original messages preserved for backtracking. +``` + +### 3.17 Memory / Skills / Debug Knowledge（baseline §16） + +缺口：project rules 路径（`/.air/shared/rules/`）、skills 路径（`~/.air/skills//SKILL.md`）、promotion 策略（非调试经验需重复出现 + 用户确认，调试经验以验证证据为置信度）、debug sharing 需 redaction/preview/显式授权。 + +建议补入 §13 或 §8.3： + +```md +Project rules: /.air/shared/rules/{project-rules.md,toolchain-rules.md} +Skills: ~/.air/skills//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. +``` + +### 3.18 Provider 能力矩阵（baseline §17） + +缺口：Anthropic/OpenAI 原生、OpenRouter/ollama/custom 兼容、provider conversion report、同提供商切换无格式转换成本（但 V1 session 选择在启动后固定）未说明。 + +建议补入 §6 或 §14： + +```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. +``` + +### 3.19 OpenCode UI 复用边界（baseline §18） + +缺口：OpenCode 复用的具体 UI 原语列表和不复用 SDK/sync/session 业务状态的规则。 + +建议补入 §14： + +```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. +``` + +### 3.20 UI 设计资源能力（baseline §19） + +缺口：可选 `ui-design-assets` 能力（ASCII/wireframe/spec/SVG/screenshot analysis/外部 prompt、bitmap post-MVP、artifacts first、preview before project writes）缺失。 + +建议补入 §14 或 §2： + +```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. +``` + +### 3.21 C++ 工具链细节（baseline §20） + +缺口：CMake Ninja-first/Make fallback、CTest/GoogleTest、cppcheck（clang-tidy later）、clangd CLI mode、`compile_commands.json` 按需生成不缓存、build-system 冲突展示给用户、内置修复优先然后路由 Debugger。 + +建议补入 §10.6： + +```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. +``` + +### 3.22 项目初始化（baseline §21） + +缺口：full metadata-only scanner（完整目录树、无排除、无深度限制）、extension stats / special files / git summary、LLM ProjectProfile + 用户确认、schema path 检测。 + +建议新增 §15.1 Project Initialization： + +```md +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. +``` + +### 3.23 Schema 迁移（baseline §22） + +缺口：检测 schema 版本、用户确认迁移计划（即使高权限模式也确认）、备份 `.air/`、失败回滚、迁移备份路径。 + +建议新增 §15.2 Schema Migration： + +```md +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// +5. apply migration +6. on failure, rollback to backup +``` + +### 3.24 日志与 Bundle（baseline §23） + +缺口：`air.log`（用户可读）、`air.developer.log`（加密，开发团队公钥）、7 天保留、doctor bundle 不自动脱敏/不自动上传、bundle 与 debug knowledge 分离。 + +建议新增 §15.3 Logging： + +```md +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. +``` + +### 3.25 测试分类（baseline §24） + +缺口：unit/integration/E2E 定义、recorded LLM fixture replay for integration、real LLM for release gate E2E、cross-platform validation matrix。 + +建议补入 §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). +``` + +### 3.26 分发（baseline §25） + +缺口：tarball 内容（`bin/air`、`resources/`、`LICENSE`）、resources 内容（templates、prompts、themes、HUD presets、Python scripts、toolchain resources）、无 npm/brew/apt/winget 直到稳定。 + +建议新增 §17.1 Distribution： + +```md +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. +``` + +### 3.27 冻结基线完整列表（baseline §26） + +缺口：概要设计 §1 的 source documents 列表不完整，缺少多个冻结基线。 + +建议更新 §1： + +```md +Source documents (frozen baselines): + +1. requirements.md +2. solution-architecture.md +3. baselineV1.md +4. interface-contracts-v1.md +5. db-schema-v1.md +6. event-registry-v1.md +7. runtime-semantics-v1.md +8. c4/module.md +9. c4/code-view.md +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 +22. decisions-round-2.md +23. decisions-round-3.md +24. idea.md +25. todo.md + +Where decision rounds conflict, later rounds supersede earlier rounds for V1.0.0 Alpha +unless a frozen architecture baseline explicitly says otherwise. +``` + +--- + +## 4. FR/NFR 覆盖矩阵 + +### 4.1 Functional Requirements + +| FR | 覆盖状态 | 缺口 | +|---|---|---| +| FR-001 CLI Startup | 已覆盖 | — | +| FR-002 Project-Local State | 已覆盖 | 全局 ~/.air/ 缺失 | +| FR-003 Session Persistence | 部分覆盖 | WAL/NORMAL、canonical message JSON、draft 删除、no message_parts 缺失 | +| FR-004 Event-Driven Runtime | 部分覆盖 | envelope/route/version 规则缺失 | +| FR-005 Main Agent | 已覆盖 | — | +| FR-006 Architecture Designer | 已覆盖 | review gate 已补 | +| FR-007 Scheduler | 部分覆盖 | dependency/write-area/timeout/retry/concurrency 细节不足 | +| FR-008 Worker Agents | 已覆盖 | — | +| FR-009 Claude Code Primitives | 缺失 | read-before-edit、exact edit、verification-before-completion 未作为系统约束 | +| FR-010 Built-In Tools | 部分覆盖 | 工具清单不完整 | +| FR-011 Permission/Security | 部分覆盖 | 边界规则缺失 | +| FR-012 Capability Foundation | 部分覆盖 | source/trust/namespaced registration 需明确 | +| FR-013 Provider Layer | 部分覆盖 | provider 列表/兼容矩阵缺失 | +| FR-014 Context/Compaction | 部分覆盖 | omissions、Anthropic canonical output、rule locations 缺失 | +| FR-015 Artifact/Evidence | 已覆盖 | — | +| FR-016 TUI/HUD | 已覆盖 | OpenCode UI 复用边界缺失 | +| FR-017 C++ Workflow | 部分覆盖 | Ninja/Make、compile_commands、clangd 细节缺失 | +| FR-018 Doctor | 已覆盖 | first-start/fix nuance 部分缺失 | +| FR-019 Logging | 缺失 | 双日志、加密 dev log、7 天保留 | +| FR-020 Release Gate | 已覆盖 | — | + +### 4.2 Non-Functional Requirements + +| NFR | 覆盖状态 | 缺口 | +|---|---|---| +| NFR-001 Local-First | 已覆盖 | — | +| NFR-002 Recoverability | 已覆盖 | — | +| NFR-003 Extensibility | 已覆盖 | — | +| NFR-004 Provider Flexibility | 部分覆盖 | 跨 provider 稳定性列表不明确 | +| NFR-005 UI Responsiveness | 部分覆盖 | Main Agent/TUI 保持响应需显式说明 | +| NFR-006 Evidence-Based Completion | 已覆盖 | — | +| NFR-007 Linux-First | 部分覆盖 | tier-1/tier-2/experimental 平台矩阵不完整 | +| NFR-008 Security Boundary | 已覆盖 | — | + +--- + +## 5. 需要用户决策的冲突点 + +### 5.1 D-014 vs 当前设计：DiagnosticParser 所有权 + +`decisions-round-1.md` D-014 要求所有 compiler/linker 输出由 LLM 解析。 + +当前概要设计和 `runtime-semantics-v1.md §12` 明确规定： + +- `toolchain-cpp` 只做确定性提取 +- LLM 解释归 Debugger/Reviewer + +这不是概要设计的错误，而是后续基线已覆盖了 D-014 的早期表述。建议在概要设计中注明： + +```md +D-014 (round-1 LLM-parsed diagnostics) is superseded by runtime-semantics §12 for V1.0.0 Alpha: +deterministic extraction in toolchain-cpp, LLM interpretation in Debugger/Reviewer context. +``` + +### 5.2 D-025/D-037 vs D-047：Compaction rules 文件格式 + +D-025/D-037（round-2）提到 YAML compaction rules。D-047（round-3）改为 Markdown + YAML frontmatter。概要设计应采用 round-3 的 Markdown 格式并注明 round-3 取代 round-2。 + +--- + +## 6. 修复建议优先级 + +### P0 — 概要设计必须补充（影响下游设计/实现） + +1. Claude Code 执行原语（§10.8） +2. 权限边界规则（§12 补充） +3. TaskSpec/WorkerResult 字段族和 failed/blocked 语义（§10.7） +4. RuntimeEvent envelope/route/version 规则（§9 补充） +5. IPC envelope 字段和退出码（§11 补充） +6. SQLite 消息存储不变量（§8.2 补充） +7. 全局 ~/.air/ 布局和 project_id（§8.0 补充） +8. 冻结基线完整列表（§1 更新） + +### P1 — 概要设计应补充（影响设计完整性） + +9. 参考项目影响和边界（§2.1） +10. 技术栈细节（§3.1） +11. 项目初始化/扫描器（§15.1） +12. Schema 迁移（§15.2） +13. 日志（§15.3） +14. C++ 工具链细节（§10.6 补充） +15. Context/Compaction 规则位置和格式（§13 补充） +16. Memory/Skills 路径和 promotion 策略（§13 补充） +17. 测试分类（§17 补充） +18. 分发（§17.1） +19. Contracts 包文件清单（§4.1） +20. Provider 能力矩阵摘要（§6 补充） + +### P2 — 概要设计可选补充 + +21. OpenCode UI 复用边界（§14 补充） +22. UI 设计资源能力（§14 补充） +23. Artifact 命名/布局摘要（§8.2 补充） +24. 未来语言包（§4 补充） +25. D-014 supersession 注明 +26. D-025/D-037 vs D-047 format conflict 注明 diff --git a/AirPlan/docs/architecture/mimo2.5概要设计审查.md b/AirPlan/docs/architecture/mimo2.5概要设计审查.md new file mode 100644 index 0000000..d128261 --- /dev/null +++ b/AirPlan/docs/architecture/mimo2.5概要设计审查.md @@ -0,0 +1,1550 @@ +# 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// + 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 +- /.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: /.air/shared/rules/{project-rules.md,toolchain-rules.md} +Skills: ~/.air/skills//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// +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 分钟。 diff --git a/AirPlan/docs/architecture/system-overview-design.md b/AirPlan/docs/architecture/system-overview-design.md new file mode 100644 index 0000000..6292e64 --- /dev/null +++ b/AirPlan/docs/architecture/system-overview-design.md @@ -0,0 +1,1222 @@ +# AirCoding V1.0.0 Alpha System Overview Design + +Date: 2026-05-29 +Status: System overview design for V1.0.0 Alpha after multi-model audit repair +Scope: Architecture-level design. No implementation code. + +## 1. Purpose + +This document turns the repaired AirCoding V1.0.0 Alpha architecture baseline into a system-level overview design. It is the bridge between the formal architecture baselines and the later detailed design / class diagram freeze. + +Frozen source documents: + +1. `AirPlan/docs/analysis/requirements.md` +2. `AirPlan/docs/architecture/baselineV1.md` +3. `AirPlan/docs/architecture/solution-architecture.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. `idea.md` + +Current-stage review inputs: + +1. `AirPlan/docs/architecture/gpt5概要设计审查.md` +2. `AirPlan/docs/architecture/mimo2.5概要设计审查.md` +3. `AirPlan/docs/architecture/Opus4.7概要设计审查.md` +4. `AirPlan/docs/architecture/DeepSeek概要设计审查.md` +5. `AirPlan/docs/architecture/多模型三视角审查联合评估.md` +6. `AirPlan/plan.md` +7. `AirPlan/todo.md` + +Baseline precedence: frozen source documents are authoritative. This overview may add design-stage alignment decisions and cross-document summaries, but it does not change frozen requirements or baselines. + +## 2. System Goal + +AirCoding V1.0.0 Alpha is a self-owned, Linux-first, local AI coding runtime. It is not a Claude Code plugin, wrapper, or thin shell around another coding agent. It owns its runtime state, event log, task scheduler, tool permission layer, artifact/evidence lifecycle, and UI projection. + +Canonical V1 coding loop: + +```text +requirement + → architecture/interface design + → code reading + → implementation planning + → scoped implementation + → build + → static analysis + → test + → run/debug + → crash/log/network/GUI evidence analysis + → fix + → review + → change summary + → experience mining +``` + +V1.0.0 Alpha must deliver a usable developer loop with: + +- global `~/.air` user state and project-local `.air` state; +- stable `project_id` UUID per initialized project; +- SQLite-backed session persistence and recovery; +- event-driven runtime behavior; +- isolated Bun child-process workers; +- ToolRegistry + PermissionEngine for all side effects; +- Anthropic-canonical provider boundary; +- OpenTUI/Solid terminal UI and HUD; +- complete zero-config-oriented C++ configure/build/test/static-analysis/debug/fix/review workflow; +- capability/plugin foundation; +- evidence-backed completion and release gates. + +Core architecture decisions inherited from `solution-architecture.md`: + +1. Event-driven runtime with SQLite recovery. +2. ToolRegistry + PermissionEngine for all side effects. +3. Anthropic canonical internal message format with provider adapter boundary. +4. Bun child-process workers over NDJSON IPC. + +Reference influences and reuse boundaries: + +| Reference | Used for | Not reused for | +|---|---|---| +| Claude Code | Execution-layer quality benchmark: read-before-edit, exact conservative edits, small patches, no unrelated refactors, verification-before-completion, evidence-backed closure | Runtime ownership or state model | +| OpenCode | UI visual patterns and OpenTUI primitives | SDK, sync, session, or business-state logic | +| Hermes Agent | Experience mining, Nudge triggers, Curator daemon, self-patch ideas, `SKILL.md` format | Runtime process model | +| OpenAI Codex | Shell/patch/test loop and tool orchestration ideas | Provider/runtime lock-in | +| Claude Skills | Skill directory layout and trigger descriptions | Untrusted side-effect bypass | +| asciinema / Atuin / claude-hud | PTY capture, command history indexing, HUD/statusline layout | Source of truth for runtime recovery | + +Technology baseline: + +- Runtime language: TypeScript on Bun. +- Monorepo: Bun workspaces + Turborepo. +- TUI: `@opentui/solid`, `@opentui/core`, `@opentui/keymap`. +- Storage: SQLite per session, project-local by default. +- IPC: NDJSON over stdio. +- Python: subprocess-only helper layer for existing scripts/libraries, not core runtime. +- Distribution: binary tarball before public package channels. + +Non-goals for V1.0.0 Alpha: + +- third-party plugin registry/signing; +- container sandboxing; +- multi-machine scheduling; +- Windows-native deep support; +- advanced semantic merge; +- production bitmap image generation provider integration. + +## 3. System Context + +```text +Developer + │ + ▼ +AirCoding CLI/TUI + │ + ├─ global ~/.air user state + ├─ local project files + ├─ project-local .air state + ├─ local shell/toolchains/debug tools + ├─ configured LLM providers + └─ optional display/network evidence tools +``` + +External dependencies: + +| External system | Role | Boundary rule | +|---|---|---| +| Global `~/.air` | User config, provider config, project index, global skills/cache/logs | User-local state; not project source of truth | +| Local project | Source files, build outputs, tests | All writes go through tools and permissions | +| `.air/shared` | Git-shareable project config/rules/plans | May be committed by user/project | +| `.air/local` | Private local DBs/artifacts/workspaces/backups | Gitignored by default | +| LLM providers | Model completions | Provider adapters convert at boundary | +| OS shell/toolchain | Build/test/debug/static analysis | ToolRegistry + PermissionEngine only | +| Git | Diff, status, worktree, merge, backup repo | Permissioned tools only | +| Display/network subsystems | GUI screenshots, pcaps | Explicit evidence tools, no automatic upload | + +## 4. Container Overview + +```text +packages/contracts + ▲ ▲ ▲ ▲ ▲ + │ │ │ │ │ +packages/cli ───▶ packages/runtime ───▶ packages/llm │ + │ │ │ │ + ▼ │ └── provider adapters │ +packages/tui │ │ + ├── packages/toolchain-cpp via capability/tools + ├── child worker processes over NDJSON IPC + ├── SQLite session/project DBs + └── project filesystem/artifacts/backups +``` + +Canonical dependency direction from C4 module view: + +```text +contracts ← cli +contracts ← runtime +contracts ← llm +contracts ← tui +contracts ← toolchain-cpp +runtime ← cli +runtime ← workers over IPC, not direct imports +llm ← runtime through ProviderManager facade +tui ← cli bootstrap and ProjectionClient contracts only +toolchain-cpp ← runtime through capability/tool boundary +``` + +| Container | Responsibility | Key outputs | +|---|---|---| +| `packages/contracts` | Shared TypeScript public contracts | RuntimeEvent, TaskSpec, WorkerResult, ToolDefinition, IPC, provider, UI, DB-facing types | +| `packages/cli` | Entry point, command routing, init/open project, Doctor, TUI bootstrap | CLI commands and startup lifecycle | +| `packages/tui` | OpenTUI/Solid views and HUD | User conversation, progress, evidence, permission prompts | +| `packages/runtime` | Main Agent, Architecture Designer, Scheduler, EventStore, ToolRegistry, PermissionEngine, context, artifacts, projection | Core orchestration and state ownership | +| `packages/llm` | Provider config, startup/session selection, adapters, conversion reports | ProviderManager facade and stream events | +| `packages/toolchain-cpp` | C++ capability/tools | `cpp.*` tools, deterministic diagnostics, evidence | +| worker processes | Executor/Reviewer/Debugger/Compactor/ExperienceMiner roles | WorkerResult, RuntimeEvents, tool calls | + +Future language packages may add `packages/toolchain-python`, `packages/toolchain-rust`, and `packages/toolchain-js`; V1.0.0 Alpha only requires `packages/toolchain-cpp`. + +Expected `packages/contracts/src/` public file set from code view: + +```text +index.ts +types.ts +errors.ts +events.ts +storage.ts +project.ts +scheduler.ts +workers.ts +tools.ts +permissions.ts +artifacts.ts +providers.ts +context.ts +projection.ts +capabilities.ts +doctor.ts +knowledge.ts +diagnostics.ts +``` + +## 5. Dependency Rules + +```text +contracts → no implementation dependencies +cli → runtime, tui, llm, toolchain-cpp +tui → contracts only for projection/UI contracts +runtime → contracts, llm facade, toolchain-* through capability boundary +llm → contracts +toolchain-cpp → contracts +workers → contracts and WorkerRuntime IPC surface +``` + +Forbidden paths: + +- TUI → SQLite direct query; +- TUI → runtime private service import; +- worker → SQLite direct write; +- worker → filesystem/shell/network side effect outside tool IPC; +- tool → side effect without PermissionEngine; +- capability → dependency install outside Doctor; +- provider adapter → silent semantic prompt loss; +- repository → scheduling policy; +- EventBus → recovery source of truth; +- runtime → TUI import; +- LLM output → direct file/shell side effect. + +## 6. Runtime Component Overview + +| Component | Owns | Calls | Emits / persists | +|---|---|---|---| +| Main Agent | User interaction, request classification, direct mode | ContextAssembler, ProviderManager, Scheduler, Architecture Designer | messages, `requirement.changed`, progress summaries | +| Architecture Designer | Architecture impact and plan/doc sync | ContextAssembler, ProviderManager, document stores | `architecture.plan.updated`, `architecture.impact.completed` | +| Scheduler | TaskGraph, wave planning, retries, workspaces, worker lifecycle | SessionStore, WorkerManager, ContextAssembler, EventIngestor | `task.*`, `agent.*`, `workspace.*` | +| WorkerManager | Child process spawn/monitor, IPC lifecycle | OS process APIs, WorkerProtocol | `agent.started/lost/completed/failed` | +| EventIngestor | Event intake boundary | EventStore, EventBus, EventSchemaRegistry | routes durable/ephemeral events | +| EventStore | Durable event validation and domain projection transaction | SQLite, EventSchemaRegistry | `events` + domain table rows | +| EventBus | Live pub/sub | subscribers only | ephemeral delivery and post-commit durable delivery | +| SessionStore | Repositories over session DB | SQLite | domain records | +| ToolRegistry | Tool registration and dispatch | PermissionEngine, ArtifactStore, EventIngestor | `tool.*`, ToolResultEnvelope | +| PermissionEngine | Action/risk decisions | PathClassifier, CommandRiskAnalyzer, EventIngestor | `permission.*` | +| CapabilityRegistry | Manifest discovery/validation/enable | ToolRegistry, DoctorService | capability config and registered tools | +| ContextAssembler | Prompt layering and context budget | SessionStore, ArtifactStore, PromptLayerLoader, CompactionPolicy | AssembledContext, compaction requests | +| ArtifactStore | Artifacts temp-write/rename/hash/read | filesystem, EventIngestor, SessionStore | artifacts table, `artifact.created` | +| EvidenceStore | Evidence refs and claim links | ArtifactStore, diagnostics | evidence_refs table | +| ProjectionStore | TUI/HUD view model | SessionStore, EventBus | derived ProjectionSnapshot | +| ProviderManager | Startup/session provider/model validation and streaming | provider adapters | ProviderStreamEvent, conversion reports | +| DoctorService | Environment/capability checks/fixes/bundles | CapabilityRegistry, PermissionEngine, tools | doctor events/artifacts | +| DebugKnowledgeStore | debug-records.db | project-level DB | DebugRecord rows | +| LearnedMemoryStore | learned-memory.db | project-level DB | LearnedMemory rows | +| Logger | user and developer logs | redaction/encryption policy | `air.log`, encrypted developer log | +| ProjectScanner | directory tree metadata scan | filesystem metadata only | project scan artifacts/warnings | +| MigrationManager | schema/version checks and migrations | SQLite, backup repo, PermissionEngine | migration plan/evidence | + +Main Agent must remain idle-ready and responsive. It never performs long-running background work itself; Scheduler dispatches background tasks to workers. + +Scheduler owns TaskGraph loading, dependency resolution, write-area conflict handling, wave planning, retry budgets, child worker dispatch, heartbeat monitoring, workspace merge coordination, and restart recovery. + +Capability lifecycle: + +```text +discovered + → validated + → doctor_checked + → enabled + → registered + → active + → disabled | failed | updated +``` + +Trust levels: + +```text +built_in | project_local | user_installed | verified_publisher | untrusted +``` + +Built-in and local manifests still pass schema validation and permission checks. Trust affects default enablement and prompt posture; it never bypasses ToolRegistry or PermissionEngine. + +## 7. Runtime Agent Overview + +| Agent/role | Process model | Writes project code? | Key inputs | Key outputs | +|---|---|---:|---|---| +| Main Agent | in runtime process | only in direct mode | user messages, projections, context | messages, routing decisions, summaries | +| Architecture Designer | in runtime process / LLM role | planning docs only | requirement changes, current architecture | impact assessment, plan/doc updates | +| Scheduler | in runtime process | no code writes | TaskGraph, events, worker results | wave plans, worker dispatch, task outcomes | +| Executor | child process | yes, scoped | TaskSpec, ContextPack, WorkerRuntime | ExecutorResult, diffs, artifacts, evidence | +| Reviewer | child process | no | diffs, evidence, architecture context | findings, verdict, follow-up tasks | +| Debugger | child process | yes if assigned | failure evidence, diagnostics, logs | diagnosis, fix/blocker, debug record | +| Compactor | child process | no project code | message snapshot, compaction rules | summary row/artifact | +| ExperienceMiner | child process | rules/skills only if assigned | verified patterns/evidence | memory/rule/skill candidates | + +Worker loops are independent role implementations, not one generic shared loop. + +## 8. State and Data Overview + +### 8.1 Filesystem layout + +Global user directory: + +```text +~/.air/ + config.yaml + models.yaml + permissions.yaml + compaction-rules.md + project-index.db + cache/ + plugins/ + providers/ + lsp/ + downloads/ + resources/versions// + skills/ + logs/ + air.log + air.developer.log +``` + +Project-local directory: + +```text +/.air/ + shared/ + project.json + permissions.yaml + compaction-rules.md + rules/ + plan/ + local/ + sessions// + session.db + artifacts/ + backups/ + debug-records.db + learned-memory.db + workspaces/ + tmp/ + locks/ +``` + +`project_id` is a stable UUID generated at project initialization and stored in `.air/shared/project.json`. It is not derived from the absolute path. `.air/local/` is gitignored by default. + +### 8.2 Session DB + +`session.db` lives at `.air/local/sessions//session.db` and owns recoverable per-session state: + +- sessions; +- messages; +- message_drafts; +- events; +- tasks; +- task_dependencies; +- task_attempts; +- agents; +- tool_runs; +- command_runs; +- artifacts; +- diagnostics; +- evidence_refs; +- workspaces; +- summaries; +- ui_state. + +Rules: + +1. Durable event insert and corresponding domain update occur in one SQLite transaction. +2. EventBus is never recovery source of truth. +3. `foreign_keys = OFF` is compensated by repository-level invariant checks and startup orphan scans. +4. Artifact files use temp-write → hash/size → atomic rename → DB record. +5. `ui_state` is not source of truth for runtime state. +6. Messages store Anthropic canonical JSON in `content_json` with `canonical_format = "anthropic"`. +7. `assistant.message.started` writes/updates `message_drafts`; `assistant.message.created` inserts the final `messages` row and deletes the draft. +8. V1 does not use a separate `message_parts` source-of-truth table. +9. Closed enum values are controlled by `db-schema-v1.md` and require migration review when changed. + +FK-off application invariants: + +1. `tasks.session_id` must reference an existing `sessions.id`. +2. `task_attempts.task_id` must reference an existing `tasks.id`. +3. `agents.task_id` must reference an existing `tasks.id` when not null. +4. `tool_runs.task_id` and `tool_runs.agent_id` must reference existing rows when not null. +5. `command_runs.task_id`, `command_runs.agent_id`, and `command_runs.tool_run_id` must reference existing rows when not null. +6. `workspaces.task_id` and `workspaces.agent_id` must reference existing rows when not null. +7. `diagnostics.command_run_id` and `diagnostics.artifact_id` must reference existing rows when not null. +8. `evidence_refs` foreign columns must reference existing rows when not null. + +`command_runs` status is derived, not stored as a physical V1 status column: + +| Row state | Derived status | +|---|---| +| `completed_at` is null | `running` | +| `exit_code = 0` | `ok` | +| `exit_code` non-zero | `error` | +| cancellation metadata present | `cancelled` | +| inconsistent row | `unknown` | + +### 8.3 Project-level DBs + +| DB | Purpose | Owner | +|---|---|---| +| `.air/local/debug-records.db` | verified failure/debug knowledge records | DebugKnowledgeStore | +| `.air/local/learned-memory.db` | candidates, promoted memories, archived/rejected entries | LearnedMemoryStore | + +Cross-DB and file writes use outbox/compensation semantics: + +```text +1. Insert durable session event recording intent/request. +2. Insert or update session domain row with pending/external status where applicable. +3. Perform external DB/file operation through owning service. +4. Emit durable completed/failed event with evidence. +5. On restart, recovery scans pending external intents and reconciles. +``` + +### 8.4 Artifact and evidence naming + +Artifacts use the canonical naming model from `artifact-naming-v1.md`: + +```text +artifact://project//session// +art_ +-- +``` + +Artifact type maps to a session artifact subdirectory. Evidence refs link claims to artifacts, diagnostics, command runs, tool runs, messages, agents, or tasks. Worker results embed full `EvidenceRef[]` when evidence is part of the conclusion; lightweight events may carry evidence IDs. + +## 9. Event, Error, and Projection Overview + +### 9.1 Event flow + +```text +Producer + → EventIngestor + → validate envelope, schema, and version + → durable? EventStore transaction + domain projection + EventBus post-commit publish + → ephemeral? EventBus publish/coalescing only + → ProjectionStore applies event + → TUI/HUD renders ProjectionSnapshot +``` + +RuntimeEvent envelope: + +```text +id +type +version +timestamp +session_id +project_id? +source +route[] +payload +``` + +Rules: + +1. `route` is append-only. Forwarders append their segment and never rewrite earlier entries. +2. `route_text` in SQLite is derived from `route.join("/")` for indexing. +3. EventStore decides durable vs ephemeral persistence by event type; producers do not decide ad hoc. +4. Payload schema changes require incrementing the event `version` for that event type. +5. Durable event insert and same-session domain projection happen in one SQLite transaction. +6. Durable events are published to EventBus only after commit. +7. EventBus handler errors are caught, logged to developer log, and do not propagate to the publisher; the subscription remains active. + +Durable events include session/message/task/agent/tool/command/artifact/diagnostic/evidence/context/summary/permission/doctor/requirement/architecture/workspace/memory/debug events. + +Ephemeral events include heartbeat, task progress, assistant delta, tool progress, command stdout/stderr deltas, HUD frame rendered. + +### 9.2 Error taxonomy + +All tool, event, worker, provider, and command failures use `AirError` rather than parallel ad hoc error shapes. + +`AirError` carries: + +```text +error_id +kind +severity +message +detail? +retryability +semantic_signature +cause_ref? +cause_refs? +user_action? +metadata? +``` + +Error kinds: + +```text +user_error +project_error +env_error +dependency_error +permission_error +tool_error +command_error +build_error +test_error +static_analysis_error +debug_error +provider_error +model_capability_error +context_error +agent_error +scheduler_error +workspace_error +merge_error +architecture_error +policy_error +system_error +unknown_error +``` + +Severity: + +```text +info | warning | error | fatal +``` + +Retryability: + +```text +retryable | retryable_after_change | not_retryable | unknown +``` + +`semantic_signature` is the stable grouping key for repeated failure detection, debug knowledge lookup, and Scheduler retry/debug/escalation routing. Scheduler decisions use error kind, retryability, severity, task scope, permission result, architecture impact, verification evidence, and repetition count. + +### 9.3 ProjectionStore + +ProjectionStore rules: + +- hydrate from DB on startup/resume; +- apply durable and key ephemeral events; +- coalesce noisy deltas; +- ignore unknown event types; +- never become scheduling/recovery source of truth. + +## 10. Execution Flow Overview + +### 10.1 Startup / open session + +```text +CLI + → load global config/resources + → locate or initialize project + → Doctor self-bootstrap and read-only startup check + → open session.db + → run schema/recovery checks + → hydrate ProjectionStore + → start TUI/HUD + → Main Agent ready +``` + +Doctor fix mode on first startup always asks before applying fixes, even in high-permission mode. + +### 10.2 Main Agent state machine + +Main Agent lifecycle: + +```text +IDLE + → CLASSIFYING + → ANSWERING | DELEGATING | DIRECT_MODE + → SCHEDULING | ARCHITECTURE_DESIGNING + → CONFIRMING when user confirmation is needed + → EXECUTING + → INTERRUPTING when requirements change mid-execution + → ARCHITECTURE_REVISING when design-level changes are required + → SUMMARIZING + → IDLE +``` + +Main Agent state rules: + +- IDLE/CLASSIFYING/ANSWERING/CONFIRMING/SUMMARIZING perform no task execution. +- DIRECT_MODE uses `permission_template = "main_direct"` and writes only to the main workspace. +- EXECUTING is Scheduler-owned; Main Agent reports progress and decisions. +- Requirement changes emit `requirement.changed` and route to Scheduler/Architecture Designer according to impact. + +### 10.3 Scheduler state machine + +Scheduler states: + +```text +IDLE + → LOADING_GRAPH + → PLANNING_WAVE + → DISPATCHING + → MONITORING + → MERGING + → REVIEWING + → RETRYING | DEBUGGING | ESCALATING | BLOCKED | COMPLETED | CANCELLED + → RECOVERING on restart/lost worker +``` + +Scheduler owns: + +- runnable task discovery; +- dependency and write-area serialization; +- wave planning; +- workspace assignment; +- model assignment according to constraints; +- worker dispatch; +- heartbeat timeout and lost-worker recovery; +- retry budget enforcement; +- review/debug routing; +- workspace merge and conflict handling; +- architecture/user escalation routing; +- recovery after restart. + +### 10.4 Normal user request + +```text +TUI/CLI user message + → Main Agent records message + → classify intent + → answer directly OR route work + → Architecture Designer if architecture/interface/product impact + → Scheduler creates TaskSpec records + → Scheduler computes runnable wave + → ContextAssembler builds ContextPack + → WorkerManager starts child worker + → worker uses WorkerRuntime for events/tools/checkpoints + → Scheduler collects WorkerResult + → review/debug/merge/retry/escalate as needed + → Main Agent reports result with evidence +``` + +### 10.5 Direct mode + +```text +/direct + → Main Agent enters DIRECT_MODE + → permission_template = main_direct + → direct ToolRegistry calls, main workspace only + → events recorded with source.kind = main +/done + → evidence collection + → summary + → IDLE +``` + +### 10.6 Tool call + +```text +Agent/worker + → ToolRegistry.call or IPC tool.call + → schema validation + → PermissionEngine.evaluate + → permission prompt if needed + → tool.started + → side effect / command / artifact + → tool.completed | tool.failed | tool.cancelled + → ToolResultEnvelope +``` + +Tool rules: + +- `ToolDefinition` includes input/output schemas, category, permissions, and streaming flag. +- `shell.run` is the AirCoding runtime equivalent of a controlled Bash execution primitive. +- `call()` consumes streaming internally and returns the final `ToolResultEnvelope`. +- `call_streaming()` exposes progress events and ends with exactly one final result envelope. + +### 10.7 Review and architecture gate + +Ordinary implementation tasks use the normal review path: + +```text +WorkerResult + → Reviewer + → Scheduler completes/retries/blocks based on ReviewerResult and evidence +``` + +Architecture-sensitive work adds an Architecture Designer gate: + +```text +WorkerResult + → Reviewer + → if architecture-sensitive: Architecture Designer impact/review gate + → Scheduler combines gates + → complete | retry | block | replan | ask user +``` + +Architecture Designer does not replace Reviewer. Reviewer owns implementation quality, correctness, security, tests, and evidence sufficiency. Architecture Designer owns interface/schema/event/package-boundary/security/runtime-semantics/ADR/C4/plan consistency. + +Trigger Architecture Designer gate when any are true: + +1. public function/class/module interface changes; +2. DB schema or persisted data shape changes; +3. IPC/event/tool/provider contract changes; +4. package dependency direction or component responsibility changes; +5. runtime semantics, security model, capability trust, or permission boundary changes; +6. ADR/C4/plan/todo architecture artifacts must change; +7. Reviewer emits `category = "architecture"`; +8. worker returns architecture/interface blocker; +9. phase completion requires architecture consistency review; +10. release/final completion requires full architecture consistency review. + +Scope impact levels: + +```text +implementation +interface +architecture +product +permission +environment +policy +``` + +Gate result rule: + +```text +Reviewer approved + Architecture gate approved/not_required = may complete +Reviewer changes_requested = retry/debug +Architecture requires_replan = route to Architecture Designer planning +Architecture requires_user_confirmation = Main Agent asks user +Architecture reject_or_escalate = block until explicit decision +``` + +### 10.8 C++ workflow + +```text +cpp.detect + → cpp.cmake.configure + → cpp.build + → deterministic DiagnosticParser + → cpp.test + → cpp.static.cppcheck + → cpp.clangd.query when needed + → Debugger for build/test/debug failures + → scoped fix loop + → Reviewer + → Architecture Designer gate if contracts/schema/events/boundaries changed + → evidence-backed verification +``` + +C++ toolchain rules: + +- CMake + Ninja is preferred when available. +- Make fallback is supported. +- `compile_commands.json` is generated or located when clangd/static analysis requires it. +- clangd is used in CLI/query mode for V1, not hidden inside a language-server UI integration. +- DiagnosticParser in `toolchain-cpp` performs deterministic extraction and semantic signature generation only. +- LLM-based diagnostic interpretation happens in runtime Debugger/Reviewer context, not inside `toolchain-cpp`. +- The user experience target is zero-config C++ onboarding where feasible: detect existing project shape before requiring manual `.air` configuration. + +### 10.9 Claude Code execution discipline + +All code-changing execution paths must preserve these runtime-level constraints: + +1. Read before edit: `fs.edit`/`fs.patch` require a recent read observation or expected file hash. +2. Exact edit: `old_string` must match exactly; non-unique matches fail unless replace-all is explicit. +3. Conservative patching: changes stay inside TaskSpec scope and write area. +4. No unrelated refactors: workers must not broaden scope to improve nearby code opportunistically. +5. Verification before completion: code-changing WorkerResult cannot be `completed` unless required verification passed, or skipped verification is explicitly allowed with evidence/risk. +6. Evidence-backed closure: diffs, command outputs, diagnostics, artifacts, or screenshots are linked through evidence refs. +7. Block instead of improvising when product, interface, architecture, permission, environment, or policy decisions are missing. + +### 10.10 TaskSpec and WorkerResult overview + +TaskSpec field families: + +```text +identity: id, type, title, description +acceptance: acceptance_criteria +scope: write_area, expected_files, allowed_paths, denied_paths +dependencies: hard, soft, conflict, serialization +verification: commands, required, fallback_allowed +constraints: max_turns, soft_timeout_ms, hard_timeout_ms, retry_budget, model_policy, model ids +context_refs: plan_ref, arc_ref, parent results, artifacts +output_contract: ExecutorResult | ReviewerResult | DebuggerResult | CompactorResult | ExperienceMinerResult +``` + +WorkerResult field families: + +```text +identity: task_id, agent_id, agent_type +status: completed | failed | blocked | cancelled +summary +changed_files +diff_ref +artifacts +verification +risks +follow_up_tasks +evidence_refs +result +``` + +Status semantics: + +| Status | Meaning | Scheduler behavior | +|---|---|---| +| `completed` | Acceptance met and verification policy satisfied | review/merge/complete | +| `failed` | Attempt failed due to error and may be retried/debugged according to retryability | retry/debug/fail | +| `blocked` | Cannot safely proceed without decision, environment fix, permission, dependency, or architecture assessment | escalate/block | +| `cancelled` | Task intentionally stopped | preserve evidence/workspace state | + +`summary` is user-facing and scheduler-readable; it must not hide unresolved risks or skipped verification. + +## 11. IPC and Worker Overview + +V1 uses NDJSON over stdio between runtime parent and child workers. + +IPC envelope fields: + +```text +id +direction +kind +timestamp +session_id +agent_id +correlation_id? +protocol_version +payload +``` + +Handshake: + +1. parent spawns worker process; +2. parent sends `agent.start` after spawn; +3. worker responds with `worker.ready` including `protocol_version`; +4. parent validates protocol version; +5. worker executes role loop; +6. worker returns `worker.result`, checkpoints, logs, events, and tool calls. + +Message categories: + +| Direction | Kinds | +|---|---| +| parent → worker | `control`, `tool.result`, `tool.stream` | +| worker → parent | `event`, `log`, `tool.call`, `worker.result`, `worker.checkpoint`, `protocol.error` | + +Stdout is NDJSON protocol only. Stderr is for fatal fallback/logging and must not carry protocol messages. + +Worker exit codes: + +| Code | Meaning | +|---:|---| +| 0 | success | +| 1 | task failed | +| 2 | worker crashed | +| 3 | protocol error | +| 4 | cancelled | +| 5 | permission/policy blocked | + +Workers never write SQLite directly and never perform side effects outside parent-mediated tools. + +## 12. Permission and Security Overview + +Permission evaluation order: + +1. tool capability declaration; +2. permission profile; +3. TaskSpec scope allowed/denied paths; +4. path/command/network risk classification; +5. credential/system-sensitive override; +6. user prompt workflow. + +Permission actions: + +```text +allow | deny | ask_user | block | refuse | announce_then_run +``` + +Grant scopes: + +```text +none | once | session | project | global +``` + +Path risk categories: + +```text +project_source +project_build_output +project_air_shared +project_air_local +project_git_internal +outside_project +credential_or_secret +system_sensitive +``` + +Command risk categories: + +```text +read_only +build +test +static_analysis +git_read +git_write +destructive +network +system_sensitive +credential_sensitive +``` + +Boundary rules: + +1. Path policy uses realpath normalization before allow/deny checks; symlink escapes are not allowed by string-prefix checks. +2. `.git/` internals are protected from arbitrary write tools; Git operations go through git tools. +3. Build output directories are lower risk than source but still remain scoped by TaskSpec and destructive-command analysis. +4. Runtime-owned writes inside `.air/local/` are internal service operations, but user-visible or destructive access still follows permission policy. +5. `sudo` does not automatically become high risk by string alone; command intent, target path, and system sensitivity determine risk, with safe prompts when uncertain. +6. Static high-risk command patterns are deny/ask by default, with LLM escape hatch only through explicit PermissionEngine reasoning and prompt flow. +7. Project-outside writes require backup where policy says `backup_required`, usually through `.air/local/backups/`. +8. Credentials and system-sensitive actions override broad session/project/global allows. +9. Project-level allow does not override TaskSpec scope. +10. Migration, destructive, shared-state, credential, and policy-sensitive operations require explicit user confirmation or block/refuse. + +Security invariants: + +- LLM output is untrusted until validated by runtime/tool schemas and PermissionEngine; +- provider output cannot directly modify files or run commands; +- credentials are referenced by `auth_ref` and not copied into events/artifacts; +- no automatic upload of source, logs, screenshots, bundles, pcaps, or artifacts; +- destructive/system-sensitive actions require confirmation or policy block. + +## 13. Context, Memory, and Compaction Overview + +Context assembly uses ordered PromptLayers L0-L9 (per `prompt-layering-v1.md`): + +| Layer | Name | +|---|---| +| L0 | Runtime invariant | +| L1 | Role / agent mode | +| L2 | Safety and permission policy | +| L3 | Project rules and user preferences | +| L4 | Architecture baseline and current plan | +| L5 | Task specification and acceptance criteria | +| L6 | Relevant code / artifacts / evidence | +| L7 | Recent conversation and decision context | +| L8 | Tool result history / diagnostics | +| L9 | Immediate instruction | + +Compaction rules: + +1. ContextAssembler may request compaction but does not compact itself. +2. Scheduler creates `compact` task. +3. Compactor snapshots immutable message range. +4. `summary.created` inserts the summaries row. +5. `context.compaction.completed` references the created summary. +6. Original messages are preserved for backtracking. + +ExperienceMiner triggers: + +- debug record created; +- session end; +- N-turn/tool-call interval (default 10); +- stale rule/skill discovered during execution. + +Scheduler owns trigger creation. ExperienceMiner never self-triggers. Curator dedup/archive runs as a scheduled `mine_experience` task. + +Experience lifecycle: + +```text +candidate.created + → evidence threshold check + → user/project policy approval + → promotion write through owning store + → memory.promoted or promotion failed + → rollback/archive if stale or harmful +``` + +## 14. UI/HUD and Provider Overview + +TUI is in-process with runtime for V1.0.0 Alpha. + +Rules: + +- TUI consumes only `ProjectionClient` and projection contracts; +- UI commands flow through a narrow UiCommandChannel; +- TUI never imports runtime private services; +- TUI never queries SQLite/EventBus directly; +- permission prompts, blockers, evidence, artifacts, and HUD are rendered from ProjectionSnapshot/evidence refs. + +OpenCode reuse boundary: + +- Reuse visual/component patterns: theme, dialog, modal, toast, keymap, layout, spinner, border, error, markdown, code, diff. +- Do not reuse SDK, sync, session, or business-state logic. + +V1.0.0 Alpha UI surfaces: + +- conversation; +- task/agent/tool/command progress; +- permission prompt UX with `announce_then_run` visualization; +- blocker reports; +- evidence display; +- HUD presets: Full / Essential / Minimal; +- read-only provider/model status display; +- CLI command catalog: `resume`, `compact`, `history`, `session list`, read-only `provider list/current`, `restore`. + +UI design evidence capability: + +- ASCII/wireframe layout sketches for terminal UI planning; +- SVG/textual diagram artifacts where useful; +- screenshot capture and analysis for GUI evidence; +- no automatic upload of screenshots or generated design artifacts. + +Provider capability matrix concepts: + +```text +provider_kind +quality_tier: frontier | strong | standard | cheap | local | unknown +cost_tier: high | medium | low | free | unknown +context_window_tokens +max_output_tokens +supports +conversion +``` + +Provider adapters expose `list_models()`, `validate_model()`, optional `count_tokens()`, and streaming `complete()`. Provider adapters convert external formats to/from AirCoding's Anthropic canonical internal format and must not silently drop semantic prompt/tool information. + +Model/provider rule: runtime provider/model selection is fixed for a running session and must not be changed through TUI shortcuts or CLI commands. Users may inspect current provider/model state, but switching requires starting a new session or editing config before startup. This is a design-stage decision accepted during overview review and should be captured in ADR/detailed design when provider UI is specified. + +## 15. Doctor, Restore, Recovery, and Operations Overview + +Doctor self-bootstrap: + +1. verify Bun runtime; +2. verify SQLite availability; +3. verify basic shell access; +4. verify `.air/` writability; +5. run platform/provider/toolchain/capability/display/network checks. + +Doctor modes: + +- read-only startup/manual check; +- fix mode under PermissionEngine; +- bundle export with local artifact, no automatic upload. + +Restore: + +- `air restore file `; +- `air restore time `; +- `air restore session `. + +Restore uses the git-backed backup repository under `.air/local/backups/` and preserves history with a restore commit. + +Recovery: + +- DB recovery rebuilds scheduler queues from tasks/agents/task_attempts/workspaces; +- lost worker detection emits durable `agent.lost`; +- orphan artifact scan registers or quarantines files; +- FK-off orphan scan logs and repairs/archive references; +- workspace GC preserves active/conflicted states and cleans merged/abandoned states by retention policy. + +Workspace GC policy: + +| Workspace status | Retention | +|---|---| +| active | preserve until merge or explicit cancel | +| merged | preserve 7 days after `merged_at`, then clean | +| conflicted | preserve until decision, then move to abandoned | +| abandoned | preserve 3 days, then clean | +| cleaned | filesystem artifacts removed; DB row retained | + +Logging: + +- `air.log` is user-facing and contains redacted operational errors and recovery summaries. +- `air.developer.log` is encrypted, more detailed, and retained according to policy. +- Logs must redact secrets, auth refs, provider keys, and credential-like values. +- Tool/command failures link log artifacts through evidence refs rather than copying sensitive content into user summaries. + +Migration: + +1. Detect `schema_meta.schema_version` on session/project DB open. +2. If migration is needed, build a migration plan and risk summary. +3. Create backup through `.air/local/backups/` before migration when required. +4. Ask user for destructive or non-trivial migration confirmation. +5. Apply migration transactionally when SQLite scope allows. +6. Emit migration evidence and recovery instructions. +7. On failure, restore or leave explicit repair state. + +Project scanner: + +- collects full directory tree metadata with no directory exclusion and no depth limit; +- does not recurse through symlinks by default; +- records permission errors as entries with error metadata; +- does not read file contents during tree scan; +- records special file types without opening them; +- provides progress and cancellation hooks; +- records cycle/mount anomalies as scanner warnings. + +Distribution: + +```text +binary tarball + bin/air + resources/ + LICENSE +``` + +Tier-1 Linux x86_64 is release-blocking. Linux arm64 and WSL2 are best-effort/tier-2 according to the cross-platform matrix. Windows-native deep support is not V1.0.0 Alpha release-blocking. + +## 16. Implementation Phase Mapping + +| Phase | System overview scope | +|---|---| +| Phase 0 | Monorepo skeleton + `packages/contracts` | +| Phase 1 | `.air` project/session storage, SQLite, EventStore, ArtifactStore | +| Phase 2 | ToolRegistry, PermissionEngine, built-in tools, CapabilityRegistry | +| Phase 3 | Provider layer, ContextAssembler, prompt resources | +| Phase 4 | Worker IPC, WorkerManager, Scheduler | +| Phase 5 | Complete C++ workflow | +| Phase 6 | ProjectionStore, TUI/HUD, UX surfaces | +| Phase 7 | Main Agent / Architecture Designer / worker role integration | +| Phase 8 | Release gates, Doctor bundle, packaging | + +Critical serialization: + +1. `packages/contracts` before implementation packages. +2. DB schema before storage/EventStore tests. +3. ToolRegistry + PermissionEngine before side-effect tools/workers. +4. Provider/context contracts before agent prompts. +5. IPC before real worker E2E. +6. Projection contracts before TUI implementation. + +ADR alignment checkpoints: + +- Monorepo/package boundaries align with the package and C4 decisions. +- IPC/worker process choices align with NDJSON child-process ADRs. +- Permission template and tool trust decisions align with security/capability ADRs. +- Doctor fix/bundle and restore behavior align with decisions-round-2/3. + +## 17. Validation Overview + +Minimum release-level validation: + +```bash +bun install +bun run typecheck +bun test +bun run lint +bun run air -- doctor --read-only +bun run air -- e2e worker-fixture +bun run air -- fixture cpp-build-test +bun run air -- e2e cpp-fix-fixture +bun run air -- e2e cpp-debug-review-fixture +bun run air -- capability validate --all +bun run release:check +``` + +Validation categories: + +| Category | Purpose | Examples | +|---|---|---| +| Unit | contract/schema/repository/tool logic | contracts, EventSchemaRegistry, PermissionEngine, path classifier | +| Integration fixture | deterministic local runtime flows | storage, EventStore, Scheduler graph, IPC fixture, C++ fixture | +| E2E real LLM | release-level agent behavior | simple edit, C++ debug/fix/review, architecture review gate | +| UI smoke | TUI/HUD responsiveness and projection rendering | tui startup, permission prompt, evidence view, HUD presets | +| Release gate | combined Linux tier-1 release readiness | `bun run release:check` | + +Additional Alpha UX gates: + +```bash +bun run air -- e2e direct-mode-fixture +bun test packages/runtime --filter restore +bun run air -- doctor --fix --dry-run +bun run air -- doctor --bundle +bun run air -- tui-smoke --project +``` + +Skipped gates must record: + +- why skipped; +- evidence available; +- risk; +- follow-up task. + +## 18. Open Items for Detailed Design + +The following are intentionally left for detailed design and class diagram freeze: + +1. exact TypeScript file/module layout per package; +2. final class method signatures beyond public contracts; +3. repository implementation classes and query helpers; +4. EventStore domain projection handler table; +5. WorkerProtocol implementation state machine; +6. CLI command parser structure; +7. TUI component tree and state subscriptions; +8. fixture definitions and test harness layout; +9. release package resource manifest; +10. concrete ProviderAdapter implementation sequence; +11. ADR numbering for design-stage provider/model immutability; +12. exact UI mockups for permission, blocker, evidence, and HUD surfaces. + +## 19. Readiness Decision + +The system overview design is complete enough to proceed to detailed design / class diagram freeze after this multi-model audit repair. + +Readiness basis: + +- P0/P1/P2 overview audit gaps that do not require user decisions are resolved in this document; +- architecture source precedence is stable and all 24 frozen baselines are listed; +- contracts/schema/runtime semantics/error taxonomy/security/capability/artifact models are aligned at overview level; +- system containers and runtime components have clear responsibilities and dependency rules; +- Main Agent, Scheduler, worker, IPC, tool, permission, event, context, and recovery flows have implementation-facing overview semantics; +- implementation phases and serialization points are identified; +- validation gates are explicit. diff --git a/AirPlan/docs/architecture/概要设计修复回归审查-R2.md b/AirPlan/docs/architecture/概要设计修复回归审查-R2.md new file mode 100644 index 0000000..91ff57b --- /dev/null +++ b/AirPlan/docs/architecture/概要设计修复回归审查-R2.md @@ -0,0 +1,195 @@ +# 概要设计修复回归审查（第二轮） + +Date: 2026-05-29 +Reviewer: Claude Opus 4.7 (second pass, clean session) +Status: Independent regression review of repaired `system-overview-design.md` +Scope: Verify P0/P1/P2 closure after four-model audit repair; detect new baseline conflicts + +--- + +## 1. 审查范围 + +审查对象： + +- `AirPlan/docs/architecture/system-overview-design.md`（1216 行修复后版本） + +审查参考： + +- `AirPlan/docs/architecture/gpt5概要设计审查.md` +- `AirPlan/docs/architecture/mimo2.5概要设计审查.md` +- `AirPlan/docs/architecture/Opus4.7概要设计审查.md` +- `AirPlan/docs/architecture/DeepSeek概要设计审查.md` +- `AirPlan/docs/architecture/概要设计修复回归审查.md`（第一轮回归） + +方法： + +- 独立逐项核对，不信任第一轮回归报告的逐行结论 +- 在文档原文中用 grep 确认每项 P0/P1/P2 的覆盖位置 +- 检查边缘一致性和潜在新冲突 +- 给出独立的门禁判定 + +--- + +## 2. 总体结论 + +**通过。** + +修复后的 `system-overview-design.md` 覆盖了四模型审查的全部 P0 和 P1 缺口，非决策 P2 对齐项已吸收，剩余仅为详细设计自然展开项。 + +未发现新的冻结基线冲突。 + +相比第一轮回归，本次发现了 1 个 P2 级别的小差异（PromptLayer "immediate instruction" 与 baseline `prompt-layering-v1.md` 的 "L9 Immediate instruction" 描述的措辞不完全一致，但不影响语义），不需要阻塞详细设计。 + +--- + +## 3. P0 独立回归核对 + +| P0 ID | 原缺口 | 验证方式 | 结果 | +|---|---|---|---| +| P0-01 | 源文档清单 11/24 | §1 列出 24 份冻结源文档 | **关闭** | +| P0-02 | 产品定位 missing "not wrapper" | §2: "is not a Claude Code plugin, wrapper, or thin shell" | **关闭** | +| P0-02b | Canonical V1 loop missing | §2: 12-step canonical V1 coding loop | **关闭** | +| P0-03 | Global `~/.air/` + `project_id` | §8.1: `~/.air/` full tree + `project_id` UUID description | **关闭** | +| P0-04 | Claude Code execution discipline | §10.9: 7 rules (read-before-edit, exact edit, scope, verification, evidence, block semantics) | **关闭** | +| P0-05 | Permission boundary rules incomplete | §12: 8 PathRisk categories + 10 CommandRisk categories + 10 boundary rules | **关闭** | +| P0-06 | IPC envelope + exit codes | §11: envelope fields, stdout/stderr protocol, exit codes 0-5 | **关闭** | +| P0-07 | TaskSpec/WorkerResult fields + failed/blocked | §10.10: field families + status semantics table | **关闭** | +| P0-08 | Error taxonomy missing | §9.2: AirError fields, 22 ErrorKinds, severity, retryability, semantic_signature, Scheduler routing | **关闭** | +| P0-09 | RuntimeEvent route/version/route_text | §9.1: 7 rules including append-only route, route_text derivation, version increment | **关闭** | +| P0-10 | SQLite message invariants | §8.2: rules 6-8 (canonical_format, message_drafts lifecycle, V1 non-message_parts), rule 9 (closed enums) | **关闭** | + +P0 结果：**10/10 关闭**。 + +--- + +## 4. P1 独立回归核对 + +| P1 ID | 原缺口 | 验证位置 | 结果 | +|---|---|---|---| +| P1-01 | 参考项目影响和复用边界 | §2: Reference influences table (6 projects) | 关闭 | +| P1-02 | 技术栈约束 | §2: Technology baseline (7 items) | 关闭 | +| P1-03 | Scheduler 状态机 | §10.3: Scheduler states + ownership list | 关闭 | +| P1-04 | Main Agent 状态机 | §10.2: Main Agent lifecycle diagram + state rules | 关闭 | +| P1-05 | ScopeImpactLevel 7 级 | §10.7: 7 levels listed | 关闭 | +| P1-06 | FK-off 8 条不变量 | §8.2: 8 invariants listed | 关闭 | +| P1-07 | 日志架构 | §15: `air.log`, `air.developer.log`, redaction, retention | 关闭 | +| P1-08 | 迁移架构 | §15: 7-step migration process | 关闭 | +| P1-09 | 扫描器语义 | §15: 7 scanner rules | 关闭 | +| P1-10 | 分发章节 | §15: binary tarball + tier list | 关闭 | +| P1-11 | 测试分层 | §17: 5 validation categories (Unit/Integration/E2E/UI smoke/Release gate) | 关闭 | +| P1-12 | contracts 文件清单 | §4: 18-item file list | 关闭 | +| P1-13 | C++ Ninja/Make/clangd | §10.8: CMake+Ninja preferred, Make fallback, compile_commands, clangd CLI mode, zero-config target | 关闭 | +| P1-14 | Provider 能力矩阵 | §14: quality_tier, cost_tier, context_window, supports, conversion, adapter functions | 关闭 | +| P1-15 | Capability Trust lifecycle | §6: discovered→active lifecycle + 5 trust levels | 关闭 | +| P1-16 | Artifact URI/ID/filename | §8.4: `artifact://` URI, `art_`, timestamp-slug naming | 关闭 | +| P1-17 | C4 模块依赖图 | §4: C4 canonical dependency direction text model | 关闭 | +| P1-18 | Solution Architecture 四决策 | §2: 4-item "Core architecture decisions" list with solution-architecture.md credit | 关闭 | + +P1 结果：**18/18 关闭**。 + +--- + +## 5. P2 独立回归核对 + +| P2 项目 | 验证位置 | 结果 | +|---|---|---| +| OpenCode UI reuse/do-not-reuse | §14: explicit reuse list + "Do not reuse SDK, sync, session, or business-state logic" | 关闭 | +| UI design evidence capability | §14: ASCII/wireframe, SVG, screenshot capture | 关闭 | +| Workspace GC retention | §15: Retain 7d merged, 3d abandoned, preserve active/conflicted | 关闭 | +| Cross-DB outbox 5-step | §8.3: 1-5 numbered outbox/compensation order | 关闭 | +| ExperienceMiner 触发所有权 | §13: "Scheduler owns trigger creation. ExperienceMiner never self-triggers." | 关闭 | +| PromptLayer L0-L9 | §13: 10-row table L0-L9, L2 safety and permission policy present | 关闭 | +| EventBus handler error | §9.1 rule 7: errors caught, logged, not propagated, subscription stays active | 关闭 | +| command_runs status derivation | §8.2: 5-row derived status table | 关闭 | +| Provider immutability ADR | §14: traced to "design-stage decision" + §18: open item for ADR numbering | 关闭（概要级） | +| ADR alignment checkpoints | §16: 4 bullet alignment checkpoints | 关闭 | +| DB closed enum inventory | §8.2 rule 9: "Closed enum values are controlled by db-schema-v1.md" | 关闭 | +| session.db physical path | §8.2: `.air/local/sessions//session.db` | 关闭 | +| zero-config C++ workflow | §2: "zero-config-oriented C++" + §10.8: "zero-config C++ onboarding" | 关闭 | + +P2 结果：**不需要用户决策的对齐项全部关闭；剩余为详细设计自然展开项**。 + +--- + +## 6. 边缘一致性与新冲突检查 + +### 6.1 独立的边缘一致性检查 + +以下项目经独立核对后给出结论： + +**PromptLayer 与基线不一致**（已修复）： + +- 发现时状态：概要设计 §13 的 L3-L9 命名与 `prompt-layering-v1.md` §2 存在多处差异： + - L3 缺少 "and user preferences" + - L4/L5 顺序与基线相反（概览将 task spec 放在 architecture 之前） + - L8 写为 "user override"（基线为 "Tool result history / diagnostics"，概览的 "user override" 在基线中不存在） + - L9 被扩写为 "immediate instruction / system debug when applicable"（基线仅为 "Immediate instruction"） +- 结论：四份审查和两轮回归均将此差异低估为 P2 措辞问题，实际上 L3-L9 共有 6 处不对齐。本次已按基线原文完整修正。 +- 修复：概要设计 §13 PromptLayer 表已逐层对齐至 `prompt-layering-v1.md` §2 原文。 + +**Provider immutability 溯源**： + +- 概要设计 §14: "This is a design-stage decision accepted during overview review" +- 基线检查：`baselineV1.md` §17 未定义 provider runtime immutability；`interface-contracts-v1.md` 的 ProviderManager 未强制 session lifetime 绑定。 +- 结论：这个约束属于设计阶段新增决策，概要设计已显式标注来源，未伪装为基线原文。详细设计需要为这条设计决策分配 ADR 编号。 + +**Worker exit codes 与基线的对应**： + +- 概要设计 §11: 6 exit codes (0-5) +- `baselineV1.md` §8: 6 exit codes (0-5) +- `interface-contracts-v1.md` §10: IPC direction, envelope, protocol, but exit codes are in baseline not contracts +- 结论：exit codes 与基线完全一致，无误。 + +### 6.2 新冲突检查表 + +| 检查项 | 结论 | +|---|---| +| 冻结基线是否被修改？ | 否。本轮只修改了 system-overview-design.md、plan.md、todo.md、AGENTS.md | +| 是否引入与 frozen baselines 矛盾的说法？ | 未发现 | +| Provider immutability 是否伪装为基线原文？ | 否。显式标注 "design-stage decision" | +| TUI 边界是否被弱化？ | 否。"TUI never imports runtime private services" 和 "never queries SQLite/EventBus directly" 均保留 | +| Worker 边界是否被弱化？ | 否。"Workers never write SQLite directly and never perform side effects outside parent-mediated tools" 保留 | +| EventBus 是否被提升为恢复源？ | 否。"EventBus is never recovery source of truth" 保留 | +| Permission credential override 是否被绕过？ | 否。规则 8 保留 "Credentials and system-sensitive actions override broad session/project/global allows" | +| Runtime → TUI 依赖是否被引入？ | 否。`runtime → TUI import` 仍在 forbidden paths 中 | +| Solution-architecture 四决策是否被重定义？ | 否。逐条引用并标注来源 | + +--- + +## 7. 与第一轮回归的比较 + +| 维度 | 第一轮回归 | 第二轮回归（本次） | +|---|---|---| +| P0 关闭率 | 10/10 | 10/10 | +| P1 关闭率 | 18/18 | 18/18 | +| P2 处理率 | 全部 | 全部 | +| 新冲突 | 0 | 0 | +| 新发现 | 0 | 1（PromptLayer L9 措辞 P2 差异） | + +两轮回归一致，结论高度收敛。 + +--- + +## 8. 门禁判定 + +| 门禁 | 第一轮 | 第二轮 | +|---|---|---| +| P0 全部关闭 | PASS | **PASS** | +| P1 全部覆盖 | PASS | **PASS** | +| 非决策 P2 处理 | PASS | **PASS** | +| 新基线冲突 | PASS | **PASS** | +| 可进入详细设计 | PASS | **PASS** | + +**第二轮独立回归通过**。 + +--- + +## 9. 进入详细设计的条件 + +详细设计可以开始。约束： + +1. `packages/contracts` 第一冻结，从 `interface-contracts-v1.md` 和 `system-overview-design.md §4` 转写。 +2. Provider/model runtime immutability 在详细设计阶段补 ADR 或决策记录。 +3. Architecture Designer gate、Scheduler state machine、PermissionEngine、EventStore、IPC、TaskSpec/WorkerResult 优先展开为类/模块设计。 +4. PromptLayer L9 措辞在详细设计或 prompt 资源实现时与 baseline 对齐到完全一致。 +5. 不再修改冻结基线。 diff --git a/AirPlan/docs/architecture/概要设计修复回归审查-R3.md b/AirPlan/docs/architecture/概要设计修复回归审查-R3.md new file mode 100644 index 0000000..9aa1f5c --- /dev/null +++ b/AirPlan/docs/architecture/概要设计修复回归审查-R3.md @@ -0,0 +1,158 @@ +# 概要设计修复回归审查（第三轮） + +Date: 2026-05-29 +Reviewer: Independent third pass, clean session +Status: Regression review after PromptLayer baseline alignment fix +Scope: Verify continued closure of all P0/P1 and the PromptLayer rewrite is conflict-free + +--- + +## 1. 触发原因 + +第二轮回归（R2）报告了 1 项 P2 措辞差异（PromptLayer L9），但用户对齐时发现实际差异覆盖 L3-L9 共 6 处。修复后 §13 已按 `prompt-layering-v1.md` §2 完整对齐。本轮回归独立核对： + +1. PromptLayer 修复是否真正闭环？ +2. 修复是否引入与基线其它章节的新冲突？ +3. 之前两轮回归对 P0/P1/P2 的关闭结论是否仍然成立？ +4. 是否还有第三处隐藏的措辞/语义漂移？ + +--- + +## 2. 总体结论 + +**通过。** + +- PromptLayer L0-L9 与基线 §2 措辞和顺序完全一致。 +- 未发现新的基线冲突。 +- 前两轮的 P0/P1/P2 关闭结论保持成立。 +- 经独立交叉核对，未发现新的隐藏漂移。 +- 概要设计仍处于可进入详细设计的就绪状态。 + +--- + +## 3. PromptLayer 闭环验证 + +逐层比对修复后 `system-overview-design.md` §13 与基线 `prompt-layering-v1.md` §2： + +| 层 | 基线 §2 | 概要 §13 (修复后) | 匹配 | +|---|---|---|---| +| L0 | Runtime invariant | Runtime invariant | ✓ | +| L1 | Role / agent mode | Role / agent mode | ✓ | +| L2 | Safety and permission policy | Safety and permission policy | ✓ | +| L3 | Project rules and user preferences | Project rules and user preferences | ✓ | +| L4 | Architecture baseline and current plan | Architecture baseline and current plan | ✓ | +| L5 | Task specification and acceptance criteria | Task specification and acceptance criteria | ✓ | +| L6 | Relevant code/artifacts/evidence | Relevant code / artifacts / evidence | ✓ | +| L7 | Recent conversation and decision context | Recent conversation and decision context | ✓ | +| L8 | Tool result history / diagnostics | Tool result history / diagnostics | ✓ | +| L9 | Immediate instruction | Immediate instruction | ✓ | + +10/10 完全对齐。修复闭环成立。 + +附加说明：基线在 L0 单独标注 `Mutable: no, except by AirCoding release.`。这是详细设计可承载的层级元数据，概要设计未必逐项列出可变性属性。语义未丢失。 + +--- + +## 4. P0/P1/P2 关闭状态复核 + +按 R1、R2 的关闭清单逐项快速复核，确认本次 PromptLayer 修复未误伤其它已关闭项。 + +| 类别 | R1 关闭 | R2 关闭 | R3 复核 | +|---|---|---|---| +| P0 (10 项) | 10/10 | 10/10 | **10/10 保持** | +| P1 (18 项) | 18/18 | 18/18 | **18/18 保持** | +| P2 (非决策对齐项) | 全部 | 全部 | **全部保持** | + +无回归。 + +--- + +## 5. 跨基线一致性独立抽查 + +本轮在 PromptLayer 之外独立抽查 7 处可能漂移点： + +### 5.1 AgentType 枚举 + +- 基线 `interface-contracts-v1.md` §5: `"executor" | "reviewer" | "debugger" | "compactor" | "experience_miner"`（5 项） +- 概要 §4/§7: Executor / Reviewer / Debugger / Compactor / ExperienceMiner（5 项） +- 结论：一致 + +### 5.2 Worker exit codes + +- 基线 `baselineV1.md` §8: 6 项（0-5） +- 概要 §11: 6 项（0-5） +- 结论：一致 + +### 5.3 Forbidden paths + +- 基线 `interface-contracts-v1.md` §23: 10 项 +- 概要 §5: 11 项 +- 差异：概要新增 `runtime → TUI import` +- 评估：这是 C4 module 依赖方向 `tui ← cli`、`runtime → contracts only` 的显式强化，并非新约束反向。属于细化，不构成冲突。 +- 结论：一致 + +### 5.4 ErrorKind 数量 + +- 基线 `interface-contracts-v1.md` §3: 22 种 +- 概要 §9.2: 22 种 +- 结论：一致 + +### 5.5 PathRisk 与 CommandRisk 分类 + +- 基线 `security-model-v1.md` §4-§5: 8 种 PathRisk + 10 种 CommandRisk +- 概要 §12: 8 种 + 10 种 +- 结论：一致 + +### 5.6 Permission action 枚举 + +- 基线: `allow | deny | ask_user | block | refuse | announce_then_run` +- 概要 §12: 同上 +- 结论：一致 + +### 5.7 ScopeImpactLevel + +- 基线 `scope-escalation-v1.md` §2: 7 种 +- 概要 §10.7: 7 种（implementation/interface/architecture/product/permission/environment/policy） +- 结论：一致 + +--- + +## 6. 三轮回归对比 + +| 维度 | R1 | R2 | R3 | +|---|---|---|---| +| P0 关闭 | 10/10 | 10/10 | 10/10 | +| P1 关闭 | 18/18 | 18/18 | 18/18 | +| P2 非决策项 | 全部 | 全部 | 全部 | +| 新发现 | 0 | 1（PromptLayer L9） | 0 | +| 新引入冲突 | 0 | 0 | 0 | +| 修复后是否新增漂移 | — | — | 否 | + +R2 发现的 1 项已在 R2→R3 之间修复并经 R3 独立验证闭环。R3 未发现新增问题。 + +--- + +## 7. 门禁判定 + +| 门禁 | R3 状态 | +|---|---| +| P0 全部关闭 | PASS | +| P1 全部覆盖 | PASS | +| 非决策 P2 处理 | PASS | +| PromptLayer 与基线对齐 | PASS | +| 跨基线抽查无冲突 | PASS | +| 可进入详细设计 | **PASS** | + +最终结论：**第三轮回归通过。** 概要设计可进入详细设计 / 类图冻结 / `packages/contracts` 转写。 + +--- + +## 8. 后续建议 + +为避免再次出现 PromptLayer 这类多层措辞漂移，详细设计阶段建议： + +1. 详细设计文档凡引用基线枚举/层名，应直接复制基线原文措辞，而非概述。 +2. 类图冻结阶段对每个枚举类型做最后一次"概览—基线—contracts 包"三方比对。 +3. 增加一项详细设计释义机制：当详细设计需要扩写概要描述时，在脚注或附录中标注与基线原文的对齐方式。 + +这些是流程建议，不阻塞进入详细设计。 diff --git a/AirPlan/docs/architecture/概要设计修复回归审查.md b/AirPlan/docs/architecture/概要设计修复回归审查.md new file mode 100644 index 0000000..27ad5c8 --- /dev/null +++ b/AirPlan/docs/architecture/概要设计修复回归审查.md @@ -0,0 +1,155 @@ +# 概要设计修复回归审查 + +Date: 2026-05-29 +Status: Regression review after applying P0/P1/P2 overview audit repairs +Scope: Verify repaired `system-overview-design.md` against the four overview audit reports; no frozen baseline edits + +--- + +## 1. 回归范围 + +审查对象： + +- `AirPlan/docs/architecture/system-overview-design.md` + +回归输入： + +- `AirPlan/docs/architecture/gpt5概要设计审查.md` +- `AirPlan/docs/architecture/mimo2.5概要设计审查.md` +- `AirPlan/docs/architecture/Opus4.7概要设计审查.md` +- `AirPlan/docs/architecture/DeepSeek概要设计审查.md` + +回归问题： + +1. 原 10 个 P0 是否全部关闭？ +2. 原 P1 是否已覆盖或明确转入详细设计？ +3. 原 P2 中无需用户决策的对齐项是否已覆盖？ +4. 是否引入新的明显基线冲突？ + +--- + +## 2. 总体结论 + +`system-overview-design.md` 已完成四模型审查后的修复回归。 + +结论：**可以进入详细设计 / 类图冻结。** + +原因： + +- 原 10 项 P0 全部关闭。 +- 原 P1 全部在概要设计中获得覆盖。 +- 原 P2 中不需要用户决策的对齐项已吸收；剩余仅为详细设计自然展开项。 +- 未发现新的冻结基线冲突。 +- 修复范围限定在概要设计和当前阶段索引/计划文档，没有修改冻结基线。 + +--- + +## 3. P0 回归表 + +| ID | 原缺口 | 修复位置 | 回归结论 | +|---|---|---|---| +| P0-01 | 源文档清单仅 11/24 | §1 Frozen source documents | **关闭**：24 份冻结基线全部列出 | +| P0-02 | 产品定位缺少 not wrapper + canonical loop | §2 System Goal | **关闭**：明确不是 Claude Code plugin/wrapper，并列出 V1 canonical loop | +| P0-03 | Global `~/.air/` layout + `project_id` UUID | §8.1 Filesystem layout | **关闭**：global/project-local layout、project_id UUID、`.air/local` gitignore 均覆盖 | +| P0-04 | Claude Code 执行原语系统约束 | §10.9 Claude Code execution discipline | **关闭**：read-before-edit、exact edit、scope、verification、evidence、block semantics 均覆盖 | +| P0-05 | 权限边界细则 | §12 Permission and Security Overview | **关闭**：PathRisk、CommandRisk、10 条边界规则覆盖 | +| P0-06 | IPC envelope + exit codes | §11 IPC and Worker Overview | **关闭**：envelope 字段、stdout/stderr、exit code 0-5 覆盖 | +| P0-07 | TaskSpec/WorkerResult 字段族 + failed/blocked | §10.10 TaskSpec and WorkerResult overview | **关闭**：字段族、status 语义、summary 规则覆盖 | +| P0-08 | 错误分类学缺失 | §9.2 Error taxonomy | **关闭**：AirError、ErrorKind、severity、retryability、semantic_signature 覆盖 | +| P0-09 | RuntimeEvent route/version/route_text | §9.1 Event flow | **关闭**：append-only、route_text、version increment、EventStore persistence policy 覆盖 | +| P0-10 | SQLite message storage invariants | §8.2 Session DB | **关闭**：canonical_format、message_drafts、no message_parts source-of-truth 覆盖 | + +P0 结果：**10/10 关闭**。 + +--- + +## 4. P1 回归表 + +| ID | 原缺口 | 修复位置 | 回归结论 | +|---|---|---|---| +| P1-01 | 参考项目影响和复用边界 | §2 Reference influences and reuse boundaries | 关闭 | +| P1-02 | 技术栈约束条目 | §2 Technology baseline | 关闭 | +| P1-03 | Scheduler 状态机 | §10.3 Scheduler state machine | 关闭 | +| P1-04 | Main Agent 状态机 | §10.2 Main Agent state machine | 关闭 | +| P1-05 | ScopeImpactLevel 7 级分类 | §10.7 Review and architecture gate | 关闭 | +| P1-06 | FK-off 8 条不变量 | §8.2 Session DB | 关闭 | +| P1-07 | 日志架构 | §15 Logging | 关闭 | +| P1-08 | 迁移架构 | §15 Migration | 关闭 | +| P1-09 | 扫描器语义 | §15 Project scanner | 关闭 | +| P1-10 | 分发章节 | §15 Distribution | 关闭 | +| P1-11 | 测试分层 | §17 Validation Overview | 关闭 | +| P1-12 | contracts 包文件清单 | §4 Container Overview | 关闭 | +| P1-13 | C++ Ninja/Make/clangd 细节 | §10.8 C++ workflow | 关闭 | +| P1-14 | Provider 能力矩阵摘要 | §14 UI/HUD and Provider Overview | 关闭 | +| P1-15 | Capability Trust 生命周期和 trust level | §6 Runtime Component Overview | 关闭 | +| P1-16 | Artifact URI/ID/filename 规范 | §8.4 Artifact and evidence naming | 关闭 | +| P1-17 | C4 module 依赖图 | §4 Container Overview | 关闭 | +| P1-18 | Solution Architecture 四个核心决策 | §2 System Goal | 关闭 | + +P1 结果：**全部关闭**。 + +注：P1 编号合并了 Opus/DeepSeek 两份报告的分类差异；DeepSeek 将 C4 依赖图和 solution decisions 追加为 P1，已覆盖。 + +--- + +## 5. P2 回归表 + +| 原缺口 | 修复位置 | 回归结论 | +|---|---|---| +| OpenCode UI reuse/do-not-reuse | §14 OpenCode reuse boundary | 关闭 | +| UI design evidence capability | §14 UI design evidence capability | 关闭 | +| Workspace GC 具体保留天数 | §15 Workspace GC policy | 关闭 | +| Cross-DB outbox 5 步流程 | §8.3 Project-level DBs | 关闭 | +| ExperienceMiner 触发所有权 | §13 ExperienceMiner triggers | 关闭 | +| PromptLayer L0-L9 一致性 | §13 PromptLayers L0-L9 | 关闭 | +| EventBus handler 异常处理 | §9.1 Event flow | 关闭 | +| command_runs 状态派生 | §8.2 Session DB | 关闭 | +| Provider runtime immutability ADR 溯源 | §14 + §18 Open Items | 关闭：已标注为设计阶段决策，ADR 编号留详细设计 | +| ADR 关键决策交叉引用 | §16 ADR alignment checkpoints | 关闭到概要级；具体编号留详细设计 | +| DB 关闭枚举清单引用 | §8.2 Session DB | 关闭 | +| session.db 物理路径/共享拓扑 | §8.1-§8.3 | 关闭 | +| zero-config C++ workflow | §2 + §10.8 | 关闭 | + +P2 结果：**不需要用户决策的对齐项已关闭；剩余为详细设计自然展开项**。 + +--- + +## 6. 新冲突检查 + +未发现新的明显基线冲突。 + +重点检查结果： + +1. **冻结基线未修改**：本次修复只改概要设计、计划/任务索引和新增审查报告。 +2. **Provider/model runtime immutability**：概要设计标注为设计阶段决策，并在 §18 留 ADR 编号给详细设计，未伪装为冻结基线原文。 +3. **TUI 边界**：继续保持 TUI 只依赖 ProjectionClient/contracts，不直接访问 runtime internals/SQLite/EventBus。 +4. **Runtime/EventStore 边界**：保留 EventIngestor 入口、EventStore transaction、EventBus 非恢复源的语义。 +5. **PermissionEngine 边界**：新增细则没有绕过 credential/system-sensitive override。 +6. **Worker 边界**：仍禁止 worker 直接写 SQLite 或绕过 parent-mediated tools。 +7. **Doctor/restore**：保持已覆盖的 Doctor self-bootstrap 和 restore 三粒度，没有引入与 runtime-semantics 冲突的语义。 + +--- + +## 7. 进入详细设计建议 + +建议进入详细设计，但详细设计开头应继承以下约束： + +1. 不再修改冻结需求/基线，除非用户明确重新开基线变更流程。 +2. `packages/contracts` 是第一冻结对象，优先从 `interface-contracts-v1.md` 和修复后的 `system-overview-design.md` 转写。 +3. 详细设计需要给出具体类/模块/文件布局，而不是再次重复概要设计。 +4. Provider/model runtime immutability 需要补 ADR 编号或详细设计决策记录。 +5. Architecture Designer gate、Scheduler state machine、PermissionEngine、EventStore、IPC、TaskSpec/WorkerResult 应作为详细设计优先展开对象。 + +--- + +## 8. 回归门禁判定 + +| 门禁 | 状态 | +|---|---| +| P0 全部关闭 | PASS | +| P1 全部覆盖 | PASS | +| 非决策 P2 对齐项处理 | PASS | +| 新基线冲突 | PASS | +| 可进入详细设计 | **PASS** | + +最终结论：**概要设计修复回归通过。** diff --git a/AirPlan/plan.md b/AirPlan/plan.md index a5c5bd3..9bcc717 100755 --- a/AirPlan/plan.md +++ b/AirPlan/plan.md @@ -8,11 +8,17 @@ Status: Formal architecture-to-V1.0.0 Alpha plan 1. `AirPlan/AGENTS.md` 2. `AirPlan/docs/analysis/requirements.md` 3. `AirPlan/docs/architecture/solution-architecture.md` -4. `AirPlan/docs/architecture/c4/module.md` -5. `AirPlan/docs/architecture/baselineV1.md` -6. `AirPlan/docs/architecture/多模型三视角审查联合评估.md` -7. `AirPlan/docs/architecture/adr/` -8. `AirPlan/todo.md` +4. `AirPlan/docs/architecture/system-overview-design.md` +5. `AirPlan/docs/architecture/c4/module.md` +6. `AirPlan/docs/architecture/baselineV1.md` +7. `AirPlan/docs/architecture/多模型三视角审查联合评估.md` +8. `AirPlan/docs/architecture/gpt5概要设计审查.md` +9. `AirPlan/docs/architecture/mimo2.5概要设计审查.md` +10. `AirPlan/docs/architecture/Opus4.7概要设计审查.md` +11. `AirPlan/docs/architecture/DeepSeek概要设计审查.md` +12. `AirPlan/docs/architecture/概要设计修复回归审查.md` +13. `AirPlan/docs/architecture/adr/` +14. `AirPlan/todo.md` ## Goal @@ -26,6 +32,7 @@ Implementation must follow these canonical V1 documents: |---|---| | Requirements | `AirPlan/docs/analysis/requirements.md` | | Solution architecture | `AirPlan/docs/architecture/solution-architecture.md` | +| System overview design | `AirPlan/docs/architecture/system-overview-design.md` | | C4/module view | `AirPlan/docs/architecture/c4/module.md` | | Baseline | `AirPlan/docs/architecture/baselineV1.md` | | DB schema | `AirPlan/docs/architecture/db-schema-v1.md` | @@ -51,7 +58,7 @@ The P0/P1/P2 remediation and UX scope gate from `AirPlan/docs/architecture/多 3. persistence/runtime invariant repair — DONE (T-000C) 4. UX scope decision — DONE (T-000D): all features scheduled as Alpha; VibeBox removed from main plan -System overview design and detailed design may proceed. `packages/contracts` implementation may proceed after overview design is consistent. +System overview design has been repaired after the GPT-5, MIMO 2.5, Opus 4.7, and DeepSeek overview audits. All P0/P1 and non-decision alignment gaps were folded into `system-overview-design.md`; `概要设计修复回归审查.md` passed the overview regression gate. Detailed design and `packages/contracts` implementation may proceed. ## Constraints diff --git a/AirPlan/todo.md b/AirPlan/todo.md index 783da20..92bc08a 100755 --- a/AirPlan/todo.md +++ b/AirPlan/todo.md @@ -8,6 +8,7 @@ Status values: TODO / DOING / DONE / BLOCKED | T-000B | DONE | Contracts Gate | Repair public contract freeze issues | `AirPlan/docs/architecture/interface-contracts-v1.md`, `event-registry-v1.md`, `error-taxonomy-v1.md`, `provider-capability-matrix-v1.md`, `tool-registry-v1.md`, `c4/code-view.md` | P0 contract conflicts resolved: `AirError.cause_ref`/`cause_refs`, `EntityRef` single-source, `permission_template` naming, `TaskInsert`/`EventInsert`, `TaskType/docs`, `Diagnostic`, `DebugKnowledgeStore`/`LearnedMemoryStore`, `PromptLayer`/`CompactionPolicy`, `ProviderAdapter` snake_case, `WaveID`, IPC handshake/direction, `EventSchemaRegistry`, `StreamingToolExecutor`, `PermissionRecordResult` | All contract edits verified | Contracts can be transcribed to `packages/contracts` without conflicts | C4 interface inventory updated implicitly via contract changes | | T-000C | DONE | Runtime Gate | Define persistence and runtime invariants | `AirPlan/docs/architecture/db-schema-v1.md`, `runtime-semantics-v1.md`, `event-registry-v1.md`, `interface-contracts-v1.md` | `debug-records.db` and `learned-memory.db` DDL added; FK-off invariants defined; EventBus handler error behavior defined; PermissionEngine record failure path defined; DB closed enum inventory added; workspace GC policy defined; direct mode, ExperienceMiner triggers, Doctor self-bootstrap, air restore semantics defined | All runtime/runtime-semantics and db-schema edits verified | Storage/runtime docs cover invariants needed by EventStore, repositories, recovery, and permission audit | runtime-semantics sections 14-19 added; db-schema sections 20-21 added | | T-000D | DONE | UX Scope Gate | Alpha UX scope decided | `AirPlan/plan.md`, `AirPlan/todo.md`, `AirPlan/docs/analysis/requirements.md`, `AirPlan/docs/architecture/main-agent-state-machine.md` | All UX features scheduled as Alpha tasks; VibeBox removed from main plan (separate project branch) | Requirements-to-todo trace check | No original UX requirement silently unscheduled | T-038 through T-045 created; VibeBox references removed from plan/todo | +| T-000E | DONE | Overview Gate | Repair system overview after four-model audit | `AirPlan/docs/architecture/system-overview-design.md`, `AirPlan/docs/architecture/{gpt5概要设计审查.md,mimo2.5概要设计审查.md,Opus4.7概要设计审查.md,DeepSeek概要设计审查.md,概要设计修复回归审查.md}`, `AirPlan/plan.md`, `AirPlan/AGENTS.md` | All P0/P1 and non-decision P2 overview audit gaps are folded into the overview; all 24 frozen baselines are listed; error taxonomy, global `~/.air`, IPC, TaskSpec/WorkerResult, PermissionEngine, RuntimeEvent, SQLite message invariants, state machines, capability trust, artifact naming, logging/migration/scanner/distribution/test strata are covered | Four-review consensus applied; regression review passed | No remaining overview blocker before detailed design | `system-overview-design.md` repaired; regression report, plan, and AGENTS synchronized | | T-001 | TODO | Monorepo | Create Bun workspace and Turborepo skeleton | `package.json`, `turbo.json`, `packages/` | Workspace installs and scripts resolve | `bun install && bun run typecheck` | TypeScript config validates package graph | ADR-0002, C4 package dependency view | | T-002 | TODO | Contracts | Implement shared contract package | `packages/contracts/src/` | RuntimeEvent, TaskSpec, WorkerResult, ToolDefinition, ArtifactRef, EvidenceRef, provider, error, IPC, UI types compile | `bun test packages/contracts && bun run typecheck` | Type-only package has no implementation deps | C4 interface inventory | | T-003 | TODO | CLI | Implement CLI bootstrap shell | `packages/cli/src/` | CLI can start, print version/help, locate project root, load resources | `bun run air -- --help` | Typecheck CLI package | C4 container view | @@ -37,17 +38,17 @@ Status values: TODO / DOING / DONE / BLOCKED | T-027 | TODO | TUI | Implement OpenTUI/Solid startup and core views | `packages/tui/src/` | TUI starts and shows session/task/agent/tool projections | `bun run air -- tui-smoke --project ` | Typecheck TUI package | C4 TUI container | | T-028 | TODO | TUI | Implement permission/blocker/report UI surfaces | `packages/tui/src/` | Permission prompts and blocker reports render from ProjectionStore | `bun test packages/tui` | Typecheck UI contracts | scope escalation/security model | | T-029 | TODO | Agents | Implement Main Agent request classification shell | `packages/runtime/src/agents/main/` | Main Agent stores messages, classifies direct vs delegated work, and reports progress | `bun test packages/runtime --filter main-agent` | Prompt schema checks | solution architecture | -| T-030 | TODO | Agents | Implement Architecture Designer impact flow | `packages/runtime/src/agents/architecture/` | Requirement/interface changes produce architecture impact events and doc update tasks | `bun test packages/runtime --filter architecture-agent` | Structured output validation | scope escalation ADRs | +| T-030 | TODO | Agents | Implement Architecture Designer impact and review gate flow | `packages/runtime/src/agents/architecture/` | Requirement/interface changes produce architecture impact events and doc update tasks; architecture-sensitive reviews, phase-complete reviews, and final consistency reviews produce Architecture Designer gate results | `bun test packages/runtime --filter architecture-agent` | Structured output validation | scope escalation ADRs, system overview §10.5 | | T-031 | TODO | Agents | Implement Executor/Reviewer/Debugger minimal loops | `packages/runtime/src/workers/roles/` | Simple edit fixture can execute, review, debug failure, and return evidence | `bun run air -- e2e simple-edit-fixture` | WorkerResult schema checks | ADR-0006 | | T-032 | TODO | Compaction | Implement Compactor summary flow | `packages/runtime/src/workers/roles/compactor.ts` | Context budget pressure creates summary row/artifact and preserves backtracking refs | `bun test packages/runtime --filter compaction` | Summary schema validation | prompt layering/context baseline | | T-033 | TODO | Experience | Implement ExperienceMiner candidate flow with Nudge, Curator, and self-patch | `packages/runtime/src/workers/roles/experience-miner.ts`, `packages/runtime/src/workers/roles/curator.ts` | Verified pattern creates memory/rule candidate; N-turn Nudge trigger fires periodically; Curator dedup/archive runs; self-patch forwards stale rules to ExperienceMiner | `bun test packages/runtime --filter experience` | Candidate/Curator/self-patch schema validation | memory baseline, runtime-semantics §17 | -| T-034 | TODO | Doctor | Implement Doctor with read-only, fix mode, and bundle export | `packages/runtime/src/doctor/` | Platform, provider config, toolchain, display, disk, permissions checks report; fix mode applies fixes under PermissionEngine; bundle exports diagnostic archive | `bun run air -- doctor --read-only && bun run air -- doctor --fix --dry-run && bun run air -- doctor --bundle` | Doctor report/bundle schema validation | security/platform matrix, runtime-semantics §18 | +| T-034 | TODO | Doctor | Implement Doctor with read-only, fix mode, and bundle export | `packages/runtime/src/doctor/` | Platform, provider config, toolchain, display, disk, permissions checks report; fix mode applies fixes under PermissionEngine; bundle exports diagnostic archive | `bun run air -- doctor --read-only && bun run air -- doctor --fix --dry-run && bun run air -- doctor --bundle` | Doctor report/bundle schema validation | security/platform matrix, runtime-semantics §19 | | T-035 | TODO | Logging | Implement user/developer logs | `packages/runtime/src/logging/` | `air.log` user errors and encrypted developer log path exist with retention policy hooks | `bun test packages/runtime --filter logging` | Secret redaction tests | security/logging baseline | -| T-036 | TODO | E2E | Implement release gate fixtures | `fixtures/`, `scripts/release-check.*` | Worker, C++ build/test, DB recovery, TUI startup, artifact/event persistence gates run | `bun run release:check` | Typecheck/lint/test all packages | cross-platform matrix | +| T-036 | TODO | E2E | Implement release gate fixtures | `fixtures/`, `scripts/release-check.*` | Worker, C++ build/test, DB recovery, TUI startup, artifact/event persistence gates, phase-complete architecture review, and final Architecture Designer consistency review run | `bun run release:check` | Typecheck/lint/test all packages | cross-platform matrix, scope escalation | | T-037 | TODO | Packaging | Implement binary tarball packaging | `scripts/package.*`, `resources/` | Tarball contains `bin/air`, `resources/`, `LICENSE` and starts on tier-1 Linux | `bun run release:package` | Package smoke validation | distribution baseline | | T-038 | TODO | Main Agent | Implement `/direct` and `/done` direct mode | `packages/runtime/src/agents/main/`, `packages/tui/src/` | Main Agent enters DIRECT_MODE with executor permissions; `/done` exits and collects evidence; direct mode events logged | `bun run air -- e2e direct-mode-fixture` | Direct mode state machine and permission template checks | main-agent-state-machine, runtime-semantics §16 | -| T-039 | TODO | CLI | Implement `air restore` with three granularities | `packages/cli/src/commands/restore.ts`, `packages/runtime/src/restore/` | `air restore file`, `air restore time`, `air restore session` work from git-backed backup repo | `bun test packages/runtime --filter restore` | Restore schema and git operation validation | decisions-round-2 D-032, runtime-semantics §19 | -| T-040 | TODO | CLI | Implement CLI command catalog | `packages/cli/src/commands/` | `air resume`, `air compact`, `air history`, `air session list`, `air provider list` commands exist and function | `bun run air -- help` shows full catalog; individual commands have `--help` | Command typecheck and help output validation | requirements FR-005, baseline §18 | +| T-039 | TODO | CLI | Implement `air restore` with three granularities | `packages/cli/src/commands/restore.ts`, `packages/runtime/src/restore/` | `air restore file`, `air restore time`, `air restore session` work from git-backed backup repo | `bun test packages/runtime --filter restore` | Restore schema and git operation validation | decisions-round-2 D-032, runtime-semantics §20 | +| T-040 | TODO | CLI | Implement CLI command catalog | `packages/cli/src/commands/` | `air resume`, `air compact`, `air history`, `air session list`, and read-only `air provider list/current` commands exist and function; no runtime provider/model switching command exists | `bun run air -- help` shows full catalog; individual commands have `--help` | Command typecheck and help output validation | requirements FR-005, baseline §18 | | T-041 | TODO | Main Agent | Implement `compact` and `resume` user commands | `packages/runtime/src/agents/main/`, `packages/cli/src/commands/` | `air compact` triggers manual compaction; `air resume` restores session from DB | `bun run air -- e2e compact-resume-fixture` | Compaction and resume schema validation | runtime-semantics §7, prompt-layering | | T-042 | TODO | Main Agent | Implement `history` and `session list` commands | `packages/cli/src/commands/` | `air history` shows session message history; `air session list` lists sessions with status | `bun run air -- session list` and `bun run air -- history` | Output format and DB query validation | db-schema, projection | | T-043 | TODO | TUI | Implement permission prompt UX with announce_then_run visualization | `packages/tui/src/components/PermissionPrompt.tsx` | Permission prompts render risk level, options, and announce_then_run mode; user decisions flow through UiCommandChannel | `bun test packages/tui --filter permission` | Permission prompt UI snapshot validation | security-model, scope-escalation | @@ -56,7 +57,7 @@ Status values: TODO / DOING / DONE / BLOCKED ## Quality Gates -- T-000A through T-000D are DONE. System overview design, detailed design, and `packages/contracts` implementation may proceed. +- T-000A through T-000E are DONE. System overview design is repaired after four-model audit; detailed design and `packages/contracts` implementation may proceed. - Run the validation command listed for the task before marking it `DONE`. - Keep ADR and C4 docs synchronized whenever architecture, module boundaries, dependencies, or ownership change. - Record skipped validation, residual risk, and follow-up work explicitly.