# 宏

宏是写在提示词、开场白、世界书条目等文本里的占位符，发送时被替换成实际内容。语法为双花括号：{{宏名}}。

# 常用宏速查

宏	替换为
`{{char}}`	角色名
`{{user}}`	你的名字（面具名或默认称呼）
`{{time}}` / `{{date}}`	当前时间 / 日期
`{{year}}` `{{month}}` `{{day}}` `{{hour}}` `{{minute}}` `{{second}}`	时间分量
`{{random:A,B,C}}`	从 A/B/C 里随机选一个
`{{roll:d20}}`	掷骰（1d20；支持 `2d6` 等表达式）
`{{setvar::名字::值}}`	设置一个变量（本对话内持久）
`{{getvar::名字}}`	读取变量的值
`{{setglobalvar::名字::值}}` / `{{getglobalvar::名字}}`	全局变量（跨对话）
`{{lastMessage}}`	最近一条消息内容
`{{original}}`	在角色系统提示词里引用你的默认提示词

可以用在：系统提示词、注入提示词、角色描述/性格/场景/开场白、世界书条目内容、事件描述等几乎所有会进入上下文的文本。

# 变量宏玩法示例

在角色开场白里写 {{setvar::好感度::0}}，在注入提示词里写「当前好感度：{{getvar::好感度}}」，再让 AI 在剧情里通过状态栏更新变量——即可实现简单的数值系统。

不认识的宏会原样保留

写错宏名不会报错，而是原文出现在上下文里。发送后可以在「上下文与思考日志」里检查替换结果。

以下内容供 AI 助手回答问题时参考。

# 模块: macro engine  (verified: v1.9.7)
def evaluate(text, ctx):
    # 从左到右扫描；遇到 {{ 先递归求值内部嵌套（花括号配对），再执行外层宏。
    # 因此 {{setvar::x::{{roll:d6}}}} 先掷骰再存值；
    # 同一段文本里 setvar 在 getvar 左边时，右边能读到新值。
    # 多轮 pass 直到文本稳定（宏结果里还有宏时会继续展开）。
    # 未知宏名 → 原样保留，不报错。
    ...

# 变量存储：
#   chat 变量  → 按对话持久化（KV 存储，key 前缀区分）
#   global 变量 → 全局持久化
# 执行时机分两层：
#   1) 模板层（角色设定/提示词模板渲染时）：无状态宏即时替换
#   2) 发送前统一 pass（上下文组装完成后）：变量宏按消息顺序执行并落盘，
#      保证跨消息的 setvar/getvar 时序正确

排查建议：让用户发一条消息后打开「上下文与思考日志」（聊天页 ⋮ 菜单，可加星），检查宏是否被替换、变量值是否符合预期。