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

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

@@ -23,7 +23,7 @@
 - 状态用连续取值的 `enum class`：`kPending`、`kActive`、`kDone`。
 - 状态转换写成显式函数或规则对象，不用一串 `if` 直接改整数。
 - “动作是否合法”和“动作执行结果”分开：合法性查询返回 `bool` 或原因，执行返回结果对象。
-- 可预期失败（编号不存在、输入格式不对）用返回值表达；违反合同（下标越界、状态机不可能分支）才抛异常。
+- 失败是调用方的正常结果（编号不存在、输入格式不对）时用返回值表达；函数无法完成自己的任务、或状态机进入不可能分支时抛异常，规则见 `references/exceptions.md`。
 - 结果对象携带足够信息让调用方决定下一步，不要只返回 `bool` 再让调用方猜原因。
 
 ## 规则核心与外围
@@ -53,7 +53,7 @@
 - 平台变化（Windows/WSL/macOS 路径、动态库查找）放构建脚本或适配层，不进核心。
 - 测试需要替换的外部依赖（时钟、随机源、输入输出）通过接口注入，不在核心内部直接调用。
 
-公共头文件只暴露稳定契约；实现细节放 `.cpp` 或私有头。一个组件一个 `CMakeLists.txt`，组件的 `include/` 是对外接口，`src/` 是实现。
+公共头文件只暴露稳定契约；实现细节放 `.cc` 或私有头。一个组件一个 `CMakeLists.txt`，组件的 `include/` 是对外接口，`src/` 是实现。
 
 ## 什么时候抽共享库
 
@@ -73,7 +73,7 @@
 
 - [ ] 领域值有明确类型，封闭集合用 `enum class`。
 - [ ] 规则核心不依赖终端、GUI、Web、Python 或当前环境。
-- [ ] 可预期失败用返回值，合同违反才抛异常。
+- [ ] 失败是正常结果时用返回值，函数无法完成任务时抛异常；异常类型和捕获方式符合 `references/exceptions.md`。
 - [ ] 边界按变化原因划分，依赖方向从外向内。
 - [ ] 共享抽象有第二个真实使用方和明确理由。
 - [ ] 规则歧义已问清或记录了保守假设。

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

@@ -77,7 +77,7 @@ std::erase_if(values, [](int value) { return value % 2 == 0; });
 ## `std::format` 与输出
 
 - 组合消息优先 `std::format`；它返回 `std::string`，不直接写流。
-- 输出仍走 `std::cout` / `std::cerr` / 项目传入的 `std::ostream&`；C++20 没有 `std::print`。
+- 输出仍走 `std::cout` / `std::cerr` / 项目传入的 `std::ostream&`；C++23 且库支持时程序边界可用 `std::print`，C++20 及更早没有。
 - 格式串里的 `{}` 按顺序取参数；需要位置时写 `{0}`、`{1}`。
 - 自定义类型要格式化时，特化 `std::formatter<T>`；不要在 `operator<<` 里塞业务格式。
 - 浮点默认格式可能与预期不同；需要固定精度时写 `{:.2f}`，需要科学计数时写 `{:e}`。

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

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

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

@@ -2,16 +2,17 @@
 
 ## 产出
 
-公共头文件、类型与函数声明、命名、声明顺序和声明注释。声明要能让调用方在不读 `.cpp` 的情况下知道怎么用、什么时候失败。
+公共头文件、类型与函数声明、命名、声明顺序和声明注释。声明要能让调用方在不读 `.cc` 的情况下知道怎么用、什么时候失败。
 
 ## 通用情况
 
-- 语言固定 C++20，不使用 C++23 特性；头文件用 `#pragma once`。
-- 命名按 `references/naming.md`：类型与函数 PascalCase，变量与参数 snake_case，类成员尾随 `_`，常量与枚举子 `k` 前缀。
+- 语言标准由项目声明决定，新工程默认 C++23，支持 C++11–C++23；头文件用 `#define` 守卫，名字由源码树全路径生成。
+- 命名按 `references/naming.md`：类型与函数 PascalCase，变量与参数 snake_case，类成员尾随 `_`、结构体成员不尾随，常量与枚举子 `k` 前缀。
 - 声明顺序按 `references/declaration-order.md`：类型 → 静态常量 → 工厂 → 构造/赋值/析构 → 其他函数 → 数据成员。
 - 公共头文件自包含：自身需要的头都直接包含，不依赖调用方的包含顺序。
 - 单参数构造函数写 `explicit`；可查询的成员函数加 `[[nodiscard]]`；默认成员初始化写在声明处，不在构造函数里重复。
