@chengzhao-dev/dsh-cpp-workflow 0.3.1 → 0.5.1

package/README.en.md

@@ -2,29 +2,30 @@
 
 [中文](README.md)
 
-Two skills for C++11–C++23 source and build work; new projects default to C++23. The plugin registers a skill provider only; it does not register tools, compile, download a toolchain, or write project files.
+Three skills for C++11–C++23 source, CMake, and build work; new projects default to C++23. The plugin registers a skill provider only; it does not register tools, compile, download a toolchain, or write project files.
 
 ## What it provides
 
 | Skill | Covers | Open it when |
 | --- | --- | --- |
 | `developing-cpp` | Behavior, boundaries, declarations, implementation; naming, exceptions, and source comments in `.h` / `.cpp` / `.cc` | The user names source code, or the work is a new project or whole-stage refactor |
-| `building-cpp` | Build setup, tool configuration, checks; CMake, Ninja, Clang config, build scripts, and environment combinations | The change touches build files, tool config, or the environment declaration, or the project is first connected to a build |
+| `configuring-cmake` | Targets, modules, checks; CMakeLists.txt, `cmake/` functions and modules, target properties, C++11–C++23 standards, 2-space layout | The change touches CMake targets, standards, link boundaries, functions, or modules |
+| `building-cpp` | Build setup, tool configuration, checks; Ninja, Clang config, build scripts, environment combinations, formatting, and static analysis | The change touches build commands, tool config, or the environment declaration, or the project is first connected to a build |
 
-The exception material follows the C++ Core Guidelines' Error handling section and guides source and examples only during development; the plugin runtime never compiles or executes those rules. Both skills read the project skill `cpp-workflow-project` first. Without it, the workspace gate never exposes these names.
+The exception material follows the C++ Core Guidelines' Error handling section and guides source and examples only during development; the plugin runtime never compiles or executes those rules. All three skills read the project skill `cpp-workflow-project` first. Without it, the workspace gate never exposes these names.
 
 ## Install
 
 Pinned npm install:
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.3.1
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.5.1
 ```
 
 The matching Git tag:
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.3.1
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.5.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.
@@ -35,7 +36,7 @@ Only one condition must hold before either skill appears: walking up from the cu
 
 The project skill marker is the repository's opt-in declaration. The plugin no longer requires a first-party `CMakeLists.txt` or C++ source file in the same repository: a docs-only repository, a repository that only copied the template, or a repository with no source files yet still matches; with an empty environment axis, the four source steps still work but build setup stops. Without the marker the list is empty, even when the repository contains CMake or `.cpp` files. Scan limits and boundary cases are in [docs/plugin-boundaries.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-boundaries.md).
 
-The packaged skills use rank 550. A project `.agents/skills` skill uses rank 200 and overrides a plugin skill with the same name; do not copy `developing-cpp` or `building-cpp` into a project.
+The packaged skills use rank 550. A project `.agents/skills` skill uses rank 200 and overrides a plugin skill with the same name; do not copy `developing-cpp`, `configuring-cmake`, or `building-cpp` into a project.
 
 ## Project conventions
 
@@ -57,7 +58,7 @@ Keep one `environment.json` per repository. Its first three environment axes are
 | `compiler` | `clang`, `gcc` | One compiler per configuration |
 | `standard` | `c++11`, `c++14`, `c++17`, `c++20`, `c++23` | New projects default to `c++23`; one standard per project |
 
-The standard lives in `environment.json` as `standard` and must match the CMake target and compile database. New projects default to C++23; for C++11–C++20, lower `standard`, `cxx_std_*`, `CXX_STANDARD`, and the `.clang-format` parsing level together, not one at a time. Per-standard facilities, tooling, and downgrade tables are in the [standard directory](skills/building-cpp/references/standards/README.md).
+The standard lives in `environment.json` as `standard` and must match the CMake target and compile database; on the CMake side, prefer `configuring-cmake`'s `CompileSettings_SetCxxStandard` function. New projects default to C++23; for C++11–C++20, lower `standard`, `cxx_std_*`, `CXX_STANDARD`, and the `.clang-format` parsing level together, not one at a time. Per-standard facilities, tooling, and downgrade tables are in the [standard directory](skills/building-cpp/references/standards/README.md); the CMake two-layer declaration is in [cxx-standard.md](skills/configuring-cmake/references/cxx-standard.md).
 
 The generator is always Ninja. Build directories are `build/clang/` and `build/gcc/`; they are never shared. Analysis tools are always `clang-format`, `clang-tidy`, and `clangd`; GCC mode does not switch to another analyzer.
 
@@ -77,7 +78,7 @@ The project root carries only `.vscode/extensions.json` and `settings.json`: cla
 ```text
 dsh-cpp-workflow/
 ├── lib/                 # build output, shipped in the npm package
-├── skills/              # developing-cpp and building-cpp
+├── skills/              # developing-cpp, configuring-cmake, and building-cpp
 ├── templates/           # empty project template to copy
 ├── package.json
 ├── package-lock.json    # repository only, used by npm ci
@@ -99,7 +100,7 @@ Requires Node.js 22 or newer.
 
 ```bash
 npm ci
-npm test              # build, structural check, gate/environment/schema/comment tests
+npm test              # build, three-skill structural check, gate/environment/schema/comment tests
 npm run test:matrix   # real build matrix: 4 templates x 5 standards
 npm run pack:check    # inspect the npm package contents
 ```

