GKD订阅规则开发指南：从问题诊断到社区贡献

一、问题发现：识别应用广告干扰

1.1 广告行为特征分析

当使用移动应用时，常见的广告干扰表现为：启动时的全屏弹窗、内容流中的横幅广告、操作后的强制观看视频等。这些广告通常具有明显的视觉特征，如"关闭"按钮、广告标签或固定位置。

典型广告场景：

• 启动页广告：应用打开后全屏显示，需等待倒计时或点击关闭
• 信息流广告：夹杂在正常内容中的推广卡片
• 悬浮窗广告：位于界面边缘的可拖动广告组件
• 激励视频：完成特定操作前强制观看的视频广告

1.2 广告元素定位方法

要拦截广告，首先需要精确定位广告元素。这就像快递员根据地址找到具体住户一样，我们需要通过元素的"地址信息"来识别广告组件。

关键识别维度：

• 元素ID：应用开发中为组件分配的唯一标识
• 文本内容：按钮上的文字如"关闭广告"、"跳过"
• 位置特征：固定出现在屏幕底部或顶部的元素
• 资源特征：包含广告标识的图片或图标

二、方案设计：构建广告拦截规则

2.1 开发环境搭建

GKD订阅规则基于TypeScript语言编写，需要配置Node.js开发环境。

环境配置步骤：

1. 安装Node.js LTS版本（推荐16.x以上）
2. 安装pnpm包管理工具：npm install -g pnpm
3. 克隆规则仓库：git clone https://gitcode.com/gh_mirrors/gkd/GKD_subscription
4. 安装依赖：cd GKD_subscription && pnpm install
5. 配置VSCode编辑器，安装TypeScript插件

成功验证标准：运行pnpm run check命令无错误输出

2.2 规则文件结构设计

每个应用的拦截规则独立存放在src/apps目录下，文件名为应用包名.ts。

文件组织结构：

GKD_subscription/
├── src/
│   ├── apps/                # 应用规则目录
│   │   ├── com.example.app.ts  # 应用规则文件
│   ├── types.ts             # 类型定义
│   └── subscription.ts      # 订阅入口
└── package.json             # 项目配置

2.3 选择器语法设计

GKD选择器基于CSS选择器语法，用于精确定位界面元素。就像用GPS坐标定位位置一样，选择器能帮助GKD找到需要操作的界面元素。

常用选择器类型：

选择器类型	语法格式	应用场景	示例
ID精确匹配	[id="完整ID"]	元素有固定唯一ID	[id="com.douban.frodo/ad_close"]
ID包含匹配	[id*="部分ID"]	ID包含特定关键词	[id*="ad"] 匹配所有含ad的ID
文本匹配	[text="按钮文本"]	按钮文本固定不变	[text="跳过广告"]
文本包含	[text*="部分文本"]	文本包含特定词语	[text*="广告"]
复合条件	条件1 && 条件2	多条件筛选元素	[text="关闭"] && [id$="button"]

三、分步实现：编写实战规则

3.1 应用信息定义

每个规则文件首先需要定义应用的基本信息，包括应用包名和名称。

// 抖音短视频应用规则示例
export default {
  id: 'com.ss.android.ugc.aweme',  // 参数名: 应用唯一标识，即包名
  name: '抖音',                     // 参数名: 应用名称，用于显示
  groups: [                         // 参数名: 规则组集合，可包含多个规则组
    // 规则组内容将在下方定义
  ]
}

3.2 规则组编写

规则组用于分类管理不同场景的广告拦截规则，每个规则组包含一个或多个具体规则。

{
  key: 1,                          // 参数名: 规则组唯一标识，数字类型
  name: '启动页广告',               // 参数名: 规则组名称，描述拦截场景
  activityIds: [                   // 参数名: 生效的页面列表
    'com.ss.android.ugc.aweme.splash.SplashActivity'
  ],
  rules: [                         // 参数名: 具体拦截规则集合
    {
      matches: '[text="跳过"] && [id$="skip_button"]',  // 参数名: 元素匹配条件
      action: 'click',                                 // 参数名: 执行动作，点击/隐藏
      delay: 1000,                                     // 参数名: 延迟执行时间(毫秒)
      snapshotUrls: ''                                 // 参数名: 广告截图证据链接
    }
  ]
}

