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

package/README.en.md

@@ -8,7 +8,7 @@ Two skills for C++11–C++23 source and build work; new projects default to C++2
 
 | Skill | Covers | Open it when |
 | --- | --- | --- |
-| `developing-cpp` | Behavior, boundaries, declarations, implementation; naming, exceptions, and source comments in `.h` / `.cc` | The user names source code, or the work is a new project or whole-stage refactor |
+| `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 |
 
 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.
@@ -18,13 +18,13 @@ The exception material follows the C++ Core Guidelines' Error handling section a
 Pinned npm install:
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.2.0
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.3.1
 ```
 
 The matching Git tag:
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.2.0
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.3.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.
@@ -89,7 +89,9 @@ dsh-cpp-workflow/
 └── icon.svg
 ```
 
-Maintenance notes: flow and gate in [docs/plugin-flow.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-flow.md), directory and npm whitelist in [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-layout.md), version rules in [docs/versioning.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/versioning.md).
+The repository also keeps `src/`, `scripts/`, `tests/` and `docs/` for development and review; they are not published. The whitelist lives in [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-layout.md).
+
+Maintenance notes: flow and gate in [docs/plugin-flow.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-flow.md), skill layers and data flow in [docs/architecture.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/architecture.md), trigger matrix in [docs/triggering.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/triggering.md), directory and npm whitelist in [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-layout.md), version rules in [docs/versioning.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/versioning.md).
 
 ## Local development
 
@@ -97,7 +99,7 @@ Requires Node.js 22 or newer.
 
 ```bash
 npm ci
-npm test              # build, structural check, gate/environment/schema tests
+npm test              # build, 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

@@ -8,7 +8,7 @@
 
 | 技能 | 管什么 | 什么时候打开 |
 | --- | --- | --- |
-| `developing-cpp` | 定行为、定边界、定声明、定实现；`.h` / `.cc` 的命名、异常和源码注释 | 用户点名源码，或需要新建/整段重构源码 |
+| `developing-cpp` | 定行为、定边界、定声明、定实现；`.h` / `.cpp` / `.cc` 的命名、异常和源码注释 | 用户点名源码，或需要新建/整段重构源码 |
 | `building-cpp` | 定构建、定工具配置、通过检查；CMake、Ninja、Clang 配置、构建脚本和环境组合 | 改动落在构建文件、工具配置或环境声明上，或第一次接构建 |
 
 异常条文采用 C++ Core Guidelines 的 Error handling，只在开发阶段指导源码和示例；插件运行时不编译、不执行这些规则。两个技能都先读项目技能 `cpp-workflow-project`。没有项目技能时，门禁不会放出这两个名字。
@@ -18,13 +18,13 @@
 npm 安装钉死版本：
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.2.0
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.3.1
 ```
 
 同版本的 Git 标签：
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.2.0
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.3.1
 ```
 
 桌面应用独占 `desktop` profile。命令行 `add` 被拒绝时，在应用设置里添加插件，地址填同一个 npm 版本。Git 标签安装使用仓库内已构建的 `lib/`，不在目标机器上重新构建；包内也不含需要授权执行的安装脚本。
@@ -89,7 +89,9 @@ dsh-cpp-workflow/
 └── icon.svg
 ```
 
-边界与门禁的维护说明在 [docs/plugin-flow.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-flow.md)，目录和进包白名单在 [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-layout.md)，版本规则在 [docs/versioning.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/versioning.md)。
+仓库另有 `src/`、`scripts/`、`tests/` 与 `docs/`，只服务开发与评审，不进包；白名单见 [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-layout.md)。
+
+边界与门禁的维护说明在 [docs/plugin-flow.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-flow.md)，技能的层次与数据流在 [docs/architecture.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/architecture.md)，触发矩阵在 [docs/triggering.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/triggering.md)，目录和进包白名单在 [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-layout.md)，版本规则在 [docs/versioning.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/versioning.md)。
 
 ## 本地开发
 
@@ -97,7 +99,7 @@ dsh-cpp-workflow/
 
 ```bash
 npm ci
