Keil File Importer

独立 VSCode 扩展 + 可独立运行的命令行脚本。在 VSCode 中将 C 源文件与 H 头文件加入 uVision 工程分组，无需启动 Keil，不修改 Keil Assistant 本体。

非官方独立扩展，非 Keil 或 Keil Assistant 官方产品，也不是 Keil Assistant 的分支。

适配对象：Keil Assistant Community Fork（candycium.keil-assistant-new）。

1. 安装与右键使用

VSCode ≥ 1.85；将工作区设为可信。Keil 工程树功能需要先安装上述 Keil Assistant 扩展并打开工程。
扩展面板右上角「…」→「从 VSIX 安装…」→ 选择交付的 VSIX 安装包。也可执行：
```
code --install-extension keil-file-importer-1.0.2.vsix
```
在 Keil uVision Project 上方工程树中的 Hardware 等分组上右键 → Keil: 导入 C/H 文件到分组 → 选择磁盘上已有的 C 源文件或 H 头文件。
保存工程后，由 Keil Assistant 自己的文件监听刷新工程树，无需启动 Keil。

也支持下方普通资源管理器：

右键文件夹：选择工程 → 分组/Target → 选择 C/H 文件。
右键 .c / .h 文件（忽略扩展名大小写）：选择工程 → 分组/Target，直接导入当前文件。
右键工程文件：选择分组/Target → 选择 C/H 文件。
或打开命令面板执行 Keil: 导入 C/H 文件到分组。

支持 .c 源文件与 .h 头文件（忽略扩展名大小写），只添加工程引用，不创建、移动或复制文件，不自动加入 include 路径。头文件加入工程树不等于设置编译器头文件搜索路径。选择的源文件可以在工程目录外，存入工程的路径会相对工程文件所在目录计算（允许 ..），分隔符统一使用反斜杠。同一完整文件名（含扩展名）在同一分组中存在时，忽略大小写去重；即使来自不同目录也不重复添加。W25Q64.c 与 W25Q64.h 可以同时加入。

多工程、多 Target 的处理

Keil 分组右键对象不提供工程路径或 Target，只提供分组名和工程路径的 MD5（prjID）。扩展通过工作区工程路径匹配 prjID；无法唯一匹配时，必须明确选择工程，支持浏览工作区外工程。自动发现最多返回 500 个工程，遗漏时请用「浏览其它工程」。

若多个 Target 含同名分组，必须明确选择 Target，不会默认写入第一个 Target；如果一个 Target 内还有多个同名分组，则安全拒绝修改。界面当前激活的 Target 不作为可可靠读取的公共 API。

2. 纯命令行（不需要 VSCode 或 Keil）

交付的编译后 CLI 已包含 XML 解析器，不需要 npm install，只需 Node.js ≥ 18。在源码包根目录执行：

node .\dist\cli.cjs "D:\STM32\Project.uvprojx" "Hardware" "Hardware\W25Q64.c"

多个 Target 包含同名分组时：

node .\dist\cli.cjs "D:\STM32\Project.uvprojx" "Hardware" "Hardware\W25Q64.c" --target "Target 1"

注意：第三个参数必须相对于 工程文件所在目录，不是终端当前目录。例如工程在 MDK-ARM 子目录，源文件在旁边的 Hardware 目录时，路径应为：

node .\dist\cli.cjs "D:\STM32\MDK-ARM\Project.uvprojx" "Hardware" "..\Hardware\W25Q64.c"

CLI 允许导入尚未存在的相对路径，只写引用、不创建源文件；VSCode 文件选择入口要求源文件已经存在。成功与已存在返回 0，失败返回 1。提示示例：

成功：已将「Hardware\W25Q64.c」添加到分组「Hardware」。工程已保存，无需打开 Keil。
已存在：分组「Hardware」中已有「W25Q64.c」，未重复添加。
错误：找不到分组「Hardware」，工程文件未修改。

新增 C 源文件节点（FileType=1）：

<File>
  <FileName>W25Q64.c</FileName>
  <FileType>1</FileType>
  <FilePath>Hardware\W25Q64.c</FilePath>
</File>

头文件导入命令：

