前言¶

在 DSH 里让智能体改 C/C++ 工程，常见做法是反复调用 Shell 去跑 cmake、ninja 和 MSVC 的 vcvars64.bat。命令长、环境变量易丢、编译输出一大段纯文本，agent 很难稳定拿到「第几行第几列、什么错误码」。长构建还会占满前台工具调用。下面介绍的 dsh-build-driver 把配置、增量构建、后台任务和停止收成四个 DSH 工具，并统一解析诊断与日志，面向 Windows 上典型的 CMake + Ninja + MSVC 链路。

这是什么¶

dsh-build-driver 是社区维护的 DSH 客户端类插件（维护者 Rcyc-1025）。插件 id 为 build-driver，npm 包名 dsh-build-driver。它不负责写业务代码，而是把 CMake 配置、Ninja 增量构建、MSVC 环境注入、编译诊断解析、长构建转后台 做成 agent 可直接调用的工具，与「每次让 Shell 拼一整条构建命令」相比，返回结构化的 ok / status / 诊断对象，便于后续改代码或重试。

• 目录页：https://www.skillhub.cn/plugins/Rcyc-1025/dsh-build-driver
• 源码：https://github.com/Rcyc-1025/dsh-build-driver

四个工具与返回语义¶

ok 的含义：完成且 exit 0 为 true；完成但非 0 为 false；仍在后台运行为 null（成败需结合 status）。status 可取 completed / failed / running / stopped / timed_out。

buildDir 解析：显式传入时相对会话 cwd；省略时与 build_configure 一致——有 sourceDir 则用 <sourceDir>/.build，否则 <cwd>/.build。

诊断对象形如 { file, line, col, severity, code, message }，支持 MSVC 编译/链接、clang/clang-cl、CMake Error/Warning；errors 最多返回 maxDiagnostics 条，errorCount / warningCount 统计全部命中。

中文诊断与编码¶

本机 cl.exe 常按控制台代码页（GBK/936）输出中文；若 subprocess 用 collect 模式按 UTF-8 解码会乱码。插件优先用 stdio: 'pipe' 取原始字节，构建结束后先 UTF-8 严格解码，失败再回退 gb18030 写日志。宿主不支持 pipe 时会退回 collect 模式（构建仍可完成，中文诊断可能乱码）。

可选配置¶

在 profile 的 cordis.patch.yml 中配置（均可选）：

构建日志路径：<buildDir>/.build-driver/build-<时间>-<序号>.log（UTF-8）。

依赖与环境¶

• Node.js ^22.19.0 || >=24.0.0
• DSH >=0.2.1-rc.5 <0.3.0-0
• CMake ≥ 3.20、Ninja、MSVC（Visual Studio 或 Build Tools）
• 可选：toolchain.json（与 P-01 同一份）；没有时也可用 cmakePath / ninjaPath / vcvarsPath 显式指定

MSVC 环境解析顺序：vcvars64.bat dump；失败时按目录布局兜底（MSVC Tools + Windows SDK，读 KitsRoot10 注册表）。README 注明：部分精简 VS 的 vcvars64.bat 是 shim，vcvarsall.bat 可能失败，此时走目录布局兜底。

安装与启用¶

官方 README 给出的方式是从 GitHub 取得源码目录后，装进 desktop profile（路径按本机替换）：

git clone https://github.com/Rcyc-1025/dsh-build-driver
& 'D:\exe\DSH\resources\runtime\cli\bin\dsh.cmd' plugin --profile desktop add D:\path\to\dsh-build-driver

也可在 DSH 内用 plugin_manager install_bundle，target 传插件目录的绝对路径。

修改 lib/*.js 后需重载插件才会生效（cordis.patch.yml 只承载配置，不会重新 import 模块）。在 DSH 中可执行：

plugin_manager set_plugin target "include:build-driver" enabled:false
plugin_manager set_plugin target "include:build-driver" enabled:true

典型用法（流程）¶

1. 对源码目录调用 build_configure，指定 sourceDir 与 buildDir（或省略 buildDir 使用 <sourceDir>/.build）。
2. 调用 build_run 做增量构建；若返回 backgroundJobId，用 build_status 轮询或带 waitMs 等待完成。
3. 需要中断时调用 build_stop；根据返回的 errors / logPath 让 agent 定位编译问题。
4. 配置错误（如错误的 vcvarsPath / cmakePath）会 ok:false 并带中文 hint，而非未捕获的 ENOENT。

README 中的验收记录（2026-11-04 本机）覆盖了最小 configure、hello 构建、带列号的 C2065、增量 ninja: no work to do、长构建转后台与 build_stop、错误 toolchain 路径等场景，可作为行为参考。

适用场景与注意¶

适合： 在 Windows 上用 CMake + Ninja + MSVC 维护的 C/C++ 工程，且希望 DSH agent 以固定工具链完成 configure/build，并拿到结构化诊断与可控的后台构建。

注意：

• 插件以当前 DSH 进程权限运行；安装前应阅读源码与 MIT 许可证，确认路径与 toolchain 配置符合本机策略。
• 当前版本（package.json 0.1.0）面向 Ninja 生成器与 MSVC；Linux/macOS 工具链不在 README 描述范围内。
• DeepSeek Harness 社区插件目录（如 skillhub.cn）为独立生态站点，与 DeepSeek / 幻方无官方从属关系；安装方式以仓库 README 为准，不要凭插件名臆造 dsh plugin add github:... 一类命令。

结尾¶

dsh-build-driver 把 Windows 上常见的 CMake + Ninja + MSVC 构建拆成四个可编排工具，并处理 MSVC 环境、诊断列号与中文编码、长构建后台化。若你的 agent 工作流里反复出现「配环境 + cmake + 解析 cl 输出」，可以在上述目录页查看分类信息，并在 GitHub 仓库阅读完整工具参数与验收表。

• 目录：https://www.skillhub.cn/plugins/Rcyc-1025/dsh-build-driver
• GitHub：https://github.com/Rcyc-1025/dsh-build-driver