admin/AirCoding
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
AircOding
AirCoding/AirPlan/docs/analysis/full-requirements-audit.md
AirCoding ae44be31d5 chore: push all design docs, V2 plan specs, and current working state 
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>
2026-06-12 17:12:29 +08:00

34 KiB
Executable File
Raw Permalink Blame History

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

  1. NFR-001 (requirements.md §4): Local-First Operation — 项目状态/制品/日志/调试知识保留在本地,除非用户显式导出/分享/上传。

  2. NFR-002 (requirements.md §4): Recoverability — 从进程/session重启恢复:读取SQLite状态,检测丢失agents,保留workspaces,重建Scheduler队列。

  3. NFR-003 (requirements.md §4): Extensibility — 通过toolchain-*包和能力清单添加语言/工具链支持。

  4. NFR-004 (requirements.md §4): Provider Flexibility — 内部契约在Anthropic/OpenAI/OpenRouter/ollama/兼容端点间保持稳定。

  5. NFR-005 (requirements.md §4): UI Responsiveness — Main Agent和TUI在后台Worker运行时保持响应。

  6. NFR-006 (requirements.md §4): Evidence-Based Completion — 任务未获得build/test/debug/review证据或显式skipped-gate报告前不得标记完成。

  7. NFR-007 (requirements.md §4): Linux-First Platform Support — Linux x86_64 tier1, arm64/WSL2 tier2, macOS实验, Windows native post-MVP/实验。

  8. NFR-008 (requirements.md §4): Security Boundary Preservation — LLM输出/工具结果/插件/外部内容在被运行时契约和策略验证前为不可信数据。

AC (Acceptance Criteria) — 13条

来源: requirements.md §6

  1. AC-01: CLI starts and initializes/opens a project .air/ tree.
  2. AC-02: Session DB schema initializes and persists messages/events/tasks/tool runs/artifacts.
  3. AC-03: EventStore transactionally applies core durable events to domain tables.
  4. AC-04: ProjectionStore hydrates and updates a usable TUI/HUD view.
  5. AC-05: Scheduler dispatches worker child processes via NDJSON IPC, supports tool calls, receives WorkerResult.
  6. AC-06: ToolRegistry executes filesystem/shell/git/artifact/context/doctor/C++/debug/GUI/network tools through PermissionEngine.
  7. AC-07: C++ workflow can detect, configure, build, statically analyze, test, debug, fix, review, re-verify a fixture project.
  8. AC-08: Failed build/test/debug commands produce diagnostics/artifacts/evidence refs and can trigger Debugger repair.
  9. AC-09: ContextAssembler produces Anthropic canonical messages with omissions where needed.
  10. AC-10: Provider adapter path can perform model calls under capability validation and conversion reporting.
  11. AC-11: Capability manifests can be loaded, validated, enabled, registered as namespaced tools.
  12. AC-12: Doctor reports platform/provider/toolchain/capability/display/network status and supports permissioned fix mode.
  13. AC-13: Release gate commands are documented and runnable on tier-1 Linux.

CT (Constraints) — 16条

来源: requirements.md §5 + baselineV1.md §3-§5

  1. CT-01 (requirements.md §5): Runtime: TypeScript on Bun.
  2. CT-02 (requirements.md §5): Monorepo: Bun workspaces + Turborepo.
  3. CT-03 (requirements.md §5): TUI: OpenTUI/Solid.
  4. CT-04 (requirements.md §5): IPC: NDJSON over stdio.
  5. CT-05 (requirements.md §5): DB: SQLite per session with WAL/NORMAL/foreign_keys OFF.
  6. CT-06 (requirements.md §5): Internal message format: Anthropic canonical content blocks.
  7. CT-07 (requirements.md §5): C++ is first deep toolchain; runtime remains language-agnostic.
  8. CT-08 (requirements.md §5): Python is subprocess-only helper layer, not core runtime.
  9. CT-09 (requirements.md §5): Early distribution uses binary tarball, not public package channels.
  10. CT-10 (requirements.md §5): Architecture docs and workflow state live under AirPlan/.
  11. CT-11 (baselineV1 §3-§4): Monorepo packages (Alpha) — contracts, cli, tui, runtime, llm, toolchain-cpp.
  12. 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.
  13. CT-13 (baselineV1 §5): Global user directory — ~/.air/.
  14. CT-14 (baselineV1 §5): project_id is stable UUID in .air/shared/project.json, not derived from absolute path.
  15. CT-15 (baselineV1 §5): .gitignore: .air/local/.
  16. CT-16 (baselineV1 + solution-arch): All side effects must pass through ToolRegistry and PermissionEngine.