package/README.md

@@ -2,29 +2,30 @@
 
 [English](README.en.md)
 
-把 C++11–C++23 的源码工作和构建工作收成两个技能，新工程默认 C++23。插件只注册技能 provider，不注册工具、不编译、不下载工具链、不写项目文件。
+把 C++11–C++23 的源码、CMake 与构建工作收成三个技能，新工程默认 C++23。插件只注册技能 provider，不注册工具、不编译、不下载工具链、不写项目文件。
 
 ## 提供什么
 
 | 技能 | 管什么 | 什么时候打开 |
 | --- | --- | --- |
 | `developing-cpp` | 定行为、定边界、定声明、定实现；`.h` / `.cpp` / `.cc` 的命名、异常和源码注释 | 用户点名源码，或需要新建/整段重构源码 |
-| `building-cpp` | 定构建、定工具配置、通过检查；CMake、Ninja、Clang 配置、构建脚本和环境组合 | 改动落在构建文件、工具配置或环境声明上，或第一次接构建 |
+| `configuring-cmake` | 定 target、定模块、通过检查；CMakeLists.txt、`cmake/` 函数与模块、target 属性、C++11–C++23 标准、2 空格排版 | 改动落在 CMake target、标准、链接边界、函数或模块上 |
+| `building-cpp` | 定构建、定工具配置、通过检查；Ninja、Clang 配置、构建脚本、环境组合、格式化与静态检查 | 改动落在构建命令、工具配置或环境声明上，或第一次接构建 |
 
-异常条文采用 C++ Core Guidelines 的 Error handling，只在开发阶段指导源码和示例；插件运行时不编译、不执行这些规则。两个技能都先读项目技能 `cpp-workflow-project`。没有项目技能时，门禁不会放出这两个名字。
+异常条文采用 C++ Core Guidelines 的 Error handling，只在开发阶段指导源码和示例；插件运行时不编译、不执行这些规则。三个技能都先读项目技能 `cpp-workflow-project`。没有项目技能时，门禁不会放出这三个名字。
 
 ## 安装
 
 npm 安装钉死版本：
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.3.1
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.5.1
 ```
 
 同版本的 Git 标签：
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.3.1
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.5.1
 ```
 
 桌面应用独占 `desktop` profile。命令行 `add` 被拒绝时，在应用设置里添加插件，地址填同一个 npm 版本。Git 标签安装使用仓库内已构建的 `lib/`，不在目标机器上重新构建；包内也不含需要授权执行的安装脚本。
@@ -35,7 +36,7 @@ dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.3.1
 
 项目技能标记就是仓库选择加入本工作流的声明。插件不再要求同一仓库里已经有第一方 `CMakeLists.txt` 或 C++ 源文件：纯文档仓库、只复制了模板、还没有任何源文件的仓库也会出现；环境轴为空时，源码四步仍能做，但定构建会停。没有标记就返回空列表，即使仓库里有 CMake 或 `.cpp`。扫描上限和边界情形见 [docs/plugin-boundaries.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-boundaries.md)。
 
-插件技能 rank 550。项目自己的 `.agents/skills` 技能 rank 200，会以同名覆盖插件；不要在项目里复制 `developing-cpp` 或 `building-cpp`。
+插件技能 rank 550。项目自己的 `.agents/skills` 技能 rank 200，会以同名覆盖插件；不要在项目里复制 `developing-cpp`、`configuring-cmake` 或 `building-cpp`。
 
 ## 项目级约定
 
@@ -57,7 +58,7 @@ dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.3.1
 | `compiler` | `clang`、`gcc` | 一次配置一个编译器 |
 | `standard` | `c++11`、`c++14`、`c++17`、`c++20`、`c++23` | 新工程默认 `c++23`；一个工程一个标准 |
 
-标准写在 `environment.json` 的 `standard`，并同步到 CMake target 和编译数据库。新工程默认 C++23；C++11–C++20 工程把 `standard`、`cxx_std_*`、`CXX_STANDARD` 和 `.clang-format` 的解析档位一起降级，不要只改一处。每档的设施、工具和降档表见 [标准目录](skills/building-cpp/references/standards/README.md)。
+标准写在 `environment.json` 的 `standard`，并同步到 CMake target 和编译数据库；CMake 侧优先调用 `configuring-cmake` 提供的 `CompileSettings_SetCxxStandard` 函数。新工程默认 C++23；C++11–C++20 工程把 `standard`、`cxx_std_*`、`CXX_STANDARD` 和 `.clang-format` 的解析档位一起降级，不要只改一处。每档的设施、工具和降档表见 [标准目录](skills/building-cpp/references/standards/README.md)，CMake 两层声明见 [cxx-standard.md](skills/configuring-cmake/references/cxx-standard.md)。
 
 生成器固定 Ninja，构建目录是 `build/clang/` 与 `build/gcc/`，不共用 `build/`。诊断工具固定 `clang-format`、`clang-tidy`、`clangd`；GCC 模式也不换成别的分析器。
 
