CAPTCHA #
本文介绍如何使用 SCP-079-CAPTCHA 的机器人实例。
简介 #
本机器人提供对新入群用户的验证审核。群组如开启了免验证模式，用户在成功验证一次后，在一段时间内可以自动在多群免验证。并且，验证流程不会在群内呈现，多人进群也不会造成验证码的刷屏，本机器人力求以最简短最不干扰群组内正常交流的方式提醒用户进行验证。同时，为满足各群组的不同需求，本机器人同时支持设置自定义问题。
所需权限 #
机器人若需正常工作，则在群组中需要如图所示的权限，权限缺失可能将导致机器人退出群组：
PERMISSONS：
运作流程 #
以下介绍机器人的工作流程，在进行使用和设置前，建议您了解此流程。
注意
- 此处介绍的为机器人默认设置的流程，如需查看自定义问题的验证流程，请见「设置自定义问题」一节。
- CAPTCHA 不会对已被管理员限制发言的用户发起验证。主要认为既然该用户被管理员限制发言，那么其是受到了特别处理的，机器人无需对其再次验证。另外避免个别群组同时使用两个验证机器人产生的问题。
提示部分 #
单个用户入群 #
- 机器人将禁言用户，同时机器人将回复用户的入群消息，提供一个按钮 前往验证 ，点击按钮会前往专用验证群组。
- 提示消息中默认以用户 ID 的形式 mention 该用户。群组可通过命令自定义该入群提示。
单用户入群时的默认提示：
多个用户入群 #
- 当多个用户入群时，机器人将禁言用户，同时机器人将回复用户的入群消息，提供两个按钮，左侧按钮为： 我需要验证吗 ，用户点击该按钮，机器人会用弹出窗口的形式回复该用户是否需要验证；右侧按钮为： 前往验证 ，点击按钮会前往专用验证群组。
- 在触发验证的原始群组中，用户验证提示消息只保留最后一条，因此即使多名用户短时间入群，群内也只有一条验证提示消息，该条验证提示消息会显示待验证的用户数量，同时，会以多个不可见的字符在消息内 @ 所有待验证的用户，通常情况下每个用户都能再次得到此条消息的通知提示，防止了稍早入群的待验证用户忽视该验证提示消息。群组可通过命令自定义该入群提示。
多用户入群时的常规提示：
待验证用户点击「我需要验证吗」按钮后，收到的提示：
验证部分 #
需要验证的用户加入专用验证群组中，会触发随机类别的问题——
- 文字形式的数学加减法运算（提供备选按钮）
- 图片形式的数字验证码（可更换问题）
- 图片形式的汉字成语验证码（可更换问题）
- 图片形式的英文字母验证码（可更换问题）
- 图片形式的看图辨物（提供备选按钮）
- 图片形式的数学加减法运算（提供备选按钮）（可更换问题）
- 图片形式的汉字验证码（提供备选按钮）（文字是与食品有关的名称）
举例：用户随机抽到的图片形式的数学加减法运算
如用户在有限时间内正确回答，即验证通过，用户在最初触发验证的群组中将被解除禁言。同时用户将在几分钟后于专用验证群组中被移除。提示中提供一键返回原群组的按钮，方便用户立即回到原待验证群组中。含有返回原群组链接的提示将于几十秒后于专用验证群组中自动删除。
验证通过后的提示：
如用户回答超时，或在有限时间内根本未加入专用验证群组，将导致验证失败。如用户在专用验证群组中回答超时，该用户将在 10 秒后于专用验证群组中移除。初次超时失败将在原始群组中封禁用户，10 分钟后解封，解封后用户可再次加入原始群组触发验证，如果第二次再次超时失败，将在原始群组中永久封禁该用户。
验证超时后的提示：
如用户回答错误，导致验证失败，用户将在 15 秒后在专用验证群组中被移除，错误提示中会留下建议，提醒用户在 10 分钟后可再次加入原始群组中触发验证。回答错误的同时，将在原始群组中封禁用户，10 分钟后解封，解封后用户可再次加入原始群组触发验证。尚未对该类失败的尝试次数做出限制。
验证失败后的提示：
无关人员 #
不需要验证的用户如果加入专用验证群组中，会被机器人踢出。有时用户反复入群，可能不会重复发送入群的服务消息（xxx joined the group），此时机器人将不能够立即踢出这名不需要验证的用户，但机器人会每 10 分钟获取专用验证群组的所有用户，对无关用户进行踢出操作。
开放监督 #
所有 CAPTCHA 所在群组中的所有管理员，可随意加入专用验证群组中查看机器人运行情况。USER、LONG、和 CAPTCHA 将共同保证专用群组中没有任何多余消息。
极端情况应对 #
在大量用户短时间内入群（炸群）时，机器人将触发自动静态消息模式，即，对用户入群消息实行立即删除的操作（不保留任何入群消息）。如果群组开启了自动置顶功能（默认开启），将在此时发送一条独立提示，并将此提示置顶，不再重复发送入群提示消息。当轰炸结束后，自动恢复群组的原置顶。
跨机器人合作 #
与 NOSPAM 合作
CAPTCHA 可以接收来自 NOSPAM 的针对某个用户的验证发起请求。当防广告的机器人 NOSPAM 判断用户应当被封禁时，如果经检查用户加入群组的时间较长，是一名 “老群员”，则将导致 “操作降级”。降级的操作将导致用户的消息被全局删除，但该用户不会被封禁；如果群组中存在 CAPTCHA ，则降级的操作可能不全局删除用户的消息（尽量保持对话的完整性），而是要求用户成功进行一次 CAPTCHA 验证后，方可正常发言。用户验证超时或失败仍旧会被 CAPTCHA 移出群组，10 分钟后解禁。
与 TIP 合作
当群组中有 TIP 机器人，CAPTCHA 会确保用户成功通过验证后，才通知 TIP 进行入群欢迎。
群组设置 #
以下介绍如何在群组中更改机器人的设置。
按钮设置 #
管理员在群内发送：
/config captcha
即可通过 SCP-079-CONFIG 方便地调整机器人设置，机器人将回报前往设置的链接，5 分钟内设置将被锁定，无法再次更改。请记得在完成设置后点击「提交」按钮。
协助删除： 用户验证失败时，令 USER 协助删除该用户所发所有消息（包括该用户入群消息，同时避免机器人在特殊情况下遗漏在成功禁言前用户所发的其他消息）。
禁言模式： 多次验证失败，导致永久惩罚时，选择禁言该用户，而不是封禁该用户。
封禁模式： 首次验证失败，选择直接永久封禁该用户，而不在 600 秒后解禁该用户（不给用户再次尝试的机会）。
自动解禁： 当某名用户在其他群组验证成功，选择自动解除该用户在您的群组中受到的永久性惩罚。
入群提示： 如关闭，机器人将不会发送新用户入群时的验证提示。某些群组可能有这类需求。群组可以在提示关闭后，在置顶消息、群组描述中提供必要说明，并提供 @SCP_079_CAPTCHA 的链接，让用户入群后主动地加入专用群组中进行验证。如群组一定要选择关闭入群提示，我们更推荐管理员在群内发送 /static 命令获取一个永久有效的验证提示消息，该消息同样有两个按钮，群组可在置顶和群组描述中提供该条消息的链接，这样用户即可通过按钮更清楚自己是否需要验证（static 消息只适用于新加入用户有权限查看群组历史消息的情况）。
自动免验证： 开启后，用户在某个群组验证通过一段时间后，将不会再次重复地在其他群组触发验证。即使关闭，用户也会在几分钟内不需验证，这是为了保证用户已被从专用验证群组中移除。
自动置顶： 开启后，当群组短时间内进入大量用户时，机器人将不再重复发送入群验证提示，而是发送一条通用提示，并将此提示置顶，其后保持静默。当群组的入群频率恢复正常状态，并保持正常状态一定时间后，机器人将自动取消置顶，如果群组之前已有置顶，则自动恢复群组原有的置顶消息。置顶产生的服务消息将被 USER 自动删除，以期最小化对群组正常对话的影响
自定义问题： 开启后，当群组设定了自定义问题时，机器人将选取指定的问题提问用户。详情请见「设置自定义问题」一节。
仅手动： 开启后，新用户入群将不再触发验证流程。无论是否开启，管理员都可以使用 /captcha 命令回复某用户，要求该用户进行一次验证（但机器人判断用户不需重复验证时，不会有反应）。
命令设置 #
除使用 /config captcha 外，管理员也可以通过 /config_captcha 命令在群组中手动调整设置：
/config_captcha 功能代号 on|off：开启或关闭某功能 / 模式
功能代号如下：
delete：协助删除restrict：禁言模式ban：封禁模式forgive：自动解禁hint：入群提示pass：自动免验证pin：自动置顶qns：自定义问题manual：仅手动
例如开启自动免验证功能：
/config_captcha pass on
设置自定义提示 #
注意
本节说明的是如何设置「自定义提示」，而不是「自定义问题」。
通过此命令可设置机器人所发送的验证提示：/custom 类别代号 自定义提示内容
类别代号如下：
flood：加群轰炸时的提示manual：手动触发验证时的提示nospam：NOSPAM 降级触发验证的提示single：只有一名待验证用户时的提示static：手动获取的静态消息的提示multi：多名用户带验证时的提示
自定义内容中可以添加与用户相关的代号：
$mention_id：此代号将自动被替换为用户的 ID 并 @ 该用户$mention_name：此代号将自动被替换为用户昵称 并 @ 该用户$code_id：代号将自动被替换为用户的 ID$code_name：此代号将自动被替换为用户的昵称$code_count：此代号仅在multi类别下有效，将替换为待验证用户的数量，例如：3
注意事项：
- 当类别为
nospam时，自定义内容应至少包含$mention_id和$mention_name中的一个- 当类别为
flood和static时，自定义内容不应该包含$mention_id或$mention_name- 仅当类别为
multi时，$code_count代号才会被有效替换- 当设定自定义提示的样式时（链接、加粗、斜体、代码块），请内容遵从 HTML 格式，请见：https://docs.pyrogram.org/topics/text-formatting#html-style
示例，自定义单用户入群时的提示：
/custom single 您好 $mention_name，请您点击下方按钮进行验证，以证明您不是机器人本示例对应的效果：
如需查看某个类别的设置，可如此操作：/custom single
设置自定义问题 #
介绍如何设置自定义问题，以及说明自定义问题的验证流程。
注意：
- 原则上我们不推荐群组使用自定义问题，建议群组有特殊需求时方才使用该功能。
- 设置自定义问题需要与机器人进行私聊。在设计原则上，私聊的设置无法得到「操作可查原则」的保证。因此，若群组开启自定义问题，则认为群组主动放弃这部分设置的公开可查性，因此机器人将对
/qns命令做证据留存，转发至 LOGGING 频道中。- 若群组使用自定义问题，则问题的难易度无法被托管者调控，当前群组验证通过与否对其他群组失去了参考价值，因此 CAPTCHA 将无法对用户产生评分，其他机器人也因此无法更好地评价用户的行为。
- 自定义问题并不能脱离群组进行验证。
- 使用自定义问题时，「自动免验证」功能将失效，因此对于用户来说无法减少重复验证。
自定义问题验证流程 #
单个用户入群 #
- 机器人将禁言用户，同时机器人将回复用户的入群消息，提供问题和备选答案。
- 提示消息中默认以用户 ID 的形式 mention 该用户。群组可通过命令自定义分割线前的入群提示。
单用户入群时的自定义问题：
多个用户入群 #
- 当多个用户入群时，机器人将禁言用户，同时机器人将回复用户的入群消息，提供问题和备选答案。
- 自定义问题模式下，入群提示仍保留叠加特性，由于提示和问题只保留最后一条，因此该多名用户所需回答的题目将保持一致。该条验证提示消息会显示待验证的用户数量，同时，会以多个不可见的字符在消息内 @ 所有待验证的用户。群组可通过命令自定义分割线前的入群提示。
多用户入群时的自定义问题：
回答正确 #
如待验证用户在有限时间内回答正确，机器人将对该用户解除禁言。同时，用户会收到机器人的弹窗提示，告知验证通过。该用户即可在群组中正常发言。
回答错误 #
如待验证用户在有限时间内回答错误，机器人将封禁该用户 n 小时（其中 n = 2(m - 1) ，m 为验证失败次数）。同时，用户会收到机器人的弹窗提示，告知用户回答错误，验证失败，重试需要等待 n 小时。用户可在 n 小时后再次入群触发验证。
待用户回答错误收到的弹窗提示：
如需直接永久封禁该用户，请开启「封禁模式」。
验证超时 #
自定义问题的验证等待时间为 time_captcha 的二分之一。即，当 time_captcha 设置为 240 时（默认），自定义问题等待时间为 120 秒。超时将导致验证失败。
因自定义问题超时导致的验证失败，机器人将封禁相应用户 24 * n 小时（其中 n = 2(m - 1) ，m 为验证失败次数）。用户可在 24 * n 小时后再次入群触发验证。
如需直接永久封禁该用户，请开启「封禁模式」。
启用自定义问题 #
进行设置前，应先启用自定义问题功能，管理员在群组中发送：/config_captcha qns on
请求设置会话 #
管理员在群组中发送：/qns
执行此命令后，将视为群组已主动放弃「操作可查原则」提供的保护。
机器人将回报前往设置的按钮：
/qns命令的回应：
点击回报的按钮与机器人展开私聊，如图：
通过按钮
/start：
该设置会话将维持 600 秒，期间该群组不接受其他管理员的自定义问题设置。若在本次会话中操作超时，则机器人不再会有任何响应。
添加问题 #
添加问题时，命令为 /add，请使用一行三个加号 +++ 来分隔问题、正确答案、错误答案，如果正确答案或错误答案部分，有多个，则用换行分隔。例如：
/add 问题描述
+++
正确答案 1
正确答案 2
+++
错误答案 1
错误答案 2
错误答案 3
注意事项：
- 问题描述不得超过
140字。- 单个答案长度不得超过
64字节，换算即：以全部是汉字为例，字数不得超过21；以全部是英文字符为例，字数不得超过64。- 正确答案和错误答案的总数不得超过
6个。- 群组自定义问题的总数不得超过
20个。- 当设定自定义问题的样式时（链接、加粗、斜体、代码块），请内容遵从 HTML 格式，请见：https://docs.pyrogram.org/topics/text-formatting#html-style
- 只有问题可以设置样式，答案不可设置样式
添加问题：
如图所示，若添加成功，则机器人将回复问题简述，消息下方的按钮仅供效果预览，点击任意按钮将导致按钮消失。
编辑已有问题 #
编辑问题遵从的格式与添加问题类似，命令为 /edit，/edit 后要附加问题编号。例如：
/edit 问题编号 问题描述
+++
正确答案 1
正确答案 2
+++
错误答案 1
错误答案 2
错误答案 3
编辑问题：
群组选择编辑问题而不是删除问题，是为了可保留该问题的统计数据。
删除已有问题 #
删除问题的命令为 /remove，后跟问题编号，例如：/remove 问题编号
删除问题：
除使用 /remove 外，还可使用 /rm，效果相同。
显示所有问题 #
显示问题的命令为：/show
显示所有问题：
如图，将显示该问题的详情，和在群组中的提出次数、通过率、参与率、答错率。
- 提出次数：机器人成功发送出问题的次数
- 通过率：
通过验证人数占提出次数的百分比 - 参与率：
参与回答问题（无论正确或失败）的人数占提出次数的百分比 - 答错率：
回答错误的人数占参与回答问题人数的百分比
当问题数量大于 5 时，将自动以 TXT 文件的形式发送报告。如需手动要求以文件形式显示，则发送：/show file
以 TXT 文件形式显示所有问题：
设置自定义弹窗 #
通过此命令可设置机器人所发送的自定义问题的验证结果弹窗提示：/custom 类别代号 自定义弹窗提示内容
类别代号如下：
correct：回答正确后的弹窗提示wrong：回答错误后的弹窗提示，可接受待等待时间（单位为小时）为参数，使用{}即可代表，例如：回答错误，您需要等待 {} 小时后重试
示例，自定义回答正确后的弹窗提示：
/custom correct 回答正确，欢迎加入！
注意事项：
- 弹窗提示内容不得超过
140字。- 弹窗提示内容不可设置样式。
极端情况应对 #
在大量用户短时间内入群（炸群）时，机器人将回归常规验证模式，并采取常规验证模式的极端情况应对方法，要求所有待验证用户加入专用验证群组进行验证。
实用命令 #
以下介绍本机器人可响应的文字命令。
群组管理员 #
/captcha：手动对被回复的成员发起一次验证/pass：回复某用户的入群消息，使该待验证用户跳过验证/pass @username：令 username 为 @username 的用户在本群中通过验证。此命令亦可在用户尚未加群 / 验证失败时使用。/pass 12345678：令用户 ID 为 12345678 的用户在本群中通过验证。此命令亦可在用户尚未加群 / 验证失败时使用。/static：手动获取一条长期有效的静态验证提示，此提示可用于置顶或引用
SCP-079-CAPTCHA 中的成员 #
/pass：回复某用户的入群消息，使该待验证用户通过验证（对已验证失败的用户无效）
SCP-079-TEST 中的成员 #
/version captcha：检查机器人版本信息
问与答 #
常见问题汇总。
Q：假设程序已经在中文模式下运行，如何满足英文群组的验证需求？
A：同时利用自定义提示、自定义问题、自定义弹窗，可以做到验证环节无任何中文出现。
Q：为什么在非自定义问题模式下，不在群内进行验证的全部流程？
A：有时多个用户在短时间内入群，机器人的大量验证码反而会导致刷屏，对群内的正常对话造成很大干扰。而且，这种刷屏问题不符合项目 “最少发言” 的设计原则。
Q：为什么不采取私聊机器人，而是在专用的验证群组中操作？
A：私聊的验证是可行的，但同时带来了透明度问题。私聊导致机器人的验证流程无法可靠地受到监督，而在专用群组中，CAPTCHA 所在群组的所有管理员都可以随意加入，每个用户的验证流程都是对管理员们可见的，这种更直观的表达增加了机器人的透明度。同时，在群组中的直接展示，利于及时发现验证过程中出现的问题和错误。而且，这种私聊过程中的不透明性不符合项目 “操作可查” 的原则。
Q：如果某用户连续加入了多个群组，触发了多个验证请求后，再去通过了验证，会发生什么？
A：如在 “有限时间内” 通过了一次验证，该用户将同时在所有等待验证的群组中被解除限制（除设置自定义问题的群组外），均可正常发言。
Q：在上一问题的答案中，机器人是如何计算 “有限时间内”？
A：若连续加入了多个群组，则以最开始加入群组（除设置自定义问题的群组外）的时间点为起点，240 秒后为终点，在此期间完成验证才视为有效，否则将导致超时。
Q：假设群组启用了自定义问题模式，当用户入群尚未回答问题的时候，群管修改或删除了该问题，或者群管关闭了自定义问题模式，机器人将如何处理该用户的验证？
A：此情况下，无论用户点击哪个答案按钮，均将通过验证。