@chengzhao-dev/dsh-cpp-workflow 0.5.4 → 0.5.5

package/README.en.md

@@ -19,13 +19,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.5.4
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.5.5
 ```
 
 The matching Git tag:
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.5.4
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.5.5
 ```
 
 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.
@@ -103,9 +103,11 @@ npm ci
 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
+npm run ci            # replay the Ubuntu CI job: install, test, package check
+npm run ci:full       # ci plus the standard matrix; needs a POSIX host
 ```
 
-Source lives in `src/`; `npm run build` writes `lib/`. The structural check is `scripts/checking-skill-links.mjs`. Tests do not invoke a local compiler; the environment checks use fixed version strings. The standard matrix needs `cmake`, `ninja`, `perl`, and `clang++` (or the compiler named by `CXX`) on a POSIX host such as WSL, Linux, or macOS.
+Source lives in `src/`; `npm run build` writes `lib/`. The structural check is `scripts/checking-skill-links.mjs`. Tests do not invoke a local compiler; the environment checks use fixed version strings. The standard matrix needs `cmake`, `ninja`, `perl`, and `clang++` (or the compiler named by `CXX`) on a POSIX host such as WSL, Linux, or macOS. On Windows, run `npm run ci` first, then run `npm run ci:full` from WSL inside the checkout.
 
 ## License
 

package/README.md

@@ -19,13 +19,13 @@
 npm 安装钉死版本：
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.5.4
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.5.5
 ```
 
 同版本的 Git 标签：
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.5.4
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.5.5
 ```
 
 桌面应用独占 `desktop` profile。命令行 `add` 被拒绝时，在应用设置里添加插件，地址填同一个 npm 版本。Git 标签安装使用仓库内已构建的 `lib/`，不在目标机器上重新构建；包内也不含需要授权执行的安装脚本。
@@ -103,9 +103,11 @@ npm ci
 npm test              # 构建、三技能结构检查、门禁/环境/schema/注释测试
 npm run test:matrix   # 四套模板 × 五档标准的真实构建矩阵
 npm run pack:check    # 核对 npm 包内容
+npm run ci            # 复现 Ubuntu CI：安装、测试、打包检查
+npm run ci:full       # 在 ci 之上再跑标准矩阵，需 POSIX 宿主
 ```
 
-源码在 `src/`，`npm run build` 生成 `lib/`。结构检查在 `scripts/checking-skill-links.mjs`；测试不调用本机编译器，环境检查用固定版本字符串。标准矩阵需要 POSIX 宿主上的 `cmake`、`ninja`、`perl` 和 `clang++`（或 `CXX` 指定的编译器），在 WSL/Linux/macOS 上运行。
+源码在 `src/`，`npm run build` 生成 `lib/`。结构检查在 `scripts/checking-skill-links.mjs`；测试不调用本机编译器，环境检查用固定版本字符串。标准矩阵需要 POSIX 宿主上的 `cmake`、`ninja`、`perl` 和 `clang++`（或 `CXX` 指定的编译器），在 WSL/Linux/macOS 上运行。Windows 上先跑 `npm run ci`，再从 WSL 进入仓库跑 `npm run ci:full`。
 
 ## 许可
 

package/package.json

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

package/skills/developing-cpp/examples/comments-declaration.md

@@ -14,11 +14,10 @@
 **好**：
 
 ```cpp
-//===----------------------------------------------------------------------===//
-// board.h - 定义井字棋棋盘、格子坐标与格子类型。
-//
-// 棋盘保存九个棋盘格子的状态，提供只读查询、落子与整盘清空。
-//===----------------------------------------------------------------------===//
+/// @file board.h
+/// @brief 定义井字棋棋盘、格子坐标与格子类型。
+///
+/// 棋盘保存九个棋盘格子的状态，提供只读查询、落子与清空棋盘。
 ```
 
 文件头只介绍这个文件里有什么，不写作者和变更史，也不把读者指去另一个文件。
@@ -310,11 +309,10 @@ Standard: Latest
 **好**：
 
 ```cpp
-//===----------------------------------------------------------------------===//
-// board.h - 棋盘状态与规则判断
-//
-// 定义 Board 的查询、落子与整盘清空。
-//===----------------------------------------------------------------------===//
+/// @file board.h
+/// @brief 棋盘状态与规则判断。
+///
+/// 定义 Board 的查询、落子与清空棋盘。
 ```
 
 变更史进提交说明，外部资料进文档，团队流程进规范文件；注释只写这个文件或这个类型自己的内容，不把读者指去别的文件。

package/skills/developing-cpp/references/comments.md

@@ -100,7 +100,7 @@ GameResult result_ = GameResult::kInProgress;
 
 | 层 | 行数 | 第一句 | 写什么 |
 | --- | --- | --- | --- |
