> ## 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.

# YAML API

扩展名：`.yaml` / `.yml`。顶层必须是对象。空文件跳过并 warning；未知扩展名导致编译失败。

## 字段修饰符

键名后缀决定写入方式。解析时先去掉后缀得到基础字段名。

<ParamField body="key" type="scalar | object | array">
  默认。

  * 标量：覆盖
  * 对象：递归合并
  * 数组：整表替换
</ParamField>

<ParamField body="key-start" type="array">
  插入到目标列表开头。
</ParamField>

<ParamField body="key-end" type="array">
  追加到目标列表末尾。
</ParamField>

<ParamField body="key-merge" type="object">
  Map 递归合并，保留目标已有键。
</ParamField>

<ParamField body="key-force" type="any">
  整字段替换，不做合并。
</ParamField>

<ParamField body="angle-wrapped key" type="any">
  字面量字段名。用尖括号包裹后不再解析修饰符后缀。
</ParamField>

`rules`、`proxies`、`proxy-groups` 等列表字段支持 `-start` / `-end`。带 `name` 的对象列表按 `name` 去重，**同名保留最后一次**。

## 同一字段多修饰符时的顺序

1. `force`（存在则结束该字段）
2. `start`
3. 普通 `key` 替换，或保留原列表
4. `end`
5. `merge`

## 示例

```yaml append-rules.yaml icon="file-code" lines theme={null}
rules-end:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - DOMAIN-SUFFIX,lan,DIRECT
```

```yaml patch-dns.yaml icon="file-code" lines theme={null}
dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://dns.alidns.com/dns-query
```

```yaml rules-head-tail.yaml icon="file-code" lines theme={null}
rules-start:
  - DOMAIN-SUFFIX,router.local,DIRECT

rules-end:
  - MATCH,PROXY
```

```yaml hosts-and-dns.yaml icon="file-code" lines theme={null}
hosts-merge:
  router.local: 192.168.1.1

dns-force:
  enable: true
  nameserver:
    - 1.1.1.1
```

```yaml literal-key.yaml icon="file-code" lines theme={null}
"<rules-end>": keep-this-key-name
```