# CLAUDE.md

## What This Repo Does

自动选优 Cloudflare 优选域名/IP，写入运行时文件供 Sub-Store 等下游消费。

两种独立运行模式：

| 模式 | 数据源 | 配置 | 输出目录 | Git 自动化 |
|------|--------|------|----------|-----------|
| Server | 远程 API | `config.server.json` | `runtime/` | `runtime-state` 分支 |
| Router (Python) | 本地 `cfst` | `config.local.json` | `cfip_runtime/` | 无 |
| Router (BusyBox) | 本地 `cfst` | `config_router.conf` | 由配置决定 | 无 |

## File Map

```
scripts/
├── domain_updater.py          # 核心：两种模式共用的 Python 更新器
├── run_update_and_commit.sh   # Server 模式调度器 + git 提交逻辑
├── router_local_update.sh     # BusyBox 路由器：运行 cfst 并写输出
├── router_local_http.sh       # BusyBox 路由器：httpd 提供运行时文件
├── install_debian.sh          # systemd timer/service 安装
└── uninstall_debian.sh        # systemd 卸载

substore/
└── operator_template.js       # Sub-Store 脚本操作符，消费运行时 JSON

build_router_package.sh        # 打包路由器部署 tarball → vmess.tar.gz
config.server.json             # Server 模式完整配置
config.local.json              # Python 本地 cfst 模式配置
config_router.conf             # BusyBox shell 模式配置
```

## Common Commands

### 语法校验

```bash
env PYTHONPYCACHEPREFIX=/tmp/pycache python3 -m py_compile scripts/domain_updater.py
bash -n scripts/run_update_and_commit.sh
bash -n scripts/install_debian.sh
bash -n scripts/uninstall_debian.sh
sh -n scripts/router_local_update.sh
sh -n scripts/router_local_http.sh
```

### 运行

```bash
# Server 模式单次运行
python3 scripts/domain_updater.py --config config.server.json

# 本地 cfst 模式单次运行
python3 scripts/domain_updater.py --config config.local.json

# 查看解析后的输出路径（不执行更新）
python3 scripts/domain_updater.py --config config.server.json --print-output-settings

# Server 调度器入口
bash scripts/run_update_and_commit.sh config.server.json

# 强制提交
bash scripts/run_update_and_commit.sh --force-commit config.server.json

# BusyBox 路由器
sh scripts/router_local_update.sh ./config_router.conf
sh scripts/router_local_http.sh ./config_router.conf

# 打包路由器部署包
./build_router_package.sh
```

### systemd 安装/卸载

```bash
sudo bash scripts/install_debian.sh --config config.server.json
sudo bash scripts/uninstall_debian.sh
```

`install_debian.sh --help` 查看完整参数（peak/offpeak 间隔、时区等）。

## Testing

- 无专用测试框架，以语法校验 + 手动运行为主。
- `--print-output-settings` 是最快的路径解析验证方式。
- **本地测试服务器端时，仅运行 `python3 scripts/domain_updater.py --config config.server.json` 进行输出验证，不要运行 `run_update_and_commit.sh` 调度/Git 推送脚本。**

## Key Constraints

- `config.json` / `config.example.json` 已废弃，不要重新引入。
- 输出路径由配置驱动，不要硬编码 `runtime/current_domain.txt` 之类的路径。
- `runtime/` 和 `cfip_runtime/` 在 `main` 分支被 gitignore。
- 只有 Server 模式向 `runtime-state` 分支提交。
- `state.json` 用于 fallback（保存上次正常值），两种模式都依赖它。
- `substore_vars.json` 是给下游消费者的轻量契约，不要把完整运行时数据塞进去。
- BusyBox shell 脚本需兼容 POSIX sh，不能用 bash 特性。
- `router_local_http.sh` 使用配置中的 BusyBox 二进制的 httpd applet，不使用系统 httpd。
- SubStore 脚本的 `$arguments.domain` 参数为最高优先级覆盖，`$arguments.domain_override` 控制开关，不受任何模式和策略影响。

## Where to Look

- 想了解配置字段含义 → 直接读对应的 config JSON/conf 文件，字段名即文档
- 想了解评分/筛选逻辑 → `scripts/domain_updater.py`
- 想了解 git 提交/推送流程 → `scripts/run_update_and_commit.sh`
- 想了解 systemd 部署细节 → `scripts/install_debian.sh`
- 想了解下游消费方式 → `substore/operator_template.js`
- 想了解完整工作流图 → `workflow.md`（Mermaid 流程图）
- 想了解用户文档 → `README.md`