azKeilConfigurationWizard

在 VS Code/Cursor 中右键 .h 文件，选择 AZ：打开配置界面，通过分组、滑动开关、下拉框、数值及字符串输入修改配置宏。使用现有 Keil Configuration Wizard 注释，无需另建一份配置数据。

修改进入编辑器撤销记录，点击“保存文件”或按 Ctrl+S 写回头文件。修改参数时只替换对应宏的字面量，保留外围注释、行尾和由编辑器管理的文件编码。

本地安装与使用

1. 在扩展面板菜单中选择 Install from VSIX / 从 VSIX 安装，选择 dist/vscode/az-keil-configuration-wizard-0.6.2.vsix，更新后重载编辑器窗口。

2. 打开包含配置头的工程，在文件树或文本编辑器中右键 .h → AZ：打开配置界面。缺少合法向导格式时先询问是否允许格式化；取消不会修改或打开配置页。允许后添加或修复向导标记，再打开配置页。修改进入缓冲区，不自动保存，可一次撤销。

3. 已包含下面标记的文件，标记上方会显示可点击的 ⚙ 打开配置界面。现有 Keil 配置头无需再填写地址或绝对路径。

   // <<< Use Configuration Wizard in Context Menu >>>
   

4. 修改参数并保存，需要时点击“查看源码”核对；按工程原有方式重新编译。

可先打开 示例配置头 体验。示例使用 GBK；首次打开时如中文异常，请在编辑器状态栏选择 重新打开编码 → GBK。较新宿主支持时，扩展入口会尝试按 UTF-8/GBK 打开；有未保存修改时不会自动重载编码。

无需常驻服务、浏览器端口或 npm 安装。扩展不会自动安装依赖、执行编译或烧录。

从旧版迁移：显示名现在为 azKeilConfigurationWizard，扩展 ID 为 az-tools.az-keil-configuration-wizard。VS Code 的内部名称使用小写连字符格式。首次请手动安装新 VSIX，并卸载旧扩展 az-local.az-config-editor，避免重复菜单；原有 .h 文件和注释不需改名。之后保持扩展 ID 和 publisher 稳定即可自动更新。

Gitee 自动更新

源码和正式发行版位于 AZ-TOOLS/az-keil-configuration-wizard。从 Gitee Release 下载更新，无需扩展市场或 Git 命令。

默认 自动检查并安装：IDE 启动后约 15 秒检查；成功或失败后至少间隔 12 小时再做后台请求。检查到更高的正式版本后，下载 VSIX、核对 SHA-256、插件 ID、版本和 IDE 引擎要求，再通过 IDE 的安装命令更新。安装成功后提示重载窗口，由用户选择重载时机，不会强制关闭正在编辑的文件。等待重载期间不会重复安装同版。

在用户设置中搜索 azKeilConfigurationWizard.updates.mode：

命令面板可执行 azKeilConfigurationWizard：检查更新 或 查看更新日志。手动检查发现新版后会提供安装按钮。后台网络错误仅记录日志；不影响配置编辑，手动检查可以立即重试。该设置为应用级，工作区配置不能覆盖。扩展开发宿主不启动后台轮询。

更新源必须有可公开读取的正式 Release，标签如 v0.4.1，并包含：

az-keil-configuration-wizard-0.4.1.vsix
az-keil-configuration-wizard-0.4.1.vsix.sha256

校验文件格式为 64 位十六进制 SHA-256、两个空格、完整 VSIX 文件名和换行。预发布、缺附件的发行版及版本号不符合要求的标签会被跳过；只推送源代码不会产生可安装更新。公开 Release 列表及附件不需 Token。IDE 自身的发布者信任及安装策略仍然适用；受限网络下可继续手动安装 VSIX。

维护与发布

本项目为独立仓库，不依赖原 MCU 工程目录。运行以下命令准备发行文件，不写入远端：

python scripts/release.py --prepare

脚本运行本地测试，并在 dist/ 输出 VSIX 及 SHA-256 文件。修改 package.json 的正式语义版本后再生成下一版。确认改动、完成代码审核及远端合入后，可在 Gitee 创建相应正式 Release，上传以上两个文件；也可使用明确的发布入口：

python scripts/release.py --publish --target <已合入远端的完整40位提交SHA> --notes-file <UTF-8发行说明文件>

