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>
201 lines
11 KiB
Markdown
Executable File
201 lines
11 KiB
Markdown
Executable File
---
|
||
name: airplan
|
||
description: AirPlan V2 — 统一制品驱动开发调度器。单一插件整合规划(arc)、执行(do)、调试(dbg)、GUI验证(xdb)、静态分析(sdb)、网络调试(ndb)、部署(dep)、测试(tst)、安全扫描(sec)、需求审查(rvr)。L1代码级保障：不依赖LLM自觉。
|
||
allowed-tools: [Read, Glob, Grep, Bash, Write, Edit]
|
||
---
|
||
|
||
# AirPlan V2
|
||
|
||
## 概述
|
||
|
||
AirPlan V2 是 V1 的 8 个独立插件（airarc, aireng, airdo, airdbg, airxdb, airsdb, airndb, aircontext）合并为 **1 个统一插件**，新增 4 个组件（airdep, airtst, airsec, airrvr），共 **12 个子模式**。
|
||
|
||
核心设计原则：
|
||
1. **制品驱动通信** — 插件间通过 AirPlan/ 文件通信
|
||
2. **上下文隔离** — Worker `fork_context=false`
|
||
3. **L1 代码级保障** — 关键逻辑不依赖 LLM 自觉，由引擎代码强制执行
|
||
|
||
## 子模式速查
|
||
|
||
| 子模式 | 角色 | 关键文件 |
|
||
|--------|------|----------|
|
||
| arc | 架构规划器 — 产出执行计划、DAG | execution-plan.json, task-graph.json |
|
||
| eng | 调度引擎 — 波次派发、监控、合并 | state/aireng/state.json |
|
||
| do | 任务执行器 — 单任务切片<E58887><E78987><EFBFBD>行 | state/airdo/tasks/{task_id}/result.json |
|
||
| dbg | 调试器 — 7 步工作流强制追踪 | state/airdbg/sessions/*.json |
|
||
| xdb | GUI 验证器 — 截图取证、DRM/KMS | state/airxdb/artifacts/ |
|
||
| sdb | 静态分析器 — 多语言分析 | state/airsdb/reports/ |
|
||
| ndb | 网络调试器 — 抓包分析 | state/airndb/captures/ |
|
||
| ctx | 上下文管理器 — 压缩、Token 估算 | state/aircontext/ |
|
||
| dep | 部署器 — SSH 远程构建 + systemd | state/airdep/sessions/ |
|
||
| tst | 测试运行器 — 统一多框架测试 | state/airtst/reports/ |
|
||
| sec | 安全扫描器 — 敏感数据检测 | state/airsec/ |
|
||
| rvr | 需求审查器 — 交付物与需求一致性 | state/airrvr/reviews/ |
|
||
|
||
## 关键不变量（INV-）
|
||
|
||
### INV-1 制品驱动通信
|
||
插件间**不直接调用**，而是通过 AirPlan/ 目录下的 JSON/MD 文件通信。状态文件是唯一真相来源。
|
||
|
||
### INV-2 上下文隔离
|
||
所有 Worker 派发使用 `fork_context=false`，确保子任务不继承父线程的完整上下文，仅传递任务相关的必要信息。
|
||
|
||
### INV-3 架构同步强制
|
||
不更新架构文档（ADR、C4、plan.md）不能标记任务为 DONE。AirEng merge 时强制检查 documentUpdates。
|
||
|
||
### INV-4 证据先于修复
|
||
GUI 任务必须先有截图/验证证据，网络任务必须先有抓包/连通性证据，代码任务必须先有静态分析/测试结果。EvidenceGatePolicy 根据任务类型自动判断需要哪种证据。
|
||
|
||
### INV-5 闭环自动修复
|
||
执行 → 失败 → 调试 → 修复 → 重执行 的闭环由 AirEng 的修复预算机制自动驱动。
|
||
|
||
### INV-6 调度器不写代码
|
||
AirEng 是调度器，不是执行器。它只做 plan/dispatch/monitor/merge/intervene/doc-sync，绝不直接实现任务代码。所有任务实现必须通过 /do 子代理（fork_context=false）完成。调度线程直接写代码是严重违规，唯一例外是 Worker 硬阻塞无法自恢复时的紧急干预，干预后必须立即回到调度模式。
|
||
|
||
### INV-7 架构器只读不写
|
||
AirArc 是纯规划器，只做分析依赖、写集冲突、产出调度计划。禁止编写代码、修改源代码文件、执行构建命令。allowed-tools 仅含 Read/Glob/Grep，不含 Write/Edit/Bash。
|
||
|
||
### INV-8 架构三阶段门控
|
||
AirArc 必须遵循三阶段流程：discussing（需求探讨）→ proposing（架构提议）→ confirmed（用户确认后）。execution-plan.json 仅在 phase=confirmed 时允许写入。
|
||
|
||
### INV-9 调试先读后写
|
||
AirDbg 修改代码前必须至少完成一项取证行为（截图/抓包/静态分析/日志分析/代码追踪/复现步骤）。未取证就修改代码是严重违规。
|
||
|
||
### INV-10 中文锁定
|
||
AirEng 必须始终使用中文与用户交流。自主决策不停下来问用户。
|
||
|
||
### INV-11 项目日志标准
|
||
所有 C++ 项目必须集成 spdlog，禁止 std::cout/qDebug/printf。AirArc 规划时强制首任务为 spdlog 集成（如未存在），AirRvr 审查时检查日志完备性。
|
||
|
||
### INV-12 边界测试强制
|
||
AirArc 规划时必须为每个模块边界自动生成测试任务：
|
||
- 接口测试任务（模块边界）
|
||
- 单元测试任务（核心逻辑）
|
||
- 标记 test_required=True
|
||
- Done When 必须包含"测试通过"
|
||
|
||
### INV-13 终审高风险审计
|
||
AirRvr 终审必须包含 highRiskAudit 报告，强制检查：
|
||
- lifecycle: 资源申请释放配对、RAII 覆盖、异步回调保证
|
||
- nullPointer: 指针使用前判空、智能指针生命周期、回调闭包指针有效性
|
||
- danglingPointer: 悬垂指针风险
|
||
- exceptionSafety: 异常<E5BC82><E5B8B8>径资源释放、异常吞没、跨模块异常传播
|
||
- concurrency: 共享状态锁保护、锁顺序（防死锁）、条件变量虚假唤醒
|
||
|
||
deliveryVerdict = block-release 时阻止 AirEng 所有后续派发。
|
||
|
||
### INV-14 界面设计 Skill 强制
|
||
AirDo 处理 UI 任务时必须使用 frontend-design Skill：
|
||
- 任务涉及 UI/前端/界面时，检测并路由
|
||
- frontend-design Skill 不存在则自动安装
|
||
- 安装失败时阻止任务执行
|
||
|
||
### INV-15 ADR 变更级联失效
|
||
架构方案变更（如 ffmpeg → gstreamer）时，基于旧 ADR 已完成的任务必须自动失效：
|
||
- TaskGraph 维护 ADR→任务溯源链（adr_refs）
|
||
- ADR 变更时级联失效所有相关任务（含已完成和下游依赖）
|
||
- 调度冻结直到 Arc 重新生成受影响部分的任务
|
||
- 自动 git revert 已合并的旧代码
|
||
- AirRvr 终审检查 INVALIDATED 任务代码是否已清理
|
||
|
||
### INV-16 弱模型安全任务描述
|
||
AirArc 产出任务时，假设 Do Worker 是**廉价模型/本地小模型**，字面理解任务无推断能力：
|
||
- **禁止歧义词**：禁止"清理"、"重构"、"优化"等宽泛动词，必须指明具体改什么文件、改什么内容
|
||
- **否定约束显式化**：任务必须写明**不做什么**（如"不删除 src/ 下现有模块文件"、"不修改 CMakeLists.txt 中已有 target"）
|
||
- **文件范围精确化**：`files_dirs` 不能写 `src/` 这种目录级范围，必须精确到具体文件
|
||
- **完成标准可验证**：`done_when` 必须能用 `grep`/`diff`/`cmake --build` 等命令客观验证，不含主观判断
|
||
|
||
## L1 代码级保障（不依赖 LLM 自觉）
|
||
|
||
以下功能由引擎代码强制执行，SKILL.md 指令仅作辅助：
|
||
|
||
1. **原子写入** — `air_runtime/io.py:atomic_json_write()` 使用 tempfile + os.replace()
|
||
2. **文件锁** — `air_runtime/lock.py:FileLock` 持有者才能读写 state.json
|
||
3. **证据门控** — `air_runtime/evidence_gate.py:EvidenceGatePolicy` 分类任务类型，强制要求对应证据
|
||
4. **强制 AirDbg 路由** — `air_runtime/modes/do_mode.py:finish_worker()` 中 blocked/failed/done无证据 时强制路由到 airdbg
|
||
5. **硬编码轮询循环** — `air_runtime/modes/eng_mode.py:monitor_engine()` 每 5 分钟检测所有 Worker 状态
|
||
6. **Worker 超时** — 超过 2 小时硬上限自动 terminate
|
||
7. **部署一致性验证** — merge 时检测 deployRequired 字段是否有对应验证证据
|
||
8. **任务 ID 校验** — `air_runtime/utils.py:sanitize_task_id()` 防止路径注入
|
||
9. **Arc 三阶段门控** — `air_runtime/modes/arc_mode.py:ArcPhaseGate` 仅 confirmed 阶段可写 execution-plan.json
|
||
10. **Dbg 先读后写门控** — `air_runtime/modes/dbg_mode.py:WorkflowViolation` fix 步骤前必须有 collectedEvidence
|
||
11. **Arc 工具白名单** — commands/arc.md allowed-tools 仅 [Read, Glob, Grep]，deny-plan-mode=true
|
||
12. **边界测试强制** — `air_runtime/modes/arc_mode.py:_inject_boundary_tests()` 为每个模块注入测试任务
|
||
13. **block-release 阻止派发** — `air_runtime/modes/eng_mode.py:dispatch_worker_group()` 检查 deliveryVerdict
|
||
14. **UI Skill 路由** — `air_runtime/modes/do_mode.py:route_ui_task()` 检测并确保 frontend-design Skill
|
||
15. **ADR 级联失效** — `air_runtime/task_graph.py:invalidate_by_adr()` ADR 变更时级联失效 + `air_runtime/modes/eng_mode.py:handle_adr_invalidation()` 调度冻结 + git revert
|
||
|
||
## 使用示例
|
||
|
||
```bash
|
||
# 架构规划
|
||
airplan --mode arc --project /path/to/project --sub enter
|
||
airplan --mode arc --project /path/to/project --sub parallel-review --todo AirPlan/todo.md
|
||
|
||
# 调度引擎
|
||
airplan --mode eng --project /path/to/project --sub enter
|
||
airplan --mode eng --project /path/to/project --sub plan --todo AirPlan/todo.md
|
||
airplan --mode eng --project /path/to/project --sub dispatch
|
||
airplan --mode eng --project /path/to/project --sub monitor
|
||
airplan --mode eng --project /path/to/project --sub merge --result /path/to/result.json
|
||
|
||
# 任务执行
|
||
airplan --mode do --project /path/to/project --task-id T-001 --sub enter
|
||
airplan --mode do --project /path/to/project --task-id T-001 --sub finish --result /path/to/result.json
|
||
|
||
# 调试
|
||
airplan --mode dbg --project /path/to/project --task-id T-001 --sub start
|
||
airplan --mode dbg --project /path/to/project --task-id T-001 --sub snapshot
|
||
|
||
# 部署
|
||
airplan --mode dep --project /path/to/project --task-id T-001 --host 192.168.1.100 --binary ./build/myapp
|
||
|
||
# 测试
|
||
airplan --mode tst --project /path/to/project --task-id T-001 --framework pytest
|
||
|
||
# 安全扫描
|
||
airplan --mode sec --project /path/to/project --task-id T-001 --scan-path ./src
|
||
|
||
# 需求审查
|
||
airplan --mode rvr --project /path/to/project --task-id T-001 --sub review
|
||
```
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
AirPlan/
|
||
├── AGENTS.md # Agent 行为规范（各子模式入口）
|
||
├── plan.md # 执行计划摘要
|
||
├── todo.md # 任务列表（人类可读）
|
||
├── docs/
|
||
│ ├── architecture/
|
||
│ │ ├── adr/ # ADR 记录
|
||
│ │ └── c4/module.md # C4 模块文档
|
||
│ ├── debug/
|
||
│ │ ├── debug-log.md # 调试日志
|
||
│ │ └── gui-debug-log.md # GUI 调试日志
|
||
│ ├── staticanalysis.md # 静态分析报告
|
||
│ └── network/ # 网络抓包
|
||
└── state/
|
||
├── airarc/reviews/ # 架构规划输出
|
||
├── aireng/ # 调度引擎状态
|
||
├── airdo/tasks/ # Worker 结果
|
||
├── airdbg/sessions/ # 调试会话
|
||
├── airxdb/artifacts/ # 截图/验证证据
|
||
├── airsdb/reports/ # 静态分析报告
|
||
├── airndb/captures/ # 网络抓包
|
||
├── aircontext/ # 上下文压缩状态
|
||
├── airdep/sessions/ # 部署记录
|
||
├── airtst/reports/ # 测试报告
|
||
├── airsec/ # 安全扫描<E689AB><E68F8F>果
|
||
└── airrvr/reviews/ # 需求审查报告
|
||
```
|
||
|
||
## 故障排查
|
||
|
||
| 症状 | 排查步骤 |
|
||
|------|----------|
|
||
| Worker 假阳性阻塞 | 检查 `state/airxdb/` 是否存在对应截图证据，确认任务类型是否被 EvidenceGatePolicy 误分类 |
|
||
| 部署后未生效 | 检查 merge 时是否包含 deploy 验证证据（remote-deploy-verify / remote-binary-md5） |
|
||
| 任务状态卡在 DISPATCHED | 运行 `airplan --mode eng --project . --sub monitor` 查看 Worker 是否超时或停滞 |
|
||
| 敏感数据泄露 | 检查 AirSec 扫描结果，查看 `state/airsec/` 是否有 finding | |