FilterFusion

多源广告过滤规则的自动聚合引擎 — 抓取 · 去重 · 融合 · 分发，一气呵成

中文 | English

关于

FilterFusion 是一个自动聚合和融合多源广告过滤规则的工具集。它帮你抓取主流规则源 → 去重合并 → 输出标准格式，彻底告别手动维护自定义规则列表。

VS 为什么选择 FilterFusion？

对比维度	😰 手动维护	✨ FilterFusion
多源聚合	逐个打开、复制粘贴	自动并发抓取
规则去重	肉眼比对、手动删除	Unicode NFKC 算法自动去重
规则分类	手动整理	按 ABP 标准 7 级自动分类
持续更新	想起来才更新	GitHub Actions 每日自动
分发部署	手动上传	jsDelivr + GitHub Raw 多 CDN 分发
元数据统计	无	自动输出控制台摘要

✨ 核心亮点

🚀 极致性能	🎨 高度可定制	⚡ 一键自动化	🔄 双管道并行
异步并发 + 预编译正则，大规模规则秒级处理	自由配置规则源、模板和输出格式	一条命令完成抓取、合并、发布全流程	AdBlock 浏览器拦截 + DNS 网络级拦截独立运行

💡 一句话总结：FilterFusion = 自动抓取 + 智能去重 + 标准输出 + 每日更新，让你专注规则质量，而不是重复劳动。

规则订阅地址

将对应链接导入你的广告拦截工具即可。每个地址为独立代码块，点击右上角复制按钮即可复制单个地址（推荐第一行 jsDelivr）：

🟦 AdBlock 规则（浏览器广告拦截）

📱 移动端（Mobile）

https://cdn.jsdelivr.net/gh/Chaniug/FilterFusion@main/dist/adblock-mo.txt

https://raw.githubusercontent.com/Chaniug/FilterFusion/main/dist/adblock-mo.txt

https://gh.llkk.cc/https://raw.githubusercontent.com/Chaniug/FilterFusion/main/dist/adblock-mo.txt

🖥️ 电脑端（PC）

https://cdn.jsdelivr.net/gh/Chaniug/FilterFusion@main/dist/adblock-pc.txt

https://raw.githubusercontent.com/Chaniug/FilterFusion/main/dist/adblock-pc.txt

https://gh.llkk.cc/https://raw.githubusercontent.com/Chaniug/FilterFusion/main/dist/adblock-pc.txt

📌 三个地址依次为：jsDelivr CDN（中国大陆推荐）/ GitHub Raw（全球）/ gh.llkk.cc（备用）

🟪 DNS 过滤规则（网络级广告拦截）

https://cdn.jsdelivr.net/gh/Chaniug/FilterFusion@main/dist/dns-blocklist.txt

https://raw.githubusercontent.com/Chaniug/FilterFusion/main/dist/dns-blocklist.txt

https://gh.llkk.cc/https://raw.githubusercontent.com/Chaniug/FilterFusion/main/dist/dns-blocklist.txt

📌 三个地址依次为：jsDelivr CDN（中国大陆推荐）/ GitHub Raw（全球）/ gh.llkk.cc（备用）

📋 规则反馈

如需反馈误拦截、漏拦截或希望补充的新规则，请前往我们的子项目 @Chaniug/AdSuper 提交规则 Issue，我们会及时处理！

系统要求

最低配置

项目	要求
🐍 Python	3.14+
💻 操作系统	Windows / macOS / Linux
🌐 网络	需要互联网连接以抓取规则源
📦 依赖	`httpx[http2]>=0.27.0`、`pyyaml>=6.0`

# 检查 Python 版本
python --version

快速开始

1. 克隆项目

git clone https://github.com/Chaniug/FilterFusion.git
cd FilterFusion

2. 安装依赖

pip install -r requirements.txt

3. 抓取并合并规则

管道	抓取	合并去重
🟦 AdBlock (Mobile)	`python -m scripts.fetch_rules`	`python -m scripts.merge_all`
🟦 AdBlock (PC)	`python -m scripts.fetch_rules`	`python -m scripts.merge_all`
🟪 DNS	`python -m scripts.fetch_dns_rules`	`python -m scripts.merge_dns_rules`