node .\dist\cli.cjs "D:\STM32\Project.uvprojx" "Hardware" "Hardware\W25Q64.h"

头文件节点使用 FileType=5（头文件/文本类，不作为 C 源文件编译）：

<File>
  <FileName>W25Q64.h</FileName>
  <FileType>5</FileType>
  <FilePath>Hardware\W25Q64.h</FilePath>
</File>

3. XML 与保存安全

严格解析 XML，只匹配 Project/Targets/Target/Groups/Group 的直接层级，分组名称精确匹配。
只插入新 File 记录；没有 Files 时添加 Files，自闭合 Files 展开为成对标签，容器原有属性保留。
不对整份 XML 重新序列化：保留原有元素、属性、节点顺序、注释、处理指令、实体写法、换行及 BOM；仅在插入位置添加格式化空白。
UTF-8 写入。保留原 XML 声明；缺少声明时在开头补充 UTF-8 声明。非法 UTF-8 或声明为其它编码的工程安全拒绝，不能直接转换 GBK/UTF-16 工程。
对新增内容做 XML 转义，写入前重新校验结果。拒绝 DOCTYPE/外部实体、畸形 XML、多个 Files 等歧义结构。
重复、缺失分组、取消选择、校验失败不写工程；不会自动创建分组。
同目录临时文件 → flush/fsync → rename 替换；尽可能避免读取到半份 XML。工程同目录必须可写。
使用同目录排他锁防止本工具的并发导入；保存前复核原文件内容，检测到外部修改则取消。
不覆盖编辑器内未保存的工程文档。仍请避免 Keil、其它编辑器和脚本同时改工程；外部程序不遵守本工具锁，复核到替换之间存在很小竞争窗口。
不自动备份；首次使用建议自行备份或使用 Git。
若进程崩溃留下 .keil-c-import.lock 锁文件，请先确认没有导入进程运行，再手动删除对应锁文件。正常结束和异常路径均会清理锁及临时文件。

4. 源码、测试、重新打包

扩展入口：右键、工程匹配、选择文件、中文提示。
核心逻辑：XML 解析、原文增量插入、去重、锁与原子保存。
CLI 源码 / 编译后 CLI。
自动化测试 / VSCode API 模拟测试 / CLI 验收测试。
构建脚本 / 扩展清单。

开发与打包建议 Node.js ≥ 22、pnpm 11。项目锁定依赖版本；不需要运行可选原生模块安装脚本：

pnpm install --frozen-lockfile --ignore-scripts
pnpm test
pnpm run package

构建通过 esbuild 将 saxes 和 xmlchars 打入两个产物；安装 VSIX 不需要另装 Node/npm/Python，CLI 则需要 Node。第三方许可证见 THIRD_PARTY_NOTICES。

Marketplace 发布信息

显示名称：Keil File Importer
发布者 ID（publisher）：keil-file-importer
插件名称（name）：keil-file-importer
完整扩展 ID：keil-file-importer.keil-file-importer
当前版本：1.0.2

在 Marketplace 管理页面选择发布者 keil-file-importer，上传新构建的 VSIX；不要仅修改旧安装包文件名。包内发布者 ID 必须与上传页面的发布者 ID 完全一致。发布者账号权限与 Marketplace 审核仍由平台验证。

本扩展与此前 local-keil-tools.keil-c-importer 本地测试版属于不同扩展 ID，不会自动覆盖。安装正式命名版本前请卸载旧测试版，避免两份扩展注册相同命令。

5. 兼容性依据与验收范围

已核对 Marketplace 2.5.2 的发布清单；树节点参数依据其公开 master 源码，未承诺未来版本内部字段不变：

自动化覆盖 XML 增量写入、磁盘失败路径、模拟 VSCode 交互和真实 CLI 子进程。未在真实 VSCode + Keil Assistant 窗口中端到端验证侧边栏刷新，也未启动 Keil 进行编译验证。

建议安装后在工程副本上验收：右键 Hardware 导入一次 → 检查工程树出现文件 → 再导入应提示已存在 → 比较工程差异仅新增节点 → 用原有工具链编译。若分组菜单因第三方插件升级不显示，仍可从命令面板或普通资源管理器入口选择工程与分组。