-- 可预期的失败用返回值表达（结果类型、`bool` + 输出参数、`std::optional`）；合同违反才在声明注释里写清抛出的异常类型。
+- 头文件只就地定义大约 10 行以内的短函数；更长或需要完整定义的普通函数只在 `.cc` 定义，模板和 `constexpr` 例外。
+- 失败是调用方的正常结果时，用结果类型、`bool` + 输出参数或 `std::optional` 表达；函数无法完成自己的任务、或构造函数无法建立 invariant 时，才在声明注释里写清抛出的异常类型。判据见 `references/exceptions.md`。
 - 声明注释写契约：参数范围、返回值、失败方式、所有权。不要写实现步骤。
 - `std::format` 用于组合消息；声明里不要承诺 `std::print`（C++23）。
 
@@ -19,14 +20,14 @@
 
 **新增类型**：先判断是聚合 `struct`、有不变量的 `class`，还是 `enum class`；接口多于数据且有 invariant 时用 `class`，纯数据传递用 `struct`。
 
-**改公共接口**：先找所有调用方；改签名、改返回类型、改异常合同都算破坏性变更。能加默认参数或重载时优先加，不要静默改变旧调用的含义。
+**改公共接口**：先找所有调用方；改签名、改返回类型、改异常声明都算破坏性变更。能加默认参数或重载时优先加，不要静默改变旧调用的含义。
 
-**异常合同**：构造函数、`Get` 类查询、解析函数最容易违反合同；在声明注释里写「当……时抛出 `std::invalid_argument` / `std::out_of_range`」，不要只写「可能抛异常」。
+**异常声明**：构造函数、`Get` 类查询、解析函数最容易抛；在声明注释里写「当……时抛出 `TaskIndexError`」这样的具体类型，不要只写「可能抛异常」，也不要机械地写成 `std::invalid_argument` / `std::out_of_range`。类型选择见 `references/exceptions.md`。
 
-**注释**：声明注释用 `///`，只写调用方需要知道的；实现细节留给 `.cpp`。文件头、章节横幅和 TODO 的格式见 `references/comments.md`。
+**注释**：声明注释用 `///`，只写调用方需要知道的；实现细节留给 `.cc`。文件头、章节横幅和 TODO 的格式见 `references/comments.md`。
 
 ## 正反例指针
 
 - 命名、访问器、语义角色：`examples/naming.md`。
-- 异常合同与返回值选择：`examples/exceptions.md`。
+- 异常声明与返回值选择：`examples/exceptions.md`。
 - 声明注释写成了实现说明：`examples/comments.md`「声明注释」。

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

@@ -2,16 +2,16 @@
 
 ## 产出
 
-`.cpp` 中的函数体、操作顺序、分组空白和实现注释。实现只兑现第 1 步的行为和第 3 步的声明，不新增公共接口。
+`.cc` 中的函数体、操作顺序、分组空白和实现注释。实现只兑现第 1 步的行为和第 3 步的声明，不新增公共接口。
 
 ## 通用情况
 
 - 函数保持短小；一个函数只做一件事。超过约 40 行时先找可以命名的中间步骤，不要用注释把长函数切成几段。
 - 按「准备 → 操作 → 收尾」排列语句，用空行分组；组与组之间的空行表达阶段，不用大段叙述。
-- `.cpp` 第一个 include 是自己的配对头，然后直接包含本文件用到的标准库头；不要依赖公共头替本文件转发声明。若所用 clang-tidy 版本带 `misc-include-cleaner`，这类缺失会被报出来。
+- `.cc` 第一个 include 是自己的配对头，然后直接包含本文件用到的标准库头；不要依赖公共头替本文件转发声明。包含顺序见 `references/google-cpp-style.md`。
 - 实现注释只写「为什么这样做」「这里的边界条件」「这样排序的代价」，不复述代码。
-- 错误处理：可预期失败返回结果类型；合同违反抛异常。捕获异常时按 `const` 引用捕获，只处理能处理的类型，其余继续抛。
-- 组合输出用 `std::format`，再写入 `std::cout` / `std::cerr`；不要在库实现里直接打印。C++20 没有 `std::print`。
+- 错误处理：失败是调用方正常结果时返回结果类型、`bool` 或 `std::optional`；函数无法完成自己的任务时抛异常，不拿异常做正常分支。捕获时按 `const` 引用，只处理能处理的类型，其余继续抛。
+- 组合输出用 `std::format`，再写入 `std::cout` / `std::cerr`；不要在库实现里直接打印。C++23 且库支持时程序边界可用 `std::print`，C++20 及更早没有。
 - 不写 C 风格强制转换；用 `static_cast` / `std::bit_cast` 等具名转换。
 - 所有权用 `std::unique_ptr`；没有共享所有权的理由时不用 `std::shared_ptr`。
 - 只改注释时，不改可观察行为；只改实现时，不改公共声明。两者同时需要时，先改声明，再改实现。