@@ -77,7 +78,7 @@ node "<skill-dir>/scripts/checking-environment.mjs" --project . --live
 ```text
 dsh-cpp-workflow/
 ├── lib/                 # 构建产物，随 npm 包发布
-├── skills/              # developing-cpp 与 building-cpp
+├── skills/              # developing-cpp、configuring-cmake 与 building-cpp
 ├── templates/           # 复制到项目的空模板
 ├── package.json
 ├── package-lock.json    # 只在仓库，供 npm ci
@@ -99,7 +100,7 @@ dsh-cpp-workflow/
 
 ```bash
 npm ci
-npm test              # 构建、结构检查、门禁/环境/schema/注释测试
+npm test              # 构建、三技能结构检查、门禁/环境/schema/注释测试
 npm run test:matrix   # 四套模板 × 五档标准的真实构建矩阵
 npm run pack:check    # 核对 npm 包内容
 ```

package/lib/index.js

@@ -1,6 +1,6 @@
 // dsh-cpp-workflow bundle entry.
 //
-// Registers the two packaged skills as one bundle-scoped skill provider. The
+// Registers the three packaged skills as one bundle-scoped skill provider. The
 // provider is read-only and scans only `skills/<name>/SKILL.md`; each skill
 // directory becomes the resourceBase so relative steps, references, examples
 // and assets resolve from the installed package.
@@ -15,8 +15,8 @@
 //
 // Rank 550 is lower priority than project/user skills (project `.agents/skills`
 // 200, user `.agents/skills` 500) and higher priority than the bundled root
-// (600), so a project can override either skill by name without editing the
-// package. The project skill itself (cpp-workflow-project, rank 200) is a
+// (600), so a project can override any packaged skill by name without editing
+// the package. The project skill itself (cpp-workflow-project, rank 200) is a
 // separate name and does not collide.
 import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
@@ -26,7 +26,7 @@ export const name = 'dsh-cpp-workflow';
 export const inject = ['skills'];
 const PROVIDER = 'dsh-cpp-workflow';
 const RANK = 550;
-const KNOWN_SKILLS = new Set(['building-cpp', 'developing-cpp']);
+const KNOWN_SKILLS = new Set(['building-cpp', 'configuring-cmake', 'developing-cpp']);
 const SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const PACKAGE_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const SKILLS_ROOT = path.join(PACKAGE_ROOT, 'skills');

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "C++ Workflow",
-    "description": "Four source steps and three build steps for C++11–C++23 projects (C++23 by default), checked against the environment the project declares."
+    "description": "Four source steps, three CMake steps, and three build steps for C++11–C++23 projects (C++23 by default), checked against the environment the project declares."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "C++ 工程流程",
-    "description": "用源码四步与构建三步推进 C++11–C++23 工程（默认 C++23），并在项目声明的环境组合里核对构建与 clang 工具链。"
+    "description": "用源码四步、CMake 三步与构建三步推进 C++11–C++23 工程（默认 C++23），并在项目声明的环境组合里核对构建与 clang 工具链。"
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chengzhao-dev/dsh-cpp-workflow",
-  "version": "0.3.1",
-  "description": "C++11–C++23 工程流程技能包：源码四步与构建三步，按项目声明的环境组合校验 · C++11–C++23 workflow skills for DeepSeek Harness",
+  "version": "0.5.1",
+  "description": "C++11–C++23 工程流程技能包：源码四步、CMake 三步与构建三步，按项目声明的环境组合校验 · C++11–C++23 workflow skills for DeepSeek Harness",
   "type": "module",
   "main": "./lib/index.js",
   "exports": {

package/skills/building-cpp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: building-cpp
-description: 用 CMake、Ninja、clang-format、clang-tidy、clangd 配置、构建和检查 C++11–C++23 工程时使用；新工程默认 C++23；按定构建、定工具配置、通过检查三步推进。一次改动同时碰到源码和构建文件时，先打开 developing-cpp。不用于只改源码语义、文档、Python 或与 C++ 无关的文件。
+description: 在已经写好 CMake 的 C++11–C++23 工程上配置、构建和检查时使用：Ninja、compile_commands.json、clang-format、clang-tidy、clangd、environment.json 与 running-build.sh；按定构建、定工具配置、通过检查三步推进。要编写或重构 CMakeLists.txt / cmake 模块时先开 configuring-cmake。一次改动同时碰到源码和构建文件时，先打开 developing-cpp。不用于只改源码语义、文档、Python 或与 C++ 无关的文件。
 metadata:
   short-description: C++11–C++23 构建三步
 ---
@@ -9,38 +9,59 @@ metadata:
 
 ## 适用场景
 
-管 `CMakeLists.txt`、`cmake/`、`running-build.sh`、`.clang-format`、`.clang-tidy`、`.clangd`、`.vscode/` 和 `environment.json`。函数体、类型、命名、异常和源码注释只开 `developing-cpp`。一次改动同时碰到源码和构建文件时，先打开 `developing-cpp`：只改函数体、命名、异常或注释且入口命令可运行时，定实现后直接到本技能的通过检查；新增或移动源文件、改库与程序的边界、补测试 target 时，到本技能先做定构建，把文件写进 CMake，再决定是否定工具配置，最后通过检查。`.qmd`、仓库 README、Python 和非 C++ 文档不打开本技能。
+管 `environment.json`、`running-build.sh`、`.clang-format`、`.clang-tidy`、`.clangd`、`.vscode/`、构建命令、编译数据库、CTest 和运行。`CMakeLists.txt` 与 `cmake/` 下的 target、属性、标准和模块由 `configuring-cmake` 负责；本技能只读它们来配置和检查，不在这一步改 target 图。函数体、类型、命名、异常和源码注释只开 `developing-cpp`。
 
-编译失败先分因：诊断指向函数体，回 `developing-cpp` 的定实现；诊断指向声明或类型，回定声明；诊断是找不到头、链接失败、没有编译数据库或工具不在 PATH，留在本技能的定构建或定工具配置。
+一次改动同时碰到源码和构建文件时，先打开 `developing-cpp` 定行为、边界与实现；需要新增或移动源文件、改库与程序的边界、补测试 target 时，转到 `configuring-cmake` 把文件写进 CMake；最后回到本技能做定工具配置与通过检查。只改函数体、命名、异常或注释且入口命令可运行时，定实现后只开本技能的「通过检查」。
 
-源码和构建文件用 UTF-8 无 BOM、检出 LF；`.bat` / `.cmd` 用 CRLF；`.clang-format` 写 `LineEnding: LF`。MSVC 原生构建优先加 `/utf-8`，不要靠 BOM 过关。完整规则见 `references/encoding.md`，检查脚本是 `scripts/checking-encoding.mjs`，机器规则以仓库根 `.gitattributes` 与 `.editorconfig` 为准。
+存在项目技能 `cpp-workflow-project` 时先读它的 `SKILL.md`、`environment.json` 和 `stages/stage-table.md`。三个环境轴为空、`standard` 非法或组合非法时停在定构建，不猜 WSL、Clang 或构建目录；`windows` + `native` 直接拒绝，提示「本版本不能在 Windows 原生壳里构建」，不要给出补 PowerShell 的路线。
+
+编译失败先分因：诊断指向函数体，回 `developing-cpp` 的定实现；诊断是找不到头、链接失败、target 不存在或标准不对，转 `configuring-cmake` 的对应步骤；诊断是没有编译数据库、format/tidy 不在 PATH 或配置不生效，留在本技能的定工具配置。
 
-存在项目技能 `cpp-workflow-project` 时先读它的 `SKILL.md`、`environment.json` 和 `stages/stage-table.md`。三个环境轴为空、`standard` 非法或组合非法时停在定构建，不猜 WSL、Clang 或构建目录；`windows` + `native` 直接拒绝，提示「本版本不能在 Windows 原生壳里构建」，不要给出补 PowerShell 的路线。环境组合空着时源码四步仍可做，只是不能构建。
+源码和构建文件用 UTF-8 无 BOM、检出 LF；`.bat` / `.cmd` 用 CRLF；`.clang-format` 写 `LineEnding: LF`。MSVC 原生构建优先加 `/utf-8`，不要靠 BOM 过关。完整规则见 `references/encoding.md`，检查脚本是 `scripts/checking-encoding.mjs`，机器规则以仓库根 `.gitattributes` 与 `.editorconfig` 为准。
 
 ## 两种走法
 
 | 走法 | 什么时候用 | 怎么做 |
 | --- | --- | --- |
-| 增量修正 | 用户点了一条链接错误、一个工具配置或一条诊断 | 先判断属于定构建还是定工具配置，只改那一处，不动无关 target 和配置 |
-| 整段重构 | 新工程、新阶段、换环境组合，或第一次接构建 | 同样三步；先定 target 和目录，再改工具文件，最后跑完整检查 |
+| 增量修正 | 用户点了一条工具配置、一条诊断或一个入口脚本错误 | 先判断属于定构建还是定工具配置，只改那一处，不动无关 target 和配置 |
+| 整段重构 | 新工程、新阶段、换环境组合，或第一次接构建 | 同样三步；先确认 target 与标准已由 configuring-cmake 写好，再改工具文件，最后跑完整检查 |
 
-共同不变量：不发明项目没有声明的环境轴、命令和 target；只改格式或配置时不改可观察行为；不覆盖已有源码、`CMakeLists.txt` 和 `.clang-*`；不安装工具链；代理侧不写 `wsl` 或 `bash -lc`。后一步发现前一步没做完，退回那一步。拿不准先用增量修正；发现环境轴、编译器或构建目录需要改，退回整段，从定构建重走。
+共同不变量：不发明项目没有声明的环境轴、命令和 target；只改格式或配置时不改可观察行为；不覆盖已有源码、`CMakeLists.txt` 和 `.clang-*`；不安装工具链；代理侧不写 `wsl` 或 `bash -lc`。后一步发现前一步没做完，退回那一步。拿不准先用增量修正；发现环境轴、编译器、构建目录或 target 契约需要改，退回整段，并转 `configuring-cmake`。
 
 ## 步骤
 
 | 步 | 名称 | 文件 | 一句话 |
 | --- | --- | --- | --- |
-| 1 | 定构建 | `steps/01-build.md` | 一次配置一个编译器，Ninja，target-based CMake，编译数据库 |
+| 1 | 定构建 | `steps/01-build.md` | 读环境声明，固定 Ninja 与单一编译器，产出编译数据库 |
 | 2 | 定工具配置 | `steps/02-tooling.md` | 格式化、静态检查、clangd 各管一段，互不越界 |
 | 3 | 通过检查 | `steps/03-check.md` | 按编码 → 声明校验 → 活动校验 → 项目入口的次序跑，前一步失败就停 |
 
-每步只打开同号的一个步骤文件。判不准才打开 `examples/` 里与该步对应的案例；`references/` 保存完整条文，只在排错、整目录重构，或步骤里明确指向某一条文时按需打开。链接、rpath 与产物布局读 `references/linking.md`；警告选项、GoogleTest 与 rpath 的 CMake 片段在 `assets/cmake/`，由 `references/cmake.md` 指路。
+每步只打开同号的一个步骤文件。判不准才打开 `examples/` 里与该步对应的案例；`references/` 保存完整条文，只在排错、整目录重构，或步骤里明确指向某一条文时按需打开。链接、rpath 与产物布局读 `references/linking.md`；CMake 的 target、标准和函数写法读 `../configuring-cmake/references/`，可复用片段在 `../configuring-cmake/assets/cmake/`。
+
+本轮激活按三条上限走：
+
+- 只开当前步对应的一个步骤文件；本轮已经开了别的技能，就不再开第二个技能的步骤。
+- 条文只开该步点名的一份；同号案例留到下一次激活。
+- 标准档只打开项目技能声明的那一档，没有声明时用本技能已有的新工程默认，不把其余标准档读进来。
+
+项目技能列出了检查命令时只跑那一条，没有时跑本技能自己的 `scripts/checking-environment.mjs` 与 `scripts/checking-encoding.mjs`；退出码为 0 后在同一轮结束 goal，不再继续走没有失败的步骤。
+
+### 四类改动
+
+先认这次改的是哪一类，再决定从哪一步进；一次改动混了两类时，按「写作 → 布局 → 排版 → 润色」的次序拆开做。
+
+| 类型 | 典型请求 | 从哪进 | 先读哪份条文 |
+| --- | --- | --- | --- |
+| 写作 | 改环境轴、入口脚本或构建流程 | 第 1 步 | `steps/01-build.md`、`references/environment.md`、`references/build-script.md` |
+| 布局 | 移动工具配置文件、补 `.vscode/` | 第 2 步 | `steps/02-tooling.md`、`examples/tooling.md` |
+| 排版 | 只改编码、行尾或 clang-format | 第 2 步 | `references/encoding.md`、`steps/02-tooling.md` |
+| 润色 | 只改诊断措辞、失败分流说明 | 第 3 步 | `steps/03-check.md`、`references/build-script.md` |
 
 ## 完成判据
 
 - 项目 `environment.json` 的三个环境轴齐全且是合法组合，`standard` 在 `c++11`–`c++23` 内；新工程默认 `c++23`，没有靠猜。
 - 配置命令固定 Ninja 和单一编译器，`build/<compiler>/compile_commands.json` 存在，根 `build/compile_commands.json` 指向当前编译器。
-- 标准写在 target 上（`CXX_STANDARD` + `CXX_STANDARD_REQUIRED ON` + `cxx_std_*`），`CXX_EXTENSIONS OFF`；`compile_commands.json` 的实际 `-std` 与 `environment.json` 一致，没有全局 `include_directories()` 或 GLOB。
+- target 契约已经成立：程序 `app`、库 target、公共 include、标准与输出目录都已由 `configuring-cmake` 写好；本技能没有偷偷改 CMake 来绕过失败。
 - `clang-format --dry-run --Werror` 与 `clang-tidy` 在项目源码上零告警；只扫描项目源码和项目头。
 - CTest 全绿，程序从该编译器的构建目录启动；失败时报告的是具体角色和原因。
 - 没有改源码语义，没有覆盖已有工程文件，也没有安装或下载任何工具。

package/skills/building-cpp/references/build-script.md

@@ -40,6 +40,17 @@
 - 失败时保留原始命令输出；不要在脚本里 `2>/dev/null` 吞掉诊断。
 - 脚本自身用 `bash -n` 检查语法；文件权限保持可执行。
 
+## 构建模式的错误合同
+
+脚本可以为 Debug、Release 各跑一次；模式只改变诊断详略，不改变失败方式：
+
+- 返回值：两种模式的返回值相同，调用方不按 `NDEBUG` 分支。
+- 自定义异常：两种模式都抛；Debug 的 `what()` 可以带 `file:line`，Release 只留值。
+- `Check`：两种模式都在条件不成立时打印诊断并终止。
+- `DebugCheck`：只在 Debug 生效，`NDEBUG` 后展开为空，参数不能带副作用。
+
+不要写成 Debug 抛异常、Release 返回 false 的模式分支；这会把调用方逼成两套逻辑。规则详见 `developing-cpp/references/exceptions.md`。
+
 ## 失败分诊
 
 | 输出 | 先看 | 回到 |

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

@@ -65,7 +65,7 @@ build/<compiler>/
 - 运行时动态加载器默认不搜索可执行文件旁边的 `lib/`；需要 RPATH：
   - Linux：`-Wl,-rpath,'$ORIGIN/../lib'`
   - macOS：`-Wl,-rpath,@loader_path/../lib`
-- CMake 用 `BUILD_RPATH` / `INSTALL_RPATH` 设置，不要手工拼链接命令；见 `assets/cmake/setting-rpath.cmake`。
+- CMake 用 `BUILD_RPATH` / `INSTALL_RPATH` 设置，不要手工拼链接命令；见 [`LinkSettings.cmake`](../../configuring-cmake/assets/cmake/LinkSettings.cmake)。
 - RPATH 里的 `$ORIGIN` 要防止被 shell 展开：CMake 字符串里写 `\$ORIGIN` 或使用 `BUILD_RPATH_USE_ORIGIN`。
 
 ## 验收：`file` 与 `ldd`

package/skills/building-cpp/references/standards/README.md

@@ -160,6 +160,6 @@ target_link_options(app PRIVATE -stdlib=libc++)
 ## 相关文件
 
 - [environment.md](../environment.md)：四轴声明与校验。
-- [cmake.md](../cmake.md)：CMake 形状与排版。
+- [configuring-cmake/references/cxx-standard.md](../../../configuring-cmake/references/cxx-standard.md)：C++11–C++23 在 CMake 里的两层声明与验证。
 - [static-analysis.md](../static-analysis.md)：clang-format / clang-tidy / clangd 分工。
 - [01-build.md](../../steps/01-build.md)：定构建步骤。

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

@@ -2,10 +2,9 @@
 
 ## 产出
 
-一组 target-based 的 CMake 规则、一个固定的构建目录、一个可用的编译数据库。构建结果只取决于 `environment.json` 声明的组合，不取决于当前 shell 碰巧有什么。
+一个固定的构建目录、一个可用的编译数据库、一组可复现的配置与构建命令。构建结果只取决于 `environment.json` 声明的组合，不取决于当前 shell 碰巧有什么。
 
 ```text