-npm test              # 构建、结构检查、门禁/环境/schema 测试
+npm test              # 构建、结构检查、门禁/环境/schema/注释测试
 npm run test:matrix   # 四套模板 × 五档标准的真实构建矩阵
 npm run pack:check    # 核对 npm 包内容
 ```

package/lib/workspace.js

@@ -6,12 +6,10 @@
 // freshly copied template still sees the workflow. The git root is the
 // repository boundary: marker lookup ignores sibling directories and never
 // searches above the root.
-import { access, readdir } from 'node:fs/promises';
+import { access } from 'node:fs/promises';
 import path from 'node:path';
 export const PROJECT_SKILL = path.join('.agents', 'skills', 'cpp-workflow-project', 'SKILL.md');
 export const MAX_ASCENT = 64;
-export const MAX_SCAN_DEPTH = 12;
-export const MAX_SCAN_ENTRIES = 4000;
 const SKIPPED_DIRS = new Set([
     '.git',
     'node_modules',
@@ -22,16 +20,6 @@ const SKIPPED_DIRS = new Set([
     'temp',
     '.cache',
 ]);
-export const CPP_SOURCE_EXTENSIONS = new Set([
-    '.c',
-    '.cc',
-    '.cpp',
-    '.cxx',
-    '.h',
-    '.hh',
-    '.hpp',
-    '.hxx',
-]);
 export const CPP_BUILD_FILES = new Set(['CMakeLists.txt']);
 async function exists(target) {
     try {
@@ -107,49 +95,6 @@ export async function findProjectSkill(cwd, gitRoot) {
 export async function hasProjectSkill(cwd, gitRoot) {
     return (await findProjectSkill(cwd, gitRoot)) !== undefined;
 }
-/**
- * True when `root` contains at least one first-party `CMakeLists.txt` or C++
- * source/header. Generated, dependency, template and build trees are skipped.
- * The scan is bounded to 12 levels and 4000 directory entries.
- */
-export async function hasCppProject(root) {
-    let seen = 0;
-    const queue = [{ dir: root, depth: 0 }];
-    while (queue.length > 0) {
-        const current = queue.shift();
-        if (!current)
-            break;
-        let entries;
-        try {
-            entries = await readdir(current.dir, { withFileTypes: true });
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            seen += 1;
-            if (seen > MAX_SCAN_ENTRIES)
-                return false;
-            if (entry.isSymbolicLink())
-                continue;
-            if (entry.isDirectory()) {
-                if (current.depth >= MAX_SCAN_DEPTH)
-                    continue;
-                if (SKIPPED_DIRS.has(entry.name))
-                    continue;
-                queue.push({ dir: path.join(current.dir, entry.name), depth: current.depth + 1 });
-                continue;
-            }
-            if (!entry.isFile())
-                continue;
-            if (CPP_BUILD_FILES.has(entry.name))
-                return true;
-            if (CPP_SOURCE_EXTENSIONS.has(path.extname(entry.name).toLowerCase()))
-                return true;
-        }
-    }
-    return false;
-}
 /**
  * Session gate. The project skill must sit between `cwd` and the git root
  * (inclusive). First-party C++ or CMake evidence is deliberately not required:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chengzhao-dev/dsh-cpp-workflow",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "C++11–C++23 工程流程技能包：源码四步与构建三步，按项目声明的环境组合校验 · C++11–C++23 workflow skills for DeepSeek Harness",
   "type": "module",
   "main": "./lib/index.js",
@@ -42,7 +42,8 @@
   "icon": "./icon.svg",
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node scripts/checking-skill-links.mjs && node --test tests/*.test.mjs",
+    "test": "npm run build && node scripts/checking-skill-links.mjs && node skills/building-cpp/scripts/checking-encoding.mjs --quiet && node --test tests/*.test.mjs",
+    "check:encoding": "node skills/building-cpp/scripts/checking-encoding.mjs",
     "test:matrix": "bash scripts/checking-standard-matrix.sh",
     "pack:check": "npm pack --dry-run"
   },

package/skills/building-cpp/SKILL.md

@@ -13,6 +13,8 @@ metadata:
 
 编译失败先分因：诊断指向函数体，回 `developing-cpp` 的定实现；诊断指向声明或类型，回定声明；诊断是找不到头、链接失败、没有编译数据库或工具不在 PATH，留在本技能的定构建或定工具配置。
 
+源码和构建文件用 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 的路线。环境组合空着时源码四步仍可做，只是不能构建。
 
 ## 两种走法
@@ -30,9 +32,9 @@ metadata:
 | --- | --- | --- | --- |
 | 1 | 定构建 | `steps/01-build.md` | 一次配置一个编译器，Ninja，target-based CMake，编译数据库 |
 | 2 | 定工具配置 | `steps/02-tooling.md` | 格式化、静态检查、clangd 各管一段，互不越界 |
-| 3 | 通过检查 | `steps/03-check.md` | 先跑环境脚本的 `--live`，再跑项目入口，按失败位置分诊 |
+| 3 | 通过检查 | `steps/03-check.md` | 按编码 → 声明校验 → 活动校验 → 项目入口的次序跑，前一步失败就停 |
 
-每步只打开同号的一个步骤文件。判不准才打开 `examples/` 里与该步对应的案例；`references/` 保存完整条文，只在排错、整目录重构，或步骤里明确指向某一条文时按需打开。
+每步只打开同号的一个步骤文件。判不准才打开 `examples/` 里与该步对应的案例；`references/` 保存完整条文，只在排错、整目录重构，或步骤里明确指向某一条文时按需打开。链接、rpath 与产物布局读 `references/linking.md`；警告选项、GoogleTest 与 rpath 的 CMake 片段在 `assets/cmake/`，由 `references/cmake.md` 指路。
 
 ## 完成判据
 

package/skills/building-cpp/assets/config/.clang-format

@@ -3,3 +3,5 @@
 Language: Cpp
 BasedOnStyle: Google
 Standard: Latest
+# 与根 .gitattributes 和 .editorconfig 同档：格式化不把行尾改回 CRLF。
+LineEnding: LF

package/skills/building-cpp/assets/config/.clang-tidy

@@ -5,6 +5,7 @@ InheritParentConfig: false
 Checks: >
   -*,
   google-*,
+  portability-avoid-pragma-once,
   readability-identifier-naming
 
 WarningsAsErrors: '*'

package/skills/building-cpp/assets/templates/projects/multi/CMakeLists.txt

@@ -7,8 +7,8 @@ set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
 enable_testing()
 
 add_executable(app
-  src/main.cc
-  src/greeting.cc
+  src/main.cpp
+  src/greeting.cpp
 )
 target_include_directories(app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
 target_compile_features(app PRIVATE cxx_std_23)

package/skills/building-cpp/assets/templates/projects/shared-library/CMakeLists.txt

@@ -9,7 +9,7 @@ enable_testing()
 
 add_subdirectory(greeting)
 
-add_executable(app src/main.cc)
+add_executable(app src/main.cpp)
 target_include_directories(app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
 target_compile_features(app PRIVATE cxx_std_23)
 set_target_properties(app PROPERTIES

package/skills/building-cpp/assets/templates/projects/shared-library/greeting/CMakeLists.txt

@@ -1,4 +1,4 @@
-add_library(greeting SHARED src/greeting.cc)
+add_library(greeting SHARED src/greeting.cpp)
 target_include_directories(greeting PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/..)
 target_compile_features(greeting PUBLIC cxx_std_23)
 set_target_properties(greeting PROPERTIES

package/skills/building-cpp/assets/templates/projects/single/CMakeLists.txt

@@ -6,7 +6,7 @@ set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
 
 enable_testing()
 
-add_executable(app src/main.cc)
+add_executable(app src/main.cpp)
 target_compile_features(app PRIVATE cxx_std_23)
 set_target_properties(app PROPERTIES
   CXX_STANDARD 23

package/skills/building-cpp/assets/templates/projects/static-library/CMakeLists.txt

@@ -9,7 +9,7 @@ enable_testing()
 
 add_subdirectory(greeting)
 
-add_executable(app src/main.cc)
+add_executable(app src/main.cpp)
 target_include_directories(app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
 target_compile_features(app PRIVATE cxx_std_23)
 set_target_properties(app PROPERTIES

package/skills/building-cpp/assets/templates/projects/static-library/greeting/CMakeLists.txt

@@ -1,4 +1,4 @@
-add_library(greeting STATIC src/greeting.cc)
+add_library(greeting STATIC src/greeting.cpp)
 target_include_directories(greeting PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/..)
 target_compile_features(greeting PUBLIC cxx_std_23)
 set_target_properties(greeting PROPERTIES

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

@@ -10,13 +10,13 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
 set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
 
-add_library(greeting STATIC greeting/src/greeting.cc)
+add_library(greeting STATIC greeting/src/greeting.cpp)
 target_include_directories(greeting PUBLIC greeting/include)
 target_compile_features(greeting PUBLIC cxx_std_23)
 set_target_properties(greeting PROPERTIES CXX_EXTENSIONS OFF)
 target_compile_options(greeting PRIVATE -Wall -Wextra -Werror)
 
-add_executable(app src/main.cc)
+add_executable(app src/main.cpp)
 target_compile_features(app PRIVATE cxx_std_23)
 set_target_properties(app PROPERTIES CXX_EXTENSIONS OFF)
 target_link_libraries(app PRIVATE greeting)
@@ -30,7 +30,7 @@ target_link_libraries(app PRIVATE greeting)
 
 ```cmake
 include_directories(include greeting/include)