RB (Reference Baselines) — 6条

来源: baselineV1.md §2

  1. 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.

  2. 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.

  3. 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.

  4. RB-04 (baselineV1 §2): OpenAI Codex — Reference for shell/patch/test direct execution loop, coding sandbox, tool orchestration, MCP implementation ideas.

  5. RB-05 (baselineV1 §2): Anthropic Claude Skills — Reference for SKILL.md structure/frontmatter, skill directory layout (scripts/references/assets), reusable workflow packaging.

  6. 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)

  1. AP-01: AirCoding is a self-owned AI coding agent/runtime, not a Claude Code plugin wrapper.
  2. AP-02: Runtime is language-agnostic; C++ is first deep language profile.
  3. 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)

  1. AP-45: Execution quality follows Claude Code — read-before-edit, exact, conservative, small, verified before completion.
  2. AP-46: OpenCode is UI/runtime reference, not business-state dependency.
  3. AP-47: Project-local source of truth under .air/.
  4. AP-48: Events drive live behavior; SQLite drives recovery.
  5. AP-49: Workers are isolated child processes over NDJSON IPC.
  6. AP-50: Main Agent remains responsive; background work delegated to Scheduler.
  7. AP-51: Architecture changes are explicit — implementation-level continues silently.
  8. AP-52: Tool/capability boundaries are permissioned through ToolRegistry+PermissionEngine.
  9. AP-53: Provider boundary isolated — internal Anthropic canonical; adapters convert at boundary.
  10. AP-54: Evidence first-class — build/test/debug/review outputs become artifacts/evidence before completion.

容器职责 (solution-architecture §4)

  1. AP-55: CLI: command entrypoint, startup, Doctor, project discovery, TUI/runtime bootstrap.
  2. AP-56: TUI/HUD: consumes ProjectionStore only, no SQLite/EventBus queries.
  3. AP-57: Runtime: MainAgent, ArchitectureDesigner, Scheduler, child process mgmt, EventBus/EventStore, SessionStore, ToolRegistry, PermissionEngine, CapabilityRegistry, ContextAssembler, ArtifactStore, EvidenceStore.
  4. AP-58: LLM: provider config, adapters, Anthropic canonical handling, conversion, capability matrix.
  5. AP-59: Toolchain C++: project detection, CMake, Ninja/Make, CTest, cppcheck, clangd, diagnostic parsing.
  6. AP-60: Contracts: compileable shared TS interfaces, no domain implementation deps.

禁止路径 (system-overview §5)

  1. 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)

  1. AP-71: Startup: CLI→detect→load→open/init .air→read-only Doctor→open session DB→hydrate ProjectionStore→start TUI/Main Agent.
  2. 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.
  3. AP-73: Requirement change: requirement.changed→Scheduler pause→Architecture Designer assess→silent continue or confirm/replan.
  4. 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)

  1. AP-69: SQLite: WAL/NORMAL/foreign_keys OFF.
  2. AP-88: Durable event insert + domain update in same SQLite transaction.
  3. AP-91: Event flow: Producer→EventIngestor→validate→durable: EventStore transaction+projection+EventBus publish; ephemeral: EventBus publish.

