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

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

@@ -0,0 +1,49 @@
+# C++20 标准档案
+
+[返回标准索引](../README.md)
+
+| 项 | 值 |
+| --- | --- |
+| `standard` | `c++20` |
+| CMake meta-feature | `cxx_std_20` |
+| `CXX_STANDARD` | `20` |
+| `__cplusplus` | `202002L` |
+| clang-format 21/22 | `Standard: c++20` |
+| 模板实用下限 | GCC 13 / Clang 16（`std::format`） |
+
+## 最重要的三件事
+
+1. `std::format` 是这一档的库门槛：libstdc++ 13+，libc++ 14+（特性宏到 19 才稳定），不是有 `-std=c++20` 就自动可用。
+2. concepts/ranges/`std::span`/`std::bit_cast` 可以用；`std::print`、`std::expected`、`if consteval` 仍不能假设。
+3. 模板在 `__cplusplus >= 202002L` 时切到 `std::format`；降回 C++17 时必须把它换回 `std::ostringstream`。
+
+## 本档能用
+
+- C++17 的全部内容。
+- concepts、requires、ranges、`std::span`、`std::bit_cast`、`std::source_location`。
+- `std::format`、协程、`std::jthread`、三路比较。
+- 模块语法（工具链支持不完整，模板不使用）。
+
+## 本档不能假设
+
+- 没有 `std::print`、`std::expected`、`std::stacktrace`、`if consteval`、显式对象参数。
+- `std::format` 不只看语言核心：libstdc++ 13+；libc++ 14+ 实现完成，但特性宏到 19 才稳定。
+- 模块、协程的构建支持因编译器/构建系统而异；模板不依赖它们。
+
+## CMake
+
+把 [cmake-snippet.cmake](cmake-snippet.cmake) 的 target 名换成实际 target。模板从这一档开始会在 `__cplusplus >= 202002L` 时使用 `std::format`，此前用字符串拼接。
+
+## 工具
+
+- `.clang-format`：`Standard: c++20`。
+- `.clangd`：不写 `-std`，从 `compile_commands.json` 读。
+- `.clang-tidy`：Google 基线；不要为了 concepts 打开一整族非 Google 检查。
+
+## 降档/升级
+
+从 C++23 降到这里时，把 `std::print` 改成 `std::format` + `std::cout`，把 `std::expected` 改成 `std::optional` 或项目结果类型，去掉 `if consteval`。升级到 C++23 后仍要逐项确认库实现，不要因为 `-std=c++23` 通过就假定 `print`/`stacktrace` 可用。
+
+## 验证
+
+configure、build、run 必测；`compile_commands.json` 的最后一个 `-std=` 必须是 `-std=c++20`。模板在 C++20 下应走 `std::format` 分支。

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

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

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

