@chengzhao-dev/dsh-cpp-workflow 0.0.0-stage → 0.1.1

package/skills/building-cpp/references/cmake.md

@@ -0,0 +1,168 @@
+# CMake
+
+目标：一个编译器、Ninja、target-based 规则、可用的编译数据库。下面是最小形状和常见边界；模板在 `assets/templates/projects/`。
+
+## 最小可用形状
+
+### 单文件
+
+```cmake
+cmake_minimum_required(VERSION 3.20)
+project({{PROJECT_NAME}} VERSION 0.1.0 LANGUAGES CXX)
+
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
+
+add_executable(app src/main.cpp)
+target_compile_features(app PRIVATE cxx_std_20)
+set_target_properties(app PROPERTIES CXX_EXTENSIONS OFF)
+target_compile_options(app PRIVATE -Wall -Wextra -Werror)
+```
+
+### 库 + 程序
+
+```cmake
+cmake_minimum_required(VERSION 3.20)
+project({{PROJECT_NAME}} VERSION 0.1.0 LANGUAGES CXX)
+
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
+set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
+
+add_subdirectory(greeting)
+
+add_executable(app src/main.cpp)
+target_compile_features(app PRIVATE cxx_std_20)
+set_target_properties(app PROPERTIES CXX_EXTENSIONS OFF)
+target_link_libraries(app PRIVATE greeting)
+target_compile_options(app PRIVATE -Wall -Wextra -Werror)
+```
+
+```cmake
+# greeting/CMakeLists.txt
+add_library(greeting STATIC src/greeting.cpp)
+target_include_directories(greeting PUBLIC include)
+target_compile_features(greeting PUBLIC cxx_std_20)
+set_target_properties(greeting PROPERTIES CXX_EXTENSIONS OFF)
+target_compile_options(greeting PRIVATE -Wall -Wextra -Werror -Wold-style-cast -Wshadow)
+```
+
+- 库的 `PUBLIC include` 让程序能 `#include "greeting.h"`，不需要程序再写 include 路径。
+- `cxx_std_20` 用 `PUBLIC` 从库传播；程序自己再加一次也无害。
+- `CXX_EXTENSIONS OFF` 把 `-std=gnu++20` 收成 `-std=c++20`，与 Google 的「不用非标准扩展」一致；每个 target 都要设。
+- 程序 target 固定 `app`；库 target 用组件名。
+
+## target-based 规则
+
+- 每个 target 自己声明 include、标准、编译选项、链接库；不要用全局 `include_directories()`、`add_definitions()`、`CMAKE_CXX_FLAGS` 给所有 target 加料。
+- `target_include_directories(<target> PUBLIC|PRIVATE <dir>)`：公共头给 `PUBLIC`，私有实现目录给 `PRIVATE`。
+- `target_compile_features(<target> PUBLIC cxx_std_20)`：标准是 target 属性，不是全局开关。
+- `target_link_libraries(<target> PRIVATE|PUBLIC <lib>)`：实现依赖用 `PRIVATE`，接口依赖用 `PUBLIC`。
+- 不要 `file(GLOB ...)`；显式列源文件，新增文件时改 CMake，构建系统才知道。`CONFIGURE_DEPENDS` 依赖构建系统每次检查目录，跨生成器行为也不完全一致，不作为工程规则。
+- 不把 `main()` 编进库；程序只做装配和 I/O。
+- 头文件不参与编译时，不需要 `target_sources` 列出；需要 IDE 展示时再列。
+- 组件多起来时，一个组件一个 `CMakeLists.txt`：库放 `<component>/include` 与 `<component>/src`，程序放 `apps/include` 与 `apps/src`；`apps/include` 只给程序内部用，不要被库 `PUBLIC` 导出。
+- 测试 target 等出现第二个消费者时再加，不要为单个 `main()` 提前引入测试框架；测试只链接库的公共接口。
+
+## 工程名
+
+`project()` 的名字用 PascalCase，目录名用 kebab-case：
+
+```cmake
+project(TaskList VERSION 0.1.0 LANGUAGES CXX)
+```
+
+目录 `task-list/` 对应 `project(TaskList ...)`。派生规则是「按 `-` 切分、每段首字母大写、其余保留」，不要直接照抄目录名，也不要把 `{{PROJECT_NAME}}` 留在模板里。库 target 用组件名的小写形式（`task_list` 或 `tasks`），程序 target 固定 `app`。
+
+## 编译数据库
+
+```cmake
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+```
+
+- 只对 Makefile 和 Ninja 生成器生效；本项目固定 Ninja。
+- 生成位置是构建目录根部：`build/<compiler>/compile_commands.json`。
+- 构建脚本把它链接到 `build/compile_commands.json`；clangd 默认读这个路径，clang-tidy 用 `-p build/<compiler>`。
+- 换编译器时，旧目录的数据库不能复用；清理或换目录。
+
+## 输出目录
+
+```cmake
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
+set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
+```
+
+- 可执行文件统一到 `build/<compiler>/bin`；库到 `build/<compiler>/lib`。
+- 不要输出到源码目录；`git status` 不应出现构建产物。
+- 运行程序时从 `build/<compiler>/bin` 启动，或由脚本设置工作目录。
+
+## 共享库运行时路径
+
+```cmake
+if(APPLE)
+  set_target_properties(app PROPERTIES BUILD_RPATH "@loader_path/../lib")
+else()
+  set_target_properties(app PROPERTIES BUILD_RPATH "$ORIGIN/../lib")
+endif()
+```
+
+- 只对需要直接运行构建产物的程序设置；安装规则另算。
+- 不要用全局 `LD_LIBRARY_PATH` 包装所有命令；共享库的运行时路径由 target 的 RPATH 设置，不在脚本里全局改寻库路径。
+- `$ORIGIN` 在 CMake 字符串里要转义成 `\$ORIGIN` 吗？在双引号里 `$ORIGIN` 会被 CMake 当变量；写成 `"$ORIGIN/../lib"` 在 CMake 中 `$ORIGIN` 不是 `${...}`，不会被展开，保持字面量。若遇到展开问题，用 `"\$ORIGIN/../lib"`。
+
+## 标准库与编译器一致
+
+- 一个构建树只用一个 C++ 标准库实现。Clang 可以配 libstdc++（Linux 默认）或 libc++，但 `clang++`、`clang-tidy`、`clangd` 和链接进同一个程序的库必须一致。
+- `-stdlib=libc++` 是编译和链接都要的选项，不要只加在编译选项上；也不要全局 `add_compile_options`，按 target 传，或由工具链文件统一设置。
+- 混用 libstdc++ 与 libc++ 的典型症状是链接期大量未定义符号、`std::string` ABI 不匹配，或运行期崩溃；先查 `clang++ -v` 与 `ldd`，不要靠加 `-lstdc++` 掩盖。
+- 项目想固定 libc++ 时，在 CMake 工具链文件或项目自己的编译选项里写清，不要只写在某个人的脚本里；`environment.json` 只保留 `host`、`build_host`、`compiler` 三个轴，不放 libc++。换机器后必须能复现同一组合。
+- 本插件默认使用目标平台默认标准库；只有项目明确要求 libc++ 时才切换，并保证整套工具一致。
+
+## 警告与静态检查
+
+- 警告选项统一：`-Wall -Wextra -Werror`；库额外 `-Wold-style-cast -Wshadow`。
+- 不要把警告选项加到全局 `CMAKE_CXX_FLAGS`；每个 target 显式加，或用一个函数统一施加。
+- `clang-tidy` 在构建后单独跑，不挂进 CMake 的编译命令；这样编译数据库稳定，诊断可复现。
+- 需要 `clang-tidy` 集成时用 `CMAKE_CXX_CLANG_TIDY`，但本项目默认不启用，避免构建与检查耦合。
+
+## GoogleTest
+
+需要测试框架时，用固定版本的 `FetchContent`：
+
+```cmake
+include(FetchContent)
+FetchContent_Declare(
+  googletest
+  URL https://codeload.github.com/google/googletest/tar.gz/refs/tags/v1.17.0
+  URL_HASH SHA256=65fab701d9829d38cb77c14acdc431d2108bfdbf8979e40eb8ae567edf10b27c
+)
+set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+FetchContent_MakeAvailable(googletest)
+```
+
+- 版本固定，不用 `master`；URL 和哈希写在一起，避免供应链漂移。
+- 只在 `tests/` 需要时拉取；库和程序不依赖测试框架。
+- 没有网络时，项目可以自带 vendored 副本；不要构建时静默跳过测试。
+
+## 模板选择
+
+| 模板 | 何时用 | 关键文件 |
+| --- | --- | --- |
+| `single` | 一个 `main.cpp`，辅助函数很少 | `CMakeLists.txt`, `src/main.cpp` |
+| `multi` | 多个源文件，一个程序 | `CMakeLists.txt`, `include/`, `src/` |
+| `static-library` | 库需要被测试或第二个程序链接 | 根 + `greeting/` 子目录 |
+| `shared-library` | 需要运行时加载/替换 | 同上，`SHARED` + RPATH |
+
+模板里的 `{{PROJECT_NAME}}` 必须替换；不要留下占位符。
+
+## 反模式
+
+- 全局 `include_directories(include)`：所有 target 共享，边界消失。
+- `file(GLOB sources "src/*.cpp")`：新增文件不触发重新配置。
+- 把库和 `main()` 编进同一个 target：测试无法只链接库。
+- 在源码目录生成 `compile_commands.json` 或可执行文件。
+- 同时设 `CMAKE_CXX_COMPILER` 和 `CXX` 环境变量，互相覆盖。
+- 在 `CMakeLists.txt` 里 `execute_process` 下载依赖或改源码。
+- 用 `CMAKE_CXX_FLAGS` 加 `-std=c++23` 之类与声明不符的标准。

