feat(assists): 添加步骤管理器和步骤实现基类

ven-coder · ven-coder · commit 7db4d337900f · 2025-03-12T07:53:10.000+08:00
- 新增 StepManager 类，用于管理和执行自动化步骤
- 新增 StepImpl 类，作为步骤实现的基础类
- 更新 documents.md，添加 StepManager 和 StepImpl 的说明和使用示例
- 优化 StepOperator 类，增加步骤重复执行和链式调用支持
diff --git a/assists/src/main/java/com/ven/assists/stepper/StepImpl.kt b/assists/src/main/java/com/ven/assists/stepper/StepImpl.kt
@@ -3,19 +3,39 @@ package com.ven.assists.stepper
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
 
+/**
+ * 步骤实现基类
+ * 用于实现自动化脚本的基础类，提供步骤实现的框架和协程执行环境
+ * 继承此类的子类需要实现onImpl方法来定义具体的步骤逻辑
+ */
 abstract class StepImpl {
 
+    /**
+     * 步骤实现方法
+     * 子类必须实现此方法来定义具体的步骤逻辑
+     * 通过StepCollector来收集和注册步骤的具体实现
+     *
+     * @param collector 步骤收集器，用于注册步骤的具体实现
+     */
     abstract fun onImpl(collector: StepCollector)
 
     /**
      * IO协程执行任务
+     * 在Dispatchers.IO协程上下文中执行指定的挂起函数
+     * 适用于执行IO操作、网络请求等耗时任务
+     *
+     * @param function 要执行的挂起函数
      */
     suspend fun runIO(function: suspend () -> Unit) {
         withContext(Dispatchers.IO) { function.invoke() }
     }
 
     /**
      * 主协程执行任务
+     * 在Dispatchers.Main协程上下文中执行指定的挂起函数
+     * 适用于执行UI操作、更新界面等需要在主线程进行的任务
+     *
+     * @param function 要执行的挂起函数
      */
     suspend fun runMain(function: suspend () -> Unit) {
         withContext(Dispatchers.Main) { function.invoke() }
diff --git a/assists/src/main/java/com/ven/assists/stepper/StepManager.kt b/assists/src/main/java/com/ven/assists/stepper/StepManager.kt
@@ -7,21 +7,43 @@ import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.cancel
 
-
 /**
  * 步骤管理器
+ * 用于管理和执行自动化步骤的核心类。提供步骤注册、执行、监听等功能，
+ * 支持协程异步执行和步骤间延时控制。
  */
 object StepManager {
-    //步骤默认间隔时长
+    /**
+     * 步骤默认间隔时长（毫秒）
+     * 用于控制连续步骤执行之间的默认等待时间
+     */
     var DEFAULT_STEP_DELAY = 1000L
 
-    //步骤监听器
+    /**
+     * 步骤监听器
+     * 用于监听步骤执行的状态和进度
+     */
     var stepListeners: StepListener? = null
 
+    /**
+     * 步骤收集器映射
+     * 存储所有已注册的步骤实现类及其对应的步骤收集器
+     * key: 步骤实现类的完整类名
+     * value: 对应的步骤收集器实例
+     */
     private val stepCollector: HashMap<String, StepCollector> = hashMapOf()
 
+    /**
+     * 协程作业实例
+     * 用于管理步骤执行的协程生命周期
+     */
     private var job = Job()
 
+    /**
+     * 协程作用域
+     * 提供步骤异步执行的协程环境
+     * 当job被取消或不活跃时会自动创建新的协程作用域
+     */
     var coroutine: CoroutineScope = CoroutineScope(job + Dispatchers.IO)
         private set
         get() {
@@ -32,12 +54,10 @@ object StepManager {
             return field
         }
 
-
-
-
     /**
      * 控制停止操作的变量
-     * 当设置为true时，将取消步骤器下的所有步骤（需要执行步骤时需要设置为false）
+     * 当设置为true时，将取消步骤器下的所有步骤
+     * 在执行新的步骤前需要将其设置为false
      */
     var isStop = false
         set(value) {
@@ -48,12 +68,28 @@ object StepManager {
             }
         }
 
-
+    /**
+     * 执行指定步骤
+     * 
+     * @param stepImpl 步骤实现类的Class对象
+     * @param stepTag 步骤标识
+     * @param delay 步骤执行前的延迟时间（毫秒），默认使用DEFAULT_STEP_DELAY
+     * @param data 传递给步骤的数据
+     * @param begin 是否作为起始步骤（如果是，会重置isStop标志）
+     */
     fun <T : StepImpl> execute(stepImpl: Class<T>, stepTag: Int, delay: Long = DEFAULT_STEP_DELAY, data: Any? = null, begin: Boolean = false) {
         execute(stepImpl.name, stepTag, delay, data = data, begin = begin)
     }
 
-
+    /**
+     * 执行指定步骤
+     * 
+     * @param implClassName 步骤实现类的完整类名
+     * @param stepTag 步骤标识
+     * @param delay 步骤执行前的延迟时间（毫秒），默认使用DEFAULT_STEP_DELAY
+     * @param data 传递给步骤的数据
+     * @param begin 是否作为起始步骤（如果是，会重置isStop标志）
+     */
     fun execute(implClassName: String, stepTag: Int, delay: Long = DEFAULT_STEP_DELAY, data: Any? = null, begin: Boolean = false) {
         if (begin) isStop = false
         if (isStop) return
@@ -70,7 +106,10 @@ object StepManager {
     }
 
     /**
-     * 注册业务实现类
+     * 注册步骤实现类
+     * 创建步骤收集器并初始化步骤实现类
+     * 
+     * @param implClassName 步骤实现类的完整类名
      */
     fun register(implClassName: String) {
         StepCollector(implClassName).let {
diff --git a/assists/src/main/java/com/ven/assists/stepper/StepOperator.kt b/assists/src/main/java/com/ven/assists/stepper/StepOperator.kt
@@ -9,16 +9,39 @@ import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
 import kotlin.coroutines.cancellation.CancellationException
 
+/**
+ * 步骤操作器
+ * 负责单个步骤的执行控制、状态管理和异常处理
+ * 支持步骤的重复执行、链式调用和协程调度
+ *
+ * @property implClassName 步骤实现类的完整类名
+ * @property step 步骤标识
+ * @property next 步骤执行的核心逻辑，返回下一个要执行的步骤
+ * @property isRunCoroutineIO 是否在IO线程执行，默认为false（在主线程执行）
+ * @property data 步骤执行时的附加数据
+ */
 class StepOperator(
     val implClassName: String,
     val step: Int,
     val next: suspend (stepOperator: StepOperator) -> Step,
     val isRunCoroutineIO: Boolean = false,
     var data: Any? = null
 ) {
+    /**
+     * 步骤重复执行的次数
+     * 当步骤返回Step.repeat时会增加计数
+     * 当步骤返回其他Step时重置为0
+     */
     var repeatCount = 0
         private set
 
+    /**
+     * 执行步骤
+     * 在协程中执行步骤，支持延迟执行和异常处理
+     *
+     * @param delay 执行前的延迟时间（毫秒）
+     * @param data 可选的步骤数据，会覆盖原有的data属性
+     */
     fun execute(delay: Long, data: Any? = null) {
         this.data = data
         if (StepManager.isStop) {
@@ -49,6 +72,15 @@ class StepOperator(
         }
     }
 
+    /**
+     * 处理下一个步骤
+     * 根据步骤的返回值决定后续操作：
+     * - Step.none: 停止执行
+     * - Step.repeat: 重复当前步骤
+     * - 其他: 执行指定的下一个步骤
+     *
+     * @param nextStep 下一个要执行的步骤
+     */
     private fun onNextStep(nextStep: Step) {
         when (nextStep) {
             Step.none -> {
@@ -77,6 +109,13 @@ class StepOperator(
         }
     }
 
+    /**
+     * 执行步骤的核心逻辑
+     * 处理步骤的生命周期回调和拦截逻辑
+     *
+     * @param next 步骤执行的具体逻辑
+     * @return 下一个要执行的步骤
+     */
     private suspend fun onStep(next: suspend (stepOperator: StepOperator) -> Step): Step {
         StepManager.stepListeners?.onStepStart(this)
         StepManager.stepListeners?.onIntercept(this)?.let { return it }
diff --git a/documents.md b/documents.md
@@ -115,18 +115,18 @@ Assists.getAllNodes().forEach { it.logNode() }
 |-|-|
 |[AssistsService](#assistsservice)|AccessibilityService服务类|
 |[AssistsCore](#assistscore)|基础类，对AccessibilityService API进行一系列的包装便于调用|
-|[AssistsWindowManager](#)|浮窗管理，管理浮窗添加、删除、触控手势切换、隐藏、浮窗toast|
-|[AssistsWindowWrapper](#)|浮窗包装，对浮窗移动、缩放做统一包装|
+|[AssistsWindowManager](#assistswindowmanager)|浮窗管理，管理浮窗添加、删除、触控手势切换、隐藏、浮窗toast|
+|[AssistsWindowWrapper](#assistswindowwrapper)|浮窗包装，对浮窗移动、缩放做统一包装|
 ## 进阶
 |类|描述|
 |-|-|
-|[MPManager](#)|屏幕录制管理，利用屏幕录制截取屏幕内容快捷获取图片，结合OpencvWrapper可以对图片进行识别操作等|
-|[OpencvWrapper](#)|Opencv包装，当前仅结合[MPManager](#)做简单的模版匹配包装，可自行结合[Assists]()、[MPManager](#)做更深层包装实现基于机器视觉的自动化|
+|[MPManager](#mpmanager)|屏幕录制管理，利用屏幕录制截取屏幕内容快捷获取图片，结合OpencvWrapper可以对图片进行识别操作等|
+|[OpencvWrapper](#opencvwrapper)|Opencv包装，当前仅结合[MPManager](#mpmanager)做简单的模版匹配包装，可自行结合[Assists](#assistscore)、[MPManager](#mpmanager)做更深层包装实现基于机器视觉的自动化|
 ## 高级
 |类|描述|
 |-|-|
-|[StepManager](#)|步骤管理器，对于实现自动化脚本提供一个快速实现业务、可复用、易维护的步骤框架及管理器|
-|[StepImpl](#)|步骤实现类，用于实现自动化脚本时继承此类|
+|[StepManager](#stepmanager)|步骤管理器，对于实现自动化脚本提供一个快速实现业务、可复用、易维护的步骤框架及管理器|
+|[StepImpl](#stepimpl)|步骤实现类，用于实现自动化脚本时继承此类|
 
 ### AssistsService
 无障碍服务核心类，负责处理无障碍服务的生命周期和事件分发，提供全局服务实例访问和监听器管理功能。
@@ -794,4 +794,104 @@ val result = OpencvWrapper.matchTemplate(screenMat, templateMat, mask)
 2. 模板匹配支持掩膜操作，可以指定匹配区域
 3. 获取匹配结果时可以设置忽略距离，避免相近位置重复匹配
 4. 所有涉及图像操作的方法都需要注意空值处理
-5. 图像掩膜创建支持HSV颜色空间的阈值分割，可以更精确地控制匹配区域
+5. 图像掩膜创建支持HSV颜色空间的阈值分割，可以更精确地控制匹配区域
+
+### StepManager
+步骤管理器，用于管理和执行自动化步骤的核心类。提供步骤注册、执行、监听等功能，支持协程异步执行和步骤间延时控制。
+
+#### 重要属性
+
+|属性|描述|
+|-|-|
+|`DEFAULT_STEP_DELAY`|步骤默认间隔时长（毫秒），用于控制连续步骤执行之间的默认等待时间|
+|`stepListeners`|步骤监听器，用于监听步骤执行的状态和进度|
+|`stepCollector`|步骤收集器映射，存储所有已注册的步骤实现类及其对应的步骤收集器|
+|`coroutine`|协程作用域，提供步骤异步执行的协程环境|
+|`isStop`|控制停止操作的变量，当设置为true时，将取消步骤器下的所有步骤|
+
+#### 核心方法
+
+|方法|描述|
+|-|-|
+|`execute(stepImpl: Class<T>, stepTag: Int, delay: Long, data: Any?, begin: Boolean)`|执行指定步骤，支持通过Class对象指定步骤实现类|
+|`execute(implClassName: String, stepTag: Int, delay: Long, data: Any?, begin: Boolean)`|执行指定步骤，支持通过类名字符串指定步骤实现类|
+|`register(implClassName: String)`|注册步骤实现类，创建步骤收集器并初始化步骤实现类|
+
+#### 使用示例
+
+1. 注册和执行步骤
+```kotlin
+// 注册步骤实现类
+StepManager.register("com.example.MyStepImpl")
+
+// 执行步骤
+StepManager.execute(
+    MyStepImpl::class.java,  // 步骤实现类
+    stepTag = 1,             // 步骤标识
+    delay = 1000,            // 延迟执行时间
+    data = "some data",      // 步骤数据
+    begin = true             // 作为起始步骤
+)
+```
+
+2. 停止步骤执行
+```kotlin
+// 设置停止标志，将取消所有正在执行的步骤
+StepManager.isStop = true
+```
+
+#### 注意事项
+
+1. 执行步骤前需要先注册对应的步骤实现类
+2. 步骤执行支持延迟和数据传递
+3. 可以通过begin参数指定是否作为起始步骤（会重置isStop标志）
+4. 步骤执行在协程中进行，支持异步操作
+
+### StepImpl
+步骤实现基类，用于实现自动化脚本的基础类，提供步骤实现的框架和协程执行环境。继承此类的子类需要实现onImpl方法来定义具体的步骤逻辑。
+
+#### 核心方法
+
+|方法|描述|
+|-|-|
+|`onImpl(collector: StepCollector)`|步骤实现方法，子类必须实现此方法来定义具体的步骤逻辑|
+|`runIO(function: suspend () -> Unit)`|在IO线程执行任务，适用于执行IO操作、网络请求等耗时任务|
+|`runMain(function: suspend () -> Unit)`|在主线程执行任务，适用于执行UI操作、更新界面等任务|
+
+#### 使用示例
+
+1. 创建步骤实现类
+```kotlin
+class MyStepImpl : StepImpl() {
+    override fun onImpl(collector: StepCollector) {
+        // 注册步骤1
+        collector.collect(1) { operator ->
+            // 在IO线程执行耗时操作
+            runIO {
+                // 执行耗时任务
+            }
+            
+            // 在主线程更新UI
+            runMain {
+                // 更新界面
+            }
+            
+            // 返回下一步
+            Step.next(2)
+        }
+        
+        // 注册步骤2
+        collector.collect(2) { operator ->
+            // 步骤逻辑
+            Step.none
+        }
+    }
+}
+```
+
+#### 注意事项
+
+1. 子类必须实现onImpl方法来定义步骤逻辑
+2. 使用runIO执行耗时操作，避免阻塞主线程
+3. 使用runMain执行UI相关操作，确保在主线程更新界面
+4. 每个步骤都需要返回一个Step对象来指示下一步操作
