HANDOVER.md 28 KB

Coordinate 项目接手报告(Handover Report)

生成时间:2026-08-25(本地时钟) 作者视角:框架架构师 / 项目负责人(接手即用) 本文所有论断均标注【已验证】或【未验证】,验证命令与结果见 §9。

2026-08-30 Italy Query 更新:本地实现及 387 项 Italy 回归【已验证】;15 分钟受控重建 E51【已验证】:909 秒、3 次查询、1 次恢复、监测 OTP/AVANTI/final 均 0、exit 0,源码指纹一致。真实认证过期及 2/24 小时现场运行【未验证】。最新合同、完整终端命令、验收记录与必须完成的 ITA-OTP-01 见 CS3R。本条不更新下面 2026-08-25 的历史环境结论,也不代表 Book/生产上线完成。


2026-08-31 Italy Book 更新:用户回传 v8 实测最终请求 1 次,新增确认回执 Confermata / 2,日期 2026-09-03,分配时间 09:26,历史未变、请求审计通过。网站已显示确认;程序尚未识别新状态/完整归属,仍 unknown / exit 4,勿重跑提交或清除 claim。详见 CS5 §27。598 项为第 26 节先前本地离线证据;真实回传未包含 Book 源码指纹。下一步用已有回执只读完善成功判定,生产 final 仍关闭,跨进程阻断与自动 OTP 仍待完成。

后续本地更新:已接入 Confermata / 2 → ACTIVE,并在原回执工具增加 --expect-confirmed;611 项 Italy 离线测试与 receipt-readonly-confirmed-v4 无网络预检通过。下一步执行 CS5 §28 的只读命令,不重跑预约。成功时表示已存在匹配的确认预约,不等同于已完成历史提交归属或生产 Book 成功接线。

最新真实验收:receipt-readonly-confirmed-v4 / a4840ececb 已由用户终端验证通过,existingReservationConfirmed=true,列表 2→2、五项业务请求 0、清理成功、EXIT_CODE=0。见 CS5 §29。下一步是最终结果与本次尝试归属接线,不重复提交或取消现有预约;生产 final 仍未开放。

最新本地接线:book-final-attribution-v9 / 1949de6664 已完成最终核心→本地验收入口的成功回传,626 项 Italy 离线回归及无网络预检通过。只有已匹配的单次原生请求、唯一新增确认回执、服务/日期/分配时刻一致且历史未变,才返回 VSBookResult.success=True;网站分配时刻不替换为选择区间。详见 CS5 §30。本轮未操作真实网站或 claim,不能倒推旧 v8 的请求归属;生产 final 仍关闭。下一步复用既有 Booker/订单状态建设成功回传、持久未知结果暂停与恢复,自动 OTP 仍为待办。

上线审查补充:已只读定位 webapp 任务后端,并离线复现 return_to_queue 将 pause/grabbed 覆盖为 pending;OrderBooker 对 FinalOutcomeUnknown 在两次信号中调用 Book 两次;成功上报入线程队列后 tracker 先被移除。详见 CS5 §31。修复需确认 webapp 共享任务接口与 Coordinate 调度层的改动范围,不能只补插件局部暂停便宣称可上线。本轮仅归档,未修改业务代码/后端或运行线上操作。

2026-08-31 最新范围调整(优先于上面的跨仓库提案):负责人明确要求按现有 VFS/BLS 链路推进,不新增平台复杂度。本轮已接 ItaPlugin.query/book 的显式人工 OTP 工作模式,提取调试与生产共用的 Calendar 准备代码,复用最终提交/回执核心,标准 VSBookResult 继续走现有 OrderBooker 成功上报。未知结果只复用现有 pause API,不修改 webapp、Redis 结构或 Sweeper。原 626 项 + 新增 24 项离线测试通过;不是上线/真实新入口验收。旧配置默认仍停止在原边界,真实提交未启用;自动 OTP 仍为 ITA-OTP-01。配置、验证命令与剩余边界见 CS5 §32。