package/skills/building-cpp/references/environment.md

@@ -0,0 +1,104 @@
+# 环境组合
+
+环境是**声明**，不是探测结果。项目技能 `cpp-workflow-project` 的 `environment.json` 写清楚三个轴；构建规则、工具配置和检查都按这个声明执行。声明为空或组合非法时，先修声明，不要靠猜。
+
+## 三个轴
+
+| 轴 | 取值 | 说明 |
+| --- | --- | --- |
+| `host` | `windows` / `linux` / `macos` | 编辑器与代理壳所在的系统 |
+| `build_host` | `native` / `wsl` | 编译在哪执行；`wsl` 只对 `host=windows` 合法 |
+| `compiler` | `clang` / `gcc` | 一次只配一个；不支持 MSVC、clang-cl，也不把 C 编译器单独作为一个轴 |
+
+```json
+{
+  "host": "windows",
+  "build_host": "wsl",
+  "compiler": "clang"
+}
+```
+
+## 合法组合
+
+| host | build_host | compiler | 声明 | 本版本能构建 |
+| --- | --- | --- | --- | --- |
+| windows | wsl | clang | 合法 | 是（WSL 内跑 POSIX 脚本） |
+| windows | wsl | gcc | 合法 | 是 |
+| windows | native | clang | 合法 | 否：缺 POSIX 壳（本版无 PowerShell 脚本） |
+| windows | native | gcc | 合法 | 否：缺 POSIX 壳（本版无 PowerShell 脚本） |
+| linux | native | clang | 合法 | 是 |
+| linux | native | gcc | 合法 | 是 |
+| macos | native | clang | 合法 | 是 |
+| macos | native | gcc | 合法 | 是（要求真正的 GCC，不是 Apple 的 `g++` 别名） |
+
+非法组合：
+
+- `host` 不是三个值之一，或 `build_host` / `compiler` 不是两个值之一。
+- 三个轴任意为空、缺失、写成数组或同时写两个值。
+- `host=linux` / `host=macos` + `build_host=wsl`。
+- `compiler=msvc`、`compiler=clang-cl`、`compiler=c`。
+
+`windows` + `native` 是合法声明，但本版本**没有** PowerShell 构建脚本。`--live` 会明确报告「缺的是 shell，不是编译器」；不要为了让它通过把 `build_host` 改成 `wsl`，也不要临时写一个脚本伪装成已支持。
+
+## 工具角色
+
+| 角色 | clang 模式 | gcc 模式 |
+| --- | --- | --- |
+| 编译器 | `clang++` | `g++`（macOS 上必须是真正的 GCC） |
+| 格式化 | `clang-format` | `clang-format` |
+| 静态检查 | `clang-tidy` | `clang-tidy` |
+| 语言服务 | `clangd` | `clangd` |
+| 构建 | `cmake` + `ninja` | `cmake` + `ninja` |
+| 测试 | `ctest` | `ctest` |
+| 程序 | `app` | `app` |
+
+工具角色与编译器解耦：GCC 模式下仍用 Clang 的格式化、静态检查和语言服务。不要因为编译器是 GCC 就换成 `gcc-format` 之类不存在的工具。工程确有 C 源时，C 编译器用同一套的 `clang` 或 `gcc`，不能与 C++ 编译器分属两套；`--live` 的 compiler 角色核对的是 C++ 驱动，C 驱动缺失时由 configure 报错。
+
+## 版本与能力
+
+- **C++20**：编译器必须支持 `-std=c++20`；CMake ≥ 3.20（C++20 标准属性从 3.12 起可用）。
+- **clang-format / clang-tidy**：≥ 16。`BreakAfterAttributes` 在 16 才支持，15 及以下没有该选项。
+- **clang 模式同版本**：`clang++`、`clang-format`、`clang-tidy`、`clangd` 必须是同一 LLVM 主版本。混装 17 的 clangd 与 18 的 clang-format 会出现诊断与格式化不一致。Apple Clang 也按这条核对；若工具版本对不上，报告的是具体角色和版本，不要为了通过而改声明。
+- **gcc 模式**：检查器不拿 GCC 的主版本去比 Clang 工具；`clang-format` / `clang-tidy` 仍要 ≥ 16，`clangd` 只要求可用。`g++` 必须是真的 GCC，不能是 Apple clang 的别名。GCC 需要自带 C++20 `<format>` 的标准库；版本过旧时先升级工具链，不要改检查器绕过。
+- **Apple Clang**：`/usr/bin/clang++` 通常是 Apple Clang；clangd 需能经 `xcrun` 找到 SDK。不要混用 Homebrew LLVM 与 Xcode 资源目录，也不要把 Homebrew 路径写死。
+
+## 构建目录
+
+| compiler | 构建目录 | 编译数据库 |
+| --- | --- | --- |
+| clang | `build/clang/` | `build/clang/compile_commands.json` |
+| gcc | `build/gcc/` | `build/gcc/compile_commands.json` |
+| 当前 | `build/` | `build/compile_commands.json` → 上面之一的符号链接 |
+
+一次 configure 只用一个编译器；切换编译器时用另一个目录，不要在同一目录里改 `CMAKE_CXX_COMPILER` 后复用缓存。
+
+## 活动校验
+
+`<skill-dir>/scripts/checking-environment.mjs` 做两件事：
+
+1. **静态**（默认）：读 `environment.json`，检查三个轴和组合。轴为空或组合非法时以退出码 2 结束，不查找任何可执行文件。
+2. **活动**（`--live`）：先做声明校验，再核对当前进程是否在声明的 build host 上，然后查 PATH、角色和版本。声明本身不合法时仍以退出码 2 结束；声明合法但活动核对失败时以退出码 3 结束。
+
+```bash
+node "<skill-dir>/scripts/checking-environment.mjs" --project . --json
+node "<skill-dir>/scripts/checking-environment.mjs" --project . --live
+```
+
+`<skill-dir>` 是安装后的 `building-cpp` 目录；脚本不复制到目标工程，也不改目标工程的 PATH。
+
+约束：
+
+- 只读：不安装、不下载、不改 PATH、不写项目文件。
+- `--live` 在 `host=windows` + `build_host=native` 下直接报告「缺 POSIX 壳；本版没有 PowerShell 构建脚本」，不继续找编译器。
+- WSL 模式要求当前进程在 WSL 内（`WSL_DISTRO_NAME` / `WSL_INTEROP` 或 `/proc/version` 含 Microsoft）；只在 Linux 上但不在 WSL 时失败。
+- macOS 上声明 `compiler=gcc` 时，`g++ --version` 若显示 Apple clang，按「不是真正的 GCC」失败。
+- 没有 `--live` 时不做任何 PATH 探测，CI 和 Windows 开发机都能做声明校验。
+
+## 退出码
+
+| 码 | 含义 |
+| --- | --- |
+| 0 | 通过 |
+| 2 | 声明缺失、轴为空、组合非法 |
+| 3 | 活动校验失败：不在声明的 build host、角色缺失、版本不符 |
+| 1 | 脚本自身错误：参数错误或内部异常 |

