admin/AirCoding
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
AircOding
AirCoding/AirPlan/docs/spec/AirPlan-Para_V1.0.0_白皮书版_参考.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

11 KiB
Executable File
Raw Permalink Blame History

AirPlan-Para V1.0.0 白皮书参考稿

摘要

AirPlan-Para V1.0.0 是一套面向 Claude Code / Codex 本地工作流的 AI 工程插件套件。它通过 AirPlan/ 工作流根、结构化上下文资产、任务级 handoff、受控调度、结构化结果合并以及证据驱动验证，解决 AI 辅助开发中的上下文衰减、调试失稳、GUI 误判、网络不可见性与 C/C++ 静态分析缺口等问题。其调度层 aireng 采用非占用式设计，保持开发者对执行过程的全程可见与即时介入能力；同时以隔离并行派发替代串行执行，将独立子任务的交付从线性等待中解放出来。

当前真实交付应准确描述为：8 个插件构成的一体化套件。其中 airarc、aireng、airdo、airdbg、airxdb、airndb、airsdb 负责规划到证据闭环，aircontext 负责同一套件内的规则驱动压缩与自动 resume。

1. 背景问题

在长期软件工程中，AI 辅助开发通常会暴露以下结构性问题：

  • 会话级上下文不可持续继承
  • 任务状态缺少持久化载体
  • 规划、执行、调试彼此脱节
  • GUI 行为缺少可靠 test oracle
  • 网络问题缺少 packet-level evidence
  • C/C++ 风险缺少 static analysis gate
  • 多任务执行下，结果路径与最终交付产物容易混淆
  • 默认 compact 策略与当前工程目标不匹配
  • 调度执行过程缺少透明介入点，开发者难以在任务中途补充信息或纠正方向
  • 串行执行模式下独立子任务互相等待，整体周期被不必要地拉长

这些问题本质上不是单一模型能力问题，而是缺少可持久化的 canonical context、明确的 workflow contract 和运行时状态约束。

2. 系统目标

AirPlan-Para 当前版本的目标是：

  • 将项目级关键上下文外部化为文件资产
  • 让规划层输出可被调度层直接消费的执行工件
  • 用任务级 handoff 隔离执行上下文
  • 用结构化 result 和 worker-state 管理交付结果
  • 用 GUI / 网络 / 静态分析证据驱动验证
  • 用 repair queue 和 debug workflow 提升失败路径可恢复性
  • 用 aircontext 将 compact 策略外部化并在长会话后自动恢复执行
  • 让调度层保持非占用状态，使开发者可随时介入、补充信息或调整约束
  • 以隔离并行执行替代串行等待，用并发换交付速度

3. 核心上下文资产

系统当前围绕以下上下文资产运行：

AirPlan/AGENTS.md
AirPlan/plan.md
AirPlan/todo.md
AirPlan/docs/architecture/adr/
AirPlan/docs/architecture/c4/module.md
AirPlan/docs/debug/debug-log.md
AirPlan/docs/debug/gui-debug-log.md
AirPlan/docs/network/airndb-log.md
AirPlan/docs/staticanalysis.md
AirPlan/state/
AirPlan/AirContext/

这些资产分别承担：

  • 项目入口与规则
  • 执行计划与质量门
  • 任务状态账本
  • 架构决策与模块边界
  • 调试轨迹
  • GUI 调试证据
  • 网络证据
  • 静态分析证据
  • 调度与 worker 运行时状态
  • compact / resume 配置与会话快照

airarc 与 aireng 已经支持在首次启动时自动补齐缺失的 AirPlan/ bootstrap 工件；aircontext 则在使用时维护 AirPlan/AirContext/。

4. 插件架构

AirPlan-Para V1.0.0 当前包含以下 8 个插件：

  • airarc 0.3.1
  • aireng 0.6.0
  • airdo 0.5.0
  • airdbg 0.1.4
  • airxdb 0.2.2
  • airndb 0.1.2
  • airsdb 0.1.1
  • aircontext 0.1.0

4.1 AirArc

