Grok Sub2api Ops

Grok Sub2API Operations

范围门禁

继续使用本技能前，同时确认：

1. 对象明确是 Grok/xAI OAuth 账号、xai-*.json、Grok auth 批次，或 grok-build-auth 的正式账号注册/导入流程。
2. 动作至少包含注册、OIDC/OAuth mint/remint/refresh、auth 导入、bridge create/update、指定账号探针、Grok 分组收口、账号恢复处置、出口型 402 恢复或锁定 429 的账号出口预绑定之一。

仅出现 Grok 模型、Sub2API、代理、账号、导入、清理、402/429/5xx 等词语不构成触发条件。以下任务退出本技能，改用对应源码、部署、数据库、协议或网络排障流程：

• Sub2API 通用源码合并、部署检查、数据库 schema/sequence/ID 排序、Redis 或调度器实现分析。
• Codex、CC Switch、Router、Responses/SSE/工具调用、上下文压缩、图片/识图或跨模型子代理兼容。
• Grok2API 架构选型、通用模型路由设计，或不实际迁移/验证 Grok OAuth 账号的方案比较。
• 借用 Grok 注册代理池测试 MetaAPI、签到站点或其他非 Grok 服务，以及一般代理节点测速。
• K12/OpenAI/Codex auth；输入格式未识别时先检查 schema，不因目录名含 cpa_auths 就使用本技能。

复合任务只在实际 Grok OAuth 账号子流程中使用本技能，不让它接管同一任务中的 Router、源码、Redis、数据库设计或通用代理工作。委派子代理时，仅向负责上述账号生命周期动作的子代理显式传递本技能；不得因父任务历史上使用过本技能，就把它写入其他子代理任务或续接摘要的当前要求。继承记录中的“已使用本技能”只是历史事实，不是新任务的触发依据。

按所选模式定义完成标准。注册或恢复必须证明目标账号已完成 OAuth、真实指定账号探针及必要的 Sub2API/分组收口；批量导入必须证明本批 auth 已完成 refresh/可用性判定、精确去重、导入和逐账号 postimport test。Web 注册、SSO、本地 auth、HTTP 2xx、数据库 active 或 schedulable 标记都不能单独证明完成。指定账号探针得到 402/429 额度耗尽仍算账号可用，应保留并等待额度窗口。唯一例外是已有新鲜被动 429 证据的出口预绑定：只以锁定 plan、恢复点、Admin GET 前后状态和 proxy 终态为证据，禁止新增 test，并将结果记为 binding_applied 而非额度恢复。

已有 Auth 批量导入快路径

用户说“把这个目录/这批账号导入 Sub2API”且输入是 xai-*.json 时，只处理这一批，不展开注册、浏览器或 K12 流程：

1. 读取目录或清单，校验 type/auth_kind/email/sub/access_token/refresh_token/base_url，统计数量和文件权限；不要逐文件输出敏感字段。
2. 先按 bridge 的稳定账号名、email 和 subject 精确查询本批在 Sub2API 中是否存在。这一步应是小范围查找，不做全库宽泛扫描。将候选分为新账号和已存在账号，避免本地旧 refresh token 与 Sub2API 已轮换的刷新链竞争。
3. 判断 OAuth 可用性：
   • 新账号：access token 过期本身不是坏号。使用正式 cpa refresh helper 交换 refresh token，成功后原子写回当前 auth，再对 Grok CLI /responses 做一次真实探针。
   • 已存在账号：先对库中精确 account_id 做一次指定账号 test；正常或 402/429 时直接保留并跳过本地 refresh。只有库中账号失效且需要恢复时，才比较 subject、token 时间和 refresh 所有权，经 bridge 更新。
   • 只有 invalid_grant、refresh revoked 或明确身份不匹配才判无效；网络、5xx 和 permission propagation 记为不确定；402/429 记为可用但额度受限。
4. 将候选归类为 create、keep-existing、update、stale-auth 和 identity-mismatch。不要把 access 过期当作停止条件。
5. 写入前只建立一次批次数据库恢复点。通过 hardened bridge 导入 create/update 候选；bridge 负责写前 preprobe、精确 create/update、Grok 分组与调度收口。
6. 对 bridge 返回的每个本批 account_id 执行一次指定账号 postimport test，并核对只绑定 Grok 分组、schedulable=true、官方 CLI base URL。bridge 已完成且返回结构化 postimport test 证据时不要重复测试。
7. 汇总本批：输入数、refresh 成功/失败、probe 分类、已存在数、保留数、新建数、更新数、stale 拒绝数、账号 ID、逐账号 test 结果和最终可用数。