-CMakeLists.txt
 build/
   clang/                 # compiler=clang
     compile_commands.json
@@ -14,37 +13,32 @@ build/
   compile_commands.json  # 指向上面的当前数据库
 ```
 
-## 通用情况
+## 前置
 
-先读 `environment.json`。源文件清单来自 `developing-cpp` 的定边界和定实现；定构建只把它们写进 target，不重新决定库与程序的边界。三个环境轴加语言标准分别表示：
+先读项目技能与 `environment.json`，再确认 `configuring-cmake` 已经把 target 图、公共 include、语言标准和输出目录写进 CMake。target 缺失、标准不对、include 或链接边界没写时，停止本步，转 `configuring-cmake` 的定 target 与标准；不要在这里用全局变量或临时 `-std` 绕过。
+
+## 环境
 
 | 轴 | 取值 | 含义 |
 | --- | --- | --- |
 | `host` | `windows` / `linux` / `macos` | 编辑器与代理壳所在系统 |
-| `build_host` | `native` / `wsl` | 执行编译和运行产物的环境；`native` 表示 `host` 本机，`wsl` 表示 Windows 的 WSL，且只允许 `host=windows`；`windows` + `native` 本版本不支持 |
+| `build_host` | `native` / `wsl` | 执行编译和运行产物的环境；`wsl` 只允许 `host=windows`；`windows` + `native` 本版本不支持 |
 | `compiler` | `clang` / `gcc` | 用哪个编译器；一次只配一个 |
 | `standard` | `c++11`–`c++23` | 一个工程一个语言标准；新工程默认 `c++23`，已有工程按原声明 |
 
-环境轴为空、`standard` 非法或组合非法（如 `host=linux` + `build_host=wsl`、`host=windows` + `build_host=native`）时，停在定构建，先让用户把 `environment.json` 填对。不要替用户选 WSL、Clang 或构建目录。`windows` + `native` 只给一句「本版本不能在 Windows 原生壳里构建」，不要建议改 WSL、不要提出补 PowerShell 脚本。
+环境轴为空、`standard` 非法或组合非法时，停在定构建，先让用户把 `environment.json` 填对。不要替用户选 WSL、Clang 或构建目录。`windows` + `native` 只给一句「本版本不能在 Windows 原生壳里构建」。
 
-构建规则：
+## 规则
 
-- CMake 最低 3.20；`project(... LANGUAGES CXX)`；只有确有 C 源时才写 `LANGUAGES C CXX`。新工程默认标准 C++23；已有工程按 `environment.json` 的 `standard` 或现有 target 声明，不擅自升降。
-- 生成器固定单配置 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 只链接被测库的公共接口。头文件按 Google 规则从仓库根写完整路径，构建时把仓库根加入搜索路径，不要改成组件的 `include/` 根后再写裸文件名。
-- `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_23)`；库用 `PUBLIC` 传播标准。再加 `set_target_properties(... CXX_STANDARD 23 CXX_STANDARD_REQUIRED ON CXX_EXTENSIONS OFF)`：meta-feature 只保证“至少”，`CXX_STANDARD_REQUIRED` 防 decay，`CXX_EXTENSIONS OFF` 把 `-std=gnu++23` 收成 `-std=c++23`。configure 后读 `compile_commands.json` 的最后一个 `-std=`，必须与 `environment.json` 的 `standard` 一致。
-- 工程确有 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 模块，只把下载用于测试依赖。
+- 生成器固定单配置 Ninja，不用 Ninja Multi-Config：同一源文件会写多条命令，clangd 默认只取第一条，容易读错数据库；构建目录固定 `build/clang` 或 `build/gcc`。
+- 一个 configure 只用一个编译器：`-DCMAKE_CXX_COMPILER=clang++` 或 `g++`；确有 C 源时 C 编译器与 C++ 编译器同属一套。
+- `set(CMAKE_EXPORT_COMPILE_COMMANDS ON)` 由 `configuring-cmake` 写在顶层；Ninja 下产出 `compile_commands.json`。
+- 输出目录由 `configuring-cmake` 统一设到 `build/<compiler>/bin` 与 `build/<compiler>/lib`；本步只核对，不重复设。
+- 配置后把 `build/<compiler>/compile_commands.json` 符号链接到 `build/compile_commands.json`，让 clangd 默认能找到当前数据库；换编译器时重建链接。
+- 不写全局 `CMAKE_CXX_FLAGS`、`include_directories()` 或 `add_definitions()`；这些属于 target 契约，发现就转 `configuring-cmake`。
+- 配置阶段不隐式下载依赖；测试框架由项目显式选择固定版本、带哈希的 `FetchContent`，或使用项目自带模块。
 
-命令形状：
+## 命令
 
 ```bash
 cmake -S . -B build/clang -G Ninja \
