# @chengzhao-dev/dsh-cpp-workflow 中文文档

规范地址：https://npmcn.com/package/%40chengzhao-dev/dsh-cpp-workflow/

版本：0\.7\.4
npm 元数据更新时间：2026-11-09T04:55:41.277Z
中文译文更新时间：2026-11-09T12:14:04.204Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40chengzhao-dev/dsh-cpp-workflow
原文对照：https://npmcn.com/package/%40chengzhao-dev/dsh-cpp-workflow/?lang=original
项目主页：https://github.com/chengzhao-dev/dsh-cpp-workflow#readme
源码仓库：https://github.com/chengzhao-dev/dsh-cpp-workflow

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：661 kB，182 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：1 个
- peer 依赖：@deepseek-ai/dsh-skill \>=0\.2\.1-rc\.1 \<0\.3\.0-0
- 首次发布：2026-10-21T08:34:20.718Z
- 最新版本发布：2026-11-09T04:55:40.962Z
- 近 30 天下载量：5626（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：34（近 12 个月 34 个）

## 中文简介

写 C++ 源码、配 CMake、用 Clang 构建；头文件用 /// Doxygen 文档注释，函数体用 // 分段说明，文件头标签可在设置里改。

## 安装

```sh
npm install @chengzhao-dev/dsh-cpp-workflow
```

也可以使用：`pnpm add @chengzhao-dev/dsh-cpp-workflow`、`yarn add @chengzhao-dev/dsh-cpp-workflow`、`bun add @chengzhao-dev/dsh-cpp-workflow`

## README

# dsh-cpp-workflow

