---
title: "AI 指令与宏"
description: "AI 用来改游戏状态的方括号指令，引擎解析它们的顺序，以及所有能写进设定里的宏。"
---

<div v-pre>

# AI 指令与宏

AI 负责写故事。故事里夹着一些很短的指令，比如 `[health: -15]`、`[gold: +50]`，引擎会在玩家看到之前把它们拿掉。玩家读到的是干净的故事，游戏状态在幕后跟着变。

宏的方向正好相反：它是你写在设定里的占位符，比如 `{{char}}`、`{{user}}`，引擎会在 AI 读到之前把它们填好。

还没看过[变量](/zh/creator/variables)的话，先去看那一页。知道了指令改的是什么，指令才好理解。

::: tip 哪些变量用指令
打开了 **精准追踪** 的变量（新建的数值和开关变量默认就开着）由追踪小助手在每次回复后去改，不走指令。AI 看它们是只读的，它给这些变量写的指令会被丢掉。AI 能改的其它变量都靠指令来改：没开精准追踪的变量、没填可选值的文字变量，以及列表/表格变量。在 **AI 权限** 里设成 **AI 只读** 或 **仅引擎（对 AI 隐藏）** 的变量，同样不认指令。
:::

---

## 为什么要有指令

桌面 RPG 里，主持人说「哥布林砍中你的手臂，扣 15 点血」，玩家就在角色卡上擦掉一个数字重写。在 Yumina 里，AI 是主持人，引擎是那张角色卡。

AI 当然可以直接写「玩家现在有 85 点生命」，但那样引擎就得去解析自然语言，弄清楚是哪个变量变了，再算出新值。这很脆弱，也不可靠。

所以 AI 会在叙述的最后写一个结构化的方括号：

```
The goblin's claw rakes across your forearm, drawing a hot line of pain.
[health: -15]
```

引擎看到 `[health: -15]`，减去 15，按最小值/最大值卡住，再把这条指令从文字里删掉。玩家只看到故事，状态面板也跟着更新。

AI 不用自己算数，也不用记上下限。这两件事都由引擎来做。

---

## 指令语法

每条指令都是同一个格式：

```
[variable-id: operation value]
```

方括号里有三部分：**哪个变量**、**做什么**、**用什么值**。

### 全部九种操作

| 操作 | 语法 | 示例 | 效果 |
|------|------|------|------|
| **Set** | `[var: set value]` 或 `[var: value]` | `[location: set "forest"]` | 整个替换变量的值 |
| **Add** | `[var: add N]` 或 `[var: +N]` | `[gold: +50]` | 给数值变量加 N |
| **Subtract** | `[var: subtract N]` 或 `[var: -N]` | `[health: -15]` | 给数值变量减 N |
| **Multiply** | `[var: multiply N]` 或 `[var: *N]` | `[damage: *2]` | 把数值变量乘以 N |
| **Toggle** | `[var: toggle]` | `[has-key: toggle]` | 翻转开关（true 变 false，false 变 true） |
| **Append** | `[var: append "text"]` | `[log: append ", found key"]` | 在文字变量末尾接一段文字 |
| **Merge** | `[var: merge {...}]` | `[stats: merge {"level": 2}]` | 把一个对象浅合并进 JSON 变量 |
| **Push** | `[var: push {...}]` | `[inventory: push {"name": "Sword"}]` | 往 JSON 数组末尾加一个元素 |
| **Delete** | `[var: delete "key"]` 或 `[var: delete N]` | `[config: delete "old-field"]`、`[inventory: delete 0]` | 从 JSON 对象里删掉一个键（带引号的字符串），或者按下标从 JSON 数组里删掉一个元素（数字）。`delete` 后面必须带值，光写 `[var: delete]` 会悄悄变成一次隐式 set。 |

**写进 JSON 变量内部的路径。** `[relations.chars.lin: merge {...}]` 会写进 JSON 变量内部。键还不存在时，这次写入会把它建出来：`merge` 建出对象，`push` 建出只有一项的列表，`add`/`subtract` 从 0 开始算。路径经过一个普通值时（`hp` 是数字却写 `hp.max`）会跳过，不会覆盖。数组元素写成 `list.0.hp` 或 `list[0].hp`。

### 值的写法

- **数字**：直接写，`10`、`3.5`、`-7`
- **字符串**：用双引号，`"forest"`、`"magic sword"`
- **布尔值**：直接写关键字，`true`、`false`
- **JSON**：直接写对象或数组，`{"level": 2}`、`[1, 2, 3]`

### 简写的坑

新手最容易在这里搞混：

