GKD订阅规则机制：构建智能自动化生态-优快云博客

GKD订阅规则机制：构建智能自动化生态

GKD订阅规则系统采用高度结构化的JSON5格式来定义自动化点击规则，通过声明式配置实现精准的界面元素匹配与操作。系统包含订阅文件基础结构、规则组层级结构、规则项核心属性、选择器语法规范等核心组件，采用严格的数据结构规范确保规则的可读性、可维护性和执行效率。

订阅规则的数据结构与格式规范

GKD订阅规则系统采用高度结构化的JSON5格式来定义自动化点击规则，其核心设计理念是通过声明式配置实现精准的界面元素匹配与操作。订阅规则文件遵循严格的数据结构规范，确保规则的可读性、可维护性和执行效率。

订阅文件基础结构

每个订阅文件都是一个JSON5对象，包含以下核心字段：

字段名	类型	必填	描述
`id`	Long	是	订阅唯一标识符
`name`	String	是	订阅名称
`version`	Int	是	订阅版本号
`author`	String	否	作者信息
`updateUrl`	String	否	更新URL
`globalGroups`	Array[RawGlobalGroup]	否	全局规则组
`categories`	Array[RawCategory]	否	分类信息
`apps`	Array[RawApp]	否	应用特定规则

{
  id: 1234567890,
  name: "示例订阅",
  version: 100,
  author: "GKD Team",
  updateUrl: "https://example.com/update.json5",
  categories: [
    { key: 1, name: "开屏广告", enable: true }
  ],
  apps: [
    {
      id: "com.example.app",
      name: "示例应用",
      groups: [
        // 应用规则组定义
      ]
    }
  ]
}

规则组层级结构

GKD采用三层级的规则组织架构，确保规则的精细化管理：

mermaid

1. 全局规则组 (RawGlobalGroup)

全局规则组适用于所有应用或特定类型的应用，包含以下关键属性：

{
  key: 1001,
  name: "全局弹窗处理",
  desc: "处理各类应用的通用弹窗",
  enable: true,
  rules: [
    // 全局规则定义
  ],
  apps: [
    {
      id: "com.example.app1",
      enable: true,
      activityIds: ["MainActivity"],
      excludeActivityIds: ["SplashActivity"]
    }
  ],
  disableIfAppGroupMatch: "弹窗处理",
  matchAnyApp: true,
  matchSystemApp: false
}

2. 应用规则组 (RawAppGroup)

应用规则组针对特定应用设计，支持丰富的匹配条件：

{
  key: 2001,
  name: "开屏广告-跳过",
  desc: "跳过示例应用的开屏广告",
  enable: true,
  activityIds: ["SplashActivity", "AdActivity"],
  rules: [
    // 应用规则定义
  ],
  versionCode: {
    minimum: 1000,
    maximum: 2000,
    exclude: [1500]
  },
  versionName: {
    pattern: "^1\\.[0-9]+\\.0$",
    exclude: ["1.5.0"]
  }
}

规则项核心属性

每个规则项(RawAppRule/RawGlobalRule)包含丰富的匹配和执行属性：

属性类别	属性名	类型	描述
匹配条件	`matches`	Array[String]	必须全部匹配的选择器
	`anyMatches`	Array[String]	任意一个匹配的选择器
	`excludeMatches`	Array[String]	排除匹配的选择器
	`activityIds`	Array[String]	目标Activity ID
执行控制	`action`	String	执行动作类型
	`position`	Object	点击位置计算
	`actionCd`	Long	动作冷却时间(ms)
	`actionMaximum`	Int	最大执行次数
性能优化	`fastQuery`	Boolean	快速查询模式
	`matchRoot`	Boolean	从根节点开始匹配
	`matchDelay`	Long	匹配延迟时间

选择器语法规范

GKD采用类似CSS选择器的强大语法系统，支持丰富的匹配操作：

mermaid

选择器操作符详解

操作符	语法	示例	描述
等于	`=`	`[text='关闭']`	完全匹配文本
包含	`*=`	`[text*='广告']`	包含指定文本
开头	`^=`	`[text^='跳过']`	以指定文本开头
结尾	`$=`	`[text$='按钮']`	以指定文本结尾
正则	`~=`	`[text~='\\d+s']`	正则表达式匹配
不等于	`!=`	`[text!='取消']`	不等于指定文本

数据类型与验证机制

1. 字符串匹配器 (StringMatcher)

{
  pattern: "^广告.*$",
  include: ["跳过", "关闭"],
  exclude: ["立即下载", "升级"]
}

2. 数值匹配器 (IntegerMatcher)

{
  minimum: 1000,
  maximum: 2000,
  include: [1500, 1600],
  exclude: [1550]
}

3. 位置计算器 (Position)

支持基于数学表达式的精确位置计算：