发布所需 GITEE_TOKEN 由当前终端环境提供，不写入仓库、日志或命令参数。发布前必须保证本地 HEAD 与 --target 一致、工作区干净、origin 正确，且远端已存在该提交。脚本重新测试并打包，创建版本标签/Release，先上传校验文件再上传 VSIX。脚本不会提交代码、推送分支或合并 MR；只有指定 --publish 才会访问远端写接口。若创建 Release 后上传中断，在 Gitee 补上传缺失附件；客户端会忽略未完成的发行版，不会安装半成品。

自动更新尚无首个远端发行版时，会明确显示“尚未发布”。需要先完成首次源码提交和首版 Release，才能验证真实远端升级。若新版出现问题，可手动安装保留的旧版 VSIX，并将自动更新暂时设为 off。

VS Code 商城快速发布

根目录 publish-vscode.bat 是 Windows 发布入口，需要 Python 3.9+、Node.js 和已安装的 vsce，脚本不会自动安装依赖。

首次使用先在 Marketplace 创建或选择 package.json 中 publisher 对应的发布者（当前为 az-tools），执行一次登录：

.\publish-vscode.bat --login

按 vsce 提示在本机输入具有 Marketplace Manage 权限的 Token。登录由 vsce 自行管理；脚本不保存 Token。也可以通过 VSCE_PAT 环境变量提供凭据，或在发布时加 --azure-credential 使用已配置的 Microsoft Entra ID 身份。官方发布说明。

日常更新代码后，双击 publish-vscode.bat，或在工程目录执行：

.\publish-vscode.bat

脚本显示插件 ID 和当前版本，提示输入本次新版本，回车采用下一个 patch 版本（例如 0.6.0 变为 0.6.1）。随后运行全部本地测试、生成 VSIX 和 SHA-256，校验包内发布者、版本及 Public 公开发布标记，显示目标后询问是否上传。输入 y 后验证发布权限并调用 vsce publish --packagePath，上传完成后仍需等待商城校验。

常用命令：

新包写到 dist/vscode/，同时生成 .vsix.sha256 与 .vsix.release.json。包只包含运行代码、页面资源、示例和项目说明，不包含 .ai_tmp、Git 配置、测试及历史 VSIX。相同源文件生成相同的安装包字节。

指定版本或增加版本会修改 package.json，保持原编码和换行，并在 .ai_tmp/bak/vscode-version-*/ 备份原文件；测试失败或取消上传后也保留所选版本，便于修复后按该版本重试。不会自动提交或推送 Git、创建标签或发布 Gitee Release。版本号与代码仍按正常 MR 流程管理，Gitee 分发继续使用前述发行流程。

测试失败、未获发布权限、发布者不匹配，或确认期间代码 / 安装包发生变化时停止上传。Marketplace 同一个版本不能重复发布；上传异常后先查看商城后台版本状态，再决定重试或增加版本。.vsix.release.json 的 submitted 只表示上传命令成功返回，不表示商城已完成校验或公开。package.json 的 private 是 npm 设置，商城公开标记位于 VSIX 清单中。

编辑配置项

直接在配置页操作，不需要切换到另一张编辑页面：

• 顶部 ＋ 添加分组 新增顶层分组；分组标题旁 ＋ 子分组 在当前分组内新增分组。
• 分组框内 ＋ 添加配置项 弹出配置窗口。宏来源可选 选择头文件中已有的宏 或 创建新宏。
• 选择已有宏时，列出尚未作为配置项的宏名、原始字面量或算式及当前行号，自动带入类型、原值和行尾说明。例如可直接选择 RTE_RFOP_CLIENT_ENABLE，首次关联保持原值；添加后在配置页修改值。已配置宏不重复列出，纯整数常量算式（如 (4096*2)）可选并显示计算结果；引用其他宏的表达式、别名、函数宏、多行宏和重复定义显示原因并禁用。
• 选择创建新宏时，填写宏名、名称、类型、初始值和范围等属性，创建新的 #define。
• 配置项右侧 编辑 打开同一弹窗，调整名称、描述、所属分组、显示顺序、控件类型和当前值；已有宏名保持不变。
• 分组标题旁 编辑分组 可调整名称、说明、父分组及同级顺序，不允许形成循环。
• 位掩码的多个开关共享一个宏，在弹窗的 位选项 中切换编辑，可新增或移除位选项；当前值不能包含未定义的位。

