admin/AirPlan-V2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 全部 12 个命令文件完整化 — 消除 P0/P1 操作歧义

Browse Source 
P0: 9 个存根命令文件从 11 行模板扩展为完整操作文档
- dbg: 7 步工作流表格 + 证据类型 + 子命令 + Dbg↔Do 集成路径
- ctx: 三级降级压缩 + 质量校验 + Token 估算 + 陈旧锁清理
- dep: SSH 部署流程 + MD5 校验 + systemd 管理
- tst: 5 种测试框架 + run 命令 + T-TEST 集成
- sec: advisory/blocking 双模式 + 文件/目录/Woker result 三种扫描
- rvr: 审查模式 + highRiskAudit + code-to-design + Eng merge 集成
- sdb: 6 种后端 + diff 模式 + Dbg 取证集成
- ndb: 网络抓包 + Dbg 取证集成
- xdb: kmsgrab/xvfb/fallback 三后端 + Dbg/Do GUI 验证集成

P1: 3 个有内容文件的歧义修复
- do: AirDbg 路由具体命令 + 证据采集（xdb/ndb/sdb/tst）命令
- arc: 三阶段→命令映射表 + phase 推进方式
- eng: monitor 轮询循环伪代码（Agent 无时钟概念，必须循环调 monitor）

全部命令统一使用 `python scripts/airplan.py` 路径（清除旧 $HOME/plugins 引用）

63 项功能测试全通过

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
AirLongDian
2026-06-11 15:57:12 +08:00
parent cda601a73a
commit 9ad232af38
12 changed files with 499 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
commands/arc.md
View File

@@ -23,27 +23,39 @@ AirArc is a pure architecture planner. It analyzes dependencies, write-set confl
### enter ### enter
```bash ```bash
python "$HOME/plugins/airplan/scripts/airplan.py" --mode arc --project . --sub enter python scripts/airplan.py --mode arc --project . --sub enter
``` ```
### status ### status
```bash ```bash
python "$HOME/plugins/airplan/scripts/airplan.py" --mode arc --project . --sub status python scripts/airplan.py --mode arc --project . --sub status
``` ```
### parallel-review ### parallel-review
```bash ```bash
python "$HOME/plugins/airplan/scripts/airplan.py" --mode arc --project . --sub parallel-review --todo AirPlan/todo.md python scripts/airplan.py --mode arc --project . --sub parallel-review --todo AirPlan/todo.md
``` ```
### incremental-replan ### incremental-replan
```bash ```bash
python "$HOME/plugins/airplan/scripts/airplan.py" --mode arc --project . --sub incremental-replan --todo AirPlan/todo.md python scripts/airplan.py --mode arc --project . --sub incremental-replan --todo AirPlan/todo.md
``` ```
## 三阶段 → 命令映射
ArcPhaseGate 控制 execution-plan.json 写入权限。phase 默认 `discussing`，必须推进到 `confirmed` 才能生成规划。
| 阶段 | phase 值 | 操作 |
|------|---------|------|
| 需求探讨 | `discussing` | 与用户对话讨论，不需要命令 |
| 架构确认 | `proposing` | 向用户呈现方案，等待确认 |
| 生成规划 | `confirmed` | `parallel-review` 或 `incremental-replan` |
**推进方式**：用户说"确认"/"可以"/"同意"后，`ArcPhaseGate.confirm_architecture()` 自动推进。不丢失（已修复）。
## Logging Standard ## Logging Standard
When planning C++ projects, the first task MUST be "integrate spdlog" if not already present. All generated code must use spdlog, not std::cout/qDebug/printf. When planning C++ projects, the first task MUST be "integrate spdlog" if not already present. All generated code must use spdlog, not std::cout/qDebug/printf.

62
commands/ctx.md
View File

