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

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

@@ -15,7 +15,7 @@
 | 命名空间 | snake_case | `taskflow`, `warehouse` | `Taskflow`, `Warehouse` |
 | 宏 | 全大写 + 项目前缀，尽量不用 | `CPP_WORKFLOW_ASSERT` | `ASSERT` |
 
-- 文件名用 snake_case：`order_result.h`、`task_table.cc`；测试文件 `task_table_test.cc`。
+- 文件名用 snake_case：`order_result.h`、`task_table.cpp`；测试文件 `task_table_test.cpp`。
 - 布尔变量用 `is_` / `has_` / `can_` 开头：`is_valid`、`has_stock`；不要用 `flag`、`status`。
 - 容器用复数：`tasks`、`orders`；单个元素用单数。
 - 缩写按单词处理：`url`、`id`、`http`，不要写 `URL` 混进 snake_case；类型名里可以 `HttpClient`。
@@ -26,7 +26,7 @@
 | 角色 | 前缀 / 动词 | 例子 | 说明 |
 | --- | --- | --- | --- |
 | 查询 | `Get` 或访问器风格 | `GetCurrentOrder()`、`CurrentOrder()` | 只读、不改变状态；同一 API 选一种 |
-| 判断 | `Is` / `Has` / `Can` | `Contains()`, `HasStock()` | 返回 `bool`，不抛异常 |
+| 判断 | `Is` / `Has` / `Can`；成对规则用 `Completes` 等限定式 | `IsEmpty()`、`HasStock()`、`CompletesLine()` | 返回 `bool`，不抛异常 |
 | 查找 | `Find` | `FindTask()` | 找不到是正常结果，返回 `optional` 或迭代器，不抛 |
 | 计数 | `Count` | `CountPendingTasks()` | 返回数量，不修改状态 |
 | 尝试 | `Try` | `TryReserve()` | 可能失败但不抛异常，返回结果类型 |
@@ -47,6 +47,7 @@
 ## 谓词与查询命名
 
 - 返回 `bool` 的查询用肯定式，读起来像一句断言：`IsEmpty()`、`HasStock()`、`CanReserve()`、`CompletesLine()`。
+- 前缀集就是这四类：`Is` / `Has` / `Can`，外加与成对规则一一对应的 `Completes`、`Would` 这类限定式；`Contains` 只保留给容器成员（`std::vector::empty` 一类已有标准名），不拿它当一般谓词。
 - `Get` 只用于取值，`Set` 只用于设值；不要用 `CheckLine()` 当布尔 getter。
 - `Check` / `Validate` 留给会报告错误、产生诊断或可能失败的操作；它们不返回纯 `bool` 查询。
 - 假设性查询在名字里写明条件：`CompletesLine(position, cell)` 读作「这一手会成线吗」；需要更强语气时用 `WouldCompleteLine()`。同一 API 只选一种，改名时同步声明、定义、调用点、测试和注释。

package/skills/developing-cpp/references/project-design.md

@@ -62,7 +62,7 @@
 - 平台变化（Windows/WSL/macOS 路径、动态库查找）放构建脚本或适配层，不进核心。
 - 测试需要替换的外部依赖（时钟、随机源、输入输出）通过接口注入，不在核心内部直接调用。
 
-公共头文件只暴露稳定契约；实现细节放 `.cc` 或私有头。一个组件一个 `CMakeLists.txt`，组件的 `include/` 是对外接口，`src/` 是实现。
+公共头文件只暴露稳定契约；实现细节放 `.cpp` 或私有头。一个组件一个 `CMakeLists.txt`，组件的 `include/` 是对外接口，`src/` 是实现。
 
 ## 什么时候抽共享库
 

package/skills/developing-cpp/references/standard-library.md

@@ -97,4 +97,4 @@ std::erase_if(values, [](int value) { return value % 2 == 0; });
 - [ ] 没有保存 `string_view` / `span` 指向的临时对象。
 - [ ] 修改容器大小前处理了迭代器失效。
 - [ ] 能用算法表达时没有手写下标循环。