避坑指南：

1. 错误：activityIds未指定或错误 解决：通过"开发者选项→显示活动"获取正确的页面标识

2. 错误：选择器过于简单导致误触 解决：使用复合条件提高选择器精确度，如同时匹配ID和文本

3. 错误：delay设置过短导致元素未加载 解决：根据广告加载速度调整延迟，一般设置1000-3000毫秒

3.3 复杂场景处理

某些应用广告具有复杂的展示逻辑，需要特殊处理策略。

场景假设：广告关闭后弹出"不感兴趣"反馈窗口，需要二次操作 问题拆解：1. 关闭初始广告 2. 处理反馈弹窗 解决方案：使用多规则组合处理

{
  key: 2,
  name: '视频播放页广告',
  activityIds: ['com.ss.android.ugc.aweme.detail.DetailActivity'],
  rules: [
    // 规则1: 关闭广告按钮
    {
      matches: '[text="关闭广告"]',
      action: 'click',
      delay: 1500
    },
    // 规则2: 处理反馈弹窗
    {
      matches: '[text="以后再说"]',
      action: 'click',
      delay: 500,
      // 仅在广告关闭后出现此弹窗时执行
      condition: 'prevRuleMatched'
    }
  ]
}

避坑指南：

1. 错误：未处理广告加载延迟 解决：设置合理delay或使用循环检测

2. 错误：规则执行顺序错误 解决：按实际交互流程排序规则，必要时使用condition控制执行条件

3. 错误：未考虑屏幕适配问题 解决：避免使用基于坐标的定位方式，优先使用ID和文本匹配

四、质量优化：规则测试与贡献

4.1 本地验证流程

规则编写完成后，需要进行本地验证确保有效性。

验证步骤：

1. 运行语法检查：pnpm run check
2. 检查规则格式：pnpm run lint
3. 本地测试规则：使用GKD应用导入本地规则文件

成功验证标准：

• 广告元素被正确识别并处理
• 应用正常功能不受影响
• 规则在不同设备上表现一致

4.2 规则质量提升

高质量的规则应满足以下标准：

简化方案（适用于新手）：

• 使用精确的ID匹配
• 为每个规则添加延迟时间
• 限制规则适用的页面范围

进阶方案（适用于复杂场景）：

• 使用条件规则处理动态场景
• 结合多个属性提高匹配精度
• 添加规则生效的时间条件

避坑指南：

1. 错误：规则过于宽泛导致误操作 解决：限制activityIds范围，使用更精确的选择器

2. 错误：未提供广告截图证据 解决：为每个规则添加snapshotUrls，提供广告场景截图

3. 错误：规则未考虑应用版本差异 解决：在规则描述中注明适用的应用版本范围

4.3 社区贡献流程

完成的规则可以提交到社区规则库，供其他用户使用。

贡献步骤：

1. 创建分支：git checkout -b feature/add-app-rule
2. 提交修改：git commit -m "feat: add rule for 抖音"
3. 推送分支：git push origin feature/add-app-rule
4. 创建合并请求

社区贡献价值评估：

• 基础贡献：单一简单规则，解决特定广告问题
• 中等贡献：完整应用规则集，覆盖多种广告场景
• 优质贡献：通用规则模板，帮助其他开发者快速编写规则
• 卓越贡献：规则优化工具或自动化测试方法，提升整体规则质量

通过贡献规则，不仅能帮助其他用户解决广告困扰，还能提升自己的移动开发和逆向分析能力。优质的规则会被更多用户采用，为社区带来显著价值。

总结

本指南通过"问题发现→方案设计→分步实现→质量优化"四个阶段，详细介绍了GKD订阅规则的开发流程。从识别广告特征到编写精确的选择器，再到测试和贡献规则，每个环节都需要细致的观察和不断的实践。随着移动应用广告形式的不断变化，规则编写也需要持续迭代优化。希望本文能帮助你成为GKD规则开发的贡献者，共同打造更纯净的移动应用体验。