package/skills/building-cpp/references/linking.md

@@ -0,0 +1,101 @@
+# 从源文件到可执行文件
+
+链接错误和编译错误是两类问题。先判断失败发生在哪个阶段，再改对应的文件。
+
+## 四个阶段
+
+```text
+预处理  ->  编译  ->  汇编  ->  链接  ->  加载运行
+.i         .s / .o             可执行文件 / 库
+```
+
+- 预处理：展开 `#include`、宏和条件编译，得到翻译单元。头文件找不到在这一步失败。
+- 编译：把翻译单元变成目标文件，做语法、类型和模板检查。函数体错误在这一步失败。
+- 汇编：把汇编文本变成目标文件；通常由编译器驱动。
+- 链接：把多个目标文件和库合并，解析符号引用。`undefined reference` 在这一步失败。
+- 加载：程序启动时由动态加载器找到共享库；`error while loading shared libraries` 在这一步失败。
+
+`g++ -c file.cpp` 只编译不链接；`g++ file.o -o app` 只链接。`-E` 只看预处理，`-S` 只看汇编。
+
+## 头文件、声明与定义
+
+- `#include` 是文本替换，不是模块导入；头文件只放声明、`inline` 定义、模板和 `constexpr` 定义。
+- 普通函数的定义放 `.cpp`；在头文件里写非 `inline` 函数定义，多个翻译单元包含时会重复定义。
+- 类定义放头文件；成员函数在类外定义时写 `ClassName::`，定义放 `.cpp`。
+- 只用到声明时不要包含完整定义；前置声明可以减少编译依赖，但不能替代需要完整类型的场景（继承、成员对象、按值返回）。
+- 每个头文件自包含：单独编译一个只包含该头文件的 `.cpp` 应通过。用 `#pragma once` 防止重复包含。
+
+## `undefined reference` 分诊
+
+| 现象 | 常见原因 | 修法 |
+| --- | --- | --- |
+| 链接器说某个成员函数未定义 | 声明了但没写定义，或 `.cpp` 没加入 target | 补定义，或把源文件加入 `target_sources` |
+| 只有某个平台失败 | 条件编译把定义排除了 | 检查宏和平台分支，保证每个平台都有定义 |
+| 第三方库符号缺失 | 没链接库，或库顺序不对 | `target_link_libraries` 加库；CMake 会处理顺序 |
+| C++ 符号被当成 C 符号 | 头文件缺少 `extern \"C\"` | C 接口头加 `extern \"C\"`，C++ 调用方也可见 |
+| 模板成员未定义 | 模板定义在 `.cpp`，实例化点看不到 | 模板定义移到头文件，或显式实例化 |
+| 静态库中的目标文件没被拉入 | 链接器只取被引用符号所在的目标文件 | 确认符号确实被引用，或改用对象库/共享库 |
+
+先看链接器报的完整符号名和来源文件，不要只看第一行。
+
+## 静态库与共享库
+
+| 形式 | 产物 | 链接时机 | 运行期依赖 | 适用 |
+| --- | --- | --- | --- | --- |
+| 静态库 | `libname.a` | 链接时复制所需目标文件 | 无 | 分发简单、启动快、库小 |
+| 共享库 | `libname.so` / `.dylib` / `.dll` | 链接时只记录依赖 | 运行时要能找到库 | 多程序共享、插件、独立升级 |
+
+- 静态库不是“把源码打包”；它仍是多个目标文件的归档，链接器按需取用。
+- 共享库的符号默认可能被导出；需要隐藏内部符号时设置可见性（`-fvisibility=hidden` + 显式导出）。
+- 共享库的 ABI 包括类布局、虚表、标准库类型和编译器选项；不同编译器或 `-stdlib` 混用可能链接成功但运行崩溃。
+- 一个项目里不要同时链接两套标准库（libstdc++ 与 libc++）；编译器、clangd、库和可执行文件必须一致。
+
+## 输出目录与 RPATH
+
+推荐布局：
+
+```text
+build/<compiler>/
+  bin/app
+  lib/libgame.so
+  compile_commands.json
+```
+
+- 可执行文件在 `bin/`，共享库在 `lib/`；不要把库和可执行文件混在同一层。
+- 运行时动态加载器默认不搜索可执行文件旁边的 `lib/`；需要 RPATH：
+  - Linux：`-Wl,-rpath,'$ORIGIN/../lib'`
+  - macOS：`-Wl,-rpath,@loader_path/../lib`
+- CMake 用 `BUILD_RPATH` / `INSTALL_RPATH` 设置，不要手工拼链接命令；见 `assets/cmake/setting-rpath.cmake`。
+- RPATH 里的 `$ORIGIN` 要防止被 shell 展开：CMake 字符串里写 `\$ORIGIN` 或使用 `BUILD_RPATH_USE_ORIGIN`。
+
+## 验收：`file` 与 `ldd`
+
+链接成功不等于能运行。构建后检查产物：
+
+```bash
+file build/clang/bin/app
+ldd build/clang/bin/app
+```
+
+- `file` 确认架构、位数、是否动态链接。
+- `ldd` 确认每个共享库都能解析到实际路径；出现 `not found` 就是加载期会失败。
+- 运行 `app` 做一次最小启动；动态库缺失会在启动时暴露，而不是链接时。
+- macOS 用 `otool -L` 代替 `ldd`；Windows 用 `dumpbin /dependents`。
+
+## 构建脚本里的顺序
+
+1. 配置：CMake 生成构建系统，导出编译数据库。
+2. 编译 + 链接：构建所有 target。
+3. 产物检查：确认 `bin/app`、`lib/`、编译数据库存在。
+4. 运行：用项目入口命令启动，检查退出码和输出。
+5. 测试：`ctest` 跑注册的测试。
+
+不要用“链接成功”代替“运行成功”；也不要用“测试通过”代替“产物存在”。
+
+## 检查清单
+
+- [ ] 头文件自包含，普通函数定义不在头文件。
+- [ ] 每个声明都有定义，且定义所在源文件加入 target。
+- [ ] 静态库/共享库选择有理由，没有混用两套标准库。
+- [ ] 产物在 `bin/` 与 `lib/`，RPATH 指向相对位置。
+- [ ] `file` 与 `ldd` 检查过，程序能最小启动。

