> 规范网页：https://docs.tensuu.com/功能模块详解/09_智能名片.html ｜ Markdown：/功能模块详解/09_智能名片.md ｜ 文档修订：2026.10.26

# 智能名片

这篇帮你做什么：给 **某个群** 配一条"名片格式"，机器人按格式自动改写群成员名片（新成员进群、成员发言、定时巡检时检查）；还可以监控名片内容，发现包含敏感词的名片时警告或踢人。入口：**侧边栏 → 群设置 → 智能名片**。

## 开始前确认

- 先在顶部选好群，所有配置只对当前所选群生效。
- 机器人改名片、踢人，都要求机器人在该群有 **管理员** 权限，否则平台会拒绝执行。
- **启用踢出检测会把命中的成员直接移出群聊**。这次踢出本身不带“拒绝再次申请入群”标记，但若本群 **群员事件监控 → 踢出拉黑** 已开启，踢出动作报告成功后会尝试写入本群黑名单（报告成功不等于平台已确认踢出）；写入成功后，该成员再申请入群会被拦。关闭联动不会移除已写入的黑名单，不能一概承诺“重新申请即可”。确定要用了再开。
- 想让部分成员 **保留自定义名片、不被改写**：用本页的 **白名单用户** 或 **忽略名片带**，两者对自动改名和违规检测都生效（见下文"违规检测豁免与限制"）。没有配置豁免时，自动改名会作用于所有被检查成员。
- 适用选择：想把名片统一成固定格式，用本页；只想在名片出现敏感词时处罚、不改名片，打开 **监控名片变更** 并保持三个改名时机关闭即可。

## 配置名片格式

1. 打开 **启用智能名片** 总开关。关闭时本页所有功能都不运行。
2. 在 **名片格式** 里写模板，例如 `{{.nickname_truncated}}-{{.gender_code}}-{{.region_or_default}}`。可用变量共 8 个（页面上有悬浮说明）：
   - `{{.nickname}}` 昵称；`{{.nickname_truncated}}` 按下方"截取昵称长度"截断后的昵称
   - `{{.region}}` 地区；`{{.region_or_default}}` 地区为空时用"地区为空显示"兜底
   - `{{.gender}}` 性别原文；`{{.gender_code}}` 按"性别代号设置"映射后的代号
   - `{{.join_time}}` 入群时间（如 2026-07-21）；`{{.join_verification_info}}` 最近一条入群验证信息（需先打开"使用进群验证信息"）
3. 点击 **可用变量** 按钮可将变量插入光标位置，边写边看 **实时预览**。预览使用内置示例昵称、性别和地区，**不是当前群的真实成员资料**；性别代号未配置时，相应变量可能为空。确认模板后点群选择框旁的 **保存**。
4. **怎样确认成功**：提示"智能名片设置保存成功"；刷新页面（F5）后配置仍在。名片是否真被改写，需机器人在真实群里运行后观察（见下方"它会什么时候改名片"）。

## 自动改名的三个时机

- **进群自动改名**：新成员进群后检查并改写。
- **发言时检测名片**：成员发言时检查并改写。
- **定时自动修改 + 检测周期**：在系统调度到点时巡检全群名片漂移并改回。检测周期单位为分钟，0 表示不启用；它限制本群两次巡检的最短间隔，**不是精确的触发时间**。系统调度间隔较长时，实际等待也会更长，不能把填入 15 分钟理解为每 15 分钟一定执行。

三类时机各自独立开关；任一开关开启且总开关开启时，机器人才会动手。改名是"按需执行"：名片已经符合格式时不会重复提交。

## 违规检测豁免与限制

- **白名单用户**：填用户号码（多个用英文逗号分隔）。豁免按 **被检查成员的号码精确匹配**，空条目不豁免。名单成员的名片 **不会** 被自动改名，也 **不会** 因违规名片被警告或踢出——包括名片变更通知触发的检测在内，当前所有入口都遵守这份名单。
- **忽略名片带**：名片包含所填文字时，同样同时跳过违规检测和自动改名。
- 这份白名单是本页（智能名片）的豁免名单，**不是** 全局或群组黑白名单，也 **不会** 因此赋予权限等级 6；其它功能（监控方案、投票等）处罚该成员时不受本页名单影响。
- 需要临时停止对某个成员的一切名片干预时，把 TA 加入白名单最直接；需要整群停用检测时，关闭 **监控名片变更** 并保存。

## 违规名片检测（警告/踢出）