```
[health: -10]     → subtracts 10 (shorthand for subtract)
[health: +10]     → adds 10 (shorthand for add)
[health: *2]      → multiplies by 2 (shorthand for multiply)
[health: 10]      → SETS health to 10 (implicit set, NOT add)
```

开头的符号（`-`、`+`、`*`）决定是什么操作。**没有符号就是 set。** 所以 `[health: 50]` 不是加 50，是把当前值换成 50。

想明确设一个负数（很少见，但可以），写 `[health: set -10]`。

### 用 ID 还是显示名

指令里可以用变量的 **ID**（`player-hp`），也可以用 **显示名**（`Player HP`）。引擎有一张名字到 ID 的对照表，两种都认。ID 更可靠，尤其是显示名里有空格的时候。

### JSON 变量的嵌套路径

JSON 变量有嵌套结构时，AI 可以用点号定位到某个字段：

```
[relationships.aria.trust: +10]
[game-state.factions.ember-court.affinity: set 75]
[inventory.0.durability: -1]
```

引擎会自己沿着路径找下去。中间的对象不存在就建出来。所以 AI 可以只改复杂对象深处的一个字段，别的都不动。

---

## 音频指令

音频用的是类似的方括号语法：`[audio: track-id action]`，动作有 `play`、`stop`、`crossfade`、`volume`，还能把音轨串起来。完整的音频指令和例子见[音频设计](/zh/creator/advanced/audio-deep)。

---

## JSON Patch 格式

做复杂操作的时候，尤其是从数组里删东西，引擎支持一种用 XML 包起来的 JSON Patch 格式。从 SillyTavern 迁过来的世界用的也是这种格式。

```xml
<UpdateVariable target="inventory">
<JSONPatch>
[
  {"op": "remove", "path": "/0"},
  {"op": "replace", "path": "/1/durability", "value": 5}
]
</JSONPatch>
</UpdateVariable>
```

支持四种 patch 操作：

| 操作 | 作用 | 示例 |
|------|------|------|
| `replace` | 把某个路径设成一个值 | `{"op": "replace", "path": "/health", "value": 80}` |
| `delta` | 加或减（正数加，负数减） | `{"op": "delta", "path": "/gold", "value": -50}` |
| `insert` | 加一个新的键值对 | `{"op": "insert", "path": "/inventory/torch", "value": 1}` |
| `remove` | 删掉一个键或数组元素 | `{"op": "remove", "path": "/0"}` |

路径用斜杠写（`/health`、`/inventory/0`），引擎内部会转成点路径。

::: details 什么时候用 JSON Patch，什么时候用方括号指令
大多数时候方括号指令更简单，AI 写得也更稳。JSON Patch 适合两种情况：

1. **按下标删数组元素。** `[inventory: delete 0]` 也能用，但处理数组时，有些模型写 JSON Patch 的 `{"op": "remove", "path": "/0"}` 更稳定。

2. **一次改同一个变量的好几处。** 要一次更新一个 JSON 变量的好几个字段时，一个 JSON Patch 块比五条单独的方括号指令清爽。

如果你在给 AI 写行为规则，告诉它用哪种格式。大多数世界只用方括号指令。只有确实要删数组元素、而方括号写法又不够稳的时候，才引入 JSON Patch。
:::

---

## 引擎怎么处理 AI 的输出

AI 回复回来之后，引擎会先过一遍解析流程，玩家才看得到。知道这个顺序，指令没被识别的时候好查原因。

**第 1 步：去掉思考标签。** 有些模型（比如 Gemini）会把内部推理写在 `<thinking>...</thinking>` 里。引擎先把这些删掉。

**第 2 步：提取 JSON Patch 块。** 引擎找出 `<UpdateVariable>` XML 块，转成内部的效果操作。有些模型会把指令包在一个 `json` 代码块里，这些也在这一步被找出来。

**第 3 步：提取音频指令。** 所有匹配 `[audio: ...]` 的内容被拿出来，交给音频系统排队。

**第 4 步：提取 JSON 指令。** 带 JSON 值的方括号指令（`set`、`merge`、`push`、`delete`）被拿出来。它们要先处理，因为 JSON 内容里可能有会让简单正则认错的字符。`[image: …]` 这种嵌图不动。

**第 5 步：提取普通指令。** 所有匹配 `[var: op value]` 的内容，也就是 add、subtract、set、toggle 这些简单操作。

**第 6 步：清理文字。** 拿出来的指令全部删掉。多余的空行合并。得到的是干净的叙述文字，加上一串效果。

之后，[回复处理](/zh/creator/reply-rules)的规则会在这段干净文字上跑一遍。引擎应用这些效果（连同精准追踪的判断），再检查行为。玩家看到的是干净的文字。