@@ -56,23 +50,16 @@ 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；不要依赖上一次的缓存。
+GCC 模式把目录和编译器换成 `build/gcc`、`g++`。每次构建都重新 configure；不要依赖上一次缓存。
 
 ## 情况
 
-**新工程**：从 `assets/templates/projects/` 选形态：`single` 单文件、`multi` 多文件单程序、`static-library` 静态库 + 程序、`shared-library` 动态库 + 程序。只复制目标工程缺的文件；已有的 `CMakeLists.txt`、`.clang-*`、源码不覆盖。模板里的 `{{PROJECT_NAME}}` 换成真实工程名，默认标准 C++23；四套模板已按 `__cplusplus` 条件使用 `std::format`，把 `standard`、`cxx_std_*`、`CXX_STANDARD` 和 `.clang-format` 的解析档位一起降到 C++11–C++20 后仍应能构建，降完跑 `references/standards/README.md` 的五档矩阵。模板源码是 `.cpp`，头文件用路径式 `#define` 守卫；新增文件沿用 `.cpp` / `.h`，已有工程保持原有扩展名。
-
-**已有工程**：先读现有 `CMakeLists.txt`，找出全局设置、GLOB、输出目录和 target 命名；只改与当前任务相关的一处。大改前先让通过检查的项目入口跑通，保留可回退点。
-
-**库 + 程序**：库 target 的 `PUBLIC` include 根按项目约定设置；本工作流把仓库根作为源码根，程序按 `#include "component/include/name.h"` 包含公共头，不直接包含库的 `src/`。静态库与动态库的接口相同；动态库额外设置运行时库路径。
+**新工程**：从 `../assets/templates/projects/` 选形态；模板缺 target 时先转 `configuring-cmake`，target 齐了再 configure。
 