快路径只读取 audit-import-pipeline.zh-CN.md 和所调用正式脚本的相关段落。只有本批 Grok auth 出现 bridge 422、指定账号 429、revoked、注册/OAuth route 代理或 bridge 故障时再读取 runbook.md。不要为已有 auth 批量导入通读注册手册，也不要调用 K12/OpenAI bundle 工具。

402 出口恢复与 429 无探针绑定

用户报告 Grok OAuth 账号批量 402、换出口后恢复，或要求真实 429 到期后继续走已验证出口时，读取 grok-egress-402-warp-429.zh-CN.md。先将账号互斥分为出口型 402、明确额度 429、传输不确定和 OAuth/permission 问题，不混用处理路径。

1. 如果账号已绑定 Resin 逻辑身份 GrokEU.shard-N，使用 scripts/recover_402_resin_lease.py 保留 proxy_id，只删除该 shard 的 Resin sticky lease；每账号 24 小时最多一次指定账号 test，成功后才清 rate limit，首个失败触发全局退避。硬排除所有 429。
2. 非 Resin 的旧固定出口拓扑才使用“改 proxy_id 后 canary”的历史流程；出口型 402 先用一个账号、一个已验证生产出口和唯一一次指定账号 test，通过后再分小波。WARP 只是 canary 候选，不能仅凭品牌进入批量恢复池。
3. 已有被动 snapshot/cooldown 的真实 429 使用 scripts/bind_quota_egress.py 执行 plan -> apply。重新冻结候选、随机种子和均衡映射，写入前建立一次 custom-format 恢复点。
4. 429 路径只允许 GET、临时 schedulable 隔离、PUT proxy_id、恢复 schedulable 和 GET 验收；禁止 /test、生成请求、DELETE temp、清 rate limit/overload 或宣称额度恢复。
5. proxy_id 是账号粘性绑定；随机只发生在 plan 内，apply 必须使用 plan hash 锁定的映射。单账号失败只回滚该账号 proxy 和 schedulable。

Refresh-revoked 快速路径

用户报告“Grok 账号突然少一批”“OAuth refresh 失败后暂停”，或已明确要求删除不可恢复账号、remint 有材料账号时，直接读取 revoked-recovery-fast-path.zh-CN.md，使用本技能 scripts/reconcile_revoked.py。不要重新通读所有注册资料，也不要临时编写删除/remint one-shot。

1. 先用最近的被动审计、数据库 error 和 refresh 日志冻结 revoked ID；不要用全量 Test Connection 生成候选。usage 可能把 status 从 error 清回 active、但保留 schedulable=false，因此 UI 状态变化不能改变已锁定集合。
2. 将 ID 一次分成互斥的 delete/recover 集合。helper 的直接 recover 集合必须有唯一 result 映射和完整 email/password/SSO；只有可收信邮箱但还需重置密码的账号单列待恢复，不得进入 delete。402/429、网络、5xx、permission 和归属不明项同样不得进入 delete。
3. 协议 remint 默认不启用 Playwright，也不依赖 Xvfb；只有显式选择 --playwright-fallback 或 server-client-full 才检查相应浏览器运行时。不要因浏览器路径未就绪阻塞可直接执行的协议恢复。
4. 使用 manifest 模板、一次 custom-format 备份和 helper 的 validate → backup → delete → 单 ID remint canary → 串行 remint → reverify → status 顺序。重复执行 backup 时复用 hash 与 pg_restore -l 均通过的现有恢复点；delete/reverify 按已落盘结果验证后断点续跑。
5. validate 必须把审计 revoked 分区、候选 ID、材料 hash、代理证据和唯一 email/sub 身份写入 validate-results.json；后续写相 scope 不一致即停。只按唯一 email/sub 锁定原 ID并保留现有显示名；bridge 返回值必须是 action=updated 和预期 ID。
6. bridge 内固定执行隔离、清旧 error、语义 postprobe、通过后 promote；helper 收到成功证据后立即重新隔离该账号。全部 remint 完成后，reverify 不重复账号测试，只消费已锁定的 bridge probe 证据逐号 promote；quota 账号保留 probe 写入的当前 cooldown。最终再用官方 Codex CLI、Grok 支持的 high effort，并从日志确认 Grok group/provider/account HTTP 200 且未 fallback。

直接原因与深层根因分开报告：相近 expires_at 会让同批账号在 1 小时 refresh window 和 5 分钟周期内同步触发；invalid_grant/revoked 证明 refresh 链被拒绝，但不能单独证明是旧 auth 覆盖、第二刷新器争用、持久化失败、xAI 批量 revoke 或账号封禁。

