这是本节的多页打印视图。 .

参考

配置文件、诊断与恢复、隐私、卸载与常见问题。

1: 配置文件
2: 诊断与恢复
3: 卸载
4: 隐私
5: 常见问题

1 - 配置文件

Capslock 的文件存放位置、映射与设置的 YAML 格式、备份，以及未知字段如何被保留。

你不必手工编辑这些文件，这里的一切都可以在应用中修改。它们是普通的 YAML，方便你阅读、纳入版本管理，或通过「导出」和「导入」迁移到另一台 Mac。

文件位置

~/Library/Application Support/com.vonng.capslock/

action_mappings.yml映射、动作与方案
app_config.yml设置
backups/自动快照
Logs/
- Capslock.log诊断日志
ClipboardSlots/加密的剪贴板槽位
usage_stats.json统计计数
hidutil-transaction.json恢复记录

「设置 › 恢复 › 显示配置文件夹」会在访达中打开它。语言选择保存在应用的偏好设置中，剪贴板密钥保存在你的钥匙串中。

action_mappings.yml

文件由三部分组成：由 Capslock 维护的 capslock_profile 块、你的自定义 actions，以及mappings。内置动作从不写入文件。

capslock_profile:
  id: classic-v3
  version: 3.1.0
  runtime_policy:            # 仅在你修改方案行为后写入
    unmapped_keys: passthrough
    modifier_sides: left
actions:
- id: 4C1F0A52-6E2B-4D0B-9C1E-2B7D3F8E9A10
  name: Open Calculator
  action:
    kind: open_app
    bundle_id: com.apple.calculator
    app_name: Calculator
mappings:
- trigger:
    kind: single_tap_hyper
  action_id: builtin.escape
- trigger:
    kind: hyper_plus_key
    key: 72                  # H
    plane: 0
  action_id: builtin.move_left
- trigger:
    kind: hyper_plus_key
    key: 67                  # C
    plane: 8                 # Shift
  action_id: 4C1F0A52-6E2B-4D0B-9C1E-2B7D3F8E9A10

映射

trigger.kind: hyper_plus_key、single_tap_hyper、double_tap_hyper 或 double_tap_modifier
trigger.key: 用于 hyper_plus_key：按键的 JavaScript 键码（72 是 H）
trigger.plane: 用于 hyper_plus_key：0 到 15，即 Command 1、Option 2、Control 4、Shift 8 之和
trigger.modifier: 用于 double_tap_modifier：哪个修饰键
action_id: 内置 ID（如 builtin.move_left），或自定义动作的 id
action: 内联动作，代替 action_id 使用
bindings: 可选的 App 规则

动作

key_combo: target_key，以及 with_ctrl、with_alt、with_cmd、with_target_shift
jump: direction、count
open_app: bundle_id、app_name
command: command、trusted
input_source: input_source_id
hold_modifier: modifier
directional、independent: action（内置动作使用）
native: native_action（Classic 布局中的鼠标、滚动、媒体、剪贴板与睡眠动作）

从你编辑过或导入的文件中读取的 command 动作，即使文件中写着 trusted: true，也要在应用中确认后才会被信任。

app_config.yml

schema_version: 1
hyper_output_mode: classic_compatibility   # 或 native_clean
hold_to_reveal_enabled: true
hold_to_reveal_threshold_ms: 550
hold_reveal_dismiss_mode: action_start     # 或 caps_release
double_tap_window_ms: 200
show_hud: false
hud_duration_ms: 1350
theme_mode: system                         # light、dark
cjkv_fix_strategy: none                    # shortcut_simulation、switching_focus
show_window_on_launch: true
hide_dock_icon: false
stats_show_inline: true
key_remaps: []                             # 例如 {source: right_option, destination: f19}

备份

在一次性替换大量内容的修改之前——例如导入、重新安装 Classic 布局、移除某个 App 的全部规则、修改方案行为——Capslock 会把 action_mappings.yml 复制一份到 backups/，保留最新的 20 份。

文件的安全规则

**未知字段会被保留。**当前版本不认识的键、字段乃至整条记录都会原样写回，因此新版本的配置被旧版本打开后依然完整。
**损坏的文件绝不会被覆盖。**如果 action_mappings.yml 无法读取，Capslock 会先备份它，把配置显示为只读，并在你修复或导入正确的文件之前不会启动。诊断页会报告「配置需要修复」。
**外部修改会被检测到。**在其他编辑器中所做的修改，会在你切回 Capslock 时重新加载，保存时也绝不会覆盖它们。
**旧格式可以读取。**早期版本的纯映射列表会被当作带内联动作的映射读取；编辑某条映射时会将其转换为当前格式。

2 - 诊断与恢复

