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>
287 lines
11 KiB
Markdown
Executable File
287 lines
11 KiB
Markdown
Executable File
# 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. 核心上下文资产
|
||
|
||
系统当前围绕以下上下文资产运行：
|
||
|
||
```text
|
||
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. 规划、调度与会话连续性模型
|
||
|
||
当前版本的总体模型为：
|
||
|
||
```text
|
||
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 保持对执行过程的可见与介入，同时以并行执行换取交付速度，不因治理而牺牲效率。
|