doc: fix for logic

CLAUDE.md

@@ -155,6 +155,7 @@ Generated in `runtime/`:
 
 - Fallback behavior is stateful: `last_good_domain` persistence is critical for resilience.
 - `runtime-state` branch is intended to isolate frequently changing runtime outputs from `main` source history.
+- `main` normally ignores `runtime/` outputs via `.gitignore`; runtime artifacts are intended to be tracked on `runtime-state`.
 - Debian installer (`scripts/install_debian.sh`) writes `/etc/vmess-domain-rotator.env`, configures oneshot service+timer, and sets push-required behavior when push is enabled.
 - Repository `systemd/*` static templates are intentionally not maintained; install script dynamically generates unit files under `/etc/systemd/system/`.
 - Default install path is in-place (current git clone), default service user is `SUDO_USER`, and default auth mode is credential helper store.

README.md

@@ -33,6 +33,8 @@
 - `runtime/substore_vars.json`：给外部系统消费的变量
 
 > 注意：`domain_updater.py` 现在会按 `--config` 文件所在目录解析 `output.runtime_dir`（默认 `./runtime`），避免误写到 `scripts/runtime/`。
+> 
+> 注意：`main` 分支通常不追踪 `runtime/`（由 `.gitignore` 忽略），运行时产物建议通过 `runtime-state` 分支消费。
 
 ---
 