airarc 是 architecture-first planning 插件，当前实现能力包括：

  • 项目规划上下文初始化
  • plan.md / todo.md 驱动的 planning workflow
  • post-plan parallel review
  • dependency edges、parallel groups、shared write-set conflicts、serialization points 输出
  • execution plan 产物生成

4.2 AirEng

aireng 是公共调度插件，在整个套件中承担“将规划转化为执行、再将执行结果收敛为交付产物”的枢纽角色。其设计有两个核心优势：

非占用式的开放调度。 与 worker 不同，aireng 在派发任务后不持续占用上下文窗口去执行具体工作。它多数时候处于空闲可响应状态，开发者在任务执行过程中可以随时与 aireng 对话：补充遗漏的需求细节、调整某个 worker 的约束条件、重新排定剩余任务的优先级，或在发现某个 worker 方向偏差时立即要求更正。调度不是一次性的人工输入，而是一个持续的协作过程。

并行执行替代串行等待。 aireng 按 bounded concurrency 策略生成 dispatch manifest，将无依赖冲突的子任务并行派发给多个隔离的 airdo worker。同一波次内的 worker 并发推进、互不阻塞。对于包含多个独立模块、多组件并行开发的工程任务，这种模式将原本串行叠加的时间成本压缩为一轮并发周期，显著缩短端到端交付时间。

aireng 当前实现能力包括：

  • 读取 airarc execution artifacts
  • 生成 dispatch manifest
  • bounded concurrency 调度多个隔离 airdo worker
  • 合并结构化 worker result
  • repair dispatch / repair queue 准备
  • 文档同步与 merge 后收敛

4.3 AirDo

airdo 是单任务执行插件，当前实现能力包括：

  • task-local brief / handoff
  • 结构化 result.json
  • finalize 到 AirPlan/state/airdo/results/<task-id>.json
  • worker-state.json 维护 canonical result path
  • GUI 任务自动衔接 airxdb
  • blocked / failed validation 自动衔接 airdbg

4.4 AirDbg

airdbg 是 debug-first repair 插件，当前实现能力包括：

  • reproduce -> RCA -> minimal fix -> verify
  • GUI 问题强制引入 airxdb 或等效证据
  • 网络问题联动 airndb
  • C/C++ 静态分析问题联动 airsdb
  • 同步维护 AGENTS、ADR、C4、debug log

4.5 AirXDB

airxdb 是 Midscene-based GUI 调试插件，当前实现能力包括：

  • 本地与远程截图证据
  • Computer MCP smoke
  • Midscene model-family 检查
  • Windows 截图资产修复
  • GUI 调试报告生成

4.6 AirNDB

airndb 是网络抓包插件，当前实现能力包括：

  • bounded local / remote tcpdump or WinDump capture
  • Windows 首次自动下载官方 WinDump.exe
  • BPF filters
  • pcap 读取与摘要
  • 远程 SSH 抓包辅助

4.7 AirSDB

airsdb 是 C/C++ 静态分析插件，当前实现能力包括：

  • 本机与远程 cppcheck
  • --check-level=exhaustive
  • XML / JSON 报告输出
  • staticanalysis.md 摘要维护

4.8 AirContext

aircontext 是同一套件中的会话压缩与自动恢复插件，当前实现能力包括：

  • wrapper 方式启动 Claude Code
  • 在 SessionStart、UserPromptSubmit、PostToolUse、PreCompact 事件接入 hook
  • 基于阈值与 cooldown 触发外部 compactor
  • 使用 OpenAI-compatible backend 执行规则驱动压缩
  • 将摘要与 continuation prompt 追加到 session JSONL
  • 自动 claude --resume <session-id>
  • 在 AirPlan/AirContext/ 下维护配置、活动规则、状态与 snapshots

5. 规划、调度与会话连续性模型

当前版本的总体模型为：

AirArc -> 规划与并行评审 -> Execution Plan
AirEng -> Dispatch Manifest -> Isolated AirDo Workers
AirDo  -> Structured Result -> AirEng Merge
AirDbg / AirXDB / AirNDB / AirSDB -> Evidence and Repair
AirContext -> Rule-driven compaction -> Auto resume

