@chengzhao-dev/dsh-cpp-workflow 0.1.0 → 0.1.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 chengzhao-dev
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2026 chengzhao-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

package/README.en.md

@@ -18,13 +18,13 @@ Both skills read the project skill `cpp-workflow-project` first. Without it, the
 Pinned npm install:
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.1.0
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.1.1
 ```
 
 The matching Git tag:
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.1.0
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.1.1
 ```
 
 The desktop app owns the `desktop` profile. If the command-line `add` is rejected, add the plugin in the app settings and use the same pinned npm version. A Git tag install uses the prebuilt `lib/` committed in the repository and runs no build on the target machine; the package has no install script that needs approval.
@@ -96,7 +96,6 @@ Requires Node.js 22 or newer.
 ```bash
 npm ci
 npm test           # build, structural check, gate/environment/schema tests
-npm run check      # same as npm test
 npm run pack:check # inspect the npm package contents
 ```
 

package/README.md

@@ -18,13 +18,13 @@
 npm 安装钉死版本：
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.1.0
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.1.1
 ```
 
 同版本的 Git 标签：
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.1.0
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.1.1
 ```
 
 桌面应用独占 `desktop` profile。命令行 `add` 被拒绝时，在应用设置里添加插件，地址填同一个 npm 版本。Git 标签安装使用仓库内已构建的 `lib/`，不在目标机器上重新构建；包内也不含需要授权执行的安装脚本。
@@ -96,7 +96,6 @@ dsh-cpp-workflow/
 ```bash
 npm ci
 npm test           # 构建、结构检查、门禁/环境/schema 测试
-npm run check      # 同 npm test
 npm run pack:check # 核对 npm 包内容
 ```
 

package/cordis.patch.yml

@@ -4,11 +4,8 @@
 # replaced. The row loads this package's `main` entry, which registers the
 # packaged developing-cpp and building-cpp skills through `ctx.skills`.
 #
-# Install from npm or from the matching Git tag, for example:
-#
-#   dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.1.0
-#   dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.1.0
-#
+# Install with `dsh plugin --profile <name> add <package>`. Pinned npm and Git
+# tag addresses are in the README's Install section.
 - insert:
     - id: cpp-workflow
       name: "@chengzhao-dev/dsh-cpp-workflow"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chengzhao-dev/dsh-cpp-workflow",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "C++20 工程流程技能包：源码四步与构建三步，按项目声明的环境组合校验 · C++20 workflow skills for DeepSeek Harness",
   "type": "module",
   "main": "./lib/index.js",
