> ## Documentation Index
> Fetch the complete documentation index at: https://yumebox.gal.tf/llms.txt
> Use this file to discover all available pages before exploring further.

# 列表与规则

本页专门说明列表修饰符。所有示例都假设原配置已经存在对应字段。

## `key-start`

将数组项插入原列表开头。

```yaml 插入列表开头.yaml icon="file-code" lines theme={null}
rules-start:
  - DOMAIN-SUFFIX,first.example,DIRECT
```

```yaml key-start 结果 diff.yaml icon="file-code" lines theme={null}
rules:
  - DOMAIN-SUFFIX,first.example,DIRECT # [!code ++]
  - DOMAIN-SUFFIX,old.example,DIRECT
  - MATCH,PROXY
```

错误或无效用法：

```yaml key-start 无效类型.yaml icon="file-code" lines theme={null}
mixed-port-start: 7890
dns-start:
  enable: true
```

这两项不会报错，但 `mixed-port` 是标量、`dns` 是对象，因此不会产生列表插入。

## `key-end`

将数组项追加到原列表末尾。对于 `rules`，原配置中的终端 `MATCH` 段会保留在新增内容之后；新增内容内部顺序不变。

```yaml 追加列表末尾.yaml icon="file-code" lines theme={null}
rules-end:
  - DOMAIN-SUFFIX,last.example,DIRECT
```

```yaml key-end 结果 diff.yaml icon="file-code" lines theme={null}
rules:
  - DOMAIN-SUFFIX,old.example,DIRECT
  - DOMAIN-SUFFIX,last.example,DIRECT # [!code ++]
  - MATCH,PROXY
```

错误或无效用法：

```yaml key-end 无效类型.yaml icon="file-code" lines theme={null}
mode-end: global
```

`mode` 是标量，`mode-end` 不会把它变成列表，也不会覆盖 `mode`。

## `key-merge`

`key-merge` 对不同字段类型有不同结果：

| 字段类型    | 结果                 |
| ------- | ------------------ |
| 普通列表    | 追加数组项。             |
| 命名对象列表  | 追加后按 `name` 去重。    |
| `rules` | 追加后把 `MATCH` 放回末尾。 |
| 对象映射    | 递归合并映射。            |
| 普通对象    | 按字面量键合并，嵌套修饰符不再解析。 |
| 标量      | 忽略。                |

### 列表追加

```yaml key-merge 列表.yaml icon="file-code" lines theme={null}
rules-merge:
  - DOMAIN-SUFFIX,merge.example,DIRECT
```

```yaml key-merge 列表结果 diff.yaml icon="file-code" lines theme={null}
rules:
  - DOMAIN-SUFFIX,old.example,DIRECT
  - DOMAIN-SUFFIX,merge.example,DIRECT # [!code ++]
  - MATCH,PROXY
```

### 映射合并

```yaml key-merge 映射.yaml icon="file-code" lines theme={null}
proxy-providers-merge:
  extra:
    type: file
    path: extra.yaml
```

```yaml key-merge 映射结果 diff.yaml icon="file-code" lines theme={null}
proxy-providers:
  base:
    type: http
  extra: # [!code ++]
    type: file # [!code ++]
    path: extra.yaml # [!code ++]
```

错误或无效用法：

```yaml key-merge 标量.yaml icon="file-code" lines theme={null}
mixed-port-merge:
  value: 7890
```

`mixed-port` 是标量，`key-merge` 会被忽略，不会把端口变成对象。

## `key-force`

`key-force` 直接替换整个字段，并跳过字段类型处理。它适用于清空原列表、替换整个对象或覆盖未知结构。

```yaml key-force 列表.yaml icon="file-code" lines theme={null}
rules-force:
  - DOMAIN-SUFFIX,new.example,DIRECT
  - MATCH,PROXY
```