4. 使用生成的规则

生成的规则文件位于 dist/ 目录
直接导入到支持自定义规则的广告拦截工具中

工作原理

FilterFusion 的工作流程分为四个阶段，由两条独立管道并行运行。

点击查看详细工作流程图和技术细节

flowchart LR
    subgraph PIPE["两条独立管道"]
        direction TB
        subgraph AD["AdBlock 管道"]
            A1["📋 配置<br/>sources.yaml"] --> A2["⬇️ 抓取<br/>fetch_rules.py"]
            A2 --> A3["🔀 合并<br/>merge_all.py → merge_custom<br/>按 custom_rules 配置驱动"]
            A3 --> A4a["📤 输出<br/>adblock-mo.txt"]
            A3 --> A4b["📤 输出<br/>adblock-pc.txt"]
            A3 --> A4c["📤 输出<br/>自定义.txt"]
        end
        subgraph DNS["DNS 管道"]
            D1["📋 配置<br/>dns_sources.yaml"] --> D2["⬇️ 抓取<br/>fetch_dns_rules.py"]
            D2 --> D3["🔀 合并<br/>merge_dns_rules.py"]
            D3 --> D4["📤 输出<br/>dns-blocklist.txt"]
        end
    end
    A4a --> CDN["jsDelivr + GitHub Raw<br/>多 CDN 全球分发"]
    A4b --> CDN
    A4c --> CDN
    D4 --> CDN

    style AD fill:#ebf5ff,stroke:#2196f3
    style DNS fill:#f3e5f5,stroke:#9c27b0
    style CDN fill:#e8f5e9,stroke:#4caf50

规则格式: Adblock Plus（ABP）/ uBlock Origin / EasyList / 兼容 ABP 的格式均支持。

||example.com^                  # 域名屏蔽
example.com##.ad-banner         # 元素隐藏
@@||whitelist.com^$document     # 白名单放行

规则分类体系

合并引擎（merge_rules.py）会把每条规则识别为以下 7 种语义类型之一，并按类型分组输出（注释类不写入产物）：

类型	识别特征	示例
💬 注释	`!` 或 `[Adblock Plus]` 开头	`! Title: ...`
🟠 例外/白名单	`@@` 开头，或 `#@#` 元素隐藏例外	`@@\|\|trusted.com^$document`
🔴 正则规则	`/pattern/flags` 形式	`/ads\.example\.com/`
🟣 HTML/脚本注入	`#%#`、`#@%#`、`#?`、scriptlet 等	`example.com#%#//script:inject(...)`
🟡 元素隐藏	含 `##`	`example.com##.ad-banner`
🔵 特殊参数	`$` 后带 `badfilter`/`important`/`third-party` 等	`\|\|ad.com^$important`
🟢 普通屏蔽	其余（域名/网络屏蔽）	`\|\|doubleclick.net^`

实际输出分为 6 组（注释除外）：例外、元素隐藏、HTML/脚本注入、正则、特殊参数、普通屏蔽。DNS 规则由独立的 merge_dns_rules.py 管道处理，不在此列。

使用指南

配置规则源

编辑 config/sources.yaml（AdBlock）或 config/dns_sources.yaml（DNS），YAML 格式，GitHub 网页编辑有语法高亮。

点击查看详细配置说明和 YAML 示例

# config/sources.yaml — AdBlock 规则源
# category: mo(手机端) / pc(电脑端) / bo(两端共用，同 URL 只下载一次)
#   也兼容旧全称 mobile / pc / both；YAML 对大小写敏感，建议全小写
# 存在即启用，行首 # 注释即禁用
# 给源写说明：在某个源上方加一行 # 注释即可（脚本忽略，仅给人看）
sources:
  # AdGuard 官方移动端过滤规则
  - name: AdGuard Mobile
    category: mo
    url: https://raw.githubusercontent.com/.../filter.txt
    id: m1

  # AdGuard 中文广告过滤规则（两端共用）
  - name: AdGuard Chinese
    category: bo
    url: https://raw.githubusercontent.com/.../filter.txt
    id: b1

