ms-vite-plugin 1.1.2 → 1.1.4

package/docs/apipython/action.md

@@ -0,0 +1,901 @@
+# 动作模块 (Action)
+
+动作模块提供了丰富的触摸和按键操作功能，包括点击、滑动、长按滑动、返回首页、多点触摸等动作。
+
+**注意事项**
+
+- 此模块仅支持 快点 Agent 模式使用
+- HID 模式，请使用 HID 模块
+
+## 类型定义
+
+```python
+from typing import TypedDict, List, Literal, Optional
+
+class TapPoint(TypedDict):
+    x: int
+    y: int
+```
+
+## 抖动值
+
+### setJitterValue - 设置动作抖动值
+
+默认抖动值为 5 像素，设置后有 jitter 参数的动作会在像素范围 `-value` 到 `value` 随机偏移。
+
+```python
+def setJitterValue(value: int) -> None
+```
+
+**参数说明：**
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述 |
+| ---------- | ------- | -------- | ------ | ------------------------------------------------------- |
+| `value` | int | 是 | - | 抖动值，点击、滑动等动作会在像素范围 `-value` 到 `value` 随机偏移 |
+
+**返回值：** 无
+
+**示例:**
+
+```python
+from kuaijs import action
+# 设置抖动值为5像素
+action.setJitterValue(5)
+```
+
+## 基础触摸操作
+
+### click - 点击操作
+
+```python
+def click(x: int, y: int, duration: int = 20, jitter: bool = False) -> bool
+```
+
+**参数说明：**
+
+| 参数名     | 类型 | 是否必填 | 默认值 | 描述                   |
+| ---------- | ---- | -------- | ------ | ---------------------- |
+| `x`        | int  | 是       | -      | 点击的 x 坐标          |
+| `y`        | int  | 是       | -      | 点击的 y 坐标          |
+| `duration` | int  | 否       | 20     | 点击持续时间，单位毫秒 |
+| `jitter`   | bool | 否       | False  | 启用随机抖动偏移       |
+
+**返回值：**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 点击是否成功 |
+
+**示例：**
+
+```python
+from kuaijs import action
+
+# 基础点击
+if action.click(100, 100, 20, False):
+    print("点击成功")
+
+# 带抖动的点击（更自然，避免检测）
+action.click(200, 300, 50, True)
+
+# 快速点击
+action.click(150, 250, 10, False)
+
+# 长按效果（增加持续时间）
+action.click(100, 100, 800, True)
+```
+
+### clickRandom - 执行随机点击操作
+
+```python
+def clickRandom(x1: int, y1: int, x2: int, y2: int, duration: int = 20) -> bool
+```
+
+**参数说明：**
+
+| 参数名     | 类型 | 是否必填 | 默认值 | 描述                        |
+| ---------- | ---- | -------- | ------ | --------------------------- |
+| `x1`       | int  | 是       | -      | 随机点击区域的左上角 x 坐标 |
+| `y1`       | int  | 是       | -      | 随机点击区域的左上角 y 坐标 |
+| `x2`       | int  | 是       | -      | 随机点击区域的右下角 x 坐标 |
+| `y2`       | int  | 是       | -      | 随机点击区域的右下角 y 坐标 |
+| `duration` | int  | 否       | 20     | 点击持续时间，单位毫秒      |
+
+**返回值：**
+
+| 类型   | 描述             |
+| ------ | ---------------- |
+| `bool` | 随机点击是否成功 |
+
+**示例：**
+
+```python
+from kuaijs import action
+
+# 在指定矩形区域内随机点击
+action.clickRandom(100, 100, 200, 200, 20)
+
+# 在更大区域内随机点击
+action.clickRandom(50, 50, 400, 600, 50)
+
+# 快速随机点击
+action.clickRandom(150, 150, 250, 250, 10)
+```
+
+### doubleClick - 执行双击操作
+
+```python
+def doubleClick(x: int, y: int, duration: int = 20, interval: int = 20, jitter: bool = False) -> bool
+```
+
+**参数说明：**
+
+| 参数名     | 类型 | 是否必填 | 默认值 | 描述                             |
+| ---------- | ---- | -------- | ------ | -------------------------------- |
+| `x`        | int  | 是       | -      | 双击的 x 坐标                    |
+| `y`        | int  | 是       | -      | 双击的 y 坐标                    |
+| `duration` | int  | 否       | 20     | 每次点击的持续时间，单位毫秒     |
+| `interval` | int  | 否       | 20     | 两次点击之间的间隔时间，单位毫秒 |
+| `jitter`   | bool | 否       | False  | 启用随机抖动偏移                 |
+
+**返回值：**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 双击是否成功 |
+
+**示例：**
+
+```python
+from kuaijs import action
+
+# 基础双击
+if action.doubleClick(100, 100, 20, 20, False):
+    print("双击成功")
+
+# 带抖动的双击（更自然，避免检测）
+action.doubleClick(200, 300, 50, 20, True)
+
+# 慢速双击（增加间隔时间）
+action.doubleClick(100, 100, 30, 300, True)
+```
+
+### doubleClickRandom - 执行随机双击操作
+
+```python
+def doubleClickRandom(x1: int, y1: int, x2: int, y2: int, duration: int = 20, interval: int = 20) -> bool
+```
+
+**参数说明：**
+
+| 参数名     | 类型 | 是否必填 | 默认值 | 描述                             |
+| ---------- | ---- | -------- | ------ | -------------------------------- |
+| `x1`       | int  | 是       | -      | 随机双击区域的左上角 x 坐标      |
+| `y1`       | int  | 是       | -      | 随机双击区域的左上角 y 坐标      |
+| `x2`       | int  | 是       | -      | 随机双击区域的右下角 x 坐标      |
+| `y2`       | int  | 是       | -      | 随机双击区域的右下角 y 坐标      |
+| `duration` | int  | 否       | 20     | 每次点击的持续时间，单位毫秒     |
+| `interval` | int  | 否       | 20     | 两次点击之间的间隔时间，单位毫秒 |
+
+**返回值：**
+
+| 类型   | 描述             |
+| ------ | ---------------- |
+| `bool` | 随机双击是否成功 |
+
+**示例：**
+
+```python
+from kuaijs import action
+
+# 在指定矩形区域内随机双击
+action.doubleClickRandom(100, 100, 200, 200, 20, 20)
+
+# 慢速随机双击
+action.doubleClickRandom(100, 100, 300, 300, 30, 300)
+```
+
+### swipe - 执行滑动操作
+
+```python
+def swipe(startX: int, startY: int, endX: int, endY: int, duration: int = 100, jitter: bool = False, steps: int = 6) -> bool
+```
+
+**参数说明：**
+
+| 参数名     | 类型 | 是否必填 | 默认值 | 描述                                                   |
+| ---------- | ---- | -------- | ------ | ------------------------------------------------------ |
+| `startX`   | int  | 是       | -      | 滑动起始坐标 x 坐标                                    |
+| `startY`   | int  | 是       | -      | 滑动起始坐标 y 坐标                                    |
+| `endX`     | int  | 是       | -      | 滑动结束坐标 x 坐标                                    |
+| `endY`     | int  | 是       | -      | 滑动结束坐标 y 坐标                                    |
+| `duration` | int  | 否       | 100    | 滑动持续时间，单位毫秒                                 |
+| `jitter`   | bool | 否       | False  | 是否开启抖动，开启后会在滑动路径上随机偏移，默认 False |
+| `steps`    | int  | 否       | 6      | 生成抖动点的数量，影响滑动的平滑度，默认 6             |
+
+**返回值：**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 滑动是否成功 |
+
+**示例：**
+
+```python
+from kuaijs import action
+
+# 基础滑动（从左到右）
+action.swipe(100, 300, 400, 300, 500, False, 10)
+
+# 向上滑动（滚动页面）
+action.swipe(200, 600, 200, 200, 800, True, 15)
+
+# 向下滑动
+action.swipe(200, 200, 200, 600, 800, True, 15)
+
+# 对角线滑动
+action.swipe(100, 100, 300, 400, 1000, True, 20)
+
+# 快速滑动
+action.swipe(150, 500, 150, 100, 300, False, 5)
+
+# 慢速精确滑动
+action.swipe(100, 200, 300, 200, 1500, True, 30)
+```
+
+### pressAndSwipe - 执行长按滑动操作，适用于拖拽等场景
+
+```python
+def pressAndSwipe(startX: int, startY: int, endX: int, endY: int, touch_down_duration: int = 500, touch_move_duration: int = 1000, touch_up_duration: int = 500, jitter: bool = False, steps: int = 6) -> bool
+```
+
+**参数说明：**
+
+| 参数名                | 类型 | 是否必填 | 默认值 | 描述                                                   |
+| --------------------- | ---- | -------- | ------ | ------------------------------------------------------ |
+| `startX`              | int  | 是       | -      | 长按起始坐标 x 坐标                                    |
+| `startY`              | int  | 是       | -      | 长按起始坐标 y 坐标                                    |
+| `endX`                | int  | 是       | -      | 拖拽结束坐标 x 坐标                                    |
+| `endY`                | int  | 是       | -      | 拖拽结束坐标 y 坐标                                    |
+| `touch_down_duration` | int  | 否       | 500    | 按下阶段的持续时间，单位毫秒，默认 500ms               |
+| `touch_move_duration` | int  | 否       | 1000   | 移动阶段的持续时间，单位毫秒，默认 1000ms              |
+| `touch_up_duration`   | int  | 否       | 500    | 松开阶段的持续时间，默认 500ms                         |
+| `jitter`              | bool | 否       | False  | 是否开启抖动，开启后会在滑动路径上随机偏移，默认 False |
+| `steps`               | int  | 否       | 6      | 移动过程中的步数，影响滑动的平滑度，默认 6             |
+
+**返回值：**
+
+| 类型   | 描述             |
+| ------ | ---------------- |
+| `bool` | 长按滑动是否成功 |
+
+**示例：**
+
+```python
+from kuaijs import action
+
+# 拖拽元素
+action.pressAndSwipe(
+    100, 100, # 起始位置
+    300, 400, # 目标位置
+    500,      # 按下500ms
+    1000,     # 移动1000ms
+    200,      # 松开200ms
+    True,     # 开启抖动
+    20        # 20个步数
+)
+
+# 长按拖拽（更长的按下时间）
+action.pressAndSwipe(150, 200, 350, 500, 1000, 800, 300, True, 15)
+
+# 精确拖拽（无抖动）
+action.pressAndSwipe(200, 300, 200, 100, 300, 600, 100, False, 25)
+```
+
+### swipeCurve - 执行 3 点曲线滑动操作（先快后慢）
+
+```python
+def swipeCurve(startX: int, startY: int, midX: int, midY: int, endX: int, endY: int, duration: int = 1000) -> bool
+```
+
+**参数说明：**
+
+| 参数名     | 类型 | 是否必填 | 默认值 | 描述                                  |
+| ---------- | ---- | -------- | ------ | ------------------------------------- |
+| `startX`   | int  | 是       | -      | 滑动起始坐标 x 坐标                   |
+| `startY`   | int  | 是       | -      | 滑动起始坐标 y 坐标                   |
+| `midX`     | int  | 是       | -      | 曲线中间控制点 x 坐标                 |
+| `midY`     | int  | 是       | -      | 曲线中间控制点 y 坐标                 |
+| `endX`     | int  | 是       | -      | 滑动结束坐标 x 坐标                   |
+| `endY`     | int  | 是       | -      | 滑动结束坐标 y 坐标                   |
+| `duration` | int  | 否       | 1000   | 总滑动持续时间，单位毫秒，默认 1000ms |
+
+**返回值：**
+
+| 类型   | 描述             |
+| ------ | ---------------- |
+| `bool` | 曲线滑动是否成功 |
+
+**功能特点：**
+
+- 使用二次贝塞尔曲线算法生成平滑的滑动路径
+- 实现先快后慢的滑动效果，模拟真实的手势操作
+- 根据滑动距离自动调整路径点数量，确保滑动平滑度
+- **拟人化轨迹**：添加随机偏移和微抖动，模拟真实人手操作的不稳定性
+- **随机化时间**：每个路径点的时间间隔都有随机变化，避免机械化操作
+- **智能偏移**：中间路径点偏移更大，起点和终点保持精确，更符合人类操作习惯
+- 适用于需要更自然滑动轨迹场景
+
+**示例：**
+
+```python
+from kuaijs import action
+
+# 基础曲线滑动
+action.swipeCurve(100, 100, 200, 150, 300, 200, 1000)
+
+# 弧形向上滑动
+action.swipeCurve(200, 500, 150, 300, 200, 100, 800)
+
+# S形曲线滑动
+action.swipeCurve(100, 200, 300, 100, 200, 400, 1200)
+
+# 快速曲线滑动
+action.swipeCurve(150, 300, 250, 200, 350, 400, 600)
+
+# 慢速精确曲线滑动
+action.swipeCurve(100, 100, 200, 50, 300, 100, 1500)
+```
+
+## 文本输入操作
+
+- 仅输入框聚焦可用，以下方法是在模拟键盘操作
+- 更多高级输入操作，请参考 [IME 模块](ime.md)
+
+### input - 输入文本
+
+```python
+def input(text: str) -> bool
+```
+
+**参数说明：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述             |
+| ------ | ---- | -------- | ------ | ---------------- |
+| `text` | str  | 是       | -      | 要输入的文本内容 |
+
+**返回值：**
+
+| 类型   | 描述             |
+| ------ | ---------------- |
+| `bool` | 输入文本是否成功 |
+
+**示例：**
+
+```python
+from kuaijs import action
+if action.input("hello 快点JS"):
+    print("成功输入文本")
+```
+
+### backspace - 删除文本
+
+```python
+def backspace(count: int = 1) -> bool
+```
+
+**参数说明：**
+
+| 参数名  | 类型 | 是否必填 | 默认值 | 描述                        |
+| ------- | ---- | -------- | ------ | --------------------------- |
+| `count` | int  | 否       | 1      | 删除数量，默认删除 1 个字符 |
+
+**返回值：**
+
+| 类型   | 描述             |
+| ------ | ---------------- |
+| `bool` | 删除文本是否成功 |
+
+**示例：**
+
+```python
+from kuaijs import action
+
+# 删除最后一个字符
+if action.backspace():
+    print("成功删除最后一个字符")
+
+# 删除多个字符
+if action.backspace(3):
+    print("成功删除 3 个字符")
+```
+
+### enter - 调用回车
+
+```python
+def enter() -> bool
+```
+
+**返回值：**
+
+| 类型   | 描述             |
+| ------ | ---------------- |
+| `bool` | 调用回车是否成功 |
+
+**示例：**
+
+```python
+from kuaijs import action
+
+# 调用回车
+if action.enter():
+    print("成功调用回车")
+```
+
+## 系统按键操作
+
+### homeScreen - 返回到设备主屏幕
+
+```python
+def homeScreen() -> bool
+```
+
+**返回值：**
+
+| 类型   | 描述             |
+| ------ | ---------------- |
+| `bool` | 返回首页是否成功 |
+
+**示例：**
+
+```python
+from kuaijs import action
+
+# 返回主屏幕
+if action.homeScreen():
+    print("成功返回主屏幕")
+
+# 在操作完成后返回主屏幕
+def completeTaskAndGoHome():
+    # 执行一些操作...
+    action.click(200, 300, 100, True)
+
+    # 返回主屏幕
+    action.homeScreen()
+```
+
+### pressButton - 按下系统按钮
+
+```python
+def pressButton(button: Literal["home", "volumeup", "volumedown"]) -> bool
+```
+
+**参数说明：**
+
+| 参数名   | 类型    | 是否必填 | 默认值 | 描述                                                                                       |
+| -------- | ------- | -------- | ------ | ------------------------------------------------------------------------------------------ |
+| `button` | Literal | 是       | -      | 按钮类型： <br>-`"home"` Home 键 <br>- `"volumeup"` 音量上键 <br>- `"volumedown"` 音量下键 |
+
+**返回值：**
+
+| 类型   | 描述             |
+| ------ | ---------------- |
+| `bool` | 按下按钮是否成功 |
+
+**示例：**
+
+```python
+from kuaijs import action
+
+# 按下 Home 键
+action.pressButton("home")
+
+# 调高音量
+action.pressButton("volumeup")
+
+# 调低音量
+action.pressButton("volumedown")
+
+# 连续调节音量
+for i in range(5):
+    action.pressButton("volumeup")
+```
+
+## 动作构建器
+
+ActionBuilder 提供了更高级的多点触控操作能力，支持链式调用构建复杂的手势动作。
+
+### createBuilder - 创建 ActionBuilder 构建器
+
+```python
+def createBuilder() -> ActionBuilder
+```
+
+**返回值：**
+
+| 类型            | 描述                     |
+| --------------- | ------------------------ |
+| `ActionBuilder` | ActionBuilder 构建器实例 |
+
+**示例：**
+
+```python
+from kuaijs import action
+builder = action.createBuilder()
+```
+
+### ActionBuilder - ActionBuilder 构建器
+
+ActionBuilder 构建器支持链式调用，可以构建复杂的多点触控动作。
+
+#### addPointer - 添加指针（手指）
+
+```python
+def addPointer(id: int) -> PointerBuilder
+```
+
+**参数说明：**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述                                 |
+| ------ | ---- | -------- | ------ | ------------------------------------ |
+| `id`   | int  | 是       | -      | 指针编号，1-10，对应设备上的手指编号 |
+
+**返回值：**
+
+| 类型             | 描述                             |
+| ---------------- | -------------------------------- |
+| `PointerBuilder` | 指针构建器，用于配置该指针的动作 |
+
+**示例：**
+
+```python
+from kuaijs import action
+builder = action.createBuilder()
+# 添加第一个手指
+pointer1 = builder.addPointer(1)
+
+# 添加第二个手指
+pointer2 = builder.addPointer(2)
+```
+
+#### singleTap - 快速单点点击
+
+```python
+def singleTap(x: int, y: int, duration: int = 20) -> ActionBuilder
+```
+
+**参数说明：**
+
+| 参数名     | 类型 | 是否必填 | 默认值 | 描述                                  |
+| ---------- | ---- | -------- | ------ | ------------------------------------- |
+| `x`        | int  | 是       | -      | X 坐标                                |
+| `y`        | int  | 是       | -      | Y 坐标                                |
+| `duration` | int  | 否       | 20     | 点击持续时间，如果未定义则默认为 20ms |
+
+**返回值：**
+
+| 类型            | 描述                   |
+| --------------- | ---------------------- |
+| `ActionBuilder` | 返回自身，支持链式调用 |
+
+**示例：**
+
+```python
+from kuaijs import action
+builder = action.createBuilder()
+# 快速单点点击
+builder.singleTap(100, 100, 50).execute()
+
+# 连续点击
+builder.singleTap(100, 100, 30).singleTap(200, 200, 30).execute()
+```
+
+#### multiTap - 快速多点点击
+
+```python
+def multiTap(points: List[dict], duration: int = 20) -> ActionBuilder
+```
+
+**参数说明：**
+
+| 参数名     | 类型       | 是否必填 | 默认值 | 描述                                   |
+| ---------- | ---------- | -------- | ------ | -------------------------------------- |
+| `points`   | List[dict] | 是       | -      | 点击坐标数组，每个元素包含 x 和 y 坐标 |
+| `duration` | int        | 否       | 20     | 点击持续时间，如果未定义则默认为 20ms  |
+
+**返回值：**
+
+| 类型            | 描述                   |
+| --------------- | ---------------------- |
+| `ActionBuilder` | 返回自身，支持链式调用 |
+
+**示例：**
+
+```python
+from kuaijs import action
+builder = action.createBuilder()
+# 多点同时点击
+points = [
+  { "x": 100, "y": 100 },
+  { "x": 200, "y": 200 },
+  { "x": 300, "y": 300 },
+]
+builder.multiTap(points, 50).execute()
+
+# 双指点击
+builder.multiTap(
+    [
+      { "x": 150, "y": 300 },
+      { "x": 250, "y": 300 },
+    ],
+    100
+).execute()
+```
+
+#### execute - 执行动作
+
+```python
+def execute() -> bool
+```
+
+**返回值：**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 执行是否成功 |
+
+**示例：**
+
+```python
+from kuaijs import action
+builder = action.createBuilder()
+# 执行构建的动作
+success = builder \
+  .addPointer(1) \
+  .moveTo(100, 100) \
+  .tap(200, 200) \
+  .done() \
+  .execute()
+
+if success:
+    print("动作执行成功")
+```
+
+### PointerBuilder - 指针构建器
+
+指针构建器用于配置单个指针（手指）的动作序列。
+
+#### moveTo - 移动到指定坐标
+
+```python
+def moveTo(x: int, y: int, duration: int = 0) -> PointerBuilder
+```
+
+**参数说明：**
+
+| 参数名     | 类型 | 是否必填 | 默认值 | 描述                                 |
+| ---------- | ---- | -------- | ------ | ------------------------------------ |
+| `x`        | int  | 是       | -      | X 坐标                               |
+| `y`        | int  | 是       | -      | Y 坐标                               |
+| `duration` | int  | 否       | 0      | 移动持续时间，如果未定义则默认为 0ms |
+
+**返回值：**
+
+| 类型             | 描述                   |
+| ---------------- | ---------------------- |
+| `PointerBuilder` | 返回自身，支持链式调用 |
+
+#### down - 按下手指
+
+```python
+def down() -> PointerBuilder
+```
+
+**返回值：**
+
+| 类型             | 描述                   |
+| ---------------- | ---------------------- |
+| `PointerBuilder` | 返回自身，支持链式调用 |
+
+#### up - 抬起手指
+
+```python
+def up() -> PointerBuilder
+```
+
+**返回值：**
+
+| 类型             | 描述                   |
+| ---------------- | ---------------------- |
+| `PointerBuilder` | 返回自身，支持链式调用 |
+
+#### stay - 停留时间
+
+```python
+def stay(duration: int = 20) -> PointerBuilder
+```
+
+**参数说明：**
+
+| 参数名     | 类型 | 是否必填 | 默认值 | 描述                                      |
+| ---------- | ---- | -------- | ------ | ----------------------------------------- |
+| `duration` | int  | 否       | 20     | 停留时间（毫秒），如果未定义则默认为 20ms |
+
+**返回值：**
+
+| 类型             | 描述                   |
+| ---------------- | ---------------------- |
+| `PointerBuilder` | 返回自身，支持链式调用 |
+
+#### tap - 执行点击动作
+
+```python
+def tap(x: int, y: int, duration: int = 20) -> PointerBuilder
+```
+
+**参数说明：**
+
+| 参数名     | 类型 | 是否必填 | 默认值 | 描述                                  |
+| ---------- | ---- | -------- | ------ | ------------------------------------- |
+| `x`        | int  | 是       | -      | X 坐标                                |
+| `y`        | int  | 是       | -      | Y 坐标                                |
+| `duration` | int  | 否       | 20     | 按下持续时间，如果未定义则默认为 20ms |
+
+**返回值：**
+
+| 类型             | 描述                   |
+| ---------------- | ---------------------- |
+| `PointerBuilder` | 返回自身，支持链式调用 |
+
+**功能说明：**
+
+- 自动执行：移动 -> 按下 -> 暂停 -> 抬起的完整点击序列
+
+#### done - 完成指针配置
+
+```python
+def done() -> ActionBuilder
+```
+
+**返回值：**
+
+| 类型            | 描述                               |
+| --------------- | ---------------------------------- |
+| `ActionBuilder` | 返回主构建器，可以继续添加其他指针 |
+
+## 高级使用示例
+
+### 单指滑动
+
+```python
+from kuaijs import action
+
+# 单指从左到右滑动
+builder = action.createBuilder()
+builder \
+  .addPointer(1) \
+  .moveTo(100, 300, 0) \
+  .down() \
+  .moveTo(400, 300, 500) \
+  .up() \
+  .done() \
+  .execute()
+```
+
+### 双指缩放（放大）
+
+```python
+from kuaijs import action
+
+# 双指从中心向外扩展
+builder = action.createBuilder()
+builder \
+  .addPointer(1) \
+  .moveTo(200, 300, 0) \
+  .down() \
+  .moveTo(150, 250, 300) \
+  .up() \
+  .done() \
+  .addPointer(2) \
+  .moveTo(200, 300, 0) \
+  .down() \
+  .moveTo(250, 350, 300) \
+  .up() \
+  .done() \
+  .execute()
+```
+
+### 双指缩放（缩小）
+
+```python
+from kuaijs import action
+
+# 双指从外向中心收缩
+builder = action.createBuilder()
+builder \
+  .addPointer(1) \
+  .moveTo(150, 250, 0) \
+  .down() \
+  .moveTo(200, 300, 300) \
+  .up() \
+  .done() \
+  .addPointer(2) \
+  .moveTo(250, 350, 0) \
+  .down() \
+  .moveTo(200, 300, 300) \
+  .up() \
+  .done() \
+  .execute()
+```
+
+### 双指旋转
+
+```python
+from kuaijs import action
+
+# 双指围绕中心点旋转
+builder = action.createBuilder()
+centerX, centerY = 200, 300
+radius = 50
+
+builder \
+  .addPointer(1) \
+  .moveTo(centerX - radius, centerY, 0) \
+  .down() \
+  .moveTo(centerX, centerY - radius, 200) \
+  .moveTo(centerX + radius, centerY, 200) \
+  .up() \
+  .done() \
+  .addPointer(2) \
+  .moveTo(centerX + radius, centerY, 0) \
+  .down() \
+  .moveTo(centerX, centerY + radius, 200) \
+  .moveTo(centerX - radius, centerY, 200) \
+  .up() \
+  .done() \
+  .execute()
+```
+
+### 长按拖拽
+
+```python
+from kuaijs import action
+
+# 长按后拖拽元素
+builder = action.createBuilder()
+builder \
+  .addPointer(1) \
+  .moveTo(100, 100, 0) \
+  .down() \
+  .stay(800) \
+  .moveTo(300, 400, 1000) \
+  .up() \
+  .done() \
+  .execute()
+```
+
+### 复杂手势组合
+
+```python
+from kuaijs import action
+
+# 先点击，再滑动，最后双击
+builder = action.createBuilder()
+
+# 第一步：单击
+builder.singleTap(100, 100, 50)
+
+# 第二步：滑动
+builder \
+  .addPointer(1) \
+  .moveTo(200, 200, 0) \
+  .down() \
+  .moveTo(400, 200, 600) \
+  .up() \
+  .done()
+
+# 第三步：双击
+builder.multiTap([{ "x": 300, "y": 300 }], 30)
+
+# 执行所有动作
+builder.execute()
+```