批次归档与源文件收口

所有 Grok 注册、已有 auth 导入、恢复和对账批次统一写入项目的 private/runs/<batch-id>/，不要把 checkpoint、auth 副本或临时数据库恢复点散落在 /root、输入目录或通用 /root/backups：

• manifest.json：长期批次索引。只为最终 usable 或 usable_exhausted 账号保存脱敏身份、账号 ID、source/auth hash、created/updated/kept、探针分类、分组和调度验证；失败项只保存数量和无秘密的分类摘要。
• import/checkpoint.json、import/result.json：保存可恢复的批次进度、bridge action、账号 ID 和逐账号验证结果，不保存 token、管理密钥或完整上游响应。
• backup/：仅在写入、回滚或重试窗口内保存本批数据库恢复点。最终验证完成后按用户的备份保留策略保留或删除，并在 manifest 记录路径、hash、状态和删除时间。
• auth/：只保存尚未交接或仍需恢复的精确 auth。Sub2API 成功接管 refresh 链、最终账号验证通过且 manifest 已原子落盘后，按用户明确的 auth 保留/删除策略处理 manifest 精确列出的交接副本；未取得 auth 文件删除授权时保留并记录。不得使用目录通配或模糊名称清理。未完成、瞬时失败、permission、revoked 待恢复和归属不明的 auth 必须保留并标记状态。

完成批次前确认长期记录只包含仍可用账号，批次目录权限为 0700、文件为 0600，并清理本任务创建且已证明不再需要的空目录。/root/backups 只用于另有明确主机级保留策略的长期备份，不是 Grok 批次的默认落点。

定位与读取

服务器项目默认位于 /root/grok-build-auth；用户给出其他路径时先核验仓库身份。寻找以下入口：

OPERATIONS.zh-CN.md
scripts/register_and_import.py
clients/windows/grok_register_ttk.py
scripts/windows_client_preflight.py

新注册、浏览器、服务器协议或 OAuth 恢复任务读取仓库 OPERATIONS.zh-CN.md 的相关章节，不默认通读全文。Windows、CDP、422、429 或 revoked 读取 runbook.md；批量对账、导入、分组和清理读取 audit-import-pipeline.zh-CN.md。只使用正式入口，不运行历史 patch、debug 或 one-shot 脚本。

选择模式

• server-full：服务器协议注册，运行 scripts/register_and_import.py。这是独立可选方式，不是废弃流程。
• client-full：外部 Windows/受控 Edge 注册，运行 clients/windows/grok_register_ttk.py 并经 bridge 推送。
• server-client-full：用户明确授权时，在部署服务器通过 Linux Edge + Xvfb 运行同一客户端，并使用 scripts/run_linux_client_full.py 建立隔离 route、代理和私有产物目录。
• export-only：账号已在用户 Edge 登录，运行本技能 scripts/export_logged_in.py。
• push-only：已有完整且 access 未过期的 xai-*.json，运行本技能 scripts/push_auth.py 幂等重推。
• batch-import：已有一批 xai-*.json，按“已有 Auth 批量导入快路径”统一 refresh、探针、查重、备份、导入和逐账号验证。
• audit-recover：冻结被动 revoked 证据后，使用 revoked 快速路径分流恢复或逐 ID 清理；只有分类不确定时才补指定账号测试。
• egress-recover-402：用单账号 canary 和有上限分波恢复已锁定的出口型 402。
• bind-quota-egress：对已有新鲜 429 被动证据且 proxy 为空的账号执行无探针均衡预绑定。

默认不在服务器混跑协议批次和浏览器客户端。只有用户明确要求服务器模拟客户端，且历史或 canary 已证明 Edge/Xvfb、客户端 venv、代理和 bridge 可用时，才选择 server-client-full；运行期间不得并发启动 register_and_import.py。只有旧的“先 quarantine 写库、再探针筛选”流程废弃。

配置发现与写入门禁