在弹窗点击 应用 即更新编辑器缓冲区，也可以先点 查看差异 核对，再应用。差异查看不修改文件；应用后可用一次撤销恢复，再由配置页 保存文件 或 Ctrl+S 写入磁盘。关闭或取消弹窗不会应用草稿。源码被其他页面修改时，旧弹窗保留草稿并禁止应用，关闭后重新打开即可载入新内容。

支持非负整数、0/1 开关、数值枚举、位开关、字符串和浮点数。整数范围、浮点范围、字符串长度和枚举项随类型显示。切换类型后可直接修正当前值，不会静默转换不兼容的值。宏名重复、值越界、位编号重复等会在弹窗显示诊断。只改当前定义或移动对应块，保留其他定义、普通说明、宏尾注和配置区外的代码。此版不提供删除已有宏或分组的入口。

添加已有宏以 Keil 兼容优先：使用标准 <o>、<q>、<s> 等标签，将原 #define 连同尾注移动到所选分组，不生成新的 reference 引用元数据，也不重复定义宏。原值和数值写法保持不变；纯整数常量算式转成等值数字，例如 (4096*2) 转成 (8192)，原式记录为普通注释。条件编译分支、#undef、移动路径中已有宏引用或跨行注释边界等无法安全移动的宏会禁用并说明原因。跨过 #include 会提示重新编译核对头文件依赖。

已有引用格式迁移：升级后打开旧文件，顶部出现 迁移为 Keil 格式。点击后先 查看差异，核对再 应用；原值、分组和说明保留，仅在安全范围移动宏并展开标准标签。不安全的项原样保留并提示。迁移不会创建或改写任何编译校验块，不自动保存，可用一次撤销恢复。仍留有引用项时继续显示兼容提示；浮点配置始终标注 仅 AZ 插件支持，不会声称 Keil 原生支持浮点控件。

普通头文件格式化先建立空配置分组，不自动把协议常量、派生值或所有宏变成配置项，用户再通过添加窗口选择。存在常见头文件保护宏时，配置区域优先放入保护范围内；不移动原代码。可修复可识别的标记大小写及简单缺失边界；遇到多套边界、不支持的已有标签、表达式或无法安全推断的配置范围，会保留原文件并提示使用 AI 提示词整理。确认期间源码若发生变化，会停止格式化，避免覆盖。

自动校验与手写代码保护

界面不提供手工判断表达式或报错语法编辑框。新增配置项，或修改配置项的类型、范围、枚举、位定义、名称及描述时，按定义自动生成或更新 当前宏 的校验。普通配置值修改、弹窗中仅修改当前值、分组编辑及排序移动不重新生成校验，也不扫描重建所有宏的校验。

• 整数：生成非负 32 位范围或指定区间的 #if / #error。
• 开关：限制为 0 或 1；枚举：限制为列出的值；位掩码：限制为已定义位的组合。
• 浮点范围和字符串长度：自动做界面输入校验，不能直接用于 C #if，因此不生成不合法的预处理表达式。

每个宏的自动块位于配置结束标记之后、头文件保护结束之前，使用 AZ CONFIG CHECK BEGIN/END 宏名 和内容 SHA-256 标识。更新前先比对摘要；正文、摘要或标记被用户手改后，工具原样保留该块并显示提示，同时仍可应用配置定义。请自行核对手改校验与新定义是否一致；工具不会替用户恢复或覆盖手改代码。

原有手写 #if / #error、跨宏依赖、旧版 AZ CONFIG VALIDATION BEGIN/END 区域全部原样保留，包括已被用户手改的内容。工具不推断跨宏依赖，不将建议自动变成硬约束，配置是否合法仍需通过实际工程编译检查。

AI 提示词

点击配置页的 AI 提示词，或右键选择 AZ：AI 提示词，进入独立页面。内置“格式化配置头”和“检查配置约束”两份固定提示词，可直接复制给 AI。约束提示词提供类型和范围建议，由用户在弹窗审核应用；不要求手工改写自动校验。

复制提示词只复制模板；复制并附带当前头文件显式附带当前编辑器中的文件内容，包括未保存修改。页面不连接 AI 服务，也不自动发送文件。没有配置注释的头文件也能从右键入口打开此页，先让 AI 整理注释，再用编辑器查看结果。

支持的文件

