前言¶

在 DeepSeek Harness（DSH）裏做嵌入式固件時，常見情況是：模型能讀 C 源碼、能改文件，但真正決定能不能出貨的是 Keil MDK/uVision 那一套——.uvprojx 裏的工程登記、本機安裝的編譯器、以及 IDE 裏配好的調試與燒錄。編譯、讀日誌、改代碼、再下載，這個循環仍在廠商 IDE 裏完成，智能體拿不到結構化的構建結果，人往往要在 IDE 和對話窗口之間來回轉述。

社區插件 dsh-keil（維護者 wimi996123，GitHub 倉庫 wimi996123/dsh-keil，當前包版本 0.2.0，MIT 許可證）把上述循環暴露成 JSON：一次構建請求可得到退出碼、錯誤/警告數、Program Size、日誌路徑和 HEX 路徑。面板、CLI、HTTP API 與 DSH 的 keil 工具共用同一核心，避免多套實現各自漂移。分類上屬於 DSH 客戶端 插件；可選側邊欄依賴 dsh-better-sidebar。

這是什麼¶

dsh-keil 是 DSH 的 Keil MDK/uVision 工作臺：人類可在可選 Keil 側邊欄裏選工程、點編譯/燒錄；智能體通過 keil 工具 或 dsh-keil CLI 做同樣的事；在掛載了 webServer 的 profile 上還有 /keil/api。它解決的是「agent 無法直接跑 UV4 閉環」的問題，而不是替代 Keil 或重寫構建系統。

核心功能¶

下面介紹 README 中已明確的能力，均可在倉庫文檔中核對。

工程選擇與只讀查看¶

工作區內的 .uvprojx 候選會被掃描並列出（有深度上限，超出時標記 truncated），但不會自動選中；選定工程是用戶的顯式操作，按工作區保存在 %USERPROFILE%\.dsh\keil\state.json（可用環境變量 DSH_KEIL_STATE 覆蓋路徑）。模型工具 刻意沒有 select 操作；未選工程時調用構建類操作會報 NO_PROJECT_SELECTED。

只讀能力包括：status、doctor、candidates、tree、files 等，可查看工程組、已登記文件（磁盤缺失會標記）、以及分號分隔的 <IncludePath>。

通過 UV4 編譯與燒錄¶

在 Windows 10/11 上，插件調用 UV4.exe：-b 增量編譯、-r 全量重編、-c 清理、-f 下載。同一時間只允許一個構建任務；UV4 輸出寫入 %USERPROFILE%\.dsh\keil\logs\ 下按工程與時間戳命名的日誌文件。只讀查看工程樹與路徑在能運行 Node 的系統上即可；編譯與 download 依賴 Windows。

僅修改 .uvprojx 登記¶

插件不創建或刪除磁盤上的源文件，不碰 .uvoptx 和構建產物目錄；清理由 UV4 -c 完成。每次改工程前先備份（保留最近 50 份），寫入採用臨時文件再 rename。XML 編輯採用區間拼接而非整文件重序列化，以便保留 BOM、CRLF 和註釋；先加後刪可字節級還原（倉庫測試中有覆蓋）。

登記類操作包括：add_file、remove_file、add_include、remove_include、create_group、delete_group（工具與 CLI 對應命令見下文示例）。

三種入口，一套核心¶

Host 端至少需要 DSH 的 tools 服務；無 webServer 時無 HTTP 路由與面板，但工具和 CLI 仍可用。

環境要求¶

安裝與啓用¶

DSH 生態裏插件以 bundle 形式安裝；必須使用 file: 加正斜槓絕對路徑，相對路徑會按包管理器當前工作目錄解析，容易靜默失敗。以下命令來自倉庫 README，請把路徑換成你本機 checkout 的絕對路徑。

CLI 管理的 profile（示例 profile 名爲 web）¶

先在本地取得插件目錄（例如 C:/src/dsh-keil），再執行：

dsh plugin --profile web add "file:C:/src/dsh-keil"
dsh plugin --profile web add dsh-better-sidebar@0.28.2   # 可選 UI

普通 dsh CLI 需要 pnpm 在 PATH 上。安裝後需重啓該 profile。注意：CLI 不能直接改保留的 desktop profile（會提示由 Electron 應用獨佔管理），桌面版請用下面方式。

開發時若希望改代碼即生效，可用 link:C:/src/dsh-keil 代替 file:；file: 安裝的是快照，git pull 後需重新安裝。

桌面應用¶

可在 Settings → Plugins 從絕對 checkout 目錄安裝，或在插件目錄運行：

node scripts/install.mjs --check                 # 只報告 profile、CLI、UV4、倉庫
node scripts/install.mjs --dry-run               # 打印將執行的命令，不寫入
node scripts/install.mjs                         # 安裝到解析出的 profile
node scripts/install.mjs --profile web --no-ui   # 指定 profile，不裝側邊欄依賴