安全 (solution-architecture §10, system-overview §12)

  1. 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.
  2. AP-104: Permission evaluation order: tool capability → permission profile → TaskSpec scope → path/command/network risk → credential/system-sensitive → user prompt.
  3. AP-105: Permission actions: allow, deny, ask_user, block, refuse, announce_then_run.
  4. 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.
  5. 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)

  1. AP-109: Compaction: ContextAssembler may request; Scheduler creates compact task; Compactor snapshots messages; summary.created; original messages preserved.
  2. AP-158: ContextAssembler assembles Anthropic-canonical context; fits to token_budget; reports omissions; sets compaction_requested if budget cannot fit required layers.
  3. 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)

  1. AP-148: WorkerManager spawn starts Bun child process then handshake; WorkerProcess owns NDJSON pipe.
  2. AP-150: Worker roles: ExecutorRole (scoped write), ReviewerRole (read-only), DebuggerRole (scoped write assigned), CompactorRole (summaries/artifacts only), ExperienceMinerRole (candidates/rules/skills assigned).
  3. AP-151: TaskType→WorkerRole: execute→Executor, review→Reviewer, debug→Debugger, compact→Compactor, mine_experience→ExperienceMiner, docs→Executor.
  4. AP-103: Workers never write SQLite directly; never perform side effects outside parent-mediated tools.

调度器 (system-detailed-design §7)

  1. AP-143: Scheduler states: IDLE→LOADING_GRAPH→PLANNING_WAVE→DISPATCHING→MONITORING→COLLECTING_RESULTS→MERGING→REVIEWING_WAVE→REPAIRING_OR_CONTINUING. Terminals: COMPLETED, BLOCKED, CANCELLED.
  2. AP-144: TaskGraph: get_runnable_tasks honors hard deps completed, soft deps priority, conflict/serialization block concurrent dispatch on overlapping write areas.
  3. AP-146: RetryPlanner actions: retry, retry_serial, debug, skip, block, cancel.
  4. AP-147: WorkspaceManager strategies: main (no merge), worktree (git merge/patch), isolated_copy (copy-back/patch).

可追溯性 (system-detailed-design §24)

  1. 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)

  1. INV-1: Session-DB state columns written only by event projection; no direct UPDATE from services.
  2. INV-2: Cross-DB/external writes use outbox model; EventStore.project() never opens external DBs or files.
  3. INV-3: All side effects only through tool + permission path (ToolRegistry.call → PermissionEngine.evaluate).
  4. INV-4: Import/dependency direction is one-way per allowed graph; never crossed.
  5. INV-5: EventBus is transport, never source of truth; recovery rebuilds from SQLite.

参考复用 (system-detailed-design §23)

  1. AP-185: Reference reuse modes — npm-dep (consume directly), fork/adapt (copy+adapt), pattern (reference structure), behavioral (match behavior/quality).
  2. 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.
  3. 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条)

  1. P0-1: AirXDB false positive blocking — evidence gate no task-type awareness; 11+ tasks.
  2. P0-2: Deployment verification gap — validate_for_finalize() structural-only.
  3. P0-3: Non-atomic writes — 5 _json_dump sites use direct path.write_text().
  4. P0-4: Zero concurrency control — todo.md read-modify-write race.
  5. P0-5: AirArc hijacked by plan mode.
  6. P0-6: AirEng stops to ask instead of autonomous decisions.
  7. P0-7: AirEng no child-thread status polling — relies on Agent self-discipline.
  8. P0-8: AirDo does not call AirDbg — skips debug, directly reports blocked/false-done.
  9. P0-9: Installer script path errors.
  10. P0-10: AirEng deviates from scheduling to write code.

