admin/AirCoding
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
ae44be31d515ab4001134d3cc415d4738251aab1
AirCoding/AirPlan/docs/analysis/requirements-audit-report.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

18 KiB
Executable File
Raw Blame History

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
Reference in New Issue View Git Blame Copy Permalink