# shunt-rules

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

## 目标

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

## 目录结构

```text
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
bash tools/sync_surge_full.sh
```

2. 生成全部分类规则

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

3. 只生成指定分类

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

## 快捷方式

- 规则说明：`dist/README.md`
- Surge 目录：`dist/surge/`
- Loon 目录：`dist/loon/`
- Clash 目录：`dist/clash/`
- Mihomo 目录：`dist/mihomo/`

## 配置说明

默认配置：`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`）