# 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 配置）

## 快速开始

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

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

```bash
bash scripts/sync_surge_full.sh
```

2. 生成全部分类规则：

```bash
python3 main.py --config config.json
```

3. 只生成指定分类：

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

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

```bash
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.GITEA_USERNAME`（可选，默认 `yuanzhen869`）
- `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`）

## 目录结构

```text
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
```