@@ -1,11 +1,65 @@
--- ---
description: "AirPlan ctx mode" description: "AirPlan ctx mode - context manager: compression, token estimation, stale lock detection"
argument-hint: "[enter|status|...]" argument-hint: "[enter|compress|validate|estimate|status]"
allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]" allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
--- ---
# /ctx # /ctx
Run AirPlan ctx mode. AirContext 管理上下文压缩、Token 估算、陈旧锁检测。三级降级压缩策略：重试 → 换模型 → 截断。
python "$HOME/plugins/airplan/scripts/airplan.py" --mode ctx --project . [OPTIONS] ## 硬规则
1. **压缩质量校验** — 压缩后必须调用 `--sub validate` 验证关键信息（ADR 引用、TODO、文件路径）保留率 ≥70%
2. **压缩前备份** — 每次压缩自动备份原文件为 `.bak`
3. **陈旧锁清理** — 检测到锁持有进程已死则自动清理
## 三级降级压缩
1. **RETRY** — 重新压缩（换 prompt）
2. **FALLBACK_MODEL** — 换模型压缩
3. **TRUNCATE** — 放弃压缩，保留原始上下文，通知用户
## 子命令
### enter — 初始化上下文管理器
```bash
python scripts/airplan.py --mode ctx --project . --sub enter
```
### compress — 压缩上下文
```bash
python scripts/airplan.py --mode ctx --project . --sub compress
```
读取 `AirPlan/context.md`，执行三级降级压缩。emit `context.compacted` 事件。
### validate — 校验压缩质量
```bash
python scripts/airplan.py --mode ctx --project . --sub validate
```
检查压缩是否保留关键模式：文件路径、ADR-XXXX、TODO/FIXME、INV-X。返回 `{validation_ok, level, tokens}`。
### estimate — Token 估算
```bash
python scripts/airplan.py --mode ctx --project . --sub estimate
```
按内容类型（中文/英文/代码/Markdown）分比率估算 token 数。
### status — 查看状态
```bash
python scripts/airplan.py --mode ctx --project . --sub status
```
## 集成路径
**Eng 压缩检查**：每轮 `monitor_engine()` 后可调 `--sub validate` 检查上下文质量。
**Do Worker 压缩**：长任务 Worker 可在执行前调 `--sub compress` 精简上下文。

60
commands/dbg.md
View File

@@ -1,11 +1,63 @@
--- ---
description: "AirPlan dbg mode" description: "AirPlan dbg mode - 7-step debug workflow with evidence-first gate"
argument-hint: "[enter|status|...]" argument-hint: "[start|snapshot|status]"
allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]" allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
--- ---
# /dbg # /dbg
Run AirPlan dbg mode. AirDbg 是调试器，强制 7 步证据先于修复流程。EvidenceFirstGate 硬门控——未取证不可改代码（INV-9）。
python "$HOME/plugins/airplan/scripts/airplan.py" --mode dbg --project . [OPTIONS] ## 硬规则
1. **先读后写** — 修改代码前必须至少完成一项取证（截图/抓包/静态分析/日志分析/代码追踪/复现）
2. **修复前快照** — 修改代码前必须 `--sub snapshot` 创建回滚点
3. **步骤不可跳过** — 7 步工作流按顺序推进，每步需要对应证据
## 7 步工作流
| 步 | 名称 | 需要证据 | 操作 |
|----|------|---------|------|
| 1 | confirm_symptoms | 症状描述 | `--sub start` 初始化会话 |
| 2 | load_context | | 读取相关文件、日志、配置 |
| 3 | reproduce | (可跳过) | 复现或标记为不可复现 |
| 4 | locate_root_cause | ≥1 种证据 | 分析证据定位根因 |
| 5 | fix | 根因分析结论 | 先 `--sub snapshot`，再改代码 |
| 6 | verify_again | 测试结果 | 验证修复有效 |
| 7 | document | | 写 debug-log.md，关闭会话 |
## 子命令
### start — 启动调试会话
```bash
python scripts/airplan.py --mode dbg --project . --sub start --task-id T-001
```
返回 `{sessionId, currentStep, steps}`。会话状态写入 `AirPlan/state/airdbg/sessions/`。
### snapshot — 修复前创建回滚点
```bash
python scripts/airplan.py --mode dbg --project . --sub snapshot --task-id T-001
```
在当前 HEAD 创建 git tag，返回 `{snapshot_ref}`。
### status — 查看调试状态
```bash
python scripts/airplan.py --mode dbg --project . --sub status
```
## 集成路径
**Eng → Dbg**：`monitor_engine()` 检测到 stalled/blocked Worker 且 action=`"upgraded-to-airdbg"` 时：
1. 读 `interventions[].sessionId` 获取 Dbg 会话 ID
2. 调 `--sub start --task-id {tid}` 开始 Dbg 会话
3. Dbg 完成后：finish Worker，然后 merge
**Dbg → Do finish**：Dbg 修复完成后回到原任务：
```bash
python scripts/airplan.py --mode do --project . --sub finish --task-id T-001 --result AirPlan/state/airdo/tasks/T-001/result.json
```