{
  left: "width/2 - 50",
  top: "height - 100",
  right: null,
  bottom: null
}

版本控制与兼容性

订阅规则系统支持完善的版本控制机制：

{
  version: 20241201,  // 版本号格式: YYYYMMDD
  versionCode: {
    minimum: 100,     // 最低支持版本
    maximum: null     // 最高支持版本
  }
}

错误处理与验证

每个规则组和规则项都包含内置的验证机制：

val errorDesc by lazy { getErrorDesc() }
val valid by lazy { errorDesc == null }

系统会自动检测以下问题：

选择器语法错误
数学表达式计算异常
版本号格式错误
必填字段缺失

最佳实践建议

命名规范：规则组名称采用"功能-动作"格式，如"开屏广告-跳过"
版本管理：每次更新递增版本号，确保向后兼容
性能优化：合理使用fastQuery和matchRoot提升匹配效率
错误处理：为每个规则提供详细的desc描述和exampleUrls示例
测试验证：使用snapshotUrls提供快照链接便于测试验证

通过这种结构化的数据格式设计，GKD订阅规则系统能够实现高度灵活且可靠的自动化操作，为开发者提供了强大的界面元素识别和操作能力。

规则匹配引擎的工作原理

GKD的规则匹配引擎是整个系统的核心组件，它负责解析和执行用户定义的订阅规则，实现对Android界面元素的智能识别和自动化操作。该引擎采用类CSS选择器的语法设计，结合高效的遍历算法和类型检查机制，确保了匹配过程的准确性和性能。

核心架构与组件设计

GKD的匹配引擎采用分层架构设计，主要由以下几个核心组件构成：

mermaid

匹配流程与算法实现

GKD的匹配引擎采用深度优先搜索（DFS）算法，结合快速查询优化机制，实现了高效的节点匹配。整个匹配过程可以分为以下几个关键步骤：

1. 选择器解析与AST构建

当用户定义的选择器字符串传入时，引擎首先通过SelectorParser进行语法解析，构建抽象语法树（AST）。解析过程支持复杂的嵌套表达式和连接操作符：

// 选择器解析示例
val selector = Selector.parse("[text='跳过广告'] <<n [vid='ad_container']")

2. 类型检查与验证

在匹配开始前，引擎会进行严格的类型检查，确保表达式的合法性和类型一致性：

// 类型检查过程
override fun checkType(typeInfo: TypeInfo) {
    binaryExpressionList.forEach { exp ->
        if (!exp.operator.allowType(exp.left, exp.right)) {
            throw MismatchOperatorTypeException(exp)
        }
        val leftType = getExpType(exp.left, typeInfo)
        val rightType = getExpType(exp.right, typeInfo)
        if (leftType != null && rightType != null && leftType != rightType) {
            throw MismatchExpressionTypeException(exp, leftType, rightType)
        }
    }
}

3. 快速查询优化

为了提高匹配性能，引擎实现了快速查询（FastQuery）机制，针对常见的属性匹配进行优化：

// FastQuery类型定义
sealed class FastQuery(open val value: String) {
    data class Id(override val value: String) : FastQuery(value)
    data class Vid(override val value: String) : FastQuery(value)
    data class Text(override val value: String, val operator: CompareOperator) : FastQuery(value) {
        override fun acceptText(text: String): Boolean = when (operator) {
            CompareOperator.Equal -> text == value
            CompareOperator.Start -> text.startsWith(value)
            CompareOperator.Include -> text.contains(value)
            CompareOperator.End -> text.endsWith(value)
            else -> error("Invalid operator: $operator")
        }
    }
}

4. 节点遍历与匹配

匹配引擎采用递归下降的方式进行节点遍历，支持多种连接操作符：

操作符	描述	示例
`>`	祖先关系	`A > B` (A是B的祖先)
`<`	父子关系	`A < B` (A是B的子节点)
`<<`	后代关系	`A << B` (A是B的后代)
`+`	前兄弟节点	`A + B` (A在B之前)
`-`	后兄弟节点	`A - B` (A在B之后)
`->`	上下文前节点	`A -> B` (A是B的前节点)

mermaid

属性匹配机制

属性匹配是规则引擎的核心功能，支持多种匹配条件和操作符：

// 属性匹配实现
fun <T> match(context: QueryContext<T>, transform: Transform<T>): Boolean {
    return matchName(context.current, transform) && units.all { ex ->
        ex.expression.match(context, transform)
    }
}

private fun <T> matchName(node: T, transform: Transform<T>): Boolean {
    if (matchAnyName) return true
    val str = transform.getName(node) ?: return false
    if (str.length == name.length) {
        return str.contentEquals(name)
    } else if (str.length > name.length) {
        return str[str.length - name.length - 1] == '.' && str.endsWith(name)
    }
    return false
}

