变量使用指南
这篇帮你做什么：理解群管家各类文案里 {{.变量名}} 占位符的用法——哪里能用、能用哪几个、写错了会怎样。
先分清三件事
- 变量不是通用的。每个功能有自己的一套变量，A 功能的变量拿到 B 功能里不会生效。每条文案编辑窗下方的“可用变量”标签就是当前条目能用的全部变量，点击标签即可插入到光标位置，不需要手打。
- 语法不止一种。群提示、提示设置、问答、智能名片和定时任务使用双花括号带点的模板写法
{{.user_id}}；消息转发没有模板配置，只对原文中的少数非点号形式做字符串替换。缺少括号、漏点、写成中文括号或把两种写法混用，都可能导致替换失败。 - 改完先预览：群提示和问答都带不实际发送的预览（群提示用“测试”，问答用“测试渲染”）；提示设置和定时任务没有同等预览，先在测试群验证。
- 区分“语法错误”和“变量不存在”：前者通常导致预览报错、回复失败或实际发送退回原文；后者在多数功能中只是渲染为空字符串，不会报错。
各功能的变量清单
群提示（群设置 → 群提示）
所有条目都支持 5 个基础变量：
| 变量 | 含义 | 注意 |
|---|---|---|
{{.user_id}} | 当事人用户 ID | 入群、退群等事件的当事人 |
{{.nickname}} | 当事人昵称 | 取不到时可能为空 |
{{.group_id}} | 群标识 | 协议层群号 |
{{.group_name}} | 群名 | 从本地群资料读取 |
{{.time}} | 渲染时刻 | 是本次提示处理的当前时间，不是事件发生时间 |
部分条目还有事件专用变量，编辑弹窗的“可用变量”标签会列全，常见的有：
- 被踢/禁言/撤回通知：
{{.operator}}（操作者）、{{.duration}}（禁言时长）、{{.message_id}} - 角色变更：
{{.old_role}}、{{.new_role}} - 文件上传：
{{.file_name}}、{{.file_size}} - 名片变更：
{{.old_card}}、{{.new_card}}
把只属于消息事件的变量用在入群提示里，通常得到空字符串，不会自动变成有意义的值。
提示设置（应用设置 → 提示设置）
每条提示各自声明可用变量，以编辑弹窗中的“可用变量”标签为准。大体分两类：
- 指令回复类（帮助、各命令清单等）：多为固定文案，常见变量有
{{.user_id}}、{{.group_id}}、{{.nickname}}、{{.reason}}、{{.trigger_keyword}}。 - 查询结果类（查黑白名单、查信用分等）：有成套的结果变量（如
{{.count}}、{{.entries}}），可能包含range结构。这类条目不建议改结构，改动容易导致整条回复失败。
当前限制：页面右上角的“变量说明”弹窗列的是中文占位符（如 {{.用户名}}、{{.用户QQ}}），与实际可用的英文变量名不一致；照它填写会导致变量无法替换。请忽略该弹窗，以编辑窗里的“可用变量”标签为准。
问答（群设置 → 问答词库）
回答支持 6 个变量：
| 变量 | 含义 |
|---|---|
{{.user_id}} | 触发问答的成员 ID |
{{.nickname}} | 触发问答的成员昵称 |
{{.group_id}} | 群号 |
{{.group_name}} | 群名 |
{{.time}} | 回复时刻 |
{{.question}} | 触发命中那条消息的原文 |
问答变量不包含监控记录、警告次数或信用分明细；需要查这些内容时使用对应的查询指令。
智能名片（群设置 → 智能名片）
名片模板支持 8 个变量：{{.nickname}}、{{.nickname_truncated}}、{{.region}}、{{.region_or_default}}、{{.gender}}、{{.gender_code}}、{{.join_time}}、{{.join_verification_info}}。各变量含义与配置联动（如截断长度、地区兜底文案）见智能名片。
定时任务（群设置 → 定时任务）
“发消息”正文是文本模板，但可用值很少：
| 变量 | 定时任务中的实际值 |
|---|---|
{{.group_id}} | 当前任务所属群的协议层群号 |
{{.user_id}} | 空；定时任务没有发起成员 |
{{.trigger_keyword}} | 空；不是关键词触发 |
不要用定时任务期待 {{.nickname}}、{{.group_name}} 等成员或群资料变量；它们不会自动变成个性化内容。语法错误时系统回退发送原文并记录日志。
消息转发（群设置 → 消息转发）
当前转发没有“按模板发送”模式，界面也没有可填的模板。纯文本转发会对原消息正文做有限字符串替换：
| 原文中出现的写法 | 文本转发时的结果 |
|---|---|
{{user_id}} 或 | 替换为来源消息发送者的 ID |
{{group_id}} 或 | 替换为来源群群号 |
{{.user_id}}、{{.group_id}} | 不替换，保留原文 |
| 图片、视频、文件、合并转发等结构化内容 | 按原消息段转发，不做替换 |
这不是常规模板能力，也不保证来源信息被标注。不要依赖它来生成“来自某群/某人”的格式；发送前按原消息内容核对。详见消息转发。
写错了会怎样
先区分 模板语法错误 和 变量名不存在。例如 {{.user_id 缺少右括号，是语法错误；{{.not_a_var}} 括号完整但变量名不存在，是另一种情况。
下面列的是模板语法错误的后果：
| 功能 | 后果 | 怎么发现 |
|---|---|---|
| 群提示 | 预览直接报“模板语法错误”；没预览就保存的话，实际发送时会 退回原文发出（变量原样显示），并留下日志 | 用“测试”预览 |
| 提示设置 | 对应指令执行时 回复失败、什么都不回（不会自动退回默认文案） | 核对实际执行日志及模板语法；修正当前模板，或确认影响范围后使用恢复默认 |
| 问答 | 保存或导入时会拒绝该回答；若运行期仍遇到渲染错误，该次回复不发送，“渲染失败”计数加一 | 看编辑校验和“渲染失败”列 |
| 智能名片 | 本次名片渲染失败，不会回退原文；按调用入口记录错误 | 检查名片格式并重新保存 |
| 定时任务 | 解析或执行失败时 回退发送原文，并记录日志 | 到点后在测试群核对实际文本 |
| 消息转发 | 没有模板语法；带点写法会原样保留 | 按原消息内容核对，不要依赖变量 |
变量名不存在通常不会让整条消息失败，而是渲染为空字符串（各功能均启用缺失变量零值处理）。因此“预览没有报错”只能说明语法通过，不能证明变量名正确；必须对照当前条目的“可用变量”标签。
正例：给群提示写“欢迎 {{.nickname}}”，从可用变量标签插入并预览；给问答写“{{.nickname}}，答案是……”，先测试渲染。反例：把提示设置查询模板里的 {{.entries}} 复制到问答回答里，或把消息转发的 {{user_id}} 当成 {{.user_id}} 使用。