这套模型已经实现：

  • 规划层生成 engine-consumable execution artifacts
  • 调度层依据 parallel review 进行 bounded dispatch，以 non-blocking 方式保持开发者介入通道
  • 执行层通过 isolated handoff 保持 task-local context，同一波次内独立 worker 并行推进互不阻塞
  • merge 层以结构化结果与文档更新为准，将并发 worker 的产出收敛为一致的项目状态
  • 会话层在 compact 后自动恢复长任务上下文

6. 结果完整性机制

AirPlan-Para 当前版本已实现以下 result integrity 机制：

  • worker-state.json 作为 canonical result locator
  • finalize 后结果默认写入 AirPlan/state/airdo/results/<task-id>.json
  • untouched 默认模板不能 finalize
  • done 结果不能是逻辑空载荷
  • done 结果至少需带有变更、验证、证据或文档更新之一
  • 无真实 blocker 时，worker 默认继续执行到 finalize

这保证了系统不会把形式上的“完成”误当作真实交付完成。

7. 调试与证据模型

AirPlan-Para 当前采用 evidence-based verification：

  • GUI：airxdb
  • 网络：airndb
  • C/C++：airsdb
  • 通用调试闭环：airdbg
  • 长会话压缩与恢复：aircontext

这使得验证行为不再只依赖聊天说明，而是依赖结构化 artifact：

  • screenshot / GUI report
  • pcap / network summary
  • cppcheck XML / JSON / staticanalysis.md
  • debug log / RCA record
  • compaction snapshots / active rules / continuation chain

8. 断点恢复与可持续执行

当前版本已经实现的可恢复能力主要来自：

  • todo.md 任务状态账本
  • AirPlan/state/ 运行时状态
  • dispatch manifest
  • repair queue
  • worker-state
  • canonical result path
  • AirPlan/AirContext/state.json
  • AirPlan/AirContext/snapshots/

因此，系统已经支持：

  • 会话中断后恢复任务状态
  • worker finalize 后准确定位结果产物
  • blocked 结果进入 repair 路径并继续收敛
  • compact 后自动恢复长会话工作流

9. 部署与安装边界

默认部署包负责：

  • 安装 Air 工作流插件、skills 与 shared runtime
  • 提供 install_to_home.ps1 / init_project_airplan.ps1
  • 自动 bootstrap AirPlan/ 工作流根

仓库中还包含 AirContext/ 目录，作为同一套件中的 context continuity 插件实现与分发目录。使用时通过 aircontext wrapper 启动 Claude Code，并在项目内创建和维护 AirPlan/AirContext/。

仓库中的 AirContextServer/ 可视为相关变体或附带目录，不属于当前主工作流介绍口径的核心部分。

10. 边界说明

AirPlan-Para 当前版本应被准确描述为：

  • 本地 AI 工程治理框架
  • 规划、调度、执行、调试与证据插件体系
  • 结构化 project memory + task runtime state + compact/resume layer 组合

不应超前描述为：

  • 已实现 file lock / document lock runtime
  • 已实现多账号 relay / broker 调度平台
  • 已实现容器化隔离执行 fabric

11. 结论

AirPlan-Para V1.0.0 当前已经把 AI 辅助开发中的核心工程问题拆解为可运行插件和文件化上下文体系，并在以下层面完成了工程化落地：

  • planning
  • scheduling
  • execution
  • debugging
  • GUI evidence
  • network evidence
  • static analysis
  • resumable workflow
  • controllable compaction and auto resume

它的核心贡献，是把 AI 从“依赖对话记忆的临时助手”推进为“围绕明确上下文资产、运行时状态和受控压缩机制工作的工程参与者”——并且在这个过程中，开发者始终可以通过 aireng 保持对执行过程的可见与介入，同时以并行执行换取交付速度，不因治理而牺牲效率。

Reference in New Issue View Git Blame Copy Permalink