性能优化策略

GKD匹配引擎采用了多种性能优化策略：

快速查询缓存：对常见的id、vid、text属性建立快速查询索引
短路评估：在逻辑表达式中使用短路评估，提前终止不匹配的分支
类型预检查：在匹配前进行类型验证，避免运行时类型错误
遍历优化：针对不同的连接操作符实现专门的遍历算法

错误处理与异常机制

引擎实现了完善的错误处理机制，包括：

SyntaxException：语法解析错误
TypeException：类型不匹配错误
UnknownIdentifierException：未知标识符错误
MismatchParamTypeException：参数类型不匹配错误

// 异常处理示例
try {
    val selector = Selector.parse(ruleString)
    val result = selector.match(node, transform, MatchOption.default)
    // 处理匹配结果
} catch (e: TypeException) {
    // 处理类型错误
    logger.error("Type mismatch in rule: ${e.message}")
} catch (e: SyntaxException) {
    // 处理语法错误
    logger.error("Syntax error in rule: ${e.message}")
}

通过这种精心设计的架构和算法，GKD的规则匹配引擎能够在复杂的Android界面结构中高效、准确地识别目标元素，为自动化操作提供可靠的技术基础。

全局规则与应用特定规则设计

GKD的规则系统采用了精心设计的双轨制架构，通过全局规则（GlobalRule）和应用特定规则（AppRule）的协同工作，实现了灵活而强大的自动化控制能力。这种设计不仅确保了规则的精确匹配，还提供了高度的可配置性和扩展性。

规则类型架构设计

GKD的规则系统基于面向对象的设计理念，构建了清晰的类层次结构：

mermaid

应用特定规则（AppRule）设计

应用特定规则专门针对单个应用程序设计，提供了精细化的控制能力：

核心特性：

精确应用定位：通过appId精确绑定到特定应用
活动页面过滤：支持activityIds和excludeActivityIds进行页面级控制
版本兼容性检查：支持基于版本号和版本名称的条件匹配
启用状态管理：动态检测应用安装状态和启用条件

配置示例：

// AppRule 配置结构
val appRule = AppRule(
    rule = rawAppRule,        // 原始规则配置
    g = resolvedAppGroup,     // 解析后的应用组
    appInfo = appInfo         // 应用信息（版本、状态等）
)

匹配逻辑流程： mermaid

全局规则（GlobalRule）设计

全局规则设计用于跨应用场景，支持复杂的多应用匹配逻辑：

核心特性：

多应用支持：通过apps映射表管理多个应用的配置
系统级过滤：支持启动器应用和系统应用的单独控制
灵活的匹配策略：支持任意应用匹配、特定应用匹配混合模式
优先级控制：内置禁用 > 用户配置 > 规则自带的优先级体系

配置结构：

// GlobalRule 配置结构
val globalRule = GlobalRule(
    rule = rawGlobalRule,         // 原始全局规则
    g = resolvedGlobalGroup,      // 解析后的全局组
    appInfoCache = appInfoMap     // 应用信息缓存
)

规则匹配优先级体系

GKD实现了精细的规则匹配优先级控制，确保最精确的规则优先执行：

优先级	控制类型	描述	示例
1	内置禁用	系统级强制禁用	关键系统应用保护
2	用户配置	用户自定义设置	手动排除特定应用
3	规则自带	订阅规则定义	规则作者定义的排除列表
4	精确匹配	特定应用规则	AppRule的精确匹配
5	通配匹配	全局规则匹配	GlobalRule的通用匹配

高级匹配特性

版本控制匹配：

// 版本号匹配示例
val versionMatch = rule.versionCode?.match(appInfo.versionCode) ?: true
val nameMatch = rule.versionName?.match(appInfo.versionName) ?: true
val enable = versionMatch && nameMatch

活动页面通配符支持：

com.example.app.MainActivity - 精确匹配
com.example.app. - 包名前缀匹配
.*Dialog - 正则表达式匹配

性能优化设计

GKD在规则匹配过程中采用了多项性能优化措施：

缓存机制：应用信息缓存减少重复查询
延迟加载：规则按需加载和解析
优先级排序：高优先级规则优先匹配
短路评估：快速失败机制避免不必要的匹配

实际应用场景

场景1：跳过应用启动广告

{
  "key": "skip-startup-ad",
  "name": "跳过启动广告",
  "rules": [
    {
      "activityIds": ["com.example.app.MainActivity"],
      "matches": ["[text='跳过'][clickable=true]"],
      "action": "click"
    }
  ]
}

场景2：全局登录确认

{
  "key": "global-login-confirm", 
  "name": "电脑登录确认",
  "global": true,
  "rules": [
    {
      "matches": ["[text*='确认登录'][clickable=true]"],
      "action": "click"
    }
  ]
}