42
commands/dep.md
View File

@@ -1,11 +1,45 @@
--- ---
description: "AirPlan dep mode" description: "AirPlan dep mode - SSH remote build + deploy + systemd management"
argument-hint: "[enter|status|...]" argument-hint: "[deploy|status]"
allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]" allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
--- ---
# /dep # /dep
Run AirPlan dep mode. AirDep 是部署器。SSH 远程构建 → 二进制传输（scp + MD5 校验）→ systemd 生命周期管理 → 部署验证。
python "$HOME/plugins/airplan/scripts/airplan.py" --mode dep --project . [OPTIONS] ## 硬规则
1. **部署前必须已有构建产物** — 本地 `--binary` 路径文件必须存在
2. **传输后 MD5 校验** — scp 后远程 MD5 必须与本地一致
3. **部署后验证** — systemd `is-active` 检查服务状态
## 子命令
### deploy — 执行部署
```bash
python scripts/airplan.py --mode dep --project . --sub deploy --task-id T-001 --host 192.168.1.100 --binary ./build/myapp
```
参数：
- `--task-id`：关联任务 ID
- `--host`：远程主机地址
- `--binary`：本地二进制文件路径
返回 `{task_id, success, md5, service_status}`。emit `deploy.completed` 事件。
制品：`AirPlan/state/airdep/sessions/{session_id}.json`
### status — 查看部署状态
```bash
python scripts/airplan.py --mode dep --project . --sub status
```
## 集成路径
**Do Worker 完成后部署**：Worker finish → Eng merge 检测 `deployRequired` 字段 → 调 dep deploy：
```bash
python scripts/airplan.py --mode dep --project . --sub deploy --task-id T-001 --host <host> --binary <path>
```

90
commands/do.md
View File