@@ -43,7 +43,6 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "npm run build && node scripts/checking-skill-links.mjs && node --test tests/*.test.mjs",
-    "check": "npm test",
     "pack:check": "npm pack --dry-run"
   },
   "keywords": [

package/skills/building-cpp/steps/01-build.md

@@ -1,76 +1,76 @@
-# 第 1 步：定构建
-
-## 产出
-
-一组 target-based 的 CMake 规则、一个固定的构建目录、一个可用的编译数据库。构建结果只取决于 `environment.json` 声明的组合，不取决于当前 shell 碰巧有什么。
-
-```text
-CMakeLists.txt
-build/
-  clang/                 # compiler=clang
-    compile_commands.json
-  gcc/                   # compiler=gcc
-    compile_commands.json
-  compile_commands.json  # 指向上面的当前数据库
-```
-
-## 通用情况
-
-先读 `environment.json`。三个轴分别表示：
-
-| 轴 | 取值 | 含义 |
-| --- | --- | --- |
-| `host` | `windows` / `linux` / `macos` | 编辑器与代理壳所在系统 |
-| `build_host` | `native` / `wsl` | 执行编译和运行产物的环境；`native` 表示 `host` 本机，`wsl` 表示 Windows 的 WSL，且只允许 `host=windows` |
-| `compiler` | `clang` / `gcc` | 用哪个编译器；一次只配一个 |
-
-轴为空、值未知或组合非法（如 `host=linux` + `build_host=wsl`）时，停在定构建，先让用户把 `environment.json` 填对。不要替用户选 WSL、Clang 或构建目录。
-
-构建规则：
-
-- CMake 最低 3.20；`project(... LANGUAGES CXX)`；只有确有 C 源时才写 `LANGUAGES C CXX`。目标标准 C++20。
-- 生成器固定单配置 Ninja，不用 Ninja Multi-Config：同一源文件会写多条命令，clangd 默认只取第一条，容易读错数据库（clangd#2026）；构建目录固定 `build/clang` 或 `build/gcc`。
-- 一个 configure 只用一个编译器：`-DCMAKE_CXX_COMPILER=clang++` 或 `g++`。
-- 程序 target 固定叫 `app`；库 target 用组件名，程序链接库。库与程序分开，不把 `main()` 编进库。
-- 用 `target_include_directories`、`target_compile_features`、`target_link_libraries` 表达依赖；禁止全局 `include_directories()`、`add_definitions()`、`CMAKE_CXX_FLAGS` 污染所有 target。
-- 库的公共 include 根用 `PUBLIC`；实现私有头用 `PRIVATE`；测试 target 只链接被测库的公共接口。
-- `set(CMAKE_EXPORT_COMPILE_COMMANDS ON)`；Ninja 生成器下会产出 `compile_commands.json`。
-- 输出目录统一：可执行文件到 `build/<compiler>/bin`，库到 `build/<compiler>/lib`；不要用源码目录当输出目录。
-- 开启 `CMAKE_EXPORT_COMPILE_COMMANDS` 后，把 `build/<compiler>/compile_commands.json` 符号链接到 `build/compile_commands.json`，让 clangd 默认能找到当前数据库。本插件固定产出 `build/<compiler>/` 并在 `build/` 下维护链接，不生成 `out/build/`，也不把两套构建根混用。
-- 目标标准写在 target 上：`target_compile_features(app PRIVATE cxx_std_20)`；库用 `PUBLIC` 传播标准。每个 target 再加 `CXX_EXTENSIONS OFF`，避免 CMake 默认的 `-std=gnu++20`。
-- 工程确有 C 源时才写 `LANGUAGES C CXX`，并且 `CMAKE_C_COMPILER` 与 `CMAKE_CXX_COMPILER` 必须来自同一套编译器（`clang`/`clang++` 或 `gcc`/`g++`）；没有 C 源时只启用 CXX。
-- 不写 `file(GLOB ...)`；源文件显式列出，新增文件时改 CMake。
-- 不加 `-march=native`、`-ffast-math` 等改变语义或可移植性的选项；警告选项按团队约定统一加。
-- 配置阶段不隐式下载依赖；需要 GoogleTest 时由项目显式选择固定版本、带哈希的 `FetchContent`，或使用项目自带的 cmake 模块，只把下载用于测试依赖。
-
-命令形状：
-
-```bash
-cmake -S . -B build/clang -G Ninja \
-  -DCMAKE_BUILD_TYPE=Debug \
-  -DCMAKE_CXX_COMPILER=clang++ \
-  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
-cmake --build build/clang
-rm -f build/compile_commands.json
-ln -s clang/compile_commands.json build/compile_commands.json
-```
-
-GCC 模式把目录和编译器换成 `build/gcc`、`g++`。工程确有 C 源时，再补 `-DCMAKE_C_COMPILER=clang` 或 `gcc`，和 C++ 编译器同属一套。每次构建都重新 configure；不要依赖上一次的缓存。
-
-## 情况
-
-**新工程**：从 `assets/templates/projects/` 选形态：`single` 单文件、`multi` 多文件单程序、`static-library` 静态库 + 程序、`shared-library` 动态库 + 程序。只复制目标工程缺的文件；已有的 `CMakeLists.txt`、`.clang-*`、源码不覆盖。模板里的 `{{PROJECT_NAME}}` 换成真实工程名。
-
-**已有工程**：先读现有 `CMakeLists.txt`，找出全局设置、GLOB、输出目录和 target 命名；只改与当前任务相关的一处。大改前先让通过检查的项目入口跑通，保留可回退点。
-
-**库 + 程序**：库 target 的 `PUBLIC` include 根指向 `<component>/include`；程序 target 只链接库，不直接包含库的 `src/`。静态库与动态库的接口相同；动态库额外设置运行时库路径。
-
-**测试**：`enable_testing()` 放在顶层，`add_subdirectory(tests)` 在 `add_subdirectory(<component>)` 之后；测试 target 用 `add_test(NAME ... COMMAND ...)` 注册。没有测试时不要为了「看起来完整」加空测试。
-
-**CMakePresets**：如果项目使用 preset，名称固定 `clang` / `gcc`，与构建目录一致；没有 preset 时直接用上面的命令，不要两套并存。
-
-## 正反例指针
-
-- 全局 include、GLOB、把 `main()` 编进库：`examples/cmake.md`。
-- 正确的最小库 + 程序：`examples/cmake.md`「最小可用形状」。
-- target 与目录的完整说明：`references/cmake.md`。
+# 第 1 步：定构建
+
+## 产出
+
+一组 target-based 的 CMake 规则、一个固定的构建目录、一个可用的编译数据库。构建结果只取决于 `environment.json` 声明的组合，不取决于当前 shell 碰巧有什么。
+
+```text
+CMakeLists.txt
+build/
+  clang/                 # compiler=clang
+    compile_commands.json
+  gcc/                   # compiler=gcc
+    compile_commands.json
+  compile_commands.json  # 指向上面的当前数据库
+```
+
+## 通用情况
+
+先读 `environment.json`。三个轴分别表示：
+
+| 轴 | 取值 | 含义 |
+| --- | --- | --- |
+| `host` | `windows` / `linux` / `macos` | 编辑器与代理壳所在系统 |
+| `build_host` | `native` / `wsl` | 执行编译和运行产物的环境；`native` 表示 `host` 本机，`wsl` 表示 Windows 的 WSL，且只允许 `host=windows` |
+| `compiler` | `clang` / `gcc` | 用哪个编译器；一次只配一个 |
+
+轴为空、值未知或组合非法（如 `host=linux` + `build_host=wsl`）时，停在定构建，先让用户把 `environment.json` 填对。不要替用户选 WSL、Clang 或构建目录。
+
+构建规则：
+
+- CMake 最低 3.20；`project(... LANGUAGES CXX)`；只有确有 C 源时才写 `LANGUAGES C CXX`。目标标准 C++20。
+- 生成器固定单配置 Ninja，不用 Ninja Multi-Config：同一源文件会写多条命令，clangd 默认只取第一条，容易读错数据库（clangd#2026）；构建目录固定 `build/clang` 或 `build/gcc`。
+- 一个 configure 只用一个编译器：`-DCMAKE_CXX_COMPILER=clang++` 或 `g++`。
+- 程序 target 固定叫 `app`；库 target 用组件名，程序链接库。库与程序分开，不把 `main()` 编进库。
+- 用 `target_include_directories`、`target_compile_features`、`target_link_libraries` 表达依赖；禁止全局 `include_directories()`、`add_definitions()`、`CMAKE_CXX_FLAGS` 污染所有 target。
+- 库的公共 include 根用 `PUBLIC`；实现私有头用 `PRIVATE`；测试 target 只链接被测库的公共接口。
+- `set(CMAKE_EXPORT_COMPILE_COMMANDS ON)`；Ninja 生成器下会产出 `compile_commands.json`。
+- 输出目录统一：可执行文件到 `build/<compiler>/bin`，库到 `build/<compiler>/lib`；不要用源码目录当输出目录。
+- 开启 `CMAKE_EXPORT_COMPILE_COMMANDS` 后，把 `build/<compiler>/compile_commands.json` 符号链接到 `build/compile_commands.json`，让 clangd 默认能找到当前数据库。本插件固定产出 `build/<compiler>/` 并在 `build/` 下维护链接，不生成 `out/build/`，也不把两套构建根混用。
+- 目标标准写在 target 上：`target_compile_features(app PRIVATE cxx_std_20)`；库用 `PUBLIC` 传播标准。每个 target 再加 `CXX_EXTENSIONS OFF`，避免 CMake 默认的 `-std=gnu++20`。
+- 工程确有 C 源时才写 `LANGUAGES C CXX`，并且 `CMAKE_C_COMPILER` 与 `CMAKE_CXX_COMPILER` 必须来自同一套编译器（`clang`/`clang++` 或 `gcc`/`g++`）；没有 C 源时只启用 CXX。
+- 不写 `file(GLOB ...)`；源文件显式列出，新增文件时改 CMake。
+- 不加 `-march=native`、`-ffast-math` 等改变语义或可移植性的选项；警告选项按团队约定统一加。
+- 配置阶段不隐式下载依赖；需要 GoogleTest 时由项目显式选择固定版本、带哈希的 `FetchContent`，或使用项目自带的 cmake 模块，只把下载用于测试依赖。
+
+命令形状：
+
+```bash
+cmake -S . -B build/clang -G Ninja \
+  -DCMAKE_BUILD_TYPE=Debug \
+  -DCMAKE_CXX_COMPILER=clang++ \
+  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+cmake --build build/clang
+rm -f build/compile_commands.json
+ln -s clang/compile_commands.json build/compile_commands.json
+```
+
+GCC 模式把目录和编译器换成 `build/gcc`、`g++`。工程确有 C 源时，再补 `-DCMAKE_C_COMPILER=clang` 或 `gcc`，和 C++ 编译器同属一套。每次构建都重新 configure；不要依赖上一次的缓存。
+
+## 情况
+
+**新工程**：从 `assets/templates/projects/` 选形态：`single` 单文件、`multi` 多文件单程序、`static-library` 静态库 + 程序、`shared-library` 动态库 + 程序。只复制目标工程缺的文件；已有的 `CMakeLists.txt`、`.clang-*`、源码不覆盖。模板里的 `{{PROJECT_NAME}}` 换成真实工程名。
+
+**已有工程**：先读现有 `CMakeLists.txt`，找出全局设置、GLOB、输出目录和 target 命名；只改与当前任务相关的一处。大改前先让通过检查的项目入口跑通，保留可回退点。
+
+**库 + 程序**：库 target 的 `PUBLIC` include 根指向 `<component>/include`；程序 target 只链接库，不直接包含库的 `src/`。静态库与动态库的接口相同；动态库额外设置运行时库路径。
+
+**测试**：`enable_testing()` 放在顶层，`add_subdirectory(tests)` 在 `add_subdirectory(<component>)` 之后；测试 target 用 `add_test(NAME ... COMMAND ...)` 注册。没有测试时不要为了「看起来完整」加空测试。
+
+**CMakePresets**：如果项目使用 preset，名称固定 `clang` / `gcc`，与构建目录一致；没有 preset 时直接用上面的命令，不要两套并存。
+
+## 正反例指针
+
+- 全局 include、GLOB、把 `main()` 编进库：`examples/cmake.md`。
+- 正确的最小库 + 程序：`examples/cmake.md`「最小可用形状」。
+- target 与目录的完整说明：`references/cmake.md`。

package/skills/building-cpp/steps/02-tooling.md

@@ -1,41 +1,41 @@
-# 第 2 步：定工具配置
-
-## 产出
-
-工程自己的 `.clang-format`、`.clang-tidy`、`.clangd` 和编辑器推荐配置。三份配置各管一段：格式化、静态检查、语言服务，不互相复制规则。
-
-## 通用情况
-
-- 工程拥有配置：`.clang-format`、`.clang-tidy`、`.clangd`、`.vscode/` 放在工程根；不要依赖用户主目录或插件目录里的同名文件。
-- 只复制缺失的文件。已有配置先读再改，不覆盖；需要合并时逐项说明理由。
-- 工具角色固定：`clang-format` 管排版，`clang-tidy` 管静态诊断，`clangd` 管补全/跳转/诊断；无论 `compiler` 是 clang 还是 gcc，这三件都用 Clang 工具链。
-- 版本要求见 `references/environment.md`：Clang 模式要求 `clang++`、`clang-format`、`clang-tidy`、`clangd` 同一 LLVM 主版本；GCC 模式要求 `clang-format` / `clang-tidy` ≥ 16，`clangd` 只要求可用。
-- `.clangd` 的 `CompilationDatabase` 指向 `build/<compiler>`；切换编译器时同步改，不能留旧目录。
-- `--query-driver` 是 clangd 的命令行参数，写在 `.vscode/settings.json` 的 `clangd.arguments` 里，不是 `.clangd` 的 YAML 键。它告诉 clangd 允许执行哪个编译器驱动来取系统头路径；路径写绝对路径，并与 `environment.json` 的编译器一致。
-- 首次复制时按轴替换两个值：`compiler=clang` 用 `CompilationDatabase: build/clang` 和 `--query-driver=/usr/bin/clang++`；`compiler=gcc` 用 `build/gcc` 和 `/usr/bin/g++`。只复制模板而不改这两处，GCC 模式会指向错误的数据库或驱动。原工程已有的 `.clangd` 不覆盖；要改先征得同意。
-- `.clang-format` 固定 `BasedOnStyle: Google`、`Standard: c++20`、`ColumnLimit: 100`、`DerivePointerAlignment: false`、`PointerAlignment: Left`；`IncludeCategories` 维持包含顺序。不要逐项手调换行。
-- `.clang-tidy` 保留 `bugprone-*`、`cppcoreguidelines-*`、`misc-*`、`modernize-*`、`performance-*`、`portability-*`、`readability-*`、`clang-analyzer-core.*` 和四条 `google-*` 的主体；关闭项必须写理由。不要把整个检查族一关了之。
-- `.vscode/extensions.json` 推荐 clangd 与 CMake Tools；`.vscode/settings.json` 固定 clangd 参数和 CMake 构建目录。配置注释用 JSONC 的 `//`，贴在被解释的键上方。
-- 配置注释写「为什么这样设」，不写「这一项是什么」；不写策略头、不指向文档路径。
-- 格式化与静态检查只扫描项目源码：`src/`、`include/`、`apps/`、`tests/` 等实际存在的源码根；不扫描 `build/`、第三方目录、生成文件。
-- `clang-tidy` 用 `-p build/<compiler>` 读取编译数据库，`--header-filter` 只列项目根下的顶层目录，避免把第三方头纳入；不要加 `--system-headers`，也不要用 clang-tidy 19 才加入、16 没有的 `--exclude-header-filter`。
-- 格式化用 `--dry-run --Werror` 做检查；需要自动修复时单独运行 `-i`，不要让构建脚本悄悄改源码。
-- 工程模板里不预置 `compile_commands.json`；它由定构建的 configure 生成，是构建产物。
-
-## 情况
-
-**新工程**：从 `assets/config/` 复制 `.clang-format`、`.clang-tidy`、`.clangd` 和 `.vscode/` 两个文件，按编译器的映射改 `.clangd` 的编译数据库目录和 `.vscode/settings.json` 的 `--query-driver` 路径。不要复制 `build/`。
-
-**已有工程**：先跑一次 `clang-format --dry-run --Werror` 和 `clang-tidy`，看现有配置实际报什么；只改导致当前失败或与声明环境冲突的项。不要借机重排全工程格式。
-
-**换编译器**：改 `.clangd` 的 `CompilationDatabase`，改 `--query-driver` 指向的编译器，清理旧构建目录；不要同时保留两套 clangd 配置。
-
-**GCC 模式**：`clangd` 仍可工作，但系统头来自 GCC；`--query-driver` 指向 `g++`。`clang-format` / `clang-tidy` 仍是 Clang 工具，版本要求不因编译器是 GCC 而降低。
-
-**共享库**：静态检查不因链接方式改变；运行时库路径在定构建的 CMake 里设置，不要写进 clang 配置。
-
-## 正反例指针
-
-- `.clangd` 指错编译数据库、`query-driver` 写进 YAML：`examples/tooling.md`。
-- 配置文件堆策略头、关闭检查不写理由：`examples/tooling.md`「配置注释」。
-- 工具调用与头文件过滤：`references/static-analysis.md`。
+# 第 2 步：定工具配置
+
+## 产出
+
+工程自己的 `.clang-format`、`.clang-tidy`、`.clangd` 和编辑器推荐配置。三份配置各管一段：格式化、静态检查、语言服务，不互相复制规则。
+
+## 通用情况
+
+- 工程拥有配置：`.clang-format`、`.clang-tidy`、`.clangd`、`.vscode/` 放在工程根；不要依赖用户主目录或插件目录里的同名文件。
+- 只复制缺失的文件。已有配置先读再改，不覆盖；需要合并时逐项说明理由。
+- 工具角色固定：`clang-format` 管排版，`clang-tidy` 管静态诊断，`clangd` 管补全/跳转/诊断；无论 `compiler` 是 clang 还是 gcc，这三件都用 Clang 工具链。
+- 版本要求见 `references/environment.md`：Clang 模式要求 `clang++`、`clang-format`、`clang-tidy`、`clangd` 同一 LLVM 主版本；GCC 模式要求 `clang-format` / `clang-tidy` ≥ 16，`clangd` 只要求可用。
+- `.clangd` 的 `CompilationDatabase` 指向 `build/<compiler>`；切换编译器时同步改，不能留旧目录。
+- `--query-driver` 是 clangd 的命令行参数，写在 `.vscode/settings.json` 的 `clangd.arguments` 里，不是 `.clangd` 的 YAML 键。它告诉 clangd 允许执行哪个编译器驱动来取系统头路径；路径写绝对路径，并与 `environment.json` 的编译器一致。
+- 首次复制时按轴替换两个值：`compiler=clang` 用 `CompilationDatabase: build/clang` 和 `--query-driver=/usr/bin/clang++`；`compiler=gcc` 用 `build/gcc` 和 `/usr/bin/g++`。只复制模板而不改这两处，GCC 模式会指向错误的数据库或驱动。原工程已有的 `.clangd` 不覆盖；要改先征得同意。
+- `.clang-format` 固定 `BasedOnStyle: Google`、`Standard: c++20`、`ColumnLimit: 100`、`DerivePointerAlignment: false`、`PointerAlignment: Left`；`IncludeCategories` 维持包含顺序。不要逐项手调换行。
+- `.clang-tidy` 保留 `bugprone-*`、`cppcoreguidelines-*`、`misc-*`、`modernize-*`、`performance-*`、`portability-*`、`readability-*`、`clang-analyzer-core.*` 和四条 `google-*` 的主体；关闭项必须写理由。不要把整个检查族一关了之。
+- `.vscode/extensions.json` 推荐 clangd 与 CMake Tools；`.vscode/settings.json` 固定 clangd 参数和 CMake 构建目录。配置注释用 JSONC 的 `//`，贴在被解释的键上方。
+- 配置注释写「为什么这样设」，不写「这一项是什么」；不写策略头、不指向文档路径。
+- 格式化与静态检查只扫描项目源码：`src/`、`include/`、`apps/`、`tests/` 等实际存在的源码根；不扫描 `build/`、第三方目录、生成文件。
+- `clang-tidy` 用 `-p build/<compiler>` 读取编译数据库，`--header-filter` 只列项目根下的顶层目录，避免把第三方头纳入；不要加 `--system-headers`，也不要用 clang-tidy 19 才加入、16 没有的 `--exclude-header-filter`。
+- 格式化用 `--dry-run --Werror` 做检查；需要自动修复时单独运行 `-i`，不要让构建脚本悄悄改源码。
+- 工程模板里不预置 `compile_commands.json`；它由定构建的 configure 生成，是构建产物。
+
+## 情况
+
+**新工程**：从 `assets/config/` 复制 `.clang-format`、`.clang-tidy`、`.clangd` 和 `.vscode/` 两个文件，按编译器的映射改 `.clangd` 的编译数据库目录和 `.vscode/settings.json` 的 `--query-driver` 路径。不要复制 `build/`。
+
+**已有工程**：先跑一次 `clang-format --dry-run --Werror` 和 `clang-tidy`，看现有配置实际报什么；只改导致当前失败或与声明环境冲突的项。不要借机重排全工程格式。
+
+**换编译器**：改 `.clangd` 的 `CompilationDatabase`，改 `--query-driver` 指向的编译器，清理旧构建目录；不要同时保留两套 clangd 配置。
+
+**GCC 模式**：`clangd` 仍可工作，但系统头来自 GCC；`--query-driver` 指向 `g++`。`clang-format` / `clang-tidy` 仍是 Clang 工具，版本要求不因编译器是 GCC 而降低。
+
+**共享库**：静态检查不因链接方式改变；运行时库路径在定构建的 CMake 里设置，不要写进 clang 配置。
+
+## 正反例指针
+
+- `.clangd` 指错编译数据库、`query-driver` 写进 YAML：`examples/tooling.md`。
+- 配置文件堆策略头、关闭检查不写理由：`examples/tooling.md`「配置注释」。
+- 工具调用与头文件过滤：`references/static-analysis.md`。

package/skills/building-cpp/steps/03-check.md

@@ -1,60 +1,60 @@
-# 第 3 步：通过检查
-
-## 产出
-
-一次可复现的通过记录：环境校验、配置、构建、格式化、静态检查、测试、运行都通过；失败时能指出是哪一步、哪个角色、哪条诊断。
-
-## 通用情况
-
-按固定顺序跑，前一步失败就停，不要带着失败继续：
-
-1. **校验环境声明（不带 `--live`）**：读 `environment.json`，检查三个轴和组合是否合法。轴为空或组合非法时，停在这里，不找可执行文件。
-2. **活动校验**：在声明的 build host 上跑 `--live`，核对 PATH 中的角色和版本。Windows 原生组合当前没有构建脚本，`--live` 会明确报告「缺的是 shell，不是编译器」。
-3. **跑项目入口命令**：项目技能里写的入口命令（如 `./running-build.sh clang`）。入口内部依次 configure → build → format → tidy → ctest → run；每一步失败都保留原始输出。
-4. **核对产物**：`build/<compiler>/compile_commands.json` 存在；`build/compile_commands.json` 指向当前编译器；`app` 可执行文件在 `build/<compiler>/bin`。
-5. **记录结果**：通过时记录编译器版本、构建目录、测试数量；失败时记录命令、退出码、第一条根因诊断。
-
-环境校验脚本：
-
-```bash
-node "<skill-dir>/scripts/checking-environment.mjs" --project .          # 声明校验
-node "<skill-dir>/scripts/checking-environment.mjs" --project . --live   # 活动校验
-```
-
-`<skill-dir>` 换成插件里 `building-cpp` 的实际目录；不要复制脚本到项目里再改。脚本只读，不安装、不下载、不改 PATH。
-
-## 失败分诊
-
-| 现象 | 先看 | 回到 |
-| --- | --- | --- |
-| 轴为空、组合非法、版本不匹配 | `environment.json`、`--live` 输出 | 定构建，先修声明 |
-| 找不到头文件、链接失败、target 不存在 | `CMakeLists.txt`、`target_include_directories`、`target_link_libraries` | 定构建 |
-| 没有 `compile_commands.json`、clangd 跳转失败 | 生成器、`CMAKE_EXPORT_COMPILE_COMMANDS`、`.clangd` 路径 | 定构建 / 定工具配置 |
-| `clang-format` 报格式 | 源码排版 | 定工具配置；只改格式，不改行为 |
-| `clang-tidy` 报命名/类型/现代 C++ 用法 | 源码声明或实现 | `developing-cpp` 的定声明 / 定实现 |
-| 编译错误指向声明或类型 | 头文件、类型定义、函数签名 | `developing-cpp` 的定声明 |
-| 编译错误指向函数体 | 实现 | `developing-cpp` 的定实现；先修语义，再重跑 |
-| CTest 失败 | 测试断言、行为句 | `developing-cpp` 的定行为 / 定实现 |
-| `app` 启动失败、找不到共享库 | 输出目录、RPATH / 运行时库路径 | 定构建 |
-
-分诊只定位，不自动改。一次只改一类问题；改完从失败的那一步重跑，只有行为或边界也变了才回到定行为。
-
-## 情况
-
-**第一次接工程**：先跑声明校验，再跑 `--live`；两者都过再跑入口命令。环境没声明对时，构建脚本再完美也会失败。
-
-**只改源码**：仍跑完整入口命令；格式化和静态检查可能暴露声明层问题，不要只看编译通过。
-
-**只改配置**：至少跑一次完整构建 + 格式化 + 静态检查；配置错误常常在 clangd 或 tidy 阶段才暴露。
-
-**没有测试**：CTest 显示没有测试是合法结果；不要为了「全绿」造空测试。行为验收由定行为的验收句负责。
-
-**Windows 原生**：当前版本没有 PowerShell 构建脚本；`--live` 会失败并说明缺 shell。不要伪造一个临时脚本绕过，也不要把 `build_host` 改成 `wsl` 来「让它过」；先和用户确认是否补脚本。
-
-**macOS**：`/usr/bin/clang++` 通常是 Apple Clang；`.clangd` 不写死 Homebrew 路径，clangd 要能经 xcrun 找到 SDK。`compiler=clang` 时 `--live` 按同一 LLVM 主版本核对 clang++、clang-format、clang-tidy、clangd；不要混用 Homebrew LLVM 与 Xcode 资源目录来凑版本，也不要为了通过而改 `environment.json` 的编译器。
-
-## 正反例指针
-
-- 环境组合与 `--live` 输出：`examples/environment.md`。
-- 失败分诊的具体命令：`references/build-script.md`「失败分诊」。
-- 工具调用细节：`references/static-analysis.md`。
+# 第 3 步：通过检查
+
+## 产出
+
+一次可复现的通过记录：环境校验、配置、构建、格式化、静态检查、测试、运行都通过；失败时能指出是哪一步、哪个角色、哪条诊断。
+
+## 通用情况
+
+按固定顺序跑，前一步失败就停，不要带着失败继续：
+
+1. **校验环境声明（不带 `--live`）**：读 `environment.json`，检查三个轴和组合是否合法。轴为空或组合非法时，停在这里，不找可执行文件。
+2. **活动校验**：在声明的 build host 上跑 `--live`，核对 PATH 中的角色和版本。Windows 原生组合当前没有构建脚本，`--live` 会明确报告「缺的是 shell，不是编译器」。
+3. **跑项目入口命令**：项目技能里写的入口命令（如 `./running-build.sh clang`）。入口内部依次 configure → build → format → tidy → ctest → run；每一步失败都保留原始输出。
+4. **核对产物**：`build/<compiler>/compile_commands.json` 存在；`build/compile_commands.json` 指向当前编译器；`app` 可执行文件在 `build/<compiler>/bin`。
+5. **记录结果**：通过时记录编译器版本、构建目录、测试数量；失败时记录命令、退出码、第一条根因诊断。
+
+环境校验脚本：
+
+```bash
+node "<skill-dir>/scripts/checking-environment.mjs" --project .          # 声明校验
+node "<skill-dir>/scripts/checking-environment.mjs" --project . --live   # 活动校验
+```
+
+`<skill-dir>` 换成插件里 `building-cpp` 的实际目录；不要复制脚本到项目里再改。脚本只读，不安装、不下载、不改 PATH。
+
+## 失败分诊
+
+| 现象 | 先看 | 回到 |
+| --- | --- | --- |
+| 轴为空、组合非法、版本不匹配 | `environment.json`、`--live` 输出 | 定构建，先修声明 |
+| 找不到头文件、链接失败、target 不存在 | `CMakeLists.txt`、`target_include_directories`、`target_link_libraries` | 定构建 |
+| 没有 `compile_commands.json`、clangd 跳转失败 | 生成器、`CMAKE_EXPORT_COMPILE_COMMANDS`、`.clangd` 路径 | 定构建 / 定工具配置 |
+| `clang-format` 报格式 | 源码排版 | 定工具配置；只改格式，不改行为 |
+| `clang-tidy` 报命名/类型/现代 C++ 用法 | 源码声明或实现 | `developing-cpp` 的定声明 / 定实现 |
+| 编译错误指向声明或类型 | 头文件、类型定义、函数签名 | `developing-cpp` 的定声明 |
+| 编译错误指向函数体 | 实现 | `developing-cpp` 的定实现；先修语义，再重跑 |
+| CTest 失败 | 测试断言、行为句 | `developing-cpp` 的定行为 / 定实现 |
+| `app` 启动失败、找不到共享库 | 输出目录、RPATH / 运行时库路径 | 定构建 |
+
+分诊只定位，不自动改。一次只改一类问题；改完从失败的那一步重跑，只有行为或边界也变了才回到定行为。
+
+## 情况
+
+**第一次接工程**：先跑声明校验，再跑 `--live`；两者都过再跑入口命令。环境没声明对时，构建脚本再完美也会失败。
+
+**只改源码**：仍跑完整入口命令；格式化和静态检查可能暴露声明层问题，不要只看编译通过。
+
+**只改配置**：至少跑一次完整构建 + 格式化 + 静态检查；配置错误常常在 clangd 或 tidy 阶段才暴露。
+
+**没有测试**：CTest 显示没有测试是合法结果；不要为了「全绿」造空测试。行为验收由定行为的验收句负责。
+
+**Windows 原生**：当前版本没有 PowerShell 构建脚本；`--live` 会失败并说明缺 shell。不要伪造一个临时脚本绕过，也不要把 `build_host` 改成 `wsl` 来「让它过」；先和用户确认是否补脚本。
+
+**macOS**：`/usr/bin/clang++` 通常是 Apple Clang；`.clangd` 不写死 Homebrew 路径，clangd 要能经 xcrun 找到 SDK。`compiler=clang` 时 `--live` 按同一 LLVM 主版本核对 clang++、clang-format、clang-tidy、clangd；不要混用 Homebrew LLVM 与 Xcode 资源目录来凑版本，也不要为了通过而改 `environment.json` 的编译器。
+
+## 正反例指针
+
+- 环境组合与 `--live` 输出：`examples/environment.md`。
+- 失败分诊的具体命令：`references/build-script.md`「失败分诊」。
+- 工具调用细节：`references/static-analysis.md`。