@chengzhao-dev/dsh-cpp-workflow 0.0.0-stage → 0.1.1

package/skills/developing-cpp/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: developing-cpp
+description: 编写或修改 C++20 源码、头文件、命名、异常与源码注释时使用；按定行为、定边界、定声明、定实现四步推进。不用于只改文档、Python、CMake、构建脚本或与 C++ 无关的文件。
+metadata:
+  short-description: C++20 源码四步
+---
+
+# developing-cpp
+
+## 适用场景
+
+管 `.h` / `.cpp` 里换一台机器也不会改的内容：可观察行为、库与程序的边界、声明、命名、异常和源码注释。`CMakeLists.txt`、`cmake/`、`running-build.sh`、`.clang-*`、`.vscode/` 和 `environment.json` 只开 `building-cpp`；两边都要动时，先做完第 2 步定边界，再开 `building-cpp`。`.qmd`、仓库 README、Python 和非 C++ 文档不打开本技能。
+
+存在项目技能 `cpp-workflow-project` 时先读它的 `SKILL.md`：工程名、库与程序的边界、阶段表、术语增补、入口命令。没有项目技能时门禁不会放出本技能，不要猜项目约定。
+
+## 两种走法
+
+| 走法 | 什么时候用 | 怎么做 |
+| --- | --- | --- |
+| 增量修正 | 用户点了一个函数、一条诊断或一个文件 | 沿本技能步骤走，只改判为不合格的那一处，其余保持原样 |
+| 整段重构 | 新工程、新阶段、用户没点名范围，或改动跨过库与程序的边界 | 同样四步；第 1、2 步先定删留，不动函数体；第 3、4 步才改代码 |
+
+共同不变量：不发明阶段表和用户请求里没有的行为、类型和命令；只改注释或格式时不改可观察行为；不覆盖已有源码；不安装工具链；代理侧不写 `wsl` 或 `bash -lc`。后一步发现前一步没做完，退回那一步，不在当前步补结构。拿不准先用增量修正；做到一半发现边界被打破，退回整段重构，从被打破的那一步重走。
+
+## 步骤
+
+| 步 | 名称 | 文件 | 一句话 |
+| --- | --- | --- | --- |
+| 1 | 定行为 | `steps/01-behavior.md` | 把这一处要能观察到的结果写成验收句 |
+| 2 | 定边界 | `steps/02-boundary.md` | 决定哪些放库、哪些放程序，依赖朝哪个方向 |
+| 3 | 定声明 | `steps/03-declaration.md` | 写命名、声明顺序、头文件契约和声明注释 |
+| 4 | 定实现 | `steps/04-implementation.md` | 写 `.cpp` 的操作顺序、分组和实现注释 |
+
+每步只打开同号的一个步骤文件。判不准才打开 `examples/` 里与该步对应的案例；`references/` 保存完整条文，只在排错、整目录重构，或步骤里明确指向某一条文时按需打开。
+
+## 完成判据
+
+- 第 1 步的行为句能被用户或测试验收；有阶段表时只覆盖对应行，没有时只覆盖用户点名的行为。
+- 第 2 步的库 target 不依赖终端、GUI 或脚本；程序 target 只做装配和输入输出；共享抽象有第二个真实使用方。
+- 第 3 步的公共头文件自包含，命名、声明顺序和异常合同符合 `references/` 的条文。
+- 第 4 步的实现只兑现声明；资源由 RAII 管理；可预期失败用返回值，合同违反才抛异常。
+- 没有改 `CMakeLists.txt`、`.clang-*`、构建脚本，也没有把外部资料路径或项目专属类名写进通用条文。

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

