主题
验证码链
默认顺序：
test_ninettocrgtmanual
统一接口返回：
js
{
ok: true,
provider: "test_nine",
token: "",
costMs: 0
}失败时必须带：
- provider
- reason
- retryable
provider
test_nine 默认访问本地服务：
text
http://127.0.0.1:9645/pass_uni?gt=...&challenge=...ttocr 支持 GT v3 和 v4，配置 key、接口等参数并启用后参与过码。v3 默认 itemid=388；v4 默认 itemid_v4=488，不会沿用旧配置中 query 的 388。其配置错误或额度不足只停止该接口，后续可继续对应版本的人工方案。
结果轮询默认并至少间隔 2 秒；旧的 1 秒配置仍可读取，实际会提高至 2 秒。同一结果 ID 的查询在当前 Node 进程内串行，不同任务仍可并行。收到明确 IP 封禁响应后，进程内暂停 ttocr 请求 30 分钟，期间继续可用的后续方案；该冷却不跨进程重启保存。主机或代理连接失败（4039）会立即保留错误码并结束当前识别任务，后续有限重试必须重新获取挑战。等待或排队后已经超时的任务不再查询。
排查时区分服务方与失败阶段：TTOCR 的 4039 表示其连接主机或代理失败，不等于本机 IP 被封禁，也不能据此判断模型识别错误；仅凭该响应无法确定具体连接目标。极验官方 SDK 的 60500 表示极验服务端拒绝，与 TTOCR 的错误码分别处理。极验帮助页说明短时间频繁验证可能触发此限制，建议间隔 30 分钟再试；出现该码时停止连续造题，保留请求时间，不能用冷却期内的重复失败证明参数或模型有问题。即使载题成功，也以业务二次校验成功为最终依据。参见 TTOCR 错误码、极验 Web 错误码及极验用户帮助。
gtmanual 默认对接：
text
https://gt.lotusshared.cn/GTest/register?key=114514人工服务默认使用子模块内置的 Lotus GT-Manual，由荷花管理，支持 v3/v4。TRSS 下挂载共用 HTTP 端口的 /lotus/gt/，公开地址沿用荷花网页配置；没有共用服务时，复用荷花独立网页端口。注册和结果领取使用本机接口，不额外开放 GT 端口。关闭 captcha.gtmanual.internal_enable 后才使用 verify_addr 指定的外部服务；已有独立部署可以继续使用。
外部服务通过健康接口或已知旧版脚本特征识别；连接失败、404 和未知页面不会直接判成旧版。确认旧版后，每次启动给主人私聊建议，每次实际进入人工验证时在请求会话提示“仅支持部分极验 v3”。旧版不支持的 v4 会跳过人工方案，由原业务继续失败或重试流程；无人值守任务仍不进入人工。
人工服务注册后返回限时人工链接及到期时间。页面只处理极验验证，结果由 Lotus 领取后交给原业务校验；人工页面不能直接兑换商品或读取账号。关闭验证弹窗、SDK 错误、提交失败、到期或结果已消费都会结束本次等待，后续尝试重新获取挑战与链接。直接关闭浏览器页面后由任务到期结束等待。人工链接及通知回调不会延长服务返回的有效期。
用户反馈
通知直接说明当前需要做什么：开始时提示正在自动验证，需要人工时立即发送验证链接，通过后提示继续处理原请求，最终未通过则提示重新发送原指令。中间的识别重试保留在日志中，不再发送“检测次数、成功次数、失败次数、已省略通知数”的汇总，避免把一次尝试失败误读成整个操作失败。验证码通过仅表示该验证步骤通过，原指令的最终结果仍由业务输出确认。
JS 签到、米游社业务和全局 mys.req.err handler 都使用同一套 provider 链。
体力、星铁挑战和绝区零 CK 抽卡查询也接入同一条链；抽卡分页与刷新 CK 后的重试会保留人工通知回调。命令中的人工链接立即回复到本次事件，后台体力查询仅私聊 profile 所属 QQ；通知失败不会中断识别。网页发起的签到任务同时提供当前 QQ、当前 profile 的验证码进度与人工链接。
人工链接只在本次任务等待验证期间有效。等待超时后需重新发送原指令并使用新链接；终态通知不再提供已停止轮询的旧链接。通知仅包含安全的状态摘要和数字错误码，服务方的原始响应、凭据及人工结果轮询地址不进入通知。
本地服务使用 onnxruntime-node 和 Sharp，覆盖九宫格、D-FINE 图标以及 YOLO/DINO 图标匹配。无需 Python 或 venv；任务在 worker 中串行执行，超时或取消会释放 worker。本机自动服务只绑定 loopback 地址。统一开机维护会自动准备本地服务，旧的自动启动与模型下载开关已移除。如需连接另行部署的 test_nine，填写远程 endpoint 即可；插件不会为远程地址启动本地监听，仍按 captcha.providers 顺序执行。enable: false 才会跳过 test_nine。
图像预处理使用 JS 实现与 Pillow 对齐的双线性、双三次和 Lanczos 重采样，包括缩小时的抗锯齿、两阶段 8 位舍入及 float32 归一化。九宫格保留原 Python 流程的 quality 75 JPEG 切片往返；底部 40px 目标对这一步尤其敏感。YOLO/DINO 的裁剪框按原流程截断为整数，越界部分补黑，点击使用框中心。
识别模型仍可能误判，极验也可能拒绝提交，不能保证单次通过。九宫格没有同类匹配时会报识别失败，交给现有的重试与 provider 回退，不猜测次高分类。Pillow 只作为算法参考，许可证随源码保留；插件运行和初始化均不需要安装 Python。
本地 v3 点击协议按服务端选择的已核实 SDK 版本构造请求，使用图片阶段返回的 c/s 和 challenge；若 challenge 更新，也会传递到业务校验。动态协议脚本只校验已核实版本的内容哈希并使用对应字段，不执行下载的脚本。遇到未知初始／点击 SDK 或动态协议会报告本地方案失败，进入现有回退链。
v3 使用 gt + challenge，保持本地识别、ttocr、人工的顺序；v4 使用 captcha_id，跳过仅支持 v3 的本地模型，依次尝试 ttocr 的 488 项目和支持 v4 的 GT-Manual。两种结果独立保存：v3 是 validate，v4 是完整的 lot_number、captcha_output、pass_token、gen_time，不能互换；v4 还需校验结果对应当前 captcha_id。ttocr 的 v4 表单字段恰好命名为 gt，其值按官方接口要求填写 captcha_id，这不代表把挑战降为 v3。人工服务不支持 v4、未配置或全部方案失败时，提示在对应官方页面处理。
米游币商城当前官方页面使用 v4。创建挑战、ttocr 或人工识别和商城二次校验分别执行；人工页面取得完整证明也不算业务成功。二次校验返回业务 challenge 后才允许重新提交兑换，保留原请求体并只增加 x-rpc-challenge。Web 手动兑换按外部识别、人工验证、业务二次校验、重试原兑换请求执行；人工链接和进度显示在当前账号的兑换计划中，仅首次人工链接为本轮提供有限等待时间，不因重复出码无限延长。
持续追踪的后台兑换仅使用外部自动识别，不生成或等待人工链接。可重试的识别失败在本轮兑换窗口内按计划间隔重新尝试，每次重新取得挑战；外部未配置、额度不足或处于冷却期时结束本次计划并释放账号锁，追踪规则继续等待后续轮询。识别等待受本轮窗口和取消信号约束。官方请求频率限制仍单独报告并暂停该账号追踪；兑换 POST 的结果不明时保留待核对状态，不自动重发。商城不会借用签到的 v3 参数重放兑换请求。
商城 v4 尚未完成真实业务验收，协议与模拟接口检查通过不代表实际兑换验证一定可用。识别服务的 IP 限制、配置错误或连接失败不能算作识别成功；程序会报告失败，不重复提交同一挑战。
每次识别或业务校验失败后，下一次尝试必须重新请求挑战，切换服务商也一样。v3 刷新若返回已经使用的 challenge 会停止，服务方返回旧 challenge 或旧 validate 也会拦截；v4 的 captcha_id 是可重复的站点标识，但同一 lot_number 只提交一次，即使其他证明字段变化也不复用。未提供刷新方法时不会拿旧挑战反复识别。签到内嵌验证码通过重新请求签到业务获取新挑战；如果重请求时业务已经成功，直接返回该结果。
业务接口的过码流程分别处理：社区使用 BBS 的 misc 接口，战绩风控使用 game_record 的验证接口，星铁和绝区零的 tool 风控使用对应 app_key。签到直接返回的内嵌 challenge 保留原来的三项验证请求头；无法核实的游戏或接口会明确失败，不猜测 app_key。
10041 是官方账号风险限制，不是极验挑战；保留账号异常提示，不触发创建验证码或付费识别。
只有 retcode=0 的响应会按风险标记判断内嵌验证码，1034/10035 则直接进入已核实的验证流程。认证失败及其他失败响应即使夹带旧的 is_risk、success 或 gt_result，也保留原错误，不额外创建挑战或调用识别。识别结果在业务提交前还会校验版本和必需字段；v4 不能降格为 v3 validate，证明不完整或 captcha_id 不匹配也不会报告成功。
非内嵌流程只有在米游社业务二次校验接受令牌后才报告过码成功；业务拒绝后刷新 challenge，继续有限次本地重试及外部／人工回退。身份失效和网络异常会停止本次操作，不作为识别失败反复提交。图标通过极验不代表战绩／tool 的业务校验已经通过，仍以业务返回及后续查询结果为准。
业务验收需以自然触发风控的原请求为起点，保留账号、设备、方法、参数及原响应上下文。脱离原业务主动创建的验证码，即使极验接受，也不能证明战绩／tool 链已通过验收。本地点击请求沿用旧 Python 的固定点击记录、1600 毫秒和鼠标轨迹，尚未完成与实际点击观测一致的改造；图像推理与 Python 对齐不能替代这部分协议验证。当前没有证据证明该既有轨迹是业务拒绝的原因，完整轨迹改造及未遇到自然风控的真实验收延后，保留已验证的现有流程。
战绩验证会保留原始失败请求的路径与该响应的 x-trace-id，在创建、刷新和二次校验时使用同一上下文；缺失 trace 时不会伪造，也不会额外重发业务请求来获取。外部插件若能提供原请求元数据会优先使用，否则仅尝试从其 URL 构建接口还原路径。
签到响应即使 retcode=0，只要 data.is_risk 为真，仍按风控处理；保留对旧版 success=1 的兼容。原神、星铁、绝区零官方签到页使用响应内嵌的 v3 challenge 重试原 /sign，不会借用战绩的 tool app_key。重试后仍有风险标志会报失败，签到成功还需重新查询状态确认。