Dnr 规则集

用于为mv3扩展装入预建的AdGuard DNR规则的功能.

可用的过滤器列表可参见: filters 在元数据中:

• MV3铬过滤器, (中文(简体) ),

• 边缘 MV3 过滤器, (中文(简体) ),

• 歌剧院 MV3 过滤器。 。 。 .

• Dnr 规则集

  • 基本用途
    • 国 际
    • API 密码
    • 产出结构
    • 用户
      • 获取版本
      • 获得Version 时间戳
  • 高级用途
    • 将规则注入显示对象
  • 示例
  • 包含过滤列表
  • 管理 validator-data.json
    • 何时更新
    • 如何更新

基本用途

安装软件包 .

注:要及时更新过滤器,请确保您安装了最新版本的软件包.

npm install --save-dev @adguard/dnr-rulesets

国 际

1. 添加脚本到您的 package.json 要装入 DNR 规则和补丁扩展列表.

{
    "scripts": {
        "load-dnr-rulesets": "dnr-rulesets load <path-to-output>",
        "patch-manifest": "dnr-rulesets manifest <path-to-manifest> <path-to-filters>"
    }
}

可用命令 :

load 命令

下载并保存 DNR 规则到指定的目录 .

dnr-rulesets load <path-to-output>

备选方案 load 命令 :

• -l, --latest-filters - 下载最新文本过滤器而不是 DNR 规则( 默认: 假)
• -b, --browser <browser> - 指定可装入过滤器的浏览器 (默认:"铬-mv3"). 可用的浏览器 : chromium-mv3, (中文(简体) ), edge-mv3, (中文(简体) ), opera-mv3。 。 。 .

manifest 命令

补齐扩展列表以包含 DNR 规则 .

dnr-rulesets manifest <path-to-manifest> <path-to-filters> [options]

备选方案 manifest 命令 :

• -f, --force-update - 使用已存在的 id 强制更新规则( 默认: 假)
• -i, --ids <ids...> - 过滤 id 到附件, 其他将被忽略( 默认 : [] - 附加全部)
• -e, --enable <ids...> - 默认启用过滤器( 默认 : [])
• -r, --ruleset-prefix <prefix> - 过滤器 id 前缀( 默认: “ rulesset ”)
• -m, --filters-match <match> - 过滤文件与 glob 模式相匹配( 默认 : “ filter%%% ([ 0- 9]) ). txt )

关于数组选项的说明: 对于接受多个值的选项(ids 财务报告和审定财务报表 enable),使用下列语法:

--ids=1,2

watch 命令

监视过滤文件的更改并重建 DNR 规则.

dnr-rulesets watch <path-to-manifest> <path-to-resources> [options]

参数 :

• <path-to-manifest> - 运算表的路径.json文件
• <path-to-resources> - 有资源建立美元直接规则的文件夹 (可通过 @adguard/tswebextension war 命令)

备选方案 watch 命令 :

• -p, --path-to-filters - 过滤器和 i18n 元数据文件路径( 默认 ): ./filters 相对于显示文件夹)
• -o, --output-path-for-rulesets - 规则的输出路径 (默认 : ./filters/declarative 相对于显示文件夹)
• -f, --force-update - 使用已存在的 id (默认: true) 强制更新规则
• -i, --ids <ids...> - 过滤 id 处理, 其他将被忽略 (默认 : [] - 处理所有匹配的过滤器 --filters-match(中文(简体) )
• -e, --enable <ids...> - 默认情况下在表单中启用过滤器。json(默认:[])
• -r, --ruleset-prefix <prefix> - 过滤器 id 前缀( 默认: “ rulesset ”)
• -m, --filters-match <match> - 过滤文件与 glob 模式相匹配( 默认 : “ filter%%% ([ 0- 9]) ). txt )
• -l, --latest-filters - 在表前第一个开始下载最新文本过滤器( 默认: 虚假)
• -b, --browser <browser> - 指定下载最新过滤器的浏览器 (默认:"铬-mv3"). 见 --latest-filters 选项. 可用的浏览器 : chromium-mv3, (中文(简体) ), edge-mv3, (中文(简体) ), opera-mv3。 。 。 .
• -d, --debug - 在转换时允许扩展记录( 默认: 假)
• -j, --prettify-json - 预设 JSON 输出( 默认: 真)

exclude-unsafe-rules 命令

在指定的目录中扫描规则, 排除不安全的规则,并保存 排除元数据文件中不安全的规则,并更新规则检查和.

dnr-rulesets exclude-unsafe-rules <dir> [options]

参数 :

• <dir>: 包含要处理的规则的文件夹路径.

选项 :

