Rules and Rulesets

📜 规则与规则集

SubConverter-Extended 可以使用传统 ruleset 定义、Clash/Mihomo 原生 Rule Provider，以及外部完整 Clash 规则。

基本规则集配置

TOML 示例：

[ruleset]
enabled = true
overwrite_original_rules = true
update_ruleset_on_request = false

[[rulesets]]
import = "snippets/rulesets.toml"

INI 使用 [rulesets] 段和重复的 ruleset= 项。YAML 使用相应序列。

原生 Clash/Mihomo Provider

常见类型：

• clash-domain:：域名规则；
• clash-ipcidr:：IP CIDR 规则；
• clash-classic:：经典完整规则。

直接 Provider URL、由 /getruleset 转换的 URL 和内联展开具有不同输出。不要仅根据 .txt 后缀猜测最终内容格式。

v1.7.1 Provider 路径

对非 Script 的 Clash/Mihomo Rule Provider，v1.7.1 生成的本地路径使用以下结构：

./providers/<provider-name>-<behavior>-<source-fingerprint>.<extension>

• <provider-name> 会只保留安全的文件名字符，并限制长度；无可用字符时使用 provider。
• <behavior> 为 domain、ipcidr 或 classical。
• <source-fingerprint> 是对原始规则来源 URL（移除 clash-domain: 等类型前缀后）计算的 16 位小写 FNV-1a 64 位指纹。策略组、Provider 显示名、behavior、输出格式和生成的 /getruleset URL 不参与指纹计算。
• 如果路径与基础模板或本次已生成的 Provider 冲突，程序会在 Provider 名称后追加 -2、-3 等序号，不会覆盖已有路径。

该路径用规则来源识别文件，避免不同 URL 只因文件名相同而复用同一路径。路径是生成结果的一部分；如果外部工具依赖旧路径，升级后需重新读取生成配置。

Provider format 和扩展名

规则来源	生成的 format	本地路径扩展名
直接 .mrs URL	mrs	.mrs
直接 .txt URL	text	.txt
直接 .yaml 或 .yml URL	yaml	.yaml
由后端 /getruleset 生成的 Provider	yaml	.yaml
其他直接 URL	省略，不猜测	.yaml

扩展名判断不受 URL 查询串或片段影响，且不区分大小写。未知扩展名不会被推断为 yaml、text 或 mrs；如果来源不符合客户端对 Provider 的实际格式要求，应改用带明确扩展名的资源或由 /getruleset 转换。

no-resolve

INI 在更新间隔后追加：

ruleset=🎯 全球直连,clash-ipcidr:https://example.com/cn-ip.yaml,28800|no-resolve

不要增加第四个逗号字段：

# 错误：会破坏传统解析
ruleset=🎯 全球直连,clash-ipcidr:https://example.com/cn-ip.yaml,28800,no-resolve

TOML/YAML 使用 options 序列。适用范围：

• 非 Script Clash/Mihomo 输出；
• clash-ipcidr；
• Provider 和内联展开的 IPv4/IPv6 规则。

clash-domain、clash-classic、Script 模式和非 Clash 目标会忽略该选项并记录警告。

外部完整规则

ruleprepend / ruleappend 是 SubConverter-Extended 扩展语法。

[custom]
ruleprepend=https://example.com/first.list
ruleappend=https://example.com/last.yaml

来源可以是：

• 每行一条完整规则的纯文本；
• 根节点为 rules: 序列的 YAML。

不支持：

• 根节点为 payload: 的 Provider 内容；
• 导入 MATCH 或 FINAL 终止规则；
• 本地文件和 data URL；
• target=clashr；
• list=true；
• script=true。

最终顺序

ruleprepend
基础模板中的非终止规则
生成的非终止规则
ruleappend
基础模板和生成的 MATCH / FINAL 尾部

多个来源和来源内部规则保持声明顺序，不自动去重。overwrite_original_rules=true 只移除基础模板原有规则，不移除 ruleprepend、ruleappend 或正常生成的规则。

失败语义

• 网络失败、非成功 HTTP 状态或空响应：记录并跳过当前外部完整规则来源，继续处理后续来源；
• 已下载内容无法解析或包含无效规则：转换返回 HTTP 400；
• 规则数量、来源数量和下载大小：受 advanced 资源限制控制；
• 请求方可控 URL：受安全档位的 SSRF 策略控制。

/getruleset

生成配置可能通过 /getruleset 把远程规则转换成目标格式。该接口的 type、url 和 group 由生成器构造，通常无需手动调用。

OpenClash 后续覆写

OpenClash 下载配置后仍可能在 LuCI 侧应用覆写。服务端输出中的规则顺序正确，不代表客户端侧覆写后仍保持相同顺序。排障时同时检查下载前配置和 OpenClash 最终运行配置。

验证

1. 使用 explain=true 检查规则集数量和加载状态。
2. 获取真实配置。
3. 使用目标客户端或配置解析器验证语法。
4. 检查终止规则位置。
5. 检查客户端侧是否再次覆写。