1. 打开 **监控名片变更**（它同时是违规检测的开关：关着时即使配置了踢出关键词也不会检测）。
2. **踢出名片包含** 填敏感词，多个用英文逗号分隔；匹配按名片里是否 **包含** 这些词判断，不区分大小写。
3. **启用踢出检测** 关着时：命中只按 **警告** 处理（警告行为见[踢人禁言](13_踢人禁言.md)里的警告说明）。开着时：命中 **直接踢出**。这次踢出不带拒绝再次申请标记，但本群 **群员事件监控 → 踢出拉黑** 开启时，动作报告成功后会尝试写入本群黑名单（不代表平台已确认踢出）；写入成功后，再申请入群会被拦。需要允许已在名单中的成员重新申请时，须在[黑白名单](14_黑白名单.md)移出；关闭“踢出拉黑”只影响后续联动，不会移除已有名单。若对方再次进群且名片仍违规，会再次命中。
4. **怎样判断结果**：刷新回读只能确认配置保存；命中与踢出/警告是否落到群里，要分别观察处理记录和实际成员状态。

## 进群验证信息与其他设置

- **使用进群验证信息**：打开后 `{{.join_verification_info}}` 才有内容；数据来自机器人收到的入群申请验证消息（申请走 [入群审核](10_入群审核.md) 或人工审批时都会保存）。
- **截取昵称长度**：0 表示不截断；**地区为空显示**：地区为空时 `{{.region_or_default}}` 显示的内容。
- **性别代号设置**：男性/女性/未知性别分别显示什么代号。
- **检测周期**：见上方"定时自动修改"。
- **清空本群附言记录缓存** 按钮：点击后只弹出成功提示，**并未真正调用后端清理**，附言记录实际不会被清空。
- 页面底部提示的"锁定名片"：当前产品 **没有提供锁定开关或锁定标记**，该提示描述的能力尚未落地。指令确实可以把成员名片改成固定内容（清除名片、改名片为模板 / 管理员 / 群员，私聊确认后批量执行，见[指令设置](04_指令设置.md)），但改出来的名片 **不符合模板时仍会被自动改名改回**。想让指令设置的名片长期保留，把该成员加入本页白名单或让其名片包含"忽略名片带"内容。

### 设置项参考

| 配置 | 含义与取值 | 默认（未保存过配置时） |
| --- | --- | --- |
| 启用智能名片 | 总开关 | 关 |
| 名片格式 | 模板文本，支持 8 个变量；留空时不改名 | 空（必须显式配置才开始改名） |
| 进群自动改名 / 发言时检测名片 / 定时自动修改 | 三个时机独立开关 | 关 |
| 检测周期 | 0–1440 分钟；0 表示不启用定时巡检，且限制的是两次巡检最短间隔 | 0 |
| 截取昵称长度 | 0 表示不截断 | 0 |
| 地区为空显示 | `{{.region_or_default}}` 的兜底文本 | 空 |
| 性别代号（男/女/未知） | 对应 `{{.gender_code}}` 的显示文本 | 空 |
| 使用进群验证信息 | 开启后 `{{.join_verification_info}}` 才有内容 | 关 |
| 白名单用户 / 忽略名片带 | 改名与违规检测共用的豁免 | 空（不豁免） |
| 监控名片变更 | 违规检测与变更提醒的总前置 | 关 |
| 踢出名片包含 | 敏感词，英文逗号分隔，包含即命中，不分大小写 | 空 |
| 启用踢出检测 | 关=命中只警告；开=命中直接踢出（是否随后拉黑取决于群员事件监控的“踢出拉黑”） | 关 |

## 没成功先检查什么

- 名片没人被改：总开关和对应时机开关是否都开了 → 机器人是否在该群且有管理员权限 → 成员是否被本页白名单或“忽略名片带”豁免 → 名片是否已经符合模板。豁免成员不改名，符合模板时也不会重复提交。
- 定时巡检不跑：检测周期是否为 0（0 表示不启用）。
- 违规检测不生效：**监控名片变更** 是否打开（它是检测前置条件）；命中后是踢出还是警告，取决于"启用踢出检测"。
- 保存报错：按[常见问题](../快速入门指南/常见问题.md)的链路核对连接与日志。

## 关闭或改回

- 全部停止：关闭 **启用智能名片** 并 **保存**。
- 只停某个时机：关掉对应的"进群自动改名 / 发言时检测 / 定时自动修改"。
- 停止踢人：关闭 **启用踢出检测**（退回警告）或关闭 **监控名片变更**（彻底不检测）。
- 被改错的名片需在 QQ 群里手动改回；机器人不会批量恢复原名片。

## 和其他页面的关系

- 名片变更提醒的提醒内容在 **群提示** 里配置（本页有跳转按钮）。
- `{{.join_verification_info}}` 的数据来自入群申请，见[入群审核](10_入群审核.md)。
- 警告/踢出动作的保护与限制见[踢人禁言](13_踢人禁言.md)。