@@ -0,0 +1,50 @@
+# C++23 标准档案
+
+[返回标准索引](../README.md)
+
+| 项 | 值 |
+| --- | --- |
+| `standard` | `c++23` |
+| CMake meta-feature | `cxx_std_23` |
+| `CXX_STANDARD` | `23` |
+| `__cplusplus` | `202302L` |
+| clang-format 21/22 | `Standard: Latest` |
+| 模板实用下限 | GCC 13 / Clang 17（模板只用 `std::format`） |
+
+## 最重要的三件事
+
+1. C++23 在 GCC/Clang 上仍是 Partial；`std::print` 要 libstdc++ 14+/libc++ 19+，`std::stacktrace` 还要链接库。
+2. clang-format 21/22 不认识 `c++23`，配置写 `Standard: Latest`；`.clangd` 不写 `-std`，否则会把编译数据库降回 C++20。
+3. 模板默认 23，但模板只强依赖 `std::format`；不要因为默认 23 就在公共头里用 `std::expected`/`std::print`，先确认所有 target 和库门槛。
+
+## 本档能用
+
+- C++20 的全部内容。
+- `std::print` / `std::println`、`std::expected`、`std::stacktrace`。
+- `if consteval`、显式对象参数（deducing this）、`std::mdspan`、`std::flat_map`。
+- ranges 的 C++23 增补（工具链实现为准）。
+
+## 本档不能假设
+
+- C++23 在 GCC/Clang 上仍是 Partial：具体设施要查编译器状态页，不能只看 `-std=c++23`。
+- `std::print` 的库门槛是 libstdc++ 14+ / libc++ 19+；`std::stacktrace` 还要链接对应库，链接失败不是语法错误。
+- `std::expected` 的 monadic 接口、`std::flat_map` 等设施在旧标准库上可能缺失。
+- 模板只用 `std::format`，不会因为默认 C++23 就强依赖 `print`/`stacktrace`。
+
+## CMake
+
+把 [cmake-snippet.cmake](cmake-snippet.cmake) 的 target 名换成实际 target。默认模板的 `cxx_std_23` 和 `CXX_STANDARD 23` 必须与 `environment.json` 的 `standard` 一致。
+
+## 工具
+
+- `.clang-format`：`Standard: Latest`（21/22 不接受 `c++23`；`Latest` 按工具支持的最高标准解析）。
+- `.clangd`：不写 `-std`，从 `compile_commands.json` 读；写死 `-std=c++20` 会让 `<print>` 和 `if consteval` 解析失败。
+- `.clang-tidy`：Google 基线；不要因为 C++23 就打开 `cppcoreguidelines-*` 整包。
+
+## 降档/升级
+
+从 C++23 降到 C++20 见 [C++20 档案](../c++20/README.md)。升级到 C++26 前先确认 CMake 3.25+、编译器/标准库支持、clang-format 的 `c++26` 枚举；新增目录流程见 [标准索引](../README.md#新增标准)。
+
+## 验证
+
+configure、build、run 必测；`compile_commands.json` 的最后一个 `-std=` 必须是 `-std=c++23`。模板在 C++23 下走 `std::format` 分支；若使用 `print`/`stacktrace`，另做链接测试。

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

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

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

@@ -1,18 +1,18 @@
 # 静态分析与语言服务
 
-三件工具各管一段：`clang-format` 排版、`clang-tidy` 诊断、`clangd` 提供补全/跳转/诊断。它们都读同一份编译数据库，但职责不重叠。
+三件语言工具各管一段：`clang-format` 排版、`clang-tidy` 诊断、`clangd` 提供补全/跳转/诊断。它们都读同一份编译数据库，但职责不重叠。编辑器侧只保留 CMake Tools 作为配置、构建、运行和调试入口；C/C++ 扩展只做 `CMake: Debug` 的调试后端，不参与语言服务。
 
 ## clang-format
 
 ```bash
-clang-format --dry-run --Werror src/*.cpp include/*.h tests/*.cpp
+clang-format --dry-run --Werror src/*.cc include/*.h tests/*.cc
 ```
 
 - 检查用 `--dry-run --Werror`；需要自动修复时单独跑 `clang-format -i`，不要在构建脚本里悄悄改源码。
 - 工程必须有根 `.clang-format`；缺失时先复制配置，不要回退到内置风格，回退会掩盖配置缺失。
 - 只扫描项目源码：`src/`、`include/`、`apps/`、`tests/` 等实际存在的目录；不扫描 `build/`、第三方、生成文件。
 - 配置文件在工程根 `.clang-format`；不要依赖用户主目录或编辑器内置配置。
-- `ColumnLimit: 100`、`Standard: c++20`、`BasedOnStyle: Google`；`IncludeCategories` 维持包含顺序。
+- `BasedOnStyle: Google`、`Standard: Latest`；clang-format 21/22 不接受 `c++23`，`Latest` 按工具支持的最高标准解析。列宽 80、2 空格、包含顺序都取 Google 预设，不另写 `ColumnLimit` 或 `IncludeCategories`。
 - 格式化失败就是失败，不要用 `// clang-format off` 绕过；确需关闭时只包住无法排版的宏或表格，并写一句理由。
 
 ## clang-tidy
@@ -21,7 +21,7 @@ clang-format --dry-run --Werror src/*.cpp include/*.h tests/*.cpp
 clang-tidy -p build/clang \
   --header-filter="^$(pwd -P)/(include|src|apps|tests)/" \
   --warnings-as-errors='*' \
-  src/*.cpp apps/*.cpp tests/*.cpp
+  src/*.cc apps/*.cc tests/*.cc
 ```
 
 - `-p` 指向当前编译器的构建目录，读取 `compile_commands.json`。
@@ -30,7 +30,7 @@ clang-tidy -p build/clang \
 - 系统头默认被排除，不要加 `--system-headers`。
 - 只扫描项目源文件；不要把 `build/` 或第三方源码传给 clang-tidy。
 - `--warnings-as-errors='*'` 把警告当失败；修代码，不要新增 `NOLINT`。确需抑制时写 `// NOLINT(检查名): 理由`，理由必须具体。
-- 配置在工程根 `.clang-tidy`；关闭项逐条写理由，不整族关闭。`cppcoreguidelines-pro-bounds-constant-array-index` 不能整族关闭；优先把下标换成 `at()` 或带边界检查的辅助函数，并补负向越界测试。
+- 配置在工程根 `.clang-tidy`；默认集合是 `google-*` 加 `readability-identifier-naming`。关闭某条时逐条写理由，不整族关闭；命名规则只配项目确实统一的项，不设 `FunctionCase`。
 - 没有编译数据库时先回到 `building-cpp` 的定构建生成；不要用 `--` 手工拼编译参数绕过。
 - `clang-tidy` 的诊断可能指向头文件；修头文件里的声明或实现，不要只改调用点。
 
@@ -41,17 +41,13 @@ clang-tidy -p build/clang \
 ```yaml
 CompileFlags:
   CompilationDatabase: build/clang
-  Add:
-    - -std=c++20
-    - -Wall
-    - -Wextra
 Diagnostics:
   Suppress:
     - pp_file_not_found
 ```
 
 - `CompilationDatabase` 指向当前编译器目录；GCC 模式改 `build/gcc`。
-- `Add` 只补编译数据库里没有的公共选项；不要重复 `-I` 项目 include（数据库里已有）。
+- 不要在 `.clangd` 写 `-std`：它会覆盖 `compile_commands.json`，把 C++23 工程降成旧标准。标准只由构建声明和编译数据库决定。
 - 静态检查规则只在 `.clang-tidy` 里维护；clangd 读取同一份配置，不要在这里复制检查列表。
 - `Suppress` 只放确实无法避免的解析噪声（如 `pp_file_not_found`），并写理由。
 
@@ -82,7 +78,11 @@ Diagnostics:
 
 ```json
 {
-  "recommendations": ["llvm-vs-code-extensions.vscode-clangd", "ms-vscode.cmake-tools"]
+  "recommendations": [
+    "llvm-vs-code-extensions.vscode-clangd",
+    "ms-vscode.cmake-tools",
+    "ms-vscode.cpptools"
+  ]
 }
 ```
 
@@ -96,13 +96,25 @@ Diagnostics:
     "--background-index"
   ],
   "cmake.buildDirectory": "${workspaceFolder}/build/clang",
-  "cmake.generator": "Ninja"
+  "cmake.generator": "Ninja",
+  "cmake.buildBeforeRun": true,
+  "cmake.exportCompileCommandsFile": true,
+  "cmake.debugConfig": {
+    "type": "cppdbg",
+    "request": "launch",
+    "MIMode": "lldb",
+    "miDebuggerPath": "/usr/bin/lldb",
+    "stopAtEntry": false
+  },
+  "C_Cpp.intelliSenseEngine": "disabled"
 }
 ```
 
+- 配置、构建、运行和调试只从 CMake Tools 进入；不要同时维护 `tasks.json` 或 `launch.json`，否则会出现第二套构建或启动路径。
+- C/C++ 扩展只作为 CMake 快速调试的 `cppdbg` 后端；IntelliSense 关闭，补全、跳转、诊断和格式化只由 clangd 提供。
 - 不推荐与 clangd 冲突的 C++ 智能提示插件；只保留一个语言服务。
 - 不把 `compile_commands.json` 提交进仓库；它是构建产物。
-- 切换编译器时同时改 `.clangd`、`settings.json` 和构建目录；三处不一致会让诊断指向旧代码。
+- 切换编译器时同时改 `.clangd`、`settings.json` 和构建目录；三处不一致会让诊断指向旧代码。GCC 模式把 `MIMode` 改为 `gdb`、`miDebuggerPath` 改为 `/usr/bin/gdb`。
 
 ## 门禁分级
 
@@ -110,9 +122,9 @@ Diagnostics:
 
 | 级别 | 典型检查 | 处理 |
 | --- | --- | --- |
-| 失败 | `bugprone-*`、`readability-math-missing-parentheses`、`readability-identifier-naming`、项目声明的致命集 | 修代码；不允许用 NOLINT 掩盖 |
+| 失败 | `google-*`、`readability-identifier-naming`、项目声明的致命集 | 修代码；不允许用 NOLINT 掩盖 |
 | 失败 | 编译诊断、链接诊断、格式检查 | 直接失败 |
-| 观察 | 迁移期暂时无法修完的 `modernize-*` | 在项目技能里列清单、写负责人和退出条件；不默认全仓关闭 |
+| 观察 | 迁移期暂时无法修完的个别 `google-*` 子项 | 在项目技能里列清单、写负责人和退出条件；不默认全仓关闭 |
 
 - 致命集宁可小、可解释，也不要把所有检查一刀切。
 - 观察项不是免死金牌：新代码不应新增观察项，已有项只能减少。

package/skills/building-cpp/scripts/checking-encoding.mjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+// Read-only encoding audit for a Git work tree.
+//
+// Default profile "portable" is the cross-platform baseline: UTF-8 without BOM,
+// LF line endings, one final newline. Profile "msvc" allows a UTF-8 BOM and CRLF
+// only for MSVC-compiled C/C++ sources; Markdown, CMake, scripts and configs stay
+// portable. It never rewrites files.
+//
+// Usage:
+//   node checking-encoding.mjs [--root DIR] [--profile portable|msvc] [--json] [--quiet]
+//
+// Exit codes: 0 clean, 1 issues found, 2 usage or Git error.
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+export const EXIT = { ok: 0, issues: 1, usage: 2 }
+
+const UTF8_BOM = [0xef, 0xbb, 0xbf]
+const UTF16_LE = [0xff, 0xfe]
+const UTF16_BE = [0xfe, 0xff]
+const UTF32_LE = [0xff, 0xfe, 0x00, 0x00]
+const UTF32_BE = [0x00, 0x00, 0xfe, 0xff]
+
+const CRLF_REQUIRED = new Set(['.bat', '.cmd'])
+const MSVC_SOURCE = new Set([
+  '.c', '.cc', '.cpp', '.cxx', '.h', '.hh', '.hpp', '.hxx', '.inl', '.ixx', '.cppm', '.rc',
+])
+const ALWAYS_LF = new Set([
+  '.md', '.qmd', '.txt', '.rst', '.yml', '.yaml', '.json', '.jsonc', '.json5', '.toml',
+  '.ini', '.cfg', '.conf', '.sh', '.bash', '.zsh', '.fish', '.ps1', '.py', '.mjs', '.cjs',
+  '.js', '.jsx', '.ts', '.tsx', '.css', '.scss', '.sass', '.less', '.html', '.htm', '.xml',
+  '.svg', '.cmake', '.lua', '.sql', '.gitignore', '.gitattributes', '.editorconfig',
+])
+const NO_EXTENSION_LF = new Set(['CMakeLists.txt', 'Makefile', 'Justfile', 'Dockerfile', 'LICENSE'])
+
+function usage(message) {
+  if (message) process.stderr.write(`错误：${message}\n`)
+  process.stderr.write('用法：node checking-encoding.mjs [--root DIR] [--profile portable|msvc] [--json] [--quiet]\n')
+  return EXIT.usage
+}
+
+function parseArgs(argv) {
+  const options = { root: undefined, profile: 'portable', json: false, quiet: false }
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === '--root') {
+      options.root = argv[index + 1]
+      index += 1
+    } else if (arg === '--profile') {
+      options.profile = argv[index + 1]
+      index += 1
+    } else if (arg === '--json') {
+      options.json = true
+    } else if (arg === '--quiet') {
+      options.quiet = true
+    } else if (arg === '--help' || arg === '-h') {
+      options.help = true
+    } else {
+      throw new Error(`未知参数 ${arg}`)
+    }
+  }
+  if (options.profile !== 'portable' && options.profile !== 'msvc') {
+    throw new Error(`--profile 只能是 portable 或 msvc，收到 ${options.profile}`)
+  }
+  return options
+}
+
+function gitRoot(from) {
+  try {
+    return execFileSync('git', ['-C', from, 'rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+  } catch {
+    return undefined
+  }
+}
+
+function listFiles(root) {
+  const output = execFileSync('git', ['-C', root, 'ls-files', '-z', '--cached', '--others', '--exclude-standard'], {
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+  })
+  return output
+    .split('\0')
+    .filter(Boolean)
+    .map((item) => path.join(root, item))
+    .filter((file) => {
+      try {
+        return statSync(file).isFile()
+      } catch {
+        return false
+      }
+    })
+}
+
+function startsWith(buffer, bytes) {
+  return bytes.every((byte, index) => buffer[index] === byte)
+}
+
+function bomOf(buffer) {
+  if (startsWith(buffer, UTF32_LE)) return 'UTF-32 LE'
+  if (startsWith(buffer, UTF32_BE)) return 'UTF-32 BE'
+  if (startsWith(buffer, UTF8_BOM)) return 'UTF-8'
+  if (startsWith(buffer, UTF16_LE)) return 'UTF-16 LE'
+  if (startsWith(buffer, UTF16_BE)) return 'UTF-16 BE'
+  return undefined
+}
+
+function isBinary(buffer) {
+  const limit = Math.min(buffer.length, 8192)
+  for (let index = 0; index < limit; index += 1) {
+    if (buffer[index] === 0) return true
+  }
+  return false
+}
+
+function inspect(file, root, profile) {
+  const rel = path.relative(root, file).split(path.sep).join('/')
+  const extension = path.extname(file).toLowerCase()
+  const source = MSVC_SOURCE.has(extension)
+  const alwaysLf = ALWAYS_LF.has(extension) || NO_EXTENSION_LF.has(path.basename(file))
+  const issues = []
+  const add = (kind, message) => issues.push({ path: rel, kind, message })
+
+  let buffer
+  try {
+    buffer = readFileSync(file)
+  } catch (error) {
+    add('read', `无法读取（${error.message}）`)
+    return { rel, issues }
+  }
+
+  const bom = bomOf(buffer)
+  if (bom === 'UTF-8') {
+    if (profile !== 'msvc' || !source) {
+      add('bom', profile === 'msvc' && !source ? '只有 MSVC 编译的 C/C++ 源码可以带 BOM' : '不应带 BOM')
+    }
+  } else if (bom) {
+    add('bom', `发现 ${bom} BOM；只接受 UTF-8`)
+  }
+
+  if (bom && bom !== 'UTF-8') {
+    return { rel, issues }
+  }
+  if (isBinary(buffer)) {
+    return { rel, issues }
+  }
+
+  let text
+  try {
+    text = new TextDecoder('utf-8', { fatal: true }).decode(buffer)
+  } catch {
+    add('utf8', '不是合法 UTF-8')
+    return { rel, issues }
+  }
+
+  const body = text.startsWith('\uFEFF') ? text.slice(1) : text
+  if (body.includes('\uFEFF')) {
+    add('bom', '文件中间含 U+FEFF')
+  }
+
+  if (buffer.length > 0 && !body.endsWith('\n')) {
+    add('newline', '缺少末尾换行')
+  }
+
+  const crlf = (body.match(/\r\n/g) ?? []).length
+  const lf = (body.match(/(?<!\r)\n/g) ?? []).length
+  const cr = (body.match(/\r(?!\n)/g) ?? []).length
+
+  if (CRLF_REQUIRED.has(extension)) {
+    if (crlf === 0 || lf > 0 || cr > 0) add('eol', '应为 CRLF')
+  } else if (profile === 'msvc' && source && !alwaysLf) {
+    if ((crlf > 0 && lf > 0) || cr > 0) add('eol', '不要混用 CRLF 与 LF')
+  } else if (crlf > 0 || cr > 0) {
+    add('eol', '应为 LF')
+  }
+
+  return { rel, issues }
+}
+
+export function checkEncoding(root, profile = 'portable') {
+  const files = listFiles(root)
+  const results = []
+  for (const file of files) {
+    results.push(inspect(file, root, profile))
+  }
+  const issues = results.flatMap((result) => result.issues)
+  const counts = { files: results.length, issues: issues.length, bom: 0, eol: 0, utf8: 0, newline: 0, read: 0 }
+  for (const issue of issues) counts[issue.kind] = (counts[issue.kind] ?? 0) + 1
+  return { root, profile, files: results.length, issues, counts }
+}
+
+function main() {
+  let options
+  try {
+    options = parseArgs(process.argv.slice(2))
+  } catch (error) {
+    return usage(error.message)
+  }
+  if (options.help) {
+    process.stdout.write('检查 Git 工作树的 UTF-8/BOM、行尾与末尾换行；默认 portable。\n')
+    return EXIT.ok
+  }
+
+  const base = options.root ? path.resolve(options.root) : process.cwd()
+  if (!existsSync(base)) return usage(`根目录不存在：${base}`)
+  const root = gitRoot(base)
+  if (!root) return usage(`不是 Git 工作树：${base}`)
+
+  let report
+  try {
+    report = checkEncoding(root, options.profile)
+  } catch (error) {
+    process.stderr.write(`错误：${error.message}\n`)
+    return EXIT.usage
+  }
+
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+  } else if (!options.quiet || report.issues.length > 0) {
+    if (report.issues.length === 0) {
+      process.stdout.write(`编码检查：${report.files} 个文件，未发现问题（profile ${report.profile}）。\n`)
+    } else {
+      process.stdout.write(`编码检查：${report.files} 个文件，发现 ${report.issues.length} 个问题（profile ${report.profile}）。\n`)
+      for (const issue of report.issues) {
+        process.stdout.write(`  ${issue.path}: [${issue.kind}] ${issue.message}\n`)
+      }
+      process.stdout.write(
+        `汇总：BOM ${report.counts.bom}，行尾 ${report.counts.eol}，UTF-8 ${report.counts.utf8}，末尾换行 ${report.counts.newline}\n`,
+      )
+    }
+  }
+  return report.issues.length === 0 ? EXIT.ok : EXIT.issues
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  process.exitCode = main()
+}

package/skills/building-cpp/scripts/checking-environment.mjs

@@ -15,6 +15,8 @@ import { fileURLToPath, pathToFileURL } from 'node:url'
 export const HOSTS = ['windows', 'linux', 'macos']
 export const BUILD_HOSTS = ['native', 'wsl']
 export const COMPILERS = ['clang', 'gcc']
+export const STANDARDS = ['c++11', 'c++14', 'c++17', 'c++20', 'c++23']
+export const DEFAULT_STANDARD = 'c++23'
 const PROJECT_SKILL_DIR = path.join('.agents', 'skills', 'cpp-workflow-project')
 const MAX_ASCENT = 64
 
@@ -34,8 +36,9 @@ function normalize(value) {
 }
 
 /**
- * Validate the three axes and their combination. Pure: no filesystem or PATH.
- * @returns {{ok: boolean, issues: string[], notes: string[], axes: {host?: string, build_host?: string, compiler?: string}}}
+ * Validate the three environment axes, the language standard, and their combination.
+ * Pure: no filesystem or PATH.
+ * @returns {{ok: boolean, issues: string[], notes: string[], axes: {host?: string, build_host?: string, compiler?: string, standard?: string}}}
  */
 export function validateEnvironment(value) {
   const issues = []
@@ -53,6 +56,18 @@ export function validateEnvironment(value) {
     host: normalize(value.host),
     build_host: normalize(value.build_host),
     compiler: normalize(value.compiler),
+    standard: normalize(value.standard),
+  }
+
+  if (axes.standard === undefined || axes.standard === null || axes.standard === '') {
+    axes.standard = DEFAULT_STANDARD
+    notes.push(`standard 未声明或为空；按默认 ${DEFAULT_STANDARD} 处理，请在 environment.json 中显式写出`)
+  } else if (Array.isArray(axes.standard)) {
+    issues.push(`standard 只能声明一个值，当前是数组 [${axes.standard.join(', ')}]`)
+  } else if (typeof axes.standard !== 'string') {
+    issues.push(`standard 必须是字符串，当前是 ${typeof axes.standard}`)
+  } else if (!STANDARDS.includes(axes.standard)) {
+    issues.push(`standard 的值 "${axes.standard}" 非法；允许：${STANDARDS.join(' / ')}`)
   }
 
   for (const [key, allowed] of [
@@ -85,12 +100,12 @@ export function validateEnvironment(value) {
   }
 
   if (axes.host === 'windows' && axes.build_host === 'native') {
-    notes.push('windows + native 是合法声明，但本版本没有 PowerShell 构建脚本；--live 会报告缺 POSIX 壳，而不是缺编译器')
+    issues.push('本版本不能在 Windows 原生壳里构建')
   }
 
   for (const key of Object.keys(value)) {
-    if (!['host', 'build_host', 'compiler'].includes(key)) {
-      notes.push(`忽略未知键 "${key}"；环境只认 host / build_host / compiler`)
+    if (!['host', 'build_host', 'compiler', 'standard'].includes(key)) {
+      notes.push(`忽略未知键 "${key}"；环境只认 host / build_host / compiler / standard`)
     }
   }
 
@@ -245,25 +260,10 @@ export function checkLive(declaration, options = {}) {
   }
   const { host, build_host: buildHost, compiler } = validation.axes
 
-  if (host === 'windows' && buildHost === 'native') {
-    return {
-      ok: false,
-      issues: [
-        'Windows 原生构建缺少 POSIX 壳；本版本没有 PowerShell 构建脚本。缺的是壳，不是编译器。请改用 WSL 并把 build_host 改成 wsl，或补一个 PowerShell 版本。',
-      ],
-      notes: validation.notes,
-      checks,
-    }
-  }
-
   if (buildHost === 'wsl') {
     if (platform !== 'linux' || !isWsl(env)) {
       issues.push('声明 build_host=wsl，但当前进程不在 WSL 内；请在 WSL 里运行 --live')
     }
-  } else if (host === 'windows') {
-    if (platform !== 'win32') {
-      issues.push(`声明 host=windows + build_host=native，但当前平台是 ${platform}；请在 Windows 上运行 --live`)
-    }
   } else if (host === 'linux' && platform !== 'linux') {
     issues.push(`声明 host=linux，但当前平台是 ${platform}；请在 Linux 上运行 --live`)
   } else if (host === 'macos' && platform !== 'darwin') {
@@ -358,7 +358,7 @@ export function checkLive(declaration, options = {}) {
     ['clang-tidy', tidyVersion],
   ]) {
     if (version && version.major < 16) {
-      issues.push(`${role} ${versionText(version)} 过旧；需要 >= 16（配置使用 BreakAfterAttributes）`)
+      issues.push(`${role} ${versionText(version)} 过旧；本工作流要求 >= 16`)
     }
   }
 

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

@@ -16,28 +16,29 @@ build/
 
 ## 通用情况
 
-先读 `environment.json`。三个轴分别表示：
+先读 `environment.json`。源文件清单来自 `developing-cpp` 的定边界和定实现；定构建只把它们写进 target，不重新决定库与程序的边界。三个环境轴加语言标准分别表示：
 
 | 轴 | 取值 | 含义 |
 | --- | --- | --- |
 | `host` | `windows` / `linux` / `macos` | 编辑器与代理壳所在系统 |
-| `build_host` | `native` / `wsl` | 执行编译和运行产物的环境；`native` 表示 `host` 本机，`wsl` 表示 Windows 的 WSL，且只允许 `host=windows` |
+| `build_host` | `native` / `wsl` | 执行编译和运行产物的环境；`native` 表示 `host` 本机，`wsl` 表示 Windows 的 WSL，且只允许 `host=windows`；`windows` + `native` 本版本不支持 |
 | `compiler` | `clang` / `gcc` | 用哪个编译器；一次只配一个 |
+| `standard` | `c++11`–`c++23` | 一个工程一个语言标准；新工程默认 `c++23`，已有工程按原声明 |
 
-轴为空、值未知或组合非法（如 `host=linux` + `build_host=wsl`）时，停在定构建，先让用户把 `environment.json` 填对。不要替用户选 WSL、Clang 或构建目录。
+环境轴为空、`standard` 非法或组合非法（如 `host=linux` + `build_host=wsl`、`host=windows` + `build_host=native`）时，停在定构建，先让用户把 `environment.json` 填对。不要替用户选 WSL、Clang 或构建目录。`windows` + `native` 只给一句「本版本不能在 Windows 原生壳里构建」，不要建议改 WSL、不要提出补 PowerShell 脚本。
 
 构建规则：
 
-- CMake 最低 3.20；`project(... LANGUAGES CXX)`；只有确有 C 源时才写 `LANGUAGES C CXX`。目标标准 C++20。
+- 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 只链接被测库的公共接口。
+- 库的公共 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_20)`；库用 `PUBLIC` 传播标准。每个 target 再加 `CXX_EXTENSIONS OFF`，避免 CMake 默认的 `-std=gnu++20`。
+- 目标标准写在 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` 等改变语义或可移植性的选项；警告选项按团队约定统一加。
@@ -59,11 +60,11 @@ GCC 模式把目录和编译器换成 `build/gcc`、`g++`。工程确有 C 源
 
 ## 情况
 
-**新工程**：从 `assets/templates/projects/` 选形态：`single` 单文件、`multi` 多文件单程序、`static-library` 静态库 + 程序、`shared-library` 动态库 + 程序。只复制目标工程缺的文件；已有的 `CMakeLists.txt`、`.clang-*`、源码不覆盖。模板里的 `{{PROJECT_NAME}}` 换成真实工程名。
+**新工程**：从 `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` 的五档矩阵。模板源码是 `.cc`，头文件用路径式 `#define` 守卫；新增文件沿用 `.cc` / `.h`，已有工程保持原有扩展名。
 
 **已有工程**：先读现有 `CMakeLists.txt`，找出全局设置、GLOB、输出目录和 target 命名；只改与当前任务相关的一处。大改前先让通过检查的项目入口跑通，保留可回退点。
 
-**库 + 程序**：库 target 的 `PUBLIC` include 根指向 `<component>/include`；程序 target 只链接库，不直接包含库的 `src/`。静态库与动态库的接口相同；动态库额外设置运行时库路径。
+**库 + 程序**：库 target 的 `PUBLIC` include 根按项目约定设置；本工作流把仓库根作为源码根，程序按 `#include "component/include/name.h"` 包含公共头，不直接包含库的 `src/`。静态库与动态库的接口相同；动态库额外设置运行时库路径。
 
 **测试**：`enable_testing()` 放在顶层，`add_subdirectory(tests)` 在 `add_subdirectory(<component>)` 之后；测试 target 用 `add_test(NAME ... COMMAND ...)` 注册。没有测试时不要为了「看起来完整」加空测试。
 
@@ -74,3 +75,4 @@ GCC 模式把目录和编译器换成 `build/gcc`、`g++`。工程确有 C 源
 - 全局 include、GLOB、把 `main()` 编进库：`examples/cmake.md`。
 - 正确的最小库 + 程序：`examples/cmake.md`「最小可用形状」。
 - target 与目录的完整说明：`references/cmake.md`。
+- 五档标准的下限、降档替换和工具映射：`references/standards/README.md`。