前言¶

在 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。