守护 Diff 构建器

@adguard/diff-builder 是 npm 软件包,用于生成和应用 添加屏蔽过滤列表的差别更新 。 而不是重新下载 每次更新时, 服务器都会产生一个紧凑的 RCS 格式补丁 对于每个版本,客户端只获取它尚未获取的补丁 应用.

说明: 此软件包开发于 辅助软件。 。 。 . 这个 守护小组/ diffBuilder 寄存器是一个公共镜像.

货包载有两个独立的API和一个CLI:

• DiffBuilder ——服务器侧 (Node.js / CI): 比较两个过滤器 修改, 撰写补丁文件, 并管理补丁目录 .
• DiffUpdater ——客户端(Node.js或浏览器):正在获取 从 URL 补丁并将其应用到本地存储的过滤器上.
• diff-builder 国 际 - 包装 DiffBuilder 用于 shell 脚本和 CI管道.

目录

• 关键概念
• 安装
• 快速启动
• CLI 参考
• API 参考
  • DiffBuilder(节点.js)
  • DiffUpdater (Node.js / 浏览器) (中文(简体) )
• 文档

关键概念

过滤列表 ——包含广告屏蔽规则的平文文件. 每个 已公布的修订版是文件的快照.

RCS 补丁 - 一个紧凑的diff英寸 RCS 格式 编码两个连续过滤器修改之间的变化。 客户 依次应用补丁,以从以往的任何修订推进到当前 一个不下载完整文件.

补丁名称 ——每个补丁文件被命名,以便其元数据可以被解码 不读取文件 :

<name>[-<resolution>]-<epochTimestamp>-<expirationPeriod>.patch

• name ——任意标识字符串 (1-64个字符,无空格).
• resolution 两个数字字段的可选时间单位: h (小时, 默认), m (分钟), s (秒数).
• epochTimestamp ——补丁创建时间,在所选的解析中.
• expirationPeriod ——补丁是否有效,在所选的解析中.

Diff-Path 标签 —— 写入过滤文件的元数据行 客户端补丁目录的 URL :

! Diff-Path: https://example.com/filters/patches/v1.2.3-m-28334060-60.patch

DiffBuilder 自动添加并更新此标签 . DiffUpdater 读出来 以发现要获取补丁的地方.

校对和 - 嵌入在补丁中的可选 SHA-1 散列 diff 指令。 现在, DiffUpdater 之后验证过滤器内容 如果散列不匹配,则应用补丁并拒绝.

安装

运行时间要求 :

• 节点.js v20 或更高( 对于构建器和 CLI; 更新器也在其中运行) 浏览器).
• 调和 diff 工具( 运行时由构建者需要) :
  • macOS - 默认可用,或通过 xcode-select --install。 。 。 .
  • Linux - 默认可用,或 apt-get install diffutils。 。 。 .
  • Windows – 在 WSL 或 Git Bash 中可用.

在您的项目中添加:

npm install @adguard/diff-builder
# or
pnpm add @adguard/diff-builder

快速启动

生成补丁( 服务器 / CI)

# CLI: compare old_filter.txt → new_filter.txt, write patch to patches/
diff-builder build \
    -n my-filter \
    -t 60 \
    -r m \
    old_filter.txt \
    new_filter.txt \
    patches/

应用补丁(客户端)

import { DiffUpdater } from '@adguard/diff-builder/diff-updater/es';

const updatedFilter = await DiffUpdater.applyPatch({
    filterUrl: 'https://example.com/filters/filter.txt',
    filterContent: currentFilterText,
});

CLI 参考

diff-builder build [options] <old_filter> <new_filter> <path_to_patches>

立场参数 :

选项 :

示例——带有校验和验证的60分钟补丁:

diff-builder build \
    -n adguard-base \
    -t 60 \
    -r m \
    -c \
    -v \
    filters/base_old.txt \
    filters/base.txt \
    filters/patches/

API 参考

DiffBuilder(节点.js)

从两个过滤器修改生成补丁文件并管理补丁 目录。 需要节点和系统 diff 函数.

司法理事会

const { DiffBuilder } = require('@adguard/diff-builder');

无害环境管理

import { DiffBuilder } from '@adguard/diff-builder/es';

DiffBuilder.buildDiff(params)

await DiffBuilder.buildDiff({
    oldFilterPath,   // string — path to the previous filter revision
    newFilterPath,   // string — path to the new filter revision (updated in-place)
    patchesPath,     // string — directory to read/write patch files
    name,            // string — patch identifier (1–64 chars, no spaces)
    time,            // number — expiration period in units of `resolution`
    resolution,      // 'h' | 'm' | 's' — time unit (default: 'h')
    checksum,        // boolean — embed SHA-1 checksum (default: false)
    deleteOlderThanSec, // number — TTL for old patches in seconds (default: 604800)
    maxPatchSize,    // number — max patch size in bytes (default: 1048576)
    verbose,         // boolean — print progress messages (default: false)
});

被调用时:

1. 如果两个过滤器之间没有有意义的变化,则函数退出 不写任何文件.
2. 否则会在其中创建新补丁文件 patchesPath,更新 Diff-Path 标记在 newFilterPath,并删除已过期的补丁.
3. 如果生成的补丁大于 maxPatchSize,没有写到: 页:1 Diff-Path 标记未添加到 newFilterPath空占位符 补丁从 patchesPath。 。 。 .

错误 :

• 如果生成的补丁失败自我验证, 则拒绝 : 补丁不能是 应用到旧过滤器,或者补丁的旧过滤器与新过滤器不同 一个 基本错误作为 cause。 。 。 .
• 新过滤器和补丁文件在拒绝时没有写入; 已过期 补丁可能已被删除 .

DiffUpdater (Node.js / 浏览器) (中文(简体) )

获取并应用待补补补丁将本地存储的过滤器带入 约会。 与 Node.js 和浏览器环境兼容——不使用 fs, (中文(简体) ), path,或 child_process。 。 。 .

司法理事会

const { DiffUpdater } = require('@adguard/diff-builder/diff-updater');

无害环境管理

import { DiffUpdater } from '@adguard/diff-builder/diff-updater/es';

DiffUpdater.applyPatch(params)

const updatedFilter = await DiffUpdater.applyPatch({
    filterUrl,      // string — URL of the filter file (used to resolve patch URLs)
    filterContent,  // string — current filter text stored by the client
    verbose,        // boolean — print progress messages (default: false)
});
// Returns the updated filter content as a string.

职能:

1. 读取 Diff-Path 标记来自 filterContent 找到补丁 目录.
2. 在 URL 获取补丁文件 。 如果服务器返回 204 或 404 过滤器已经是当前和原始的 filterContent 已返回 不变.
3. 从补丁应用 RCS 操作到 filterContent。 。 。 .
4. 如果补丁包含校验和, 则验证结果并丢出 不符合.
5. 读取新的 Diff-Path 标记从更新的内容并重复到 没有其他补丁.

错误 :

• 掷出 UnacceptableResponseError 如果服务器返回 HTTP 状态 200、204或404除外.
• 丢出通用 Error 如果一个补丁形状不当或检查和校验 失败.

import {
    DiffUpdater,
    UnacceptableResponseError,
} from '@adguard/diff-builder/diff-updater/es';

try {
    const updated = await DiffUpdater.applyPatch({ filterUrl, filterContent });
} catch (err) {
    if (err instanceof UnacceptableResponseError) {
        // Network/server error — handle or retry
    }
    throw err;
}

文档

• 发展
• 部署
• 更改日志
• LLM 代理规则