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