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

一、问题诊断：识别应用广告干扰

当你在使用"学习通"应用时，频繁弹出的课程推荐广告遮挡了学习内容，每次手动关闭不仅打断学习流程，还影响专注度。这种场景下，GKD订阅规则能自动识别并处理这些干扰元素，恢复应用的纯净体验。

广告元素通常具有以下特征：

• 固定位置出现的悬浮窗口
• 包含"关闭"、"跳过"等文字的按钮
• 具有明显视觉差异的独立UI区块
• 非应用核心功能的弹窗或横幅

二、方案设计：GKD规则工作原理

GKD订阅规则通过定义应用包名、界面活动和元素匹配规则，实现对特定UI元素的自动化操作。核心原理是基于Android视图树结构，使用选择器语法定位目标元素，并执行点击、隐藏等操作。规则文件采用TypeScript格式，通过模块化组织实现对不同应用的支持。

三、环境准备：开发环境搭建

准备条件

• Node.js 16.x或更高版本
• pnpm包管理器
• Visual Studio Code及相关插件

操作步骤

1. 克隆项目仓库

   git clone https://gitcode.com/gh_mirrors/gkd/GKD_subscription
   

2. 安装依赖

   cd GKD_subscription
   pnpm install
   

3. 配置开发工具

   • 安装VSCode插件：ESLint、Prettier、TypeScript React code snippets

验证方法

执行检查命令验证环境配置

pnpm run check

看到"All checks passed"提示表示环境搭建成功

常见错误排查

• 依赖安装失败：检查Node.js版本是否符合要求，使用pnpm cache clean清理缓存后重试
• TypeScript编译错误：确保tsconfig.json配置正确，执行pnpm run build查看详细错误信息

四、规则开发：分步实现广告拦截

1. 应用信息收集

使用Android调试工具获取应用包名和活动ID：

adb shell dumpsys window | grep mCurrentFocus

记录输出结果中的包名（如"com.example.app"）和活动名（如".MainActivity"）

2. 规则文件创建

在src/apps目录下创建以应用包名命名的TypeScript文件，例如com.example.app.ts

3. 基础规则框架编写

export default {
  id: 'com.example.app',
  name: '示例应用',
  groups: [
    {
      key: 1,
      name: '首页广告弹窗',
      activityIds: ['com.example.app.MainActivity'],
      rules: [
        {
          matches: '[text="关闭广告"]',
          action: 'click'
        }
      ]
    }
  ]
}

4. 选择器编写与测试

常用选择器类型及使用场景：

匹配方式	语法示例	应用场景
资源ID匹配	[resource-id="com.example:id/ad_close"]	元素有固定资源ID
文本包含	[text*="广告"]	元素文本包含特定关键词
类名匹配	[class="android.widget.Button"]	特定类型的控件
组合条件	[text="关闭"][clickable="true"]	多条件精确匹配

5. 规则调试

执行规则检查命令验证语法正确性：

pnpm run check:rules

效率提升技巧

• 使用VSCode代码片段快速生成规则框架
• 建立选择器测试沙盒，单独验证选择器有效性
• 使用Git分支管理不同应用的规则开发

五、场景拓展：处理复杂广告场景

1. 延迟操作配置

针对加载缓慢的广告元素，添加延迟执行配置：

{
  matches: '[text="关闭"]',
  action: 'click',
  delay: 1500 // 延迟1.5秒执行
}

2. 多步骤广告处理

处理关闭广告后出现的反馈弹窗：

{
  key: 2,
  name: '广告关闭后反馈弹窗',
  activityIds: ['com.example.app.MainActivity'],
  rules: [
    {
      matches: '[text="不再显示"]',
      action: 'click',
      delay: 500
    }
  ]
}

3. 元素隐藏策略

对于无法点击关闭的广告横幅，使用隐藏操作：

{
  matches: '[resource-id="com.example:id/ad_banner"]',
  action: 'hide'
}

六、质量优化：规则测试与完善

1. 本地测试流程

1. 将规则文件复制到GKD应用的自定义规则目录
2. 重启GKD应用使规则生效
3. 操作目标应用验证规则效果
4. 根据测试结果调整选择器和参数

2. 规则质量检查清单

• [ ] 选择器是否精准匹配目标元素
• [ ] 是否包含必要的延迟配置
• [ ] 规则是否影响应用正常功能
• [ ] 是否提供清晰的规则描述和分组

3. 性能优化建议

• 避免使用过于宽泛的选择器
• 合理设置规则优先级
• 对同一页面的多个规则进行分组管理

七、社区贡献：提交你的规则

贡献流程

1. 从主分支创建新分支，命名格式：feature/app-<包名>
2. 提交规则文件和相关说明
3. 运行本地检查确保没有错误
4. 创建Pull Request并填写详细描述

规则提交规范

• 文件名必须与应用包名完全一致
• 每个规则组需包含清晰的功能描述
• 复杂规则需添加注释说明设计思路
• 确保所有规则通过自动化检查

八、问题反馈与支持

反馈渠道

• 项目Issue跟踪系统：提交规则相关的bug报告和功能建议
• 社区讨论组：参与规则编写技巧交流
• 开发者文档：查阅详细的规则编写指南

常见问题解决

• 规则不生效：检查应用包名和活动ID是否正确
• 误操作正常元素：优化选择器精度，添加更多匹配条件
• 规则冲突：调整规则优先级或拆分复杂规则

九、工具推荐

1. UI分析工具：Android Studio Layout Inspector - 查看应用视图结构
2. 选择器生成器：GKD内置元素选择工具 - 自动生成元素选择器
3. 规则测试环境：GKD调试模式 - 实时测试规则效果
4. 批量处理工具：规则模板生成器 - 快速创建标准化规则文件

十、扩展阅读

• 官方规则编写规范
• Android视图结构解析
• CSS选择器高级用法
• TypeScript类型定义指南

通过本指南，你已掌握GKD规则开发的完整流程。从识别广告元素到编写精准规则，再到贡献社区，每个环节都需要实践和优化。高质量的规则不仅能提升个人使用体验，还能帮助整个社区用户摆脱广告干扰。期待你的贡献让GKD生态更加完善！