chore: push all design docs, V2 plan specs, and current working state

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>
2026-06-12 17:12:29 +08:00
parent 8f55c962bb
commit ae44be31d5
364 changed files with 46779 additions and 2812 deletions
--- a/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airarc/SKILL.md
+++ b/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airarc/SKILL.md
@@ -0,0 +1,37 @@
+---
+name: airarc
+description: Architecture-first workflow with built-in post-plan parallelization review. Use when planning should emit dependency edges, parallel groups, write-set conflicts, and serialization points for Air Engine. AirArc plans and edits planning docs only; it does not write code.
+---
+
+# AirArc
+
+## Upgrade Notes
+
+- Keep the original architecture-first planning role.
+- AirArc is an architect-only workflow: it may plan tasks and edit architecture or planning documents, but it must not implement code changes.
+- Add built-in post-plan review instead of a separate review-only plugin.
+- Emit engine-consumable execution artifacts after planning.
+
+## Outputs
+
+- `AirPlan/state/airarc/state.json`
+- `AirPlan/state/airarc/reviews/parallel-review.json`
+- `AirPlan/state/airarc/reviews/parallel-review.md`
+- `AirPlan/state/airarc/reviews/execution-plan.json`
+- `AirPlan/state/airarc/reviews/execution-plan.md`
+
+## Review Responsibilities
+
+- Compute dependency edges.
+- Compute parallel-safe groups.
+- Detect shared write-set conflicts.
+- Mark serialization points for global docs and merge boundaries.
+- Produce an execution plan that Air Engine can prefer directly.
+
+## Commands
+
+```bash
+python "$HOME/plugins/airarc/scripts/airarc_mode.py" --mode enter --project <project-root>
+python "$HOME/plugins/airarc/scripts/airarc_mode.py" --mode status --project <project-root>
+python "$HOME/plugins/airarc/scripts/airarc_mode.py" --mode parallel-review --project <project-root> --todo <todo-md>
+```
--- a/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airdbg/SKILL.md
+++ b/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airdbg/SKILL.md
@@ -0,0 +1,245 @@
+---
+name: airdbg
+description: Debug-first repair workflow. Use when the user invokes /airdbg or explicitly asks for AirDbg mode to debug, reproduce, diagnose, or fix software errors, including GUI, visual, screenshot, browser UI, desktop UI, remote GUI/device debugging, canvas, layout, focus, popup, graphical operation, network, packet capture, remote packet capture, pcap, DNS, TCP, UDP, TLS, HTTP connectivity, proxy, firewall, port, retransmit, reset, latency, cppcheck, static analysis, code quality, or security-relevant C/C++ defects. Load or initialize AirPlan/AGENTS.md, AirPlan/docs/architecture/adr/ decision records, and AirPlan/docs/architecture/c4/module.md; discuss symptoms and constraints with the user; reproduce the issue; require AirXDB local or remote device helpers or equivalent GUI/screen evidence for every local or remote GUI validation instead of treating process liveness as success; call AirNDB local or remote device helpers when tcpdump/WinDump packet capture, pcap analysis, BPF filters, or network-layer evidence is needed; call AirSDB local or remote device helpers when static-analysis capability, cppcheck evidence, or AirPlan/docs/staticanalysis.md documentation is needed; identify root cause; apply a focused fix; verify with tests or equivalent checks; and update AirPlan/AGENTS.md, ADR, and C4 module docs when project behavior, module boundaries, dependencies, GUI automation boundaries, network boundaries, static-analysis boundaries, remote-device boundaries, or architecture decisions change.
+---
+
+# AirDbg
+
+## 核心约束
+
+- 全程使用中文与用户交流，代码、命令、日志、路径、异常名保持原文。
+- `/airdbg` 是主要触发入口。用户进入 AirDbg 后，围绕调试和修复错误推进。
+- 先加载项目上下文，再修复：`AirPlan/AGENTS.md`、`AirPlan/docs/architecture/adr/`、`AirPlan/docs/architecture/c4/module.md`。
+- 如果这些文件不存在，先分析当前项目并初始化它们；C4 module 要记录真实模块边界，不只放空模板。
+- 与用户交流症状、复现步骤、期望行为、实际行为、影响范围和修复约束。
+- 默认做最小可验证修复，避免顺手重构。
+- 每个修复都要验证。优先自动化测试，其次是可重复命令或明确的手工验证步骤。
+- 只要验证或复现涉及本地或远程 GUI，就不能只以进程存在、窗口拉起、命令退出成功、端口监听或日志无异常判定通过；必须辅以图像/GUI 检验和测试。
+- 调试中遇到图形对比、截图取证、GUI 操作、浏览器/桌面界面、Canvas、弹窗、焦点、布局、视觉回归或其他图形功能时，必须调用 `airxdb` 获取截图、探索界面、执行操作验证或收集视觉证据；如果是嵌入式屏幕、显示链路等截图无诊断价值的场景，可不强制截图，但必须补充等效的 GUI/屏幕状态证据和操作验证，并记录原因。
+- 如果 GUI 问题发生在远程设备、测试机、VM、服务器或 SSH 主机上，调用 AirXDB remote device helper，而不是默认使用本机 Computer MCP。
+- 调试中遇到抓包分析、pcap、tcpdump/WinDump、BPF、DNS、TCP、UDP、TLS、HTTP 连接、端口、代理、防火墙、丢包、重传、RST 或延迟问题时，可以调用 `airndb` 获取网络层调试证据。
+- 如果网络问题发生在远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上，调用 AirNDB remote device helper，而不是默认使用本机抓包工具。
+- 调试中遇到需要静态分析能力的检验、测试或定位场景，以及 C/C++ 静态分析、cppcheck、代码质量、安全性初筛、未初始化变量、空指针、越界、资源释放、危险转换或 CWE 线索需求时，可以调用 `airsdb` 获取 `AirPlan/docs/staticanalysis.md`、XML/JSON 报告等静态分析证据和辅助调试文档。
+- 如果静态分析目标在远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上，调用 AirSDB remote device helper，而不是默认使用本机 cppcheck。
+- 一定要根据项目变化维护 `AirPlan/AGENTS.md`、ADR 和 C4 module。
+- ADR 是给 AI 作为上下文的决策记录，短、准、可检索即可，不写冗长修饰。
+
+## 启动与初始化
+
+进入 `/airdbg` 时运行：
+
+```bash
+python "$HOME/plugins/airdbg/scripts/airdbg_mode.py" --mode enter --project .
+```
+
+如果当前环境没有 `python`，尝试 `py` 或 `python3`。脚本不可用时，手动确保以下结构存在：
+
+- `AirPlan/AGENTS.md`
+- `AirPlan/docs/architecture/adr/`
+- `AirPlan/docs/architecture/c4/module.md`
+- `AirPlan/docs/debug/debug-log.md`
+- `AirPlan/state/airdbg/state.json`
+
+初始化后读取已有内容作为上下文。不要覆盖用户已有正文；只补齐缺失结构或更新 AirDbg 标记块。
+
+## 图形调试与 AirXDB 协作
+
+AirDbg 负责根因分析、代码层修复和验证收尾；AirXDB 负责图形界面的取证和操作层复现。遇到以下情况时，必须调用 AirXDB 或补充等效 GUI/屏幕证据：
+
+- 需要截图或图形对比来理解错误现场、视觉回归、布局错位、颜色/尺寸/遮挡差异。
+- 需要操作浏览器 UI、桌面 UI、Electron/Qt/WPF 等应用、Canvas、菜单、弹窗、托盘、任务栏或多显示器界面。
+- 需要 `/airxdb screenshot` 保存错误现场，再把截图交给 AirDbg 做代码层诊断。
+- 目标 GUI 在远程设备、测试机、VM、服务器或 SSH 主机上，需要 `/airxdb remote-screenshot` 或 `airxdb_remote_device.py` 保存远程错误现场。
+- 需要用 AirXDB 执行最小 GUI 操作，确认按钮、表单、导航、窗口切换、焦点或图形流程是否真的失败。
+- 需要把 GUI 证据沉淀到 `AirPlan/docs/debug/gui-debug-log.md`、`AirPlan/docs/debug/airxdb-artifacts/` 或 AirDbg 的 `AirPlan/docs/debug/debug-log.md`。
+
+协作规则：
+
+- 先用 AirXDB 收集最小必要证据，再回到 AirDbg 分析代码根因；不要把视觉症状直接当作根因。
+- 任何本地或远程 GUI 测试/验证都不能仅以进程存活、窗口创建成功、命令返回成功或日志无异常视为通过；默认至少保留 1 份截图/图像证据，并完成 1 次关键 GUI 操作或状态检查。
+- 如果是嵌入式屏幕、显示控制器、外接面板链路等截图无诊断价值的场景，可改用外部采集视频、framebuffer dump、串口/日志配合按键或触控操作记录、状态灯/OSD 观察记录等等效证据，但必须在 `debug-log.md` 记录为什么不截图以及替代证据是什么。
+- 截图模式可在没有 Midscene 语义模型配置时使用；语义视觉动作按 AirXDB 规则先检查模型配置。
+- 本机 GUI 证据使用 `/airxdb screenshot` 或 `airxdb_computer_mcp_smoke.py`；远程 GUI 证据使用 `airxdb_remote_device.py --action setup|screenshot`，由它探测 SSH、远端截图工具并在缺失时自动尝试配置。
+- 远程 helper 缺少 `AIRXDB_REMOTE_SSH_TARGET` 时，先让用户提供 SSH 目标；需要交互式 sudo、管理员确认或无支持包管理器时停止并说明。
+- AirDbg 的 `debug-log.md` 必须记录 AirXDB 命令、截图/报告路径、关键观察、与根因的关系、复验结果和剩余风险。
+- 如果 GUI 自动化、截图取证、视觉验收、浏览器桥接或桌面控制成为长期调试/测试边界，更新 C4 module 并创建或修订 ADR。
+- 如果发现稳定可复用的 GUI 调试命令、截图方式、远程设备配置或视觉验收步骤，更新 `AGENTS.md`。
+- 截图可能包含账号、密钥、客户数据或聊天内容时，先提醒用户脱敏，再外部分享或长期保留。
+
+## 抓包调试与 AirNDB 协作
+
+AirDbg 负责把网络证据和代码行为联系起来，定位根因并修复；AirNDB 负责 tcpdump/WinDump 抓包、pcap 摘要、BPF 过滤器和网络层证据。遇到以下情况时，调用 AirNDB：
+
+- 需要抓包判断请求是否发出、响应是否回来、连接是否被 RST/ICMP/防火墙/代理中断。
+- 需要分析 DNS 查询、TCP 三次握手、TLS 握手、HTTP 连接、UDP 流量、端口可达性、重传、丢包或延迟。
+- 需要读取已有 `.pcap` 或生成新的短时有界 pcap 给调试使用。
+- 需要确定问题在应用代码、系统网络栈、容器/WSL/VM/宿主机边界、代理、防火墙还是远端服务。
+- 目标流量发生在远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上，需要 `/airndb remote-interfaces`、`/airndb remote-capture` 或 `airndb_remote_device.py` 获取远程网络证据。
+
+协作规则：
+
+- 先让 AirNDB 明确授权范围、接口、BPF 过滤器、抓包窗口和 pcap 输出路径；不要进行无界抓包。
+- 本机网络证据使用 `airndb_capture.py`；远程网络证据使用 `airndb_remote_device.py --action setup|interfaces|command|capture`，由它探测 SSH、远端 `tcpdump` / `dumpcap` 并在缺失时自动尝试配置。
+- 远程 helper 缺少 `AIRNDB_REMOTE_SSH_TARGET` 时，先让用户提供 SSH 目标；需要交互式 sudo、管理员确认或无支持包管理器时停止并说明。
+- AirDbg 的 `debug-log.md` 必须记录 AirNDB 命令、pcap/summary/report 路径、关键包或时间线观察、与根因的关系、复验结果和剩余风险。
+- 如果抓包发现新的长期网络边界、端口、协议、DNS、代理、TLS、容器/WSL/VM/宿主机约束或观测方式，更新 C4 module 并创建或修订 ADR。
+- 如果发现稳定可复用的抓包命令、接口选择规则、BPF、远程设备配置或 pcap 读取方式，更新 `AGENTS.md`。
+- pcap 可能包含 token、cookie、payload、内网地址、主机名或个人信息；对外分享前必须提醒用户脱敏。
+
+## 静态分析与 AirSDB 协作
+
+AirDbg 负责把静态分析线索和代码根因联系起来；AirSDB 负责 cppcheck 检测/安装、本机或远程扫描、XML/JSON 产物和 `AirPlan/docs/staticanalysis.md` 简短报告。遇到以下情况时，可以调用 AirSDB：
+
+- 需要用 cppcheck 辅助定位 C/C++ bug、内存/资源/越界/空指针/未初始化变量/危险转换/CWE 线索。
+- 需要在修复前后比较静态分析结果。
+- 需要给 AirDbg 的根因分析提供短报告而不是长 XML。
+- 检验、测试或调试判断需要静态分析能力、质量门信息或可引用文档时，需要读取 `AirPlan/docs/staticanalysis.md` 或 AirSDB XML/JSON 报告辅助分析。
+- 目标代码在远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上，需要 `/airsdb remote-scan` 或 `airsdb_remote_device.py` 获取远端静态分析证据。
+
+协作规则：
+
+- 本机静态分析使用 `airsdb_cppcheck.py --action scan`；远程静态分析使用 `airsdb_remote_device.py --action setup|scan`，由它探测 SSH、远端 cppcheck 并在缺失时自动尝试配置。
+- AirDbg 的 `AirPlan/docs/debug/debug-log.md` 必须记录 AirSDB 命令、`AirPlan/docs/staticanalysis.md`、XML/JSON 报告路径、关键 findings、与根因的关系、复验结果和剩余风险。
+- 如果静态分析发现新的长期质量门槛、suppressions、远程设备配置或 cppcheck 命令，更新 `AGENTS.md`。
+- 如果静态分析成为长期测试/调试边界，更新 C4 module 并创建或修订 ADR。
+
+## 调试流程
+
+1. 确认问题边界：
+   - 用户看到的错误是什么。
+   - 期望行为和实际行为是什么。
+   - 复现步骤、输入数据、环境、版本、最近变更是什么。
+   - 有哪些不能破坏的兼容性或性能要求。
+2. 加载上下文：
+   - 读取 `AGENTS.md`。
+   - 读取 ADR 列表和相关 ADR。
+   - 读取 `docs/architecture/c4/module.md`。
+   - 查看测试、入口、依赖、配置和最近相关文件。
+3. 复现问题：
+   - 优先运行已有失败测试或用户给出的命令。
+   - 没有复现命令时，先构造最小复现或定位性测试。
+   - 如果复现依赖 GUI、截图或图形操作，必须调用 AirXDB 获取截图、执行最小界面操作或保存 GUI 报告；远程目标走 AirXDB remote device helper；嵌入式截图无效时改用等效 GUI/屏幕证据并记录原因。
+   - 如果复现依赖网络路径或抓包证据，调用 AirNDB 获取短时 pcap、摘要或网络层时间线；远程目标走 AirNDB remote device helper。
+- 如果复现或定位需要 C/C++ 静态分析，或当前检验需要静态分析能力辅助判断，调用 AirSDB 运行本机或远程 cppcheck，并读取 `AirPlan/docs/staticanalysis.md`。
+   - 记录复现命令和关键输出到 `docs/debug/debug-log.md`。
+4. 定位根因：
+   - 从错误栈、日志、测试断言、数据流和模块边界推断。
+   - 对 GUI 问题，结合 AirXDB 本机或远程截图/报告判断视觉症状、交互失败和代码根因之间的关系。
+   - 对网络问题，结合 AirNDB 本机或远程 pcap/摘要判断请求是否出站、响应是否入站、失败发生在 DNS/TCP/TLS/应用层哪一段。
+   - 对静态分析问题，结合 AirSDB findings 判断哪些是当前 bug 线索、哪些是既有质量债或误报。
+   - 必要时加临时日志或小范围探针，完成后清理。
+   - 区分根因、诱因和表面症状。
+5. 修复：
+   - 优先选择影响面小、能解释根因的修复。
+   - 不做无关格式化、批量重构或架构迁移。
+   - 如果修复会改变模块边界、依赖、接口、数据所有权或关键行为，先更新 C4/ADR。
+6. 验证：
+   - 运行失败用例、相关单元测试、集成测试、lint/typecheck。
+   - 如果修复涉及 GUI 或视觉行为，必须调用 AirXDB 截图、图形对比或操作验证关键路径；远程目标用远程 helper 复验；嵌入式截图无效时改用等效 GUI/屏幕证据并记录原因。
+   - 如果修复涉及网络行为，调用 AirNDB 复验关键网络路径或读取 pcap 摘要；远程目标用远程 helper 复验。
+- 如果修复涉及 C/C++ 风险、静态分析 findings，或验证需要静态分析能力辅助判断，调用 AirSDB 复跑 cppcheck 并更新 `AirPlan/docs/staticanalysis.md`。
+   - 如果不能运行，说明原因，并给出可复验的替代验证。
+   - 记录验证证据到 debug log。
+7. 收尾：
+   - 更新 `AGENTS.md` 中与调试、测试、运行方式相关的项目上下文。
+   - 更新或新增 ADR。
+   - 更新 C4 module。
+   - 向用户汇报根因、改动、验证结果、剩余风险。
+
+## AGENTS.md 维护
+
+在以下情况更新 `AGENTS.md`：
+
+- 发现新的运行、测试、构建、调试命令。
+- 发现新的 AirXDB 截图、GUI 操作验证、图形对比、远程设备配置或视觉验收命令。
+- 发现新的 AirNDB 抓包命令、BPF 过滤器、接口选择规则、远程设备配置、pcap 读取方式或网络复验步骤。
+- 发现新的 AirSDB cppcheck 命令、suppressions、质量门槛、远程设备配置或静态分析复验步骤。
+- 发现影响后续 AI 会话的重要项目约束。
+- 修复改变了模块职责、关键流程或错误处理策略。
+- 发现常见坑、环境要求或验证方式。
+
+保持内容可执行、可复用，不写调试过程流水账。
+
+## ADR 维护
+
+目录：`docs/architecture/adr/`。
+
+需要 ADR 的情况：
+
+- 修复选择了一个会影响长期架构或行为兼容性的方案。
+- 改变错误处理、重试、事务、缓存、一致性、安全边界。
+- 改变模块依赖、数据所有权、接口契约。
+- 将 GUI 自动化、截图取证、远程设备 GUI 取证、视觉验收或图形调试流程纳入长期测试/调试边界。
+- 将抓包、远程设备抓包、pcap 分析、网络观测、端口、协议、DNS、代理、TLS 或网络拓扑纳入长期调试/测试边界。
+- 将 cppcheck、staticanalysis.md、静态分析质量门槛或远程静态分析纳入长期调试/测试边界。
+- 拒绝了明显可选方案，需要给后续 AI 留下原因。
+
+ADR 模板：
+
+```markdown
+# ADR-000X: short-title
+
+- Status: Accepted
+- Date: YYYY-MM-DD
+
+## Context
+简述错误、约束和为什么需要决策。
+
+## Decision
+简述采用的修复或架构选择。
+
+## Consequences
+- 正面影响
+- 代价或风险
+
+## Alternatives
+- 方案 A：放弃原因
+```
+
+## C4 Module 维护
+
+文件：`docs/architecture/c4/module.md`。
+
+必须记录：
+
+- 模块名。
+- 职责。
+- 对外接口。
+- 依赖。
+- 数据所有权。
+- 与本次错误或修复相关的质量属性。
+
+新增模块、拆分模块、改变依赖、改变接口、改变数据边界、改变错误处理流时必须更新。
+
+引入或改变 GUI 自动化、浏览器桥接、桌面控制、截图取证、远程设备 GUI 取证、视觉验收或图形调试基础设施时，也必须更新。
+
+引入或改变 tcpdump/WinDump 抓包、远程设备抓包、pcap 分析、网络观测、端口、协议、DNS、代理、TLS、容器/WSL/VM/宿主机网络边界时，也必须更新。
+
+引入或改变 cppcheck、staticanalysis.md、静态分析质量门槛、suppressions 或远程静态分析边界时，也必须更新。
+
+## debug-log 维护
+
+文件：`docs/debug/debug-log.md`。
+
+每次 AirDbg 修复至少追加：
+
+- 问题摘要。
+- 复现命令或复现步骤。
+- 根因。
+- 修复摘要。
+- 验证命令和结果。
+- AirXDB 本机或远程截图/报告/操作验证证据及其结论（如适用）。
+- AirNDB 本机或远程 pcap/summary/report/抓包分析证据及其结论（如适用）。
+- AirSDB 本机或远程 staticanalysis.md/XML/JSON 静态分析证据及其结论（如适用）。
+- 相关 ADR/C4 更新。
+- 剩余风险。
+
+## 输出格式
+
+调试完成后用中文简洁汇报：
+
+- 根因。
+- 修复了什么。
+- 更新了哪些 `AGENTS.md` / ADR / C4 / debug log 上下文。
+- 运行了哪些验证；是否调用 AirXDB/AirNDB/AirSDB，截图、pcap、staticanalysis、报告或操作证据在哪里。
+- 仍然存在的风险或未验证项。
--- a/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airdbg/agents/openai.yaml
+++ b/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airdbg/agents/openai.yaml
@@ -0,0 +1,3 @@
+name: airdbg
+short_description: Debug-first repair with local/remote AirXDB, AirNDB, and AirSDB evidence
+default_prompt: "使用 AirDbg 调试并修复当前项目错误；GUI 测试或验证必须保留 GUI 复验证据，嵌入式截图无效时改用等效屏幕证据；网络证据调用 AirNDB，需要静态分析能力时调用 AirSDB。"
--- a/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airdo/SKILL.md
+++ b/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airdo/SKILL.md
@@ -0,0 +1,38 @@
+---
+name: airdo
+description: Public Air executor for one scoped todo slice. Use it standalone or as an isolated AirEng subagent and finalize the result into AirPlan.
+---
+
+# AirDo
+
+## Role
+
+- Execute one task or one very small implementation slice.
+- Keep AirDo execution guarantees for context loading, evidence, and validation.
+- Finalize one structured result package in `AirPlan/state/airdo/results/`.
+- Act as the standard AirEng child executor when work is delegated into isolated subagents.
+
+## Inputs
+
+- `AirPlan/AGENTS.md`
+- `AirPlan/docs/architecture/adr/`
+- `AirPlan/docs/architecture/c4/module.md`
+- `AirPlan/plan.md`
+- `AirPlan/todo.md`
+- `AirPlan/state/airdo/tasks/<task-id>/brief.md`
+- `AirPlan/state/airdo/tasks/<task-id>/subagent-handoff.md` when launched by AirEng
+
+## Result Rules
+
+- Finalize one `result.json` per task.
+- Treat `AirPlan/state/airdo/tasks/<task-id>/worker-state.json` `resultPath` as the canonical pointer to the latest result artifact. The task-local `result.json` is only the editable template before finalize.
+- Include validations, evidence, risks, blockers, and document updates when needed.
+- Do not edit global `AirPlan/todo.md`, `AirPlan/AGENTS.md`, ADR, or C4 files directly unless explicitly delegated through `documentUpdates`.
+- If the task changes execution planning or architecture reality, include concrete `documentUpdates` so AirEng can keep `todo`, `plan`, ADR, and C4 synchronized during merge.
+
+## Automatic Routing
+
+- On `blocked` results, auto-request AirDbg before finalize.
+- On GUI or visual work, auto-request AirXDB before finalize.
+- If AirEng queued an active repair attempt, continue repairing automatically instead of stopping at the first blocker.
+- Do not stop at implementation-prep or progress-only updates when the task is actionable. Continue until finalize unless a real blocker or explicit user decision is required.
--- a/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airdo/agents/openai.yaml
+++ b/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airdo/agents/openai.yaml
@@ -0,0 +1,3 @@
+name: airdo
+short_description: Public Air executor for one scoped task, validation evidence, and AirPlan result finalization
+default_prompt: "Use AirDo to execute one task, gather validation evidence, auto-route GUI or debug work, and finalize a structured result in AirPlan for AirEng to merge."
--- a/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/aireng/SKILL.md
+++ b/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/aireng/SKILL.md
@@ -0,0 +1,65 @@
+---
+name: aireng
+description: Sole public Air scheduler that reads AirArc execution artifacts, dispatches isolated AirDo subagents with bounded concurrency, monitors them on a 5-minute cadence, and merges structured results into AirPlan.
+---
+
+# AirEng
+
+## Role
+
+- Own the global execution contract in `AirPlan/`.
+- Read AirArc review output before falling back to local todo analysis.
+- Dispatch isolated AirDo subagents with `fork_context=false`.
+- Monitor active workers, merge structured worker results, and keep the scheduler moving unattended.
+- Own debug policy, XDB policy, repair policy, intervention policy, and global document convergence.
+- Default to no parent-thread coding; use parent-thread edits only for short unblock actions that restore the scheduler.
+
+## Planning Source Order
+
+1. `AirPlan/state/airarc/reviews/execution-plan.json`
+2. `AirPlan/state/airarc/reviews/parallel-review.json`
+3. Engine fallback analysis of `AirPlan/todo.md`
+
+## Dispatch Contract
+
+- Generate the dispatch manifest under `AirPlan/state/aireng/dispatch/`.
+- Respect `recommendedConcurrency`; do not flood the workspace with overlapping workers.
+- Spawn one isolated AirDo subagent per task handoff.
+- After a worker finishes, read its `workerStatePath` and use the `resultPath` recorded there as the canonical finalized result location.
+- Pass only the task handoff and project path to each worker. Do not fork the full parent thread history.
+- Do not interrupt actionable workers for midpoint status updates; let them continue through implementation and finalize unless they surface a real blocker.
+- Keep parent-thread work limited to orchestration, monitoring, merge, repair, document convergence, and minimal unblock actions.
+- Refresh `AirPlan/todo.md` and the active dispatch block in `AirPlan/plan.md` when a wave starts so execution progress is visible during the run.
+
+## Monitoring Contract
+
+- Store scheduler state in `AirPlan/state/aireng/state.json`.
+- Track `engineMode`, `activeWaveId`, `activeDispatchPath`, `activeWorkers`, `monitoringPolicy`, `nextAction`, and `interventionHistory`.
+- Use `monitoringPolicy.checkIntervalSeconds = 300` as the default cadence for unattended monitoring.
+- Prefer re-dispatch, repair, debug, or other isolated recovery flows before direct intervention.
+- Escalate to user decision only when a worker remains hard-blocked after the allowed intervention budget.
+
+## Merge Guarantees
+
+- Update task status and merge log in `AirPlan/todo.md`.
+- Apply worker `documentUpdates`.
+- Refresh engine-managed sync blocks in `AirPlan/AGENTS.md` and `AirPlan/docs/architecture/c4/module.md`.
+- Track AirXDB sessions in `AirPlan/state/aireng/state.json`.
+- Track debug sessions in `AirPlan/state/aireng/state.json`.
+- Track repair attempts in `AirPlan/state/aireng/state.json`.
+- Refuse a `done` merge when required global document updates are missing.
+- Refuse a GUI-like `done` merge when successful AirXDB evidence is missing.
+- Apply worker `documentUpdates` promptly so plan, ADR, and C4 changes do not lag behind completed slices.
+
+## Commands
+
+```bash
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode enter --project <project-root>
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode status --project <project-root>
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode plan --project <project-root> --todo <airplan-todo-md>
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode dispatch --project <project-root> [--dispatch-group <wave-group-name>]
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode monitor --project <project-root>
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode run --project <project-root> [--todo <airplan-todo-md>]
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode intervene --project <project-root>
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode merge --project <project-root> --result <worker-result-json>
+```
--- a/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/aireng/agents/openai.yaml
+++ b/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/aireng/agents/openai.yaml
@@ -0,0 +1,3 @@
+name: aireng
+short_description: Public Air scheduler for isolated AirDo subagent dispatch and AirPlan merges
+default_prompt: "Use AirEng to read AirArc execution artifacts from AirPlan, dispatch isolated AirDo subagents with bounded concurrency, and merge structured worker results back into AirPlan."
--- a/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airndb/SKILL.md
+++ b/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airndb/SKILL.md
@@ -0,0 +1,214 @@
+---
+name: airndb
+description: Network-debug packet capture workflow. Use when the user invokes /airndb or asks to debug networking, packet loss, DNS, TCP, UDP, TLS handshakes, HTTP connectivity, ports, retransmits, resets, latency, firewall, proxy, service reachability, pcap files, tcpdump, WinDump, remote packet capture over SSH, or BPF filters. Load or initialize AirPlan/AGENTS.md, AirPlan/docs/architecture/adr/ decision records, AirPlan/docs/architecture/c4/module.md, AirPlan/docs/network/airndb-log.md, and AirPlan/docs/network/airndb-captures/; on first startup detect tcpdump/WinDump and on Windows auto-download official WinDump.exe when no capture tool is available; when remote debugging, call the AirNDB remote device helper and auto-configure remote tcpdump/dumpcap when missing; build safe bounded tcpdump/WinDump commands; capture or read pcap artifacts; summarize packet evidence; and maintain AirPlan/AGENTS.md, ADR, C4 module docs, and network debug logs when capture tooling, network boundaries, or debugging decisions change.
+---
+
+# AirNDB
+
+## 核心约束
+
+- 全程使用中文与用户交流，命令、接口名、BPF、日志、路径和协议名保持原文。
+- `/airndb` 专用于网络抓包、pcap 分析和网络层调试证据收集。
+- 只抓取用户授权的本机、项目、测试环境或明确允许的网络流量。
+- 默认不做无界抓包；必须使用包数、超时、时长或轮转上限。
+- 默认先列接口，再确认接口、目标 host/port/protocol/filter、抓包窗口和输出路径。
+- 初次启动必须检测 `tcpdump` / `windump` / `WinDump.exe` 是否可用；Windows 下如果不可用，自动从 WinDump 官方下载页获取 `WinDump.exe`，校验 SHA1 后写入 `AirPlan/state/airndb/tool.env`。
+- 远程设备、测试机、VM 或 SSH 主机上的网络调试，先调用 `$HOME/plugins/airndb/scripts/airndb_remote_device.py`；缺少远程 `tcpdump` / `dumpcap` 时允许脚本自动配置，无法无密码 `sudo` 或无包管理器时停止并提示用户。
+- 自动获取只下载 WinDump 用户态程序，不静默安装 WinPcap/Npcap 抓包驱动；如果接口列举失败，提示用户安装 Npcap 或 WinPcap 并用管理员权限重试。
+- 默认使用 `-nn` 避免 DNS/service-name 解析，使用 `-s 0` 写入完整 pcap。
+- pcap 可能包含凭据、cookie、token、payload、内网地址、主机名或个人信息；对外分享前必须提醒脱敏。
+- 网络证据要写入 `AirPlan/docs/network/airndb-log.md`，pcap/摘要/JSON 报告写入 `AirPlan/docs/network/airndb-captures/`。
+- 根据项目变化维护 `AirPlan/AGENTS.md`、ADR 和 C4 module。
+- 如果需要 WinDump/tcpdump 选项和 BPF 简表，读取 [references/windump-tcpdump-notes.md](references/windump-tcpdump-notes.md)。
+
+## 启动与初始化
+
+进入 `/airndb` 时运行：
+
+```bash
+python "$HOME/plugins/airndb/scripts/airndb_mode.py" --mode enter --project .
+```
+
+如果当前环境没有 `python`，尝试 `py`、`python3` 或用户提供的 Python 绝对路径。脚本不可用时，手动确保以下结构存在：
+
+- `AirPlan/AGENTS.md`
+- `AirPlan/docs/architecture/adr/`
+- `AirPlan/docs/architecture/c4/module.md`
+- `AirPlan/docs/network/airndb-log.md`
+- `AirPlan/docs/network/airndb-captures/`
+- `AirPlan/state/airndb/state.json`
+
+初始化后读取已有内容作为上下文。不要覆盖用户已有正文；只补齐缺失结构或更新 AirNDB 标记块。
+
+## 首次工具配置
+
+`airndb_mode.py --mode enter` 会执行工具自检：
+
+1. 查找显式配置、项目 `AirPlan/state/airndb/tool.env`、环境变量 `AIRNDB_TCPDUMP`、项目 `AirPlan/state/airndb/tools/WinDump.exe`、PATH 中的 `windump` / `WinDump.exe` / `tcpdump`。
+2. 如果找到可用工具，写入或刷新 `AirPlan/state/airndb/tool.env`，后续 `airndb_capture.py` 自动读取。
+3. 如果 Windows 上找不到工具，自动从 WinDump 官方下载地址获取 `WinDump.exe`，校验 SHA1 `d59bc54721951dec855cbb4bbc000f9a71ea4d95`，保存到 `AirPlan/state/airndb/tools/WinDump.exe`，然后写入 `AirPlan/state/airndb/tool.env`。
+4. 如果下载失败或校验失败，停止并提示用户手动安装 `tcpdump` / `WinDump.exe` 或设置 `AIRNDB_TCPDUMP`。
+
+`AirPlan/state/airndb/tool.env` 是本机路径配置，由 `AirPlan/state/airndb/.gitignore` 忽略，不应提交。
+
+注意：WinDump 仍需要抓包驱动。官方 WinDump 安装页要求先安装 WinPcap 3.1 或更新版本；WinPcap 主页提示项目已停止维护并建议 Windows 10 用户使用 Npcap。AirNDB 不静默安装驱动，只负责检测、下载 WinDump.exe 和配置本机路径。
+
+## 远程设备工具配置
+
+当用户说明目标流量发生在远程设备、测试机、服务器、VM、容器宿主机、SSH 主机，或本机抓包看不到目标流量时，不要先使用本机 `airndb_capture.py`。先运行远程设备 helper：
+
+```bash
+python "$HOME/plugins/airndb/scripts/airndb_remote_device.py" --project . --action setup
+```
+
+如果当前环境没有 `python`，尝试 `py`、`python3` 或用户提供的 Python 绝对路径。首次运行会生成 `AirPlan/state/airndb/remote-device.env.example`；把连接信息写入 `AirPlan/state/airndb/remote-device.env` 或当前环境变量：
+
+- `AIRNDB_REMOTE_SSH_TARGET=user@host`
+- `AIRNDB_REMOTE_SSH_PORT=22`
+- `AIRNDB_REMOTE_SSH_OPTIONS=`
+- `AIRNDB_REMOTE_WORKDIR=`
+- `AIRNDB_REMOTE_TCPDUMP=auto`
+- `AIRNDB_REMOTE_CAPTURE_PREFIX=sudo -n`
+
+远程 helper 行为：
+
+- 检查本机 `ssh`、远程连通性和远程工作目录。
+- 探测 `tcpdump`、`dumpcap`、`windump`、`WinDump.exe`。
+- 工具缺失时自动尝试用远端包管理器安装 `tcpdump`，只使用非交互式 `sudo -n`；需要密码、管理员确认或无支持的包管理器时停止并提示用户。
+- 将可复用配置写入 `AirPlan/state/airndb/remote-device.env`，该文件由 `AirPlan/state/airndb/.gitignore` 忽略。
+- 抓包产物拉回 `AirPlan/docs/network/airndb-captures/`，并追加 `AirPlan/docs/network/airndb-log.md`。
+
+常用远程命令：
+
+```bash
+python "$HOME/plugins/airndb/scripts/airndb_remote_device.py" --project . --action interfaces
+python "$HOME/plugins/airndb/scripts/airndb_remote_device.py" --project . --action command --iface <iface> --filter "<bpf>" --count 200
+python "$HOME/plugins/airndb/scripts/airndb_remote_device.py" --project . --action capture --iface <iface> --filter "<bpf>" --count 200 --timeout 30
+```
+
+远程抓包仍必须有明确授权、接口、BPF、包数或超时上限。`AIRNDB_REMOTE_CAPTURE_PREFIX` 默认是 `sudo -n`；如果远端已配置免 sudo 的 capture capability，可改为空或指定更合适的前缀。
+
+## 工作流
+
+1. 明确网络问题：
+   - 现象：连不上、超时、重置、DNS 异常、TLS 握手失败、丢包、延迟、端口不可达、代理/防火墙疑似问题。
+   - 目标：源/目的 host、端口、协议、服务名、容器/VM/WSL/宿主机边界。
+   - 抓包窗口：包数、超时、复现步骤和是否允许保存 payload。
+2. 发现接口：
+   - 本机调试运行 `airndb_capture.py --action interfaces`。
+   - 远程调试运行 `airndb_remote_device.py --action interfaces`。
+   - Windows 优先使用 `windump -D` 或 `WinDump.exe -D`；Linux/macOS 优先 `tcpdump -D`。
+3. 设计过滤器：
+   - 使用最窄可行 BPF：`host`、`src host`、`dst host`、`port`、`tcp`、`udp`、`icmp`、`net`。
+   - 不确定时先短时宽过滤，再根据结果收窄。
+4. 执行有界抓包：
+   - 使用 `airndb_capture.py --action capture --iface <iface> --filter "<bpf>" --count <n> --timeout <seconds>`。
+   - 产物写入 `AirPlan/docs/network/airndb-captures/`。
+5. 读取和分析：
+   - 使用 `airndb_capture.py --action read --read-file <pcap> --filter "<bpf>"` 生成文本摘要。
+   - 结合时间线、TCP flags、重传、RST、DNS 响应、ICMP、TLS ClientHello/ServerHello 迹象判断网络层事实。
+6. 记录证据：
+   - exact command
+   - interface
+   - BPF filter
+   - packet count or timeout
+   - pcap path
+   - summary/report path
+   - 观察结论、限制和剩余风险
+
+## 与 AirDbg 协作
+
+- AirNDB 负责抓包、pcap 摘要、网络层证据和过滤器。
+- AirDbg 负责代码层根因分析、修复和验证收尾。
+- AirDbg 调试中遇到 DNS、TCP、UDP、TLS、HTTP 连接、端口、代理、防火墙、丢包、重传或 pcap 证据需求时，可以调用 AirNDB。
+- AirNDB 收集到的证据必须能被 AirDbg 直接引用：命令、pcap 路径、摘要、关键包、时间线和结论要写清楚。
+
+## 常用命令
+
+列接口：
+
+```bash
+python "$HOME/plugins/airndb/scripts/airndb_capture.py" --project . --action interfaces
+```
+
+检查或初始化工具路径：
+
+```bash
+python "$HOME/plugins/airndb/scripts/airndb_mode.py" --project . --mode enter
+```
+
+只生成命令：
+
+```bash
+python "$HOME/plugins/airndb/scripts/airndb_capture.py" --project . --action command --iface 1 --filter "tcp and port 443" --count 200
+```
+
+短时抓包：
+
+```bash
+python "$HOME/plugins/airndb/scripts/airndb_capture.py" --project . --action capture --iface 1 --filter "tcp and port 443" --count 200 --timeout 30
+```
+
+读取 pcap：
+
+```bash
+python "$HOME/plugins/airndb/scripts/airndb_capture.py" --project . --action read --read-file AirPlan/docs/network/airndb-captures/example.pcap
+```
+
+## AGENTS.md 维护
+
+在以下情况更新 `AGENTS.md`：
+
+- 发现稳定可复用的 tcpdump/WinDump 命令、接口选择规则、BPF 过滤器或 pcap 读取方式。
+- 发现影响后续 AI 调试的网络边界：容器、WSL、VM、代理、防火墙、VPN、DNS、TLS、NAT、端口映射。
+- 发现抓包权限、驱动、管理员权限或平台差异。
+- 发现本机 tcpdump/WinDump 路径或 `AirPlan/state/airndb/tool.env` 配置方式。
+- 发现远程设备 SSH 入口、远程抓包工具、`AIRNDB_REMOTE_*` 配置方式或远端抓包权限限制。
+
+## ADR 维护
+
+目录：`docs/architecture/adr/`。
+
+需要 ADR 的情况：
+
+- 长期采用 tcpdump/WinDump 作为项目网络诊断方式。
+- 抓包流程改变了测试边界、网络观测边界、运行权限、数据留存或安全策略。
+- 发现需要保留的网络架构决策，例如代理、DNS、TLS、端口、服务发现或跨容器/宿主机边界。
+
+ADR 保持简洁：Context、Decision、Consequences、Alternatives。
+
+## C4 Module 维护
+
+文件：`docs/architecture/c4/module.md`。
+
+当网络调试发现或改变以下内容时，必须更新：
+
+- 模块间网络依赖。
+- 服务端口、协议、DNS、代理、TLS、队列、网关、容器/宿主机/WSL/VM 边界。
+- 抓包或观测基础设施成为长期模块或运行边界。
+- 网络错误处理、重试、超时、连接池或安全边界。
+
+## network log 维护
+
+文件：`AirPlan/docs/network/airndb-log.md`。
+
+每次 AirNDB 会话至少追加：
+
+- 问题摘要。
+- 授权范围和目标流量。
+- 接口、BPF、抓包窗口。
+- 是否使用远程设备 helper 以及远程目标、抓包工具和权限限制。
+- pcap/summary/report 路径。
+- 关键包或时间线观察。
+- 结论、限制和给 AirDbg 的线索。
+- ADR/C4/AGENTS 更新。
+
+## 完成输出
+
+本轮网络调试结束时，用中文简洁汇报：
+
+- 使用了哪个接口和过滤器。
+- 抓包是否成功，证据在哪里。
+- 关键观察和网络层结论。
+- 更新了哪些 `AGENTS.md` / ADR / C4 / network log。
+- 是否需要切给 AirDbg 做代码层修复。
--- a/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airndb/agents/openai.yaml
+++ b/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airndb/agents/openai.yaml
@@ -0,0 +1,3 @@
+name: airndb
+short_description: Local and remote packet capture workflow with tcpdump and WinDump
+default_prompt: "使用 AirNDB 做安全有界抓包；远程设备优先调用 remote device helper 并自动配置 tcpdump。"
--- a/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airndb/references/windump-tcpdump-notes.md
+++ b/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airndb/references/windump-tcpdump-notes.md
@@ -0,0 +1,83 @@
+# WinDump / Tcpdump Notes
+
+Source: https://www.winpcap.org/windump/docs/manual.htm
+
+## AirNDB Summary
+
+- WinDump follows tcpdump-style packet capture usage on Windows.
+- `-D` lists available capture interfaces.
+- `-i <interface>` selects the capture interface. On Windows this is often the interface number from `-D`.
+- `-c <count>` stops after a bounded number of packets.
+- `-w <file>` writes raw packets to a pcap file.
+- `-r <file>` reads packets back from a pcap file.
+- `-n` avoids host name resolution; `-nn` also avoids service name resolution.
+- `-s <snaplen>` controls packet snapshot length. AirNDB uses `-s 0` for pcap captures so packets are not truncated.
+- Filter expressions use BPF primitives such as `host`, `net`, `port`, `src`, `dst`, `tcp`, `udp`, `icmp`, `arp`, `and`, `or`, and `not`.
+
+## Windows Notes
+
+- Prefer `WinDump.exe` or `windump` when `tcpdump` is unavailable on Windows.
+- WinDump normally requires a packet capture driver such as WinPcap/Npcap and may require an elevated terminal.
+- Interface names can be long adapter paths; the numeric index from `windump -D` is usually easier to use.
+- Store pcap artifacts in a project-local ignored directory such as `docs/network/airndb-captures/`.
+
+## AirNDB Auto Setup
+
+- On `/airndb enter`, AirNDB checks for `tcpdump`, `windump`, or `WinDump.exe`.
+- If no capture tool is available on Windows, AirNDB downloads the official `WinDump.exe` linked from the WinDump install page:
+
+```text
+https://www.winpcap.org/windump/install/bin/windump_3_9_5/WinDump.exe
+```
+
+- AirNDB verifies SHA1 before using the file:
+
+```text
+d59bc54721951dec855cbb4bbc000f9a71ea4d95
+```
+
+- AirNDB stores the binary at `AirPlan/state/airndb/tools/WinDump.exe` and writes `AirPlan/state/airndb/tool.env`:
+
+```text
+AIRNDB_TCPDUMP=<absolute path to WinDump.exe>
+```
+
+- AirNDB does not silently install WinPcap/Npcap drivers. If `WinDump.exe -D` fails after download, tell the user to install Npcap or WinPcap and retry from an elevated terminal.
+
+## Safe Defaults
+
+- Start with interface discovery before capture:
+
+```bash
+windump -D
+tcpdump -D
+```
+
+- Prefer short, bounded capture:
+
+```bash
+tcpdump -i <iface> -nn -s 0 -w <file>.pcap -c 200 '<bpf>'
+```
+
+- Read back a pcap summary:
+
+```bash
+tcpdump -nn -r <file>.pcap '<bpf>'
+```
+
+## BPF Examples
+
+```text
+host 192.0.2.10
+tcp and port 443
+udp and port 53
+src host 192.0.2.10 and dst port 443
+net 10.0.0.0/8 and not port 22
+icmp or icmp6
+```
+
+## Evidence Rules
+
+- Record exact command, interface, filter, packet count, capture window, pcap path, and summary path.
+- Keep pcap files private unless reviewed; they can contain tokens, cookies, payload, internal hostnames, and addresses.
+- If application payload is encrypted, use packet timing, DNS, TCP/TLS handshakes, retransmissions, resets, or connection failures as evidence instead of expecting plaintext.
--- a/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airsdb/SKILL.md
+++ b/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airsdb/SKILL.md
@@ -0,0 +1,166 @@
+---
+name: airsdb
+description: Cppcheck static-analysis workflow for C/C++ projects. Use when the user invokes /airsdb, asks to run static analysis, evaluate code quality or security with cppcheck, generate a short AI-context static-analysis report for AirDbg or AirDo, diagnose issues that need static analysis, maintain AirPlan/docs/staticanalysis.md, or run local/remote cppcheck over SSH. On first startup detect cppcheck and auto-install or auto-configure it when missing; default local and remote scans to `--check-level=exhaustive` for maximum branch-analysis detail; and call the AirSDB remote device helper when remote cppcheck is needed.
+---
+
+# AirSDB
+
+## 核心约束
+
+- 全程使用中文与用户交流，命令、路径、工具名、告警 id、CWE 保持原文。
+- `/airsdb` 专用于 C/C++ 静态分析、代码质量/安全性初筛、cppcheck 证据收集，以及给 AirDbg/AirDo 提供简短 AI 上下文报告。
+- 第一次进入必须检测 `cppcheck`。本机缺失时自动尝试用包管理器安装或配置；无法自动安装时停止并提示官方下载页或 `AIRSDB_CPPCHECK`。
+- 必须创建或维护 `AirPlan/docs/staticanalysis.md`。它只写简短摘要，详细 XML/JSON 产物放在 `AirPlan/state/airsdb/reports/`。
+- 本机分析使用 `$HOME/plugins/airsdb/scripts/airsdb_cppcheck.py`。
+- 远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上的静态分析，先使用 `$HOME/plugins/airsdb/scripts/airsdb_remote_device.py`；远端缺少 `cppcheck` 时允许脚本自动配置，无法无密码 `sudo` 或无包管理器时停止并提示用户。
+- 优先使用 `compile_commands.json`；没有时只扫描最窄可行目录，并排除 `.git`、`AirPlan/state/airsdb`、`build`、`node_modules`、`vendor`、`third_party` 等常见噪声目录。
+- 默认使用 `--check-level=exhaustive`，尽可能提供详细分支分析信息，避免出现 `normalCheckLevelMaxBranches` 这类因分支分析深度受限造成的信息缺口；只有用户明确要求降级时才改。
+- Cppcheck 是静态分析，不等同于编译、测试或安全审计；结论要写成“证据/线索”，不要夸大。
+- 如果需要 cppcheck 安装和命令细节，读取 [references/cppcheck-notes.md](references/cppcheck-notes.md)。
+
+## 启动与环境检测
+
+进入 `/airsdb` 时运行：
+
+```bash
+python "$HOME/plugins/airsdb/scripts/airsdb_mode.py" --mode enter --project .
+```
+
+如果当前环境没有 `python`，尝试 `py`、`python3` 或用户提供的 Python 绝对路径。
+
+脚本会：
+
+- 初始化 `AirPlan/state/airsdb/`、`AirPlan/state/airsdb/tool.env.example`、`AirPlan/state/airsdb/.gitignore`。
+- 创建或维护 `AirPlan/docs/staticanalysis.md`。
+- 在 `AirPlan/AGENTS.md` 中维护 AirSDB 标记块。
+- 检测 `AIRSDB_CPPCHECK`、`AirPlan/state/airsdb/tool.env`、PATH 和常见 Windows 安装路径。
+- 找不到 `cppcheck` 时自动尝试安装：
+  - Windows：`winget`、`choco`、`scoop`
+  - Linux/macOS：`apt-get`、`dnf`、`yum`、`apk`、`pacman`、`brew`、`port`
+
+`AirPlan/state/airsdb/tool.env` 是本机路径配置，由 `AirPlan/state/airsdb/.gitignore` 忽略，不应提交。
+
+## 本机分析
+
+检查或安装 cppcheck：
+
+```bash
+python "$HOME/plugins/airsdb/scripts/airsdb_cppcheck.py" --project . --action setup
+```
+
+只生成命令：
+
+```bash
+python "$HOME/plugins/airsdb/scripts/airsdb_cppcheck.py" --project . --action command
+```
+
+执行扫描：
+
+```bash
+python "$HOME/plugins/airsdb/scripts/airsdb_cppcheck.py" --project . --action scan --timeout 900
+```
+
+常用参数：
+
+- `--project-file build/compile_commands.json`：指定编译数据库。
+- `--target src`：没有编译数据库时限制扫描目录。
+- `--enable warning,style,performance,portability,information`：默认检查集合。
+- `--check-level exhaustive`：默认详细分支分析级别。
+- `--std c++17`：指定 C/C++ 标准。
+- `--extra "--suppress=missingIncludeSystem"`：追加 cppcheck 参数。
+
+扫描后必须确认：
+
+- `AirPlan/state/airsdb/reports/<timestamp>-cppcheck.xml`
+- `AirPlan/state/airsdb/reports/<timestamp>-cppcheck.json`
+- `AirPlan/docs/staticanalysis.md` 已追加简短报告
+
+## 远程设备分析
+
+当目标代码或复现场景在远程设备上时，不要先跑本机 cppcheck。先运行：
+
+```bash
+python "$HOME/plugins/airsdb/scripts/airsdb_remote_device.py" --project . --action setup
+```
+
+首次运行会生成 `AirPlan/state/airsdb/remote-device.env.example`。将连接信息写入 `AirPlan/state/airsdb/remote-device.env` 或当前环境变量：
+
+- `AIRSDB_REMOTE_SSH_TARGET=user@host`
+- `AIRSDB_REMOTE_SSH_PORT=22`
+- `AIRSDB_REMOTE_SSH_OPTIONS=`
+- `AIRSDB_REMOTE_WORKDIR=`
+- `AIRSDB_REMOTE_PROJECT=/path/to/remote/project`
+- `AIRSDB_REMOTE_CPPCHECK=auto`
+
+远程 helper 行为：
+
+- 检查本机 `ssh`、远程连通性、远程工作目录。
+- 探测远端 `cppcheck`。
+- 缺失时自动尝试用远端包管理器安装 `cppcheck`，只使用非交互式 `sudo -n`；需要密码、管理员确认或无支持包管理器时停止并提示用户。
+- 在远端项目目录运行 cppcheck，把 XML 拉回本机 `AirPlan/state/airsdb/reports/` 并更新本机 `AirPlan/docs/staticanalysis.md`。
+
+远程命令：
+
+```bash
+python "$HOME/plugins/airsdb/scripts/airsdb_remote_device.py" --project . --action command
+python "$HOME/plugins/airsdb/scripts/airsdb_remote_device.py" --project . --action scan --timeout 900
+```
+
+## 与 AirDbg 协作
+
+AirDbg 调试中遇到以下情况时调用 AirSDB：
+
+- 需要用静态分析辅助定位崩溃、内存错误、未初始化变量、空指针、越界、危险转换、资源释放或 CWE 线索。
+- 需要在修复前后比较 cppcheck 结果。
+- 需要给根因分析提供短报告，而不是完整 XML 噪声。
+
+AirSDB 给 AirDbg 的交接必须写入 `AirPlan/docs/staticanalysis.md`：
+
+- 命令和目标
+- XML/JSON 报告路径
+- severity/id/CWE 计数
+- Top findings
+- 哪些 findings 与当前 bug 相关
+- 剩余风险
+
+## 与 AirDo 协作
+
+AirDo 执行 `AirPlan/todo.md` 时可以调用 AirSDB 做验收或排障：
+
+- todo 要求静态分析、质量检查、安全性初筛或 C/C++ 代码风险评估。
+- 验证失败但需要 cppcheck 辅助定位。
+- 远程设备上的实现需要远端 cppcheck 证据。
+
+AirDo 仍然拥有 `AirPlan/todo.md` 进度。调用 AirSDB 后，把命令、报告路径、结论和剩余风险写回当前 todo 项。
+
+## staticanalysis.md 维护
+
+每次 AirSDB 扫描至少追加：
+
+- Target：local 或 remote target
+- Tool：cppcheck 路径和版本
+- Command：实际命令
+- Result：ok / findings / failed
+- Counts：各 severity 数量
+- Reports：XML/JSON 路径
+- Top findings：最多 12 条，含 severity、id、CWE、文件行号、摘要
+- AirDbg/AirDo handoff：当前任务如何使用这些结果
+- Residual risk：静态分析未覆盖的风险
+
+不要把完整 XML、长日志或大段 cppcheck 输出塞进 `staticanalysis.md`。
+
+## AGENTS / ADR / C4
+
+- 发现稳定可复用的 AirSDB 命令、远程设备配置、过滤策略、suppressions 或质量门槛时，更新 `AGENTS.md`。
+- 如果静态分析成为长期测试/调试边界，或影响模块边界、质量策略、安全策略、CI 策略，更新 C4 module 并新增或修订 ADR。
+- 如果只是一次临时扫描，只维护 `staticanalysis.md` 即可。
+
+## 完成输出
+
+本轮结束时用中文简洁汇报：
+
+- 使用本机还是远程 cppcheck。
+- cppcheck 是否可用，是否发生自动配置。
+- 报告路径和 `staticanalysis.md` 是否更新。
+- 发现数量和最重要的 3-5 条线索。
+- 是否建议交给 AirDbg 修复，或交给 AirDo 写回 todo 验收。
--- a/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airsdb/agents/openai.yaml
+++ b/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airsdb/agents/openai.yaml
@@ -0,0 +1,3 @@
+name: airsdb
+short_description: Cppcheck static analysis with exhaustive local/remote reports
+default_prompt: "使用 AirSDB 运行本机或远程 cppcheck 静态分析，默认启用 --check-level=exhaustive，生成简短 staticanalysis.md 报告并交给 AirDbg/AirDo 使用。"
--- a/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airsdb/references/cppcheck-notes.md
+++ b/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airsdb/references/cppcheck-notes.md
@@ -0,0 +1,27 @@
+# Cppcheck Notes
+
+Use this only when AirSDB needs cppcheck install or command details.
+
+## Sources
+
+- Official open-source download page: https://cppcheck.sourceforge.io/
+- Official repository package notes: https://github.com/danmar/cppcheck
+- Official manual: https://cppcheck.sourceforge.io/manual.html
+- User-provided Chinese guide: https://www.zeeklog.com/cppcheckzhong-ji-zhi-nan-cong-ling-kai-shi-zhang-wo-c-c-jing-tai-dai-ma-fen-xi
+- User-provided download reference: http://cppcheck.net/#download
+
+## Install Notes
+
+- The official page lists current open-source releases and package-manager examples.
+- Windows official installer is linked from the Cppcheck open-source page.
+- Package managers can be convenient but may lag behind official releases.
+- AirSDB auto-configures with package managers first because it must be non-interactive for agent workflows.
+
+## Command Notes
+
+- Prefer `cppcheck --project=compile_commands.json` when the project has a compilation database.
+- Generate a CMake compilation database with `cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .` when appropriate.
+- Use `--xml --xml-version=2` for machine-readable reports.
+- Use `--cppcheck-build-dir=<path>` for incremental analysis and better whole-program analysis.
+- Use `-i<path>` to skip generated/vendor directories.
+- Use suppressions instead of deleting warnings when a finding is a known false positive.
--- a/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airxdb/SKILL.md
+++ b/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airxdb/SKILL.md
@@ -0,0 +1,263 @@
+---
+name: airxdb
+description: Midscene-based GUI debugging workflow. Use when the user invokes /airxdb, asks to debug browser UI, desktop UI, canvas UI, visual regressions, flaky interface interactions, remote GUI/device debugging over SSH, or reproduce graphical issues with Midscene.js. Load or initialize AirPlan/AGENTS.md, AirPlan/docs/architecture/adr/ decision records, and AirPlan/docs/architecture/c4/module.md; collaborate with AirDbg for GUI issues; choose the right Midscene mode for Playwright, Chrome bridge mode, desktop computer automation, MCP, or the AirXDB remote device helper; auto-configure remote screenshot tooling when missing; generate visual reproduction steps and reports; and maintain AirPlan/AGENTS.md, ADR, C4 module, and GUI debug logs whenever GUI-debug tooling or interface behavior changes.
+---
+
+# AirXDB
+
+## 核心约束
+
+- 全程使用中文与用户交流，代码、命令、日志、路径、包名保持原文。
+- `/airxdb` 专用于图形界面和视觉交互层面的调试，不替代 `airdbg` 的通用根因分析职责。
+- 优先与 `airdbg` 配合：
+  - `airxdb` 负责界面复现、视觉定位、交互自动化、Midscene 报告与截图证据。
+  - `airdbg` 负责代码层根因、最小修复、测试验证和通用调试收尾。
+- 先加载或初始化上下文：`AirPlan/AGENTS.md`、`AirPlan/docs/architecture/adr/`、`AirPlan/docs/architecture/c4/module.md`、`AirPlan/docs/debug/gui-debug-log.md`。
+- 如果这些文件不存在，先分析当前项目并初始化它们；C4 module 要反映真实模块边界，尤其是前端、UI、桌面桥接、自动化测试相关边界。
+- Midscene 路线优先使用视觉复现和 HTML 报告收集证据，不把 GUI 调试退化成纯日志猜测。
+- 截图取证是 AirXDB 的一等能力：即使没有语义模型配置，也可以连接 Computer MCP 截图，为 `airdbg` 提供错误现场、布局状态、弹窗、焦点和多显示器信息。
+- 远程设备、测试机、VM 或 SSH 主机上的 GUI 调试，先调用 `$HOME/plugins/airxdb/scripts/airxdb_remote_device.py`；缺少远程截图工具时允许脚本自动配置，无法无密码 `sudo` 或无包管理器时停止并提示用户。
+- 优先做最小可验证复现和最小必要修复，不顺手大改界面架构。
+- GUI 调试过程中，一定要维护 `AirPlan/AGENTS.md`、ADR、C4 module 和 `AirPlan/docs/debug/gui-debug-log.md`。
+- 如果需要 Midscene 包名、桥接/MCP 配置、常用命令，读取 [references/midscene-official-notes.md](references/midscene-official-notes.md)。
+
+## 启动与初始化
+
+进入 `/airxdb` 时运行：
+
+```bash
+python "$HOME/plugins/airxdb/scripts/airxdb_mode.py" --mode enter --project .
+```
+
+如果当前环境没有 `python`，尝试 `py` 或 `python3`。脚本不可用时，手动确保以下结构存在：
+
+- `AirPlan/AGENTS.md`
+- `AirPlan/docs/architecture/adr/`
+- `AirPlan/docs/architecture/c4/module.md`
+- `AirPlan/docs/debug/gui-debug-log.md`
+- `AirPlan/state/airxdb/state.json`
+
+初始化后读取已有内容作为上下文。不要覆盖用户已有正文；只补齐缺失结构或更新 AirXDB 标记块。
+
+## 首次模型配置
+
+AirXDB 第一次进入项目时必须检查 Midscene 模型配置。`airxdb_mode.py` 会输出 `midscene_config`，如果出现 `midscene_config_required=true` 或 `midscene_config=missing:...`：
+
+- 暂停执行 `act`、`Tap`、`Input`、`KeyboardPress`、视觉定位等语义动作。
+- 用中文向用户索取配置：
+  - `MIDSCENE_MODEL_NAME`
+  - `MIDSCENE_MODEL_BASE_URL`
+  - `MIDSCENE_MODEL_API_KEY`
+  - `MIDSCENE_MODEL_FAMILY`
+  - 可选：`MCP_SERVER_REQUEST_TIMEOUT`
+- 告知用户可以只在当前会话设置环境变量，或写入 `AirPlan/state/airxdb/midscene.local.env` 方便后续复用。
+- `AirPlan/state/airxdb/midscene.local.env` 只保存本机密钥，默认由 `AirPlan/state/airxdb/.gitignore` 忽略；不要把真实 API key 写入 `AirPlan/AGENTS.md`、ADR、C4 或 debug log。
+- 如果用户暂时不提供模型配置，仍然可以做截图、MCP 连接、显示器枚举、环境探测等非语义取证操作；不能声称完成了 Midscene 视觉语义操作。
+- `MIDSCENE_MODEL_FAMILY` 是语义视觉动作必填项。`gpt-5.4` 这类 GPT-5.x 视觉模型使用 `gpt-5`。
+- 常见合法 family：`gpt-5`、`qwen2.5-vl`、`qwen3-vl`、`gemini`、`doubao-seed`、`vlm-ui-tars`。
+
+## 截图取证模式
+
+当用户需要给 `airdbg` 提供错误诊断信息、GUI 现场、弹窗、焦点状态、布局错位或多显示器证据时，优先使用截图取证模式：
+
+```bash
+python "$HOME/plugins/airxdb/scripts/airxdb_computer_mcp_smoke.py" --project . --action screenshot
+```
+
+截图取证模式不要求 `MIDSCENE_MODEL_NAME`、`MIDSCENE_MODEL_BASE_URL`、`MIDSCENE_MODEL_API_KEY` 或 `MIDSCENE_MODEL_FAMILY`。它只验证 Computer MCP 桌面连接和截图能力，并将截图/JSON 报告写入 `AirPlan/docs/debug/airxdb-artifacts/`。
+
+截图后必须在 `AirPlan/docs/debug/gui-debug-log.md` 追加：
+
+- 截图目标和平台
+- 截图文件路径
+- 当前界面关键观察
+- 给 `airdbg` 的诊断线索
+- 是否还需要语义视觉动作或代码层修复
+
+如果截图可能包含密钥、聊天内容、账号、客户数据或隐私信息，在对外分享前提醒用户脱敏。
+
+## 远程设备截图模式
+
+当用户说明目标在远程设备、测试机、服务器、VM、SSH 主机，或当前桌面不是目标 GUI 所在机器时，不要先使用本机 Computer MCP。先运行远程设备 helper：
+
+```bash
+python "$HOME/plugins/airxdb/scripts/airxdb_remote_device.py" --project . --action setup
+```
+
+如果当前环境没有 `python`，尝试 `py`、`python3` 或用户提供的 Python 绝对路径。首次运行会生成 `AirPlan/state/airxdb/remote-device.env.example`；把连接信息写入 `AirPlan/state/airxdb/remote-device.env` 或当前环境变量：
+
+- `AIRXDB_REMOTE_SSH_TARGET=user@host`
+- `AIRXDB_REMOTE_SSH_PORT=22`
+- `AIRXDB_REMOTE_SSH_OPTIONS=`
+- `AIRXDB_REMOTE_WORKDIR=`
+- `AIRXDB_REMOTE_SCREENSHOT_TOOL=auto`
+- `AIRXDB_REMOTE_DISPLAY=`
+
+远程 helper 行为：
+
+- 检查本机 `ssh`、远程连通性和远程工作目录。
+- 探测 `gnome-screenshot`、`spectacle`、`scrot`、`grim`、`import`、`screencapture`。
+- 工具缺失时自动尝试用远端包管理器安装 `scrot`，只使用非交互式 `sudo -n`；需要密码、管理员确认或无支持的包管理器时停止并提示用户。
+- 将可复用配置写入 `AirPlan/state/airxdb/remote-device.env`，该文件由 `AirPlan/state/airxdb/.gitignore` 忽略。
+
+远程截图：
+
+```bash
+python "$HOME/plugins/airxdb/scripts/airxdb_remote_device.py" --project . --action screenshot
+```
+
+远程截图和 JSON 报告写入 `AirPlan/docs/debug/airxdb-artifacts/`，并追加 `AirPlan/docs/debug/gui-debug-log.md`。远程截图只能证明远端截图链路和当前 GUI 现场；如果需要 Midscene 语义视觉动作，仍需单独确认远端或本机可用的 Midscene 接入方式。
+
+## Computer MCP 快速验证
+
+验证桌面 GUI 能力时优先运行 smoke test 脚本，而不是临时拼 MCP 客户端：
+
+```bash
+python "$HOME/plugins/airxdb/scripts/airxdb_computer_mcp_smoke.py" --project . --action mousemove --prompt "Windows taskbar Start button"
+```
+
+如果当前环境没有 `python`，尝试 `py`、`python3` 或用户提供的 Python 绝对路径。
+
+脚本行为：
+
+- 加载 `AirPlan/state/airxdb/midscene.local.env`，但输出和 JSON 报告会屏蔽 API key；`--action screenshot` 不要求模型配置。
+- 启动 `@midscene/computer-mcp` HTTP 服务。
+- Windows 下自动检查并修复 `screenCapture_1.3.2.bat` / `app.manifest` 缺失问题；修复来源是 `screenshot-desktop@1.15.3` 官方 npm 包。
+- 执行 `computer_connect`、可选语义动作、`take_screenshot`、`computer_disconnect`。
+- 证据写入 `docs/debug/airxdb-artifacts/`，包括截图和 `airxdb-smoke.json` 报告。
+
+结果判断：
+
+- `airxdb_smoke=ok` 才能说明 Computer MCP 视觉链路通过。
+- 如果只完成截图，没有完成 `MouseMove` / `act` / `Tap` 等语义动作，只能说“截图/连接可用”，不能说“视觉语义操作已通过”。
+- 如果报 `MIDSCENE_MODEL_FAMILY is not set to a visual language model`，先补 family；`gpt-5.4` 用 `gpt-5`。
+- Windows 开始菜单 + 中文输入法场景下，输入查询词后可能需要双回车：第一次提交输入法，第二次执行启动。
+
+## Midscene 模式选择
+
+先判断目标界面和现有技术栈，再选 Midscene 模式：
+
+1. Web + 已有 Playwright：
+   - 优先使用 Midscene 的 Playwright 集成。
+   - 适合已有 E2E、页面复现、交互不稳定、视觉断言场景。
+2. Web + 需要复用本地 Chrome 状态：
+   - 使用 Chrome Bridge Mode。
+   - 适合需要复用 cookies、扩展、已登录会话、人工介入浏览器态的场景。
+3. 桌面应用 GUI：
+   - 使用 Midscene Computer / Playground。
+   - 适合 Electron、Qt、WPF、原生应用和跨应用流程。
+4. 远程设备 GUI：
+   - 先使用 AirXDB remote device helper 取证和自动配置远端截图工具。
+   - 适合 SSH 可达的测试机、VM、服务器桌面或远程 Linux/macOS GUI。
+5. 需要把 GUI 操作暴露给上层 Agent 或工具链：
+   - 使用 Midscene MCP。
+   - 浏览器优先 Web Bridge MCP，桌面优先 Computer MCP。
+
+不确定时，一次只问一个关键问题：
+
+- 这是浏览器页面还是桌面应用？
+- 项目里是否已有 Playwright？
+- 是否必须复用本机浏览器登录态？
+- 是要快速复现，还是要沉淀成长期自动化脚本？
+
+## GUI 调试流程
+
+1. 明确问题边界：
+   - 哪个界面、哪条交互链路、什么平台。
+   - 期望行为和实际行为。
+   - 是否涉及视觉错位、点击不到、浮层遮挡、Canvas、焦点问题、窗口切换、多显示器等。
+2. 加载上下文：
+   - 读取 `AGENTS.md`。
+   - 读取相关 ADR。
+   - 读取 `docs/architecture/c4/module.md`。
+   - 查看前端/桌面自动化相关代码、测试、构建配置。
+3. 选择 Midscene 模式并做最小复现：
+   - Playwright
+   - Chrome Bridge
+   - Computer / Playground
+   - MCP
+4. 生成可回放证据：
+   - Midscene HTML 报告
+   - 关键截图
+   - 复现命令
+   - 相关日志和报错
+5. 将证据和观察写入 `AirPlan/docs/debug/gui-debug-log.md`。
+6. 如果问题只是界面复现层，继续用 `airxdb` 深挖。
+7. 如果已定位到代码层根因，转入或并行配合 `airdbg` 做修复。
+8. 修复后再次用 Midscene 复跑关键 GUI 路径，确认问题关闭。
+
+## 与 AirDbg 的协作
+
+- `airxdb` 先做：
+  - GUI 复现
+  - 视觉定位
+  - 界面交互脚本/桥接/MCP 配置
+  - 报告与截图证据
+- `airdbg` 再做：
+  - 根因代码分析
+  - 修复实现
+  - 测试验证
+  - 风险收尾
+
+如果当前问题同时包含“界面复现难”和“代码根因不明”，先用 `airxdb` 稳定复现，再把复现结论和报告交给 `airdbg`。
+
+## AGENTS.md 维护
+
+在以下情况更新 `AGENTS.md`：
+
+- 发现新的 GUI 调试命令、Playwright 命令、Midscene 运行方式。
+- 发现系统权限要求，例如桌面自动化权限、屏幕录制权限、多显示器限制。
+- 发现影响后续 GUI 调试的重要约束，如浏览器桥接、登录态、测试环境、显示缩放。
+- 发现远程设备 SSH 入口、远程截图工具、`AIRXDB_REMOTE_*` 配置方式或远端显示环境限制。
+- 引入了新的 GUI 自动化脚本、报告目录或运行前置条件。
+
+内容保持可执行、可复用，不写流水账。
+
+## ADR 维护
+
+目录：`docs/architecture/adr/`。
+
+需要 ADR 的情况：
+
+- 决定长期采用某种 Midscene 接入方式，例如 Playwright 集成、Bridge Mode、Computer、MCP。
+- GUI 调试方案改变了测试边界、前端交互契约、浏览器控制方式、桌面自动化权限模型。
+- 为了稳定复现而新增长期保留的自动化脚本、报告流程或辅助基础设施。
+
+ADR 保持简洁：Context、Decision、Consequences、Alternatives。
+
+## C4 Module 维护
+
+文件：`docs/architecture/c4/module.md`。
+
+当 GUI 调试或修复改变以下内容时，必须更新：
+
+- 前端模块边界
+- 自动化测试边界
+- 浏览器桥接/桌面控制边界
+- 报告和调试基础设施
+- UI 层和服务层之间的数据所有权或依赖
+
+## GUI Debug Log 维护
+
+文件：`AirPlan/docs/debug/gui-debug-log.md`。
+
+每次 AirXDB 会话至少追加：
+
+- 问题摘要
+- 目标平台和界面
+- Midscene 模式（Playwright / Bridge / Computer / MCP）
+- 是否使用远程设备 helper 以及远程目标、截图工具和限制
+- 复现步骤或命令
+- 报告文件路径
+- 截图或关键观察
+- 转交给 `airdbg` 的结论，或已完成的修复验证
+- 剩余风险
+
+## 输出格式
+
+本轮 GUI 调试结束时，用中文简洁汇报：
+
+- 选择了哪种 Midscene 模式，为什么。
+- 复现是否成功，证据在哪里。
+- 更新了哪些 `AGENTS.md` / ADR / C4 / GUI debug log。
+- 是否需要切给 `airdbg` 继续做代码层修复。
--- a/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airxdb/agents/openai.yaml
+++ b/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airxdb/agents/openai.yaml
@@ -0,0 +1,3 @@
+name: airxdb
+short_description: Midscene GUI debug workflow with local and remote screenshot evidence
+default_prompt: "使用 AirXDB 配合 AirDbg 做图形界面调试；远程设备优先调用 remote device helper 并自动配置截图工具。"
--- a/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airxdb/references/midscene-official-notes.md
+++ b/AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airxdb/references/midscene-official-notes.md
@@ -0,0 +1,159 @@
+# Midscene Official Notes
+
+用于 `airxdb` 的轻量参考，不替代官方文档。
+
+## 选择模式
+
+- Web + 现有 Playwright 项目：
+  - 优先 Midscene Playwright 集成
+  - 适合浏览器页面复现、E2E、界面交互不稳定问题
+- Web + 需要复用本机 Chrome 的 cookies / 已登录状态 / 扩展：
+  - 使用 Chrome Bridge Mode
+- 桌面应用 GUI：
+  - 使用 Midscene Computer 或 Playground
+- 需要给上层 Agent / MCP 客户端暴露 GUI 操作：
+  - 浏览器用 Web Bridge MCP
+  - 桌面用 Computer MCP
+
+## 关键能力
+
+- Midscene 的 UI 操作以纯视觉为主，可用于 Web、移动端、桌面端和 Canvas。
+- Midscene 支持生成 HTML 报告，适合作为 GUI debug 证据。
+- Midscene 可通过 MCP 暴露截图和动作空间操作。
+
+## 首次模型配置
+
+AirXDB 第一次进入项目时先检查这些变量：
+
+```bash
+MIDSCENE_MODEL_NAME
+MIDSCENE_MODEL_BASE_URL
+MIDSCENE_MODEL_API_KEY
+MIDSCENE_MODEL_FAMILY
+MCP_SERVER_REQUEST_TIMEOUT
+```
+
+前三个是连接模型服务的基本配置。`MIDSCENE_MODEL_FAMILY` 是视觉语义动作必填项，`MCP_SERVER_REQUEST_TIMEOUT` 按模型服务情况补充。
+
+常见 `MIDSCENE_MODEL_FAMILY`：
+
+- `gpt-5`：GPT-5.x 视觉模型，例如 `gpt-5.4`
+- `qwen2.5-vl`
+- `qwen3-vl`
+- `gemini`
+- `doubao-seed`
+- `vlm-ui-tars`
+
+不要把真实 API key 写入 ADR、C4、debug log 或可提交文档。需要本机持久化时优先使用 `AirPlan/state/airxdb/midscene.local.env`。
+
+## Chrome Bridge Mode
+
+- 官方说明：
+  - 需要 Midscene Chrome 插件
+  - 终端侧配置模型环境变量
+  - 适合复用本地浏览器登录态和页面状态
+- 常用依赖：
+
+```bash
+npm install @midscene/web tsx --save-dev
+```
+
+- 常见入口：
+
+```ts
+import { AgentOverChromeBridge } from "@midscene/web/bridge-mode";
+```
+
+- 常见运行方式：
+
+```bash
+tsx demo-new-tab.ts
+```
+
+- 常见模型环境变量：
+
+```bash
+MIDSCENE_MODEL_BASE_URL
+MIDSCENE_MODEL_API_KEY
+MIDSCENE_MODEL_NAME
+MIDSCENE_MODEL_FAMILY
+```
+
+## MCP
+
+- 浏览器桥接 MCP：
+
+```text
+@midscene/web-bridge-mcp
+```
+
+- 桌面 MCP：
+
+```text
+@midscene/computer-mcp
+```
+
+- Computer MCP 常见配置核心：
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "@midscene/computer-mcp"]
+}
+```
+
+- 常见 MCP 模型环境变量：
+
+```bash
+MIDSCENE_MODEL_BASE_URL
+MIDSCENE_MODEL_API_KEY
+MIDSCENE_MODEL_NAME
+MIDSCENE_MODEL_FAMILY
+MCP_SERVER_REQUEST_TIMEOUT
+```
+
+## 桌面自动化
+
+- Midscene 支持 Windows、macOS、Linux 桌面自动化。
+- 桌面控制包括鼠标、键盘、截图、多显示器。
+- Linux 可在 Xvfb 下做无头执行。
+- Windows 下 `@midscene/computer-mcp` 的 npx 缓存包可能缺 `dist/screenCapture_1.3.2.bat` 和 `dist/app.manifest`。AirXDB smoke test 会从 `screenshot-desktop@1.15.3` npm 包自动补齐。
+- 桌面 GUI 调试可优先考虑：
+  - 快速试用：Playground
+  - 持续脚本化：Computer SDK / MCP
+
+## AirXDB Smoke Test
+
+```bash
+python "$HOME/plugins/airxdb/scripts/airxdb_computer_mcp_smoke.py" --project . --action mousemove --prompt "Windows taskbar Start button"
+```
+
+输出：
+
+- `airxdb_smoke=ok`：Computer MCP 连接、截图、语义动作完成。
+- `airxdb_smoke=blocked`：缺模型配置或 family 不合法。
+- `asset_repair=repaired`：已补齐 Windows 截图脚本。
+- `report=<path>`：JSON 报告，API key 已脱敏。
+
+## AirXDB Screenshot Evidence
+
+截图取证不需要模型配置：
+
+```bash
+python "$HOME/plugins/airxdb/scripts/airxdb_computer_mcp_smoke.py" --project . --action screenshot
+```
+
+用于：
+
+- 给 `airdbg` 提供 GUI 错误现场
+- 捕获弹窗、遮挡、焦点、布局错位、任务栏/托盘状态
+- 记录多显示器和当前桌面状态
+
+截图可能包含敏感信息。写入 ADR/C4/debug log 时记录路径和观察，不复制密钥或隐私内容。
+
+## GUI Debug 推荐策略
+
+1. 先选模式，不要一上来混用多种接入。
+2. 先做最小复现，再考虑长期自动化。
+3. 保留 HTML 报告、截图和复现命令。
+4. 若问题已定位到代码层，把证据交给 `airdbg` 做修复。