@@ -24,10 +24,14 @@
 
 **重构**：一次只动一种东西（改名、抽函数、换容器）。每步都让测试保持绿色；行为句不变。
 
-**异常边界**：库内部可以让合同异常向上传播；程序入口捕获 `std::exception`，用 `std::format("错误: {}", error.what())` 打印，返回非零退出码。不要吞掉异常后继续用无效状态。
+**异常边界**：库内部让异常向上传播；程序入口捕获 `std::exception`，用 `std::format("错误: {}", error.what())` 打印，返回项目约定的非零退出码。不要吞掉异常后继续用无效状态。
+
+## 交回构建
+
+要补测试、新增或移动源文件时，交给 `building-cpp` 的定构建：把文件显式写进 CMake，再决定是否定工具配置，最后通过检查。不要只改完函数体就宣称完成。
 
 ## 正反例指针
 
 - 实现注释复述代码、分组混乱：`examples/comments.md`「实现注释」。
-- 合同异常与结果类型混用：`examples/exceptions.md`「抛还是返回」。
-- `std::format` 与流输出混用得当：`examples/exceptions.md`「消息格式」。
+- 异常类型与结果类型混用：`examples/exceptions.md`「什么时候抛」。
+- `std::format` 与流输出混用得当：`examples/exceptions.md`「异常类型与消息」。

package/templates/cpp-workflow-project/SKILL.md

@@ -18,7 +18,7 @@ metadata:
 | 组件名 | `<component-name>` |
 | 源码根 | `<src-root>` |
 
-同目录的 `environment.json` 三个轴必须填本工程的真实组合；留空时技能仍可能出现，但定构建会停。
+同目录的 `environment.json` 三个环境轴必须填本工程的真实组合；`standard` 默认 `c++23`，可改成 `c++11`–`c++23`。环境轴留空时技能仍可能出现，但定构建会停。
 
 ## 库与程序的边界
 

package/templates/cpp-workflow-project/environment.json

@@ -1,5 +1,6 @@
 {
   "host": "",
   "build_host": "",
-  "compiler": ""
+  "compiler": "",
+  "standard": "c++23"
 }

package/skills/building-cpp/assets/templates/projects/multi/src/greeting.cpp

@@ -1,13 +0,0 @@
-#include "greeting.h"
-
-#include <format>
-#include <string>
-#include <string_view>
-
-namespace greeting {
-
-std::string MakeGreeting(std::string_view name) {
-  return std::format("Hello, {}!", name);
-}
-
-}  // namespace greeting

package/skills/building-cpp/assets/templates/projects/multi/src/main.cpp

@@ -1,8 +0,0 @@
-#include <iostream>
-
-#include "greeting.h"
-
-int main() {
-  std::cout << greeting::MakeGreeting("C++20") << '\n';
-  return 0;
-}

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

@@ -1,13 +0,0 @@
-#include "greeting.h"
-
-#include <format>
-#include <string>
-#include <string_view>
-
-namespace greeting {
-
-std::string MakeGreeting(std::string_view name) {
-  return std::format("Hello, {}!", name);
-}
-
-}  // namespace greeting

package/skills/building-cpp/assets/templates/projects/shared-library/src/main.cpp

@@ -1,8 +0,0 @@
-#include <iostream>
-
-#include "greeting.h"
-
-int main() {
-  std::cout << greeting::MakeGreeting("C++20") << '\n';
-  return 0;
-}

package/skills/building-cpp/assets/templates/projects/single/src/main.cpp

@@ -1,9 +0,0 @@
-#include <format>
-#include <iostream>
-#include <string>
-
-int main() {
-  const std::string name = "C++20";
-  std::cout << std::format("Hello, {}!\n", name);
-  return 0;
-}

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

@@ -1,13 +0,0 @@
-#include "greeting.h"
-
-#include <format>
-#include <string>
-#include <string_view>
-
-namespace greeting {
-
-std::string MakeGreeting(std::string_view name) {
-  return std::format("Hello, {}!", name);
-}
-
-}  // namespace greeting

package/skills/building-cpp/assets/templates/projects/static-library/src/main.cpp

@@ -1,8 +0,0 @@
-#include <iostream>
-
-#include "greeting.h"
-
-int main() {
-  std::cout << greeting::MakeGreeting("C++20") << '\n';
-  return 0;
-}