P1 — 限制可靠性与可维护性 (14条)

  1. P1-1: Hardcoded developer paths (debug_runtime.py:130, airxdb_runtime.py:156).
  2. P1-2: _json_dump/_json_load duplicated 5 times.
  3. P1-3: _ordered_unique duplicated 4 times.
  4. P1-4: policy normalization duplicated 3 times.
  5. P1-5: merge-into-state duplicated 3 times.
  6. P1-6: marker block upsert duplicated 2 times with different interfaces.
  7. P1-7: _session_stamp format inconsistent.
  8. P1-8: todo.md column index hardcoded (doc_sync.py:154-156).
  9. P1-9: Concurrency cap hardcoded as 3 (engine.py:527).
  10. P1-10: Child processes have no timeout in airxdb/debug runtime.
  11. P1-11: task_id path injection at worker.py:59 — no ../ validation.
  12. P1-12: Marker injection risk in doc_sync.py _replace_marker_block().
  13. P1-13: Silent exception swallowing — session file corruption continue with no log.
  14. P1-14: Arc re-planning then Eng cannot connect — static todo.md table cannot absorb dynamic replanning.
  15. P1-15: Same-file non-conflicting tasks forced serial — file-level conflict detection.
  16. P1-16: AirArc skips requirements discussion, directly generates plan.
  17. P1-17: AirDbg modifies code without evidence collection.
  18. P1-18: Project lacks standardized logging (no spdlog).
  19. P1-19: No boundary tests + final review lacks high-risk checks.
  20. P1-20: UI design lacks professional Skill support.
  21. P1-21: ADR changes have no cascading invalidation mechanism.
  22. P1-22: Dispatch→Worker launch has no bridge — dispatch_worker_group() writes JSON, no Worker launch.
  23. P1-23: Dispatch instruction ambiguity — commands/eng.md intent description, not pseudocode.
  24. P1-24: Merge then TaskGraph state out of sync — merge_worker_result() doesn't update task-graph.json.

P2 — 限制规模化 (4条)

  1. P2-1: Conflict detection O(n²) — review.py combinations(active_tasks, 2).
  2. P2-2: state.json unbounded growth — mergedResults never truncated.
  3. P2-3: todo.md full re-parse on every operation.
  4. P2-4: Zero test coverage — entire air_runtime/.

P3 — 限制用户体验 (5条)

  1. P3-1: AGENTS.md bloat — AirEng sync appends without dedup.
  2. P3-2: Write-set rigidity causes cascading task chains.
  3. P3-3: Parallel Workers compete for shared hardware — no awareness.
  4. P3-4: Environment-specific fixes not persistable.
  5. P3-5: Cross-project knowledge not transferred.

V2I (V2 Improvements) — 40条

来源: airplanV2-Qwen3.7-Max设计.md §3

  1. V2I-01 (§3.1.1): air_runtime.io — atomic_json_write (tempfile+os.replace), safe_json_load.
  2. V2I-02 (§3.1.2): air_runtime.lock — FileLock based on fcntl.flock with timeout.
  3. V2I-03 (§3.1.3): air_runtime.utils — ordered_unique, session_stamp, normalize_policy, sanitize.
  4. V2I-04 (§3.2.1): EvidenceGatePolicy — task-type-aware (GUI_INDICATORS, NETWORK_INDICATORS).
  5. V2I-05 (§3.2.2): Deploy verification enforcement in WorkerResult.validate_for_finalize.
  6. V2I-06 (§3.2.3): AdaptivePoller — dynamic intervals (min 30s, max 300s).
  7. V2I-07 (§3.2.4): Worker timeout (WORKER_MAX_WALL_TIME=7200s) + resource protection.
  8. V2I-08 (§3.2.5): Merge transactionization with FileLock.
  9. V2I-09 (§3.2.6): AirArc plan mode blocking — allowed_tools: [Read, Glob, Grep]; deny_plan_mode.
  10. V2I-10 (§3.2.7): AirEng autonomous decision + Chinese lock.
  11. V2I-11 (§3.2.8): AirEng hardcoded polling loop — mandatory 5-minute cycle.
  12. V2I-12 (§3.2.8b): AirEng scheduling boundary — EXTREME_TAKEOVER only when budget exhausted + ≤5 lines.
  13. V2I-13 (§3.2.9): AirDo mandatory AirDbg routing (forced=true).
  14. V2I-14 (§3.2.10): Installer path correction — absolute paths + post_install_verify.
  15. V2I-15 (§3.2.11): Dynamic graph scheduling (TaskGraph+PlanDelta) — 已在AirCoding实现.
  16. V2I-16 (§3.2.11b): Dispatch→Worker launch bridge — spawn_workers standardized.
  17. V2I-17 (§3.2.11c): Merge→TaskGraph state sync — task-graph.json node status is authoritative.
  18. V2I-18 (§3.2.12): Worktree isolation for same-file different-region parallelism.
  19. V2I-19 (§3.2.13): AirArc requirements discussion gate — three-phase process.
  20. V2I-20 (§3.2.14): Project-level spdlog logging standard.
  21. V2I-21 (§3.2.15): Boundary test enforcement + final review high-risk audit.
  22. V2I-22 (§3.2.16): frontend-design Skill integration.
  23. V2I-23 (§3.2.17): ADR change cascading invalidation — 已在AirCoding实现方法,待生产接线.
  24. V2I-24 (§3.3.1): Compression quality validation — 已在AirCoding实现CompressionValidator.
  25. V2I-25 (§3.3.2): Token estimation improvement — AdaptiveTokenEstimator.
  26. V2I-26 (§3.3.3): Stale lock detection.
  27. V2I-27 (§3.4): AirSDB multi-language static analysis.
  28. V2I-28 (§3.5.1): AirDbg workflow enforcement — 7 mandatory steps.
  29. V2I-29 (§3.5.2): Fix rollback — pre_fix_snapshot.
  30. V2I-30 (§3.5.3): Evidence-first gate.
  31. V2I-31 (§3.6.1): AirXDB DRM/KMS native screenshot.
  32. V2I-32 (§3.6.2): AirXDB headless CI XvfbCapture.
  33. V2I-33 (§3.7.1): AirDep deployment plugin.
  34. V2I-34 (§3.7.2): AirTst test runner plugin.
  35. V2I-35 (§3.7.3): AirSec security scan plugin.
  36. V2I-36 (§3.7.4): AirRvr requirements reviewer plugin.
  37. V2I-37 (§3.7.4): Code-to-Design consistency review (mandatory line-level comparison every review).
  38. V2I-38 (§3.7.4): AirRvr AirEng integration — verdict=pass/conditional-pass/fail.
  39. V2I-39 (§3.7.4): Event index layer — EventLog as structured JSONL timeline.
  40. 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

  1. Reliability — state writes not lost, concurrent ops race-free, self-healing after crash.
  2. Observability — all engine operations traceable, metrics exportable.
  3. Intelligence — evidence gating perceives task type, polling adaptive.
  4. Scale — support 100+ tasks, 5+ parallel Workers.

