shunt-rules/README.md

shunt-rules

基于 Surge 单源 的规则生成器，统一输出 Surge / Loon / Clash / Mihomo 四种格式。

目标

• 上游仅使用 ios_rule_script 的 rule/Surge
• 本地先合并与去重，再做多端格式转换
• 输出规则可直接用于常见代理客户端

目录结构

shunt-rules/
├── src/
│   └── rulegen.py                  # 主程序入口
├── tools/
│   └── sync_surge_full.sh          # 同步上游 Surge 源到本地缓存
├── configs/
│   ├── config.json                 # 默认配置（本地缓存模式）
│   └── examples/
│       ├── config.example.json
│       └── config.example.toml
├── data/
│   └── upstream/                   # 本地上游缓存（自动生成，默认忽略）
├── dist/
│   ├── surge/
│   ├── loon/
│   ├── clash/
│   └── mihomo/
└── .gitea/workflows/
    ├── repo-manage-daily.yml
    └── generate-rules.yml

运行环境

• Python 3.11+（推荐，支持 TOML 配置）
• Python 3.10（可用 JSON 配置）

快速开始

在仓库根目录执行：

1. 同步上游 Surge 源到本地缓存

bash tools/sync_surge_full.sh

2. 生成全部分类规则

python3 src/rulegen.py --config configs/config.json

3. 只生成指定分类

python3 src/rulegen.py --config configs/config.json --names Apple,YouTube

输出路径

• dist/surge/<Name>.list
• dist/loon/<Name>.list
• dist/clash/<Name>.yaml
• dist/mihomo/<Name>.yaml

配置说明

默认配置：configs/config.json

source 关键字段：

• mode：数据源模式，支持 local（本地缓存，推荐）和 gitea（通过 Gitea API）
• local_root：本地缓存根目录（默认 data/upstream）
• root：规则目录（默认 rule/Surge）
• filename_pattern：分类主文件模板（默认 {name}.list）
• include_categories：仅生成白名单分类
• exclude_categories：排除分类

output 关键字段：

• dir：输出目录（默认 dist）
• clash_no_resolve：Clash 的 IP-CIDR/IP-CIDR6 是否追加 no-resolve
• mihomo_no_resolve：Mihomo 的 IP-CIDR/IP-CIDR6 是否追加 no-resolve

本地合并规则

每个分类优先按以下顺序合并去重：

1. <Name>.list
2. <Name>_Domain.list
3. <Name>_Resolve.list

若上述文件不存在，会自动回退到：

1. <Name>_All.list
2. <Name>_Domain.list
3. <Name>_Resolve.list
4. <Name>.list

另外，*_Domain.list 中的裸域名会自动规范化为 DOMAIN-SUFFIX,<domain>。

多端转换策略

• surge：保留合并后的 Surge 规则
• loon：与 Surge 规则兼容输出
• clash：YAML provider 输出（跳过 USER-AGENT、URL-REGEX，并将 DEST-PORT 转为 DST-PORT）
• mihomo：YAML provider 输出，转换策略与 Clash 一致

自动化工作流

repo-manage-daily.yml：

• 每天自动执行（UTC 5 2 * * *）或手动触发
• 执行同步、生成规则、自动提交推送

generate-rules.yml：

• 手动触发
• 执行同步与生成，不自动发布

可选变量：

• vars.UPSTREAM_REF（默认 master）

私有仓库发布到公开仓库

当本仓库是私有时，外部无法直接访问规则文件。可启用以下工作流，将 dist/ 自动同步到公开仓库：

• .gitea/workflows/publish-public-rules.yml

需要在仓库设置中配置：

• vars.PUBLIC_REPO：公开仓库，格式 owner/repo
• vars.PUBLIC_BRANCH：公开仓库分支（可选，默认 main）
• secrets.PUBLIC_REPO_TOKEN：可写入公开仓库的 token