完整參數以 node scripts/install.mjs --help 爲準。安裝後若列表裏看不到插件，需重啓應用或 profile，並在 Settings → Plugins 中確認。

安裝後驗證¶

checkout 內可直接運行：

node bin/keil.mjs --help
node bin/keil.mjs doctor --compact
node bin/keil.mjs show-config
node --test test/core.test.mjs

裝入 profile 後，同一 CLI 以 dsh-keil 出現在該 profile 的 node_modules/.bin 下。

配置 UV4¶

構建前需能定位 UV4.exe。解析順序依次爲：環境變量 DSH_KEIL_UV4 / KEIL_UV4 → %USERPROFILE%\.dsh\keil\config.json 的 uv4 字段 → 註冊表與常見安裝目錄 → PATH 上的 where UV4.exe。建議顯式寫入，避免每臺機器依賴自動發現：

dsh-keil set-uv4 --path "C:\Keil_v5\UV4\UV4.exe"
dsh-keil set-uv4 --path "C:\Keil_v5"
dsh-keil doctor

構建報 UV4_NOT_FOUND 時，用 doctor 查看嘗試過的路徑，再用 set-uv4 或環境變量修復；不要把本機絕對路徑提交進 Git 倉庫。

典型用法¶

人類：側邊欄¶

安裝 dsh-better-sidebar 並重啓後，打開 Keil 標籤。首次進入選擇或粘貼 .uvprojx 絕對路徑，之後在同一工作區會記住選擇。可用按鈕執行編譯、全量重編、下載、清理；構建日誌頁約 0.9 秒輪詢狀態；工程樹與頭文件路徑頁可編輯登記（與 CLI/工具規則一致）。

智能體與腳本：CLI¶

先爲工作區保存工程選擇，再構建：

dsh-keil select --cwd C:\work\fw --project C:\work\fw\MDK-ARM\app.uvprojx
dsh-keil tree --cwd C:\work\fw --compact
dsh-keil build --cwd C:\work\fw
dsh-keil download --project C:\work\fw\MDK-ARM\app.uvprojx

登記示例（相對路徑先按工作區再按 .uvprojx 目錄解析，寫入工程以工程目錄爲基準）：

dsh-keil add-file --cwd C:\work\fw --group App --file Core\Src\timer.c
dsh-keil add-include --cwd C:\work\fw --path ../Core/Inc2 --allow-missing

全局選項包括 --cwd、--project（覆蓋已保存選擇）、--compact（單行 JSON）。

智能體：工具 keil¶

在 DSH 對話中調用工具時傳 action（如 build、tree、add_file），可選 project、group、file、path 等。不傳 project 時使用當前會話工作區已保存的用戶選擇。構建可同步等待，或用 build_start / build_status / build_stop 非阻塞控制。

HTTP API（Web / 桌面且已掛載 webServer）¶

GET  /keil/api   → { "ok": true, "data": { "version", "build", "uv4" } }
POST /keil/api   body: { "action": "status", "cwd": "C:\\work\\fw" }

action 與核心支持的操作一致；請求體上限 1 MiB。多數錯誤以 JSON 的 ok: false 返回，而非依賴 HTTP 狀態碼。

適用場景與注意¶

適合誰： 已在 Windows 上使用 Keil MDK 維護 .uvprojx 工程，希望在 DSH 裏讓人或模型重複「看樹 → 改登記 → 編譯 → 讀日誌 → 下載」，且接受「多 Target 工程目前只讀寫第一個 Target」「無調試器 attach，download 依賴工程內已配 Flash/調試器」等範圍（見倉庫「範圍與路線圖」）。

權限與安全： 插件以當前 DSH 進程權限運行，會執行本機 UV4.exe、讀寫用戶目錄下的 %USERPROFILE%\.dsh\keil\ 狀態與備份、並按規則修改工作區內的 .uvprojx。安裝前應閱讀 倉庫源碼 與 MIT LICENSE，自行評估是否納入工作流。社區目錄 SkillHub 插件頁 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係；星標等元數據以各站點當時展示爲準（GitHub 上約爲 2 stars）。

常見錯誤： NO_PROJECT_SELECTED — 面板或 dsh-keil select 選工程；BUILD_BUSY — 等待或 build-stop；已裝插件但無 Keil 標籤 — 補裝 dsh-better-sidebar@0.28.2 並重啓。

結尾¶

dsh-keil 把 Keil 上那套「選工程 → UV4 構建/下載 → 結構化結果」接到 DSH 的工具、CLI 與可選面板上，並嚴格限制爲 .uvprojx 登記級修改，降低 agent 與 IDE 之間的人工 relay。進一步瞭解可查看 SkillHub 目錄頁 與 GitHub 倉庫 README（含簡體中文）；給 agent 的安裝與修復步驟見倉庫 AGENTS.md。