package/skills/building-cpp/references/static-analysis.md

@@ -0,0 +1,136 @@
+# 静态分析与语言服务
+
+三件工具各管一段：`clang-format` 排版、`clang-tidy` 诊断、`clangd` 提供补全/跳转/诊断。它们都读同一份编译数据库，但职责不重叠。
+
+## clang-format
+
+```bash
+clang-format --dry-run --Werror src/*.cpp include/*.h tests/*.cpp
+```
+
+- 检查用 `--dry-run --Werror`；需要自动修复时单独跑 `clang-format -i`，不要在构建脚本里悄悄改源码。
+- 工程必须有根 `.clang-format`；缺失时先复制配置，不要回退到内置风格，回退会掩盖配置缺失。
+- 只扫描项目源码：`src/`、`include/`、`apps/`、`tests/` 等实际存在的目录；不扫描 `build/`、第三方、生成文件。
+- 配置文件在工程根 `.clang-format`；不要依赖用户主目录或编辑器内置配置。
+- `ColumnLimit: 100`、`Standard: c++20`、`BasedOnStyle: Google`；`IncludeCategories` 维持包含顺序。
+- 格式化失败就是失败，不要用 `// clang-format off` 绕过；确需关闭时只包住无法排版的宏或表格，并写一句理由。
+
+## clang-tidy
+
+```bash
+clang-tidy -p build/clang \
+  --header-filter="^$(pwd -P)/(include|src|apps|tests)/" \
+  --warnings-as-errors='*' \
+  src/*.cpp apps/*.cpp tests/*.cpp
+```
+
+- `-p` 指向当前编译器的构建目录，读取 `compile_commands.json`。
+- `--header-filter` 控制哪些头文件的诊断被显示，不改变 clang-tidy 实际解析哪些头；模板实例化可能让一条根因产生多条警告，警告条数不等于缺陷条数。按根因修，不要按条数修。
+- `--header-filter` 用项目头目录的白名单，不要用 `.*` 把系统头和第三方头一并纳入。clang-tidy 按绝对路径匹配，所以上面用 `$(pwd -P)` 前缀；上面是常见目录，工程用别的顶层目录时按实际替换。`--exclude-header-filter` 到 clang-tidy 19 才加入，16/17/18 都没有，不要依赖它。
+- 系统头默认被排除，不要加 `--system-headers`。
+- 只扫描项目源文件；不要把 `build/` 或第三方源码传给 clang-tidy。
+- `--warnings-as-errors='*'` 把警告当失败；修代码，不要新增 `NOLINT`。确需抑制时写 `// NOLINT(检查名): 理由`，理由必须具体。
+- 配置在工程根 `.clang-tidy`；关闭项逐条写理由，不整族关闭。`cppcoreguidelines-pro-bounds-constant-array-index` 不能整族关闭；优先把下标换成 `at()` 或带边界检查的辅助函数，并补负向越界测试。
+- 没有编译数据库时先回到 `building-cpp` 的定构建生成；不要用 `--` 手工拼编译参数绕过。
+- `clang-tidy` 的诊断可能指向头文件；修头文件里的声明或实现，不要只改调用点。
+
+## clangd
+
+`.clangd`：
+
+```yaml
+CompileFlags:
+  CompilationDatabase: build/clang
+  Add:
+    - -std=c++20
+    - -Wall
+    - -Wextra
+Diagnostics:
+  Suppress:
+    - pp_file_not_found
+```
+
+- `CompilationDatabase` 指向当前编译器目录；GCC 模式改 `build/gcc`。
+- `Add` 只补编译数据库里没有的公共选项；不要重复 `-I` 项目 include（数据库里已有）。
+- 静态检查规则只在 `.clang-tidy` 里维护；clangd 读取同一份配置，不要在这里复制检查列表。
+- `Suppress` 只放确实无法避免的解析噪声（如 `pp_file_not_found`），并写理由。
+
+`--query-driver`：
+
+- 它是 clangd 的命令行参数，不是 `.clangd` 的 YAML 键。
+- 作用：允许 clangd 执行编译器驱动，读取系统头路径；只对编译数据库里出现的驱动生效。
+- 写在 `.vscode/settings.json`：
+
+```jsonc
+{
+  "clangd.arguments": [
+    "--query-driver=/usr/bin/clang++",
+    "--header-insertion=never",
+    "--background-index"
+  ]
+}
+```
+
+- 路径用绝对路径；多个驱动用逗号分隔。GCC 模式指向 `/usr/bin/g++`。
+- 不要写 `--query-driver=*` 或宽泛的 glob；这等于允许 clangd 执行任意匹配的驱动。
+- 如果编译数据库里的编译器是相对路径，clangd 可能拒绝执行；用绝对路径重新 configure。
+- `--query-driver` 只影响 clangd，不影响 clang-tidy；tidy 用编译数据库里的命令。
+
+## 编辑器
+
+`.vscode/extensions.json` 推荐：
+
+```json
+{
+  "recommendations": ["llvm-vs-code-extensions.vscode-clangd", "ms-vscode.cmake-tools"]
+}
+```
+
+`.vscode/settings.json` 固定：
+
+```jsonc
+{
+  "clangd.arguments": [
+    "--query-driver=/usr/bin/clang++",
+    "--header-insertion=never",
+    "--background-index"
+  ],
+  "cmake.buildDirectory": "${workspaceFolder}/build/clang",
+  "cmake.generator": "Ninja"
+}
+```
+
+- 不推荐与 clangd 冲突的 C++ 智能提示插件；只保留一个语言服务。
+- 不把 `compile_commands.json` 提交进仓库；它是构建产物。
+- 切换编译器时同时改 `.clangd`、`settings.json` 和构建目录；三处不一致会让诊断指向旧代码。
+
+## 门禁分级
+
+`--warnings-as-errors='*'` 是默认门禁。若项目必须把一组诊断先设为观察项，按检查名逐条写进项目脚本，不按 `*` 整族降级：
+
+| 级别 | 典型检查 | 处理 |
+| --- | --- | --- |
+| 失败 | `bugprone-*`、`readability-math-missing-parentheses`、`readability-identifier-naming`、项目声明的致命集 | 修代码；不允许用 NOLINT 掩盖 |
+| 失败 | 编译诊断、链接诊断、格式检查 | 直接失败 |
+| 观察 | 迁移期暂时无法修完的 `modernize-*` | 在项目技能里列清单、写负责人和退出条件；不默认全仓关闭 |
+
+- 致命集宁可小、可解释，也不要把所有检查一刀切。
+- 观察项不是免死金牌：新代码不应新增观察项，已有项只能减少。
+- 关闭某条检查时，在 `.clang-tidy` 里写一行理由，并在项目技能里记录退出条件。
+
+## 版本与一致性
+
+- `clang-format` / `clang-tidy` ≥ 16；clang 模式下与 `clang++`、`clangd` 同主版本。
+- 混版本常见症状：格式化结果与 CI 不同、clangd 诊断与 tidy 不一致、选项被静默忽略。
+- 检查器在 `--live` 时核对版本；不要用「能跑就行」绕过。
+
+## 失败分诊
+
+| 现象 | 可能原因 | 处理 |
+| --- | --- | --- |
+| `clang-tidy` 报找不到编译数据库 | 没 configure 或路径错 | 回到 `building-cpp` 的定构建生成 `build/<compiler>/compile_commands.json` |
+| clangd 报找不到系统头 | 编译数据库里的编译器是相对路径 | 用绝对路径重新 configure，或配 `--query-driver` |
+| 格式化结果与 CI 不同 | 版本不同或配置不是工程根那份 | 统一版本，确认 `.clang-format` 在工程根 |
+| tidy 报系统头 | 加了 `--system-headers` 或 header-filter 过宽 | 去掉 `--system-headers`，用项目头目录白名单 |
+| 大量 `readability-*` | 代码风格未统一 | 回到 `developing-cpp` 的定声明 / 定实现修声明与实现，不要批量 NOLINT |
+| clangd 与 tidy 诊断不一致 | 两者读的数据库/版本不同 | 统一 `CompilationDatabase` 与工具版本 |