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/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 验收。