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>

AirPlan/docs/analysis/requirements-audit-report.md

@@ -0,0 +1,347 @@
+# AirCoding V1.0.0 Alpha — 完整需求清单与差距报告
+
+**生成日期**: 2026-06-11
+**状态**: Fable5 主模型终审 + deepseek-v4-pro 全文提取
+**来源文档**:
+1. `requirements.md` — 21条FR + 8条NFR + 13条AC + 10条CT
+2. `airplanV2-Qwen3.7-Max设计.md` — 25个P0-P3缺陷 + 40个V2改进 + 26个KPI
+3. `baselineV1.md` — 5个参考项目基准 + 44条架构原则
+4. `solution-architecture.md` — 10项架构原则 + 6个容器 + 4个控制流 + 安全模型
+5. `system-overview-design.md` — 18节系统概览设计
+6. `system-detailed-design.md` — 24节详细类方法设计 + 序列 + 状态机 + 可追溯矩阵
+
+---
+
+## 一、参考项目基准 (RB-01 ~ RB-06)
+
+| ID | 参考项目 | 要求复用的内容 |
+|----|----------|---------------|
+| RB-01 | **Claude Code CLI** | 执行层质量基准: 精确编辑、读后编辑、小块补丁、不重构无关代码、验证后完成、证据闭环、TAOR/TORI反馈循环 |
+| RB-02 | **OpenCode** | TUI视觉风格/交互布局、运行时分层、Session/事件/同步概念、Provider/模型抽象、插件/SDK思路。**复用OpenTUI原语,不复用SDK/sync/session业务逻辑** |
+| RB-03 | **Hermes Agent** | 经验挖掘、Nudge Engine间隔触发学习、Curator守护进程、Skill自修复、SKILL.md格式、FTS检索 |
+| RB-04 | **OpenAI Codex** | Shell/patch/test直接执行循环、编码沙箱、工具编排、MCP实现思路 |
+| RB-05 | **Anthropic Skills** | SKILL.md结构/前置元数据、技能目录布局(scripts/references/assets)、可复用工作流打包 |
+| RB-06 | **asciinema/Atuin/claude-hud** | PTY捕获和终端回放、命令元数据/历史索引、HUD/状态栏布局 |
+
+---
+
+## 二、功能需求 (FR-001 ~ FR-020 + FR-007.5)
+
+### FR-001 CLI启动与项目初始化
+从CLI入口启动,检测/打开项目,需要时初始化`.air/`,加载资源/配置,运行只读Doctor,打开session。
+
+### FR-002 项目本地状态
+`.air/shared/`(可共享配置/规则/计划) + `.air/local/`(私有sessions/artifacts/workspaces/backups/local DBs)
+
+### FR-003 会话持久化
+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
+
+### FR-004 事件驱动运行时
+发布RuntimeEvents用于实时行为,持久事件与域表更新在同一个事务中
+
+### FR-005 主代理对话
+面向用户的Main Agent: 接收请求、适当直接回答、分类工作、显示进度、呈现阻断/确认
+
+### FR-006 架构设计师
+架构/接口/产品级决策路由到Architecture Designer: 更新架构制品、产生影响评估
+
+### FR-007 调度器与任务图
+调度TaskSpec: hard/soft依赖、写区冲突处理、重试预算、子Worker派发、心跳监控、合并协调、重启恢复
+
+### FR-007.5 ADR级联失效与架构变更回滚 (7条子要求)
+1. 通过TaskNode.adr_refs溯源所有依赖该ADR的任务(含已完成)
+2. 级联失效: completed→invalidated, running→终止, pending→cancelled
+3. 冻结调度(dispatch_frozen),阻止新任务派发
+4. 创建git回滚快照(rollback_ref),支持revert旧方案代码
+5. 接收ArchitectureDesigner产出的PlanDelta增量重规划
+6. apply_delta吸收新任务后解冻调度
+7. 终审时检查INVALIDATED任务的旧代码是否已清理
+
+### FR-008 独立Worker Agent
+Executor/Reviewer/Debugger/Compactor/ExperienceMiner作为独立Bun子进程,通过NDJSON IPC通信
+
+### FR-009 Claude Code级执行原语
+强制: read-before-edit, exact conservative edits, small patches, no unrelated refactors, permission checks, verification-before-completion
+
+### FR-010 ToolRegistry和内置工具
+Schema验证的工具: filesystem/shell/git/project scanning/完整C++ build/test/static-analysis/debug/GUI screenshot/network capture/artifacts/context assembly/permission requests/Doctor
+
+### FR-011 权限与安全模型
+路径/命令/网络/凭证分类;强制权限配置;保护系统敏感和凭证操作;项目外写入备份;拒绝不安全请求
+
+### FR-012 插件与能力基础
+Manifest加载/验证、启用/禁用配置、依赖声明、Doctor集成、命名空间工具注册、源/信任元数据、PermissionEngine强制。第三方注册/签名可延后,本地和内置capability打包必须可用
+
+### FR-013 Provider层
+内部使用Anthropic canonical消息,通过适配器路由provider调用,能力矩阵验证,转换报告
+
+### FR-014 上下文组装与压缩
+有序层组装prompt、适配token预算、记录遗漏、必要时copy-on-write压缩
+
+### FR-015 制品与证据管理
+temp-file→atomic rename,记录URI/path/hash/metadata,通过evidence refs链接声明
+
+### FR-016 TUI与HUD
+OpenTUI/Solid终端UI和HUD,**仅消费ProjectionStore,不查询原始DB/EventBus**
+
+### FR-017 完整C++开发流程
+项目检测→构建系统评估→CMake configure→Ninja优先/Make回退→编译器/链接器诊断解析→clangd代码智能查询→cppcheck静态分析→CTest/GoogleTest执行→debug运行/日志解析→失败诊断→范围修复→审查→证据支持验证
+
+### FR-018 Doctor
+启动时运行只读Doctor;报告环境/能力问题;在权限策略下支持修复模式
+
+### FR-019 日志与诊断
+可读`air.log`,加密`air.developer.log`,默认7天保留
+
+### FR-020 发布门禁
+定义tier-1 Linux发布门禁: 单元测试、集成fixture重放、真实LLM E2E、项目初始化、C++构建/测试流程、SQLite恢复、子IPC、TUI启动、制品/事件持久化
+
+---
+
+## 三、非功能需求 (NFR-001 ~ NFR-008)
+
+| ID | 需求 |
+|----|------|
+| NFR-001 | 本地优先: 项目状态/制品/日志/调试知识保留在本地,除非用户显式导出/分享/上传 |
+| NFR-002 | 可恢复性: 从进程/session重启恢复,读取SQLite状态,检测丢失agents,保留workspaces,重建Scheduler队列 |
+| NFR-003 | 可扩展性: 通过`toolchain-*`包和能力清单添加语言/工具链支持 |
+| NFR-004 | Provider灵活性: 内部契约在Anthropic/OpenAI/OpenRouter/ollama/兼容端点保持稳定 |
+| NFR-005 | UI响应性: Main Agent和TUI在后台Worker运行时保持响应 |
+| NFR-006 | 证据驱动完成: 任务未获得build/test/debug/review证据或显式skipped-gate报告前不得标记完成 |
+| NFR-007 | Linux优先: Linux x86_64=tier1, arm64/WSL2=tier2, macOS=实验, Windows=post-MVP |
+| NFR-008 | 安全边界保持: LLM输出、工具结果、插件、外部内容在被运行时契约和策略验证前为不可信数据 |
+
+---
+
+## 四、验收标准 (AC-01 ~ AC-13)
+
+1. CLI启动并初始化/打开项目`.air/`树
+2. Session DB schema初始化并持久化messages/events/tasks/tool runs/artifacts
+3. EventStore事务性地将核心持久事件应用到域表
+4. ProjectionStore水合并更新可用的TUI/HUD视图
+5. Scheduler通过NDJSON IPC派发Worker子进程,通过父runtime支持工具调用,接收WorkerResult
+6. ToolRegistry通过PermissionEngine执行filesystem/shell/git/artifact/context/doctor/C++/debug/GUI/network证据工具
+7. C++工作流可检测、配置、构建、静态分析、测试、调试、修复、审查、重新验证代表性fixture项目
+8. 失败的构建/测试/调试命令产生diagnostics/artifacts/evidence refs并可触发Debugger修复
+9. ContextAssembler产生Anthropic canonical消息,必要时记录遗漏
+10. Provider适配器路径可在能力验证和转换报告下执行模型调用
+11. 能力清单可加载、验证、启用并注册为命名空间工具
+12. Doctor报告平台/provider/toolchain/capability/display/network状态并支持权限修复模式
+13. 发布门禁命令在tier-1 Linux上记录并可运行
+
+---
+
+## 五、约束 (CT-01 ~ CT-16)
+
+| ID | 约束 |
+|----|------|
+| CT-01 | 运行时: TypeScript on Bun |
+| CT-02 | Monorepo: Bun workspaces + Turborepo |
+| CT-03 | TUI: `@opentui/solid`, `@opentui/core`, `@opentui/keymap` |
+| CT-04 | IPC: NDJSON over stdio |
+| CT-05 | DB: SQLite per session, WAL/NORMAL/foreign_keys OFF |
+| CT-06 | 内部消息格式: Anthropic canonical content blocks |
+| CT-07 | C++第一个深度工具链; runtime保持语言无关 |
+| CT-08 | Python仅子进程辅助层,非核心runtime |
+| CT-09 | 早期发行用binary tarball,非公共包渠道 |
+| CT-10 | 架构文档和工作流状态在`AirPlan/`下 |
+| CT-11 | Monorepo包(Alpha): contracts/cli/tui/runtime/llm/toolchain-cpp |
+| CT-12 | 依赖方向: contracts←(none); cli→tui/runtime/llm/toolchain-cpp; runtime→contracts+llm+toolchain-*; tui→contracts only; runtime禁止依赖tui |
+| CT-13 | 全局用户目录: `~/.air/` |
+| CT-14 | project_id是`.air/shared/project.json`中的稳定UUID |
+| CT-15 | `.gitignore`: `.air/local/` |
+| CT-16 | 所有副作用必须通过ToolRegistry和PermissionEngine |
+
+---
+
+## 六、架构原则完整清单 (AP-01 ~ AP-189)
+
+> 详细AP清单已由deepseek-v4-pro提取,参见`/home/airlongdian/DataDevices/AirWorkSpace/AirCoding/AirPlan/docs/analysis/full-requirements-audit.md`
+> 包含: 本节仅列关键原则概要,完整189条见审计文件。
+
+### 核心执行原则
+- AP-01: AirCoding是自有的AI编码runtime,非Claude Code插件包装器
+- AP-02: Runtime语言无关; C++第一个深度profile; 通过`toolchain-<lang>`扩展
+- AP-03: 核心循环: requirement → design → reading → planning → build → analysis → test → debug → evidence → fix → summary → mining
+- AP-45: 执行质量遵循Claude Code: 读后编辑、精确、保守、小步、验证后完成
+- AP-46: OpenCode是UI/runtime参考,非业务状态依赖
+- AP-47: 项目本地为真源: session状态/制品/备份/项目规则在`.air/`下
+- AP-48: 事件驱动活动行为; SQLite驱动恢复
+- AP-49: Worker是隔离的子进程(Executor/Reviewer/Debugger/Compactor/ExperienceMiner),通过NDJSON IPC通信
+- AP-50: Main Agent保持响应; 长运行后台工作委派给Scheduler/Worker
+- AP-51: 架构变更是显式的; 实现级变更静默继续; 接口级变更通过Architecture Designer
+- AP-52: 工具/能力边界受权限保护; 所有内置和插件工具通过ToolRegistry+PermissionEngine
+- AP-53: Provider边界隔离; 内部Anthropic canonical; 适配器在边界转换
+- AP-54: 证据是一等公民: build/test/debug/review输出在完成声明前成为制品和证据引用
+
+### 容器依赖
+- AP-55: CLI容器: 命令入口/启动/初始化/Doctor/项目发现/TUI/runtime引导
+- AP-56: TUI/HUD容器: 仅消费ProjectionStore; 不查询SQLite/EventBus; 不持有调度状态
+- AP-57: Runtime容器: MainAgent/ArchitectureDesigner/Scheduler/子进程管理/EventBus/EventStore/SessionStore/ToolRegistry/PermissionEngine/CapabilityRegistry/ContextAssembler/ArtifactStore/EvidenceStore/ProjectionStore
+- AP-58: LLM容器: Provider配置/适配器/Anthropic canonical处理/转换/能力矩阵/流式/工具调用/Token计数
+- AP-59: Toolchain C++容器: 项目检测/CMake/Ninja/CTest/cppcheck/clangd/诊断解析/证据生成
+- AP-60: Contracts容器: 可编译共享TS接口; 不依赖域实现包
+
+### 禁止路径
+- AP-85: TUI→SQLite直接查询、TUI→runtime私有服务导入、Worker→SQLite直接写入、Worker→工具外fs/shell/network、工具→无PermissionEngine副作用、能力→Doctor外依赖安装、Provider适配器→静默语义损失、仓库→调度策略、EventBus→恢复真源、runtime→TUI导入、LLM输出→直接文件/shell副作用
+
+### 事件/数据规则
+- AP-69: SQLite: WAL/NORMAL/foreign_keys=OFF
+- AP-88: 持久事件插入+域表更新在同一SQLite事务中
+- AP-91: 事件流: Producer→EventIngestor→验证→持久:EventStore事务+域投影+EventBus发布; 短暂:EventBus发布
+- AP-92: route追加只; route_text从route.join("/")派生; payload schema变更需版本递增
+- AP-137: EventStore.append事务中schema验证→EventRepository.insert→project(event,tx)→提交后EventBus.publish
+
+### 控制流
+- AP-72: 正常执行: 用户请求→Main Agent分类→直接回答或架构/任务规划→Scheduler创建/加载TaskGraph→ContextAssembler→Scheduler派发Worker→工具→PermissionEngine→WorkerResult→Scheduler重试/合并/审查→Main Agent报告
+- AP-73: 需求变更: requirement.changed事件→Scheduler暂停受影响工作→Architecture Designer评估→实现级静默继续→架构/产品级路由用户确认/重规划
+- AP-74: 恢复: 重启→打开session DB→加载运行/中断任务→检查子进程存活→发出agent.lost/task.failed或重连/恢复→保留未合并workspaces→重建Scheduler队列→水合ProjectionStore
+
+### 安全 (AP-79, AP-104~108, AP-171)
+- LLM输出在验证前不可信
+- 工具是文件系统/shell/network副作用的唯一路径
+- 符号链接通过realpath解析后分类
+- `.git/`默认保护; build目录允许项目写入
+- 项目外写入需备份; 凭证/系统敏感操作需显式确认
+- 无自动上传日志/制品/调试知识/Doctor包
+- 权限评估顺序: 工具能力声明→权限profile→TaskSpec范围→路径/命令/网络风险→凭证/系统敏感→用户提示
+- 8个路径风险类别 + 10个命令风险类别
+
+### 可追溯性
+完整189条AP及11条INV详见审计文件:
+`/home/airlongdian/DataDevices/AirWorkSpace/AirCoding/AirPlan/docs/analysis/full-requirements-audit.md`
+
+---
+
+## 七、AirPlan V2 缺陷 (DF-P0 ~ DF-P3, 共33个)
+
+### P0 — 已造成实际损失 (DF-P0-01 ~ DF-P0-10)
+1. AirXDB假阳性阻塞 — 证据门控无任务类型感知
+2. 部署验证缺口 — validate_for_finalize()只检查结构完整性
+3. **非原子写入** — 5处_json_dump直接覆盖(→ AirCoding已用ArtifactStore temp+rename修复)
+4. **零并发控制** — todo.md读改写竞态(→ AirCoding已用SQLite事务修复)
+5. AirArc被plan模式劫持
+6. AirEng停问而不自主决策
+7. AirEng无子线程状态轮询
+8. AirDo不调用AirDbg
+9. 安装器脚本路径错误
+10. AirEng偏离调度亲自写代码
+
+### P1 — 限制可靠性 (DF-P1-01 ~ DF-P1-14)
+1. 硬编码开发者路径
+2. _json_dump重复5份
+3. _ordered_unique重复4份
+4. policy normalization重复3份
+5. merge-into-state重复3份
+6. marker block upsert重复2份
+7. _session_stamp格式不一致
+8. todo.md列索引硬编码
+9. 并发度硬编码为3
+10. 子进程无超时
+11. task_id路径注入
+12. 标记注入风险
+13. 静默吞异常
+14. Arc重规划后Eng无法衔接 → **AirCoding TaskGraph+PlanDelta解决**
+
+### P2 — 限制规模化 (DF-P2-01 ~ DF-P2-04)
+1. 冲突检测O(n²)
+2. state.json无界增长
+3. todo.md全量重解析
+4. 零测试覆盖
+
+### P3 — 限制用户体验 (DF-P3-01 ~ DF-P3-05)
+1. AGENTS.md膨胀
+2. 写集刚性导致级联任务链
+3. 并行Worker抢占共享硬件
+4. 环境特定修复不可持久
+5. 跨项目知识不迁移
+
+---
+
+## 八、AirPlan V2 改进 (V2I-01 ~ V2I-40)
+
+见完整审计文件,关键项:
+- V2I-01: 统一原子I/O模块(air_runtime.io)
+- V2I-04: 任务类型感知的证据门控
+- V2I-15: **动态图调度(TaskGraph+PlanDelta) — 已在AirCoding中实现**
+- V2I-18: Worktree隔离同文件不同区域并行
+- V2I-22: frontend-design Skill集成
+- **V2I-23: ADR变更级联失效 — 已在AirCoding中实现方法,待生产接线**
+- **V2I-24: 压缩质量验证(CompressionValidator) — 已在AirCoding中实现**
+- V2I-28: AirDbg 7步工作流强制
+- V2I-30: 证据优先门控(EvidenceFirstGate)
+- V2I-37: Code-to-Design一致性审查(每行比较)
+
+---
+
+## 九、V2 KPI (26个)
+
+| KPI | V1当前 | V2目标 |
+|-----|--------|--------|
+| AirXDB假阳性率 | ~60% | <5% |
+| 状态文件损坏率 | 已知发生 | 0% |
+| 部署一致性事故 | 1次关键 | 0 |
+| 空壳修复循环 | 11+ | 0 |
+| 代码重复 | 5份_json_dump | 每函数1份 |
+| 测试覆盖率 | 0% | >80% |
+| ADR变更旧代码残留 | 无自动清理 | 0(级联失效) |
+| Dispatch→Worker断链 | Agent停止调度 | 0(spawn_workers标准化) |
+
+---
+
+## 十、当前产品差距评估
+
+### 参考项目对照
+
+| 参考项目 | 要求 | 实际 |
+|----------|------|------|
+| **Claude Code CLI** (RB-01) | 执行层质量基准: read-before-edit, exact edits, verification | ❌ 全凭提示词,代码无强制 |
+| **OpenCode** (RB-02) | TUI视觉/交互/Provider抽象, 复用OpenTUI, 不复用SDK | ❌ 47个console.log撕裂TUI, 重写了Provider |
+| **Hermes Agent** (RB-03) | 经验挖掘/Nudge/Curator/Skill自修复 | ❌ ExperienceMinerRole从未运行 |
+| **OpenAI Codex** (RB-04) | Shell/patch/test执行循环, 工具编排 | ⚠️ 工具内联不统一 |
+| **Anthropic Skills** (RB-05) | SKILL.md格式, 技能目录布局 | ⚠️ 仅capability manifest |
+| **asciinema/Atuin/claude-hud** (RB-06) | PTY/HUD/状态栏 | ❌ HUD无对话面板 |
+
+### 21条FR严格评估
+
+| FR | 状态 | 说明 |
+|----|------|------|
+| FR-001 | ⚠️ | init可跑,Doctor执行但结果不展示 |
+| FR-002 | ✅ | 目录布局正确 |
+| FR-003 | ❌ | NOT NULL/UNIQUE持续崩溃 |
+| FR-004 | ❌ | 投影缺口持续,虽有诊断脚本修复,未端到端验证 |
+| FR-005 | ❌ | 正则分类器+dispatchTask,无对话 |
+| FR-006 | ❌ | 正则判断(文件数>10),无LLM |
+| FR-007 | ❌ | RetryPlanner字段不匹配 |
+| FR-007.5 | ❌ | 方法全有,零生产调用 |
+| FR-008 | ❌ | 仅ExecutorRole实跑过 |
+| FR-009 | ❌ | 全凭提示词 |
+| FR-010 | ❌ | 定义28个工具,cpp.*/debug.*从未触发 |
+| FR-011 | ⚠️ | 已修复部分崩溃,permission.request修复 |
+| FR-012 | ❌ | 仅1个capability包 |
+| FR-013 | ❌ | 仅OpenAI兼容适配器 |
+| FR-014 | ❌ | CompactorRole从未运行 |
+| FR-015 | ⚠️ | ArtifactStore可用,evidence_refs已修复 |
+| FR-016 | ❌ | 47个console.log撕裂TUI |
+| FR-017 | ❌ | cpp.*从未端到端 |
+| FR-018 | ❌ | Doctor跑了不展示 |
+| FR-019 | ⚠️ | Logger存在,写入未验证 |
+| FR-020 | ❌ | 27/27门禁方法级,产品不可用 |
+
+### 分类
+
+- ✅ 可达: 1/21 (FR-002)
+- ⚠️ 部分可达: 3/21 (FR-001, FR-011, FR-015, FR-019)
+- ❌ 不可达: 17/21
+
+---
+
+## 文件导航
+
+- 完整审计文件(383条详细清单): `/home/airlongdian/DataDevices/AirWorkSpace/AirCoding/AirPlan/docs/analysis/full-requirements-audit.md`
+- 功能需求: `AirPlan/docs/analysis/requirements.md`
+- 架构方案: `AirPlan/docs/architecture/solution-architecture.md`
+- 基准V1: `AirPlan/docs/architecture/baselineV1.md`
+- V2设计: `/home/airlongdian/DataDevices/AirWorkSpace/air-plugins-dist/airplanV2-Qwen3.7-Max设计.md`
+- 详细设计: `AirPlan/docs/architecture/system-detailed-design.md`
+- 系统概览: `AirPlan/docs/architecture/system-overview-design.md`