AirCoding/AirPlan/docs/spec/AirPlanV2/skills/airplan/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
airplan	AirPlan V2 — 统一制品驱动开发调度器。单一插件整合规划(arc)、执行(do)、调试(dbg)、GUI验证(xdb)、静态分析(sdb)、网络调试(ndb)、部署(dep)、测试(tst)、安全扫描(sec)、需求审查(rvr)。L1代码级保障：不依赖LLM自觉。	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

使用示例

# 架构规划
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