本页由英文页面机器翻译而来。内容以英文页面为准。 阅读英文页面
决策钩子
决策钩子会在服务器接受某项内容之前,询问你的插件是否接受它。插件从一份固定列表中选出一个判定作为回答。它从不改写任何内容,也不会对账号采取任何操作:它最多只能阻止一条帖子、一次关注、一次注册、一次上传或一次个人资料更改,或者为你的审核员提交一份举报。对账号如何处理由人来决定。
默认情况下不审查任何内容。没有设置钩子地址的服务器不会发起调用,也不会在这上面花费任何时间。本版本保留了此处所述的记录、模式和管理界面。在各条接收路径中,来自其他服务器的帖子询问
inbound.status,来自其他服务器的关注询问 inbound.follow,注册询问 signup.check,上传询问
media.check,本站账号的帖子询问 local.status,其他服务器上账号的个人资料询问 inbound.actor,本站账号的个人资料更改询问 local.profile;其他钩子尚未被调用。
从图的上方往下:
- 审查什么,以及谁在等待。 来自其他服务器的帖子(
inbound.status)、来自其他服务器的关注(inbound.follow)和上传(media.check)在任务中审查。注册(signup.check)在申请人等待时审查,本站账号的帖子(local.status)在作者等待时审查,本站账号的个人资料更改(local.profile)在其所有者等待时审查。来自其他服务器的个人资料(inbound.actor)在服务器获取该账号的任何地方审查:在任务中,也会在某个请求等待时审查,例如来自某台服务器的请求,而该服务器的账号在这里是新的。 - 模式,
hook_<hook>_mode:off不发起调用,observe记录判定但不据此采取任何行动,enforce则据此行动(模式)。 - 你的插件收到
POST /my.plugin.hook.v1.HookService/Check。服务器最多等待plugin_<hook>_timeout,同时最多发起 8 个调用,连续失败 5 次后会在 30 秒内跳过该插件(breaker_open)。 - 判定:
allow接受该对象,flag接受并提交举报,mark_sensitive接受并将其标记为敏感内容,require_approval搁置注册等待审批,drop和reject阻止它且不保留任何内容(注册的reject仅在开启hook_signup_check_reject时生效)。失败是指timeout、error、invalid回答或breaker_open,钩子不接受的回答也算作失败。钩子处于 enforce 时,由hook_<hook>_on_failure决定:pass不经审查地接受该对象,retry不记录决定并再次运行任务,require_approval搁置注册等待审批(插件失败时)。 - 每个钩子和对象记录一条决定,再次运行的任务会读取它,而不是调用插件(决定)。
| 钩子 | 审查内容 | 可以回答 | 插件失败时 |
|---|---|---|---|
inbound.status |
来自其他服务器的帖子 | allow、drop、flag、mark_sensitive |
pass(默认)或 retry |
inbound.follow |
来自其他服务器的关注 | allow、drop、flag |
pass(默认)或 retry |
signup.check |
注册,在 CAPTCHA 和屏蔽列表之后 | allow、require_approval、reject |
pass(默认)或 require_approval |
media.check |
上传的媒体,在任何人能使用之前 | allow、mark_sensitive、flag、reject |
pass(默认)或 retry |
local.status |
本站账号的帖子及其编辑 | allow、flag、reject |
pass |
inbound.actor |
其他服务器上账号的个人资料,在其发生变化时 | allow、drop、flag |
pass(默认)或 retry |
local.profile |
本站账号的个人资料更改 | allow、flag、reject |
pass |
设置 plugin_<hook>_address 可以为钩子指定插件,名称中的点变为 _
(plugin_inbound_status_address)。插件介绍了目标地址、其认证方式,以及如何用
my plugin test --kind inbound.status <address> 测试插件。调用为 POST /my.plugin.hook.v1.HookService/Check。
各个回答的作用:
drop阻止该对象,且不保存它的任何内容。在inbound.actor上,它会保留之前保存的个人资料(见下文)。错误的drop也会悄无声息地让帖子对其关注者隐藏,因此在 enforce 之前,请先在observe中查看钩子会丢弃哪些内容。flag放行该对象,并且每条决定提交一份举报。在inbound.follow上,举报针对发出关注的账号,不指向任何帖子,并在关注被记录后提交;其举报者、类别和备注与帖子的举报相同。在inbound.actor上,举报以同样的方式针对该个人资料所属的账号。mark_sensitive放行该对象,并将其附件显示为敏感内容,直到审核员取消该决定。require_approval搁置注册等待审批。reject拒绝该对象,并显示不透露插件回答任何内容的固定文本。在signup.check上,这还需要下面的设置。在media.check上,它不保留上传的任何内容,包括原始文件(见下文)。在local.status上,作者可以申诉。在local.profile上,个人资料保持原样,且不能申诉(见下文)。
回答可以带有编码的理由(spam、harassment、sexual、violence、illegal、malware、other),以及给审核员的最多 200 个字符的备注。钩子不接受的回答算作失败。
inbound.status 审查的内容
Section titled “inbound.status 审查的内容”对于服务器将要接收的每个帖子的 Create 和每个 Update,服务器会在保存任何内容之前询问。每个修订版本都是独立的对象,有各自的决定。
- 只有当帖子与本站账号相关时才会询问:有本站账号关注其作者、它提及了某个本站账号,或者它位于包含本站帖子的讨论串中。是否有本站账号关注作者并不会进一步缩小范围:插件会收到
any_local_follower,可以据此权衡。仅由中继带来的帖子从不询问,对已保存但不再与本站账号相关的帖子的Update也不询问:其修订版本会不经询问直接保存。 - 来自没有任何本站账号关注的作者的私信帖子不会发送,除非你开启
hook_inbound_status_unfollowed_direct。无论如何设置,本站账号的帖子都不会发送。 - 投票的投票、删除、撤销、点赞、回应和转发从不询问,因此停止插件不会阻止删除的到达。讨论串的获取或转发的获取仍可能通过其他途径带来同一个帖子。
各个回答对帖子的作用:
- 对
Create的drop不保存任何内容,也不创建通知或时间线条目,重新投递会作为重复内容被忽略。对Update的drop不生成修订版本,并保留之前的版本。被丢弃的帖子没有保存,因此对它的在过去一天内发布的Update会被当作新帖子:插件会再次被询问该修订版本,与询问其他任何修订版本一样,它对之前的Create的回答不会沿用。 flag每条决定提交一份举报,举报者是你的实例 actor,类别取自理由(spam和malware为垃圾信息,illegal为法律问题,harassment、sexual和violence为违规,其他为其他),插件的备注作为备注。举报会注明它由审查提交。除非审核员转发它,否则它不会被转发到作者所在的服务器,而且转发从不发送该备注:只发送审核员当时写的文本。处理它不会通知任何人。每条决定各自提交举报,因此一波垃圾信息可能会塞满队列。mark_sensitive标记的是帖子而不是修订版本:无论之后的修订版本得到什么回答,该标记都会保留在这些版本上,直到审核员取消该决定。它会把附件显示为敏感内容,而不改变文本,因此没有附件的帖子看起来没有区别,其他服务器也看不到它。
media.check 审查的内容
Section titled “media.check 审查的内容”服务器会询问本站账号上传的每个文件,无论用途:附件、头像、横幅图片或自定义表情。它只在文件首次处理时、文件就绪之前询问一次,因此在插件做出决定期间没有人能使用它。之后把同一个文件用于其他用途时,会读取已经做出的决定。远程媒体从不询问。
它发送服务器为该文件生成的最小图像,不含元数据,也从不发送原始文件:对于视频或音频文件,发送其封面或内嵌封面的小图像,没有时则不发送图像。同时发送该文件的用途、它是图像、视频还是音频、它的尺寸、播放时长以及是否为动态。替代文本以及账号或帖子的任何信息都不会发送。HookService 协议的 MediaSubject 消息包含这些字段。
各个回答对上传的作用:
reject使处理失败,与服务器无法读取的文件一样:上传者会看到文件无法处理,帖子也无法附加它。服务器不保留被拒绝文件的任何内容。 无论回答如何,处理结束后它都会删除原始文件,被拒绝的文件不会得到处理后的版本。如果你必须保存这类文件或将其报告给某人,你的插件必须在回答时完成:服务器无法把文件还给你。取消reject只会改变其记录。mark_sensitive会在创建帖子或添加该文件的编辑所在的事务中,标记附加该文件的帖子,该标记会一直保留,直到审核员取消该决定,与inbound.status相同。头像、横幅图片或表情没有帖子,因此只记录该决定。flag每条决定提交一份举报,举报者是你的实例 actor。对于附件,举报在附加该文件的帖子发布时提交,并指向该帖子;从未发布的文件不提交举报。对于头像、横幅图片或表情,举报在文件处理时提交,针对上传它的账号。
处理任务最多等待插件 plugin_media_check_timeout(默认 10 秒)。从其他服务器添加自定义表情或批准表情请求时,图像在审核员等待时处理,因此这段等待由审核员承担。
signup.check 作用于来自注册页面和通过登录提供方的注册,在 CAPTCHA 和注册屏蔽列表之后运行,因此被二者之一拒绝的请求永远不会到达插件。使用邀请码的注册从不调用它。它发送申请人输入的电子邮件地址和客户端的 IP 地址;账号此时尚不存在,因此对象的键是该账号将会获得的 ID,再次尝试的申请人是一个新的对象。
钩子处于 enforce 时,这些回答的作用与屏蔽列表相同:
require_approval让注册在 审核 > 注册 下等待,与相同严重程度的屏蔽一样,在任何注册模式下都是如此。请在那里批准或拒绝:取消该决定不会改变注册。- 在你开启
hook_signup_check_reject(服务器设置 > 外部审查,默认关闭)之前,reject不起任何作用。关闭时,reject会在observe中记录,因为它不阻止任何内容,注册会继续进行。开启时,申请人看到的固定文本与屏蔽时相同(“此服务器无法接受此注册。”)。不会写入任何账号,因此取消这样的决定只会改变其记录,申请人需要重新注册。
申请人永远看不到决定的理由或备注。
申请人的请求最多等待插件 plugin_signup_check_timeout(默认 2 秒;请保持较短,因为有人在等待)。这段等待不属于数据库事务。之后失败的注册(例如用户名已被占用)会保留其决定,直到保留期限将其删除。
来自其他服务器的个人资料
Section titled “来自其他服务器的个人资料”inbound.actor 会在服务器接收其他服务器上账号的个人资料时审查它:首次获取该账号时、该账号发送关于自身的 Update 时,以及服务器再次获取它时(服务器每天会对你的用户关注的账号获取一次)。只有当个人资料与已保存的不同时才会询问,因此以相同的个人资料再次获取账号不会发起调用。它审查的个人资料包括:
- 昵称,作为纯文本,
- 简介和个人资料字段,按服务器保存的形式(经过清理的 HTML),
- 头像和横幅图片在其他服务器上的地址。服务器不发送图像。
插件还会收到该账号的地址、所在服务器、用户名,以及该账号对你的服务器而言是否是新的。决定的键是该账号的地址、# 和个人资料的摘要,因此每个不同的个人资料各有一条决定,再次发送相同的个人资料会读取该决定。
各个判定的作用:
drop保留之前保存的个人资料:昵称、简介、字段、头像、横幅图片及其自定义表情都保持原样。服务器仍会保存它收到的其余内容:账号的密钥、收件箱和其他地址、用户名,以及它是否锁定、是否为机器人、是否可被发现和可被收录。没有密钥和地址,服务器既无法验证该账号的活动,也无法向它投递,而锁定和可收录的设置说明了如何关注该账号以及其所有者是否允许收录。在个人资料保持被丢弃期间,再次获取它会读取同一条决定,并保留已保存的个人资料。- 首次获取的账号总是会被保存,因为关注和提及需要它,所以它的
drop会被当作flag处理:保存个人资料并提交举报。决定仍然显示为drop。 flag保存个人资料,并且每条决定针对该账号提交一份举报。
插件失败时,pass 不经审查地保存个人资料,在其再次变化之前服务器不会再询问。使用 retry 时,在插件失败期间,服务器不会保存个人资料发生变化的账号:Update 在其任务中等待,这会像 inbound.status 一样阻塞该账号的其他活动,而在请求等待时进行的获取会失败,因此其账号在这里是新的服务器,其投递会被拒绝,直到插件恢复且对方再次发送。
取消 inbound.actor 的 drop 会从其服务器重新获取该账号:如果对方现在提供的个人资料就是被丢弃的那个,服务器会不调用插件直接保存它;如果之后已有变化,则会询问插件。
local.status 会在服务器创建帖子之前审查你的服务器上账号的帖子,并在服务器保存之前审查每次编辑。作者在等待插件,因此等待时间很短:plugin_local_status_timeout(默认 1 秒)。失败、超时或断路器打开时,总是放行帖子(pass 是其唯一的失败处理方式),而且这段等待不属于数据库事务。
发送什么以及何时发送:
- 只发送注册时间短于
hook_local_status_account_age_days(服务器设置 > 外部审查,默认 7 天;0表示发送所有账号的帖子)的账号的帖子。大多数垃圾信息来自新账号,已经建立信誉的账号不会发送。 - 只发送
public、local和unlisted帖子。private和direct帖子从不发送。 - 作者输入的文本和服务器渲染后的文本、内容警告、语言、是否标记为敏感、图片描述、投票选项、话题标签、它提及的账号数量、帖子将会获得的地址、它回复或引用的帖子(仅地址)、作者的地址和用户名,以及账号的创建时间。不发送媒体。
- 对象的键是帖子将会获得的 ID。使用相同的
Idempotency-Key再次发送帖子,会返回已创建的帖子,而不调用插件;新的尝试是一个新的对象。 - 编辑以同样的方式发送,内容为编辑后的帖子,发送对象账号也相同:即处于
hook_local_status_account_age_days之内的账号。其键是帖子的 ID、#和新修订版本的 ID,因此每次编辑都是独立的对象。 - 开启语音聊天房间时发布的第一条帖子不经过此钩子。
处于 enforce 时,reject 拒绝该帖子,且不保存任何内容。作者会看到固定文本(“此帖子未发布。”)以及申诉的途径;永远看不到理由或备注。flag 放行帖子,并针对其作者提交一份关于该帖子的举报。
对于编辑,reject 只拒绝这一次编辑:帖子保持原样,作者会看到固定文本(“此编辑未保存。”)。编辑不能申诉,因为帖子仍然存在,审核员可以照常对其采取措施。flag 保存编辑并提交一份关于该帖子的举报,allow 则放行。
被拒绝帖子的作者可以在 appeal_window_days(与审核操作的期限相同)内对其提出申诉,每条决定一次。由于服务器没有保存帖子的任何内容,申诉会附带帖子的文本,以及可选的给审核员的备注。不会调用插件。
你的审核员(manage_reports)会收到每条新申诉的通知(通知设置中的 被拒绝帖子的申诉,也可以通过电子邮件接收;点击通知会打开该申诉),并在 审核 >
自动审核 > 被拒绝帖子的申诉 下审查申诉。每条申诉都在单独的页面中打开,显示作者发送的文本:
- 驳回 保持决定不变,并以
hook_appeal_upheld记入审计日志。 - 采纳 在一个事务中取消该决定(以
hook_decision_overridden记入审计日志),并停止将该账号的帖子发送给local.status。被拒绝的帖子不会恢复:作者需要重新发布它。
无论哪种结果,作者都会在来自审核员的通知中收到结果通知,发帖表单也会在拒绝信息下方显示它。通知和表单只说明决定是被维持还是被取消,从不说明理由或备注。第一方客户端通过 GET /api/v1/hook_decisions/{id}/appeal 读取申诉的状态。
因申诉被采纳而被移出钩子的账号,在该账号被删除之前都不会再进入钩子。即使之后它被盗用,local.status 也不会再审查它。
本站个人资料
Section titled “本站个人资料”local.profile 会在服务器保存之前审查你的服务器上账号的个人资料更改。所有者在等待插件,因此等待时间很短:plugin_local_profile_timeout(默认 1 秒)。失败、超时或断路器打开时,总是放行更改(pass 是其唯一的失败处理方式),而且这段等待不属于数据库事务。
发送什么以及何时发送:
- 只发送注册时间短于
hook_local_profile_account_age_days(服务器设置 > 外部审查,默认 7 天;0表示发送所有账号的更改)的账号的更改。 - 只发送钩子所见内容的更改:昵称、简介、个人资料字段、头像或横幅图片。只是锁定账号或更改其发现设置的更改不会发送。
- 昵称、输入的简介和服务器渲染后的简介、每个个人资料字段的名称和值(输入的和渲染后的)、该更改是设置、替换还是删除头像或横幅图片、账号的地址和用户名,以及账号的创建时间。不发送图像。个人资料是公开的,因此该钩子可以使用明文 TCP。
- 对象的键是账号的 ID、
#和该更改将要保存的个人资料修订版本的 ID,因此每次更改都是独立的对象。
处于 enforce 时,reject 只拒绝这一次更改:个人资料保持原样,所有者会看到固定文本(“此次个人资料更改未保存。”),永远看不到理由或备注。不能申诉:所有者可以修改个人资料后再次保存。flag 保存更改,并针对该账号提交一份不指向任何帖子的举报;其举报者、类别和备注与帖子的举报相同。
每个钩子都有一个模式,它是一项实例设置(hook_inbound_status_mode 等),你可以在服务器设置 > 外部审查 下修改,只有在模式不是 off 时,该页面才提供 enforce。更改以 setting_changed 记入审计日志。
| 模式 | 作用 |
|---|---|
off |
不调用任何内容。 |
observe |
记录判定,但不据此采取任何行动。这是所有钩子的默认值。 |
enforce |
根据判定采取行动。 |
钩子只能经由 observe 从 off 切换到 enforce。
超时、错误和无效回答会作为各自的结果(timeout、error、invalid)记录,从不记录为判定。连续 5 次调用失败后,服务器会在 30 秒内跳过该插件,然后尝试一次调用,因此故障期间每个对象都无需等待;被跳过的调用记录为 breaker_open。每个服务器进程各自计数。
之后对该对象如何处理取决于 hook_<hook>_on_failure:
pass不经审查地放行。故障期间垃圾信息可能会进入,但其他一切都不会停止。这是默认值。retry使任务失败,任务会再次运行并再次调用插件,且不记录决定。来自同一个 actor 的任务按顺序运行,因此在此期间该 actor 之后的所有内容都要等待,包括删除,最长约 4 小时 15 分钟。最后一次运行之后,该任务会成为死任务,从而释放其他任务。require_approval搁置注册,交由审核员处理。
对于 media.check,pass 会不经审查地让文件就绪。retry 会让上传保持处理中状态,直到插件回答或任务用完运行次数;在此期间文件永远不会就绪,死任务会让它保持未处理状态,随后由未附加上传的清理将其删除。没有其他任务会等待它。
每个进程同时最多对一个插件发起 8 个调用,等待轮到自己的时间超过钩子期限的调用算作超时。等待情况显示在 my.plugin.slot_wait 中(运行)。请保持 plugin_inbound_status_timeout 较短:在一个调用等待期间,同一个 actor 之后的任务也会随之等待。
在 observe 中,失败从不阻塞任何内容。当某个钩子的调用持续失败时,审核员每天会收到一次该钩子的通知。相关指标为 my.hook.decisions、my.hook.failures 和 my.hook.duration(运行)。
服务器为每个钩子和对象记录一条决定,因此再次运行的任务会读取它,而不会再次调用插件。决定包含钩子、对象的键、模式、结果、理由、备注以及调用所花费的时间。它不包含帖子的任何文本、电子邮件地址或 IP 地址。
审核 > 自动审核(manage_reports)显示过去 7 天的数量和等待时间,以及钩子阻止了什么、在 observe 中本会阻止什么、或无法检查什么。每条决定都在单独的页面中打开,显示其理由、备注和等待时间。从列表或其页面取消决定,会以 hook_decision_overridden 记入审计日志。local.status 的 reject 不在那里取消:其作者对其申诉。
取消的作用取决于回答。mark_sensitive 会失去其标记,而同一帖子上来自审核操作的标记会保留。flag 会保留其举报,你照常处理即可。inbound.status 的 drop 会在服务器保留所接收活动的期间(7 天)内,不询问插件而重新处理收到的帖子;超过这一期间后,界面会提示这一点,取消只会记录这次取消。
取消 inbound.follow 的 drop 会在服务器保留所接收活动的期间(7 天)内,不调用插件而重新执行该关注。超过这一期间后,该关注无法恢复,取消只会留下记录;对方服务器需要发送新的关注。
只有当关注将被记录为新的关注或关注请求时,才会询问钩子。撤回关注(Undo)从不询问,服务器无论如何都会拒绝的关注也不询问:被联邦模式拒绝的关注、来自已迁移或已停用账号的关注、实例 actor 的关注,或互相屏蔽的账号之间的关注,这些会照常被拒绝。为已存在的关注或请求再次发送的关注也不询问:服务器照常回应,如果关注已被接受,则再次接受。被丢弃的关注不会得到回应,因此对方服务器会继续把它显示为已请求。再次发送同一活动会作为重复内容被忽略。
自动产生的效果只有在留下状态时才会记入审计日志,操作者为系统:mark_sensitive、已提交的
flag 以及 require_approval(hook_decision_applied)。drop 和 reject 不保存任何内容,因此它们只留在决定中。
任务 hook.purge_decisions 会在 hook_decisions_retention_days 天后(默认 90,至少 30)删除决定。它会保留现存帖子上的敏感标记所依据的决定、处于保留冻结状态的账号的决定,以及 local.status 对新帖子的、作者仍可申诉或其申诉正在等待审查的每个 reject。对编辑的 reject 不能申诉,因此在保留期限结束后即被删除。申诉随其决定一起删除。删除账号会删除其决定、其申诉以及其对 local.status 的豁免。
告知用户的内容
Section titled “告知用户的内容”当某个钩子有插件且不为 off 时,你的信息页面(/about)会说明正在使用外部审查、它涵盖什么以及向它发送什么。服务器根据你的设置生成这些内容,包括
hook_local_status_account_age_days 和 hook_local_profile_account_age_days 的账号注册时间(或在
0 时说明会发送所有账号的内容),以及
hook_inbound_status_unfollowed_direct 是否会发送这里没有人关注的作者的私信帖子。
发送什么,以及成本
Section titled “发送什么,以及成本”调用次数、成本和发送的数据会随服务器接收的量而增长,尤其是 inbound.status:范围内的每个帖子都是一次调用,每个修订版本又是一次。在开启钩子之前,请检查你要发送的内容:
inbound.status和local.status会发送帖子的文本,并拒绝明文 TCP,回环地址也不例外。inbound.status发送远程服务器发送的内容:其各种语言的文本、内容警告、是否标记为敏感、发布时间、帖子的地址和 URL、其回复的帖子的地址、附件的地址和描述(不含媒体)、投票选项、话题标签、作者及作者所在的服务器、可见范围,以及帖子提及的账号数量和其中本站账号的数量。它还会发送是否有本站账号关注该作者(any_local_follower),这属于关于你的用户的数据。仅关注者(private)帖子与公开帖子一样发送,私信帖子则如上文所述。对于其回复的帖子,除地址外不发送任何内容。local.status发送本站帖子下列出的字段。HookService协议的InboundStatus消息包含这些字段。signup.check发送每个申请人的电子邮件地址和 IP 地址,并拒绝明文 TCP。inbound.follow发送关注的双方。inbound.actor发送其他服务器上账号的公开个人资料(如来自其他服务器的个人资料下所列),可以使用明文 TCP。每当这样的个人资料发生变化时都会调用它,因此其调用量取决于你的服务器所知道的账号数量。media.check发送每次上传的最小处理后图像,从不发送原始文件,同时发送文件的用途、类型、尺寸和时长。由于它不发送文本,可以使用明文 TCP:但处理后的图像仍可能显示出某个人。local.profile发送本站个人资料下列出的公开个人资料,不发送图像。它可以使用明文 TCP。
供 LLM 和编程智能体使用:llms.txt,llms-full.txt, llms-small.txt