[English](https://npmcn.com/package/%40chengzhao-dev/dsh-cpp-workflow/README.en.md)

把 C++11–C++23 的源码、CMake 与构建工作整理成三个技能，新工程默认 C++23。插件注册技能 provider 与设置面，不注册工具、不编译、不下载工具链、不写项目文件；运行时不建缓存、不写临时文件，设置由宿主保存。

## 提供什么

| 技能 | 管什么 | 什么时候打开 |
| --- | --- | --- |
| `developing-cpp` | 定行为、定边界、定声明、定实现；`.h` / `.cpp` / `.cc` 的命名、异常和源码注释 | 用户点名源码，或需要新建/整段重构源码 |
| `engineering` | 定 target、定模块、通过检查；CMakeLists.txt、`cmake/` 函数与模块、target 属性、C++11–C++23 标准，以及 `.clang-format`/`.clang-tidy`/`.clangd` 的配置条文 | 改动落在 CMake target、标准、链接边界、函数或模块，或落在编码与 clang 工具配置上 |
| `building-cpp` | 定构建、定工具配置、通过检查；Ninja、Clang 配置、构建脚本、环境组合、排版工具的配置与检查 | 改动落在构建命令、工具配置或环境声明上，或第一次接构建 |

异常条文采用 C++ Core Guidelines 的 Error handling，只在开发阶段指导源码和示例；插件运行时不编译、不执行这些规则。三个技能都先读项目技能 `cpp-workflow-project`。没有项目技能时，门禁不会列出这三个技能。

## 安装

npm 安装固定版本：

```bash
dsh plugin --profile <profile> add npm:@chengzhao-dev/dsh-cpp-workflow@0.7.1
```

npm 当前最新发布是 `0.7.1`；仓库工作区里的 `0.7.4` 尚未发布，发布前请用上面的 0.7.1。`0.7.3` 已跳过、不再发布。工作区版本发布后，把 npm 命令换成：

```bash
dsh plugin --profile <profile> add npm:@chengzhao-dev/dsh-cpp-workflow@0.7.4
```

GitHub 标签安装要等 `v0.7.4` 创建后再用；标签创建后，地址中的版本号与标签同号：

```bash
dsh plugin --profile <profile> add github:chengzhao-dev/dsh-cpp-workflow#v0.7.4
```

`--profile` 换成你实际运行的那个 profile。桌面应用固定跑 `desktop` profile，且该 profile 由应用独占管理；命令行 `add` 被拒绝时，在应用设置里添加插件，地址填同一个 npm 版本。Git 标签安装使用仓库内已构建的 `lib/`，不在目标机器上重新构建；包内也不含需要授权执行的安装脚本。

### 设置

插件页的「C++ 工程流程」是唯一入口：注释符号可选 `///` 或 `/** ... */`，页面按注释符号、文件头、类型、函数声明与只读预览分块。`@file` 固定为文件名；除它和函数体 `//` 外，文件头、类型与函数声明标签的开关出厂全开，空值跳过。函数参数要求 `@param`，返回值要求 `@return`（成立条件自明时可省），会抛才要求 `@throws`；`@pre`、`@post`、`@retval` 与类型块的 `@tparam`、`@note`、`@see` 也出厂开启，需要时可逐项关掉。函数体固定用 `//`。预览随改动即时更新，保存后下一次读取技能即生效，已有源码不会被改写。插件页不再重复列一份导航。

升级插件后如果这一页暂时只显示出厂值，说明当前窗口还挂着旧的前端产物：重启 DeepSeek Harness，或在插件页点“重新载入页面”即可编辑，不需要重装插件。页面会在打开后自动重试连接，拿到表单就切换为可编辑；保存成功后，状态行会显示写入的 `~/.dsh/profiles/<profile>/cordis.patch.yml`。保存、撤销修改与恢复默认值分三个按钮：撤销只回到最近一次读到的值，恢复默认值只填草稿，点保存才写盘。

## 工作区门禁

会话满足一个条件，技能就会出现：从当前目录向上、停在 git 根，沿途有 `.agents/skills/cpp-workflow-project/SKILL.md`。

项目技能标记就是仓库选择加入本工作流的声明。插件不再要求同一仓库里已经有第一方 `CMakeLists.txt` 或 C++ 源文件：纯文档仓库、只复制了模板、还没有任何源文件的仓库也会出现；环境轴为空时，源码四步仍能做，但定构建会停。没有标记就返回空列表，即使仓库里有 CMake 或 `.cpp`。扫描上限和边界情形见 [docs/plugin-boundaries.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-boundaries.md)。

插件技能 rank 550。项目自己的 `.agents/skills` 技能 rank 200、用户级技能 rank 500，两者都会以同名覆盖插件；不要在项目或用户目录里复制 `developing-cpp`、`engineering` 或 `building-cpp`。

## 项目级约定

把 [templates/cpp-workflow-project](https://npmcn.com/package/%40chengzhao-dev/dsh-cpp-workflow/templates/cpp-workflow-project) 整个复制到目标仓库的 `.agents/skills/` 下，目录名保持 `cpp-workflow-project`；只补还不存在的文件，不覆盖已有的源码、`CMakeLists.txt` 或 `.clang-*`。项目技能写本工程特有的事实；通用工作流、编辑器与完成判据由模板的「通用工作流约定」承担，不在项目技能里重复：

-   工程名、组件名和源码根；
-   库与程序的边界、公共头位置；
-   从仓库根能直接运行的入口命令；
-   阶段表路径和术语增补。

`environment.json` 一个仓库只有一份。模板里的前三个环境轴故意留空，`standard` 预置为 `c++23`；复制后把环境轴填成工程的真实组合，需要旧标准时再改 `standard`。环境轴留空时源码四步仍能做，但定构建会停。阶段表只写可观察行为，不写内部重构。

## 环境组合

| 轴 | 允许值 | 说明 |
| --- | --- | --- |
| `host` | `windows`、`linux`、`macos` | 编辑器和代理壳在哪 |
| `build_host` | `native`、`wsl` | `wsl` 只在 `host=windows` 时合法 |
| `compiler` | `clang`、`gcc` | 一次配置一个编译器 |
| `standard` | `c++11`、`c++14`、`c++17`、`c++20`、`c++23` | 新工程默认 `c++23`；一个工程一个标准 |

标准写在 `environment.json` 的 `standard`，并同步到 CMake target 和编译数据库；CMake 侧优先调用 `engineering` 提供的 `CompileSettings_SetCxxStandard` 函数。新工程默认 C++23；C++11–C++20 工程把 `standard`、`cxx_std_*`、`CXX_STANDARD` 和 `.clang-format` 的解析档位一起降级，不要只改一处。每档的设施、工具和降档表见 [标准目录](https://npmcn.com/package/%40chengzhao-dev/dsh-cpp-workflow/skills/engineering/references/cmake/standards/index.md)，CMake 两层声明见 [01-cxx-standard.md](https://npmcn.com/package/%40chengzhao-dev/dsh-cpp-workflow/skills/engineering/references/cmake/standards/01-cxx-standard.md)。

生成器固定 Ninja，构建目录是 `build/clang/` 与 `build/gcc/`，不共用 `build/`。诊断工具固定 `clang-format`、`clang-tidy`、`clangd`；GCC 模式也不换成别的分析器。

构建前先跑声明校验，再在构建宿主上跑活动校验。`<skill-dir>` 是插件安装后的 `building-cpp` 目录，不是目标工程里的目录：

```bash
node "<skill-dir>/scripts/checking-environment.mjs" --project .
node "<skill-dir>/scripts/checking-environment.mjs" --project . --live
```

`windows + native` 在本版本中不是合法组合：声明校验直接返回 `ok: false`，`issues` 只有一句「本版本不能在 Windows 原生壳里构建」。停在这里，不要补 PowerShell 脚本，也不要靠改声明绕过。环境脚本不安装、不下载、不改 PATH。

工程根只带 `.vscode/extensions.json` 和 `settings.json`：推荐 clangd（编辑、补全、格式化）、CMake Tools（唯一的配置、构建、运行和调试入口）与 C/C++ 扩展（只作为 CMake 快速调试的后端）。不提供 `tasks.json` 或 `launch.json`，不维护第二套构建或启动路径。Windows 上用 Remote - WSL 打开工程根；在 CMake 侧栏选中 Launch target 后按 `CMake: Debug`。clangd 从 `build/<compiler>/compile_commands.json` 读语言标准，`.clangd` 不写 `-std`；C/C++ 扩展的 IntelliSense 关闭，编辑与诊断只由 clangd 提供。

## 包结构

运行时闭包是 `lib/`、`skills/`、`templates/`、`locale/`、`cordis.patch.yml`、两个 README、`LICENSE` 与 `icon.svg`。仓库另有 `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/plugin-storage.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-storage.md)，设计原则在 [docs/design-principles.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/design-principles.md)，注释与命名资料检索流程在 [docs/comment-sources.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/comment-sources.md)，版本规则在 [docs/versioning.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/versioning.md)。

## 本地开发

需要 Node.js 22 或更新版本。

```bash
npm ci
npm test              # 提交前主门：构建、结构/编码/工作流检查与单元测试
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 上运行。Windows 上先跑 `npm run ci`，再从 WSL 进入仓库跑 `npm run ci:full`。

## 许可

MIT，见 [LICENSE](https://npmcn.com/package/%40chengzhao-dev/dsh-cpp-workflow/LICENSE)。

## 常见问题

### @chengzhao-dev/dsh-cpp-workflow 是什么？

写 C\+\+ 源码、配 CMake、用 Clang 构建；头文件用 /// Doxygen 文档注释，函数体用 // 分段说明，文件头标签可在设置里改。

### 如何安装 @chengzhao-dev/dsh-cpp-workflow？

在项目目录运行 npm install @chengzhao-dev/dsh-cpp-workflow，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/dsh-skill（\>=0\.2\.1-rc\.1 \<0\.3\.0-0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @chengzhao-dev/dsh-cpp-workflow 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/chengzhao-dev\_\_dsh-cpp-workflow 是否存在。

### @chengzhao-dev/dsh-cpp-workflow 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @chengzhao-dev/dsh-cpp-workflow 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @chengzhao-dev/dsh-cpp-workflow 可以商用吗？

@chengzhao-dev/dsh-cpp-workflow 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @chengzhao-dev/dsh-cpp-workflow 的下载量有多少？

根据 npm 官方下载统计，@chengzhao-dev/dsh-cpp-workflow 在 2026/10/10 – 2026/11/08 这 30 天内被下载 5,626 次，日均约 188 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @chengzhao-dev/dsh-cpp-workflow 还在维护吗？

最新版本 0\.7\.4 发布于 2026/11/09（今天）；至今共发布 34 个版本，其中过去 12 个月发布了 34 个；首次发布于 2026/10/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。