shunt-rules/README.md

gitea-shunt-rules

基于 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/gitea-shunt-rules

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

配置说明

默认配置文件：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/generate-rules.yml

• 触发：push / schedule / 手动触发
• 流程：
  1. scripts/sync_surge_full.sh
  2. python3 main.py --config ...
  3. 若 dist/ 有变化则自动提交

2) 发布工作流（独立发布仓库）

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

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

目录结构

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