最新用户终端验收:新 Query --production-workflow 单次正向通过,probe 0 无号、probe 1 正向,earliestDate=2026-09-03,finalSubmissionEnabled=false,清理成功、EXIT_CODE=0。见 CS5 §33。这是本次观察,不保证库存持续;末段日志未含源码指纹/完整请求计数。下一步验新 Book 公共入口至选位,最终提交仍关闭,OTP 自动化最后补。

后续验证入口已准备:原 debug_ita_book.py --production-workflow 现在调用一次公共 Book,走申请人独立登录/人工 OTP/选位并读回核对,最终提交固定关闭;成功验收看 selectionVerified=true、末尾 finalRequests=0、清理成功和 exit 0,bookResultSuccess=false 为预期。新增 9 项测试,659 项 Italy 离线回归通过。完整命令见 CS5 §34,本轮未做真实 Book 或部署。

最新 Book 阻点已定位:§34 新入口在 Services 就停止,五类业务请求均 0。用户截图确认目标服务行显示“该服务已经预约过”,因此没有 /Services/Booking/4937 链接;不是机构/服务号错误或无号。已在原诊断中补充页面级已预约提示计数及核对说明,不将无 ID 绑定的行认定为目标,不把旧预约算作本次成功,不改调度/取消预约。665 项 Italy 离线回归通过;新入口选位实测需换为已授权且该服务尚无预约的申请人账号,最终提交继续关闭。详见 CS5 §35。

最新验收(优先于上条待办):用户告知自行取消已有预约,随后新 Book --production-workflow 正向通过。选中 2026-09-03 / 09:15–10:00,remaining=2,selectionVerified=true;OTP 1、AVANTI 1、availability 3、timeSlots 2、final 0,清理成功、exit 0。bookResultSuccess=false 为预期停在最终提交前。新公共 Query 和 Book 选位均已有真实正向证据,不再重复该验收;下一步是复用原 OrderBooker 的最终结果/成功上报端到端验收及部署整包检查,OTP 自动化最后补。见 CS5 §36。本次只归档用户证据,未新增预约或部署。

最新本地上线收尾:新增 test_ita_booker_integration 8 项,实际运行公共 Book/NativeFinalSubmitter/回执解析/原异步上报回调,外部边界全替身;673 项 Italy 回归通过。已补齐 requirements 既有 redis 依赖(本地 8.1.0),无替身 Booker 导入及 pip check 通过。生产无算法改动、无新队列、无真实预约/云写入/部署。当前 Italy 生产配置仍关闭且为旧探测路由;必须整包发布并处理人工 OTP 的交互终端,不能只热更 ita_plugin.py。下一项需要明确云端 task id,验收新公共 Book → 原 Booker → 实际订单更新。见 CS5 §37。

0. 一句话定位

Coordinate 是一个面向"签证预约抢号"业务的分布式节点编排框架:Sentinel(哨兵,扫档期)→ Redis 信号 → Booker(抢号工人)→ 云端订单系统闭环,Standalone(独立单账号模式)与 Sweeper(孤儿任务回收)为辅,所有节点通过云端 API 下发配置、实时热重载、秒级插件热升级。

领域特殊性提示:本系统对接的是 TLSContact / VFS Global / BLS / 意大利 Prenot@Mi 等真实签证预约网站的浏览器自动化(DrissionPage + 反检测 + 拟人化操作 + OCR/打码),属于灰产边缘但合法的"抢预约"业务场景。接手时需注意合规边界与凭证安全。


1. 完成标准与验证结果对照(机械判定)