诊断页上的每项检查及其修复方法、Capslock 如何归还 Caps Lock，以及如何在终端中恢复。

「诊断」页运行一组检查，并为每一项失败的检查给出编号的修复步骤，大多数修复就是同一行上的一个按钮。「刷新」会重新运行所有检查。

检查项

检查	正常	失败时
Caps Lock 映射	Caps Lock 已就绪	未设置、被其他工具占用或无法读取。点「重新启用」或「恢复 Caps Lock」。
F18	F18 空闲	其他工具在使用 F18。移除那条改键后点「重新启用」。
Karabiner-Elements	未检测到，或无冲突	有规则使用 Caps Lock 或 F18，见 Karabiner。
崩溃恢复	无需恢复	上次没有正常退出，已在启动时清理；或另一个 Capslock 正在运行。
辅助功能	已授权	点「打开辅助功能设置」「重新检查」或「重置并重新请求」。
发送按键	已允许	随辅助功能权限一并授予。点「请求权限」「重新检查」或「重置并重新请求」。
读取键盘	正在读取键盘	macOS 停止了事件钩子。点「重新启用」或「全部松开」。
安全输入	关闭	密码输入框或终端的「安全键盘输入」会对所有应用隐藏按键。Capslock 从不关闭它；请关闭该输入框或选项。
Caps Lock 按键	已收到	按一次 Caps Lock，然后点「刷新」。
配置	有效	文件无法读取。点「显示配置文件夹」，修复或替换它。
签名	有效	开发版本。
更新	已启用	此版本不会自动更新，请从官网下载新版本。

「重置并重新请求」会清除 Capslock 的辅助功能和发送按键授权记录并重新请求。当系统设置显示 Capslock 已获授权、检查却仍然失败时使用它；用不同的构建替换应用后可能出现这种情况。

拿回 Caps Lock

操作	作用
「暂停」	松开 Capslock 按住的一切，把 Caps Lock 还给 macOS，并在核对系统映射后显示「已暂停，Caps Lock 一切如常。」
「全部松开」	松开 Capslock 正在按住的所有按键、修饰键和鼠标按键，但不暂停。按键像是卡住时使用。
「恢复 Caps Lock」	暂停，并恢复 Capslock 启动之前的按键映射，然后报告是否核验成功。
「退出 Capslock」	在退出之前做与「暂停」相同的事。

Capslock 只移除它自己添加的内容，其他工具的改键保持不变。

Capslock 意外停止时

当 Capslock 接管 Caps Lock 时，应用内的一个小助手会盯着它。如果 Capslock 崩溃或被强制退出，助手会松开它按住的按键，并把按键映射恢复原状。下次启动时，Capslock 会先再检查一遍，诊断页也会注明上次没有正常退出。

在必要时，Capslock 也会主动让出：当 macOS 不再允许它读取键盘、其他应用修改了系统按键映射，或出现了 Karabiner 规则时，它会停止并归还 Caps Lock，而不是去争抢这个键。睡眠唤醒后，它会重试几次再报告错误。新接入的键盘也会获得映射。

在终端中恢复

如果 Caps Lock 仍然表现异常，先退出 Capslock，再运行：

/Applications/Capslock.app/Contents/MacOS/Capslock --restore-original-caps-lock

它会恢复上一次会话之前的映射，不做任何无法核验的改动；Capslock 仍在运行时它会拒绝执行。诊断页会按你的实际安装路径显示同一条命令，并附带「拷贝」按钮。

不要手动清空映射hidutil property --set '{"UserKeyMapping":[]}' 会删除所有工具的改键，而不只是 Capslock 的。

导出诊断报告

「导出…」会保存 Capslock-Diagnostics.zip，其中包含检查结果和近期日志的脱敏副本。它从不包含你输入的内容、剪贴板、Shell 命令及其输出，也不包含你的配置。报告问题时请附上它。

3 - 卸载

移除 Capslock、它的数据与权限记录，并确认 Caps Lock 恢复正常。

Capslock 没有安装程序，除了辅助功能授权记录外，不会在你的用户目录之外留下任何东西。

从菜单栏图标或用 ⌘Q 退出 Capslock，让它归还 Caps Lock。如果它曾被强制退出、Caps Lock 仍不正常，请在删除应用之前运行恢复命令。
如果你打开过「登录时打开」，在「设置 › 通用」中关闭它。
把 /Applications/Capslock.app 移到废纸篓。
如果还要删除数据，删除以下内容：
- ~/Library/Application Support/com.vonng.capslock
- ~/Library/Preferences/com.vonng.capslock.plist
- ~/Library/Caches/com.vonng.capslock
在「系统设置 › 隐私与安全性 › 辅助功能」中选中 Capslock，点击「−」。
如果用过剪贴板槽位，在「钥匙串访问」中删除名为 com.vonng.capslock.clipboard-slots 的项目。

