diff --git a/docs/rule-snapshots.md b/docs/rule-snapshots.md index c5407bdf..c34fef54 100644 --- a/docs/rule-snapshots.md +++ b/docs/rule-snapshots.md @@ -4,9 +4,9 @@ Bundled snapshots used by rule mode are explicitly maintained artifacts: -- **geolocation-cn** (issue #63): after manually reviewing the upstream source, run `Scripts/update-geolocation-cn.sh`. It parses typed entries from the pinned `geosite.dat` release of [Loyalsoldier/domain-list-custom](https://github.com/Loyalsoldier/domain-list-custom) and generates `Vendor/rules/geolocation-cn/snapshot.json`. -- **china-ipv4** (issue #64): run `Scripts/update-china-ipv4.sh` to normalize and deduplicate IPv4 CIDRs from the pinned `china.txt` version of [gaoyifan/china-operator-ip](https://github.com/gaoyifan/china-operator-ip), generating `Vendor/rules/china-ipv4/snapshot.json`. -- **gfwlist** (issue #65): run `Scripts/update-gfwlist.sh` to decode the official Base64 AutoProxy list from a pinned `gfwlist.txt` version of [gfwlist/gfwlist](https://github.com/gfwlist/gfwlist), generating `Vendor/rules/gfwlist/snapshot.json`. `||host` and `||host^` are converted to domain-suffix matches. A `|scheme://host` rule (optionally with a valid port) is converted to an exact-domain match when its path is empty or `/`, it has no query, fragment, or user information, and its host is a valid domain without wildcards; the scheme and port are ignored. Only a root path is eligible; rules with a specific path are skipped. `@@` retains the direct-routing action. Other URL prefixes, paths, wildcards, regular expressions, single-label prefixes, and IP-literal rules are counted by category in the loss report. A `@@` exception completely covered by proxy rules is not written as an ineffective ACL entry (`sslocal` domain matching gives `proxy_list` priority over `bypass_list`). The proxy rule is retained, and the number of shadowed exceptions is included only in `absorbedCount`. The maintenance script prints per-rule evidence to stdout. +- **geolocation-cn**: after manually reviewing the upstream source, run `Scripts/update-geolocation-cn.sh`. It parses typed entries from the pinned `geosite.dat` release of [Loyalsoldier/domain-list-custom](https://github.com/Loyalsoldier/domain-list-custom) and generates `Vendor/rules/geolocation-cn/snapshot.json`. +- **china-ipv4**: run `Scripts/update-china-ipv4.sh` to normalize and deduplicate IPv4 CIDRs from the pinned `china.txt` version of [gaoyifan/china-operator-ip](https://github.com/gaoyifan/china-operator-ip), generating `Vendor/rules/china-ipv4/snapshot.json`. +- **gfwlist**: run `Scripts/update-gfwlist.sh` to decode the official Base64 AutoProxy list from a pinned `gfwlist.txt` version of [gfwlist/gfwlist](https://github.com/gfwlist/gfwlist), generating `Vendor/rules/gfwlist/snapshot.json`. `||host` and `||host^` are converted to domain-suffix matches. A `|scheme://host` rule (optionally with a valid port) is converted to an exact-domain match when its path is empty or `/`, it has no query, fragment, or user information, and its host is a valid domain without wildcards; the scheme and port are ignored. Only a root path is eligible; rules with a specific path are skipped. `@@` retains the direct-routing action. Other URL prefixes, paths, wildcards, regular expressions, single-label prefixes, and IP-literal rules are counted by category in the loss report. A `@@` exception completely covered by proxy rules is not written as an ineffective ACL entry (`sslocal` domain matching gives `proxy_list` priority over `bypass_list`). The proxy rule is retained, and the number of shadowed exceptions is included only in `absorbedCount`. The maintenance script prints per-rule evidence to stdout. Snapshots use compact JSON with schema 2 / converter 2.0.0: each rule has only `action` and `match`; the source appears only in `metadata.source`; the conversion report retains counts only. Absorbed `.cn` entries and shadowed GFWList exceptions are not distributed in the snapshot and are not restored after a broad rule is disabled. See [ADR-0024](adr/0024-snapshot-drops-absorbed-and-forensics.md). Older snapshot versions are rejected. diff --git a/docs/rule-snapshots.zh.md b/docs/rule-snapshots.zh.md index ca453bee..387f1c63 100644 --- a/docs/rule-snapshots.zh.md +++ b/docs/rule-snapshots.zh.md @@ -6,9 +6,9 @@ 规则模式使用的内置快照是显式维护产物: -- **geolocation-cn**(issue #63):人工复验上游后运行 `Scripts/update-geolocation-cn.sh`,从固定版 [Loyalsoldier/domain-list-custom](https://github.com/Loyalsoldier/domain-list-custom) `geosite.dat` 解析 typed 条目并生成 `Vendor/rules/geolocation-cn/snapshot.json`。 -- **china-ipv4**(issue #64):运行 `Scripts/update-china-ipv4.sh`,从固定版 [gaoyifan/china-operator-ip](https://github.com/gaoyifan/china-operator-ip) `china.txt` 规范化并去重 IPv4 CIDR,生成 `Vendor/rules/china-ipv4/snapshot.json`。 -- **gfwlist**(issue #65):运行 `Scripts/update-gfwlist.sh`,从固定版 [gfwlist/gfwlist](https://github.com/gfwlist/gfwlist) `gfwlist.txt` 解码官方 Base64 AutoProxy 列表并生成 `Vendor/rules/gfwlist/snapshot.json`。`||host` / `||host^` 转换为域名后缀匹配;`|scheme://host`(可含合法端口)在路径为空或仅为 `/`,无查询、fragment 或用户信息,且 host 为无通配符的合法域名时,提取 host 转换为精确域名匹配,忽略协议和端口。仅含根路径 `/` 可转换,包含具体路径的规则继续跳过。`@@` 保留直连动作。其他 URL 前缀、路径、通配符、正则、单标签前缀与 IP 字面量规则逐类计入损失报告。被代理规则完全覆盖的 `@@` 例外不写入无效 ACL 项(sslocal 域名匹配 proxy_list 优先于 bypass_list),保留代理规则,遮蔽数只计入 `absorbedCount`;逐条取证输出到维护脚本 stdout。 +- **geolocation-cn**:人工复验上游后运行 `Scripts/update-geolocation-cn.sh`,从固定版 [Loyalsoldier/domain-list-custom](https://github.com/Loyalsoldier/domain-list-custom) `geosite.dat` 解析 typed 条目并生成 `Vendor/rules/geolocation-cn/snapshot.json`。 +- **china-ipv4**:运行 `Scripts/update-china-ipv4.sh`,从固定版 [gaoyifan/china-operator-ip](https://github.com/gaoyifan/china-operator-ip) `china.txt` 规范化并去重 IPv4 CIDR,生成 `Vendor/rules/china-ipv4/snapshot.json`。 +- **gfwlist**:运行 `Scripts/update-gfwlist.sh`,从固定版 [gfwlist/gfwlist](https://github.com/gfwlist/gfwlist) `gfwlist.txt` 解码官方 Base64 AutoProxy 列表并生成 `Vendor/rules/gfwlist/snapshot.json`。`||host` / `||host^` 转换为域名后缀匹配;`|scheme://host`(可含合法端口)在路径为空或仅为 `/`,无查询、fragment 或用户信息,且 host 为无通配符的合法域名时,提取 host 转换为精确域名匹配,忽略协议和端口。仅含根路径 `/` 可转换,包含具体路径的规则继续跳过。`@@` 保留直连动作。其他 URL 前缀、路径、通配符、正则、单标签前缀与 IP 字面量规则逐类计入损失报告。被代理规则完全覆盖的 `@@` 例外不写入无效 ACL 项(sslocal 域名匹配 proxy_list 优先于 bypass_list),保留代理规则,遮蔽数只计入 `absorbedCount`;逐条取证输出到维护脚本 stdout。 快照使用 schema 2 / converter 2.0.0 的紧凑 JSON:每条规则只有 `action` 和 `match`,来源只在 `metadata.source`,转换报告只保留计数。被吸收的 `.cn` 条目与被遮蔽的 GFWList 例外不随快照分发,禁用宽规则后不再恢复;详见 [ADR-0024](adr/0024-snapshot-drops-absorbed-and-forensics.md)。旧版本快照拒载。