Keep shortcut preferences device-local and commit before activation
快捷键偏好按设备保存，提交后才激活
Keyboard bindings depend on the receiving device's operating system and browser restrictions. A Host can serve several devices, while a local save can fail after a user records a new combination. Activating an unpersisted binding makes the interface disagree with the next application launch. Rewriting unreadable or future-version preferences can destroy choices an older client cannot interpret.
English
Problem
Keyboard bindings depend on the receiving device's operating system and browser restrictions. A Host can serve several devices, while a local save can fail after a user records a new combination. Activating an unpersisted binding makes the interface disagree with the next application launch. Rewriting unreadable or future-version preferences can destroy choices an older client cannot interpret.
Decision
The shortcut service stores only versioned overrides per runtime/platform. Web owns origin-local browser storage; Electron main owns userData/keybindings.json, independently of Harness home. Both adapters share validation and transaction logic. Successful persistence publishes one accepted configuration from which command matching, keycaps, and native interception derive.
Missing commands retain dormant overrides. Explicit overrides win over newly introduced defaults; conflicting explicit overrides are all disabled. Unreadable configuration blocks ordinary edits and preserves the last accepted values. Restore All clears only the accepted current profile and cannot overwrite unreadable or future-version data.
Alternatives considered
Host settings. A server's operating system and settings scope do not identify the visitor's device or browser restrictions. Host storage would also couple remote visitors' preferences.
Optimistic activation. Updating bindings before persistence makes a failed save appear successful and leaves restart behavior inconsistent with the visible controls.
Cross-tab atomic merging. localStorage has no compare-and-swap transaction. Web rereads before each operation and rejects known stale drafts, but accepts last-writer-wins for simultaneous writes. Electron main serializes edits and rejects stale revisions.
Consequences
Devices and Web/Desktop do not synchronize bindings automatically. Repairing unreadable preferences requires correcting the stored document; application edits preserve those bytes. Browser concurrency does not promise lossless merging. Atomic Desktop replacement uses the shared writer's Windows retry behavior without promising fsync durability. Deterministic transaction, browser-storage, and Desktop-file tests cover failure retention, conflicts, stale drafts, and refusal to replace unreadable data; platform keyboard acceptance remains separate from persistence correctness.
中文
问题
快捷键取决于接收输入设备的操作系统和浏览器限制。一个 Host 可服务多个设备，而用户录入新组合后，本地保存仍可能失败。激活未持久化的绑定会使界面与下一次启动不一致。重写不可读或未来版本的偏好可能破坏旧客户端无法解释的选择。
决策
快捷键服务 只保存按运行端／平台区分的版本化覆盖。Web 使用同 origin 的浏览器存储；Electron main 管理 userData/keybindings.json，与 Harness home 独立。两端适配器共享校验和事务逻辑。持久化成功后发布一个已接受配置，命令匹配、键帽和原生拦截都由此派生。
未加载命令保留休眠覆盖。显式覆盖优先于新增默认值，相互冲突的显式覆盖全部禁用。不可读配置阻止普通编辑，并保留上次接受的值。全部恢复只清除已接受的当前平台覆盖，不会覆盖不可读或未来版本的数据。
考虑过的替代方案
Host 设置。 服务端操作系统和设置范围不能标识访问者设备或浏览器限制，Host 存储还会耦合远程访问者的偏好。
乐观激活。 在持久化之前更新绑定会让保存失败看起来像成功，并使重启行为与可见控件不一致。
跨标签页原子合并。 localStorage 没有比较并交换事务。Web 每次操作前重新读取并拒绝已知过期草稿，但同时写入采用最后成功写入生效。Electron main 串行处理编辑并拒绝旧 revision。
影响
不同设备以及 Web／Desktop 不自动同步绑定。修复不可读偏好需要更正存储文档；应用内编辑保留这些原始内容。浏览器并发不承诺无损合并。Desktop 原子替换使用共享写入器的 Windows 重试行为，不承诺 fsync 持久性。确定性的事务、浏览器存储和桌面文件测试覆盖失败保留、冲突、过期草稿以及拒绝替换不可读数据；平台键盘验收与持久化正确性分别验证。