```yaml key-force 结果 diff.yaml icon="file-code" lines theme={null}
rules:
  - DOMAIN-SUFFIX,old.example,DIRECT # [!code --]
  - MATCH,OLD # [!code --]
  - DOMAIN-SUFFIX,new.example,DIRECT # [!code ++]
  - MATCH,PROXY # [!code ++]
```

同一个基础键同时存在多个操作时，`force` 优先：

```yaml force 优先.yaml icon="file-code" lines theme={null}
rules-start:
  - DOMAIN-SUFFIX,ignored.example,DIRECT

rules-force:
  - MATCH,PROXY
```

最终只剩下 `MATCH,PROXY`，`rules-start` 不会继续执行。

## 简写

这两个写法是列表操作的简写：

| 简写     | 等价写法        | 结果    |
| ------ | ----------- | ----- |
| `+key` | `key-start` | 插入开头。 |
| `key+` | `key-end`   | 追加末尾。 |

```yaml 列表简写.yaml icon="file-code" lines theme={null}
+rules:
  - DOMAIN-SUFFIX,first.example,DIRECT

rules+:
  - DOMAIN-SUFFIX,last.example,DIRECT
```

```yaml 列表简写结果 diff.yaml icon="file-code" lines theme={null}
rules:
  - DOMAIN-SUFFIX,first.example,DIRECT # [!code ++]
  - DOMAIN-SUFFIX,old.example,DIRECT
  - DOMAIN-SUFFIX,last.example,DIRECT # [!code ++]
  - MATCH,PROXY
```

错误或无效用法：

```yaml 简写用于标量.yaml icon="file-code" lines theme={null}
+mode: rule
mode+:
  - global
```

`+mode` 和 `mode+` 只会被识别为列表操作，标量 `mode` 不会被修改。

## `null` 列表项

列表修饰符的值可以是单个值、数组或 `null`：

| 值       | 结果        |
| ------- | --------- |
| 数组      | 展开为多个列表项。 |
| 单个标量或对象 | 作为一个列表项。  |
| `null`  | 不产生列表项。   |

```yaml null 列表项.yaml icon="file-code" lines theme={null}
rules-end: null

rules-start:
  - DOMAIN-SUFFIX,example.com,DIRECT
```

最终只会插入 `DOMAIN-SUFFIX,example.com,DIRECT`。

## 多个操作的顺序

同一个 YAML 文件可以同时使用多个操作。列表字段的顺序是：

```yaml 多个列表操作.yaml icon="file-code" lines theme={null}
rules:
  - MATCH,REPLACED

+rules:
  - DOMAIN-SUFFIX,plus-start.example,DIRECT

rules-start:
  - DOMAIN-SUFFIX,start.example,DIRECT

rules-merge:
  - DOMAIN-SUFFIX,merge.example,DIRECT

rules+:
  - DOMAIN-SUFFIX,plus-end.example,DIRECT

rules-end:
  - DOMAIN-SUFFIX,end.example,DIRECT
```

```yaml 多个列表操作结果 diff.yaml icon="file-code" lines theme={null}
rules:
  - DOMAIN-SUFFIX,plus-start.example,DIRECT # [!code ++]
  - DOMAIN-SUFFIX,start.example,DIRECT # [!code ++]
  - DOMAIN-SUFFIX,merge.example,DIRECT # [!code ++]
  - DOMAIN-SUFFIX,plus-end.example,DIRECT # [!code ++]
  - DOMAIN-SUFFIX,end.example,DIRECT # [!code ++]
  - MATCH,REPLACED
```

如果同一基础键还存在 `key-force`，上面的所有操作都会被跳过。

## `MATCH` 规则

只有原列表中的字符串且逗号分隔后的第一段是 `MATCH`（不区分大小写）时，才会被识别为终端规则。对象、数字和其他规则不会触发移动；覆写文件新增的规则不会再次扫描。

```yaml 终端规则判断.yaml icon="file-code" lines theme={null}
rules-end:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - MATCH,PROXY
  - match,FINAL
```

YumeBox 会从原列表中第一个被识别的位置开始，把后续内容作为终端规则段保留在最后。