配置文件

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 时重新加载，保存时也绝不会覆盖它们。
**旧格式可以读取。**早期版本的纯映射列表会被当作带内联动作的映射读取；编辑某条映射时会将其转换为当前格式。