> 规范网页：https://docs.tensuu.com/功能模块详解/05_群提示.html ｜ Markdown：/功能模块详解/05_群提示.md ｜ 文档修订：2026.10.26

# 群提示

这篇帮你做什么：机器人所在群发生入群、退群、被踢、禁言等事件时，自动发出一条你写好的通知或欢迎语。入口：**侧边栏 → 群设置 → 群提示**。

## 适用与不适用

| 你想做的事 | 是否适合本页 | 原因 |
| --- | --- | --- |
| 新人入群时私聊欢迎或群内通知 | 适合 | 对应“新人进群”“进群通知”条目 |
| 退群、被踢、禁言、角色/名片变更、文件上传、撤回时提示 | 适合 | 对应固定事件条目 |
| 修改成员发“帮助”等指令后的回复 | 不适合 | 用[提示设置](23_提示设置.md) |
| 让机器人回答群成员的问题 | 不适合 | 用[问答](15_问答.md) |
| 定时发送公告 | 不适合 | 用[定时任务](12_定时任务.md) |

## 作用范围与工作方式

- 提示按**群**独立配置：顶部选择哪个群，列表和保存就作用于哪个群。本页没有控制台登录账号或角色概念，选群即代表要改该群配置。
- 系统内置 **10 条固定条目**，不能新增、不能删除，只能改“启用状态”和“提示内容”。条目名称、事件类型、发送方式都是固定的。
- 条目由对应的群事件触发；同一事件可以有多条提示，例如新人入群同时存在“私聊欢迎”和“群内进群通知”，两条各自判断开关。
- 提示发送与关键词监控、问答、转发等消息规则是不同入口。它可以在事件到达时发出提示，但不等于替这些规则做匹配或处罚。
- **Spam 清屏提示**不由群事件触发：它由刷屏清理功能命中后按需读取，默认内容为空；内容为空时不会发送。

## 条目速览

| 条目 | 触发场景 | 发送方式 | 默认状态 |
| --- | --- | --- | --- |
| 新人进群 | 新成员入群 | 私聊新人本人 | 启用 |
| 进群通知 | 新成员入群 | 群聊 | 关闭 |
| 退群通知 | 成员主动退群 | 群聊 | 关闭 |
| 被踢通知 | 成员被踢出 | 群聊 | 关闭 |
| 被禁言通知 | 成员被禁言 | 群聊 | 关闭 |
| 角色变更通知 | 成员角色变化 | 群聊 | 关闭 |
| 文件上传通知 | 群内上传文件 | 群聊 | 关闭 |
| 撤回通知 | 群消息被撤回 | 群聊 | 关闭 |
| 名片变更通知 | 群名片变化 | 群聊 | 关闭 |
| Spam 清屏提示 | 刷屏清理命中后按需读取 | 群聊 | 关闭，默认内容为空 |

## 修改一条提示

1. 顶部选好群，在列表中找到条目，点 **操作 → 编辑**。
2. 弹窗上半部分（条目名称、事件类型、发送方式）是固定信息，不能改。
3. 可修改的只有两项：
   - **启用状态**：关闭后该条提示不再生效。
   - **提示内容**：点击下方 **可用变量** 标签可把变量插入到光标位置（变量详见[变量使用指南](../高级功能/变量使用指南.md)）；写错了点 **恢复默认** 一键还原。
4. 点 **确定** 保存，提示“保存成功”。
5. **怎样确认成功**：刷新后核对该条内容和开关是否保持你设置的值，不只看“保存成功”提示。列表上方还有 **自动化运行状态** 卡片，可查看该群配置保存与运行情况。

**不要靠清空内容停发**：编辑时把内容删空再保存，可能提示成功但仍保留旧内容（普通编辑只把非空内容视为修改）。要停止某条提示，请关闭它的 **启用状态**，保存后刷新核对。出厂内容为空的 Spam 清屏提示与这种编辑保存情况不同。

## 模板变量

所有条目都支持 5 个基础变量；事件专用变量以编辑窗的 **可用变量** 标签为准。

