前言¶
在 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
四个工具与返回语义¶
| 工具 | 作用 |
|---|---|
build_configure |
配置工程（cmake -S <src> -B <build> -G Ninja -DCMAKE_C_COMPILER=cl ...），自动注入 MSVC 环境，并为 C/CXX 追加 /diagnostics:caret（诊断带列号） |
build_run |
增量构建（cmake --build）；前台最多等待 foregroundWaitMs，未完成则转后台并返回 backgroundJobId |
build_status |
查询后台构建（省略 jobId 时使用当前/最近一次）；可选 waitMs 短等（上限 30s） |
build_stop |
停止本插件启动的构建（只终止自有进程树，不影响系统里其他进程） |
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 中配置（均可选）：
| 键 | 默认 | 说明 |
|---|---|---|
toolchainPath |
自动发现 | toolchain.json 路径；查找顺序：包同级 → 包内 → 会话 cwd → cwd/mlir-lang |
cmakePath |
toolchain 内 cmake.path |
显式路径优先 |
ninjaPath |
toolchain 内 ninja.path |
显式路径优先 |
vcvarsPath |
toolchain 内 msvc.vcvars |
vcvars64.bat 路径 |
generator |
Ninja |
v1 仅支持 Ninja |
foregroundWaitMs |
120000 |
前台等待上限后再转后台 |
defaultTimeoutMs |
900000 |
单次构建总时间预算 |
maxDiagnostics |
50 |
返回的 errors 条数上限 |
maxOutputBytes |
1048576 |
内存中保留的输出上限（完整日志仍落盘） |
logKeep |
100 |
<buildDir>/.build-driver/ 下保留的日志份数 |
构建日志路径：<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
典型用法（流程）¶
- 对源码目录调用
build_configure，指定sourceDir与buildDir（或省略buildDir使用<sourceDir>/.build）。 - 调用
build_run做增量构建；若返回backgroundJobId，用build_status轮询或带waitMs等待完成。 - 需要中断时调用
build_stop；根据返回的errors/logPath让 agent 定位编译问题。 - 配置错误（如错误的
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 仓库阅读完整工具参数与验收表。
