# AirPlan-Para V1.0.0：面向 CTO 与架构负责人的 AI 工程治理参考稿

## 一句话定位

AirPlan-Para V1.0.0 是一套面向 Claude Code / Codex 本地工作流的 AI 工程治理框架。它已经把规划、调度、执行、调试、GUI 证据、网络证据、静态分析和长会话恢复固化为本地插件体系，用来解决 AI 辅助开发在真实项目中的稳定性和可追溯性问题。其中 aireng 作为公共调度层，多数时候处于非占用状态，开发者可以随时介入交流、补充约束或更正方向；同时支持并行派发多个隔离 worker，将串行等待变为并发推进，大幅压缩交付周期。

## 它解决的不是“能不能写代码”，而是“能不能稳定交付”

多数 coding agent 的问题不在于完全不会改代码，而在于工程行为不稳定：

- 新会话无法稳定继承历史上下文
- 任务状态只存在聊天记录中，无法断点续作
- 规划、执行、调试之间缺少统一的工作流契约
- GUI 验证容易把进程存活误判为通过
- 网络问题缺少 packet-level evidence
- C/C++ 项目缺少静态分析质量门
- 长会话 compact 后上下文语义容易漂移
- 多个子任务并行时容易出现上下文串扰或结果文件误读
- 调度过程像一个黑盒，开发者难以在任务执行中即时介入调整方向
- 串行执行模式下，独立子任务无法并发推进，整体交付周期被线性拉长

AirPlan-Para 当前版本的价值，在于把这些问题分别落到明确的插件职责、项目文件和运行时状态里。

## 当前版本的真实套件边界

