Ai玩家详细教程：宏变量系统

4. 宏变量系统（Macros）

宏（Macro）是平台文本字段中的动态占位符，格式为 {{宏名}}。平台在将内容发送给 AI 之前，会自动将宏替换为对应的实时值——AI 只会看到替换后的结果，不会看到原始宏语法。

适用字段

宏可以在以下字段中使用：

• 开场白（First Message）
• 备用开场白（Alternate Greetings）
• 角色描述（Description）
• 性格摘要（Personality）
• 场景（Scenario）
• 系统提示词（System Prompt）
• 后置指令（Post History Instructions）
• 记忆书条目内容
• 对话示例（Message Example）

4.1 基础用法

在任意支持宏的字段中，直接写入 {{宏名}} 即可：

今天是 {{date}}，当前时间 {{time}}。
你正在与 {{user}} 进行对话。

AI 实际收到的内容（运行时替换后）：

今天是 2024-03-15，当前时间 14:30:00。
你正在与 Alice 进行对话。

4.2 宏完整参考表

角色与用户

{{user}} 的解析优先级如下：

1. 会话人设中的 callName
2. 会话人设中的 name 或 nickName
3. 当前登录用户的昵称
4. 当前登录用户的用户名
5. 默认值 用户

时间与日期

datetimeformat 支持的格式符：

示例：

{{datetimeformat YYYY年MM月DD日 HH:mm}}  →  2024年03月15日 14:30
{{datetimeformat DD/MM/YYYY}}            →  15/03/2024

time_UTC 偏移格式支持 +N、-N，也支持半小时偏移如 +5:30：

{{time_UTC+8}}    →  当前北京时间
{{time_UTC-5}}    →  当前美东时间（EST）
{{time_UTC+5:30}} →  当前印度时间（IST）

聊天历史

随机与工具

{{roll}} 支持标准 D&D 骰子语法：

• {{roll:d6}} → 随机 1–6
• {{roll:2d6}} → 随机 2–12
• {{roll:d20+5}} → 随机 6–25

本地变量（当前对话）

本地变量与 $charx.variable API 共享同一套数据，宏修改和 JS 修改互相可见。

全局变量（跨对话，角色级）

全局变量以「用户 + 角色卡」为作用域，跨对话会话持久保存。

4.3 宏语法规则

单冒号 vs 双冒号

带参数的宏支持两种分隔语法：

{{random:苹果,香蕉,橙子}}          ← 单冒号，逗号分隔参数
{{random::苹果::香蕉, 橙子::西瓜}}  ← 双冒号，参数本身可包含逗号

变量操作宏只支持双冒号语法：

{{getvar::hp}}           ✅
{{setvar::name::Aria}}   ✅
{{setvar:name:Aria}}     ❌ 单冒号不被识别为变量宏

注释宏

{{// 这段内容不会被 AI 看到，仅供创作者备注使用}}

注释宏在发送前完全移除，常用于在系统提示词或记忆书中添加说明性备注，方便维护。

大小写不敏感

宏名不区分大小写，以下写法完全等价：

{{Char}}  {{CHAR}}  {{char}}  → 全部替换为角色名

未识别的宏

如果宏名无法识别（如 {{unknownMacro}}），平台会保留原始文本不做替换，AI 将看到字面量 {{unknownMacro}}。

4.4 实战示例

示例一：在系统提示词中注入当前时间

你是 {{char}}，当前时间是 {{time}}（{{weekday}}），日期是 {{datetimeformat YYYY年MM月DD日}}。
请根据时间给出自然的问候语。

AI 收到的实际内容（运行时）：

你是 Aria，当前时间是 14:30:00（Friday），日期是 2024年03月15日。
请根据时间给出自然的问候语。

示例二：随机开场情境

在开场白或场景字段中使用随机宏，每次对话都有不同起点：

{{char}} 此刻正在{{random::星港酒吧喝咖啡::边境集市巡逻::机库修理飞船}}，{{user}} 找上门来，打断了她。

每次创建新对话时，情境都会随机变化，增加角色的新鲜感。

示例三：D&D 风格技能检定

在系统提示词中结合骰子宏，要求 AI 根据随机结果描述剧情：

【本轮行动检定】
技能骰结果：{{roll:d20}}（满分 20）

请根据以上骰子结果描述本轮行动是否成功：
- 1–9：失败，出现意外状况
- 10–15：普通成功，达成目标但有代价
- 16–20：大成功，超预期完成，额外奖励

示例四：用变量宏动态调整 AI 行为

在后置指令（Post History Instructions）中读取当前好感度，让 AI 根据状态调整态度：

【当前关系状态】
{{user}} 与 {{char}} 的好感度：{{getvar::affection}} / 100

{{// 根据好感度动态调整角色行为指引 }}
- 好感度 < 30：{{char}} 态度冷漠，言辞简短，不愿多谈
- 好感度 30–70：{{char}} 保持礼貌但有距离感，偶尔展示温度
- 好感度 > 70：{{char}} 对 {{user}} 表现出明显的信任和温柔

结合 <charx_vars> 使用：在系统提示词中要求 AI 每轮更新 affection 变量，后置指令中的 {{getvar::affection}} 就能实时反映最新状态，形成动态的关系系统。

示例五：全局解锁追踪

用全局变量记录玩家跨对话的解锁进度：

{{// 在系统提示词中注入解锁状态，引导剧情分支 }}
隐藏结局解锁状态：{{getglobalvar::secret_ending_unlocked}}

配合 JS 脚本（$charx.storage）或 AI 输出标记，可实现跨剧情、跨对话的永久状态记忆。

4.5 在编辑器中使用宏参考面板

创作者编辑器为系统提示词和后置指令字段提供了专用的宏辅助工具，帮助你快速查找和插入宏。

全屏编辑模式

点击字段右上角的 「⤢ 全屏编辑」 按钮，进入专属全屏编辑界面：

┌─────────────────────────────────────────────────────────────────┐
│  系统提示词 · 全屏编辑                                    [✕ 关闭]  │
│  右侧宏参考可直接点击插入。编辑完成后点击「保存并关闭」。           │
├───────────────────────────────────────────┬─────────────────────┤
│                                           │  宏参考              │
│  Monaco 编辑器                            │  点击条目即可插入    │
│  （语法高亮 · 自动换行 · 行号显示）         ├─────────────────────┤
│                                           │  🔍 搜索宏...        │
│  你是 {{char}}，当前时间是 {{time}}...     ├─────────────────────┤
│                                           │  ▸ 角色与用户        │
│                                           │  ▸ 时间与日期        │
│                                           │  ▸ 聊天历史          │
│                                           │  ▸ 随机与工具        │
│                                           │  ▸ 本地变量          │
│                                           │  ▸ 全局变量          │
├───────────────────────────────────────────┴─────────────────────┤
│                                    [取消]  [保存并关闭]           │
└─────────────────────────────────────────────────────────────────┘

功能说明：

提示：宏参考面板仅在屏幕宽度 ≥ 1280px（xl 断点）时显示。在小屏设备上使用全屏编辑时，建议先在宏参考中查好宏名，再手动输入。

宏参考搜索

全屏模式和侧边栏的搜索框支持按宏名或描述关键词过滤：

• 输入 time → 显示所有时间相关宏
• 输入 变量 → 显示所有变量操作宏
• 输入 random → 精确找到随机宏