前言¶
在 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 倉庫閱讀完整工具參數與驗收表。
