shunt-rules-builder

基于 Surge 单源 的规则生成器：

1. 同步上游 ios_rule_script 的 rule/Surge 到本地缓存
2. 本地按分类做合并去重
3. 统一生成多端兼容规则

当前输出目录：

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

设计原则

• 上游只用 Surge 源，不直接拉 Clash 源
• Clash/Mihomo 均由 Surge 规则转换生成
• 本地先合并再转换，避免依赖远端即时拼接

运行环境

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

快速开始

cd /Users/yuan/Desktop/workspaces/docker/pve/shunt-rules-builder

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

bash scripts/sync_surge_full.sh

2. 生成全部分类规则：

python3 main.py --config config.json

3. 只生成指定分类：

python3 main.py --config config.json --names Apple,YouTube

4. 一键发布 dist/ 到 release 仓库：

bash scripts/release_dist.sh

配置说明

默认配置文件：config.json（已启用本地源模式）。

source 关键字段

• mode
  • local：从本地缓存读取（推荐）
  • gitea：从 Gitea API 直接读取
• local_root：本地缓存根目录（默认 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

如果某分类不完整，会自动回退到：

• <Name>_All.list
• <Name>_Domain.list
• <Name>_Resolve.list
• <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 同步适配

自动化

1) 全仓库自动管理（推荐）

文件：.gitea/workflows/repo-manage-daily.yml

• 触发：每天一次（cron: 5 2 * * *，UTC）+ 手动触发
• 流程：
  1. 同步上游 Surge 源
  2. 生成 dist/ 规则
  3. 自动提交并推送 builder 仓库变更
  4. 自动发布 dist/ 到 shunt-rules-release

需要配置：

• secrets.GITEA_TOKEN（必需）
• vars.GITEA_BASE_URL（可选，默认 https://git.halonice.com）
• vars.TARGET_OWNER（可选，默认 yuanzhen869）
• vars.TARGET_REPO（可选，默认 shunt-rules-release）
• vars.TARGET_BRANCH（可选，默认 main）
• vars.UPSTREAM_REF（可选，默认 master）

2) 手动生成工作流（备用）

文件：.gitea/workflows/generate-rules.yml

• 触发：手动触发
• 流程：同步上游并生成规则（不自动发布）

3) 手动发布工作流（备用）

文件：.gitea/workflows/publish-rules.yml

• 触发：手动触发
• 适合“生成仓库”和“发布仓库”分离
• 将 dist/ 同步到目标仓库分支（如 main / rules）

目录结构

shunt-rules-builder/
├── main.py
├── config.json
├── config.example.toml
├── config.example.json
├── scripts/
│   ├── sync_surge_full.sh
│   └── release_dist.sh
├── upstream/                # 本地上游缓存（自动生成，默认忽略）
│   └── rule/Surge/...
├── dist/
│   ├── surge/
│   ├── loon/
│   ├── clash/
│   └── mihomo/
└── .gitea/workflows/
    ├── repo-manage-daily.yml
    ├── generate-rules.yml
    └── publish-rules.yml