::: details 为什么解析顺序重要
JSON 指令要比普通指令先提取，因为像 `[stats: merge {"health": 50, "mana": 30}]` 这样的指令里有冒号和数字，普通的正则会认错。先处理 JSON，引擎就不会误匹配。

指令没被识别，最常见的原因是 JSON 写坏了：大括号没配对，或者少了引号。引擎遇到解析不了的指令会悄悄跳过，不会崩。

完整参考 → [World Spec: Variables](/zh/world-spec/variables)
:::

---

## 宏：设定里的动态文字

宏是写在设定里的占位符，引擎在发给 AI 之前会把它换成真实的值。长这样：`{{char}}`、`{{user}}`、`{{turnCount}}`。

设定写一次，就能跟着情况变。改了角色名字，所有 `{{char}}` 自动跟着改。玩家选了一个人设，`{{user}}` 也跟着变。

### 常用的宏

| 宏 | 换成 | 示例 |
|----|--------|---------|
| `{{char}}` | 当前角色的名字 | Luna |
| `{{user}}` | 玩家的名字（或当前人设的名字） | Kai |
| `{{turnCount}}` | 当前回合数 | 42 |

这三个能覆盖大多数情况。`{{char}}` 和 `{{user}}` 几乎每条设定都会用到。

### 随机宏

| 宏 | 行为 | 示例 |
|----|------|------|
| `{{random::a::b::c}}` | 每次随机选一个 | `{{random::sunny::cloudy::rainy}}` 可能得到「cloudy」 |
| `{{pick::a::b::c}}` | 稳定地选一个，同一回合里结果不变 | `{{pick::red::blue::green}}` 同一回合总是同一个颜色 |
| `{{roll::NdS+M}}` | 掷骰：N 个 S 面骰，再加修正值 M | `{{roll::2d6+3}}` 可能得到 11 |

**`random` 和 `pick` 的区别**：`random` 每展开一次就重新随机，同一条设定展开两次，结果可能不一样。`pick` 用宏在设定里的位置和当前回合数算一个稳定的哈希。同一回合里每次都一样，下一回合可能变。

要变化就用 `random`（天气、人群描写）。同一回合里要前后一致就用 `pick`（角色的衣服被提到两次，得是同一件）。想做 AI 能接着演的骰子机制，就用 `roll`。

### 时间日期宏

| 宏 | 换成 | 示例 |
|----|--------|---------|
| `{{time}}` | 当前时间（HH:MM） | 14:30 |
| `{{date}}` | 当前日期（本地格式） | 2026/5/13 |
| `{{weekday}}` | 星期几 | Tuesday |
| `{{isodate}}` | ISO 格式日期 | 2026-05-13 |
| `{{isotime}}` | ISO 格式时间 | 14:30:00 |
| `{{idle}}` | 距离玩家上一条消息过了多久 | 5 minutes |

这些是现实里的时间，不是游戏里的时间。适合现实时间和虚构时间混着用的世界，或者做挂机检测（「玩家 10 分钟没回，角色发一条担心的消息」）。

### 上下文宏

| 宏 | 换成 |
|----|--------|
| `{{lastMessage}}` | 最后一条消息的全文 |
| `{{lastUserMessage}}` | 玩家的最后一条消息 |
| `{{lastCharMessage}}` | 角色的最后一条消息 |
| `{{model}}` | 正在用的 AI 模型名字 |

### 玩家人设宏

玩家在 **个人主页 → 人设轮播** 里创建人设，也就是带外貌、性格、背景故事的身份。玩家用着某个人设时，这些宏从人设里取值：

| 宏 | 换成 |
|----|--------|
| `{{persona_name}}` | 当前人设的名字 |
| `{{persona_appearance}}` | 外貌描述 |
| `{{persona_personality}}` | 性格特点 |
| `{{persona_backstory}}` | 经历和来历 |
| `{{persona}}` | 上面四项合在一起，再加上人设里额外写的条目 |

**小技巧**：在 **角色和世界** 里放一条叫「关于玩家」的设定，内容写 `{{persona}}`，AI 就一直知道玩家在扮演谁。玩家换了人设，AI 也会自动跟上。

`{{user}}` 用的是当前人设的名字；没用人设的话，用玩家的用户名。两个都不知道时，用这张卡设的默认玩家名，再没有就是「Player」。

### 工具宏

| 宏 | 作用 |
|-------|-------------|
| `{{// comment text}}` | 注释。展开后什么都没有，可以在设定里留笔记，不会发给 AI |
| `{{trim}}` | 吃掉前后的空白。宏留下难看的空隙时，用来精细控制格式 |