@@ -76,59 +78,54 @@
   "field_map": {
     "domain": "ip",
     "created_at": "createdTime",
-    "avg_score": "avgScore",
-    "yd_score": "ydScore",
-    "dx_score": "dxScore",
-    "lt_score": "ltScore",
-    "avg_latency": "avgLatency",
-    "avg_pkg_lost_rate": "avgPkgLostRate",
-    "yd_latency": "ydLatency",
-    "yd_pkg_lost_rate": "ydPkgLostRate",
-    "lt_latency": "ltLatency",
-    "lt_pkg_lost_rate": "ltPkgLostRate",
-    "dx_latency": "dxLatency",
-    "dx_pkg_lost_rate": "dxPkgLostRate",
-    "location_country": "locationCountry",
-    "location_city": "locationCity"
+    "avg_score": "avgScore"
   },
   "created_time_formats": ["%Y-%m-%d %H:%M:%S"],
   "created_time_timezone": "UTC"
 }
 ```
 
-`record_filter` 示例（排除 locationCountry/locationCity 含“泛播”的记录）：
+`record_filter` 示例（示例仅保留 1 条规则）：
 
 ```json
 "record_filter": {
-  "enabled": true,
+  "enabled": false,
   "exclude_if_any": [
-    { "field": "location_country", "contains": "泛播", "case_sensitive": false },
-    { "field": "location_city", "contains": "泛播", "case_sensitive": false }
+    { "field": "domain", "regex": "(test|staging)", "case_sensitive": false }
   ]
 }
 ```
 
-`scoring` 示例（`avg_score` 默认最高权重）：
+`scoring` 示例（最简 weighted_average，且当前分数语义为“越低越好”）：
 
 ```json
 "scoring": {
   "enabled": true,
   "strategy": "weighted_average",
   "weighted_fields": [
-    { "field": "avg_score", "weight": 0.5 },
-    { "field": "yd_score", "weight": 0.2 },
-    { "field": "dx_score", "weight": 0.1 },
-    { "field": "lt_score", "weight": 0.2 }
+    { "field": "avg_score", "weight": 1.0 }
   ],
-  "prefer_lower": false,
+  "prefer_lower": true,
   "within_hours": 24,
   "tie_breakers": [
-    { "field": "created_at", "order": "desc" },
     { "field": "domain", "order": "asc" }
   ]
 }
 ```
 
+`healthcheck` 示例（当前默认 attempts=5）：
+
+```json
+"healthcheck": {
+  "enabled": false,
+  "attempts": 5,
+  "timeout_ms": 1800,
+  "port": 443,
+  "tls_verify": true
+}
+```
+
+
 规则支持：
 - `contains`
 - `equals`

config.example.json

@@ -5,10 +5,7 @@
     "headers": {
       "Authorization": "Bearer <token>"
     },
-    "params": {
-      "page": 1
-    },
-    "body": null,
+    "params": {},
     "timeout_sec": 10
   },
   "parser": {
@@ -24,20 +21,7 @@
     "field_map": {
       "domain": "ip",
       "created_at": "createdTime",
-      "avg_score": "avgScore",
-      "yd_score": "ydScore",
-      "dx_score": "dxScore",
-      "lt_score": "ltScore",
-      "avg_latency": "avgLatency",
-      "avg_pkg_lost_rate": "avgPkgLostRate",
-      "yd_latency": "ydLatency",
-      "yd_pkg_lost_rate": "ydPkgLostRate",
-      "lt_latency": "ltLatency",
-      "lt_pkg_lost_rate": "ltPkgLostRate",
-      "dx_latency": "dxLatency",
-      "dx_pkg_lost_rate": "dxPkgLostRate",
-      "location_country": "locationCountry",
-      "location_city": "locationCity"
+      "avg_score": "avgScore"
     },
     "created_time_formats": [
       "%Y-%m-%d %H:%M:%S"
@@ -45,19 +29,9 @@
     "created_time_timezone": "UTC"
   },
   "record_filter": {
-    "_comment": "可选。按记录字段排除候选（字段名必须来自 record_mapping.field_map）。",
+    "_comment": "可选。域名记录过滤规则。enabled=true 时生效。exclude_if_any 中满足任一条件即排除该记录",
     "enabled": false,
     "exclude_if_any": [
-      {
-        "field": "location_country",
-        "contains": "泛播",
-        "case_sensitive": false
-      },
-      {
-        "field": "location_city",
-        "contains": "泛播",
-        "case_sensitive": false
-      },
       {
         "field": "domain",
         "regex": "(test|staging)",
@@ -66,10 +40,10 @@
     ]
   },
   "domain_filter": {
-    "include_suffixes": [],
-    "exclude_regex": [
-      "^(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)(?:\\.(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)){3}$"
-    ]
+    "include_suffixes": [
+      ".example.com"
+    ],
+    "exclude_regex": []
   },
   "scoring": {
     "_comment_required": "enabled=true 时必须配置 strategy。weighted_average 需 weighted_fields；lexicographic 需 lexicographic_fields。",
@@ -106,10 +80,6 @@
     "prefer_lower": true,
     "within_hours": 24,
     "tie_breakers": [
-      {
-        "field": "created_at",
-        "order": "desc"
-      },
       {
         "field": "domain",
         "order": "asc"
@@ -118,7 +88,7 @@
   },
   "healthcheck": {
     "enabled": false,
-    "attempts": 2,
+    "attempts": 5,
     "timeout_ms": 1800,
     "port": 443,
     "tls_verify": true

scripts/install_debian.sh

@@ -334,4 +334,5 @@ echo "Commands:"
 echo "  Check status: systemctl status ${SERVICE_NAME}.timer"
 echo "  View logs:    journalctl -u ${SERVICE_NAME}.service -n 50 --no-pager"
 echo "  Manual run:   sudo systemctl start ${SERVICE_NAME}.service"
+echo "  Force commit: sudo -u ${RUN_USER} /bin/bash ${APP_DIR}/scripts/run_update_and_commit.sh --force-commit ${APP_DIR}/config.json"
 echo ""

workflow.md

@@ -21,8 +21,8 @@ flowchart TD
       B3 --> B4[解析候选域名<br/>parser.field_paths/json_paths/regex fallback]
       B4 --> B5[域名过滤<br/>domain_filter.include_suffixes/exclude_regex]
       B5 --> B6[记录级过滤<br/>record_filter.exclude_if_any<br/>contains/equals/regex]
-      B6 --> B7[解析评分记录<br/>scoring.records_path/ip_field/created_time_field/score_fields]
-      B7 --> B8[排序<br/>within_hours + prefer_lower/use_api_order]
+      B6 --> B7[解析记录字段<br/>record_mapping.records_path + field_map 白名单]
+      B7 --> B8[评分排序<br/>scoring.strategy(weighted_average/lexicographic)<br/>within_hours + prefer_lower + tie_breakers]
       B8 --> B9{healthcheck.enabled?}
 
       B9 -- 是 --> B10[TLS 探测候选<br/>attempts/timeout_ms/port/tls_verify]