# 断言 验证方式 结果
1 全部 Python 文件语法合法 python3 -m py_compile main.py ... plugins/*.py ... ✅ exit 0,全部通过
2 核心逻辑模块可导入(无副作用) python3 -c "import vs_types, vs_plg, gco_wrapper, ..." ✅ 通过
3 云端配置 API 集成可用 只读 GET /api/node-configurations/standalone?node_id=yecaoyun ✅ 返回 3 条 entries
4 Redis 连接配置有效 原生 RESP:AUTH/PING/SELECT/DBSIZE ✅ +OK / +PONG / DBSIZE=0
5 测试套件可用 python3 -m pytest test/test_cloud_config.py -x -q ❌ 失败(见 §8)
6 Docker 可用 docker info ✅ Server 28.3.2
7 Git 工作区干净 git status ✅ clean,同步 origin/master

2. 架构总览

2.1 三种角色 + 一个守护进程

                 ┌──────────────────────────── 云端 (api.text.skin) ────────────────────────────┐
                 │  MySQL: sentinel_entries / booker_entries / standalone_entries (节点配置)     │
                 │  API: node-configurations / vas task pop/detail/update/return_to_queue       │
                 │  API: slot_refresh start/success/fail, slots/report, wechat push             │
                 │  Redis: PubSub vs:channel:upgrade[:node_id]  (插件升级指令)                   │
                 └──────────────────────────────┬───────────────────────────────────────────────┘
                                                │ HTTP (Bearer token)
        ┌───────────────┬───────────────────────┼──────────────────────────┬───────────────────────┐
        ▼               ▼                       ▼                          ▼                       ▼
   main.py sentinel  main.py booker       main.py standalone         main_sweeper.py         (云端下发的配置)
        │               │                       │                          │
        │ 轮询云端配置(30s) + MD5 diff → 热重载 sync_groups()               │
        │               │                       │                          │
   SentinelGCO     BaseBookerGCO           StandaloneGCO             OrphanTaskSweeper
   (monitor+creator) ├─BuiltinBookerGCO    (单账号自循环)              (回收心跳超时任务)
        │            └─OrderBookerGCO            │                        │
        │               │                        │                        │
        ▼               ▼                        ▼                        ▼
   VSPlgFactory(importlib 动态加载) ──────► plugins/*.py (IVSPlg 契约, 10 个插件)
        │
        ▼
   DrissionPage 浏览器自动化 (CloakBrowser/ungoogled-chromium + mihomo 代理隧道 + OCR/打码)

2.2 数据流(核心闭环)

  1. Sentinel:VSPlgFactory.create() 实例化插件 → create_session()(登录拿会话)→ monitor 循环按 QueryWaitConfig(Loop/Fixed/Random)轮询 query(apt_type);发现档期(VSQueryResult.success)→ 写 Redis vs:signal:{routing_key}(TTL=sentinel.signal_ttl,默认 180s)→ 上报云端 slot_refresh_start/success + slot_snapshot_report。
  2. Booker(built-in):_booking_trigger_loop 每 100ms 轮询所有 vs:signal:* → 命中后临时从云端 Pop 订单(get_vas_task_pop("auto.{routing_key}"))→ instance.book() → 成功则 update_vas_task(status=grabbed) + 微信推送 → 单账号达到 max_bookings_per_account 后销毁实例。
  3. Booker(order,1:1 绑定):creator 循环按 routing_key 配额从云端 Pop 订单 → 用订单自带账号建会话(1 实例=1 订单)→ 预订成功即销毁。
  4. 心跳与守护:Booker 每 keep_alive(默认 60s ± 5s 高斯抖动)保活 + 健康检查;心跳 deadline 写入 Redis zset vs:worker:tasks_tracker:{group_id}(score=deadline 时间戳)。Sweeper 每 3s 扫描所有 tracker zset,score 过期 → 查云端任务状态,若仍 processing → return_vas_task_to_queue 强制归还。
  5. 状态监控:所有角色每 60s 上报 vs:status:{role}:{node_id}(TTL=180s,RoleStatus 含 groups 聚合状态 + 本地已安装插件元数据列表)。

2.3 配置与热重载

  • 配置来源:云端 MySQL → GET /api/node-configurations/{sentinel|booker|standalone}?node_id=&pageSize=100。
  • 本地缓存:config/config_{role}.json(save_local_cache 原子写 .tmp + os.replace)。
  • 启动:load_remote_or_cache() 云端优先、失败 fallback 本地缓存(云不可用时还能离线跑)。
  • 热重载:主循环每 --poll-interval(默认 30s)拉取 → MD5 对比(compute_config_hash,sort_keys 序列化)→ 变化则 sync_groups() 差异化 stop/update/start 各 GCOWrapper。

2.4 插件升级闭环

  • 云端发布插件 → Redis PUBLISH vs:channel:upgrade[:node_id] → 节点 start_upgrade_listener 后台线程秒级接收 → handle_plugin_upgrades:
    • 版本比较(is_newer_version,语义化数字元组)→ download_and_install_plugin(URL 下载或直传 code + SHA256 校验 + py_compile 语法预检 + 原子替换)
    • reload_wrappers_for_plugin:停掉使用该插件的 Wrapper → sys.modules.pop(plugin_name) 清缓存 → 重建加载新代码。

3. 模块地图(顶层,16.7k 行 Python)

3.1 入口与编排

文件 职责 行数
main.py 统一入口:角色分发(sentinel/booker/standalone)、云端配置轮询热重载、RoleStatus 上报、PubSub 升级监听 367
main_sweeper.py 孤儿任务回收守护进程(独立部署) 128
configure.py 集中配置:REDIS_CFG、TEST_TASK/TEST_ACCOUNT/TEST_PROXY(测试短路开关)、CHROME_PATH、MIHOMO_BIN_PATH、MIHOMO_RELAY_NODES 145
logger_setup.py 统一日志(终端 + 10MB×10 滚动文件),注入 vs_log_macros 45
download_deps.py + deps.txt 下载浏览器/mihomo 二进制到 downloads/(供 Docker 构建) 44

3.2 核心框架层

文件 职责
vs_types.py 领域模型:GroupConfig/SentinelConfig/BookerConfig/BookerStandaloneConfig(pydantic v2)、VSQueryResult/VSBookResult/VSPlgConfig、Task、状态快照 RoleStatus/GroupStatus/PluginStatus、异常体系 BizException(code/http_status 双维度)
vs_plg.py 插件契约 IVSPlg:set_config / set_log / create_session / query / book / keep_alive / health_check / cleanup / get_plugin_status(8 个抽象方法 + 元数据 name/version/description)
vs_plg_factory.py 插件工厂:importlib 按路径动态加载模块并实例化,强制 isinstance(IVSPlg) 校验
gco_wrapper.py GCO 生命周期包装器:状态机 CREATED→LOADED→RUNNING→STOPPING→STOPPED→FAILED、日志环形缓冲(1000 条)+ 订阅、update_config/get_status 透传
sentinel.py SentinelGCO:creator(按 target_instances 配额 spawn,Rate-limited 时 30s 退避 + lock_account)+ monitor(全局查询节流 global_gap)双线程
booker.py BaseBookerGCO(trigger/maintain/creator 三循环 + hook 设计)+ BuiltinBookerGCO + OrderBookerGCO
standalone.py StandaloneGCO:单实例自循环(登录冷却→健康检查→加权随机选 routing_key→查询→自动预订→微信通知)
vs_log_macros.py 全局日志宏(VSC_INFO/ERROR/WARN/DEBUG),可注入 app logger

3.3 插件(10 个,全部实现 IVSPlg)

插件 版本 行数 目标系统
vfs_plugin 1.0.1 1465 VFS Global 全球多中心(最大插件)
bls_plugin 1.0.0 1107 西班牙 BLS
tls_plugin 1.0.0 1055 TLSContact 欧洲多国
ita_plugin 1.0.0 770 意大利 Prenot@Mi
grc_plugin 1.0.0 650 希腊/爱尔兰 SuperSaaS
usa_plugin 1.0.0 624 美签 USVisaScheduling
de_plugin 1.0.0 554 德国 Visametric
pol_plugin 1.0.0 447 波兰 e-konsulat
bel_plugin 1.0.0 443 比利时
prt_plugin 1.0.0 94 葡萄牙(仅骨架,未实现 create_session/query/book 全为 pass)

3.4 工具与基建

模块 职责
toolkit/vs_cloud_api.py 云端 API 单例封装(账户轮转、代理轮转、任务 Pop/更新/归还、slot 上报、邮件抓取、微信推送、HTTP Session 托管)
toolkit/mihomo_tunnel.py / proxy_tunnel.py mihomo(Clash Meta) 代理隧道(多实例隔离 + dialer-proxy 链式路由)
toolkit/ocr_engine.py + data/ocr.pth、data/ctc.pth PyTorch 验证码 OCR(ddddocr + 自研 CNN)
toolkit/captcha_breaker.py 验证码兜底:QWEN-VL 打码(硬编码 API key)
toolkit/thread_pool.py / backoff.py 线程池单例 / 指数退避
utils/safe_redis_cli.py Redis 安全封装:超时/重试一次/失败安全默认值,防死等
utils/cloud_config.py 云端配置拉取、MD5、本地缓存原子写、fallback
utils/plugin_updater.py 插件扫描(AST 静态解析元数据,不 import 防副作用)、版本比较、下载安装+校验+原子替换
utils/mouse.py/keyboard.py/scroll.py/fingerprint_utils.py/fake_utils.py 浏览器拟人化(人类轨迹鼠标、键盘、滚动、指纹)
utils/cloudflare_bypass_for_scraping.py / network_interceptor.py CF 挑战破解 / 网络拦截
tools/proxy_uploader.py 代理批量导入云端

3.5 遗留代码(不参与当前框架,勿动除非明确要求)

tls_registration_bot.py(711) / vfs_registration_bot.py(615) / tls_registration_gui.py(837, PyQt5) / test/tls_standalone.py(780) —— 框架化之前的单点脚本,main.py 不引用。建议:确认无人使用后可归档删除或标记 deprecated。


4. Redis 键空间约定

Key 类型 说明
vs:signal:{routing_key} string(TTL) Sentinel 发现档期的信号载荷(group_id + apt_type + query_result 快照),Booker 消费后不删(信号自过期,防并发丢单)
vs:worker:tasks_tracker:{group_id} zset score=心跳 deadline,member=task_id;OrderBooker 用 heartbeat_ttl=120s,Sweeper 据此回收
vs:status:{role}:{node_id} string(TTL=180s) RoleStatus 全量状态
vs:channel:upgrade / vs:channel:upgrade:{node_id} pubsub 插件升级指令通道

当前状态【已验证】:text.skin:6379 AUTH 通过、PING PONG、DBSIZE=0(db0 目前为空,无生产信号数据——可能是 staging 实例或业务未启动)。


5. 部署与运维

5.1 Docker 部署(生产形态)

  • 镜像:python:3.10-slim-bookworm,Xvfb + dbus + 中文字体 + CloakBrowser(CHROME_BIN=/opt/ungoogled-chromium/chrome)+ mihomo(MIHOMO_BIN=/bin/mihomo)。
  • docker-compose.yml:4 个服务(visa-sentinel / visa-booker / visa-standalone / visa-sweeper),镜像 coordinator:latest,挂载 ./config ./logs ./data ./plugins(plugins 挂载=插件热升级落盘持久化),NODE_ID 默认 yecaoyun,资源上限 CPU 2.0 / 内存 2G。
  • 构建前置:downloads/ 目录(gitignore)需先跑 python3 download_deps.py(从 deps.txt 拉 CloakBrowser 与 mihomo Linux 包),否则 docker build 的 COPY downloads/... 会失败。
  • entrypoint.sh:清锁 → 起 dbus → 起 Xvfb :99 → exec 外部命令。
  • .dockerignore:排除 docs/test/日志/缓存,仅保留构建所需 Linux 依赖包。
  • 注意:compose 未内置 Redis 服务,依赖外部 text.skin:6379(凭据在 configure.py,已提交仓库——见 §7 风险 5)。

5.2 本地运行

  • python3 main.py sentinel [-c config/config_sentinel.json] [--poll-interval 30] [--status-interval 60]
    • 不带 -c = 云端模式(默认);带 -c = 纯本地模式。
  • NODE_ID 环境变量决定拉取哪份云端配置与状态 key。
  • 本地环境缺口【已验证】:本机 conda base (Python 3.11.4) 缺少 redis / DrissionPage / curl-cffi / ddddocr / bs4 / easyocr / psutil / pyyaml,完整运行需 pip install -r requirements.txt(或建 venv)再跑;生产一律走 Docker。
  • 本机代理陷阱【已验证】:shell 环境设置了 HTTP(S)_PROXY=http://127.0.0.1:7897(Clash),但 7897 未监听 → requests 直接跑会 ProxyError。绕开方式:unset 代理变量 或 session.trust_env=False。

6. 测试现状

测试文件 状态 说明
test/test_cloud_config.py ❌ 坏 from utils.cloud_config import ... fetch_remote_config —— 该函数已改名 fetch_cloud_config,import 即崩(pytest collection error)。另 mock 服务器逻辑与当前云端模式 API 已不匹配
test/test.py 片段 opencv 中值滤波示例,非测试
test/regex_test.py 片段 TLS 档期 HTML 解析正则实验
test/test_capsolver.py / image_ocr_test.py / test_publish_slot.py 一次性脚本 依赖外部服务/依赖,未纳入 pytest
test/tls_standalone.py 遗留 旧单点脚本

结论:目前没有可用的自动化测试套件。 接手第一件事应修复 test_cloud_config.py(改名 + 按新 load_remote_or_cache 语义重写),并为核心纯逻辑(配置解析、MD5、版本比较、状态聚合)补单元测试。


7. 代码审查发现(多疑资深工程师视角)

7.1 已确认的问题(高确信度)

  1. Task.qw_cfg 尾逗号 bug【已验证】:vs_types.py:220 qw_cfg: Optional[QueryWaitConfig] = None, —— Python 语法使默认值变成元组 (None,) 而非 None。实测 Task(instance=object()).qw_cfg == (None,)。当前是潜伏 bug(生产代码总是显式传 qw_cfg,Booker 任务不读该字段),但任何新代码若依赖默认值会直接 AttributeError: 'tuple' object has no attribute 'mode'。修复:删掉尾逗号。
  2. 测试套件损坏【已验证】:见 §6。
  3. 文档与代码不一致【已读码确认】:handle_plugin_upgrades docstring 示例用 "plugin_name",代码实际读 item.get("name")。以代码为准(云端下发 "name"),docstring 需修正。
  4. 活跃时段用 UTC 判定(可能偏移 8 小时)【代码确认,业务语义待确认】:sentinel.py:129 / booker.py:148 / standalone.py:56 用 datetime.utcnow() 但变量名叫 current_bj_time、注释写"北京"。Docker 里 TZ=Asia/Shanghai 不影响 utcnow()(它总是 UTC)。若业务期望北京时区,active_time_start/end 实际会偏移 8 小时生效。需与业务确认后修复(datetime.now() 或显式 ZoneInfo("Asia/Shanghai"))。

7.2 值得商榷的设计(建议,勿擅自改)

  1. 生产凭据硬编码入库【高确信度】:vs_cloud_api.py 的 api_token、configure.py 的 Redis 密码、captcha_breaker.py 的 QWEN key、config JSON 里的真实账号密码均已提交到 gogs 仓库。若这是生产环境,建议尽快轮换密钥并迁移到环境变量/secret 管理(Docker secrets / .env + configure.py 从环境读取)。注意:改动涉及多处调用点,需单独排期。
  2. Sweeper 用 KEYS vs:worker:tasks_tracker:*:键数量大时阻塞 Redis,建议换 SCAN(当前量级可接受)。
  3. configure.py 中 TEST_TASK/TEST_ACCOUNT/TEST_PROXY 是运行时短路开关(非 None 时 get_vas_task_pop/get_next_account/get_next_proxy 直接返回测试数据)—— 这是有用的本地联调机制,但生产误开会导致假数据,建议启动时打醒目标记日志。
  4. Standalone _init_instance 无条件拉代理:get_next_proxy 未按 need_proxy 门控(与 Sentinel/Booker 的 if self.m_cfg.need_proxy 不一致)。
  5. README 缺失:仓库根目录无 README(RDD 原则),本次接手报告可作起点。
  6. prt_plugin 是空壳(所有方法 pass):若 routing 配置里出现 prt_plugin 会静默"成功但无行为",建议禁用该插件或标注未完成。

7.3 初步审查的自我反驳(原则 6)

反驳:"你说 _is_within_active_hours 是 bug,但也许业务就是按 UTC 设计的,配置里 00:00–23:30 本来就是 UTC 意图。" 回应:可能性存在,所以我标"待业务确认"而非直接修。但变量名 current_bj_time + 注释"判断当前是否在允许创建实例的时间段内"(无时区声明)+ Docker TZ 设为 Asia/Shanghai,三处证据都指向"期望北京时间"。在确认前不动作,符合"禁止顺手优化"。

反驳:"Redis DBSIZE=0 说明这个实例是空的,你凭什么说生产闭环能跑通?" 回应:我只验证了"连接与认证有效"和"云端配置拉取有效"两件事,未声称业务闭环已跑通。完整的端到端验证需要部署容器 + 真实信号,属上线前联调范畴(见 §10 下一步清单)。


8. 确信度与进度标注

  • 高确信度:模块职责、数据流、Redis 键空间、插件清单、部署形态、§7.1 的四个问题(全部有代码/命令证据)。
  • 中确信度:UTC 时区问题是否是 bug(需业务确认)、sweeper 实际生产规模。
  • 未验证(明确列出,不假装验证过):
    • 插件真实浏览器端到端行为(本地缺 DrissionPage,且需要目标网站可达)——需要 Docker 环境或 venv。
    • Redis PubSub 升级链路(需要云端主动 PUBLISH 触发,无法只读验证)。
    • Docker 镜像构建(本地 downloads/ 目录不存在,需先执行 download_deps.py 下载 ~ 依赖包)。
    • 微信推送 / 邮件抓取 / 打码等外部依赖服务。

9. 验证命令清单(本文所有【已验证】的依据)

# 1. 语法全检
python3 -m py_compile main.py main_sweeper.py booker.py sentinel.py standalone.py \
  gco_wrapper.py vs_types.py vs_plg.py vs_plg_factory.py vs_log_macros.py configure.py \
  logger_setup.py utils/*.py toolkit/*.py plugins/*.py tools/*.py   # exit 0

# 2. 核心模块导入(无网络副作用)
python3 -c "import vs_types, vs_plg, vs_plg_factory, gco_wrapper, configure, logger_setup"  # exit 0

# 3. Task 默认值 bug 复现
python3 -c "from vs_types import Task; print(Task(instance=object()).qw_cfg)"  # -> (None,)

# 4. 云端只读 GET(绕开本地死代理)
python3 -c "..." # session.trust_env=False 后 GET node-configurations → 3 条

# 5. Redis 只读探测(原生 RESP,无需 redis 库)
AUTH → +OK ; PING → +PONG ; SELECT 0 → +OK ; DBSIZE → :0

# 6. 测试套件
python3 -m pytest test/test_cloud_config.py -x -q   # exit 1: ImportError fetch_remote_config

# 7. 环境
python3 --version  # 3.11.4 (conda base);docker info → Server 28.3.2
git status → clean ; git log → 124 commits,HEAD=9bee354 (2026-08-24, docker .dockerignore)

10. 立即接手清单(按优先级)

P0(上线前必须)

  1. 修复 vs_types.py Task 尾逗号 bug(一行)。
  2. 修复 test/test_cloud_config.py(改名 + 按新 API 重写)并让 pytest 全绿。
  3. 确认 UTC vs 北京时间语义(问业务),确认后修 _is_within_active_hours。

P1(质量)

  1. 补核心纯逻辑单测:compute_config_hash、is_newer_version、parse_group_configs、状态聚合(这些不依赖浏览器,本地可跑)。
  2. 修正 handle_plugin_upgrades docstring。
  3. 评估密钥外置(至少 Redis 密码与 API token 支持环境变量覆盖)。

P2(体验/长期主义)

  1. 写根 README(RDD:把本文档提炼为对外文档 + 快速开始)。
  2. prt_plugin 空壳处理(完成或禁用)。
  3. Sweeper KEYS→SCAN、Standalone 代理门控对齐。
  4. 遗留脚本(tls_registration_bot 等 4 个)确认后归档。

11. 参考文档(docs/ 内,均与代码一致)

  • docs/node_config_cloud_storage_and_api.md —— 节点配置云端化 + 轮询热重载设计(§3.1-3.3 与代码逐行对应)
  • docs/config_entries_database_schema.md —— booker/sentinel/standalone 三表 DDL 与字段映射
  • docs/plugin_cloud_storage_and_api.md —— 插件云端发布/升级/分发设计(/plugins/publish、/plugins/upgrade/dispatch、PubSub 通道)