@@ -1,54 +1,84 @@
--- ---
description: "AirPlan do mode - task executor with UI skill routing" description: "AirPlan do mode - task executor with UI skill routing and evidence gate"
argument-hint: "[enter|status|finish]" argument-hint: "[enter|status|finish]"
allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]" allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
--- ---
# /do # /do
AirDo is the task executor. It runs individual tasks, enforces routing rules, and integrates with other AirPlan modes. AirDo 是任务执行器。运行单个任务，强制执行路由规则，集成其他 AirPlan 模式。
## Hard Rules ## 硬规则
1. **UI Task Handling (P1-20)** — When task involves UI/frontend/interface design: 1. **UI Task Handling (P1-20)** — 当任务涉及 UI/前端/界面时，检测并确保 frontend-design Skill 可用。不可用时阻止执行
- Must detect UI tasks via keyword matching (gui, ui, render, widget, frontend, react, vue, etc.) 2. **Evidence Gate (INV-4)** — GUI 任务需截图，网络任务需抓包，代码任务需静态分析/测试
- Must ensure frontend-design Skill is available before executing UI code 3. **Force AirDbg Routing** — done 无证据 → airdbg；blocked/failed → airdbg
- If frontend-design Skill is not installed, block the task
- Use `ensure_frontend_design_skill()` and `route_ui_task()` functions
2. **Evidence Gate (INV-4)** — Tasks with GUI/network indicators must have corresponding evidence before finishing: ## 子命令
- GUI tasks require screenshot/validation evidence
- Network tasks require packet capture/connectivity evidence
- Code tasks require static analysis/test results
3. **Force AirDbg Routing (INV-4)** — If task finishes without evidence, force route to AirDbg: ### enter — 进入 Worker
- `done` status + no validations/files_changed → route to airdbg
- `blocked`/`failed` status → always route to airdbg
## Sub-commands
### enter
```bash ```bash
python "$HOME/plugins/airplan/scripts/airplan.py" --mode do --project . --sub enter --task-id T-001 --task-text "实现登录界面UI" python scripts/airplan.py --mode do --project . --sub enter --task-id T-001 --task-text "实现登录界面UI"
``` ```
### status 参数：
- `--task-id`：任务 ID（必须）
- `--task-text`：任务描述文本（用于 UI 检测和路由，必须）
创建 `AirPlan/state/airdo/tasks/{task_id}/worker-state.json`。返回 `{taskId, briefPath, resultPath, workerStatePath, uiRouting}`。
### status — 查看 Worker 状态
```bash ```bash
python "$HOME/plugins/airplan/scripts/airplan.py" --mode do --project . --sub status python scripts/airplan.py --mode do --project . --sub status
``` ```
### finish ### finish — 完成 Worker（含路由决策）
```bash ```bash
python "$HOME/plugins/airplan/scripts/airplan.py" --mode do --project . --sub finish --task-id T-001 --result /path/to/result.json python scripts/airplan.py --mode do --project . --sub finish --task-id T-001 --result AirPlan/state/airdo/tasks/T-001/result.json
``` ```
## UI Task Detection Keywords finish 执行强制路由：
- `done` + 有 validations/filesChanged → route to `merge`
- `done` + 无 evidence → forced route to `airdbg`
- `blocked`/`failed` → forced route to `airdbg`
UI task detection uses these keywords (case-insensitive): ## AirDbg 路由 — 具体操作
- gui, ui, render, layout, dialog, osd, overlay, visual
- widget, pane, toolbar, settings_dialog, canvas, button 当 finish 返回 `routingDecision.target = "airdbg"` 时，**必须**调 dbg 模式：
- window, popup, menu, drm, kms, opengl, vulkan
- frontend, react, vue, angular, web, css, html ```bash
# 1. 启动调试会话
python scripts/airplan.py --mode dbg --project . --sub start --task-id {tid}
# 2. Dbg 按 7 步工作流调试（取证→定位→修复→验证）
# 3. Dbg 完成后，重新 finish:
python scripts/airplan.py --mode do --project . --sub finish --task-id {tid} --result AirPlan/state/airdo/tasks/{tid}/result.json
```
## 证据采集 — GUI/Network 任务
**GUI 任务**（涉及 gui/ui/render/widget/dialog 等关键词）— 需要截图：
```bash
python scripts/airplan.py --mode xdb --project . --prefer auto --output task-{tid}-screenshot.png
```
截图路径写入 result.json 的 validations 字段。
**网络任务**（涉及 network/rtsp/http/tcp 等关键词）— 需要抓包：
```bash
python scripts/airplan.py --mode ndb --project . --sub enter
# 然后 tcpdump/tshark 抓包，存入 AirPlan/state/airndb/captures/
```
**代码任务** — 需要静态分析或测试：
```bash
python scripts/airplan.py --mode sdb --project . --backend cppcheck --target ./src
# 或
python scripts/airplan.py --mode tst --project . --sub run --task-id {tid} --framework googletest
```
## UI 任务检测关键词（中英文）
gui, ui, render, layout, dialog, osd, overlay, visual, widget, pane, toolbar, canvas, button, window, popup, menu, drm, kms, opengl, vulkan, frontend, react, vue, angular, web, css, html, 界面, 按钮, 对话框, 窗口, 菜单, 控件, 渲染, 布局

29
commands/eng.md
View File