-- [ ] 输出用 `std::format` 组合、流输出，没有 `std::print`。
+- [ ] 组合消息用 `std::format` 或流输出；`std::print` 只出现在 C++23 的程序边界，库代码没有。

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

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+// 只读注释审计：按 references/comments.md 的硬规则检查 C/C++ 源文件。
+//
+// 检查项：文件头横幅、横幅宽度、注释行宽度、Doxygen 标签、注释与声明的贴合、
+// 类型注释存在性、成员功能清单、设计论证（方案对比）、@param 完整性、枚举成员注释一致性。
+// 不重写任何文件。
+//
+// 用法：
+//   node checking-comments.mjs [--root DIR] [--width N] [--banner-width N] [--no-header] [--json] [--quiet]
+//
+// 退出码：0 无问题，1 发现问题，2 用法或读取错误。
+import { readdirSync, 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 SOURCE_EXT = new Set([
+  '.h', '.hh', '.hpp', '.hxx', '.h++', '.inl', '.ipp', '.tpp',
+  '.cpp', '.cc', '.cxx', '.c++', '.c', '.m', '.mm',
+])
+const HEADER_EXT = new Set(['.h', '.hh', '.hpp', '.hxx', '.h++', '.inl', '.ipp', '.tpp'])
+const SKIP_DIR = new Set([
+  '.git', '.hg', '.svn', 'build', 'out', 'node_modules', '_book', '.quarto', '.cache',
+  '.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 BANNER = /^\/\/=+-+=+\/\/$/
+const MEMBER_LIST = /提供[^。]{0,40}、[^。]{0,40}(的功能|的能力|的接口)|功能[:：]/
+const RATIONALE = /而不是|而非|代价.{0,4}忽略|只留一份|与其|比.{0,12}更|更(?:安全|快|清楚|直接|好写|难写)/
+const FORWARD_REF = /(?:留在|归|交给|由)\s*`?[A-Z][A-Za-z0-9_]*`?/
+const TYPE_SYSTEM = /值语义|自由拷贝/
+const DECL_KEYWORDS = /^(class|struct|union|enum|namespace|using|typedef|template|#|if|else|for|while|switch|return|case|default)\b/
+
+function usage(message) {
+  if (message) process.stderr.write(`错误：${message}\n`)
+  process.stderr.write('用法：node checking-comments.mjs [--root DIR] [--width N] [--banner-width N] [--no-header] [--json] [--quiet]\n')
+  return EXIT.usage
+}
+
+function parseArgs(argv) {
+  const options = { root: undefined, width: 80, bannerWidth: 80, requireHeader: true, 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 === '--width') {
+      options.width = Number(argv[index + 1])
+      index += 1
+    } else if (arg === '--banner-width') {
+      options.bannerWidth = Number(argv[index + 1])
+      index += 1
+    } else if (arg === '--no-header') {
+      options.requireHeader = false
+    } 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}`)
+    }
+  }
+  for (const key of ['width', 'bannerWidth']) {
+    if (!Number.isInteger(options[key]) || options[key] < 40) {
+      throw new Error(`--${key} 需要不小于 40 的整数`)
+    }
+  }
+  return options
+}
+
+/** 中文按两列计宽，用于判断渲染后的行宽。 */
+export function displayWidth(text) {
+  let width = 0
+  for (const char of text) {
+    const code = char.codePointAt(0)
+    const wide =
+      (code >= 0x1100 && code <= 0x115f) ||
+      (code >= 0x2e80 && code <= 0xa4cf) ||
+      (code >= 0xac00 && code <= 0xd7a3) ||
+      (code >= 0xf900 && code <= 0xfaff) ||
+      (code >= 0xfe30 && code <= 0xfe6f) ||
+      (code >= 0xff00 && code <= 0xff60) ||
+      (code >= 0xffe0 && code <= 0xffe6) ||
+      (code >= 0x1f300 && code <= 0x1f64f) ||
+      (code >= 0x20000 && code <= 0x3fffd)
+    width += wide ? 2 : 1
+  }
+  return width
+}
+
+/** 取出顶层逗号分隔的参数段，忽略模板与括号内的逗号。 */
+function splitParams(text) {
+  const parts = []
+  let depth = 0
+  let current = ''
+  for (const char of text) {
+    if (char === '<' || char === '(' || char === '[' || char === '{') depth += 1
+    if (char === '>' || char === ')' || char === ']' || char === '}') depth = Math.max(0, depth - 1)
+    if (char === ',' && depth === 0) {
+      parts.push(current)
+      current = ''
+      continue
+    }
+    current += char
+  }
+  if (current.trim() !== '') parts.push(current)
+  return parts.map((part) => part.trim()).filter((part) => part !== '' && part !== 'void')
+}
+
+/** 取参数名：去掉默认值、数组后缀、引用与指针，保留最后一个标识符。 */
+function paramName(part) {
+  let text = part
+  if (text.includes('=')) text = text.slice(0, text.indexOf('='))
+  text = text.replace(/\[[^\]]*\]/g, ' ').trim()
+  if (text === '...') return undefined
+  const tokens = text.match(/[A-Za-z_]\w*/g) ?? []
+  const last = tokens.at(-1)
+  if (!last) return undefined
+  if (['const', 'volatile', 'signed', 'unsigned', 'void'].includes(last)) return undefined
+  return last
+}
+
+/** 提取函数声明的参数名列表；不是函数声明时返回 undefined。 */
+export function functionParams(declaration) {
+  const decl = declaration.trim().replace(/^template\s*<[^>]*>\s*/, '')
+  if (DECL_KEYWORDS.test(decl)) return undefined
+  const open = decl.indexOf('(')
+  if (open === -1) return undefined
+  const namePart = decl.slice(0, open).trim()
+  if (!/[~A-Za-z_]\w*$|operator\W/.test(namePart)) return undefined
+  let depth = 0
+  let close = -1
+  for (let index = open; index < decl.length; index += 1) {
+    const char = decl[index]
+    if (char === '(') depth += 1
+    if (char === ')') {
+      depth -= 1
+      if (depth === 0) {
+        close = index
+        break
+      }
+    }
+  }
+  if (close === -1) return undefined
+  const tail = decl.slice(close + 1).trim()
+  if (tail !== '' && !/^[;{:]/.test(tail) && !/^(const|noexcept|override|final|->|=\s*(0|default|delete))/.test(tail)) {
+    return undefined
+  }
+  return splitParams(decl.slice(open + 1, close)).map(paramName).filter(Boolean)
+}
+
+/** 检查一段文本，返回问题列表；每个问题带 1 起始的行号。 */
+export function checkText(text, options = {}) {
+  const width = options.width ?? 80
+  const bannerWidth = options.bannerWidth ?? 80
+  const requireHeader = options.requireHeader ?? true
+  const lines = text.split(/\r?\n/)
+  const issues = []
+  const add = (line, rule, message) => issues.push({ line, rule, message })
+
+  const firstContent = lines.findIndex((line) => line.trim() !== '')
+  if (requireHeader && firstContent !== -1 && !BANNER.test(lines[firstContent].trim())) {
+    add(firstContent + 1, 'header-missing', '文件开头缺少文件头横幅（//===...===//）')
+  }
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]
+    const trimmed = line.trim()
+    if (BANNER.test(trimmed)) {
+      const actual = displayWidth(trimmed)
+      if (actual !== bannerWidth) add(index + 1, 'banner-width', `横幅宽度 ${actual} 列，应为 ${bannerWidth} 列`)
+      continue
+    }
+    if (trimmed.startsWith('///') || (trimmed.startsWith('//') && !trimmed.startsWith('//!'))) {
+      if (displayWidth(trimmed) > width) add(index + 1, 'comment-width', `注释行 ${displayWidth(trimmed)} 列，超过 ${width} 列`)
+      for (const tag of FORBIDDEN_TAGS) {
+        if (trimmed.includes(tag)) add(index + 1, 'forbidden-tag', `禁止使用 ${tag}，按 references/comments.md 的标签表改写`)
+      }
+    }
+  }
+
+  for (let index = 0; index < lines.length; index += 1) {
+    if (!lines[index].trim().startsWith('///')) continue
+    if (lines[index].trim().startsWith('///<')) continue
+    const start = index
+    let end = index
+    while (end + 1 < lines.length && lines[end + 1].trim().startsWith('///') && !lines[end + 1].trim().startsWith('///<')) {
+      end += 1
+    }
+    index = end
+    let next = end + 1
+    if (next < lines.length && lines[next].trim() === '') {
+      add(end + 1, 'doc-gap', '注释与声明之间有空行：注释会挂到下一个声明，请删掉空行')
+      while (next < lines.length && lines[next].trim() === '') next += 1
+    }
+    if (next >= lines.length) continue
+    const declaration = lines[next].trim()
+    const block = lines.slice(start, end + 1).join('\n')
+    const isType = /^(template\s*<[^>]*>\s*)?(class|struct|union|enum)\b/.test(declaration)
+    if (RATIONALE.test(block)) {
+      add(start + 1, 'rationale', '注释在写设计取舍：方案对比与理由移到正文或实现注释，接口注释只留契约')
+    }
+    if (isType && MEMBER_LIST.test(block)) {
+      add(start + 1, 'member-list', '类型注释在罗列成员功能，应改写为概念与使用约定')
+    }
+    if (isType && FORWARD_REF.test(block)) {
+      add(start + 1, 'forward-ref', '类型注释在交代别的类型负责什么：只写本类型的契约，跨文件边界留给文件头')
+    }
+    if (isType && TYPE_SYSTEM.test(block)) {
+      add(start + 1, 'type-system', '类型注释在复述类型系统已表达的性质：可拷贝与 const 查询由声明给出，删掉这句')
+    }
+    const params = functionParams(declaration)
+    if (!params) continue
+    const documented = [...block.matchAll(/@param(?:\[[^\]]*\])?\s+(\w+)/g)].map((match) => match[1])
+    if (documented.length === 0) continue
+    for (const name of params) {
+      if (!documented.includes(name)) add(start + 1, 'param-missing', `参数 ${name} 没有 @param 说明`)
+    }
+    for (const name of documented) {
+      if (!params.includes(name)) add(start + 1, 'param-extra', `@param ${name} 在声明里不存在`)
+    }
+  }
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const trimmed = lines[index].trim()
+    if (!/^(template\s*<[^>]*>\s*)?enum\b/.test(trimmed)) continue
+    let body = index
+    while (body < lines.length && !lines[body].includes('{')) body += 1
+    if (body >= lines.length) continue
+    let commented = 0
+    let bare = 0
+    for (let cursor = body + 1; cursor < lines.length; cursor += 1) {
+      const line = lines[cursor].trim()
+      if (line.startsWith('}')) break
+      if (line === '' || line.startsWith('//') || line.startsWith('#')) continue
+      const code = line.replace(/\/\/.*$/, '').trim()
+      if (/^[A-Za-z_]\w*\s*(=[^,]+)?,?$/.test(code)) {
+        if (line.includes('///<')) commented += 1
+        else bare += 1
+      }
+    }
+    if (commented > 0 && bare > 0) {
+      add(index + 1, 'enum-partial', '枚举成员注释需全写或全不写，当前只有部分成员有 ///<')
+    }
+    index = body
+  }
+
+  return issues.sort((left, right) => left.line - right.line)
+}
+
+/** 递归收集源文件，跳过生成目录与隐藏目录。 */
+export function collectFiles(root) {
+  const files = []
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory()) {
+        if (SKIP_DIR.has(entry.name.toLowerCase()) || entry.name.startsWith('.')) continue
+        walk(full)
+        continue
+      }
+      if (entry.isFile() && SOURCE_EXT.has(path.extname(entry.name).toLowerCase())) files.push(full)
+    }
+  }
+  if (statSync(root).isFile()) return [root]
+  walk(root)
+  return files.sort()
+}
+
+function main(argv) {
+  let options
+  try {
+    options = parseArgs(argv)
+  } catch (error) {
+    return usage(error.message)
+  }
+  if (options.help) return usage()
+  const root = options.root ? path.resolve(options.root) : process.cwd()
+  let files
+  try {
+    files = collectFiles(root)
+  } catch (error) {
+    return usage(`读取 ${root} 失败：${error.message}`)
+  }
+  const results = []
+  for (const file of files) {
+    let text
+    try {
+      text = readFileSync(file, 'utf8')
+    } catch (error) {
+      process.stderr.write(`错误：读取 ${file} 失败：${error.message}\n`)
+      return EXIT.usage
+    }
+    for (const issue of checkText(text, options)) results.push({ file: path.relative(root, file) || file, ...issue })
+  }
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify({ root, files: files.length, issues: results }, null, 2)}\n`)
+  } else if (results.length > 0) {
+    for (const issue of results) process.stdout.write(`${issue.file}:${issue.line}: [${issue.rule}] ${issue.message}\n`)
+    const touched = new Set(results.map((issue) => issue.file)).size
+    process.stdout.write(`发现 ${results.length} 处注释问题，涉及 ${touched} 个文件。\n`)
+  } else if (!options.quiet) {
+    process.stdout.write(`注释检查通过：${files.length} 个文件。\n`)
+  }
+  return results.length === 0 ? EXIT.ok : EXIT.issues
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  process.exitCode = main(process.argv.slice(2))
+}
+
+export { HEADER_EXT }

package/skills/developing-cpp/steps/01-behavior.md

@@ -16,7 +16,7 @@
 - 一次只定一个可验收的切片。切片太大就拆成两个行为句，分别走完四步。
 - 失败方式也要写：非法参数、空输入、越界、文件不存在时，是返回错误值、打印提示，还是抛异常。
 - 行为句不绑定实现。「用 `std::vector` 保存」是声明或实现的决定，不是行为。
-- 需要新增输出时，组合消息用 `std::format`；不要为了打印引入 C++23 的 `std::print`。
+- 需要新增输出时，组合消息用 `std::format`；`std::print` 只在 C++23 且是程序边界（`apps/`、`main`）时可用，库代码不直接打印。
 
 ## 情况
 

package/skills/developing-cpp/steps/02-boundary.md

@@ -6,7 +6,7 @@
 
 ```text
 <component>/include/<name>.h   公共接口
-<component>/src/<name>.cc     实现
+<component>/src/<name>.cpp     实现
 tests/                         测试
 app                            只做参数、输入输出和装配
 ```
@@ -16,7 +16,7 @@ app                            只做参数、输入输出和装配
 - 库 target 不依赖终端、GUI、网络脚本或全局单例；它只接收值、返回值、在无法完成任务时抛异常。
 - 程序 target 链接库，负责读参数、读标准输入、打印结果、把退出码翻译成进程退出码。
 - 公共头文件直接放在组件的 `include/` 下，从仓库根写完整路径包含，例如 `#include "task_list/include/task_list.h"`；不要写裸文件名或 `../` 相对路径。
-- 依赖方向从程序指向库。库不反向包含程序的 `cli.h`，也不引用 `main.cc`。
+- 依赖方向从程序指向库。库不反向包含程序的 `cli.h`，也不引用 `main.cpp`。
 - 测试放 `tests/`，测试 target 链接被测库；测试不复制库的实现。
 - 只有一个可执行文件、没有复用需求时，可以不分库；一旦出现第二个调用方或测试需要直接调用，再拆库。
 - 抽共享库前先确认第二个真实使用方和相同语义；只是“看起来会复用”不构成理由。抽象理由写进项目技能或设计注释。
@@ -25,11 +25,11 @@ app                            只做参数、输入输出和装配
 
 ## 情况
 
-**单文件程序**：`src/main.cc` 可以有 `main()` 和私有辅助函数；一旦辅助逻辑需要测试，把它移到库组件。
+**单文件程序**：`src/main.cpp` 可以有 `main()` 和私有辅助函数；一旦辅助逻辑需要测试，把它移到库组件。
 
 **领域核心 + 外围**：规则核心（状态、合法性、结果）只依赖标准和领域类型；终端、GUI、Web、脚本都在适配层。依赖方向从外向内，核心不知道适配层存在。
 
-**库 + 程序**：库放在 `<component>/`，程序放在 `app/` 或根 `src/main.cc`；程序只包含库的公共头。公共头只暴露稳定契约，实现细节放 `.cc` 或私有头。
+**库 + 程序**：库放在 `<component>/`，程序放在 `app/` 或根 `src/main.cpp`；程序只包含库的公共头。公共头只暴露稳定契约，实现细节放 `.cpp` 或私有头。
 
 **静态库 / 动态库**：接口相同，差别在链接方式和运行时库路径；都遵守「库不依赖终端」。选哪种由 `building-cpp` 的定构建决定。
 

package/skills/developing-cpp/steps/03-declaration.md

@@ -2,18 +2,18 @@
 
 ## 产出
 
-公共头文件、类型与函数声明、命名、声明顺序和声明注释。声明要能让调用方在不读 `.cc` 的情况下知道怎么用、什么时候失败。
+公共头文件、类型与函数声明、命名、声明顺序和声明注释。声明要能让调用方在不读 `.cpp` 的情况下知道怎么用、什么时候失败。
 
 ## 通用情况
 
-- 语言标准由项目声明决定，新工程默认 C++23，支持 C++11–C++23；头文件用 `#define` 守卫，名字由源码树全路径生成。
+- 语言标准由项目声明决定，新工程默认 C++23，支持 C++11–C++23；头文件用 `#define` 守卫，名字由源码树全路径生成，不要用 `#pragma once`。槽位与守卫名按 `references/file-template.md`。
 - 命名按 `references/naming.md`：类型与函数 PascalCase，变量与参数 snake_case，类成员尾随 `_`、结构体成员不尾随，常量与枚举子 `k` 前缀。布尔查询与 `Check` 的分工见同文件「谓词与查询命名」。
 - 声明顺序按 `references/declaration-order.md`：类型 → 静态常量 → 工厂 → 构造/赋值/析构 → 其他函数 → 数据成员。
 - 公共头文件自包含：自身需要的头都直接包含，不依赖调用方的包含顺序。
 - 单参数构造函数写 `explicit`；可查询的成员函数加 `[[nodiscard]]`；默认成员初始化写在声明处，不在构造函数里重复。
-- 头文件只就地定义大约 10 行以内的短函数；更长或需要完整定义的普通函数只在 `.cc` 定义，模板和 `constexpr` 例外。
+- 头文件只就地定义大约 10 行以内的短函数；更长或需要完整定义的普通函数只在 `.cpp` 定义，模板和 `constexpr` 例外。
 - 失败是调用方的正常结果时，用结果类型、`bool` + 输出参数或 `std::optional` 表达；函数无法完成自己的任务、或构造函数无法建立 invariant 时，才在声明注释里写清抛出的异常类型。判据见 `references/exceptions.md`。
-- 声明注释写契约：参数范围、返回值、失败方式、所有权。不要写实现步骤。
+- 声明注释按 `references/comments.md` 分四层写：文件头的范围与边界、类型注释的概念与使用约定、函数注释的承诺与契约、数据成员的行尾说明。类型注释不罗列成员功能、不写方案对比与设计论证；全项目的风格理由写进项目文档，不写进注释。
 - `std::format` 用于组合消息；声明里不要承诺 `std::print`（C++23）。
 
 ## 情况
@@ -24,7 +24,7 @@
 
 **异常声明**：构造函数、`Get` 类查询、解析函数最容易抛；在声明注释里写「当……时抛出 `TaskIndexError`」这样的具体类型，不要只写「可能抛异常」，也不要机械地写成 `std::invalid_argument` / `std::out_of_range`。类型选择见 `references/exceptions.md`。
 
-**注释**：声明注释用 `///`，只写调用方需要知道的；实现细节留给 `.cc`。文件头、章节横幅和 TODO 的格式见 `references/comments.md`。
+**注释**：声明注释用 `///` 写中文散文，只写调用方需要知道的；实现细节留给 `.cpp`。`@param`、`@return`、`@throws` 要么全写要么全不写，标识符和标签保持英文。写完运行 `node "<skill-dir>/scripts/checking-comments.mjs" --root <项目根>`，横幅、标签、参数完整性、成员清单与设计论证由脚本兜底。文件头、章节横幅和 TODO 的格式见 `references/comments.md`。
 
 ## 正反例指针
 

package/skills/developing-cpp/steps/04-implementation.md

@@ -2,14 +2,14 @@
 
 ## 产出
 
-`.cc` 中的函数体、操作顺序、分组空白和实现注释。实现只兑现第 1 步的行为和第 3 步的声明，不新增公共接口。
+`.cpp` 实现文件中的函数体、操作顺序、分组空白和实现注释。实现只兑现第 1 步的行为和第 3 步的声明，不新增公共接口。
 
 ## 通用情况
 
 - 函数保持短小；一个函数只做一件事。超过约 40 行时先找可以命名的中间步骤，不要用注释把长函数切成几段。
 - 按「准备 → 操作 → 收尾」排列语句，用空行分组；组与组之间的空行表达阶段，不用大段叙述。
-- `.cc` 第一个 include 是自己的配对头，然后直接包含本文件用到的标准库头；不要依赖公共头替本文件转发声明。包含顺序见 `references/google-cpp-style.md`。
-- 实现注释只写「为什么这样做」「这里的边界条件」「这样排序的代价」，不复述代码。
+- `.cpp` 的第一个 include 是自己的配对头，然后直接包含本文件用到的标准库头；不要依赖公共头替本文件转发声明。包含顺序见 `references/google-cpp-style.md`；文件槽位见 `references/file-template.md`。
+- 实现注释只写「为什么这样做」「这里的边界条件」「这样排序的代价」，1–3 行，放语句上方；不复述代码，不在 `if` 与 `else` 之间挂注释，记录变更史的内容留给提交说明。
 - 错误处理：失败是调用方正常结果时返回结果类型、`bool` 或 `std::optional`；函数无法完成自己的任务时抛异常，不拿异常做正常分支。捕获时按 `const` 引用，只处理能处理的类型，其余继续抛。
 - 组合输出用 `std::format`，再写入 `std::cout` / `std::cerr`；不要在库实现里直接打印。C++23 且库支持时程序边界可用 `std::print`，C++20 及更早没有。
 - 不写 C 风格强制转换；用 `static_cast` / `std::bit_cast` 等具名转换。