ae44be31d5
Includes AirPlan design documents, AircOding-alpha1-plan, AirPlanV2, AirPlan-ParaV2, AirPlan-Para V1 reference docs, and all working code changes across packages. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
494 lines
34 KiB
Markdown
Executable File
494 lines
34 KiB
Markdown
Executable File
# AirCoding V1.0.0 Alpha — 完整需求、设计决策、约束提取
|
|
|
|
**生成日期**: 2026-06-11
|
|
**提取工具**: deepseek-v4-pro 全量提取
|
|
**来源文档**: requirements.md + airplanV2-Qwen3.7-Max设计.md + baselineV1.md + solution-architecture.md + system-overview-design.md + system-detailed-design.md
|
|
**参考原型**: air-suite-20260518 (V1 Python插件系统, 8个已验证插件)
|
|
|
|
> 共 383 条。每条的 source 字段标注了来源文档和章节。
|
|
|
|
---
|
|
|
|
## FR (Functional Requirements) — 21条 + 7条子要求
|
|
|
|
### 来源: requirements.md §3
|
|
|
|
1. **FR-001** (requirements.md §3): CLI Startup and Project Initialization — 从CLI入口启动,检测/打开项目,需要时初始化`.air/`,加载资源/配置,运行只读Doctor,打开session。
|
|
|
|
2. **FR-002** (requirements.md §3): Project-Local State — `.air/shared/`(可共享配置/规则/计划) + `.air/local/`(私有sessions/artifacts/workspaces/backups/local DBs)。
|
|
|
|
3. **FR-003** (requirements.md §3): Session Persistence — SQLite at `<project>/.air/local/sessions/<session-id>/session.db`, 支持messages/drafts/durable events/task graph state/agents/tool/command runs/artifacts/diagnostics/evidence refs/workspaces/summaries/UI state。
|
|
|
|
4. **FR-004** (requirements.md §3): Event-Driven Runtime — 发布RuntimeEvents用于实时行为,持久事件与域表更新事务一致。
|
|
|
|
5. **FR-005** (requirements.md §3): Main Agent Conversation — 面向用户的Agent: 接收请求,适当直接回答,分类工作,显示进度,呈现阻断/确认。
|
|
|
|
6. **FR-006** (requirements.md §3): Architecture Designer — 架构/接口/产品级决策路由到Architecture Designer: 更新架构制品,产生影响评估。
|
|
|
|
7. **FR-007** (requirements.md §3): Scheduler and TaskGraph — 调度TaskSpec: hard/soft依赖,写区冲突处理,重试预算,子Worker派发,心跳监控,合并协调,重启恢复。
|
|
|
|
8. **FR-007.5** (requirements.md §3): ADR级联失效与架构变更回滚 — 7条子要求:
|
|
- (a) 通过TaskNode.adr_refs溯源所有依赖该ADR的任务(含已完成)
|
|
- (b) 级联失效: completed→invalidated, running→终止, pending→cancelled
|
|
- (c) 冻结调度(dispatch_frozen),阻止新任务派发
|
|
- (d) 创建git回滚快照(rollback_ref),支持revert旧方案代码
|
|
- (e) 接收ArchitectureDesigner产出的PlanDelta增量重规划
|
|
- (f) apply_delta吸收新任务后解冻调度
|
|
- (g) 终审时检查INVALIDATED任务的旧代码是否已清理
|
|
|
|
9. **FR-008** (requirements.md §3): Independent Worker Agents — Executor/Reviewer/Debugger/Compactor/ExperienceMiner作为独立Bun子进程,通过NDJSON IPC通信。
|
|
|
|
10. **FR-009** (requirements.md §3): Claude Code-Quality Execution Primitives — 强制: read-before-edit, exact conservative edits, small patches, no unrelated refactors, permission checks, verification-before-completion。
|
|
|
|
11. **FR-010** (requirements.md §3): ToolRegistry and Built-In Tools — Schema验证的工具: filesystem/shell/git/project scanning/完整C++ build/test/static-analysis/debug/GUI screenshot/network capture/artifacts/context assembly/permission requests/Doctor。
|
|
|
|
12. **FR-011** (requirements.md §3): Permission and Security Model — 分类paths/commands/network/credentials,强制权限配置,保护系统敏感和凭证操作,项目外写入备份,拒绝不安全请求。
|
|
|
|
13. **FR-012** (requirements.md §3): Plugin and Capability Foundation — manifest loading/validation/enable-disable config/dependency declaration/Doctor integration/namespaced tool registration/source-trust metadata/PermissionEngine enforcement。第三方registry/signing可延后,本地和内置capability打包必须可用。
|
|
|
|
14. **FR-013** (requirements.md §3): Provider Layer — 内部Anthropic canonical消息,通过适配器路由provider调用,能力矩阵验证和转换报告。
|
|
|
|
15. **FR-014** (requirements.md §3): Context Assembly and Compaction — 有序层组装prompt,适配token预算,记录遗漏,必要时copy-on-write压缩。
|
|
|
|
16. **FR-015** (requirements.md §3): Artifact and Evidence Management — temp-file→atomic rename,记录URI/path/hash/metadata,通过evidence refs链接声明。
|
|
|
|
17. **FR-016** (requirements.md §3): TUI and HUD — OpenTUI/Solid终端UI和HUD,仅消费ProjectionStore,不查询原始DB/EventBus。
|
|
|
|
18. **FR-017** (requirements.md §3): Complete C++ Development Workflow — 项目检测→构建系统评估→CMake configure→Ninja优先/Make回退→编译器/链接器诊断解析→clangd代码智能查询→cppcheck静态分析→CTest/GoogleTest执行→debug run/log解析→失败诊断→范围修复→审查→证据支持验证。
|
|
|
|
19. **FR-018** (requirements.md §3): Doctor — 启动时运行只读Doctor,报告环境/能力问题,在权限策略下支持修复模式。
|
|
|
|
20. **FR-019** (requirements.md §3): Logging and Diagnostics — 可读`air.log`,加密`air.developer.log`,默认7天保留。
|
|
|
|
21. **FR-020** (requirements.md §3): Release Gate — 定义tier-1 Linux发布门禁: unit tests/integration fixture replay/real LLM E2E/project init/C++ build-test flow/SQLite recovery/child IPC/TUI startup/artifact-event persistence。
|
|
|
|
---
|
|
|
|
## NFR (Non-Functional Requirements) — 8条
|
|
|
|
### 来源: requirements.md §4
|
|
|
|
22. **NFR-001** (requirements.md §4): Local-First Operation — 项目状态/制品/日志/调试知识保留在本地,除非用户显式导出/分享/上传。
|
|
|
|
23. **NFR-002** (requirements.md §4): Recoverability — 从进程/session重启恢复:读取SQLite状态,检测丢失agents,保留workspaces,重建Scheduler队列。
|
|
|
|
24. **NFR-003** (requirements.md §4): Extensibility — 通过`toolchain-*`包和能力清单添加语言/工具链支持。
|
|
|
|
25. **NFR-004** (requirements.md §4): Provider Flexibility — 内部契约在Anthropic/OpenAI/OpenRouter/ollama/兼容端点间保持稳定。
|
|
|
|
26. **NFR-005** (requirements.md §4): UI Responsiveness — Main Agent和TUI在后台Worker运行时保持响应。
|
|
|
|
27. **NFR-006** (requirements.md §4): Evidence-Based Completion — 任务未获得build/test/debug/review证据或显式skipped-gate报告前不得标记完成。
|
|
|
|
28. **NFR-007** (requirements.md §4): Linux-First Platform Support — Linux x86_64 tier1, arm64/WSL2 tier2, macOS实验, Windows native post-MVP/实验。
|
|
|
|
29. **NFR-008** (requirements.md §4): Security Boundary Preservation — LLM输出/工具结果/插件/外部内容在被运行时契约和策略验证前为不可信数据。
|
|
|
|
---
|
|
|
|
## AC (Acceptance Criteria) — 13条
|
|
|
|
### 来源: requirements.md §6
|
|
|
|
30. **AC-01**: CLI starts and initializes/opens a project `.air/` tree.
|
|
31. **AC-02**: Session DB schema initializes and persists messages/events/tasks/tool runs/artifacts.
|
|
32. **AC-03**: EventStore transactionally applies core durable events to domain tables.
|
|
33. **AC-04**: ProjectionStore hydrates and updates a usable TUI/HUD view.
|
|
34. **AC-05**: Scheduler dispatches worker child processes via NDJSON IPC, supports tool calls, receives WorkerResult.
|
|
35. **AC-06**: ToolRegistry executes filesystem/shell/git/artifact/context/doctor/C++/debug/GUI/network tools through PermissionEngine.
|
|
36. **AC-07**: C++ workflow can detect, configure, build, statically analyze, test, debug, fix, review, re-verify a fixture project.
|
|
37. **AC-08**: Failed build/test/debug commands produce diagnostics/artifacts/evidence refs and can trigger Debugger repair.
|
|
38. **AC-09**: ContextAssembler produces Anthropic canonical messages with omissions where needed.
|
|
39. **AC-10**: Provider adapter path can perform model calls under capability validation and conversion reporting.
|
|
40. **AC-11**: Capability manifests can be loaded, validated, enabled, registered as namespaced tools.
|
|
41. **AC-12**: Doctor reports platform/provider/toolchain/capability/display/network status and supports permissioned fix mode.
|
|
42. **AC-13**: Release gate commands are documented and runnable on tier-1 Linux.
|
|
|
|
---
|
|
|
|
## CT (Constraints) — 16条
|
|
|
|
### 来源: requirements.md §5 + baselineV1.md §3-§5
|
|
|
|
43. **CT-01** (requirements.md §5): Runtime: TypeScript on Bun.
|
|
44. **CT-02** (requirements.md §5): Monorepo: Bun workspaces + Turborepo.
|
|
45. **CT-03** (requirements.md §5): TUI: OpenTUI/Solid.
|
|
46. **CT-04** (requirements.md §5): IPC: NDJSON over stdio.
|
|
47. **CT-05** (requirements.md §5): DB: SQLite per session with WAL/NORMAL/foreign_keys OFF.
|
|
48. **CT-06** (requirements.md §5): Internal message format: Anthropic canonical content blocks.
|
|
49. **CT-07** (requirements.md §5): C++ is first deep toolchain; runtime remains language-agnostic.
|
|
50. **CT-08** (requirements.md §5): Python is subprocess-only helper layer, not core runtime.
|
|
51. **CT-09** (requirements.md §5): Early distribution uses binary tarball, not public package channels.
|
|
52. **CT-10** (requirements.md §5): Architecture docs and workflow state live under `AirPlan/`.
|
|
53. **CT-11** (baselineV1 §3-§4): Monorepo packages (Alpha) — contracts, cli, tui, runtime, llm, toolchain-cpp.
|
|
54. **CT-12** (baselineV1 §4): Dependency direction — contracts(no deps) → cli → tui/runtime/llm/toolchain-cpp; runtime → contracts + llm facade + toolchain via registry; tui → contracts only; runtime must not depend on tui.
|
|
55. **CT-13** (baselineV1 §5): Global user directory — `~/.air/`.
|
|
56. **CT-14** (baselineV1 §5): project_id is stable UUID in `.air/shared/project.json`, not derived from absolute path.
|
|
57. **CT-15** (baselineV1 §5): `.gitignore`: `.air/local/`.
|
|
58. **CT-16** (baselineV1 + solution-arch): All side effects must pass through ToolRegistry and PermissionEngine.
|
|
|
|
---
|
|
|
|
## RB (Reference Baselines) — 6条
|
|
|
|
### 来源: baselineV1.md §2
|
|
|
|
59. **RB-01** (baselineV1 §2): Claude Code CLI — Primary reference for execution-layer quality. Reference areas: file read/edit/write safety, exact conservative diff/update, patch granularity, tool lifecycle, permission checks, read-before-edit, small-step edits, no unrelated refactors, verification-before-completion, build/test/debug evidence, root-cause failure handling, blocker escalation, TAOR/TORI feedback loops.
|
|
|
|
60. **RB-02** (baselineV1 §2): OpenCode — Reference for runtime layering, TUI visual style/interaction, session/event/sync concepts, provider/model abstraction, plugin/SDK ideas. **Reuse OpenTUI primitives. Do NOT reuse SDK/sync/session business state.**
|
|
|
|
61. **RB-03** (baselineV1 §2): Hermes Agent — Reference for experience mining, Nudge Engine interval-triggered learning, Curator daemon, skill self-patching, SKILL.md format, FTS retrieval.
|
|
|
|
62. **RB-04** (baselineV1 §2): OpenAI Codex — Reference for shell/patch/test direct execution loop, coding sandbox, tool orchestration, MCP implementation ideas.
|
|
|
|
63. **RB-05** (baselineV1 §2): Anthropic Claude Skills — Reference for SKILL.md structure/frontmatter, skill directory layout (scripts/references/assets), reusable workflow packaging.
|
|
|
|
64. **RB-06** (baselineV1 §2): asciinema / Atuin / claude-hud — Reference for PTY capture/terminal replay, command metadata/history indexing, HUD/statusline layout and activity display.
|
|
|
|
---
|
|
|
|
## PV (V1 Plugin Prototypes) — 8个已生产验证的插件工作流
|
|
|
|
### 来源: air-suite-20260518 + airplanV2-Qwen3.7-Max设计.md §1.2
|
|
|
|
> **核心架构原则**: Agent (MainAgent/Scheduler/Worker) 存在的目的是扩展插件的能力边界。**插件代表的工作流才是产品核心**。AirCoding V1.0.0 Alpha 是V1 8个插件从 Claude Code Skill 到 TypeScript 运行时的移植重构——不是从零开发,是给已验证的工作流换一个可靠的运行时底座。
|
|
|
|
### 8个V1插件 → AirCoding移植映射
|
|
|
|
| # | V1插件 | 目录 | 工作流 | AirCoding模块 | 移植状态 |
|
|
|---|--------|------|--------|--------------|----------|
|
|
| 1 | **AirArc** | `airplan-mkt/airarc/` | 架构规划设计器: 需求探讨→架构确认→生成规划 | `ArchitectureDesigner` | ❌ 正则替代LLM |
|
|
| 2 | **AirEng** | `airplan-mkt/aireng/` | 调度引擎: 波次规划→Dispatch→Monitor→Merge→Repair | `Scheduler` | ⚠️ 基础可调度 |
|
|
| 3 | **AirDo** | `airplan-mkt/airdo/` | 任务执行器: 接收TaskSpec→调用工具→验收→返回结果 | `ExecutorRole` | ⚠️ 简单任务可跑 |
|
|
| 4 | **AirDbg** | `airplan-mkt/airdbg/` | 调试器: 确认症状→取证→定位根因→修复→验证→关闭 | `DebuggerRole` | ❌ 从未触发 |
|
|
| 5 | **AirXDB** | `airplan-mkt/airxdb/` | GUI验证: 截图取证→diff对比→headless CI | `gui.screenshot` | ❌ 仅ImageMagick |
|
|
| 6 | **AirNDB** | `airplan-mkt/airndb/` | 网络调试: 抓包→分析→TLS解密 | `network.capture` | ⚠️ tcpdump封装 |
|
|
| 7 | **AirSDB** | `airplan-mkt/airsdb/` | 静态分析: cppcheck/clang-tidy→diff→多语言 | `toolchain-cpp` | ❌ 仅cppcheck注册 |
|
|
| 8 | **AirContext** | `aircontext-mkt/` | 上下文管理: 压缩→token估算→stale lock检测 | `ContextAssembler`+`CompactorRole` | ⚠️ 基础实现 |
|
|
|
|
### V1已验证能力 → AirCoding丢失清单
|
|
|
|
| V1能力 | 来源缺陷 | AirCoding |
|
|
|---------|----------|-----------|
|
|
| 架构变更级联失效(ADR→Task失效→冻结→回滚→重规划) | P1-21, V2I-23 | ⚠️ 方法全实现, 零生产调用 |
|
|
| 证据优先门控(不取证不许改代码) | P1-17, V2I-30 | ❌ |
|
|
| 7步调试工作流强制(finish_worker 的 forced AirDbg routing) | P0-8, V2I-13, V2I-28 | ❌ |
|
|
| Plan mode 阻断(架构器永不写代码) | P0-5, V2I-09 | ❌ |
|
|
| 自主调度+中文锁定(不停下来问, 自动推进) | P0-6, P0-7, V2I-10, V2I-11 | ❌ |
|
|
| 任务类型感知证据门控(GUI/Network/CodeOnly分类) | P0-1, V2I-04 | ❌ |
|
|
| Worker超时+资源保护(7200s硬上限, load检测) | P1-10, V2I-07 | ⚠️ AgentMonitor基础 |
|
|
| 修复回滚(pre_fix_snapshot, git revert修复) | V2I-29 | ✅ _create_rollback_snapshot |
|
|
| 非原子写入保护(tempfile+os.replace) | P0-3 | ✅ ArtifactStore |
|
|
| 并发控制(flock替代无锁读改写) | P0-4 | ✅ SQLite事务 |
|
|
| Dispatch→Worker桥接(spawn_workers标准化,消除Agent回退) | P1-22, V2I-16 | ⚠️ WorkerManager可用 |
|
|
|
|
---
|
|
|
|
## AP (Architecture Principles) — 189条 (关键摘录)
|
|
|
|
### 来源: baselineV1.md + solution-architecture.md + system-overview-design.md + system-detailed-design.md
|
|
|
|
> 完整189条AP参见 `/home/airlongdian/DataDevices/AirWorkSpace/AirCoding/AirPlan/docs/analysis/requirements-audit-report.md`
|
|
|
|
### 核心架构原则 (baselineV1)
|
|
|
|
65. **AP-01**: AirCoding is a self-owned AI coding agent/runtime, not a Claude Code plugin wrapper.
|
|
66. **AP-02**: Runtime is language-agnostic; C++ is first deep language profile.
|
|
67. **AP-03**: Core loop: requirement → architecture design → code reading → implementation planning → build → static analysis → test → run/debug → evidence → fix → summary → experience mining.
|
|
|
|
### 执行质量基准 (solution-architecture §3)
|
|
|
|
68. **AP-45**: Execution quality follows Claude Code — read-before-edit, exact, conservative, small, verified before completion.
|
|
69. **AP-46**: OpenCode is UI/runtime reference, not business-state dependency.
|
|
70. **AP-47**: Project-local source of truth under `.air/`.
|
|
71. **AP-48**: Events drive live behavior; SQLite drives recovery.
|
|
72. **AP-49**: Workers are isolated child processes over NDJSON IPC.
|
|
73. **AP-50**: Main Agent remains responsive; background work delegated to Scheduler.
|
|
74. **AP-51**: Architecture changes are explicit — implementation-level continues silently.
|
|
75. **AP-52**: Tool/capability boundaries are permissioned through ToolRegistry+PermissionEngine.
|
|
76. **AP-53**: Provider boundary isolated — internal Anthropic canonical; adapters convert at boundary.
|
|
77. **AP-54**: Evidence first-class — build/test/debug/review outputs become artifacts/evidence before completion.
|
|
|
|
### 容器职责 (solution-architecture §4)
|
|
|
|
78. **AP-55**: CLI: command entrypoint, startup, Doctor, project discovery, TUI/runtime bootstrap.
|
|
79. **AP-56**: TUI/HUD: consumes ProjectionStore only, no SQLite/EventBus queries.
|
|
80. **AP-57**: Runtime: MainAgent, ArchitectureDesigner, Scheduler, child process mgmt, EventBus/EventStore, SessionStore, ToolRegistry, PermissionEngine, CapabilityRegistry, ContextAssembler, ArtifactStore, EvidenceStore.
|
|
81. **AP-58**: LLM: provider config, adapters, Anthropic canonical handling, conversion, capability matrix.
|
|
82. **AP-59**: Toolchain C++: project detection, CMake, Ninja/Make, CTest, cppcheck, clangd, diagnostic parsing.
|
|
83. **AP-60**: Contracts: compileable shared TS interfaces, no domain implementation deps.
|
|
|
|
### 禁止路径 (system-overview §5)
|
|
|
|
84. **AP-85**: Forbidden: TUI→SQLite, TUI→runtime private, Worker→SQLite, Worker→direct fs/shell/network, tool→no PermissionEngine, capability→install outside Doctor, provider→silent semantic loss, repository→scheduling policy, EventBus→recovery source, runtime→TUI import, LLM output→direct file/shell.
|
|
|
|
### 控制流 (solution-architecture §7)
|
|
|
|
85. **AP-71**: Startup: CLI→detect→load→open/init .air→read-only Doctor→open session DB→hydrate ProjectionStore→start TUI/Main Agent.
|
|
86. **AP-72**: Normal execution: user→Main Agent classify→answer or plan→Scheduler create/load TaskGraph→ContextAssembler→dispatch Worker→tools→PermissionEngine→WorkerResult→retry/merge/review→report.
|
|
87. **AP-73**: Requirement change: requirement.changed→Scheduler pause→Architecture Designer assess→silent continue or confirm/replan.
|
|
88. **AP-74**: Recovery: restart→open DB→load tasks/agents→check liveness→emit lost/failed or resume→preserve workspaces→rebuild queues→hydrate ProjectionStore.
|
|
|
|
### 数据架构 (solution-architecture §6)
|
|
|
|
89. **AP-69**: SQLite: WAL/NORMAL/foreign_keys OFF.
|
|
90. **AP-88**: Durable event insert + domain update in same SQLite transaction.
|
|
91. **AP-91**: Event flow: Producer→EventIngestor→validate→durable: EventStore transaction+projection+EventBus publish; ephemeral: EventBus publish.
|
|
|
|
### 安全 (solution-architecture §10, system-overview §12)
|
|
|
|
92. **AP-79**: Security boundaries — LLM output untrusted; tools only path to effects; symlinks resolved by realpath; .git/ protected; project-outside writes require backup; credentials require confirmation; no auto-upload.
|
|
93. **AP-104**: Permission evaluation order: tool capability → permission profile → TaskSpec scope → path/command/network risk → credential/system-sensitive → user prompt.
|
|
94. **AP-105**: Permission actions: allow, deny, ask_user, block, refuse, announce_then_run.
|
|
95. **AP-106**: Path risk categories (8): project_source, project_build_output, project_air_shared, project_air_local, project_git_internal, outside_project, credential_or_secret, system_sensitive.
|
|
96. **AP-107**: Command risk categories (10): read_only, build, test, static_analysis, git_read, git_write, destructive, network, system_sensitive, credential_sensitive.
|
|
|
|
### 上下文/压缩 (system-overview §13)
|
|
|
|
97. **AP-109**: Compaction: ContextAssembler may request; Scheduler creates compact task; Compactor snapshots messages; summary.created; original messages preserved.
|
|
98. **AP-158**: ContextAssembler assembles Anthropic-canonical context; fits to token_budget; reports omissions; sets compaction_requested if budget cannot fit required layers.
|
|
99. **AP-77**: L0-L9 layers: runtime invariant, role/mode, safety/permission, project rules, architecture, task spec, evidence, conversation, tool history, instruction.
|
|
|
|
### Worker/IPC (system-detailed-design §8)
|
|
|
|
100. **AP-148**: WorkerManager spawn starts Bun child process then handshake; WorkerProcess owns NDJSON pipe.
|
|
101. **AP-150**: Worker roles: ExecutorRole (scoped write), ReviewerRole (read-only), DebuggerRole (scoped write assigned), CompactorRole (summaries/artifacts only), ExperienceMinerRole (candidates/rules/skills assigned).
|
|
102. **AP-151**: TaskType→WorkerRole: execute→Executor, review→Reviewer, debug→Debugger, compact→Compactor, mine_experience→ExperienceMiner, docs→Executor.
|
|
103. **AP-103**: Workers never write SQLite directly; never perform side effects outside parent-mediated tools.
|
|
|
|
### 调度器 (system-detailed-design §7)
|
|
|
|
104. **AP-143**: Scheduler states: IDLE→LOADING_GRAPH→PLANNING_WAVE→DISPATCHING→MONITORING→COLLECTING_RESULTS→MERGING→REVIEWING_WAVE→REPAIRING_OR_CONTINUING. Terminals: COMPLETED, BLOCKED, CANCELLED.
|
|
105. **AP-144**: TaskGraph: get_runnable_tasks honors hard deps completed, soft deps priority, conflict/serialization block concurrent dispatch on overlapping write areas.
|
|
106. **AP-146**: RetryPlanner actions: retry, retry_serial, debug, skip, block, cancel.
|
|
107. **AP-147**: WorkspaceManager strategies: main (no merge), worktree (git merge/patch), isolated_copy (copy-back/patch).
|
|
|
|
### 可追溯性 (system-detailed-design §24)
|
|
|
|
108. **AP-188**: System Detailed Design frozen as of 2026-06-01; multi-model review complete across 7 review rounds; all P0/P1/P2 findings closed; coverage: contracts 100%, events 100%, DB schema 100%, state machines 100%, forbidden edges 100%.
|
|
|
|
### 不变量 (INV-1 ~ INV-5)
|
|
|
|
109. **INV-1**: Session-DB state columns written only by event projection; no direct UPDATE from services.
|
|
110. **INV-2**: Cross-DB/external writes use outbox model; EventStore.project() never opens external DBs or files.
|
|
111. **INV-3**: All side effects only through tool + permission path (ToolRegistry.call → PermissionEngine.evaluate).
|
|
112. **INV-4**: Import/dependency direction is one-way per allowed graph; never crossed.
|
|
113. **INV-5**: EventBus is transport, never source of truth; recovery rebuilds from SQLite.
|
|
|
|
### 参考复用 (system-detailed-design §23)
|
|
|
|
114. **AP-185**: Reference reuse modes — npm-dep (consume directly), fork/adapt (copy+adapt), pattern (reference structure), behavioral (match behavior/quality).
|
|
115. **AP-186**: Reference map — OpenTUI: npm-dep; OpenCode TUI: pattern only; @opencode-ai/llm: fork/adapt; Claude Code CLI: behavioral only; OpenAI Codex: pattern; Hermes Agent: pattern; Anthropic Skills: pattern; asciinema/Atuin/claude-hud: pattern.
|
|
116. **AP-187**: Reference reuse rules — npm-dep items never re-implemented; fork/adapt items preserve own contracts/invariants; behavioral items contribute no code.
|
|
|
|
---
|
|
|
|
## DF (Defect Fixes from AirPlan V2) — 33条
|
|
|
|
### 来源: airplanV2-Qwen3.7-Max设计.md §1.1
|
|
|
|
### P0 — 已造成实际损失 (10条)
|
|
|
|
117. **P0-1**: AirXDB false positive blocking — evidence gate no task-type awareness; 11+ tasks.
|
|
118. **P0-2**: Deployment verification gap — validate_for_finalize() structural-only.
|
|
119. **P0-3**: Non-atomic writes — 5 _json_dump sites use direct path.write_text().
|
|
120. **P0-4**: Zero concurrency control — todo.md read-modify-write race.
|
|
121. **P0-5**: AirArc hijacked by plan mode.
|
|
122. **P0-6**: AirEng stops to ask instead of autonomous decisions.
|
|
123. **P0-7**: AirEng no child-thread status polling — relies on Agent self-discipline.
|
|
124. **P0-8**: AirDo does not call AirDbg — skips debug, directly reports blocked/false-done.
|
|
125. **P0-9**: Installer script path errors.
|
|
126. **P0-10**: AirEng deviates from scheduling to write code.
|
|
|
|
### P1 — 限制可靠性与可维护性 (14条)
|
|
|
|
127. **P1-1**: Hardcoded developer paths (debug_runtime.py:130, airxdb_runtime.py:156).
|
|
128. **P1-2**: `_json_dump`/`_json_load` duplicated 5 times.
|
|
129. **P1-3**: `_ordered_unique` duplicated 4 times.
|
|
130. **P1-4**: policy normalization duplicated 3 times.
|
|
131. **P1-5**: merge-into-state duplicated 3 times.
|
|
132. **P1-6**: marker block upsert duplicated 2 times with different interfaces.
|
|
133. **P1-7**: `_session_stamp` format inconsistent.
|
|
134. **P1-8**: todo.md column index hardcoded (doc_sync.py:154-156).
|
|
135. **P1-9**: Concurrency cap hardcoded as 3 (engine.py:527).
|
|
136. **P1-10**: Child processes have no timeout in airxdb/debug runtime.
|
|
137. **P1-11**: task_id path injection at worker.py:59 — no `../` validation.
|
|
138. **P1-12**: Marker injection risk in doc_sync.py `_replace_marker_block()`.
|
|
139. **P1-13**: Silent exception swallowing — session file corruption continue with no log.
|
|
140. **P1-14**: Arc re-planning then Eng cannot connect — static todo.md table cannot absorb dynamic replanning.
|
|
141. **P1-15**: Same-file non-conflicting tasks forced serial — file-level conflict detection.
|
|
142. **P1-16**: AirArc skips requirements discussion, directly generates plan.
|
|
143. **P1-17**: AirDbg modifies code without evidence collection.
|
|
144. **P1-18**: Project lacks standardized logging (no spdlog).
|
|
145. **P1-19**: No boundary tests + final review lacks high-risk checks.
|
|
146. **P1-20**: UI design lacks professional Skill support.
|
|
147. **P1-21**: ADR changes have no cascading invalidation mechanism.
|
|
148. **P1-22**: Dispatch→Worker launch has no bridge — dispatch_worker_group() writes JSON, no Worker launch.
|
|
149. **P1-23**: Dispatch instruction ambiguity — commands/eng.md intent description, not pseudocode.
|
|
150. **P1-24**: Merge then TaskGraph state out of sync — merge_worker_result() doesn't update task-graph.json.
|
|
|
|
### P2 — 限制规模化 (4条)
|
|
|
|
151. **P2-1**: Conflict detection O(n²) — review.py combinations(active_tasks, 2).
|
|
152. **P2-2**: state.json unbounded growth — mergedResults never truncated.
|
|
153. **P2-3**: todo.md full re-parse on every operation.
|
|
154. **P2-4**: Zero test coverage — entire air_runtime/.
|
|
|
|
### P3 — 限制用户体验 (5条)
|
|
|
|
155. **P3-1**: AGENTS.md bloat — AirEng sync appends without dedup.
|
|
156. **P3-2**: Write-set rigidity causes cascading task chains.
|
|
157. **P3-3**: Parallel Workers compete for shared hardware — no awareness.
|
|
158. **P3-4**: Environment-specific fixes not persistable.
|
|
159. **P3-5**: Cross-project knowledge not transferred.
|
|
|
|
---
|
|
|
|
## V2I (V2 Improvements) — 40条
|
|
|
|
### 来源: airplanV2-Qwen3.7-Max设计.md §3
|
|
|
|
160. **V2I-01** (§3.1.1): `air_runtime.io` — atomic_json_write (tempfile+os.replace), safe_json_load.
|
|
161. **V2I-02** (§3.1.2): `air_runtime.lock` — FileLock based on fcntl.flock with timeout.
|
|
162. **V2I-03** (§3.1.3): `air_runtime.utils` — ordered_unique, session_stamp, normalize_policy, sanitize.
|
|
163. **V2I-04** (§3.2.1): EvidenceGatePolicy — task-type-aware (GUI_INDICATORS, NETWORK_INDICATORS).
|
|
164. **V2I-05** (§3.2.2): Deploy verification enforcement in WorkerResult.validate_for_finalize.
|
|
165. **V2I-06** (§3.2.3): AdaptivePoller — dynamic intervals (min 30s, max 300s).
|
|
166. **V2I-07** (§3.2.4): Worker timeout (WORKER_MAX_WALL_TIME=7200s) + resource protection.
|
|
167. **V2I-08** (§3.2.5): Merge transactionization with FileLock.
|
|
168. **V2I-09** (§3.2.6): AirArc plan mode blocking — allowed_tools: [Read, Glob, Grep]; deny_plan_mode.
|
|
169. **V2I-10** (§3.2.7): AirEng autonomous decision + Chinese lock.
|
|
170. **V2I-11** (§3.2.8): AirEng hardcoded polling loop — mandatory 5-minute cycle.
|
|
171. **V2I-12** (§3.2.8b): AirEng scheduling boundary — EXTREME_TAKEOVER only when budget exhausted + ≤5 lines.
|
|
172. **V2I-13** (§3.2.9): AirDo mandatory AirDbg routing (forced=true).
|
|
173. **V2I-14** (§3.2.10): Installer path correction — absolute paths + post_install_verify.
|
|
174. **V2I-15** (§3.2.11): Dynamic graph scheduling (TaskGraph+PlanDelta) — **已在AirCoding实现**.
|
|
175. **V2I-16** (§3.2.11b): Dispatch→Worker launch bridge — spawn_workers standardized.
|
|
176. **V2I-17** (§3.2.11c): Merge→TaskGraph state sync — task-graph.json node status is authoritative.
|
|
177. **V2I-18** (§3.2.12): Worktree isolation for same-file different-region parallelism.
|
|
178. **V2I-19** (§3.2.13): AirArc requirements discussion gate — three-phase process.
|
|
179. **V2I-20** (§3.2.14): Project-level spdlog logging standard.
|
|
180. **V2I-21** (§3.2.15): Boundary test enforcement + final review high-risk audit.
|
|
181. **V2I-22** (§3.2.16): frontend-design Skill integration.
|
|
182. **V2I-23** (§3.2.17): ADR change cascading invalidation — **已在AirCoding实现方法,待生产接线**.
|
|
183. **V2I-24** (§3.3.1): Compression quality validation — **已在AirCoding实现CompressionValidator**.
|
|
184. **V2I-25** (§3.3.2): Token estimation improvement — AdaptiveTokenEstimator.
|
|
185. **V2I-26** (§3.3.3): Stale lock detection.
|
|
186. **V2I-27** (§3.4): AirSDB multi-language static analysis.
|
|
187. **V2I-28** (§3.5.1): AirDbg workflow enforcement — 7 mandatory steps.
|
|
188. **V2I-29** (§3.5.2): Fix rollback — pre_fix_snapshot.
|
|
189. **V2I-30** (§3.5.3): Evidence-first gate.
|
|
190. **V2I-31** (§3.6.1): AirXDB DRM/KMS native screenshot.
|
|
191. **V2I-32** (§3.6.2): AirXDB headless CI XvfbCapture.
|
|
192. **V2I-33** (§3.7.1): AirDep deployment plugin.
|
|
193. **V2I-34** (§3.7.2): AirTst test runner plugin.
|
|
194. **V2I-35** (§3.7.3): AirSec security scan plugin.
|
|
195. **V2I-36** (§3.7.4): AirRvr requirements reviewer plugin.
|
|
196. **V2I-37** (§3.7.4): Code-to-Design consistency review (mandatory line-level comparison every review).
|
|
197. **V2I-38** (§3.7.4): AirRvr AirEng integration — verdict=pass/conditional-pass/fail.
|
|
198. **V2I-39** (§3.7.4): Event index layer — EventLog as structured JSONL timeline.
|
|
199. **V2I-40** (§3.8): air_runtime module reorganization — io.py, lock.py, utils.py, events.py, task_graph.py, etc.
|
|
|
|
---
|
|
|
|
## V2 Design Goals, Invariants, KPIs
|
|
|
|
### 来源: airplanV2-Qwen3.7-Max设计.md §2, §7
|
|
|
|
### V2 Goals
|
|
200. Reliability — state writes not lost, concurrent ops race-free, self-healing after crash.
|
|
201. Observability — all engine operations traceable, metrics exportable.
|
|
202. Intelligence — evidence gating perceives task type, polling adaptive.
|
|
203. Scale — support 100+ tasks, 5+ parallel Workers.
|
|
|
|
### V2 Invariants
|
|
204. INV-1: Artifact-driven communication through AirPlan/ files; V2 adds event index layer.
|
|
205. INV-2: Context isolation (fork_context=false); V2 adds selective context inheritance.
|
|
206. INV-3: Architecture sync mandatory — cannot DONE without updating architecture docs.
|
|
207. INV-4: Evidence before repair — screenshot/packet-capture/static-analysis first.
|
|
208. INV-5: Closed-loop auto-repair — execute→fail→debug→fix→re-execute.
|
|
|
|
### V2 KPIs (26个)
|
|
209. AirXDB false positive: V1 ~60% → V2 <5%
|
|
210. State file corruption: V1 known → V2 0%
|
|
211. Deployment consistency incidents: V1 1 critical → V2 0
|
|
212. Hollow fix cycles: V1 11+ → V2 0
|
|
213. Code duplication: V1 5 copies → V2 1 per function
|
|
214. Test coverage: V1 0% → V2 core >80%
|
|
215. AirArc plan mode hijack: V1 frequent → V2 0
|
|
216. AirArc skip requirements: V1 every launch → V2 0
|
|
217. AirEng non-Chinese output: V1 frequent → V2 0
|
|
218. AirDo skips AirDbg: V1 frequent → V2 0
|
|
219. AirDbg modifies code without evidence: V1 frequent → V2 0
|
|
220. Boundary without test coverage: V1 all → V2 100%
|
|
221. Final review missing high-risk: V1 none → V2 100%
|
|
222. UI tasks without Skill: V1 all → V2 100%
|
|
223. ADR change old code residue: V1 none → V2 0 (cascade+git revert)
|
|
224. Dispatch→Worker broken: V1 Agent stops → V2 0 (spawn_workers + instruction ops)
|
|
225. Post-merge duplicate dispatch: V1 redispatched → V2 0 (task-graph.json sync)
|
|
|
|
---
|
|
|
|
## V2 Phase Plan
|
|
|
|
### 来源: airplanV2-Qwen3.7-Max设计.md §4
|
|
|
|
226. **V2-Phase1** (P0 fixes): atomic I/O, file locks, utils dedup, EvidenceGatePolicy, deploy verify, hardcoded paths, child timeouts, injection protection, exception handling, Arc plan-mode blocking, Eng Chinese+autonomous, Eng polling, Do→Dbg forced routing, installer path fix, Arc requirements gate, Dbg evidence-first gate, spdlog standard, Eng boundary, boundary tests+highRiskAudit, frontend-design Skill, dispatch bridge, merge TaskGraph sync.
|
|
|
|
227. **V2-Phase2** (Engine enhancement): AdaptivePoller, Worker timeout+resource, merge transactionization, AGENTS.md dedup, EventLog, todo column derivation, configurable concurrency, state.json cap, TaskGraph+PlanDelta, region conflict+worktree, ADR cascading invalidation.
|
|
|
|
228. **V2-Phase3** (New plugins): AirDep, AirTst, AirSDB multi-lang, AirXDB kmsgrab+xvfb, AirDbg step tracking+rollback, AirRvr, AirSec.
|
|
|
|
229. **V2-Phase4** (Scale): Conflict detection O(n log n), todo.md cache, compression validation, token estimation, stale lock, AirArc incremental replanning, cross-project ops template.
|
|
|
|
230. **V2-Phase5** (Test coverage): todo_parser, review, doc_sync, contracts, engine, io, lock, evidence_gate, task_graph, worktree.
|
|
|
|
---
|
|
|
|
## 总结
|
|
|
|
### 设计文档统计
|
|
|
|
| 类别 | 数量 |
|
|
|------|------|
|
|
| FR | 21 + 7子要求 |
|
|
| NFR | 8 |
|
|
| AC | 13 |
|
|
| CT | 16 |
|
|
| RB | 6 |
|
|
| **PV (V1插件原型)** | **8** |
|
|
| AP (含INV) | 194 |
|
|
| DF (P0-P3) | 33 |
|
|
| V2I | 40 |
|
|
| V2 Goals/Invariants/KPIs | 35 |
|
|
| Phase items | 5 |
|
|
| **总计** | **391** |
|
|
|
|
### 架构核心原则
|
|
|
|
**Agent 存在的目的是扩展插件的能力边界。插件代表的工作流才是产品核心。**
|
|
|
|
AirCoding V1.0.0 Alpha 不是从零开发的新产品,而是将 8 个已验证的 Python/Claude Code Skill 插件移植到 TypeScript/Bun/SQLite 运行时。Agent (MainAgent/Scheduler/Worker) 是基础设施底座,8个插件工作流(AirArc/AirEng/AirDo/AirDbg/AirXDB/AirNDB/AirSDB/AirContext)才是交付给用户的价值。
|
|
|
|
### V1插件 → AirCoding 移植完整度 (8个核心工作流)
|
|
|
|
| V1插件 | AirCoding模块 | 工作流可运行? | 缺失 |
|
|
|--------|--------------|-------------|------|
|
|
| AirArc | ArchitectureDesigner | ❌ | 正则替代LLM, 无三步流程, 无PlanMode阻断 |
|
|
| AirEng | Scheduler | ❌ | 基础调度可跑, 无级联保护/自主决策/硬编码轮询 |
|
|
| AirDo | ExecutorRole | ⚠️ | 简单任务可跑, 不强制调AirDbg |
|
|
| AirDbg | DebuggerRole | ❌ | 从未触发, 7步工作流仅在提示词中 |
|
|
| AirXDB | gui.screenshot | ❌ | 仅ImageMagick, 无headless/diff |
|
|
| AirNDB | network.capture | ⚠️ | 仅tcpdump封装, 不产artifact |
|
|
| AirSDB | toolchain-cpp | ❌ | 仅cppcheck注册, 无build管道 |
|
|
| AirContext | ContextAssembler+Compactor | ⚠️ | 基础可组装, CompactorRole未运行 |
|
|
| **总体** | — | **0/8 可交付** | **8/8 需要工作流级别的移植** |
|
|
|
|
### 产品差距 — V1已验证能力丢失
|
|
|
|
407h的产出集中在了基础设施层(EventStore/Scheduler/ToolRegistry/SQLite),但8个V1已生产验证的插件工作流没有一个被完整移植。原因是开发从未以"插件工作流逐条移植"为目标,而是在造一个通用的Agent运行时——然后假设插件工作流"自然会跑在上面"。
|
|
|
|
**正确的开发顺序**: 先移植插件工作流(AirArc→ArchitectureDesigner, AirEng→Scheduler, AirDo→ExecutorRole...),每移植一个就端到端验证一个。基础设施随工作流需求演进,而非反过来先造全套基础设施再填工作流。
|
|
|
|
**核心结论**: 当前AirCoding产品不可发布。0/8 V1插件工作流可运行。397h的产出是一个Agent基础设施demo,不是符合6份设计文档391条要求的V1.0.0 Alpha产品。
|