@@ -100,11 +100,36 @@ dispatch 返回 `{waveId, taskIds, dispatchPath}`。**然后按以下步骤操
### monitor ### monitor
spawn Worker 之后**必须进入轮询循环**。CLI 的 `monitor_engine()` 只执行一次检测——你需要循环调用它。
```bash ```bash
python "$HOME/plugins/airplan/scripts/airplan.py" --mode eng --project . --sub monitor python scripts/airplan.py --mode eng --project . --sub monitor
``` ```
合并就绪结果，检测停滞 Worker，更新 nextAction。 monitor 返回 `{activeWorkerCount, readyToMergeCount, stalledCount, interventionCount, nextAction}`。
**轮询循环（伪代码，每轮执行）**：
```
while 有活跃 Worker (activeWorkerCount > 0):
1. 等待 60-300 秒（根据 Worker 阶段自适应）
2. 运行 monitor 命令
3. 如果 readyToMergeCount > 0:
a. 找到完成的 Worker（读 state.json activeWorkers 中 status=done 的）
b. 对每个完成的 Worker 运行 merge 命令
4. 如果 stalledCount > 0:
a. 检查 interventions 列表
b. action="upgraded-to-airdbg" → 启动 Dbg 会话
c. action="terminate-and-block" → 标记任务 blocked
5. 如果 activeWorkerCount == 0:
退出循环，检查是否需要下一波 dispatch
```
**停滞检测逻辑**（代码自动执行，Agent 只需读结果）：
- Worker state 文件 mtime > 5 分钟未更新 → 标记 stalled
- Worker 存活时间 > 2 小时 → 标记 wall-time-exceeded
- 资源压力（loadavg > 2× CPU 数）→ 暂停派发
**注意**：Agent 没有内置时钟——你必须主动循环调用 monitor，不能等。
### merge ### merge

28
commands/ndb.md
View File

@@ -1,11 +1,31 @@
--- ---
description: "AirPlan ndb mode" description: "AirPlan ndb mode - network debugger for packet capture and analysis"
argument-hint: "[enter|status|...]" argument-hint: "[enter|status]"
allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]" allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
--- ---
# /ndb # /ndb
Run AirPlan ndb mode. AirNDB 是网络调试器。抓包分析、TLS 解密、pcapng 支持。
python "$HOME/plugins/airplan/scripts/airplan.py" --mode ndb --project . [OPTIONS] ## 子命令
### enter — 初始化网络调试器
```bash
python scripts/airplan.py --mode ndb --project . --sub enter
```
返回 `{state_path}`。初始化 `AirPlan/state/airndb/` 目录结构。
### status — 查看调试器状态
```bash
python scripts/airplan.py --mode ndb --project . --sub status
```
制品：`AirPlan/state/airndb/captures/`
## 集成路径
**Dbg 取证**：Dbg 在 `locate_root_cause` 步骤可调 ndb 获取网络证据。涉及 network/rtsp/http/tcp 的任务需要抓包证据。

50
commands/rvr.md
View File

@@ -1,11 +1,53 @@
--- ---
description: "AirPlan rvr mode" description: "AirPlan rvr mode - requirement reviewer with highRiskAudit and code-to-design"
argument-hint: "[enter|status|...]" argument-hint: "[review|status]"
allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]" allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
--- ---
# /rvr # /rvr
Run AirPlan rvr mode. AirRvr 是需求审查器。基于原始需求文档对已完成任务进行独立审查，验证交付物与需求的一致性。含 highRiskAudit（生命周期/空指针/悬垂指针/异常安全/并发）和 Code-to-Design 逐行对照。
python "$HOME/plugins/airplan/scripts/airplan.py" --mode rvr --project . [OPTIONS] ## 硬规则
1. **code-to-design 对照** — 每次审查必须逐行对照代码实现与设计文档（ADR、C4、需求）
2. **高风险审计** — 终审必须包含 lifecycle/nullPointer/danglingPointer/exceptionSafety/concurrency 五项检查
3. **verdict 控制合并** — fail 阻止合并，conditional-pass 记录遗留项，pass 正常合并
4. **deliveryVerdict = block-release** — eng dispatch 阻止所有后续派发
## 审查模式
| 模式 | 触发时机 | 审查范围 |
|------|---------|---------|
| per-task | 单个任务完成后 | 单任务 |
| per-wave | 波次所有任务完成后 | 整波 |
| per-milestone | 项目阶段结束时 | 全量（比对 requirements.md） |
## 子命令
### review — 执行审查
```bash
python scripts/airplan.py --mode rvr --project . --sub review --task-id T-001
```
返回 `{task_id, verdict, report_path}`。审查报告含 coverage/intentAlignment/regressionRisk/codeQuality/lifecycleHealth/runtimeStability/codeToDesignTable/highRiskAudit。
制品：`AirPlan/state/airrvr/reviews/{task_id}-{ts}.json`
### status — 查看审查状态
```bash
python scripts/airplan.py --mode rvr --project . --sub status
```
## 集成路径
**Eng merge 时自动检查**：merge_worker_result Phase 1.5 自动调用 `get_verdict_for_task(task_id)`：
- `verdict=fail` → 抛出 `ValueError` 阻止合并
- `verdict=conditional-pass` → 记录 residualItems 但允许合并
- `deliveryVerdict=block-release` → dispatch_worker_group 阻止所有后续派发
**触发方式**：设置 `reviewPolicy.requireBeforeMerge=true` 或在 result 中设 `requireReview=true`。
**INVALIDATED 任务清理检查**（P1-21）：ADR 变更级联失效后，手动调 `check_invalidated_cleanup()` 验证旧代码已清理。