-| 文件头 | 3–6 | 文件名 - 这个文件定义或实现什么 | 本文件由哪几部分组成 |
+| 文件头 | 3–7 | `@file` 文件名 + `@brief` 一句话 | 本文件由哪几部分组成 |
 | 类型注释 | 2–14 | 名词短语：这个类型或取值是什么 | 只有类的不变量 |
 | 特殊成员 | 1–3 | 标签（默认/拷贝/移动构造函数、析构函数） | 后置条件或职责 |
 | 函数注释 | 3–10 | 正常返回什么、失败时返回或抛什么、检查什么 | 参数与失败方式 |
@@ -109,29 +109,28 @@ GameResult result_ = GameResult::kInProgress;
 
 ## 布局：放在哪一层、哪一行
 
-- `///` 只给声明：头文件里的类型、函数、枚举值、公开与私有数据成员。数据成员的主注释写在上一行；行尾 `///<` 只用于枚举项和 `struct` 的短字段。调用方和 Doxygen 从这里取契约。
-- `//` 给实现：函数体内的阶段与边界说明、局部变量、文件头横幅、配置文件的说明。
-- 不给局部变量和函数体里的语句写 `///`；文件头也不写成 `///`，否则编辑器会把它挂到紧随其后的第一个声明上。
-- 判断看一句话写的是「调用方要遵守的承诺」还是「维护者要知道的写法」：前者用 `///`，后者用 `//`。
+- `///` 给声明与文件头：头文件里的类型、函数、枚举值、公开与私有数据成员，以及文件头的 `@file`/`@brief` 块。数据成员的主注释写在上一行；行尾 `///<` 只用于枚举项和 `struct` 的短字段。调用方和 Doxygen 从这里取契约。
+- `///` 也给实现：函数体内的阶段与边界说明、局部变量，一律用 `///`，不混 `//`。
+- `//` 只留给工具指令与别种文件：`// NOLINTNEXTLINE(...)`、`#endif  // MACRO` 这类要被工具读取的标记，以及 CMake、YAML 等非 C++ 文件。
+- 判断看位置：声明写契约，实现写理由，两者都用 `///`；`//` 不再表示「实现注释」。
 - 位置固定：文件头在最上方；类型注释紧贴类型声明；特殊成员（构造、析构、拷贝与移动）排在其他函数之前；函数注释紧贴函数声明；数据成员的主注释紧贴声明上一行，不写行尾补充。
 - 类数据成员（含私有）的主注释用 `///`；行尾 `///<` 只给枚举项和 `struct` 的短字段。
 - 注释和它说明的声明之间不留空行；同一个声明块内，空行只用来分组。
 
 ### 文件头
 
-每个手写源文件开头写一段文件头：第一行是「文件名 - 本文件定义或实现什么」，后面只写本文件自己的组成部分或边界。删掉把读者指去另一个头文件、另一个目录或另一层的句子，也删掉「这一层不负责什么」。不写作者、版权年份、变更日志和外部资料路径。
+每个手写源文件开头写一段 doxygen 文件头：第一行 `/// @file <文件名>`，第二行 `/// @brief` 一句话说明这个文件定义或实现什么，用一行 `///` 隔开后，只写本文件自己的组成部分或边界。删掉把读者指去另一个头文件、另一个目录或另一层的句子，也删掉「这一层不负责什么」。不写作者、版权年份、变更日志和外部资料路径。
 
 ```cpp
-//===----------------------------------------------------------------------===//
-// board.h - 定义井字棋棋盘、格子坐标与格子类型。
-//
-// 棋盘保存九个棋盘格子的状态，提供只读查询、落子与整盘清空。
-//===----------------------------------------------------------------------===//
+/// @file board.h
+/// @brief 定义井字棋棋盘、格子坐标与格子类型。
+///
+/// 棋盘保存九个棋盘格子的状态，提供只读查询、落子与清空棋盘。
 ```
 
-- C++ 用 `//`，CMake 用 `#`，YAML/JSON 用 `#` 或 `//`。
+- C++ 源文件用以上格式；CMake 用 `#`，YAML/JSON 用 `#`。
 - 超过约 200 行的文件用章节横幅分组，组名是读者要跳转的锚点；一个文件不超过 8 个横幅。
-- 文件头 3–6 行；第一行点文件名，后面只写本文件的范围与组成，不写实现步骤、作者和变更史。
+- 文件头 3–7 行；`@file` 与 `@brief` 各占一行，后面只写本文件的范围与组成，不写实现步骤、作者和变更史。
 
 ## 排版：符号、宽度、横幅与标签
 

package/skills/developing-cpp/references/file-template.md

@@ -46,11 +46,10 @@
 5. `#endif  // MACRO`
 
 ```cpp
-//===----------------------------------------------------------------------===//
-// thing_table.h - 定义 ThingTable 与它用到的状态。
-//
-// 头文件放常量、枚举、结构体与类声明。
-//===----------------------------------------------------------------------===//
+/// @file thing_table.h
+/// @brief 定义 ThingTable 与它用到的状态。
+///
+/// 头文件放常量、枚举、结构体与类声明。
 
 #ifndef PROJECT_PATH_FILE_H_
 #define PROJECT_PATH_FILE_H_
@@ -99,9 +98,8 @@ class ThingTable {
 4. 命名空间与定义
 
 ```cpp