• 基础 Keil 标签：<h>、</h>、<i>、<q>、<q.n>、<o>、数字枚举、数值范围和 <s> / <s.N> 字符串。
• 整数为 32 位非负十进制/十六进制字面量；字符串为单个普通窄 C 字符串；可带外层括号。
• 同一掩码前可有多个位复选框。
• 固定协议常量、派生值和 #if / #error 放在配置结束标记后。

原生 Keil 标签要求单一字面量。“选择已有宏”支持读取纯整数常量算式的括号和加、减、乘、整除、取余，按 C 整数优先级计算；为避免猜测目标类型，中间值和结果限制为 0..2147483647。算式中的宏引用、函数、类型转换、移位、位运算和整数后缀暂不计算。除零、负中间值、溢出或未知语法会禁用并显示原因。导入或迁移时把算式转成等值字面量并保留原式注释，以免 Keil 改到算式中的操作数。任意跨宏依赖仍由工程编译校验负责。

字符串支持普通引号、反斜杠、换行、制表符及 ASCII 数字转义。非 ASCII 字节转义、宽字符串、拼接字符串和通用字符转义需在源码中编辑。<s.N> 的限制按 Unicode 字符数计算，不代表编码后的字节容量，需结合实际缓冲区确认。

浮点数支持符号、小数、科学计数法及 f/F 后缀，使用独立注释元数据：

// @az-config {"type":"float","title":"比例系数","description":["单位及生效条件"],"min":-10,"max":10}
#define APP_SCALE (1.25f)

min/max 可为 null。旧版 Keil 忽略该普通注释，浮点控件仅在本扩展显示。字符串长度和浮点范围用于界面输入校验；它们不能直接生成 C 预处理判断。切换控件类型或收紧范围时，若当前宏值不匹配，预览会拒绝该修改。

界面参考设置页布局：分组标题位于圆角卡片之外，选项名称和说明放左侧，控件放右侧；嵌套分组共用卡片。颜色和滑动开关强调色继续跟随 IDE 主题，支持深浅主题。

原始宏名始终以斜体显示在配置项名称旁，空间不足时自动换行；可按名称、宏名或说明搜索。正文为 15px，说明为 14px，主分组标题为 17px 并加粗；颜色继续跟随 IDE 主题。界面显示当前编码与保存状态，源码有修改时同步刷新，过期操作会被拒绝并要求重新操作。

常见问题

开发与验证

用 VS Code/Cursor 单独打开本目录，按 F5 启动扩展开发宿主。运行时不依赖额外 npm 包。

node --test test/*.test.js
python scripts/package_vsix.py

包使用 publisher az-tools，支持 Gitee Release 分发和通过上述脚本提交 VS Code Marketplace。

已在本机 Qoder 的扩展开发宿主（VS Code API 1.106.3）验证激活、自定义编辑器、页内编辑入口、独立提示词页、数值/字符串/浮点修改、定义预览及应用、自动校验生成、过期版本拒绝、GBK 保存与撤销，以及 GBK 无法编码的字符拦截。新增验证缺少向导格式时取消不修改、确认后格式化可撤销且不自动保存、RFOP 宏导入标准分组，以及旧版引用迁移的预览、应用、撤销和过期请求拒绝。80 项测试通过，含实际 MiniPack/RFOP/XCU 配置头只读回归及 Clang 编译验证；另覆盖局部编辑、空配置头添加首个配置项、校验更新、手改块保护、排序不改校验、CRLF 保留及更新机制。

Keil 兼容迁移另用独立保守语法检查器检查数值标签和目标绑定，并对转换前后的常量值做编译验证。未进行本版 Keil 原生 Configuration Wizard 界面的实际打开及改值验收；编译和静态检查通过不能替代该项验收。浮点项仅 AZ 插件显示，保留的不安全旧引用仍不属于 Keil 兼容配置。

同一套界面资源通过浏览器预览验证了已有宏选择、类型及原值自动带入、不支持宏禁用、已关联宏去重、深浅主题与窄窗口，以及页内新增分组、弹窗新增整数/字符串/浮点、范围冲突提示、共享位掩码编辑、预览应用以及手改校验保护提示。页面桥接测试验证只读差异和显式附带源文件的复制行为。VSIX 在隔离扩展目录中安装验证。

尚未在独立的 VS Code/Cursor 安装实例中验证。它们使用标准 VS Code 扩展 API，但实际兼容性仍需目标版本安装后确认。