• -j, --prettify-json <bool>: 保护 JSON 输出(true 或者说 false,默认值 : true(中文(简体) )
• -l, --limit <number>: 限制不安全规则的数量以排除. 如果不安全规则的数量超过这个限制, 命令会显示错误.

示例

dnr-rulesets exclude-unsafe-rules ./filters/declarative --prettify-json false --limit 100

关于数组选项的说明: 对于接受多个值的选项(ids 财务报告和审定财务报表 enable),使用下列语法:

--ids=1,2

1. 运行脚本以装入 DNR 规则作为构建流程的一部分 .

npm run load-dnr-rulesets

1. 补齐您的扩展列表以包含 DNR 规则 .

npm run patch-manifest

API 密码

您也可以将下载和更新运算表的功能整合到您的构建脚本中:

1. 装入 DNR 规则 .

   这种方法将预建资产复制到指定的输出目录,包括:

   • 用于所有可用过滤器的 JSON 格式的 DNR 规则
   • filters_i18n.json - 带有过滤名称和描述的翻译文件
   • local_script_rules.js - JS模块格式的本地脚本规则文件 高度建议提供 本地脚本规则 。 如果在构建过程中没有提供, 所有脚本规则 (脚本除外)不会被注入以确保遵守 Chrome Web Store 政策.
   • local_script_rules.json - JSON格式的本地脚本规则 标注 v2. 如果不提供,所有脚本规则都按允许的处理. 应根据其政策在Firefox AMO中提供.

   import { AssetsLoader, BrowserFilters } from '@adguard/dnr-rulesets';
   
   const loader = new AssetsLoader();
   await loader.load('<path-to-output>', options);
   

   地点 options 为具有下列属性的对象:

   export type AssetsLoaderOptions = {
       /**
        * Whether to download latest text filters instead of DNR rulesets.
       */
       latestFilters?: boolean;
   
       /**
        * For which browser load assets for.
       * Default value: `BrowserFilters.ChromiumMV3`.
       */
       browser?: BrowserFilters;
   };
   

To copy only the `declarative/` rulesets directory (skipping
`filters_i18n.json`, `local_script_rules.js`, etc.), pass the
`onlyDeclarativeRulesets` option. This is useful for Chrome Web Store
extensions that rely on the
[skip review](https://developer.chrome.com/docs/webstore/skip-review)
mechanism, which requires that only `rule_resources` files are changed:

```ts
await loader.load('<path-to-output>', { onlyDeclarativeRulesets: true });
```

To copy only the `declarative/` rulesets directory (skipping
`filters_i18n.json`, `local_script_rules.js`, etc.), pass the
`onlyDeclarativeRulesets` option. This is useful for Chrome Web Store
extensions that rely on the
[skip review](https://developer.chrome.com/docs/webstore/skip-review)
mechanism, which requires that only `rule_resources` files are changed:

```ts
await loader.load('<path-to-output>', { onlyDeclarativeRulesets: true });
```

2. 只复制本地脚本规则 .

   选项A:复制 JavaScript 格式规则

   import { AssetsLoader, BrowserFilters } from '@adguard/dnr-rulesets';
   
   const loader = new AssetsLoader();
   await loader.copyLocalScriptRulesJs('<path-to-output>', BrowserFilters.ChromiumMv3);
   

   此方法只复制 local_script_rules.js 文件到指定的目的目录.

   备选案文B:复制JSON格式规则

   import { AssetsLoader, BrowserFilters } from '@adguard/dnr-rulesets';
   
   const loader = new AssetsLoader();
   await loader.copyLocalScriptRulesJson('<path-to-output>', BrowserFilters.ChromiumMv3);
   

   此方法只复制 local_script_rules.json 文件到指定的目的目录.

3. 以自定义规则扩展本地脚本规则 .

   备选案文A:使用 extendLocalScriptRulesJs (主要V3级)

   import { AssetsLoader } from '@adguard/dnr-rulesets';
   
   const loader = new AssetsLoader();
   await loader.extendLocalScriptRulesJs(
       '<path-to-local-script-rules.js>',
       [
           'example.com#%#const ad = document.querySelector(".ad"); ad.remove();',
           'example.org#%#console.log("Custom script");'
       ]
   );
   

This method parses custom filtering rules, extracts JavaScript
injection rules from them, and appends them to an existing
`local_script_rules.js` file. It's useful for dynamically adding
custom JS rules to your extension at build time.

**Option B: Using `extendLocalScriptRulesJson`** (Manifest V2)

```ts
import { AssetsLoader } from '@adguard/dnr-rulesets';

const loader = new AssetsLoader();
await loader.extendLocalScriptRulesJson(
    '<path-to-local-script-rules.json>',
    [
        'example.com#%#const ad = document.querySelector(".ad"); ad.remove();',
        'example.org,~sub.example.org#%#console.log("Custom script");'
    ]
);
```

This method parses custom filtering rules, extracts JavaScript
injection rules with their domain configurations (both permitted and
restricted domains), and merges them into an existing
`local_script_rules.json` file. Use this method when you need to
maintain domain-specific rule associations.

> **Note:** The `extendLocalScriptRulesJs` and
> `extendLocalScriptRulesJson` methods are only available in the
> programmatic API and not in the CLI. These methods require
> programmatic access to parse and manipulate existing local script
> rule files, which is more suitable for build scripts and custom
> automation workflows rather than command-line usage.

4. 补丁扩展列表 .

   import { ManifestPatcher } from '@adguard/dnr-rulesets';
   
   const patcher = new ManifestPatcher();
   
   patcher.patch(
       '<path-to-manifest>',
       '<path-to-filters>',
       {
           // Optional: specify filter IDs to include
           ids: ['2', '3'],
           // Optional: specify enabled filter IDs
           enabled: ['2'],
           // Optional: set to true to overwrite existing rulesets
           forceUpdate: true,
           // Optional: set prefix for ruleset paths
           rulesetPrefix: 'ruleset_',
           // Optional: specify filter files matching glob pattern
           filtersMatch: 'filter_+([0-9]).txt',
       },
   )
   

你也可以打电话 excludeUnsafeRules 在自定义中构建流程或自动化脚本.

import { excludeUnsafeRules } from '@adguard/dnr-rulesets';

await excludeUnsafeRules('<path-to-rulesets-dir>', {
    prettifyJson: true, // optional
    limit: 100,         // optional
});

产出结构

/
    |
    |filters
        |
        |<browser>
            |
            |declarative
            |   |
            |   |ruleset_0
            |   |   |
            |   |   |ruleset_0.json # This is special ruleset which stores metadata about all other rulesets
            |   |
            |   |ruleset_<id>
            |       |
            |       |ruleset_<id>.json # DNR ruleset converted from filter_<id>.txt
            |
            |filter_i18n.json # i18n metadata (name, description, etc.) for filters

何处 <browser> 是构建规则的浏览器,例如. chromium-mv3, (中文(简体) ), edge-mv3 或者说 opera-mv3。 。 。 .

用户

该软件包为DNR规则的工作提供了一套实用功能.

getVersion()

返回软件包的版本.

import { getVersion } from '@adguard/dnr-rulesets/utils';

const dnrRulesetsVersion = getVersion();

getVersionTimestampMs()

返回基于补丁版本的 dnr 规则集构建的时间戳, 如果补丁版本中没有日期和时间,则或函数调用当前时间戳.

import { getVersionTimestampMs } from '@adguard/dnr-rulesets/utils';

const dnrRulesetsBuildTimestamp = getVersionTimestampMs();

高级用途

将规则注入显示对象

我们还提供灵活的API,对显示对象适用规则. 如果您想在捆绑时补齐标本, 这会很有用 .

import { RulesetsInjector } from '@adguard/dnr-rulesets';

const injector = new RulesetsInjector();

const manifest = {
    // Your manifest data
};

const ManifestWithRulesets = injector.applyRulesets(
    (id) => `<path to rulesets>/${id}.json`,
    manifest,
    ['2', '3'],
    {
        // Optional: specify filter IDs to include
        ids: ['2', '3'],
        // Optional: specify enabled filter IDs
        enabled: ['2'],
        // Optional: set to true to overwrite existing rulesets
        forceUpdate: true,
        // Optional: set prefix for ruleset paths
        rulesetPrefix: 'ruleset_',
    },
);

示例

使用实例: 备注- api- mv3

包含过滤列表

见包含过滤器的列表 档案员(md)。 。 。 .

管理 validator-data.json

文件 tasks/validator-data.json 有两个目的:

1. 建设后验证 (单位:千美元)pnpm validate:assets:经过一个建筑 校验器将新生成的规则ID和元数据密钥与 这个文件。 如果两者不同, 构建失败, 错误请求更新 文件和更改日志.

2. 预建许可列表 (自动建设):当环境变量 DNR_FILTER_KNOWN_ONLY=true 设置(在 Docker/CI 自动构建中用于 稳定分支),只有此文件中列出的过滤器ID被下载. 防止过滤器中新添加的过滤器漏入 更古老的稳定建筑.

何时更新

更新 validator-data.json 当过滤器是 添加或删除 用于支持浏览器的注册。 典型情景:

• 在 FiltersRegistry 中发布新的过滤器 .
• 已存在的过滤器被移除或其ID更改 .

如何更新

1. 运行一个完整的构建以下载最新的过滤器并生成规则 :

   pnpm build:assets
   

2. 运行验证——它将失败并打印添加/删除的规则集ID:

   pnpm validate:assets
   

3. 更新 tasks/validator-data.json 与新数据。 最简单的办法是 将构建中的输出复制到文件, 保留 JSON 结构 包含每个浏览器条目(chromium-mv3, (中文(简体) ), edge-mv3, (中文(简体) ), opera-mv3),每个 包含 version, (中文(简体) ), rulesetIds,以及 rulesetMetadataKeys。 。 。 .

4. 弹出软件包版本——至少 小声 版本,不仅仅是 补丁。 过滤列表版本基于时间戳(例如. 4.2.20260617150056),所以是补丁起伏(例如. 4.2.3这将是 semver - 不及当前稳定过滤列表版本。 弹出 小版本(例如:. 4.3.0)确保软件包版本保持更大 比任何过滤列表版本。 然后更新更改日志.

5. 提交更新 validator-data.json 与版本起伏.

文档

• 更改日志
• 发展指南
• LLM 代理规则