# 组合规则（custom_rules）— 按 ID 引用源，合并去重后输出到 dist/
#   output      : 输出文件名（保存到 dist/ 目录下，可自定义）
#   sources     : 引用上方 sources 里定义的 id 列表（按 id 引用源来组合产出文件）
#   description : 可选，规则文件的描述文本（会写入输出文件开头作为注释，不填则自动生成）
custom_rules:
  # 核心规则（文件名保持不变，订阅链接无需修改）
  - output: adblock-mo.txt
    description: FilterFusion - Ad blocking rules (Mobile)
    sources: [m1, m2, m3, b1, b2]

  - output: adblock-pc.txt
    description: FilterFusion - Ad blocking rules (PC)
    sources: [p1, b1, b2]

  # 示例：新增自定义规则（取消注释即可启用）
  # - output: exten.txt           # 输出文件名（可自定义，如 my-rules.txt）
  #   description: 我的自定义规则  # 可选，不填则自动生成
  #   sources: [m1, b1]          # 引用哪些源（填 id 列表），合并去重后输出到 exten.txt

# config/dns_sources.yaml — DNS 规则源
sources:
  - name: AdGuard DNS
    url: https://raw.githubusercontent.com/.../filter.txt
  # - name: HaGeZi DNS
  #   url: https://...

配置说明：

AdBlock 源（sources 段）：需 name、category、url、id 四个字段
- id 是唯一短编号（如 m1、b1、p1），被 custom_rules 引用
- category: bo 的源同 URL 只下载一次，自动分发给 mo 和 pc
- mo=手机端 / pc=电脑端 / bo=两端共用（也兼容全称 mobile/pc/both）
组合规则（custom_rules 段）：定义所有 AdBlock 产出文件
- output：输出文件名（保存到 dist/ 目录下，可自定义，如 exten.txt、my-rules.txt）
- sources：引用 sources 里定义的 id 列表（如 [m1, b1] 表示合并 m1 和 b1 两个源）
- description：可选，规则文件的描述文本（会写入输出文件开头作为注释，不填则自动生成）
- 新增自定义规则：取消注释「示例：新增自定义规则」下的示例行，修改 output、sources、description 即可
DNS 源（config/dns_sources.yaml）：仅需 name 和 url，不支持组合规则

抓取规则

python -m scripts.fetch_rules        # 抓取所有 AdBlock 规则源（异步并发）
python -m scripts.fetch_dns_rules    # 抓取所有 DNS 规则源（异步并发）

异步并发下载所有源，验证格式并缓存到 scripts/。

合并去重

python -m scripts.merge_all        # AdBlock 规则
python -m scripts.merge_dns_rules    # DNS 规则

自动分类 → NFKC 规范化去重 → 输出到 dist/。

导入工具

AdBlock（uBlock Origin / AdGuard / Brave 等）：打开扩展设置 → Filter lists → 粘贴订阅链接 → 导入。

DNS（AdGuard Home / Pi-hole / Clash 等）：管理界面 → DNS blocklists → 添加订阅链接。

兼容工具速览

点击查看支持的工具列表

工具	平台	AdBlock 规则	DNS 规则
uBlock Origin	浏览器扩展	✅	❌
AdGuard 浏览器扩展	浏览器扩展	✅	❌
Brave 内置拦截	浏览器	✅	❌
AdGuard Home	DNS 服务器	❌	✅
Pi-hole	DNS 服务器	❌	✅
AdGuard for Windows/Mac	桌面客户端	✅	✅
Clash / Sing-Box / Surge	代理客户端	❌	✅

应用场景

FilterFusion 的两条管道覆盖从浏览器到网络层的全链路过滤需求：