-add_executable(app src/main.cc greeting/src/greeting.cc)
+add_executable(app src/main.cpp greeting/src/greeting.cpp)
 ```
 
 问题：所有 target 共享 include，边界消失；程序直接编译库源码，测试无法只链接库。
@@ -47,7 +47,7 @@ target_link_libraries(app PRIVATE greeting)
 **差**：
 
 ```cmake
-file(GLOB SOURCES "src/*.cc")
+file(GLOB SOURCES "src/*.cpp")
 add_executable(app ${SOURCES})
 ```
 
@@ -57,9 +57,9 @@ add_executable(app ${SOURCES})
 
 ```cmake
 add_executable(app
-  src/main.cc
-  src/task_list.cc
-  src/task_parser.cc
+  src/main.cpp
+  src/task_list.cpp
+  src/task_parser.cpp
 )
 ```
 
@@ -70,15 +70,15 @@ add_executable(app
 **差**：
 
 ```cmake
-add_library(core STATIC src/main.cc src/core.cc)
-add_executable(app src/main.cc)   # 重复定义
+add_library(core STATIC src/main.cpp src/core.cpp)
+add_executable(app src/main.cpp)   # 重复定义
 ```
 
 **好**：
 
 ```cmake
-add_library(core STATIC src/core.cc)
-add_executable(app src/main.cc)
+add_library(core STATIC src/core.cpp)
+add_executable(app src/main.cpp)
 target_link_libraries(app PRIVATE core)
 ```
 
@@ -93,7 +93,7 @@ target_link_libraries(app PRIVATE core)
 ```
 
 ```bash
-clang-tidy src/main.cc   # 没有编译参数，头路径和标准都不对
+clang-tidy src/main.cpp   # 没有编译参数，头路径和标准都不对
 ```
 
 **好**：