@@ -0,0 +1,231 @@
+# 正反例：注释
+
+## 文件头
+
+**差**：
+
+```cpp
+// task_list.cpp
+// 作者：张三
+// 创建：2024-01-01
+// 修改：2024-02-01 修复 bug
+```
+
+**好**：
+
+```cpp
+//===----------------------------------------------------------------------===//
+// TaskList 的存储、优先级排序与稳定顺序。
+//
+// 不处理终端输入输出；程序层负责解析「优先级 名称」并打印。
+//===----------------------------------------------------------------------===//
+```
+
+文件头回答「这个文件负责什么、不负责什么」，不写作者和变更史。
+
+## 声明注释
+
+**差**：
+
+```cpp
+/// 获取任务。
+/// @param index 索引
+/// @return 任务
+Task GetTask(int index) const;
+```
+
+问题：没说越界行为，没说返回的是拷贝还是引用。
+
+**好**：
+
+```cpp
+/// 返回 index 处的任务副本。
+///
+/// @param index 任务下标，必须在 [0, tasks_.size()) 内
+/// @return 该位置的任务
+/// @throws std::out_of_range index 越界
+[[nodiscard]] Task GetTask(int index) const;
+```
+
+契约完整：范围、返回、异常。
+
+## 实现注释
+
+**差**：
+
+```cpp
+// 如果 tasks_ 为空
+if (tasks_.empty()) {
+  // 返回空
+  return {};
+}
+// 遍历 tasks_
+for (const auto& task : tasks_) {
+  // 比较优先级
+  if (task.priority < best.priority) {
+    // 更新 best
+    best = task;
+  }
+}
+```
+
+每行都在复述代码。
+
+**好**：
+
+```cpp
+// 空列表是合法状态，调用方不应被迫先判空。
+if (tasks_.empty()) {
+  return {};
+}
+
+// 优先级相同时保留先加入的任务：用严格小于，不交换等值元素。
+for (const auto& task : tasks_) {
+  if (task.priority < best.priority) {
+    best = task;
+  }
+}
+```
+
+解释「为什么」和「稳定排序的取舍」，不翻译语句。
+
+## TODO
+
+**差**：
+
+```cpp
+// TODO: 参考 xxx
+// FIXME: 这里可能有问题
+// TODO(张三): 优化
+```
+
+**好**：
+
+```cpp
+// TODO: 阶段 2 - 支持按截止日期排序
+// TODO: issue #42 - 把优先级解析抽成 TryParsePriority
+```
+
+有定位、有动作、能搜索。
+
+## 配置注释
+
+**差**：
+
+```yaml
+# 这是 clang-format 配置
+# 详见某文档
+ColumnLimit: 100
+```
+
+**好**：
+
+```yaml
+# 100 列：模板和格式化串在 80 列下换行过碎。
+ColumnLimit: 100
+```
+
+解释取值理由，不写策略头，不指文档路径。
+
+## 横幅
+
+**差**：
+
+```cpp
+// ===== 函数 =====
+void AddTask();
+void RemoveTask();
+// ===== 结束 =====
+```
+
+**好**：
+
+```cpp
+//===----------------------------------------------------------------------===//
+// 查询
+//===----------------------------------------------------------------------===//
+
+[[nodiscard]] std::size_t Size() const;
+[[nodiscard]] bool IsEmpty() const;
+```
+
+横幅是跳转锚点，不是装饰；一组函数一个横幅，单函数不加。
+
+## 枚举行尾注释
+
+**差**：
+
+```cpp
+enum class TaskStatus : std::uint8_t {
+  kPending,  // 待处理
+  kActive,   // 处理中
+  kBlocked,  // 等待外部输入
+  kDone      // 已完成
+};
+```
+
+问题：四个成员都写等于没写，且把名字重复了一遍。
+
+**好**：
+
+```cpp
+enum class TaskStatus : std::uint8_t {
+  kPending,  ///< 已登记，尚未开始
+  kActive,   ///< 正在处理
+  kBlocked,  ///< 等待外部输入，不能继续
+  kDone      ///< 已完成，不再改动
+};
+```
+
+若只有部分成员需要解释，同一枚举内要写就写全，或全不写；不要半套。语义结果写在最前，判定条件放冒号后。
+
+## 声明注释的完整契约
+
+**差**：
+
+```cpp
+/// 修改任务优先级。
+/// @param id 任务编号
+/// @param priority 优先级
+void SetPriority(TaskId id, int priority);
+```
+
+**好**：
+
+```cpp
+/// 修改任务优先级。
+///
+/// @param id 任务编号，必须已存在
+/// @param priority 新优先级，必须在 [0, 9] 内
+/// @throws std::out_of_range 编号不在当前任务表内
+/// @throws std::invalid_argument priority 越界
+void SetPriority(TaskId id, int priority);
+```
+
+只写调用者无法从签名推出来的内容：范围、所有权、失败方式。`@brief` 不写，第一行就是摘要。
+
+## 相邻注释
+
+**差**：
+
+```cpp
+// 这里先检查存在性
+// 然后检查状态
+// 最后写入
+if (!Contains(id)) return false;
+if (tasks_[Index(id)].status == TaskStatus::kDone) return false;
+tasks_[Index(id)].status = TaskStatus::kActive;
+return true;
+```
+
+**好**：
+
+```cpp
+// 先检查再写入：失败时不留下半完成状态。
+if (!Contains(id)) return false;
+if (tasks_[Index(id)].status == TaskStatus::kDone) return false;
+tasks_[Index(id)].status = TaskStatus::kActive;
+return true;
+```
+
+一段连续的实现注释只讲一个判断或一个取舍；不是逐行字幕。