| 变量 | 含义 | 注意 |
| --- | --- | --- |
| `{{.user_id}}` | 当事人用户 ID | 入群/退群等事件中的当事人 |
| `{{.nickname}}` | 当事人昵称 | 取不到时可能为空 |
| `{{.group_id}}` | 群标识 | 协议层群号，不是控制台内部编号 |
| `{{.group_name}}` | 群名 | 从本地群资料读取 |
| `{{.time}}` | 渲染时刻 | 是本次提示处理的当前时间，不保证等于事件发生时间 |

常见事件变量还包括 `{{.operator}}`、`{{.duration}}`、`{{.old_role}}`/`{{.new_role}}`、`{{.file_name}}`/`{{.file_size}}`、`{{.message_id}}`、`{{.old_card}}`/`{{.new_card}}`。不适用于当前条目的变量通常渲染为空字符串，不会自动报错。

## 先预览，再等事件

- 点条目的 **操作 → 测试**，会弹出 **测试预览**：显示变量替换后的最终文本，**不会真的发送到群里**。预览中用户 ID 固定显示为 10001、昵称显示为“测试用户”。
- 预览报“模板语法错误”说明内容里的变量写法有误，改正后再保存。
- 真实群里是否按时发出，取决于机器人已接入该群并收到了对应通知事件；预览不能证明投递成功。私聊欢迎还需要机器人具备向该用户发私信的通道，投递失败不会显示在本页。

正例：欢迎语写“欢迎 `{{.nickname}}` 加入 `{{.group_name}}`”，先用测试确认变量替换，再用测试群触发一次真实入群。反例：在入群提示里使用 `{{.message_id}}` 等只属于消息事件的变量，预览或实际发送时得到空值。

## 批量与备份

- 顶部 **批量操作 → 批量启用/批量禁用**：作用于 **当前群的全部 10 条条目**（不需要先勾选行）。
- **导出**：点顶部 **导出**，在“导出群提示”弹窗确认格式为 **CSV (.csv)**，再点 **导出** 才会下载。文件为 UTF-8 带 BOM，列固定为：

  ```text
  event_type,name,send_type,status,content
  ```

- **导入**：上传同格式 CSV，覆盖当前群的配置。规则如下：

| 情况 | 实际行为 |
| --- | --- |
| CSV 中缺少某个 event_type | 该条恢复为内置默认值（整组替换） |
| event_type 未知或行被跳过 | 该行不生效，不会新增条目 |
| 列数少于 5 | 该行跳过 |
| status 不是 `enabled`/`disabled` | 该条保留内置默认状态，内容仍按该行内容写入 |
| name、send_type 列 | 只用于导出展示，导入时忽略 |

导入前先导出留底。导入是**整组替换**，不是只改文件里出现的条目；导入完成后刷新页面核对条目数、状态和内容。若结果提示不明确，先回读再决定是否重试，不要连续覆盖。

## 没成功先检查什么

- 群里没收到提示：条目开关是否打开、内容是否为空（空内容不发送）、机器人是否在这个群、对应事件（如入群/退群）是否真的发生了。
- 提示内容是原文发出、变量没被替换：模板语法错误时，实际发送会退回原文；条目的 **操作 → 测试** 可以提前发现语法问题。若语法正确但变量名不存在，会被替换为空字符串；请从编辑窗的 **可用变量** 标签插入，不要凭未报错判断变量有效。
- 保存报错或开关自动弹回：刷新页面重试；保存失败时页面会恢复到原来的值，不会留下一半的修改。
- 私聊欢迎没收到：检查机器人是否具备私聊能力、对方是否可接收；本页只负责生成和提交提示，平台投递结果需结合日志核对。

## 关闭或改回

- 临时关闭某条：把该条开关关闭，或 **批量操作 → 批量禁用** 全部关闭。
- 恢复默认文案：编辑弹窗里点 **恢复默认**。
- 彻底不用：把所有条目禁用即可，无需删除（条目本身删不掉）。
- 已发出的消息不能靠关闭条目撤回。

## 和其他页面的关系

- **提示设置**（应用设置下）管的是机器人回复指令用的全局文案，与本页按群事件提示互相独立，见[提示设置](23_提示设置.md)。
- 变量写法、语法错误与未知变量的不同后果见[变量使用指南](../高级功能/变量使用指南.md)。
- 判断“保存了但群里没反应”属于哪一步，见[结果判断与排障](../核心概念/结果判断与排障.md#结果层次)。