# 配置文件

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

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

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

## 文件位置 {#location}

```filetree {title="~/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 {#mappings}

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

```yaml
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
```

### 映射 {#mapping-fields}

| 字段 | 含义 |
| --- | --- |
| `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 规则](/zh/docs/guide/apps/#yaml) |
{.fields}

### 动作 {#action-kinds}

| `kind` | 字段 |
| --- | --- |
| `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 布局中的鼠标、滚动、媒体、剪贴板与睡眠动作） |
{.fields}

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

## app_config.yml {#app-config}

```yaml
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}
```

## 备份 {#backups}

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

## 文件的安全规则 {#safety}

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

---

反链：

- [自定义](/zh/docs/guide/)
- [App 规则](/zh/docs/guide/apps/)
- [设置、菜单栏与统计](/zh/docs/guide/settings/)