package/skills/developing-cpp/examples/exceptions.md

@@ -0,0 +1,134 @@
+# 正反例：异常
+
+## 抛还是返回
+
+**差**：用异常表达可预期的解析失败。
+
+```cpp
+Task ParseTask(std::string_view line);  // 格式错误时抛 std::runtime_error
+```
+
+调用方被迫用 `try/catch` 做正常分支，且无法从类型看出失败。
+
+**好**：结果类型表达可预期失败，合同违反才抛。
+
+```cpp
+enum class ParseError { kEmptyLine, kMissingPriority, kBadPriority };
+
+struct ParseResult {
+  std::optional<Task> task;
+  ParseError error = ParseError::kEmptyLine;
+};
+
+[[nodiscard]] ParseResult TryParseTask(std::string_view line);
+
+/// @throws std::out_of_range index 越界
+[[nodiscard]] Task GetTask(int index) const;
+```
+
+`TryParseTask` 的失败是调用方每天都要处理的；`GetTask` 越界是调用方违反合同。
+
+## 消息格式
+
+**差**：
+
+```cpp
+throw std::out_of_range("bad index");
+```
+
+**好**：
+
+```cpp
+throw std::out_of_range{
+    std::format("GetTask: index={} 超出 [0, {})", index, tasks_.size())};
+```
+
+消息含操作、关键值、期望范围；用 `std::format`，不拼字符串。
+
+## 边界
+
+**差**：每层都捕获并打印，异常被吞掉。
+
+```cpp
+void AddTask(Task task) {
+  try {
+    tasks_.push_back(task);
+  } catch (const std::exception& error) {
+    std::cout << error.what() << "\n";  // 库打印，且吞掉异常
+  }
+}
+```
+
+**好**：库让异常传播，入口统一翻译。
+
+```cpp
+// main.cpp
+int main() {
+  try {
+    return Run(std::cin, std::cout);
+  } catch (const std::exception& error) {
+    std::cerr << std::format("错误: {}\n", error.what());
+    return 1;
+  }
+}
+```
+
+## 捕获
+
+**差**：
+
+```cpp
+try {
+  Load(path);
+} catch (...) {
+  return;  // 不知道发生了什么，状态可能半坏
+}
+```
+
+**好**：
+
+```cpp
+try {
+  Load(path);
+} catch (const std::filesystem::filesystem_error& error) {
+  return LoadResult::kNotFound;
+}
+```
+
+只捕获能处理的类型；其他异常继续抛。
+
+## 析构
+
+**差**：
+
+```cpp
+~Writer() {
+  if (file_) file_->Flush();  // 失败时抛？析构中抛会终止程序
+}
+```
+
+**好**：
+
+```cpp
+~Writer() {
+  if (file_) {
+    file_->Flush();  // 忽略失败：析构不抛，错误由 Close() 报告
+  }
+}
+```
+
+需要报告关闭失败时，提供显式 `Close()` 返回结果，析构只做兜底。
+
+## `std::format` 与 `std::print`
+
+C++20 没有 `std::print`。不要写：
+
+```cpp
+std::print("任务: {}\n", task.name);  // C++23
+```
+
+写：
+
+```cpp
+std::cout << std::format("任务: {}\n", task.name);
+```

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

