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

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

@@ -2,6 +2,12 @@
 
 目标：一个编译器、Ninja、target-based 规则、可用的编译数据库。下面是最小形状和常见边界；模板在 `assets/templates/projects/`。
 
+## 排版
+
+CMake 没有官方风格指南。这里跟随 Google 自家项目的 `cmake-format` 配置：缩进 2 个空格、行宽 80、不用 tab。来源是 [or-tools 的 .cmake-format.py](https://github.com/google/or-tools/blob/stable/.cmake-format.py) 与 [draco 的 .cmake-format.py](https://github.com/google/draco/blob/master/.cmake-format.py)，两处都设 `tab_size=2`、`line_width=80`。命令行、列表和注释都按这个宽度换行；`CMakeLists.txt` 与 `*.cmake` 一视同仁。
+
+Shell 脚本用 2 个空格缩进、不用 tab，来源是 [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html#indentation)。
+
 ## 最小可用形状
 
 ### 单文件
@@ -13,9 +19,13 @@ 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)
+add_executable(app src/main.cc)
+target_compile_features(app PRIVATE cxx_std_23)
+set_target_properties(app PROPERTIES
+  CXX_STANDARD 23
+  CXX_STANDARD_REQUIRED ON
+  CXX_EXTENSIONS OFF
+)
 target_compile_options(app PRIVATE -Wall -Wextra -Werror)
 ```
 
@@ -32,32 +42,40 @@ 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)
+add_executable(app src/main.cc)
+target_compile_features(app PRIVATE cxx_std_23)
+set_target_properties(app PROPERTIES
+  CXX_STANDARD 23
+  CXX_STANDARD_REQUIRED ON
+  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)
+add_library(greeting STATIC src/greeting.cc)
+target_include_directories(greeting PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/..)
+target_compile_features(greeting PUBLIC cxx_std_23)
+set_target_properties(greeting PROPERTIES
+  CXX_STANDARD 23
+  CXX_STANDARD_REQUIRED ON
+  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 都要设。
+- 库的 `PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/..` 让程序能从仓库根写 `#include "greeting/include/greeting.h"`，不需要程序再写 include 路径。
+- `cxx_std_23` 用 `PUBLIC` 从库传播；程序自己再加一次也无害。`CXX_STANDARD_REQUIRED ON` 防止 CMake 在编译器不支持时静默 decay；显式 `CXX_STANDARD` 与 `standard` 保持一致。
+- `CXX_EXTENSIONS OFF` 把 `-std=gnu++23` 收成 `-std=c++23`，与 Google 的「不用非标准扩展」一致；每个 target 都要设。configure 后检查 `compile_commands.json` 的最后一条 `-std=`，不能是 `gnu++NN`。
 - 程序 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_compile_features(<target> PUBLIC cxx_std_23)`：标准是 target 属性，不是全局开关。
 - `target_link_libraries(<target> PRIVATE|PUBLIC <lib>)`：实现依赖用 `PRIVATE`，接口依赖用 `PUBLIC`。
 - 不要 `file(GLOB ...)`；显式列源文件，新增文件时改 CMake，构建系统才知道。`CONFIGURE_DEPENDS` 依赖构建系统每次检查目录，跨生成器行为也不完全一致，不作为工程规则。
 - 不把 `main()` 编进库；程序只做装配和 I/O。
@@ -117,7 +135,7 @@ endif()
 - 一个构建树只用一个 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++ 时，在 CMake 工具链文件或项目自己的编译选项里写清，不要只写在某个人的脚本里；`environment.json` 只保留 `host`、`build_host`、`compiler`、`standard` 四个轴，不放 libc++。换机器后必须能复现同一组合。
 - 本插件默认使用目标平台默认标准库；只有项目明确要求 libc++ 时才切换，并保证整套工具一致。
 
 ## 警告与静态检查
@@ -150,7 +168,7 @@ FetchContent_MakeAvailable(googletest)
 
 | 模板 | 何时用 | 关键文件 |
 | --- | --- | --- |
-| `single` | 一个 `main.cpp`，辅助函数很少 | `CMakeLists.txt`, `src/main.cpp` |
+| `single` | 一个 `main.cc`，辅助函数很少 | `CMakeLists.txt`, `src/main.cc` |
 | `multi` | 多个源文件，一个程序 | `CMakeLists.txt`, `include/`, `src/` |
 | `static-library` | 库需要被测试或第二个程序链接 | 根 + `greeting/` 子目录 |
 | `shared-library` | 需要运行时加载/替换 | 同上，`SHARED` + RPATH |
@@ -160,7 +178,7 @@ FetchContent_MakeAvailable(googletest)
 ## 反模式
 
 - 全局 `include_directories(include)`：所有 target 共享，边界消失。
-- `file(GLOB sources "src/*.cpp")`：新增文件不触发重新配置。
+- `file(GLOB sources "src/*.cc")`：新增文件不触发重新配置。
 - 把库和 `main()` 编进同一个 target：测试无法只链接库。
 - 在源码目录生成 `compile_commands.json` 或可执行文件。
 - 同时设 `CMAKE_CXX_COMPILER` 和 `CXX` 环境变量，互相覆盖。

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

@@ -0,0 +1,49 @@
+# 编码与行尾
+
+默认组合是 UTF-8 无 BOM、LF。机器规则以仓库根 `.gitattributes` 与 `.editorconfig` 为准，本文件只记决定、MSVC 例外与检查方法。
+
+## 规则
+
+- 文本文件用 UTF-8，不带 BOM。JSON 按 RFC 8259；YAML 按 YAML 1.2.2；不要 GBK、UTF-16 或 Latin-1。
+- 所有文本文件用 LF，包括 `.sh`、Python、C++、Markdown、YAML、CMake 和配置文件。
+- `.sh` 必须 LF：内核会把 shebang 末尾的 CR 当作解释器路径的一部分，导致 `bad interpreter`。
+- `.bat` / `.cmd` 必须 CRLF：`cmd.exe` 对纯 LF 批处理不稳定。
+- 每个文本文件末尾一个换行；文件中间不混用 LF 和 CRLF。
+- 二进制文件（字体、图片）不转码，按 `binary` 处理。
+
+## MSVC 原生
+
+MSVC 默认按 BOM 判断源码编码。源码没有 BOM 时，它按当前用户代码页解释，除非显式传入 `/utf-8` 或 `/source-charset:utf-8`。因此 BOM 不是 MSVC 的硬要求。
+
+- 首选做法是加编译选项：在目标上写 `target_compile_options(<target> PRIVATE $<$<CXX_COMPILER_ID:MSVC>:/utf-8>)`，源码继续 UTF-8 无 BOM、LF。
+- 只有在无法改编译选项时，才把 MSVC 编译的 C/C++ 源文件保存为 UTF-8 BOM。BOM 只允许出现在这类源文件里。
+- `.sh`、`.bat`、`.cmd`、`.json`、`.yml`、`.gitattributes`、`.editorconfig` 和 CMake 文件不要加 BOM。
+- MSVC 接受 LF 源码；CRLF 不是必需项。只有 `.bat` / `.cmd` 固定 CRLF。
+- WSL 与 Linux 构建按默认组合，不要把源码转成 CRLF 来迁就 Windows。
+
+## 工具
+
+- `.gitattributes` 决定 Git 入库和检出；它覆盖贡献者自己的 `core.autocrlf`。
+- `.editorconfig` 决定编辑器保存；`charset` 与 `end_of_line` 必须和 `.gitattributes` 同一档。
+- `.clang-format` 写 `LineEnding: LF`，避免格式化把行尾改回 CRLF。
+
+## 检查
+
+在仓库根运行：
+
+```bash
+node "<skill-dir>/scripts/checking-encoding.mjs" --profile portable
+```
+
+- `portable`（默认）要求所有文本文件 UTF-8 无 BOM、LF、末尾换行。
+- `msvc` 只放宽 MSVC 编译的 C/C++ 源文件：允许 UTF-8 BOM 与 CRLF；Markdown、配置与脚本仍按 `portable` 检查。
+- 退出码：0 无问题，1 有问题，2 参数或 Git 错误。加 `--json` 输出机器可读结果。
+
+再跑 `git diff --check`，确认没有空白错误。不要用 `git add --renormalize` 把行尾改动混进功能改动；确需规范化时单独提交并说明。
+
+## 依据
+
+- MSVC `/utf-8`：<https://learn.microsoft.com/en-us/cpp/build/reference/utf-8-set-source-and-executable-character-sets-to-utf-8?view=msvc-170>
+- MSVC `/source-charset`：<https://learn.microsoft.com/en-us/cpp/build/reference/source-charset-set-source-character-set?view=msvc-170>
+- Unicode UTF-8 BOM FAQ：<https://www.unicode.org/faq/utf_bom.html>
+- Git `.gitattributes`：<https://git-scm.com/docs/gitattributes>

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

@@ -1,20 +1,22 @@
 # 环境组合
 
-环境是**声明**，不是探测结果。项目技能 `cpp-workflow-project` 的 `environment.json` 写清楚三个轴；构建规则、工具配置和检查都按这个声明执行。声明为空或组合非法时，先修声明，不要靠猜。
+环境是**声明**，不是探测结果。项目技能 `cpp-workflow-project` 的 `environment.json` 写清楚三个环境轴和一个语言标准；构建规则、工具配置和检查都按这个声明执行。声明为空或组合非法时，先修声明，不要靠猜。
 
-## 三个轴
+## 四个轴
 
 | 轴 | 取值 | 说明 |
 | --- | --- | --- |
 | `host` | `windows` / `linux` / `macos` | 编辑器与代理壳所在的系统 |
 | `build_host` | `native` / `wsl` | 编译在哪执行；`wsl` 只对 `host=windows` 合法 |
 | `compiler` | `clang` / `gcc` | 一次只配一个；不支持 MSVC、clang-cl，也不把 C 编译器单独作为一个轴 |
+| `standard` | `c++11` / `c++14` / `c++17` / `c++20` / `c++23` | 一个工程一个标准；新工程默认 `c++23`，旧声明缺字段时也按 `c++23` 处理 |
 
 ```json
 {
   "host": "windows",
   "build_host": "wsl",
-  "compiler": "clang"
+  "compiler": "clang",
+  "standard": "c++23"
 }
 ```
 
@@ -24,8 +26,6 @@
 | --- | --- | --- | --- | --- |
 | 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 | 合法 | 是 |
@@ -33,12 +33,13 @@
 
 非法组合：
 
-- `host` 不是三个值之一，或 `build_host` / `compiler` 不是两个值之一。
-- 三个轴任意为空、缺失、写成数组或同时写两个值。
+- `host`、`build_host`、`compiler` 不是各自允许的值，或 `standard` 不在 `c++11`–`c++23` 内。
+- 三个环境轴任意为空、缺失、写成数组或同时写两个值；`standard` 缺失或为空时按默认 `c++23` 处理并给出提示（视为声明升级，不覆盖已写出的 `c++11`–`c++20`）。
 - `host=linux` / `host=macos` + `build_host=wsl`。
+- `host=windows` + `build_host=native`：本版本不支持，静态校验直接返回失败。
 - `compiler=msvc`、`compiler=clang-cl`、`compiler=c`。
 
-`windows` + `native` 是合法声明，但本版本**没有** PowerShell 构建脚本。`--live` 会明确报告「缺的是 shell，不是编译器」；不要为了让它通过把 `build_host` 改成 `wsl`，也不要临时写一个脚本伪装成已支持。
+`windows` + `native` 不再作为「合法但不能构建」的声明保留。声明校验直接返回 `ok: false`，`issues` 只有一句「本版本不能在 Windows 原生壳里构建」；不要建议改 WSL，也不要临时写 PowerShell 脚本伪装成已支持。
 
 ## 工具角色
 
@@ -56,11 +57,12 @@
 
 ## 版本与能力
 
-- **C++20**：编译器必须支持 `-std=c++20`；CMake ≥ 3.20（C++20 标准属性从 3.12 起可用）。
-- **clang-format / clang-tidy**：≥ 16。`BreakAfterAttributes` 在 16 才支持，15 及以下没有该选项。
+- **标准**：新工程默认 C++23，可声明 `c++11`–`c++23`；编译器必须支持对应的 `-std=c++NN`。CMake ≥ 3.20；C++11/14 的 `cxx_std_*` 需要 CMake ≥ 3.8，但本工作流统一按 3.20 起步。`CXX_STANDARD_REQUIRED ON` 防止标准 decay；C++23 的库设施（如 `std::print`）以实际编译器/标准库为准。
+- **clang-format / clang-tidy**：≥ 16。这是本工作流的工具基线；低于该版本时检查器报告具体角色和版本。
 - **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>` 的标准库；版本过旧时先升级工具链，不要改检查器绕过。
+- **gcc 模式**：检查器不拿 GCC 的主版本去比 Clang 工具；`clang-format` / `clang-tidy` 仍要 ≥ 16，`clangd` 只要求可用。`g++` 必须是真的 GCC，不能是 Apple clang 的别名。GCC 需要自带 C++23 `<print>` / `std::expected` 的标准库；版本过旧时先升级工具链，或把项目标准降到实际可用的档位，不要改检查器绕过。
 - **Apple Clang**：`/usr/bin/clang++` 通常是 Apple Clang；clangd 需能经 `xcrun` 找到 SDK。不要混用 Homebrew LLVM 与 Xcode 资源目录，也不要把 Homebrew 路径写死。
+- **调试器**：VSCode 的 `CMake: Debug` 由 CMake Tools 调 C/C++ 扩展的 `cppdbg`；clang 模式要 `lldb`，gcc 模式要 `gdb`。调试器不在 `--live` 的编译器角色核对里，也不写进 `environment.json`；缺它时是调试启动失败，不是构建声明失败。
 
 ## 构建目录
 
@@ -76,7 +78,7 @@
 
 `<skill-dir>/scripts/checking-environment.mjs` 做两件事：
 
-1. **静态**（默认）：读 `environment.json`，检查三个轴和组合。轴为空或组合非法时以退出码 2 结束，不查找任何可执行文件。
+1. **静态**（默认）：读 `environment.json`，检查三个环境轴、`standard` 和组合。轴为空或组合非法时以退出码 2 结束，不查找任何可执行文件。
 2. **活动**（`--live`）：先做声明校验，再核对当前进程是否在声明的 build host 上，然后查 PATH、角色和版本。声明本身不合法时仍以退出码 2 结束；声明合法但活动核对失败时以退出码 3 结束。
 
 ```bash
@@ -89,7 +91,7 @@ node "<skill-dir>/scripts/checking-environment.mjs" --project . --live
 约束：
 
 - 只读：不安装、不下载、不改 PATH、不写项目文件。
-- `--live` 在 `host=windows` + `build_host=native` 下直接报告「缺 POSIX 壳；本版没有 PowerShell 构建脚本」，不继续找编译器。
+- `--live` 在 `host=windows` + `build_host=native` 下不会继续：声明校验已经失败，错误是「本版本不能在 Windows 原生壳里构建」。
 - WSL 模式要求当前进程在 WSL 内（`WSL_DISTRO_NAME` / `WSL_INTEROP` 或 `/proc/version` 含 Microsoft）；只在 Linux 上但不在 WSL 时失败。
 - macOS 上声明 `compiler=gcc` 时，`g++ --version` 若显示 Apple clang，按「不是真正的 GCC」失败。
 - 没有 `--live` 时不做任何 PATH 探测，CI 和 Windows 开发机都能做声明校验。
@@ -102,3 +104,5 @@ node "<skill-dir>/scripts/checking-environment.mjs" --project . --live
 | 2 | 声明缺失、轴为空、组合非法 |
 | 3 | 活动校验失败：不在声明的 build host、角色缺失、版本不符 |
 | 1 | 脚本自身错误：参数错误或内部异常 |
+
+各标准对应的编译器、库设施和工具档位见 [standards/README.md](standards/README.md)。

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

@@ -15,25 +15,25 @@
 - 链接：把多个目标文件和库合并，解析符号引用。`undefined reference` 在这一步失败。
 - 加载：程序启动时由动态加载器找到共享库；`error while loading shared libraries` 在这一步失败。
 
-`g++ -c file.cpp` 只编译不链接；`g++ file.o -o app` 只链接。`-E` 只看预处理，`-S` 只看汇编。
+`g++ -c file.cc` 只编译不链接；`g++ file.o -o app` 只链接。`-E` 只看预处理，`-S` 只看汇编。
 
 ## 头文件、声明与定义
 
 - `#include` 是文本替换，不是模块导入；头文件只放声明、`inline` 定义、模板和 `constexpr` 定义。
-- 普通函数的定义放 `.cpp`；在头文件里写非 `inline` 函数定义，多个翻译单元包含时会重复定义。
-- 类定义放头文件；成员函数在类外定义时写 `ClassName::`，定义放 `.cpp`。
+- 普通函数的定义放 `.cc`；在头文件里写非 `inline` 函数定义，多个翻译单元包含时会重复定义。
+- 类定义放头文件；成员函数在类外定义时写 `ClassName::`，定义放 `.cc`。
 - 只用到声明时不要包含完整定义；前置声明可以减少编译依赖，但不能替代需要完整类型的场景（继承、成员对象、按值返回）。
-- 每个头文件自包含：单独编译一个只包含该头文件的 `.cpp` 应通过。用 `#pragma once` 防止重复包含。
+- 每个头文件自包含：单独编译一个只包含该头文件的 `.cc` 应通过。用路径式 `#define` 守卫防止重复包含，不用 `#pragma once`。
 
 ## `undefined reference` 分诊
 
 | 现象 | 常见原因 | 修法 |
 | --- | --- | --- |
-| 链接器说某个成员函数未定义 | 声明了但没写定义，或 `.cpp` 没加入 target | 补定义，或把源文件加入 `target_sources` |
+| 链接器说某个成员函数未定义 | 声明了但没写定义，或 `.cc` 没加入 target | 补定义，或把源文件加入 `target_sources` |
 | 只有某个平台失败 | 条件编译把定义排除了 | 检查宏和平台分支，保证每个平台都有定义 |
 | 第三方库符号缺失 | 没链接库，或库顺序不对 | `target_link_libraries` 加库；CMake 会处理顺序 |
 | C++ 符号被当成 C 符号 | 头文件缺少 `extern \"C\"` | C 接口头加 `extern \"C\"`，C++ 调用方也可见 |
-| 模板成员未定义 | 模板定义在 `.cpp`，实例化点看不到 | 模板定义移到头文件，或显式实例化 |
+| 模板成员未定义 | 模板定义在 `.cc`，实例化点看不到 | 模板定义移到头文件，或显式实例化 |
 | 静态库中的目标文件没被拉入 | 链接器只取被引用符号所在的目标文件 | 确认符号确实被引用，或改用对象库/共享库 |
 
 先看链接器报的完整符号名和来源文件，不要只看第一行。

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

@@ -0,0 +1,165 @@
+# 语言标准档案
+
+本工作流默认 **C++23**，但一个工程只选一个 `standard`，不为同一份源码承诺“同时兼容 C++11–C++23”。标准是项目级事实，写在 `.agents/skills/cpp-workflow-project/environment.json`。
+
+每个标准单独一个目录：`c++11/`、`c++14/`、`c++17/`、`c++20/`、`c++23/`。目录里放这一档自己的编译器下限、语言/库设施、CMake 片段和工具映射；模板仍然只有一套公共骨架，靠 `__cplusplus` 条件选择实现，不复制五份模板。
+
+Google C++ Style Guide 上游仍写 “target C++20”，本工作流默认 C++23 是一处明确偏离；Google 的排版、命名、头文件和异常之外的规则不变。异常政策仍按 [exceptions.md](../../../developing-cpp/references/exceptions.md)。
+
+## 选择标准
+
+| 标准 | 目录 | 一句话 |
+| --- | --- | --- |
+| C++11 | [c++11/README.md](c++11/README.md) | 老工具链、老库仍要维护时的最低档 |
+| C++14 | [c++14/README.md](c++14/README.md) | 需要 `make_unique`、泛型 lambda，但还不想上 C++17 |
+| C++17 | [c++17/README.md](c++17/README.md) | 需要 `string_view`、`optional`、`if constexpr` 的稳定基线 |
+| C++20 | [c++20/README.md](c++20/README.md) | 需要 concepts、ranges、`std::format` 的现代基线 |
+| C++23 | [c++23/README.md](c++23/README.md) | 本工作流默认；需要 `print`、`expected` 等设施时选它 |
+
+新工程写 `c++23`；已有工程按现有 `CMakeLists.txt` 和编译器能力选，不为了“统一”擅自升降。降档前先读对应目录的“不能假设”和“降档要改什么”。
+
+## 三个规划粒度
+
+| 粒度 | 先看 | 产出 |
+| --- | --- | --- |
+| 项目 | 本页选择表、编译器/库门槛 | `environment.json` 的 `standard`，以及“为什么选这档” |
+| target | 该档的 `cmake-snippet.cmake` | `cxx_std_*`、`CXX_STANDARD`、`CXX_STANDARD_REQUIRED`、`CXX_EXTENSIONS` |
+| 代码/工具 | 该档 README 的“能用/不能假设/降档” | 设施替换、`.clang-format` 档位、`.clangd` 不写 `-std` |
+| 验证 | 本页验证矩阵、`scripts/checking-standard-matrix.sh` | configure/build/CTest 和 `compile_commands.json` 的精确 `-std` |
+
+每个标准目录都按这四层写；不要只在项目层改 `standard`，却在 target 层留着 C++23 的 `cxx_std_23`。
+
+## 共用矩阵
+
+| `standard` | CMake meta-feature | `CXX_STANDARD` | `__cplusplus` | clang-format 21/22 | 模板实用下限（含标准库设施） |
+| --- | --- | --- | --- | --- | --- |
+| `c++11` | `cxx_std_11` | 11 | `201103L` | `c++11` | GCC 4.8 / Clang 3.4 |
+| `c++14` | `cxx_std_14` | 14 | `201402L` | `c++14` | GCC 5 / Clang 3.4 |
+| `c++17` | `cxx_std_17` | 17 | `201703L` | `c++17` | GCC 7 / Clang 5 |
+| `c++20` | `cxx_std_20` | 20 | `202002L` | `c++20` | GCC 13 / Clang 16（`std::format`） |
+| `c++23` | `cxx_std_23` | 23 | `202302L` | `Latest` | GCC 13 / Clang 17（模板只用 `std::format`） |
+
+“语言核心最低编译器”只保证语法和核心库；标准库设施要单独看：
+
+| 设施 | 标准 | 额外门槛 |
+| --- | --- | --- |
+| `std::string_view`、`std::optional`、`std::variant`、`if constexpr` | C++17 | 随语言核心 |
+| `std::format` | C++20 | libstdc++ 13+；libc++ 14+（特性宏到 19 才稳定） |
+| `std::print`、`std::expected`、`std::stacktrace` | C++23 | `std::print`：libstdc++ 14+、libc++ 19+；`std::expected` 随各库 C++23 实现；`std::stacktrace` 还要链接对应库 |
+
+Clang/GCC 的 “Partial” 状态意味着 C++23 不是全量实现。用到具体设施前，先查：
+
+- [GCC C++ status](https://gcc.gnu.org/projects/cxx-status.html)
+- [Clang C++ status](https://clang.llvm.org/cxx_status.html)
+- [cppreference C++23 compiler support](https://en.cppreference.com/w/cpp/compiler_support/23)
+
+## 共用规则
+
+### CMake
+
+每个 target 同时写 meta-feature 和精确属性；片段见各标准目录的 `cmake-snippet.cmake`，把 target 名换成实际 target：
+
+```cmake
+target_compile_features(app PRIVATE cxx_std_23)
+set_target_properties(app PROPERTIES
+  CXX_STANDARD 23
+  CXX_STANDARD_REQUIRED ON
+  CXX_EXTENSIONS OFF
+)
+```
+
+- `cxx_std_23` 是“至少”，会向依赖它的 target 传播。
+- `CXX_STANDARD` 是请求值；`CXX_STANDARD_REQUIRED ON` 防止编译器不支持时静默 decay。
+- `CXX_EXTENSIONS OFF` 把 `-std=gnu++23` 收成 `-std=c++23`。
+- configure 后读 `compile_commands.json` 的最后一个 `-std=`；必须是 `-std=c++NN`，不能是 `gnu++NN`。
+- CMake 最低 3.20（模板统一要求）；只单独使用低档片段时，C++11/14 的 `cxx_std_*` meta-feature 最低 3.8，C++20 为 3.12。C++23 的 `CXX_STANDARD 23` 自 3.20 才有。
+
+### clang-format
+
+clang-format 21/22 的 `Standard` 只到 `c++20`。映射：
+
+| 声明 | 配置 |
+| --- | --- |
+| `c++11`–`c++20` | 对应 `Standard: c++NN` |
+| `c++23` | `Standard: Latest`（21/22 没有 `c++23`） |
+| `c++26`（未来） | 工具支持时写 `c++26`，否则 `Latest` |
+
+不要为了“看起来精确”写 `c++23`；clang-format 21 会报 `unknown enumerated scalar` 并退出 1。
+
+### clangd
+
+`.clangd` **不写 `-std`**。clangd 从 `compile_commands.json` 读标准；写死 `-std=c++20` 会把 C++23 工程降级，表现为 `<print>` 不存在、`if consteval` 解析失败。
+
+只保留：
+
+```yaml
+CompileFlags:
+  CompilationDatabase: build/clang
+```
+
+切换编译器时改目录；没有数据库时先回到定构建生成。
+
+### clang-tidy
+
+`.clang-tidy` 不写标准，标准来自编译数据库。检查项保持 Google 基线：
+
+```yaml
+Checks: '-*, google-*, readability-identifier-naming'
+WarningsAsErrors: '*'
+FormatStyle: file
+```
+
+低标准工程不要为了通过检查去打开 `cppcoreguidelines-*` 整包；那会把 C++ Core Guidelines 的现代写法带进 C++11 代码。
+
+### 标准库
+
+默认用系统默认标准库。需要 libc++ 时，在 CMake 工具链文件或 target 选项里显式写：
+
+```cmake
+target_compile_options(app PRIVATE -stdlib=libc++)
+target_link_options(app PRIVATE -stdlib=libc++)
+```
+
+不要只写进某个人的 `.clangd` 或 shell 脚本；换机器后不可复现。
+
+## 降档时改什么
+
+默认模板按 `__cplusplus` 条件使用 `std::format`；选低标准仍不是只改一个数字：
+
+| 从默认 C++23 降到 | 必须处理 |
+| --- | --- |
+| `c++20` | `std::print` → `std::format` + `std::cout`；`std::expected` → `std::optional`/结果类型 |
+| `c++17` | 再去掉 `std::format`，用 `std::ostringstream`；去掉 `std::span`、`std::bit_cast` |
+| `c++14` | 去掉 `std::string_view`、`[[nodiscard]]`、结构化绑定、`if constexpr`、`std::optional` |
+| `c++11` | 再去掉通用 lambda、`std::make_unique`、`std::index_sequence`、`constexpr` 放宽用法 |
+
+每个标准目录里的“不能假设”和“降档要改什么”是该档的检查清单；模板只保证自身能构建，不替项目代码做兼容层。
+
+## 验证矩阵
+
+| 标准 | configure | build | run | compile_commands `-std` | clang-format | clangd |
+| --- | --- | --- | --- | --- | --- | --- |
+| `c++11` | 必测 | 必测 | 必测 | `c++11` | `c++11` | 读 DB |
+| `c++14` | 必测 | 必测 | 必测 | `c++14` | `c++14` | 读 DB |
+| `c++17` | 必测 | 必测 | 必测 | `c++17` | `c++17` | 读 DB |
+| `c++20` | 必测 | 必测 | 必测 | `c++20` | `c++20` | 读 DB |
+| `c++23` | 必测 | 必测 | 必测 | `c++23` | `Latest` | 读 DB |
+
+本仓库在 WSL（clang 21.1.8、CMake 4.2.3、Ninja 1.13.2）上跑过四套模板 × 五档共 20 个构建：single、multi、static-library、shared-library 全部 configure/build/CTest 通过，`compile_commands.json` 都得到精确的 `-std=c++11/14/17/20/23`。模板用 `__cplusplus` 条件选择 `std::format` 或字符串拼接，默认仍交付 C++23。可复现脚本：[checking-standard-matrix.sh](../../../../scripts/checking-standard-matrix.sh)。
+
+## 新增标准
+
+增加 C++26 或更高标准时，不复制模板，按这个顺序做：
+
+1. 新建 `standards/c++26/`，写 `README.md`，复制对应档的 `cmake-snippet.cmake` 并改数字。
+2. 更新本页矩阵和 `checking-environment.mjs` 的 `STANDARDS`。
+3. 确认 CMake 的 `CXX_STANDARD 26`、clang-format 的 `Standard` 能力、编译器/标准库门槛。
+4. 在四套模板 × 新档上跑 configure/build/CTest，并在 `compile_commands.json` 核对 `-std=c++26`。
+5. 只在新档稳定后改默认；默认变更属于发布说明里要写清的破坏性变化。
+
+## 相关文件
+
+- [environment.md](../environment.md)：四轴声明与校验。
+- [cmake.md](../cmake.md)：CMake 形状与排版。
+- [static-analysis.md](../static-analysis.md)：clang-format / clang-tidy / clangd 分工。
+- [01-build.md](../../steps/01-build.md)：定构建步骤。

package/skills/building-cpp/references/standards/c++11/README.md

@@ -0,0 +1,50 @@
+# C++11 标准档案
+
+[返回标准索引](../README.md)
+
+| 项 | 值 |
+| --- | --- |
+| `standard` | `c++11` |
+| CMake meta-feature | `cxx_std_11` |
+| `CXX_STANDARD` | `11` |
+| `__cplusplus` | `201103L` |
+| clang-format 21/22 | `Standard: c++11` |
+| 模板实用下限 | GCC 4.8 / Clang 3.4 |
+
+## 最重要的三件事
+
+1. 代码只用 C++11 子集：没有 `std::make_unique`、通用 lambda、`std::string_view`、`std::optional`、`if constexpr`。
+2. CMake 同时写 `cxx_std_11` 和 `CXX_STANDARD 11`，并开 `CXX_STANDARD_REQUIRED ON`；只写 `cxx_std_11` 可能被更高默认标准满足。
+3. 验证时读 `compile_commands.json`，确认实际是 `-std=c++11`，不是 `gnu++11` 或更高的 `-std`。
+
+## 本档能用
+
+- `auto`、范围 `for`、lambda、右值引用与移动语义。
+- `std::unique_ptr`、`std::shared_ptr`、`std::thread`、`std::chrono`。
+- `enum class`、`override` / `final`、变参模板、`constexpr` 的受限用法。
+- `std::array`、`std::unordered_map` / `unordered_set`。
+
+## 本档不能假设
+
+- 没有 `std::make_unique`、泛型 lambda、变量模板、返回类型推导。
+- 没有 `std::string_view`、`std::optional`、`std::variant`、`if constexpr`、结构化绑定。
+- 没有 `[[nodiscard]]`、`std::filesystem`、`std::format`、`std::print`。
+- 不要用 C++14 的放宽 `constexpr` 写循环或多语句函数。
+
+## CMake
+
+把 [cmake-snippet.cmake](cmake-snippet.cmake) 的 target 名换成实际 target。新建工程仍建议 CMake ≥ 3.20；低版本工具链只影响 `CXX_STANDARD` 的可用性，不影响本工作流的目录约定。
+
+## 工具
+
+- `.clang-format`：`Standard: c++11`。
+- `.clangd`：不写 `-std`，从 `compile_commands.json` 读。
+- `.clang-tidy`：仍用 Google 基线；不要打开 `cppcoreguidelines-*` 整包。
+
+## 降档/升级
+
+这是最低档，没有“再降”的路径。从 C++14 降到这里时，先去掉 `std::make_unique`、泛型 lambda、返回类型推导和变量模板；`std::unique_ptr<T>(new T(...))` 只作为过渡，不要在新代码里扩散。
+
+## 验证
+
+configure、build、run 必测；`compile_commands.json` 的最后一个 `-std=` 必须是 `-std=c++11`，不能是 `gnu++11`。模板的 `__cplusplus` 分支在 C++11 下应走字符串拼接实现。

package/skills/building-cpp/references/standards/c++11/cmake-snippet.cmake

@@ -0,0 +1,7 @@
+# c++11：把 target 名换成实际 target；与 environment.json 的 standard 一致。
+target_compile_features(app PRIVATE cxx_std_11)
+set_target_properties(app PROPERTIES
+  CXX_STANDARD 11
+  CXX_STANDARD_REQUIRED ON
+  CXX_EXTENSIONS OFF
+)

package/skills/building-cpp/references/standards/c++14/README.md

@@ -0,0 +1,48 @@
+# C++14 标准档案
+
+[返回标准索引](../README.md)
+
+| 项 | 值 |
+| --- | --- |
+| `standard` | `c++14` |
+| CMake meta-feature | `cxx_std_14` |
+| `CXX_STANDARD` | `14` |
+| `__cplusplus` | `201402L` |
+| clang-format 21/22 | `Standard: c++14` |
+| 模板实用下限 | GCC 5 / Clang 3.4 |
+
+## 最重要的三件事
+
+1. C++14 只多出 `std::make_unique`、泛型 lambda、放宽的 `constexpr` 等；不要顺手用 C++17 的 `string_view`/`optional`。
+2. `std::make_unique` 是这一档最常用的替换点，但不要把 C++11 的 `std::unique_ptr(new T)` 直接当成跨档写法。
+3. 同样用 `CXX_STANDARD 14` + `REQUIRED ON` 锁定模式，并检查 `compile_commands.json` 是 `-std=c++14`。
+
+## 本档能用
+
+- C++11 的全部内容。
+- `std::make_unique`、泛型 lambda、变量模板、返回类型推导。
+- 二进制字面量、数字分隔符、放宽的 `constexpr`、`std::integer_sequence`。
+
+## 本档不能假设
+
+- 没有 `std::string_view`、`std::optional`、`std::variant`、`if constexpr`、结构化绑定。
+- 没有 `[[nodiscard]]`、`std::filesystem`、`std::format`、`std::print`。
+- 不要把结构化绑定或 `if constexpr` 写进 C++14 代码再靠编译器扩展通过。
+
+## CMake
+
+把 [cmake-snippet.cmake](cmake-snippet.cmake) 的 target 名换成实际 target。
+
+## 工具
+
+- `.clang-format`：`Standard: c++14`。
+- `.clangd`：不写 `-std`，从 `compile_commands.json` 读。
+- `.clang-tidy`：仍用 Google 基线；命名规则不要引入 C++17 属性。
+
+## 降档/升级
+
+从 C++17 降到这里时，把 `string_view` 改成 `const std::string&`，把 `optional` 改成 `bool` + 输出参数或项目结果类型，把 `if constexpr` 改成标签分派或重载。升级到 C++17 后也不要立刻把公共接口全改成 `string_view`，先看调用方生命周期。
+
+## 验证
+
+configure、build、run 必测；`compile_commands.json` 的最后一个 `-std=` 必须是 `-std=c++14`。模板在 C++14 下应走字符串拼接实现。

package/skills/building-cpp/references/standards/c++14/cmake-snippet.cmake

@@ -0,0 +1,7 @@
+# c++14：把 target 名换成实际 target；与 environment.json 的 standard 一致。
+target_compile_features(app PRIVATE cxx_std_14)
+set_target_properties(app PROPERTIES
+  CXX_STANDARD 14
+  CXX_STANDARD_REQUIRED ON
+  CXX_EXTENSIONS OFF
+)

package/skills/building-cpp/references/standards/c++17/README.md

@@ -0,0 +1,49 @@
+# C++17 标准档案
+
+[返回标准索引](../README.md)
+
+| 项 | 值 |
+| --- | --- |
+| `standard` | `c++17` |
+| CMake meta-feature | `cxx_std_17` |
+| `CXX_STANDARD` | `17` |
+| `__cplusplus` | `201703L` |
+| clang-format 21/22 | `Standard: c++17` |
+| 模板实用下限 | GCC 7 / Clang 5（语言核心） |
+
+## 最重要的三件事
+
+1. `std::string_view`/`std::optional`/`std::variant`/`if constexpr` 是这一档的主力；它们不能出现在 C++11/14 档案里。
+2. 还没有 `std::format`；字符串拼接/`ostringstream` 仍是这一档的默认写法。
+3. `std::filesystem` 在旧 GCC 上要额外链接 `stdc++fs`，先查工具链再写进 CMake。
+
+## 本档能用
+
+- C++14 的全部内容。
+- `std::string_view`、`std::optional`、`std::variant`、`std::any`。
+- `if constexpr`、结构化绑定、`[[nodiscard]]`、内联变量、嵌套命名空间。
+- `std::filesystem`、并行算法（库实现和链接方式另看）。
+
+## 本档不能假设
+
+- 没有 concepts、ranges、`std::format`、`std::span`、`std::bit_cast`。
+- 没有 `std::print`、`std::expected`、`std::stacktrace`。
+- `std::filesystem` 在 GCC 8 需要额外链接 `stdc++fs`，GCC 9 起才稳定；不要把“语言核心达标”当成文件系统库也达标。
+
+## CMake
+
+把 [cmake-snippet.cmake](cmake-snippet.cmake) 的 target 名换成实际 target。用到 `std::filesystem` 且工具链较老时，在 target 上补 `stdc++fs`，不要全局加链接选项。
+
+## 工具
+
+- `.clang-format`：`Standard: c++17`。
+- `.clangd`：不写 `-std`，从 `compile_commands.json` 读。
+- `.clang-tidy`：Google 基线；`[[nodiscard]]` 可以开始用于公共查询。
+
+## 降档/升级
+
+从 C++20 降到这里时，把 concepts 改成 `enable_if`/重载，把 ranges 改成迭代器算法，把 `std::format` 改成 `std::ostringstream`。升级到 C++20 后先确认 `std::format` 的库门槛（libstdc++ 13+ / libc++ 14+），不要只看编译器版本。
+
+## 验证
+
+configure、build、run 必测；`compile_commands.json` 的最后一个 `-std=` 必须是 `-std=c++17`。模板在 C++17 下仍走字符串拼接实现。

package/skills/building-cpp/references/standards/c++17/cmake-snippet.cmake

@@ -0,0 +1,7 @@
+# c++17：把 target 名换成实际 target；与 environment.json 的 standard 一致。
+target_compile_features(app PRIVATE cxx_std_17)
+set_target_properties(app PROPERTIES
+  CXX_STANDARD 17
+  CXX_STANDARD_REQUIRED ON
+  CXX_EXTENSIONS OFF
+)