重启 Mac 也会清除 Caps Lock 映射，macOS 不会在重启后保留它。

4 - 隐私

Capslock 在你的 Mac 上存储什么、从不记录什么，以及仅有的几种联网情形。

Capslock 在本机处理键盘与指针事件，以执行你选择的映射。它不包含任何行为分析或广告 SDK，不发送任何映射、按键、剪贴板、Shell、应用历史或使用数据。

本地存储的内容

Capslock 保存的所有内容都在你的用户目录~/Library/Application Support/com.vonng.capslock/ 下：

你的配置；
剪贴板槽位，使用随机密钥加密，密钥保存在你的钥匙串中；
私有诊断日志，仅你的用户可读；
恢复记录，用于在崩溃后归还 Caps Lock 映射；
按天统计的动作计数，供「统计」页使用。

诊断导出不包含产生的文本、剪贴板内容、Shell 命令及输出、密钥、原始按键历史和完整的应用历史。

Playground

自由练习只保留最近一次物理按键的观察结果，并且仅在 Playground 可见且位于前台时保留。离开该页面或窗口失去焦点时即被清除，从不上传。

网络访问

除非你自己打开某个链接，或正式版通过 HTTPS 更新源检查新版本，Capslock 不发起任何网络请求。开发版本没有更新源，从不检查更新。

你明确信任的 Shell 命令以你的用户权限运行，可以自行读写文件或访问网络，Capslock 不会为它们设置沙箱。暂停、释放全部输入和撤销配置都不会终止已经启动的进程，也不会回退它的效果。导入的配置中的命令，必须重新复核并信任后才能运行。

权限

Capslock 申请 macOS 辅助功能权限，这是它的主动键盘事件钩子所必需的；它不需要输入监控权限。登录时启动是可选项，使用苹果的 SMAppService。

删除你的数据

删除应用即停止运行。你还可以删除 ~/Library/Application Support/com.vonng.capslock、相关的偏好设置与缓存，并在系统设置的辅助功能列表中移除 Capslock。参见卸载。

联系方式

隐私相关问题：rh@vonng.com

5 - 常见问题

关于 Karabiner-Elements、权限、隐私、键盘布局，以及 Capslock 不做什么的简短回答。

需要 Karabiner-Elements 吗？

不需要。Capslock 是独立应用，整套布局都已内置。如果你还用 Karabiner-Elements 管理其他按键，只要没有 Karabiner 规则作用于 Caps Lock 或 F18 就没问题。见与 Karabiner-Elements 共存。

为什么需要辅助功能权限？

要修改按键事件而不只是旁观，macOS 要求使用主动事件钩子，而这需要辅助功能权限。Capslock 不申请输入监控权限，不安装内核扩展或驱动，也不运行任何特权 Helper。

Capslock 会记录我输入的内容吗？

不会。按键只在内存中处理，从不存储或发送到任何地方。日志不记录输入的文字、剪贴板内容和 Shell 输出，「统计」页只保存次数。见隐私。

打字时 Capslock 崩溃了怎么办？

应用内的助手会归还 Caps Lock 并松开所有按住的键。你也可以退出 Capslock 后运行恢复命令。重启同样会清除映射。

还能用 Caps Lock 输入大写字母吗？

可以。⇪ Esc 打开或关闭真正的大写锁定。大写锁定开启期间，Capslock 组合键输出原来的按键，直到你再按一次 ⇪ Esc。

我的键盘没有数字小键盘。

小键盘鼠标键不是必需的。⇪ 加方向键、⇪ ⌥ 加 H J K L，以及 ⇪ Return 都可以移动指针和点击。见鼠标与滚动。

支持 Dvorak、AZERTY 等布局吗？

组合键按物理按键匹配，「键盘」页按你当前的布局显示键帽文字。符号类绑定（例如用 ⇪ [ 输入 (）输入的是美式布局下的字符。

为什么笔记本上的 F1 到 F12 组合键没反应？

如果键盘顶排默认用于调节亮度和音量，按键就不会以 F 键到达。请同时按住 fn，或在「系统设置 › 键盘」中打开标准功能键。

密码框打开时什么都不起作用。

安全输入开启时（例如在密码框中，或打开了终端的「安全键盘输入」），macOS 会对所有应用隐藏按键。Capslock 从不关闭它，诊断页会显示它是否开启。

Capslock 支持 Windows 或 Linux 吗？

不支持，Capslock 是 macOS 应用。这套布局最早是 Windows 上的 AutoHotkey 脚本，它和更早的 Karabiner 版本一起保存在归档中。