只为当前 Grok 账号注册、auth 导入、恢复或逐账号验证，从 systemd unit 的 EnvironmentFiles、/root/grok-build-auth/private/*.env 和 Sub2API 元数据发现实际 bridge/Sub2API 地址、监听端口、Grok 分组 ID、数据库位置和 credential file。不得把本节扩展为通用 Sub2API 部署或数据库审计，也不得假定固定端口、固定组 ID、容器名或密钥路径。

执行生产写入前确认目标部署、Grok 分组、账号范围和授权。删除账号、清理 auth/邮箱、改分组、改调度、改 proxy 或重置密码前必须：

1. 建立可验证的数据库恢复点。
2. 输出候选账号 ID、脱敏身份、当前分组和最后探针证据。
3. 逐 ID 确认授权和处置理由。
4. 执行后逐 ID 复核，不使用关键词、扩展名或目录通配删除。

服务器协议路径

在 /root/grok-build-auth 先执行单账号 canary：

python3 scripts/register_and_import.py \
  --count 1 \
  --workers 1 \
  --registration-backend protocol-yescaptcha \
  --failure-policy abort \
  --confirm-production-write

成功必须同时满足 manifest、导入前 /responses preprobe、精确账号状态、指定账号 postimport test 和 Grok 分组 /v1/responses。服务器路径不经过 Windows 客户端或 bridge push。

外部 Windows 客户端路径

在外部客户端机器运行预检和注册；--project-dir 指向该机器的仓库副本，不照抄服务器路径：

python scripts/preflight.py --project-dir <windows-project-dir> --config <client-config> --skip-cdp
cd <windows-project-dir>/clients/windows
python grok_register_ttk.py

面向业务统一称为 Sub2API auth。cpa_* 配置键、cpa_auths/ 目录和 cpa_export 模块是现有兼容接口；auth JSON 保持 CLIProxyAPI-compatible schema，不为改名破坏客户端配置。

客户端必须在正式 auth 写盘和 push 前调用 Grok CLI /v1/responses，校验 completed 且只从 assistant output 提取随机 nonce。required 门禁不得被 enabled=false 绕过。只有 pass 才进入正式目录并 push；网络、5xx、permission propagation 进入 pending；402/429 进入 cooldown；明确 revoked 才进入 remint 或删除候选。

bridge 是最终信任边界：写库前 preprobe；写库后指定账号 test。postimport 失败时必须核对 imported、action、账号 ID 和数据库状态，不能把所有 422 都描述成零写入。

Linux/Xvfb 服务器模拟客户端

该模式复用正式客户端，不运行历史 /tmp runner、patch 或反编译产物。执行前确认：

1. 用户明确授权服务器模拟客户端和生产写入。
2. Xvfb :99、Microsoft Edge、clients/windows/.venv、bridge 和至少两个独立代理出口健康。
3. 没有 register_and_import.py 或其他 Grok 注册批次运行。
4. 先建立数据库恢复点，再用 1 route、1 success canary 验证 action=created + probe=passed。
5. 两路批量使用两个独立进程、两个代理 ref、两个私有 route 目录；每路单浏览器，并按本地 auth、bridge action=created 和精确账号 ID 对账。

正式入口：

DISPLAY=:99 python3 scripts/run_linux_client_full.py \
  --target 1 --routes 1 --attempts-per-route 20 --proxy-ref <healthy-ref>

canary 通过后再用 systemd-run --collect 启动两路后台批次。--target 是新增且通过完整门禁的账号数；不要用数据库 ID 增量或全池数量代替本批归因。服务器内存不足、浏览器反复断连或代理出口重复时停止扩并发，保持最多两路。

账号判读

以下分类仅适用于已经绑定到指定 Grok OAuth 账号的 refresh、preprobe、postimport test 或恢复证据。Router、模型调用、图片、上下文、SSE 或普通网关请求返回相同状态码时，不得套用本节结论。

• access token 过期：先 refresh；refresh 成功并通过真实探针即为可用，不能仅因 access 过期拒绝导入。
• 指定账号 test completed：保留并调度。
• 402/429 明确额度耗尽：保留，按 reset/cooldown 暂停或等待；仍算可用。
• 锁定真实 429 只为防止额度到期后回到旧出口时，可以无探针绑定已验证 proxy；保留 snapshot、reset 和 cooldown，并将完成状态写为 binding_applied。
• invalid_grant / refresh revoked：有密码、SSO 或邮箱恢复能力时 remint 并更新原账号；否则列为逐 ID 清理候选。
• permission/TOS：等待资格传播后复测；持续失败且有重复证据时列为逐 ID 清理候选。
• SSL、代理、超时、普通 5xx：只算不确定，不能删除。
• 未绑定分组：先判定是否是旧 quarantine 残留、导入中断或人工配置；不能仅凭无组直接删除。

安全与输出

不回显 token、SSO、密码、邮箱 JWT、管理密钥或代理凭据；不关闭用户 Edge、代理、IDE、Codex 或归属不明进程。报告模式、脱敏账号、精确账号 ID、探针分类、额度状态、分组绑定、bridge action/imported、恢复点、逐 ID 清理结果以及 commit/push 状态。