V2 Invariants

  1. INV-1: Artifact-driven communication through AirPlan/ files; V2 adds event index layer.
  2. INV-2: Context isolation (fork_context=false); V2 adds selective context inheritance.
  3. INV-3: Architecture sync mandatory — cannot DONE without updating architecture docs.
  4. INV-4: Evidence before repair — screenshot/packet-capture/static-analysis first.
  5. INV-5: Closed-loop auto-repair — execute→fail→debug→fix→re-execute.

V2 KPIs (26个)

  1. AirXDB false positive: V1 ~60% → V2 <5%
  2. State file corruption: V1 known → V2 0%
  3. Deployment consistency incidents: V1 1 critical → V2 0
  4. Hollow fix cycles: V1 11+ → V2 0
  5. Code duplication: V1 5 copies → V2 1 per function
  6. Test coverage: V1 0% → V2 core >80%
  7. AirArc plan mode hijack: V1 frequent → V2 0
  8. AirArc skip requirements: V1 every launch → V2 0
  9. AirEng non-Chinese output: V1 frequent → V2 0
  10. AirDo skips AirDbg: V1 frequent → V2 0
  11. AirDbg modifies code without evidence: V1 frequent → V2 0
  12. Boundary without test coverage: V1 all → V2 100%
  13. Final review missing high-risk: V1 none → V2 100%
  14. UI tasks without Skill: V1 all → V2 100%
  15. ADR change old code residue: V1 none → V2 0 (cascade+git revert)
  16. Dispatch→Worker broken: V1 Agent stops → V2 0 (spawn_workers + instruction ops)
  17. Post-merge duplicate dispatch: V1 redispatched → V2 0 (task-graph.json sync)

V2 Phase Plan

来源: airplanV2-Qwen3.7-Max设计.md §4

  1. 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.

  2. 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.

  3. V2-Phase3 (New plugins): AirDep, AirTst, AirSDB multi-lang, AirXDB kmsgrab+xvfb, AirDbg step tracking+rollback, AirRvr, AirSec.

  4. 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.

  5. 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产品。

Reference in New Issue View Git Blame Copy Permalink