46
commands/sdb.md
View File

@@ -1,11 +1,49 @@
--- ---
description: "AirPlan sdb mode" description: "AirPlan sdb mode - multi-language static analyzer (cppcheck/clang-tidy/clippy/go-vet/tsc/mypy)"
argument-hint: "[enter|status|...]" argument-hint: "[analyze]"
allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]" allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
--- ---
# /sdb # /sdb
Run AirPlan sdb mode. AirSDB 是多语言静态分析器。支持六种后端和 diff 模式。
python "$HOME/plugins/airplan/scripts/airplan.py" --mode sdb --project . [OPTIONS] ## 支持的后端
| 后端 | --backend 值 | 语言 |
|------|-------------|------|
| Cppcheck | `cppcheck` | C/C++ |
| Clang-Tidy | `clang-tidy` | C/C++ |
| Clippy | `clippy` | Rust |
| go vet + staticcheck | `go-vet` | Go |
| tsc --noEmit | `tsc` | TypeScript |
| mypy + ruff | `mypy` | Python |
## 子命令
### 执行静态分析
```bash
python scripts/airplan.py --mode sdb --project . --backend cppcheck --target ./src
```
参数：
- `--backend`：分析后端（默认 `cppcheck`）
- `--target`：分析目标路径
返回每行一个 finding：`{file}:{line}: {severity}: {message}`。最多显示 10 个。
## diff 模式
两次扫描结果对比，高亮新增/消除的 finding：
```bash
# 第一次扫描 → 保存基线
python scripts/airplan.py --mode sdb --project . --backend cppcheck --target ./src > baseline.txt
# 修改代码后第二次扫描 → Agent 读取两次结果对比 diff
```
## 集成路径
**Dbg 取证**：Dbg 在 `locate_root_cause` 步骤可调 sdb 获取静态分析证据。
**Do Worker 完成前**：Worker finish 前可调 sdb 验证代码质量。

54
commands/sec.md
View File

@@ -1,11 +1,57 @@
--- ---
description: "AirPlan sec mode" description: "AirPlan sec mode - security scanner for sensitive data detection"
argument-hint: "[enter|status|...]" argument-hint: "[scan|status]"
allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]" allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
--- ---
# /sec # /sec
Run AirPlan sec mode. AirSec 是安全扫描器。扫描制品中的敏感数据（API 密钥、令牌、密码），支持 advisory（只报告）和 blocking（阻止合并）两种模式。
python "$HOME/plugins/airplan/scripts/airplan.py" --mode sec --project . [OPTIONS] ## 两种扫描模式
| 模式 | --sec-mode | 行为 |
|------|-----------|------|
| advisory | `advisory` | 只报告，不阻止 |
| blocking | `blocking` | 发现敏感数据时阻止合并 |
## 子命令
### scan — 执行安全扫描
扫描单个文件：
```bash
python scripts/airplan.py --mode sec --project . --sub scan --task-id T-001 --scan-path ./src/config.cpp --sec-mode blocking
```
扫描整个目录：
```bash
python scripts/airplan.py --mode sec --project . --sub scan --task-id T-001 --scan-path ./src --sec-mode advisory
```
不传 `--scan-path` 时扫描 Worker result：
```bash
python scripts/airplan.py --mode sec --project . --sub scan --task-id T-001 --sec-mode blocking
```
参数：
- `--task-id`：关联任务 ID
- `--scan-path`：扫描目标路径（文件或目录，可选）
- `--sec-mode`：`advisory`（默认）或 `blocking`
返回 `{task_id, clean, findings, whitelisted, mode}`。emit `sec.scan` 事件。
### status — 查看扫描状态
```bash
python scripts/airplan.py --mode sec --project . --sub status
```
## 集成路径
**Do Worker finish 前**：Worker 完成代码后、调 finish 前，先调 sec scan：
```bash
python scripts/airplan.py --mode sec --project . --sub scan --task-id {tid} --sec-mode blocking
```
**Eng merge 前**：merge_worker_result Phase 1 验证后检查 sec 扫描结果。`clean=false` 时阻止合并。