这种双轨制的规则设计使得GKD能够同时满足精确的单应用控制和灵活的跨应用场景需求，为用户提供了强大而易用的自动化体验。

规则优先级与冲突解决机制

在GKD订阅规则系统中，规则优先级机制是确保自动化操作精准执行的核心保障。当多个规则同时匹配到同一界面元素时，系统需要智能地决定执行顺序，避免冲突并确保用户体验的流畅性。

优先级控制机制

GKD通过多维度参数来控制规则的执行优先级，主要包括：

1. 时间优先级（priorityTime）

val priorityTime = rule.priorityTime ?: group.priorityTime ?: 0
val priorityEnabled: Boolean
    get() = priorityTime > 0

fun isPriority(): Boolean {
    if (!priorityEnabled) return false
    if (priorityActionMaximum <= actionCount.value) return false
    if (!status.ok) return false
    val t = System.currentTimeMillis()
    return t - matchChangedTime.value < priorityTime + matchDelay
}

时间优先级允许规则在特定时间窗口内获得优先执行权。当priorityTime设置为正值时，该规则在匹配后的指定毫秒数内具有最高优先级。

2. 执行次数限制（priorityActionMaximum）

val priorityActionMaximum = rule.priorityActionMaximum ?: group.priorityActionMaximum ?: 1

此参数限制优先级规则的最大执行次数，确保优先级规则不会无限期地霸占执行权。

3. 排序顺序（order）

val order = rule.order ?: group.order ?: 0
val currentRules = (appRules + globalRules).sortedBy { it.order }

order数值越小，优先级越高。系统按照order值对规则进行升序排序，数值相同的规则按定义顺序执行。

冲突解决策略

当多个规则可能产生冲突时，GKD采用分层决策机制：

mermaid

状态机管理

每个规则都有明确的状态管理，确保冲突时的合理处理：

状态类型	状态值	描述	处理方式
StatusOk	正常	规则可正常执行	优先执行
Status1	达到最大执行次数	actionMaximum限制	跳过
Status2	需要前置规则	preKeys未满足	等待前置
Status3	匹配延迟中	matchDelay时间内	延迟执行
Status4	超出匹配时间	matchTime超时	跳过
Status5	冷却时间中	actionCd时间内	等待冷却
Status6	触发延迟中	actionDelay时间内	延迟触发

实际应用场景

场景1：广告跳过优先级

{
  "key": 1001,
  "name": "开屏广告-最高优先级",
  "priorityTime": 5000,
  "priorityActionMaximum": 1,
  "order": -100,
  "matches": ["[text^='跳过']"],
  "action": "click"
}

在此场景中，开屏广告跳过规则被赋予最高优先级（order=-100），并在5秒内具有独占执行权，确保用户能够快速跳过广告。

场景2：规则依赖链

{
  "key": 2001,
  "name": "弹窗检测-前置规则",
  "preKeys": [2002],
  "matches": ["[text='确认']"],
  "action": "click"
},
{
  "key": 2002, 
  "name": "弹窗关闭-后置规则",
  "matches": ["[text='关闭']"],
  "action": "click"
}

通过preKeys机制，规则2001必须在规则2002触发后才能执行，建立了明确的执行依赖关系。

场景3：全局规则与应用规则冲突解决

mermaid

全局规则和应用规则的优先级处理遵循以下原则：

同优先级下，应用规则优先于全局规则
高优先级规则（priorityTime > 0）总是优先执行
order值较小的规则优先执行

性能优化策略

为了避免优先级机制导致的性能问题，GKD实现了多项优化：

延迟加载：优先级规则只在必要时才进行深度匹配
缓存机制：频繁使用的选择器表达式会被缓存
批量处理：多个事件被合并处理，减少重复计算
状态复用：规则状态在应用切换时智能重置

调试与监控

开发者可以通过以下方式监控优先级冲突：

查看规则状态日志（statusText输出）
监控actionCount和triggerTime变化
使用快照功能分析匹配过程

优先级机制的设计确保了GKD在面对复杂界面和多重规则时，能够智能地选择最合适的操作路径，既保证了自动化效率，又避免了不必要的冲突和误操作。

总结

GKD订阅规则系统通过精心设计的双轨制架构（全局规则和应用特定规则）和智能的优先级与冲突解决机制，实现了高度灵活且可靠的自动化操作。系统采用结构化JSON5数据格式、类CSS选择器语法、高效的匹配引擎算法，为开发者提供了强大的界面元素识别和操作能力。优先级控制机制通过时间优先级、执行次数限制和排序顺序等多维度参数，确保在多个规则匹配时能够智能决定执行顺序，避免冲突并保障用户体验的流畅性。这种设计使得GKD能够同时满足精确的单应用控制和灵活的跨应用场景需求。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考