8d9c4208fa
- 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>
649 lines
26 KiB
Markdown
649 lines
26 KiB
Markdown
# 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 注明
|