# CLAUDE.md

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

`AGENTS.md` 仅作入口；项目约束只维护在此处。使用与部署说明见 [README.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/workflow.md)，文档索引见 [docs/README.md](docs/README.md)。[统一审查台账](docs/reviews/ARCHITECTURE_REVIEW_UNIFIED.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](.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](README.md)。