AirPlan V2 initial release — unified scheduler with 12 sub-modes
Merges 8 V1 plugins into 1 unified plugin, adds 4 new components (dep, tst, sec, rvr). 12 sub-modes: arc, eng, do, dbg, xdb, sdb, ndb, ctx, dep, tst, sec, rvr. L1 code-level guarantees: atomic writes, file locks, evidence gating, forced debug routing, 3-phase arc gate, evidence-first debug gate, Chinese language lock, scheduler boundary. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
AirPlan Team
159
skills/airplan/SKILL.md
Normal file
159
skills/airplan/SKILL.md
Normal file
@@ -0,0 +1,159 @@
|
||||
---
|
||||
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 |
|
||||
138
skills/airplan/airplan/SKILL.md
Normal file
138
skills/airplan/airplan/SKILL.md
Normal file
@@ -0,0 +1,138 @@
|
||||
---
|
||||
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 的修复预算机制自动驱动。
|
||||
|
||||
## 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()` 防止路径注入
|
||||
|
||||
## 使用示例
|
||||
|
||||
```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 |
|
||||
Reference in New Issue
Block a user