-//===----------------------------------------------------------------------===//
-// thing_table.cpp - 实现 ThingTable 的添加与查询。
-//===----------------------------------------------------------------------===//
+/// @file thing_table.cpp
+/// @brief 实现 ThingTable 的添加与查询。
 
 #include "project/path/thing.h"
 

package/skills/developing-cpp/scripts/checking-comments.mjs

@@ -25,8 +25,10 @@ const SKIP_DIR = new Set([
   '.tmp', 'temp', 'third_party', 'third-party', 'external', 'vendor', 'deps', 'cmake-build-debug',
   'cmake-build-release', '.vs', '.idea',
 ])
-const FORBIDDEN_TAGS = ['@returns', '@brief', '@details', '@author', '@since', '@todo', '@date', '@file', '@copyright', '@version']
+const FORBIDDEN_TAGS = ['@returns', '@details', '@author', '@since', '@todo', '@date', '@copyright', '@version']
 const BANNER = /^\/\/=+-+=+\/\/$/
+const DOXY_FILE = /^\/\/\/\s*@file\s+\S/
+const DOXY_BRIEF = /^\/\/\/\s*@brief\s+\S/
 const MEMBER_LIST = /提供[^。]{0,40}、[^。]{0,40}(的功能|的能力|的接口)|功能[:：]/
 const RATIONALE = /而不是|而非|代价.{0,4}忽略|只留一份|与其|比.{0,12}更|更(?:安全|快|清楚|直接|好写|难写)/
 const FORWARD_REF = /(?:留在|归|交给|由)\s*`?[A-Z][A-Za-z0-9_]*`?/
@@ -205,16 +207,29 @@ export function checkText(text, options = {}) {
   const inClass = classMemberLines(lines)
 
   const firstContent = lines.findIndex((line) => line.trim() !== '')
-  if (requireHeader && firstContent !== -1 && !BANNER.test(lines[firstContent].trim())) {
-    add(firstContent + 1, 'header-missing', '文件开头缺少文件头横幅（//===...===//）')
+  const firstTrimmed = firstContent === -1 ? '' : lines[firstContent].trim()
+  const hasDoxyHeader = DOXY_FILE.test(firstTrimmed)
+  let doxyHeaderEnd = -1
+  if (hasDoxyHeader) {
+    doxyHeaderEnd = firstContent
+    while (doxyHeaderEnd + 1 < lines.length && lines[doxyHeaderEnd + 1].trim().startsWith('///')) doxyHeaderEnd += 1
   }
-  if (firstContent !== -1 && BANNER.test(lines[firstContent].trim())) {
+  if (requireHeader && firstContent !== -1 && !BANNER.test(firstTrimmed) && !hasDoxyHeader) {
+    add(firstContent + 1, 'header-missing', '文件开头缺少文件头：写 /// @file <文件名>，下一行写 /// @brief')
+  }
+  if (firstContent !== -1 && (BANNER.test(firstTrimmed) || hasDoxyHeader)) {
     const own = options.fileName ? options.fileName.split(/[\\/]/).pop() : ''
+    const bannerHeader = BANNER.test(firstTrimmed)
+    if (hasDoxyHeader && !DOXY_BRIEF.test((lines[firstContent + 1] ?? '').trim())) {
+      add(firstContent + 2, 'header-brief', '文件头第二行缺少 /// @brief 一句话说明')
+    }
     for (let index = firstContent + 1; index < lines.length; index += 1) {
       const trimmed = lines[index].trim()
-      if (BANNER.test(trimmed) || !trimmed.startsWith('//')) break
+      if (bannerHeader ? BANNER.test(trimmed) || !trimmed.startsWith('//') : !trimmed.startsWith('///')) break
       const names = trimmed.match(/\b[A-Za-z0-9_-]+\.(?:h|hpp|cpp|cc)\b/g) ?? []
-      for (const name of names) {
+      const fileMatches = trimmed.match(/@file\s+(\S+)/)
+      const namesToCheck = fileMatches ? names.filter((name) => name !== fileMatches[1]) : names
+      for (const name of namesToCheck) {
         if (name !== own) add(index + 1, 'header-cross-file', `文件头提到了别的源文件 ${name}：只介绍本文件，删掉跨文件句子`)
       }
       if (/\bapps\//.test(trimmed)) add(index + 1, 'header-cross-file', '文件头指向了另一个目录：只介绍本文件')
@@ -238,6 +253,10 @@ export function checkText(text, options = {}) {
   }
 
   for (let index = 0; index < lines.length; index += 1) {
+    if (doxyHeaderEnd !== -1 && index <= doxyHeaderEnd) {
+      index = doxyHeaderEnd
+      continue
+    }
     if (!lines[index].trim().startsWith('///')) continue
     if (lines[index].trim().startsWith('///<')) continue
     const start = index