# 谁需要它，为什么单独做一个库

## 具体用户与任务

目标用户是维护 VS Code 扩展或键位包的开发者，而不是所有 GUI、TUI 或普通编辑器用户。
任务是：修改快捷键的 when 条件、平台覆盖或用户配置兼容逻辑后，在发布前确认
“正常编辑仍保存、显式模式下触发扩展、只读和非编辑焦点不误触发”等约定没有改变。

官方排障说明明确讨论了扩展覆盖默认绑定的问题，公开需求记录也讨论过 when 更新对自定义覆盖的影响：
[VS Code 排障文档](https://github.com/microsoft/vscode/wiki/Keybinding-Issues)、
[历史需求记录 #229552](https://github.com/microsoft/vscode/issues/229552)。
它们是问题存在的公开信号，不是这些作者使用了本项目、问题仍未解决或本项目已有客户的证明。

## 现有方案能做什么

| 方案 | 应当使用它的情况 | 本项目补充的流程，而非宣称替代 |
| --- | --- | --- |
| VS Code Show Same Keybindings | 查找当前安装中同键条目 | 检查固定状态契约，区分有意复用和条件变化引发的回归 |
| Keyboard Shortcuts Troubleshooting | 观察真实机器收到的键、布局和实际分派 | 不启动编辑器，对提交的快照批量重放指定状态，输出可留档 JSON |
| VS Code 实机/扩展集成测试 | 验证实际焦点、命令执行、布局、注册顺序 | 先做快速声明检查，再把未知或高风险结果交给宿主实测 |
| 项目内一次性脚本 | 单个扩展、少量固定条件 | 多调用端共用一份条件解析、顺序、未知语义和报告实现，减少维护分歧 |

现有宿主已经能发现冲突，不能说“没有人做过”。本工具提供的是一种更容易进入源代码审查的
限定状态回归流程，覆盖范围比真实宿主窄。只有少量个人键位时，内置工具或小脚本通常更合适。

## 独立成库的证据

`vscode/` 是纯 MoonBit 包，不读文件、不读取环境、不退出进程；接受声明字符串并返回结构化结果。
`cmd/main` 在文件 CLI 中调用 audit_sources，`scripts/check_vscode.mjs` 直接调用同一源码
编译导出的 audit_json，不再运行 CLI 子进程。没有为第二个调用端重写解析规则。

`node scripts/test_vscode.mjs` 用三种声明平台、反例/修复两种配置比较两个入口结果，
同时检查调用边界与 JSON 输出。它证明当前两个消费者能复用一份内核，
**不证明已经有外部项目采用，也不证明覆盖所有编辑器**。

如果未来只有 CLI 自用、没有新的消费者，独立库的维护收益仍需重新评估；不会为了赛道强行声称普适必要。

## 为什么示例不是仅换一组测试数据

目录 examples/vscode-review/extension 是含真实贡献格式及可执行处理器的开发扩展。
两份 manifest 的快捷键字符串相同；反例把 when 条件从四个限制放宽为 editorTextFocus，
导致三个指定场景选中不同命令。单纯列出重复键无法说明哪三个状态发生了变化。
输出给出预期命令、实际命令、所选规则和条件轨迹；实现上的不确定因素会显式阻止通过。

这是原创故障注入验证，不是线上用户案例。仍待完成：目标 VS Code 版本实机回放、
来自真实扩展维护者的反馈及更多现场配置。不能用测试数量代替这些证据。