50
commands/tst.md
View File

@@ -1,11 +1,53 @@
--- ---
description: "AirPlan tst mode" description: "AirPlan tst mode - unified test runner for CTest/GoogleTest/pytest/jest/go test/cargo test"
argument-hint: "[enter|status|...]" argument-hint: "[run|status]"
allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]" allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
--- ---
# /tst # /tst
Run AirPlan tst mode. AirTst 是测试运行器。支持多框架统一执行和结构化结果报告。
python "$HOME/plugins/airplan/scripts/airplan.py" --mode tst --project . [OPTIONS] ## 支持的框架
| 框架 | --framework 值 | 语言 |
|------|---------------|------|
| CTest / GoogleTest | `googletest` | C++ |
| pytest | `pytest` | Python |
| jest / vitest | `jest` | TypeScript |
| go test | `go` | Go |
| cargo test | `cargo` | Rust |
## 子命令
### run — 执行测试
```bash
python scripts/airplan.py --mode tst --project . --sub run --task-id T-001 --framework googletest
```
参数：
- `--task-id`：关联任务 ID
- `--framework`：测试框架（见上表）
返回 `{task_id, framework, total, passed, failed}`。emit `test.run` 事件。
制品：`AirPlan/state/airtst/reports/{task_id}-{ts}.json`
### status — 查看测试状态
```bash
python scripts/airplan.py --mode tst --project . --sub status
```
## 集成路径
**Arc 注入的边界测试任务执行**：Arc 规划的 `T-TEST-*` 任务执行时调 tst run：
```bash
python scripts/airplan.py --mode tst --project . --sub run --task-id T-TEST-001 --framework googletest
```
**Do Worker 完成前自测**：Worker finish 前可调 tst 验证：
```bash
python scripts/airplan.py --mode tst --project . --sub run --task-id {tid} --framework {fw}
```

40
commands/xdb.md
View File

@@ -1,11 +1,43 @@
--- ---
description: "AirPlan xdb mode" description: "AirPlan xdb mode - GUI validator with DRM/KMS native screenshot and headless CI"
argument-hint: "[enter|status|...]" argument-hint: "[capture]"
allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]" allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
--- ---
# /xdb # /xdb
Run AirPlan xdb mode. AirXDB 是 GUI 验证器。支持 DRM/KMS 原生截图（kmsgrab）、Xvfb headless 截图、多后端自动降级。
python "$HOME/plugins/airplan/scripts/airplan.py" --mode xdb --project . [OPTIONS] ## 截图后端
| 后端 | --prefer 值 | 适用场景 |
|------|------------|---------|
| KMS grab | `kms` | 嵌入式 DRM/KMS 显示 |
| Xvfb | `xvfb` | CI headless 环境 |
| fallback | `fallback` | 通用桌面环境 |
| auto | `auto` | 自动检测（默认，按 kms → xvfb → fallback 尝试） |
## 子命令
### 截图采集
```bash
python scripts/airplan.py --mode xdb --project . --prefer auto --output screenshot.png
```
参数：
- `--prefer`：截图后端偏好（默认 `auto`）
- `--output`：输出文件名（默认 `screenshot.png`）
返回 `{success, method, output, error}`。
## 集成路径
**Dbg 取证**：Dbg 在 `confirm_symptoms` 步骤调 xdb 获取截图证据：
```bash
python scripts/airplan.py --mode xdb --project . --prefer auto --output debug-screenshot.png
```
**Do Worker GUI 任务验证**：涉及 GUI/UI/Render 的任务，finish 前必须有截图证据。Worker 调 xdb 采集后，将截图路径写入 result.json 的 validations 字段。
**证据门控**：`EvidenceGatePolicy` 检测到任务含 GUI 关键词时，自动要求 xdb 截图证据。