@@ -106,7 +106,7 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 cmake -S . -B build/clang -G Ninja -DCMAKE_CXX_COMPILER=clang++
 rm -f build/compile_commands.json
 ln -s clang/compile_commands.json build/compile_commands.json
-clang-tidy -p build/clang src/main.cc
+clang-tidy -p build/clang src/main.cpp
 ```
 
 ## 共享库运行时路径
@@ -120,11 +120,11 @@ LD_LIBRARY_PATH=build/clang/lib ./build/clang/bin/app   # 每次运行都要包
 **好**：
 
 ```cmake
-add_library(greeting SHARED greeting/src/greeting.cc)
+add_library(greeting SHARED greeting/src/greeting.cpp)
 set_target_properties(greeting PROPERTIES
   LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
 
-add_executable(app src/main.cc)
+add_executable(app src/main.cpp)
 target_link_libraries(app PRIVATE greeting)
 if(APPLE)
   set_target_properties(app PROPERTIES BUILD_RPATH "@loader_path/../lib")

package/skills/building-cpp/examples/tooling.md

@@ -121,7 +121,7 @@ Checks: >
 **差**：
 
 ```bash
-clang-tidy -p build/clang --system-headers src/main.cc
+clang-tidy -p build/clang --system-headers src/main.cpp
 ```
 
 系统头也参与诊断，出现大量第三方告警。
@@ -130,7 +130,7 @@ clang-tidy -p build/clang --system-headers src/main.cc
 
 ```bash
 clang-tidy -p build/clang --header-filter="^$(pwd -P)/(include|src)/" \
-  --warnings-as-errors='*' src/main.cc
+  --warnings-as-errors='*' src/main.cpp
 ```
 
 `--header-filter` 只列项目顶层目录，避免把第三方头纳入；系统头默认排除。工程有别的顶层目录时按实际替换。
@@ -140,7 +140,7 @@ clang-tidy -p build/clang --header-filter="^$(pwd -P)/(include|src)/" \
 **差**：
 
 ```bash
-clang-format -i src/*.cc   # 构建时悄悄改源码
+clang-format -i src/*.cpp   # 构建时悄悄改源码
 ```
 
 **好**：

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

@@ -1,6 +1,6 @@
 # CMake
 
-目标：一个编译器、Ninja、target-based 规则、可用的编译数据库。下面是最小形状和常见边界；模板在 `assets/templates/projects/`。
+目标：一个编译器、Ninja、target-based 规则、可用的编译数据库。下面是最小形状和常见边界；模板在 `assets/templates/projects/`，可复用的 CMake 片段在 `assets/cmake/`：`applying-warnings.cmake` 管警告选项，`fetching-googletest.cmake` 取测试框架，`setting-rpath.cmake` 设运行时库路径。
 
 ## 排版
 
@@ -19,7 +19,7 @@ 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.cc)
+add_executable(app src/main.cpp)
 target_compile_features(app PRIVATE cxx_std_23)
 set_target_properties(app PROPERTIES
   CXX_STANDARD 23
@@ -42,7 +42,7 @@ set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
 
 add_subdirectory(greeting)
 
-add_executable(app src/main.cc)
+add_executable(app src/main.cpp)
 target_compile_features(app PRIVATE cxx_std_23)
 set_target_properties(app PROPERTIES
   CXX_STANDARD 23
@@ -55,7 +55,7 @@ target_compile_options(app PRIVATE -Wall -Wextra -Werror)
 
 ```cmake
 # greeting/CMakeLists.txt
-add_library(greeting STATIC src/greeting.cc)
+add_library(greeting STATIC src/greeting.cpp)
 target_include_directories(greeting PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/..)
 target_compile_features(greeting PUBLIC cxx_std_23)
 set_target_properties(greeting PROPERTIES
@@ -168,7 +168,7 @@ FetchContent_MakeAvailable(googletest)
 
 | 模板 | 何时用 | 关键文件 |
 | --- | --- | --- |
-| `single` | 一个 `main.cc`，辅助函数很少 | `CMakeLists.txt`, `src/main.cc` |
+| `single` | 一个 `main.cpp`，辅助函数很少 | `CMakeLists.txt`, `src/main.cpp` |
 | `multi` | 多个源文件，一个程序 | `CMakeLists.txt`, `include/`, `src/` |
 | `static-library` | 库需要被测试或第二个程序链接 | 根 + `greeting/` 子目录 |
 | `shared-library` | 需要运行时加载/替换 | 同上，`SHARED` + RPATH |
@@ -178,7 +178,7 @@ FetchContent_MakeAvailable(googletest)
 ## 反模式
 
 - 全局 `include_directories(include)`：所有 target 共享，边界消失。
-- `file(GLOB sources "src/*.cc")`：新增文件不触发重新配置。
+- `file(GLOB sources "src/*.cpp")`：新增文件不触发重新配置。
 - 把库和 `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/linking.md

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

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

@@ -43,7 +43,7 @@
 
 ## 降档/升级
 
-从 C++23 降到 C++20 见 [C++20 档案](../c++20/README.md)。升级到 C++26 前先确认 CMake 3.25+、编译器/标准库支持、clang-format 的 `c++26` 枚举；新增目录流程见[标准索引](../README.md#新增标准)。
+从 C++23 降到 C++20 见 [C++20 档案](../c++20/README.md)。升级到 C++26 前先确认 CMake 3.25+、编译器/标准库支持、clang-format 的 `c++26` 枚举；新增目录流程见 [标准索引](../README.md#新增标准)。
 
 ## 验证
 

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

@@ -5,7 +5,7 @@
 ## clang-format
 
 ```bash
-clang-format --dry-run --Werror src/*.cc include/*.h tests/*.cc
+clang-format --dry-run --Werror src/*.cpp include/*.h tests/*.cpp
 ```
 
 - 检查用 `--dry-run --Werror`；需要自动修复时单独跑 `clang-format -i`，不要在构建脚本里悄悄改源码。
@@ -21,7 +21,7 @@ clang-format --dry-run --Werror src/*.cc include/*.h tests/*.cc
 clang-tidy -p build/clang \
   --header-filter="^$(pwd -P)/(include|src|apps|tests)/" \
   --warnings-as-errors='*' \
-  src/*.cc apps/*.cc tests/*.cc
+  src/*.cpp apps/*.cpp tests/*.cpp
 ```
 
 - `-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`；默认集合是 `google-*` 加 `readability-identifier-naming`。关闭某条时逐条写理由，不整族关闭；命名规则只配项目确实统一的项，不设 `FunctionCase`。
+- 配置在工程根 `.clang-tidy`；默认集合是 `google-*`、`portability-avoid-pragma-once` 加 `readability-identifier-naming`（第二条去掉 `#pragma once`，与路径式守卫一致）。关闭某条时逐条写理由，不整族关闭；命名规则只配项目确实统一的项，不设 `FunctionCase`。
 - 没有编译数据库时先回到 `building-cpp` 的定构建生成；不要用 `--` 手工拼编译参数绕过。
 - `clang-tidy` 的诊断可能指向头文件；修头文件里的声明或实现，不要只改调用点。