# 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](./ita_query_recovery.md)。本条不更新下面 2026-08-25 的历史环境结论,也不代表 Book/生产上线完成。 --- > 2026-08-31 Italy Book 更新:用户回传 v8 实测最终请求 1 次,新增确认回执 Confermata / 2,日期 2026-09-03,分配时间 09:26,历史未变、请求审计通过。网站已显示确认;程序尚未识别新状态/完整归属,仍 unknown / exit 4,勿重跑提交或清除 claim。详见 [CS5 §27](./ita_book_cs5.md)。598 项为第 26 节先前本地离线证据;真实回传未包含 Book 源码指纹。下一步用已有回执只读完善成功判定,生产 final 仍关闭,跨进程阻断与自动 OTP 仍待完成。 > 后续本地更新:已接入 Confermata / 2 → ACTIVE,并在原回执工具增加 --expect-confirmed;611 项 Italy 离线测试与 receipt-readonly-confirmed-v4 无网络预检通过。下一步执行 [CS5 §28](./ita_book_cs5.md) 的只读命令,不重跑预约。成功时表示已存在匹配的确认预约,不等同于已完成历史提交归属或生产 Book 成功接线。 > 最新真实验收:receipt-readonly-confirmed-v4 / a4840ececb10 已由用户终端验证通过,existingReservationConfirmed=true,列表 2→2、五项业务请求 0、清理成功、EXIT_CODE=0。见 [CS5 §29](./ita_book_cs5.md)。下一步是最终结果与本次尝试归属接线,不重复提交或取消现有预约;生产 final 仍未开放。 > 最新本地接线:book-final-attribution-v9 / 1949de666430 已完成最终核心→本地验收入口的成功回传,626 项 Italy 离线回归及无网络预检通过。只有已匹配的单次原生请求、唯一新增确认回执、服务/日期/分配时刻一致且历史未变,才返回 VSBookResult.success=True;网站分配时刻不替换为选择区间。详见 [CS5 §30](./ita_book_cs5.md)。本轮未操作真实网站或 claim,不能倒推旧 v8 的请求归属;生产 final 仍关闭。下一步复用既有 Booker/订单状态建设成功回传、持久未知结果暂停与恢复,自动 OTP 仍为待办。 > 上线审查补充:已只读定位 webapp 任务后端,并离线复现 return_to_queue 将 pause/grabbed 覆盖为 pending;OrderBooker 对 FinalOutcomeUnknown 在两次信号中调用 Book 两次;成功上报入线程队列后 tracker 先被移除。详见 [CS5 §31](./ita_book_cs5.md)。修复需确认 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](./ita_book_cs5.md)。 > 最新用户终端验收:新 Query `--production-workflow` 单次正向通过,probe 0 无号、probe 1 正向,earliestDate=2026-09-03,finalSubmissionEnabled=false,清理成功、EXIT_CODE=0。见 [CS5 §33](./ita_book_cs5.md)。这是本次观察,不保证库存持续;末段日志未含源码指纹/完整请求计数。下一步验新 Book 公共入口至选位,最终提交仍关闭,OTP 自动化最后补。 > 后续验证入口已准备:原 `debug_ita_book.py --production-workflow` 现在调用一次公共 Book,走申请人独立登录/人工 OTP/选位并读回核对,最终提交固定关闭;成功验收看 selectionVerified=true、末尾 finalRequests=0、清理成功和 exit 0,bookResultSuccess=false 为预期。新增 9 项测试,659 项 Italy 离线回归通过。完整命令见 [CS5 §34](./ita_book_cs5.md),本轮未做真实 Book 或部署。 > 最新 Book 阻点已定位:§34 新入口在 Services 就停止,五类业务请求均 0。用户截图确认目标服务行显示“该服务已经预约过”,因此没有 /Services/Booking/4937 链接;不是机构/服务号错误或无号。已在原诊断中补充页面级已预约提示计数及核对说明,不将无 ID 绑定的行认定为目标,不把旧预约算作本次成功,不改调度/取消预约。665 项 Italy 离线回归通过;新入口选位实测需换为已授权且该服务尚无预约的申请人账号,最终提交继续关闭。详见 [CS5 §35](./ita_book_cs5.md)。 > 最新验收(优先于上条待办):用户告知自行取消已有预约,随后新 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](./ita_book_cs5.md)。本次只归档用户证据,未新增预约或部署。 > 最新本地上线收尾:新增 `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](./ita_book_cs5.md)。 ## 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 值得商榷的设计(建议,勿擅自改) 5. **生产凭据硬编码入库【高确信度】**:`vs_cloud_api.py` 的 `api_token`、`configure.py` 的 Redis 密码、`captcha_breaker.py` 的 QWEN key、config JSON 里的真实账号密码均已提交到 gogs 仓库。若这是生产环境,建议尽快轮换密钥并迁移到环境变量/secret 管理(Docker secrets / .env + `configure.py` 从环境读取)。**注意:改动涉及多处调用点,需单独排期。** 6. **Sweeper 用 `KEYS vs:worker:tasks_tracker:*`**:键数量大时阻塞 Redis,建议换 `SCAN`(当前量级可接受)。 7. **`configure.py` 中 `TEST_TASK/TEST_ACCOUNT/TEST_PROXY` 是运行时短路开关**(非 None 时 `get_vas_task_pop/get_next_account/get_next_proxy` 直接返回测试数据)—— 这是有用的本地联调机制,但生产误开会导致假数据,建议启动时打醒目标记日志。 8. **Standalone `_init_instance` 无条件拉代理**:`get_next_proxy` 未按 `need_proxy` 门控(与 Sentinel/Booker 的 `if self.m_cfg.need_proxy` 不一致)。 9. **README 缺失**:仓库根目录无 README(RDD 原则),本次接手报告可作起点。 10. **`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. 验证命令清单(本文所有【已验证】的依据) ```bash # 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(质量)** 4. 补核心纯逻辑单测:`compute_config_hash`、`is_newer_version`、`parse_group_configs`、状态聚合(这些不依赖浏览器,本地可跑)。 5. 修正 `handle_plugin_upgrades` docstring。 6. 评估密钥外置(至少 Redis 密码与 API token 支持环境变量覆盖)。 **P2(体验/长期主义)** 7. 写根 README(RDD:把本文档提炼为对外文档 + 快速开始)。 8. `prt_plugin` 空壳处理(完成或禁用)。 9. Sweeper KEYS→SCAN、Standalone 代理门控对齐。 10. 遗留脚本(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 通道)