Metadata-Version: 2.4
Name: misub
Version: 0.1.0
Summary: Local Mihomo subscription builder
Author: misub contributors
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6.0
Requires-Dist: ruamel.yaml>=0.18
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# misub

`misub` 是一个面向 Mihomo/Clash Meta 的本地订阅构建器。它从多个本地订阅 YAML 中抽取节点，按本地配置重新生成节点列表和代理组，避免依赖机场提供的分组与规则。

## 功能特性

- 从多个本地 Clash/Mihomo 订阅文件读取 `proxies` 节点。
- 使用 `sources[].name` 显式标记节点来源，不从节点名猜测机场。
- 通过 `regions` 配置识别地区，通过 `exclude.contains` 过滤套餐、流量、到期等非节点项。
- 使用 `naming` 模板输出短节点名，并在重名时自动追加后缀。
- 使用接近 Mihomo 原生结构的 `proxy-groups` 配置。
- 支持 `@region:地区`、`@source:来源`、`@all` 代理组占位符。
- 可通过 `preserve-base-proxies` 保留 `base.yaml` 中手写的静态代理。
- 默认只输出最终配置文件，不生成额外报告文件。

## 安装

开发版可在项目根目录安装：

```bash
pip install -e .
```

开发和测试依赖可使用额外依赖安装：

```bash
pip install -e ".[dev]"
```

## 快速开始

生成默认配置：

```bash
misub init
```

根据当前目录的 `misub.yaml` 构建配置：

```bash
misub build
```

指定配置文件构建：

```bash
misub build -c /path/to/misub.yaml
```

## 配置示例

```yaml
base: ./base.yaml
output: ./config.yaml
preserve-base-proxies: false

sources:
  - name: provider-a
    path: ./profiles/provider-a.yaml
  - name: provider-b
    path: ./profiles/provider-b.yaml

regions:
  日本: [日本, JP, Japan, Tokyo, 东京]
  新加坡: [新加坡, SG, Singapore, 狮城]
  香港: [香港, 港, HK, Hong Kong]
  台湾: [台湾, 台, TW, Taiwan]
  美国: [美国, US, USA, United States, 洛杉矶, LA]

exclude:
  contains: [流量, 到期, 过期, 官网, 套餐, 剩余, 网址, 群组]

naming: "{source}-{region}-{number}"

proxy-groups:
  - name: 节点选择
    type: select
    proxies:
      - 区域-日本
      - 区域-香港
      - DIRECT

  - name: 区域-日本
    type: fallback
    url: https://www.gstatic.com/generate_204
    interval: 300
    proxies:
      - "@region:日本"

  - name: 区域-香港
    type: fallback
    url: https://www.gstatic.com/generate_204
    interval: 300
    proxies:
      - "@region:香港"
```

## 构建规则

构建时会读取 `base` 指向的基础 Mihomo 配置，保留其中除 `proxies`、`proxy-groups` 外的字段，然后写入重新生成的节点和代理组。`base.yaml` 中未被覆盖字段的注释、引号以及 `|`、`>` 等块标量样式会尽量保留。生成的 `proxies` 节点和 `proxy-groups` 代理组使用单行 flow style 输出，减少最终配置文件长度。

默认情况下，输出的 `proxies` 只包含订阅来源中的保留节点。若 `base.yaml` 中存在手写静态代理，并且 `rules` 或代理组会引用这些代理，可设置：

```yaml
preserve-base-proxies: true
```

开启后，`base.yaml` 中原有 `proxies` 会保留在输出节点列表前部，订阅节点会追加在其后。

节点命名默认使用：

```text
{source}-{region}-{number}
```

编号优先从原始节点名中提取；无法提取时，在相同来源和地区内递增生成。无法识别地区的节点会归入 `未识别`，不会被默认丢弃。

## 占位符

| 占位符 | 含义 |
|--------|------|
| `@region:日本` | 展开为所有识别为日本的节点名 |
| `@source:provider-a` | 展开为 `provider-a` 来源的所有节点名 |
| `@all` | 展开为所有保留节点名 |

未知 `@` 占位符会导致构建失败，避免静默生成错误配置。

## 测试

```bash
python -m pytest -v
```

## 设计文档

详细设计见 [docs/2026-04-30-misub-design.md](./docs/2026-04-30-misub-design.md)。

## License

项目尚未声明许可证。发布到公开仓库前应补充许可证文件。
