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>
216 lines
8.7 KiB
Markdown
Executable File
216 lines
8.7 KiB
Markdown
Executable File
# 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 在真实项目里更稳定、更快速、更可协作地持续交付。
|