-**测试**：`enable_testing()` 放在顶层，`add_subdirectory(tests)` 在 `add_subdirectory(<component>)` 之后；测试 target 用 `add_test(NAME ... COMMAND ...)` 注册。没有测试时不要为了「看起来完整」加空测试。
+**已有工程**：先读现有 `CMakeLists.txt`，只核对 target、标准与输出目录；不改与当前任务无关的 target，大改前先让现有构建跑通。
 
-**CMakePresets**：如果项目使用 preset，名称固定 `clang` / `gcc`，与构建目录一致；没有 preset 时直接用上面的命令，不要两套并存。
+**测试**：`enable_testing()` 与 `add_subdirectory(tests)` 的顺序由 `configuring-cmake` 定；本步只跑 CTest，不在没有测试时加空测试。
 
-## 正反例指针
+**CMakePresets**：如果项目使用 preset，名称固定 `clang` / `gcc`，与构建目录一致；没有 preset 时直接用上面的命令。
 
-- 全局 include、GLOB、把 `main()` 编进库：`examples/cmake.md`。
-- 正确的最小库 + 程序：`examples/cmake.md`「最小可用形状」。
-- target 与目录的完整说明：`references/cmake.md`。
-- 五档标准的下限、降档替换和工具映射：`references/standards/README.md`。
+下一步：构建可用后，进 `steps/02-tooling.md` 配格式、静态检查与 clangd。

