AGENTS

Repo Purpose (verified)

This repo is an automation utility for VMess preferred-domain rotation: fetch API candidates, pick one domain, write runtime artifacts, then let Sub-Store/V2Ray consume them.
Main entrypoint is scripts/domain_updater.py; optional post-processor for VMess links is scripts/update_vmess_links.py.
Scheduled runtime entrypoint is scripts/run_update_and_commit.sh (runs updater, then commits only when domain changed).

config.json: active runtime config (single source for runtime settings).
runtime/current_domain.json and runtime/current_domain.txt: outputs consumed by Sub-Store/operator scripts.
substore/operator_template.js: Sub-Store script-operation template using $substore.http.get and scriptResourceCache.
systemd/vmess-domain-rotator.service and systemd/vmess-domain-rotator.timer: deployment templates (must customize user/path).

Syntax check after Python edits:
- python3 -m py_compile scripts/domain_updater.py
- python3 -m py_compile scripts/update_vmess_links.py
Manual refresh run:
- python3 scripts/domain_updater.py --config config.json
Manual refresh + conditional git commit:
- bash scripts/run_update_and_commit.sh config.json
Update VMess links (add field) from selected domain:
- python3 scripts/update_vmess_links.py --input <in> --output <out> --domain-file runtime/current_domain.txt
Debian one-shot deploy/remove:
- sudo bash scripts/install_debian.sh
- sudo bash scripts/uninstall_debian.sh
Local output smoke test endpoint:
- python3 -m http.server 8080 --directory runtime

For vps789 Top20, keep API ranking order (scoring.use_api_order=true) and keep only domains (filter IPv4 via domain_filter.exclude_regex).
healthcheck.enabled may be intentionally false in vps789 mode; do not re-enable unless you want local TLS checks to override API ranking behavior.
domain_updater.py fallback behavior depends on persisted runtime/state.json (last_good_domain). Do not delete this file in normal operation.
run_update_and_commit.sh commits only when runtime/current_domain.txt changed before/after update.
Sub-Store script preview may show no change if NODE_NAME_REGEX in substore/operator_template.js does not match node names, or if cached output is reused.
In Sub-Store operators here, use $substore.http.get(...) (not plain fetch) for compatibility.

Template service assumes:
- Working dir: /opt/vmess-domain-rotator
- User: vmessrotator
Template timer interval is 12h by default.
Before enabling timer, adjust User, WorkingDirectory, and ExecStart in systemd/vmess-domain-rotator.service to match the real host.
Enable flow: copy unit files to /etc/systemd/system/ -> systemctl daemon-reload -> systemctl enable --now vmess-domain-rotator.timer.

Keep secrets out of source snapshots/backups: avoid placing tokens in tracked/shared files.
runtime/ is operational output; avoid treating it as source-of-truth code.