@@ -0,0 +1,157 @@
+# 正反例：命名
+
+## 基本规则
+
+| 差 | 好 | 原因 |
+| --- | --- | --- |
+| `class task_list` | `class TaskList` | 类型 PascalCase |
+| `void add_task()` | `void AddTask()` | 函数 PascalCase |
+| `int TaskCount` | `int task_count` | 变量 snake_case |
+| `std::vector<Task> Tasks` | `std::vector<Task> tasks_` | 成员 snake_case + `_` |
+| `constexpr int MAX = 10` | `constexpr int kMaxTasks = 10` | 常量 `k` 前缀 |
+| `enum class Color { Red }` | `enum class Color { kRed }` | 枚举子 `k` 前缀 |
+
+## 访问器
+
+**差**：
+
+```cpp
+Order current_order() const;   // 成员名直接当函数名
+void set_current_order(Order order);
+```
+
+**好**：
+
+```cpp
+[[nodiscard]] Order GetCurrentOrder() const;
+void AdvanceOrder();             // 领域动作，不是 setter
+```
+
+查询统一 `Get` + PascalCase；修改用领域动词。只有真正需要替换值时，才考虑 `Set` 形式，并说明为什么不是动作。
+
+## 语义角色
+
+**差**：
+
+```cpp
+bool Check(int id) const;                  // Check 什么？
+Result DoSomething(Task task);            // 做什么？
+TaskState To(TaskState state);            // 从什么到什么？
+```
+
+**好**：
+
+```cpp
+[[nodiscard]] bool Contains(int id) const;
+[[nodiscard]] ParseResult TryParse(std::string_view text);
+[[nodiscard]] TaskState StatusCodeToTaskState(int code);
+```
+
+- 判断用 `Is` / `Has`。
+- 可能失败但不抛用 `Try`。
+- 映射名字含两端角色。
+
+## `current_` 前缀
+
+**差**：
+
+```cpp
+Order current_order_;   // 只有一个订单时，current 是噪音
+```
+
+**好**：
+
+```cpp
+Order order_;
+```
+
+**该用**：
+
+```cpp
+Order current_order_;   // 有 current_order_ 与 next_order_，不写会混
+```
+
+## 名字与职责
+
+**差**：
+
+```cpp
+class DataManager {};     // 管什么？
+class StringHelper {};    // 为什么是类？
+```
+
+**好**：
+
+```cpp
+class Warehouse {};       // 持有库存，维持不变量
+namespace string_utils {  // 一组自由函数
+[[nodiscard]] std::string Trim(std::string_view text);
+}
+```
+
+避免 `Manager`、`Helper`、`Util`；名字要能回答「它负责什么」。一组无状态函数用命名空间，不要造类。
+
+## 查找与读取
+
+**差**：
+
+```cpp
+[[nodiscard]] Task GetTask(std::string_view name) const;  // 可能找不到时返回什么？
+[[nodiscard]] bool FindTask(std::string_view name) const; // 返回 bool 却叫 Find
+```
+
+**好**：
+
+```cpp
+[[nodiscard]] const Task& GetTask(std::string_view name) const;  // 找不到抛 out_of_range
+[[nodiscard]] const Task* FindTask(std::string_view name) const; // 找不到返回 nullptr
+[[nodiscard]] bool HasTask(std::string_view name) const;         // 只回答存在性
+```
+
+`Get` 表示结果一定存在（或按合同失败），`Find` 表示可能找不到，`Has` / `Contains` 只回答是否存在。不要用 `Find` 返回 `bool`。
+
+## 谓词与 Lambda
+
+**差**：
+
+```cpp
+bool valid(int value);
+auto check = [](const Task& task) { return task.done; };
+```
+
+**好**：
+
+```cpp
+[[nodiscard]] bool IsValid(int value);
+auto is_done = [](const Task& task) { return task.done; };
+auto has_owner = [](const Task& task) { return !task.owner.empty(); };
+```
+
+返回 `bool` 的自由函数用 `Is` / `Has` / `Can` / `Should` 开头；Lambda 用 snake_case 的 `is_` / `has_` / `can_`，读起来像条件。
+
+## 多返回值
+
+**差**：
+
+```cpp
+bool Parse(std::string_view text, int* out_value);   // 出参 + 返回 bool
+```
+
+**好**：
+
+```cpp
+struct ParseResult {
+  bool ok{false};
+  int value{0};
+};
+
+[[nodiscard]] ParseResult TryParse(std::string_view text);
+```
+
+需要同时表达成功与结果时，用带字段的结构体或 `std::optional`，不要用输出参数加布尔返回。
+
+## 改名检查
+
+- 搜全部调用点：声明、定义、测试、注释、文档。
+- 先改声明，再改定义，再改调用点；每一步都能编译。
+- 公共 API 改名保留旧名转发时，注释写弃用期限；不要静默删除。