### 变量兜底

宏名对不上任何内置宏时，引擎会看它是不是某个变量的 ID。比如有个 ID 是 `mood` 的变量，当前值是「suspicious」，那 `{{mood}}` 就会换成「suspicious」。这只对由字母、数字和下划线组成的 ID 有效：`{{player_hp}}` 可以，`{{player-hp}}` 不行。画布上新建的变量 ID 是一串带减号的随机字符，所以想当宏用，先在变量设置的 **高级** 里给它改一个简单的 **ID**。

既不是内置宏也不是变量的话，引擎就把 `{{xxx}}` 原样留着。不报错，也不会崩。

---

## 好用的做法

### 按比例掉血的战斗

定义一个 `health`（数值，0-100），在行为规则里按武器类型写好伤害范围。AI 写叙述，再在后面带上指令：

```
The bandit's dagger catches you across the ribs — a shallow
cut, but it burns. You stumble back, keeping your guard up.
[health: -8]

You swing your greatsword in a wide arc. The bandit tries to
dodge but catches the blade across the shoulder. He screams.
[enemy-hp: -22]
```

玩家看到的是一场战斗。数字在背后记账。

### 关系递进加条件设定

拿一个数值变量（`aria-trust`，0-100）配几条按阈值发送的设定（画布上的条件设定）。AI 用指令更新信任值，设定系统会按阶段自动调整 AI 对这个角色表现的认知：

- 设定「Aria：戒备」（条件：`aria-trust < 30`）：客气，保持距离
- 设定「Aria：升温」（条件：`aria-trust >= 30 AND < 60`）：会说自己的想法，偶尔笑一下
- 设定「Aria：亲近」（条件：`aria-trust >= 60`）：会示弱，护着你，有只有你们懂的梗

AI 用指令推动数值：一次友好的互动之后写 `[aria-trust: +5]`。（打开了精准追踪的话，改为由追踪小助手来推。）设定系统决定 AI 看到哪个版本的 Aria。两边互相不知道对方存在。它们靠这个变量来传话。

### 用宏写会变的场景描写

一条能跟着情况变的设定：

```
{{char}} looks up as {{user}} enters the room. The current time
is {{time}}, and the weather outside is {{random::clear::overcast::drizzling}}.

{{char}}'s mood seems {{mood}} today.
```

如果角色是 Luna，玩家是 Kai，现在下午两点，`mood` 变量是「tense」，AI 收到的是：

```
Luna looks up as Kai enters the room. The current time is 14:00,
and the weather outside is overcast.

Luna's mood seems tense today.
```

### 掷骰判定

在一条给旁白的指令设定里写：

```
When {{user}} attempts something risky, use the roll result
to determine success. Roll: {{roll::1d20}}. 15+ = success,
10-14 = partial success, below 10 = failure.
```

AI 拿到的是一个实际的数字，可以照着往下写。结果由骰子决定，不用 AI 自己拿主意。

---

## 常见错误

**指令放错地方。** 引擎已经告诉 AI 把指令放在回复最后了。如果某个模型还是写在句子中间，解析照样能用，只是查问题更麻烦。

**指望 AI 算数。** AI 写 `[health: -15]`，减法由引擎来做。别在行为规则里写「算出新的生命值」这种话。AI 只要写对指令，算数和最小/最大值的限制都由引擎处理。

**指令里的 JSON 写错。** 大括号没配对或少了引号，引擎会悄悄跳过这条指令。`merge` 或 `push` 没生效的话，检查一下 JSON 是否合法。引擎不会崩，只是跳过去。

**把 `{{random}}` 和 `{{pick}}` 搞混。** 如果角色的眼睛颜色每次展开都在变，说明你该用 `pick` 的地方用了 `random`。稳定的属性用 `pick`，故意要变化的用 `random`。

**用 JSON Patch 把事情搞复杂。** 除非确实要从数组里删东西，否则就用方括号指令。更简单，AI 写得更稳，也更好查问题。

**忘了 `{{user}}` 会跟着人设变。** 玩家换了人设，`{{user}}` 就变成新人设的名字。通常这正是你想要的，但如果你用 `{{user}}` 的地方不该在一局中途变，要注意这一点。

---

## 另见

- [设计游戏状态](/zh/creator/advanced/variables-deep)：选变量类型、写行为规则
- [写好条目的技巧](/zh/creator/advanced/entries-deep)：在设定里用 `{{宏}}`，以及条件设定怎么设计
- [音频设计](/zh/creator/advanced/audio-deep)：完整的音频指令参考

指令语法和操作规范 → [World Spec: Variables](/zh/world-spec/variables)

</div>