AirPlan-Para 当前是 **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`

其中：

- 前 7 个插件构成围绕 `AirPlan/` 工作流根的规划-调度-执行-调试-证据链
- `aircontext` 负责同一套件中的上下文压缩与自动恢复层

## 当前版本已经实现的核心能力

### 1. 结构化项目上下文

系统围绕 `AirPlan/` 工作流根运行，并维护以下关键资产：

- `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/`

其中 `airarc` 与 `aireng` 已经支持首次启动时自动补齐缺失的 `AirPlan/` bootstrap 工件；`aircontext` 则在需要时维护 `AirPlan/AirContext/` 中的压缩规则、状态与 snapshots。

### 2. 规划与并发评审

`airarc` 当前已经实现：

- architecture-first planning
- `plan.md` / `todo.md` 驱动的执行协议输出
- post-plan parallel review
- dependency edges、parallel groups、shared write-set conflicts、serialization points 输出
- 供调度层优先读取的 execution plan 工件

### 3. 受控调度与结果合并

`aireng` 是整个套件的公共调度层，其设计有两个关键优势，直接区别于常见的单线程 agent 执行模式：

**随时可介入的调度层。** `aireng` 在派发 worker 后多数时候处于非占用状态——它不需要像 worker 一样持续消耗上下文窗口去执行具体任务。这意味着开发者在任务执行期间可以随时与 aireng 交流：补充遗漏信息、调整执行约束、重新排定优先级，或是在发现方向偏差时立即介入更正。调度不是一个黑盒，而是一个开放的协作节点。

**并行推进替代串行等待。** `aireng` 按 bounded concurrency 策略将独立子任务并行派发给多个隔离的 `airdo` worker。不再是“做完一个再看下一个”，而是同一波次内多个 worker 并发执行，互不阻塞。对于有多个独立模块、多组件并行开发的项目，这种模式大幅压缩了端到端交付时间。

在此基础上，`aireng` 当前已经实现：

- 读取 `airarc` execution artifacts
- 生成 dispatch manifest
- 按 bounded concurrency 调度多个隔离 `airdo` worker
- 使用任务级 handoff 保持上下文隔离
- 合并结构化 worker result
- 自动准备 repair dispatch，并维护 repair queue
- 在 merge 过程中同步 `plan.md`、`todo.md`、ADR 和 C4 文档

同时，`aireng` 已经明确使用 `worker-state.json` 中的 `resultPath` 作为 canonical finalized result locator，避免把任务目录里的模板 `result.json` 误当成最终结果。

### 4. 单任务执行与 finalize 完整性保护

`airdo` 当前已经实现：

- 单任务 scoped execution
- task-local brief 与 subagent handoff
- 结构化 `result.json`
- finalize 后写入 `AirPlan/state/airdo/results/<task-id>.json`
- `worker-state.json` 记录 canonical result path
- GUI 任务自动衔接 `airxdb`
- blocked 或 failed validation 自动衔接 `airdbg`
- active repair brief 下继续执行而不是停在中间状态

当前运行时还带有 finalize guard：

- untouched 默认模板不能直接 finalize
- `done` 结果不能是逻辑空载荷
- `done` 结果至少要带上变更、验证、证据或文档更新之一
- 无真实 blocker 时，worker 默认继续执行到 finalize，而不是停在“准备实施”或泛化进度汇报

### 5. Debug-first 维修闭环

`airdbg` 当前已经实现 debug-first repair workflow：

- reproduce -> evidence -> RCA -> minimal fix -> verification
- GUI 相关问题必须引入 `airxdb` 或等效 GUI/屏幕证据
- 网络问题可调用 `airndb`
- C/C++ 静态分析问题可调用 `airsdb`
- 持续维护 `AGENTS.md`、ADR、C4 module 和 `debug-log.md`

### 6. GUI / 网络 / 静态分析证据层

AirPlan-Para 当前已交付 3 个专门的证据插件：

- `airxdb`
  - Midscene-based GUI 调试
  - 截图证据
  - Computer MCP smoke test
  - model-family gating
  - 远程设备截图 helper
  - Windows 截图资产修复

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

- `airsdb`
  - 本机与远程 cppcheck
  - `--check-level=exhaustive`
  - XML / JSON 报告
  - `staticanalysis.md` AI-readable 摘要

### 7. 长会话压缩与自动恢复层

`aircontext` 当前实现的是同一套件里的 session continuity layer：

- 通过 `aircontext` wrapper 启动 Claude Code
- 在 `SessionStart`、`UserPromptSubmit`、`PostToolUse`、`PreCompact` 上接入 hook
- 基于阈值和冷却时间决定何时 compact
- 调用外部 OpenAI-compatible LLM 按规则压缩当前活跃链
- 把摘要与 continuation prompt 写回 session JSONL
- 自动执行 `claude --resume <session-id>` 继续长任务
- 在项目内维护 `AirPlan/AirContext/`

## 管理层视角的价值

从 CTO 或架构负责人角度看，AirPlan-Para 的价值不在“多一个插件”，而在于它已经把 AI 工程中的关键风险做了制度化约束：

- 用项目文件代替临时聊天上下文
- 用规划工件约束后续调度
- 用隔离 worker 替代大上下文单线程执行
- 用结构化 result 和 worker-state 约束交付结果
- 用 GUI / 网络 / 静态分析证据降低误判
- 用 session compaction policy 降低长会话语义漂移
- 用 repair queue 和可恢复状态提升中断后的连续性
- 用非占用式调度层保持开发者对执行过程的可见性与即时应变能力
- 用隔离并行执行替代串行等待，以并发换交付速度

## 当前交付清单

### 插件清单（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`

### 部署入口

- `AirPlan-Para.zip`
- `install_to_home.ps1`
- `install_to_home.cmd`
- `init_project_airplan.ps1`

## 边界说明

当前插件体系已经明确支持：

- 多会话上下文恢复
- 任务级 SubAgent 隔离执行
- 受控并发调度
- GUI / 网络 / C/C++ 证据驱动验证
- 调试与修复闭环
- 规则驱动 compact 与自动 resume

当前插件体系不应被宣传为：

- 容器级 runtime sandbox
- 完整的企业 SaaS 平台
- 面向多个账号的 broker / relay 调度系统
- 已实现的 file lock / document lock runtime

## 结论

AirPlan-Para V1.0.0 已经不是“若干 AI 插件的集合”，而是一套具备规划、调度、执行、调试、证据和恢复能力的本地 AI 工程治理框架。其中 aireng 的独特价值在于：既通过并行调度把交付效率从串行约束中释放出来，又以非占用式的设计让开发者始终可以介入协作——调度不是黑盒，效率不以失控为代价。

它解决的核心问题，不是让 AI 开始写代码，而是让 AI 在真实项目里更稳定、更快速、更可协作地持续交付。