# 📔 Rime YAML Custom Patch 语法笔记

## 一、 核心规则与权重

1. **权重排序**：`custom.yaml` > `schema.yaml` > `default.yaml`。
2. **对应关系**：修改 `xxx.schema.yaml` 需创建 `xxx.custom.yaml`。**注意：** `.dict.yaml` 无法被 patch。
3. **最终形态原则**：Patch 作用于编译后的“最终形态”（见 `build/` 文件夹）。若原方案包含 `__include`，需 patch 其引入后的结果，而非 patch `__include` 命令本身。
4. **结构限制**：一个 `custom` 文件顶层**只能有一个** `patch:` 入口。

## 二、 常用引用命令

- `__include: [路径]`：将指定段落内容引入当前位置。
- `__patch: [路径]`：功能类似 include，但可叠加使用（多个 `__include` 只有最后一个生效）。
- `__append: [列表]`：配合 patch 使用，将新列表内容追加到原列表后方实现拼接。

## 三、 语法操作符速查

| 操作类型 | 语法示例 | 说明 |
| :--- | :--- | :--- |
| **全局替换** | `key: new_value` | **慎用！** 会清空该键下的所有原有子项 |
| **局部替换** | `key/subkey: value` | 仅修改特定项，不影响同级其他项 |
| **末尾追加** | `key/+: [list]` | 在列表末尾添加新元素 |
| **特定行替换** | `key/@n: value` | 替换第 $n+1$ 行（索引从 0 开始） |
| **特定行插入** | `key/@before n: value` | 在第 $n+1$ 行前插入，原内容后移 |
| **末尾行替换** | `key/@last: value` | 直接定位并替换最后一行 |
| **删除/失效** | `key/subkey: ` | **不支持 `/-`**。通过将值设为空来使其失效 |

## 四、 关键行为解析

### 1. 局部修改 vs. 覆盖重写

- **推荐（局部）**：`menu/page_size: 10` —— 只改数字，保留 `menu` 下的其他设置（如字体、颜色）。
- **危险（全局）**：`menu: { page_size: 10 }` —— 会导致 `menu` 下除 `page_size` 外的所有配置被**删除**。

### 2. 列表（List）的操作细节

对于 `engine/filters` 等有严格顺序要求的模块：

- **不能直接用 `/+`**：因为 `/+` 默认加在末尾。如果某个引导器（Translator）必须排在前面，加在末尾会导致功能失效。
- **精准定位**：

    ```yaml
    patch:
      engine/translators/@before 0: table_translator@custom_phrase # 插入到首行
      engine/filters/@5: lua_filter@new_filter # 替换第6行
    ```

    *注：`@` 语法后直接跟值，不需要加 `-` 横线。*

### 3. 如何“删除”配置

由于 Rime Patch 不支持 `/-` 语法，删除某行有两种方式：

1. **重写整个段落**：在 `patch` 中重新列出需要的行，剔除不需要的行（最彻底）。
2. **置空法**：`key/subkey: `。虽然键还在，但值为空，通常能停止该功能。

## 五、 缩进与格式

- YAML 严格遵守 **2 空格缩进**。
- 不要在 `patch:` 段落中间插入顶层节点，否则会截断 Patch。
- 外部预设（如模糊音）建议放在文件末尾，通过 `__include` 引入到 `patch` 内部。

---

**💡 提示**：调试 Patch 时，若结果不符合预期，请第一时间检查 `build/` 文件夹下的产物，那是 Rime 真正读取的配置。