System overview design: four-model audit, repair, and regression complete
- system-overview-design.md: repaired with P0/P1/P2 gaps resolved, all 24 frozen baselines listed, error taxonomy, global ~/.air, IPC, TaskSpec/WorkerResult, PromptLayer, PermissionEngine, RuntimeEvent, state machines, capability trust, artifact naming, operations - Four cross-verification audit reports (GPT-5, MIMO 2.5, Opus 4.7, DeepSeek V4 Pro) - Three regression reviews (R1: initial repair closure, R2: second pass with PromptLayer L9 wording found, R3: full PromptLayer alignment verified) - AGENTS.md, plan.md, todo.md synchronized Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
AirCoding
@@ -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`
|
||||
|
||||
439
AirPlan/docs/architecture/DeepSeek概要设计审查.md
Normal file
439
AirPlan/docs/architecture/DeepSeek概要设计审查.md
Normal file
@@ -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-id>/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 |
|
||||
401
AirPlan/docs/architecture/Opus4.7概要设计审查.md
Normal file
401
AirPlan/docs/architecture/Opus4.7概要设计审查.md
Normal file
@@ -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/<project-id>/session/<session-id>/<artifact-id>`、ID 格式 `art_<ulid>`、文件名格式 `<timestamp>-<artifact-id>-<slug><extension>`、类型到目录映射表。
|
||||
|
||||
现状：概要设计 §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%）。
|
||||
648
AirPlan/docs/architecture/gpt5概要设计审查.md
Normal file
648
AirPlan/docs/architecture/gpt5概要设计审查.md
Normal file
@@ -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/<version>/
|
||||
skills/
|
||||
logs/{air.log,air.developer.log}
|
||||
|
||||
`project_id` is a stable UUID generated at initialization and stored in `.air/shared/project.json`.
|
||||
It is not derived from the absolute path.
|
||||
|
||||
`.air/local/` should be gitignored by default.
|
||||
```
|
||||
|
||||
### 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` / `<project>/.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
|
||||
- <project>/.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 路径（`<project>/.air/shared/rules/`）、skills 路径（`~/.air/skills/<skill-name>/SKILL.md`）、promotion 策略（非调试经验需重复出现 + 用户确认，调试经验以验证证据为置信度）、debug sharing 需 redaction/preview/显式授权。
|
||||
|
||||
建议补入 §13 或 §8.3：
|
||||
|
||||
```md
|
||||
Project rules: <project>/.air/shared/rules/{project-rules.md,toolchain-rules.md}
|
||||
Skills: ~/.air/skills/<skill-name>/SKILL.md
|
||||
|
||||
Non-debug memories require repeated occurrence (N=3) plus user confirmation before promotion.
|
||||
Debug experience confidence comes from verified evidence, not numeric scoring.
|
||||
Debug knowledge sharing requires redaction, preview, and explicit authorization.
|
||||
```
|
||||
|
||||
### 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/<timestamp>/
|
||||
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 注明
|
||||
1550
AirPlan/docs/architecture/mimo2.5概要设计审查.md
Normal file
1550
AirPlan/docs/architecture/mimo2.5概要设计审查.md
Normal file
File diff suppressed because it is too large
Load Diff
1222
AirPlan/docs/architecture/system-overview-design.md
Normal file
1222
AirPlan/docs/architecture/system-overview-design.md
Normal file
File diff suppressed because it is too large
Load Diff
195
AirPlan/docs/architecture/概要设计修复回归审查-R2.md
Normal file
195
AirPlan/docs/architecture/概要设计修复回归审查-R2.md
Normal file
@@ -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_<ulid>`, 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-id>/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. 不再修改冻结基线。
|
||||
158
AirPlan/docs/architecture/概要设计修复回归审查-R3.md
Normal file
158
AirPlan/docs/architecture/概要设计修复回归审查-R3.md
Normal file
@@ -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. 增加一项详细设计释义机制：当详细设计需要扩写概要描述时，在脚注或附录中标注与基线原文的对齐方式。
|
||||
|
||||
这些是流程建议，不阻塞进入详细设计。
|
||||
155
AirPlan/docs/architecture/概要设计修复回归审查.md
Normal file
155
AirPlan/docs/architecture/概要设计修复回归审查.md
Normal file
@@ -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** |
|
||||
|
||||
最终结论：**概要设计修复回归通过。**
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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 <fixture>` | 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.
|
||||
|
||||
Reference in New Issue
Block a user