Clash Configuration Generator

用于生成 Clash 配置文件的脚本工具。

环境准备

1. 安装 Git。
2. 安装 Python。
3. 安装依赖：

pip install deepmerge
pip install ruamel.yaml

4. 拉取仓库（含子模块）：

git clone --recurse-submodules https://github.com/martincz/clash-configuration-generator.git

快速开始

1. 准备 preference.yaml（可从示例文件复制）：

文件名	说明
preference.yaml	实际生效配置
preference.basic.yaml	基础示例
preference.merlinclash.yaml	MerlinClash 示例
preference.advanced.yaml	进阶示例

2. 按需修改 preference.yaml。
3. 在仓库根目录执行：

python generate

4. 将生成的 config.yaml 导入 Clash 客户端。

generate 参数与示例

命令格式：

python generate [--dns] [--stdout|--dry-run] [-o|--output <path>]

参数说明：

参数	说明
--dns	生成结果中包含 DNS 配置（默认不输出 DNS 段）
--stdout	只输出到标准输出，不写入 config.yaml
--dry-run	与 --stdout 等价
-o, --output <path>	输出到指定文件，不写入默认 config.yaml

行为说明：

1. 默认行为是写入项目根目录 config.yaml。
2. 使用 --stdout 或 --dry-run 时，不会修改本地 config.yaml。
3. 使用 --output 时，会自动创建目标文件的父目录。
4. 不支持位置参数；未知选项或位置参数会返回错误码 2 并输出用法。

示例：

# 默认生成到 config.yaml
python generate

# 生成包含 DNS 配置的 config.yaml
python generate --dns

# 只预览，不落盘
python generate --stdout

# 生成到指定文件（推荐用于验证）
python generate --output config.preview.yaml

# 带 DNS 并输出到指定文件
python generate --dns --output config.preview.yaml

规则生成提示

1. 规则按 rules-prefix -> rulesets -> rules-suffix -> rules/suffix.yaml 的顺序合并。
2. rulesets 部分会按规则精度排序，并结合 rules-policy-priority 决定同精度冲突优先级。
3. 相同 TYPE+PATTERN 的重复规则会在生成阶段去重，保留排序更靠前的一条。
4. 未知规则类型会被跳过，并输出到 stderr。
5. 同一路径 ruleset 被配置到不同分组时，会输出告警，最终生效分组由 rules-policy-priority 决定。

ruleset-rule-patches（本地规则补丁）

当上游 ruleset 中存在不符合你分流策略的条目时，可以在 preference.yaml 中使用 ruleset-rule-patches 做本地修正，无需修改 rules/blackmatrix7 目录文件。

支持能力：

1. drop：删除指定规则（按 TYPE+PATTERN 匹配）
2. override：改写指定规则的分组（按 TYPE+PATTERN 匹配）

作用范围：

1. ruleset：按 ruleset 路径匹配
2. name：按 ruleset 名称匹配（即 rulesets 里的 name）
3. 未设置 ruleset/name 时，视为全局补丁

示例（把 Copilot 中的 challenges.cloudflare.com 删除，并把 OpenAI 中同条目改到 Proxy）：

ruleset-rule-patches:
  - ruleset: "rules/blackmatrix7/Copilot/Copilot_No_Resolve.yaml"
    drop:
      - "DOMAIN-SUFFIX,challenges.cloudflare.com"

  - name: "OpenAI"
    override:
      - match: "DOMAIN-SUFFIX,challenges.cloudflare.com"
        group: "Proxy"

测试

项目内置 unittest 回归测试，覆盖规则排序/去重、CLI 参数行为、proxy-group 容错等场景。

# 运行全部测试
python -m unittest discover -s tests -v

# 仅运行规则逻辑测试
python -m unittest tests.test_rule_logic -v

# 仅运行 generate 参数测试
python -m unittest tests.test_generate_cli -v

# 仅运行 proxy-group 容错测试
python -m unittest tests.test_proxy_group -v