package/skills/developing-cpp/examples/structure.md

@@ -0,0 +1,79 @@
+# 正反例：行为与边界
+
+## 行为句
+
+**差**：实现一个 `TaskList` 类，用 `std::vector` 保存任务，支持添加、删除、按优先级排序，并在终端打印表格。
+
+问题：把类型、容器、实现步骤混进行为；无法验收「表格」长什么样。
+
+**好**：
+
+```text
+给定一组任务（每行「优先级 名称」），程序按优先级从高到低输出名称；
+输入为空时输出「没有任务」并返回 0；某行格式非法时输出行号并返回 1。
+```
+
+可以写成测试：输入三行，断言输出顺序；输入空，断言提示与退出码；输入坏行，断言行号。
+
+## 边界
+
+**差**：库函数直接打印，程序只调用它。
+
+```cpp
+// task_list.cpp（库）
+void TaskList::Print() const {
+  for (const auto& task : tasks_) {
+    std::cout << task.priority << " " << task.name << "\n";
+  }
+}
+```
+
+问题：库依赖终端，测试要捕获 `std::cout`，GUI 或文件输出无法复用。
+
+**好**：库返回数据，程序决定怎么显示。
+
+```cpp
+// task_list.h（库）
+[[nodiscard]] std::vector<Task> SortedByPriority() const;
+
+// app/cli.cpp（程序）
+void PrintTasks(const std::vector<Task>& tasks, std::ostream& out) {
+  for (const auto& task : tasks) {
+    out << std::format("{} {}\n", task.priority, task.name);
+  }
+}
+```
+
+测试直接断言 `SortedByPriority()`；输出格式由程序测试负责。
+
+## 头文件位置
+
+**差**：
+
+```cpp
+#include "task_list/task_list.h"   // 公共根下又套一层组件名
+```
+
+```text
+src/task_list.h                  // 公共头藏在 src，测试无法只依赖公共接口
+```
+
+**好**：
+
+```text
+task_list/include/task_list.h    // 公共头
+task_list/src/task_list.cpp      // 实现
+task_list/src/detail.h           // 私有头，只被本组件包含
+```
+
+```cpp
+#include "task_list.h"           // 相对公共 include 根
+```
+
+## 单文件何时拆库
+
+**先不拆**：一个 `main.cpp`，辅助函数在匿名命名空间，只有程序自己用。
+
+**该拆**：测试需要直接调用排序逻辑；或第二个程序要复用同一逻辑；或逻辑已经超过一个屏幕。
+
+拆的时候先定公共头（只暴露 `SortedByPriority`），把实现移到 `src/`，行为句不变，测试先绿再改构建。