flowchart LR
    subgraph S1["🎯 个人使用"]
        P1["构建个人规则库"] --> P2["每日自动更新"]
    end
    subgraph S2["🏢 企业部署"]
        E1["内网 DNS 拦截"] --> E2["统一分发到全设备"]
    end
    subgraph S3["👪 家长控制"]
        F1["专用过滤规则"] --> F2["屏蔽不良内容"]
    end
    subgraph S4["🛠️ 工具集成"]
        D1["API 获取规则"] --> D2["嵌入自有产品"]
    end

    style S1 fill:#e3f2fd,stroke:#1976d2
    style S2 fill:#e8f5e9,stroke:#388e3c
    style S3 fill:#fff3e0,stroke:#f57c00
    style S4 fill:#fce4ec,stroke:#c62828

常见问题

点击查看常见问题解答（共 7 个）

Q1: 多久更新一次规则？

项目的 GitHub Actions 每日自动运行抓取和合并流程，dist/ 下的规则文件始终保持最新。如果你本地使用，建议每天或每周执行一次脚本。

Q2: 如何自定义规则源？

编辑 config/sources.yaml（AdBlock）或 config/dns_sources.yaml（DNS），YAML 格式：

# AdBlock 源（需 name / category / url / id）
sources:
  - name: 你的规则名
    category: mo          # mo=手机端 / pc=电脑端 / bo=两端共用（也兼容全称）
    url: https://example.com/filter.txt
    id: m1
  # - name: 不需要的源
  #   category: mo
  #   url: https://example.com/other.txt  （行首 # 注释即禁用）
  #   id: m2

规则源 URL 必须返回可直链访问的纯文本规则文件（ABP/uBlock/AdGuard 格式）。

Q3: 支持哪些格式？不生效怎么办？

支持 Adblock Plus（ABP）、uBlock Origin、EasyList 等兼容格式。

规则导入后不生效的常见原因：格式不兼容、工具对规则数量有限制、缓存未刷新。大多数工具支持多个规则列表同时使用——建议保留官方规则为基础，添加 FilterFusion 作为补充。

Q4: 生成的规则文件在哪里？

文件	类型	说明
`dist/adblock-mo.txt`	AdBlock	移动端合并规则，订阅推荐用此链接
`dist/adblock-pc.txt`	AdBlock	PC 端合并规则
`dist/dns-blocklist.txt`	DNS	最新合并 DNS 规则，订阅推荐用此链接

Q5: 规则文件多大？性能如何？

文件大小通常 2–5 MB（取决于规则源数量），现代浏览器和 DNS 工具均可轻松处理。建议定期检查文件大小，移除不需要的源。

Q6: 发现误拦截或漏拦截怎么办？

前往 AdSuper 项目提交 Issue，描述具体网址和拦截情况，我们会及时处理并更新规则。

Q7: 为什么每日更新工作流使用 `secrets.PAT`？

因为 GitHub Actions 默认的 GITHUB_TOKEN 触发的推送不会触发其他工作流（包括 Pages 部署）。为了让规则文件更新后自动重新部署 GitHub Pages，daily-update.yaml 使用 Personal Access Token（PAT）进行检出和推送（PAT 触发的推送会触发后续工作流）。

如果你要 Fork 本项目自行部署，需要在仓库 Settings → Secrets and variables → Actions 中创建名为 PAT 的 Secret，并确保该 Token 至少拥有当前仓库的 contents:write 权限。

如何参与

支持项目

点亮 Star 支持项目
Fork 项目参与开发
分享给更多人使用

参与开发

通过 Issue 反馈问题和建议
提交 Pull Request 贡献代码
在 Discussions 区分享想法

贡献流程

Fork 本项目
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
打开 Pull Request

许可证

联系方式

GitHub: @Chaniug
Issues: FilterFusion Issues
Discussions: FilterFusion Discussions

喜欢这个项目？请点个 Star ⭐ 来支持我们！

Name		Name	Last commit message	Last commit date
Latest commit History 903 Commits
.github/workflows		.github/workflows
assets		assets
config		config
dist		dist
docs		docs
scripts		scripts
.gitignore		.gitignore
CNAME		CNAME
LICENSE		LICENSE
README.md		README.md
README_EN.md		README_EN.md
_cdnauth.txt		_cdnauth.txt
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation