CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

AGENTS.md 仅作入口；项目约束只维护在此处。使用与部署说明见 README.md。

项目与入口

从远程 API 或本地 cfst 选出 Cloudflare 域名/IP，原子写入运行时文件，供 Sub-Store 等下游读取。

运行方式	配置	入口与职责
Server	`configs/config.server.json`	Python 负责 API 选优；`scripts/server/run_update_and_commit.sh` 负责调度、提交与推送
本地 Python	`configs/config.local.json`	`scripts/domain_updater.py` 调用本地 `cfst`，只落盘
BusyBox 路由器	`configs/config_router.conf`	`scripts/router/router_local_update.sh` 测速与落盘；`router_local_http.sh` 提供 HTTP 访问

输出目录以配置为准。当前两个 Python 配置均使用 runtime/，路由器使用 /tmp/vmess_runtime；不同模式需要独立保存状态时，应配置不同目录，避免覆盖共用的状态和导出文件。

执行边界

Python 编排在 scripts/rotator/main.py；scripts/domain_updater.py 是直接重导出门面。mock 编排依赖时 patch 实际使用处（如 rotator.main.fetch_api_json），只替换门面同名导出不会影响编排。
Python 本地 cfst 分支保留 CSV 顺序；-dd 只绕过下载速度筛选，不触发 Python 重排。skip_run=true 只跳过测速执行，仍会写出运行文件。

流程图见 docs/workflow.md，文档索引见 docs/README.md。统一审查台账用于追溯设计与修复背景；其中的结论需结合当前代码、配置和测试核实，不能代替上游指标定义。

开发约束

这些约束保护现有部署与消费者。内部结构可以重构；改变外部行为时，应同步迁移配置、调用方和测试，不必永久保留每个历史实现。

接口兼容：Server 脚本依赖 CLI 的 --print-output-settings 和 --result-json-file 解析路径及运行状态，下游依赖输出中的配置键、状态与候选信息。变更这些接口时一起检查调用方，避免脚本能执行但读取错误。 CLI 退出码 0 也包括 last-good 回退；判断是否取得新值应读取结果 JSON 的 status，不能只看退出码。
配置与路径：输出路径、文件名和 JSON 键由配置驱动，避免多处硬编码。仓库自带配置放在 configs/，--config 仍支持外部配置；不为旧文件名复制一套默认配置。相对输出目录的解析规则见 build_output_settings()，改动时覆盖仓库配置和外部配置两种场景。
写入与回退：运行时文件需单文件原子替换，防止并发读到半截内容；state.json 的 last-good 值支持故障回退。回退必须标明状态，且应遵守适用的排除规则。改变输出字段或删除产物前检查消费者；当前 Sub-Store 模板读取完整 JSON，substore_vars.json 是额外的轻量导出，仓库内未见其消费方。
发布边界：运行时发布与源码分支隔离，只提交配置指定的运行时文件，避免夹带源码或凭据。默认分支 runtime-state、去重规则和历史长度属于可调整策略；改动时验证下游地址、状态传播及修剪失败恢复。凭据不得写入日志或作为命令行参数传递。
路由器环境：路由器脚本和打包脚本由 sh 执行，保持 POSIX sh。HTTP 服务使用 BusyBox 的 httpd applet，优先配置指定的二进制，允许现有备用路径；不能误用固件的管理后台 httpd。改动测速或输出参数时检查 --sync-from-config 打包映射，避免部署参数漂移。
Sub-Store 行为：有效的手动 domain 优先于缓存和自动来源；domain_override=false 仅关闭手动覆盖，仍可自动替换。保持主机值校验以及仅修改名称匹配的 VMess 节点的范围，避免改坏无关节点。

当前实现边界：Python API 回退复查 domain_filter，尚未复查 record_filter；Sub-Store 的路由器时效检查仅在 default 模式启用，缺失或无效时间戳会放行。修改相关逻辑时应针对这些边界验证，不能把约束当作已经全面实现的保证。

评分语义

record_mapping.field_map 定义上游字段映射，例如 yd_score → ydScore。上游 *Score 的含义、单位和公式必须有上游依据，不能凭名称、少量样本或历史审查断言。
score_value 是本项目按 scoring 配置计算的排序值。权重、prefer_lower、order、平局决胜和切换迟滞属于本项目策略，不等同于上游评分。

验证与运行

按改动范围验证；具体命令、依赖及隔离要求见 .claude/skills/verify-rotator/SKILL.md，可手动调用 /verify-rotator。纯文档修改核对事实、路径与命令即可。

本地模式测试落盘：用户要求“在本地测试某种模式”时，一律以配置文件设置为测试工作目录，按该模式配置在根目录或其子目录生成并保留结果，不将结果改放到 /tmp 等仓库外临时目录。
不在当前工作仓库直接运行 Server 调度脚本；验证应使用无远端的临时仓库和本地模拟 API。用户要求本地 Server 模式实测时，将隔离仓库及结果放在当前项目根目录下的专用子目录。GIT_PUSH_ENABLED=0 只禁用 push，不禁止 fetch。
当前时间窗口测试在设置模拟 API 前执行首次调度，不能保证离线；默认验证排除此用例并明确报告。
build_router_package.sh 不支持 --help，传入后仍会打包；--sync-from-config 默认只修改包内配置，--write-back 才回写源配置。
编辑后的 Hook 只检查语法，不能代替测试；真实运行与部署命令见 README.md。

CLAUDE.md 6.2 KB Cronologia Originale