package/skills/configuring-cmake/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: configuring-cmake
+description: 在 C++11–C++23 工程里编写或重构 CMake 时使用：CMakeLists.txt、cmake 模块、target 与属性、依赖与输出目录、语言标准与编译选项、2 空格排版；新工程默认 C++23。改 .h/.cpp 源码先开 developing-cpp；只配置、构建或跑工具链时开 building-cpp。不用于 Quarto、Python 或非 C++ 文档。
+metadata:
+  short-description: CMake 配置三步
+---
+
+# configuring-cmake
+
+## 适用场景
+
+管 `CMakeLists.txt`、`cmake/` 下的模块、`target_*` 命令、目标属性、include 与链接边界、输出目录、共享库运行时路径、`FetchContent`、preset 与安装导出。函数体、类型、命名、异常和源码注释只开 `developing-cpp`；配置完成后要跑构建、格式化、静态检查或入口脚本时开 `building-cpp`。
+
+一次改动同时碰到源码和 CMake 时先开 `developing-cpp` 定行为与边界，再用本技能把源文件、库和程序写进 target，最后到 `building-cpp` 跑检查。只改一个 target 的 include、链接或标准时走增量修正；新工程、新组件、换语言标准或抽公共函数时走整段重构。
+
+存在项目技能 `cpp-workflow-project` 时先读它的 `SKILL.md`、`environment.json` 和 `stages/stage-table.md`。`environment.json` 的 `standard` 是 target 标准的唯一来源；缺失、非法或与现有 target 不一致时停在定 target，不猜标准。构建目录、编译器和工具版本由 `building-cpp` 的定构建负责，本技能只写 target 契约。
+
+## 两种走法
+
+| 走法 | 什么时候用 | 怎么做 |
+| --- | --- | --- |
+| 增量修正 | 一个 target 的 include、链接、标准、输出目录或一条属性不对 | 先读现有 `CMakeLists.txt`，只改这一处，不动无关 target 和全局设置 |
+| 整段重构 | 新工程、新组件、抽公共函数、换语言标准或整理目录 | 同样三步；先定 target 图与标准，再定模块与函数，最后跑完整检查 |
+
+共同不变量：不发明项目没有声明的 target、标准、编译器或目录；不覆盖已有 `CMakeLists.txt`；不用全局 `include_directories()`、`add_definitions()`、`CMAKE_CXX_FLAGS` 给所有 target 加料；不写 `file(GLOB ...)`；不把 `main()` 编进库；库与程序不下载依赖，只有测试需要时调用 `LinkSettings_FetchGoogleTest`。后一步发现前一步没做完，退回那一步。
+
+## 步骤
+
+| 步 | 名称 | 文件 | 一句话 |
+| --- | --- | --- | --- |
+| 1 | 定 target 与标准 | `steps/01-targets.md` | target 图、PUBLIC/PRIVATE、标准、输出目录与编译数据库 |
+| 2 | 定模块与函数 | `steps/02-modules.md` | 何时抽函数、文件与命名、导入、注释与 2 空格排版 |
+| 3 | 通过检查 | `steps/03-check.md` | configure、构建、编译数据库与实际 `-std` 核对 |
+
+每步只打开同号的一个步骤文件。判不准才打开 `examples/cmake.md`；`references/cmake.md` 保存 target、链接、输出、RPATH、依赖与反模式的完整条文，`references/cxx-standard.md` 保存 C++11–C++23 的标准映射，`references/modules.md` 保存函数与模块契约。可复制的函数在 `assets/cmake/`：`CompileSettings.cmake` 放标准与警告，`LinkSettings.cmake` 放构建期 RPATH 与 GoogleTest 依赖；一个文件按性质收一组函数。
+
+本轮激活按三条上限走：
+
+- 只开当前步对应的一个步骤文件；本轮已经开了别的技能，就不再开第二个技能的步骤。
+- 条文只开该步点名的一份；同号案例留到下一次激活。
+- 标准档只打开项目技能声明的那一档，没有声明时用本技能已有的新工程默认，不把其余标准档读进来。
+
+项目技能列出了检查命令时只跑那一条，没有时跑插件根目录的 `npm test`；退出码为 0 后在同一轮结束 goal，不再继续走没有失败的步骤。
+
+五档标准的语言设施、工具映射与降档仍由 `building-cpp/references/standards/` 维护；本技能只负责这些标准在 CMake 里怎么写。
+
+### 四类改动
+
+先认这次改的是哪一类，再决定从哪一步进；一次改动混了两类时，按「写作 → 布局 → 排版 → 润色」的次序拆开做。
+
+| 类型 | 典型请求 | 从哪进 | 先读哪份条文 |
+| --- | --- | --- | --- |
+| 写作 | 新增 target、改公共 include 或链接边界、换语言标准 | 第 1 步 | `steps/01-targets.md`、`references/cxx-standard.md` |
+| 布局 | 抽函数、拆模块、调导入位置 | 第 2 步 | `steps/02-modules.md`、`references/modules.md` |
+| 排版 | 只改 2 空格、行宽或注释形态 | 第 2 步的契约写法 | `references/cmake.md`、`references/modules.md` |
+| 润色 | 只改函数名、注释措辞或错误消息 | 第 2 步 | `references/modules.md` |
+
+## 完成判据
+
+- target 图显式：程序 target 叫 `app`，库 target 用组件名，程序链接库，库的公共 include 用 `PUBLIC`；没有全局 include、全局编译选项或 GLOB。
+- 每个 target 的标准来自 `environment.json`；`target_compile_features` 与 `CXX_STANDARD`、`CXX_STANDARD_REQUIRED ON`、`CXX_EXTENSIONS OFF` 同时存在，live 的 `compile_commands.json` 最后一条 `-std=` 与声明一致，不是 `gnu++NN`。
+- 复用的 CMake 函数放在 `cmake/` 模块里，文件名用 UpperCamelCase，函数名用 `<ModuleName>_` 加 PascalCase，有目标与参数校验，根 `CMakeLists.txt` 通过 `CMAKE_MODULE_PATH` 导入；没有重复片段和未使用的旧模块。
+- 公开函数上方写中文 `#` 契约：一句功能、空行、边界，再用 `:param` / `:keyword` 标参数；不写 `#[[.rst:` 与 `.. command::`，完整写法见 `references/cmake.md`；函数组之间用 `#---`，不画 `#===...===#` 方框。
+- `CMakeLists.txt` 与 `*.cmake` 用 UTF-8 无 BOM、LF、2 空格缩进、不用 tab；行宽按团队约定，默认 80 列。
+- configure 与构建通过，构建产物不落在源码目录；没有改源码语义，也没有覆盖已有工程文件。