AirPlan-V2/skills/airplan/SKILL.md

---
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 审查时检查日志完备性。

## 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

## 使用示例

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