GKD订阅规则编写完全指南：从入门到精通实战教程

前言

在当今移动应用生态中，广告拦截已成为提升用户体验的关键需求。GKD订阅项目通过智能规则定义，帮助用户自动化处理应用中的各类广告和干扰元素。本指南将带你全面掌握为GKD订阅项目编写高效规则的全过程，从基础环境搭建到高级规则优化，让你轻松成为规则编写高手。

一、快速上手：环境配置一键搞定

1.1 设备准备要点

• Android设备（建议系统版本11及以上，便于无障碍服务截屏）
• 电脑设备（可选，但能极大提升规则编写效率）

1.2 开发环境快速配置

项目基于现代化的Node.js和TypeScript技术栈，配置过程简单高效：

1. Node.js环境安装：推荐LTS稳定版本
2. 包管理工具选择：强烈建议使用pnpm，执行速度显著优于npm
3. 代码编辑器推荐：Visual Studio Code提供最完善的TypeScript支持

完成基础安装后，在项目根目录执行pnpm install即可完成依赖安装。

二、核心技能：快照捕获与智能分析

2.1 设备权限配置

1. 在目标应用中启用无障碍权限
2. Android 11以下设备需额外开启截屏服务
3. 建议开启悬浮窗服务，便于快速捕获界面快照

2.2 快照捕获的三种高效方式

悬浮窗按钮操作：通过悬浮窗服务提供的截屏按钮快速捕获

控制中心快捷功能：添加"捕获快照"快捷方式到控制中心

网页审查工具：最推荐的捕获方式，提供全面的分析功能

2.3 网页审查工具实战技巧

1. 确保设备和电脑处于同一局域网环境
2. 在设备上启用HTTP服务功能
3. 通过浏览器访问审查工具界面
4. 安装必要的浏览器扩展以优化使用体验

三、规则编写实战：从零到一完整流程

3.1 快照深度分析方法

以WPS应用为例，展示广告元素的精准定位技巧：

1. 精确定位广告关闭按钮位置
2. 通过审查工具查看节点详细属性
3. 识别唯一标识符（如ID、文本内容等关键信息）

3.2 选择器编写核心技巧

选择器语法与CSS选择器高度相似，常用模式包括：

• 精确ID匹配：[id="com.example.ad/close"]
• 后缀智能匹配：[id$="/close"]（匹配以"/close"结尾的所有ID）
• 文本内容匹配：[text="关闭广告"]

3.3 规则测试与优化策略

1. 在审查工具中验证选择器有效性
2. 通过"执行选择器"功能进行真机测试验证
3. 处理复杂场景下的多阶段广告（如关闭后出现的反馈弹窗）

3.4 完整规则示例详解

{
  id: 'cn.wps.moffice_eng',
  name: 'WPS',
  groups: [
    {
      key: 1,
      name: '分段广告-首页-文档列表广告',
      activityIds: [
        'cn.wps.moffice.main.StartPublicActivity',
        'cn.wps.moffice.main.local.HomeRootActivity'
      ],
      rules: [
        {
          matches: '[text="关闭当前广告"]',
          snapshotUrls: 'https://i.gkd.li/i/12505365'
        },
        {
          matches: '[id$="/nativeclose"]',
          snapshotUrls: [
            'https://i.gkd.li/i/12505350',
            'https://i.gkd.li/i/12505286'
          ]
        }
      ]
    }
  ]
}

四、代码提交规范：确保质量的关键步骤

4.1 文件结构标准化

1. 每个应用对应独立的TypeScript文件
2. 文件命名使用应用ID标准化格式
3. 文件存放在指定目录结构中

4.2 内容编写质量标准

1. 必须包含完整的应用元信息（id和name）
2. 每个规则组需要明确分类前缀标识
3. 必须提供有效的快照URL作为参考依据
4. 示例URL建议提供完整的广告展示截图

4.3 质量检查自动化流程

1. 本地运行pnpm run check验证规则有效性
2. 确保选择器语法完全正确
3. 验证快照URL可访问且与规则精准匹配

五、高级技巧进阶：提升规则编写水平

1. 多活动智能处理：针对应用的不同界面分别指定activityIds
2. 延迟点击优化：对于需要等待的元素，可配置合理的延迟时间
3. 复合选择器应用：结合多个属性提高匹配精确度
4. 排除规则设计：定义不应当匹配的特殊情况

六、注意事项与最佳实践

1. 规则分类必须使用预定义的标准分类体系
2. 避免使用"未分类"标签，除非特殊情况并获得许可
3. 每个规则修改应独立提交，便于审查和维护
4. 保持规则简洁高效，避免过度匹配影响应用正常功能

结语

通过本指南的详细指导，你已经掌握了为GKD订阅项目贡献规则的全流程。从环境配置到规则编写，再到最终提交，每个环节都需要细心和耐心。高质量的规则不仅能有效拦截广告，还能确保应用的正常功能不受影响。期待你的贡献能让整个移动应用生态更加纯净和友好。