@harmonyos-arkts/d2h 0.1.11 → 0.1.12

package/skills/d2h-hypium-forge/references/functional-spec-template.md

@@ -1,140 +1,140 @@
-# 功能规格文档（Functional Spec）— 模板与填写指南
-
-> **用途**：转化完成后的功能验证基准。每份 spec 对应一个业务功能域，由**代码理解阶段**产出，
-> 作为 **d2h-hypium-forge 用例设计**的唯一输入。规格 = 测试预期的唯一来源。
-
----
-
-## 使用流程
-
-```
-安卓源码 → [宿主 agent 代码理解] → functional_spec.md（本文档格式）
-                                    ↓
-                              scenarios.json（场景清单）
-                                    ↓
-                          [d2h-hypium-forge] → testcases/*.py → 执行 → 标定
-```
-
----
-
-## 模板
-
-```markdown
-# 功能规格：<功能域名>
-
-## 元信息
-| 字段 | 值 |
-|---|---|
-| spec_id | FS-<模块>-<序号>（如 FS-goods-001） |
-| 业务域 | <如：商品/交易/账户/消息> |
-| 安卓源模块 | <如 feature/goods> |
-| 鸿蒙源模块 | <如 features/goods> |
-| 置信度 | <已读全/部分/骨架> |
-| 转化状态 | <已转化/部分转化/未转化> |
-| 可测试性级别 | <A/B/C（对照 testability-requirements.md T-10）> |
-
-## 1. 功能概述
-<一段话：用户视角这个功能做什么、核心业务价值、入口路径>
-
-## 2. 业务规则（BR）
-| 规则 ID | 规则描述 | 源码依据（安卓） | 源码依据（鸿蒙） | 测试含义 |
-|---|---|---|---|---|
-| BR-01 | <默认值/联动/互斥/守卫> | file.java:L120 | Index.ets:L45 | <翻译成什么断言> |
-| BR-02 | ... | ... | ... | ... |
-
-## 3. 状态机
-| 当前态 | 事件/动作 | 次态 | 可观察效果（断言锚点） |
-|---|---|---|---|
-| <初始态> | <用户操作> | <目标态> | <UI 变化/数据变更/系统事件> |
-
-## 4. 数据流
-| 输入 | 处理 | 输出 | 断言方式 |
-|---|---|---|---|
-| <用户输入/系统事件> | <业务逻辑> | <UI 变化/持久化/网络请求> | <equals/checked/hilog/absent> |
-
-## 5. 断言锚点清单
-| 锚点 | 类型 | 控件 ID / 文本 / hilog | 断言范式 |
-|---|---|---|---|
-| <如：价格文本> | 文本值 | tc_goods_price | equals |
-| <如：加入购物车按钮> | 控件状态 | btn_add_cart | enabled/disabled |
-| <如：加入成功 Toast> | 瞬态浮层 | hilog tag=GoodsVM | hilog_tail |
-| <如：购物车数量> | 结构计数 | goods_item | find_all count |
-
-## 6. 边界与异常
-| 场景 | 输入条件 | 预期行为 | 断言要点 |
-|---|---|---|---|
-| <如：库存为 0> | stock=0 | 购买按钮禁用 | checked/disabled |
-| <如：网络断开> | 离线 | 显示空态页 | exist(EmptyNetwork) |
-| <如：未登录> | token 过期 | 跳登录页 | 路由断言 |
-
-## 7. 测试场景（直接消费）
-| 场景 ID | 场景描述 | test_intent | 断言范式 | 优先级 |
-|---|---|---|---|---|
-| S-01 | <动宾结构描述> | 功能交互类 | 效果断言 | P0 |
-| S-02 | ... | 配置生效类 | 生效链断言 | P0 |
-| S-03 | ... | 导航流转类 | 终点效果 | P1 |
-
-## 8. 依赖与环境
-| 依赖项 | 状态 | 说明 |
-|---|---|---|
-| 登录 | <不需要/Mock 可测/需真实账号> | ... |
-| 网络 | <不需要/Mock Server/真实 API> | ... |
-| 权限 | <无/相机/位置/...> | ... |
-| mock 通道 | <有/无>（如有，说明激活方式） | ... |
-
-## 9. 可测试性缺口
-| 缺口 ID | 缺 TR 编号 | 描述 | 影响 | 建议修复 |
-|---|---|---|---|---|
-| G-01 | TR-0501 | Base URL 硬编码 | 无法切 Mock Server | 加配置变量 |
-```
-
----
-
-## 填写规则
-
-### BR（业务规则）——从源码推导，不从直觉
-
-| 来源 | ✅ 正确 | ❌ 错误 |
-|---|---|---|
-| 默认值 | `settings.getBoolean('answer', true)` → "默认开启" | "直觉上应该默认关闭" |
-| 联动 | `if (!answer) { allAngles.setEnabled(false) }` → "关闭应答联动禁用任意角度" | "一般这种开关会联动" |
-| 守卫 | `if (stock <= 0) { button.disabled = true }` → "库存≤0 按钮禁用" | "没库存应该不能买" |
-
-> **历史教训**：RTA TC05（守卫条件记错）与 GW 搜索（选中不切主页），两次实证直觉必错。
-
-### test_intent 分类与断言范式选型
-
-| test_intent | 测试目的 | 正确断言范式 | 反例 |
-|---|---|---|---|
-| 资源渲染类 | 图标/文案加载成功 | exist/equals 即目的本身 | — |
-| 功能交互类 | 操作产生业务效果 | 效果断言（值变化/计数增减/checked 翻转） | 仅 exist |
-| 配置生效类 | 设置改变全局行为 | 生效链（改设置→回业务页→断言输出变化） | 仅在设置页断言 |
-| 导航流转类 | 状态迁移到正确目的地 | 终点效果（城市选中→顶栏变新城市名） | 仅"目标页可达" |
-| 状态机类 | 状态转移规律 | 前置态断言→触发→后置态断言（成对） | 只断后置态 |
-| 数据输入类 | 输入被正确处理 | 输入→输出值断言（搜索词→结果计数） | 仅"页面有结果" |
-
-### 优先级
-
-| 级别 | 含义 | 分配原则 |
-|---|---|---|
-| P0 | 核心正向路径 | 每个业务域至少 1 条 |
-| P1 | 重要分支/边界 | 联动/互斥/持久化/异常处理 |
-| P2 | 补充场景 | 边缘功能/极端边界 |
-
----
-
-## 示例：FS-goods-001 规格选择弹窗（CoolMall 节选）
-
-> 完整版见 `ForgeDemos/CoolMall/docs/functional-spec-goods-001.md`
-
-| 规则 ID | 规则描述 | 测试含义 |
-|---|---|---|
-| BR-01 | 初始未选规格，数量默认 1 | 打开弹窗断言"请选择规格"存在 + 数量=1 |
-| BR-02 | 未选规格或库存≤0 → 购买按钮 disabled | `BY.key('btn_buy').enabled(False)` |
-| BR-03 | 价格 fallback：spec.price → goods.price | 选规格后 equals 新价 |
-
-| 场景 ID | 场景 | test_intent | 断言 | 优先级 |
-|---|---|---|---|---|
-| S-01 | 选中规格后价格/库存/按钮联动 | 功能交互类 | 值变化 + enabled 翻转 | P0 |
-| S-02 | 立即购买跨页一致性 | 配置生效类 | 订单确认页 equals 规格/单价/数量 | P0 |
-| S-03 | stock=0 时购买拦截 | 功能交互类 | disabled + 点击无跳转 | P1 |
+# 功能规格文档（Functional Spec）— 模板与填写指南
+
+> **用途**：转化完成后的功能验证基准。每份 spec 对应一个业务功能域，由**代码理解阶段**产出，
+> 作为 **d2h-hypium-forge 用例设计**的唯一输入。规格 = 测试预期的唯一来源。
+
+---
+
+## 使用流程
+
+```
+安卓源码 → [宿主 agent 代码理解] → functional_spec.md（本文档格式）
+                                    ↓
+                              scenarios.json（场景清单）
+                                    ↓
+                          [d2h-hypium-forge] → testcases/*.py → 执行 → 标定
+```
+
+---
+
+## 模板
+
+```markdown
+# 功能规格：<功能域名>
+
+## 元信息
+| 字段 | 值 |
+|---|---|
+| spec_id | FS-<模块>-<序号>（如 FS-goods-001） |
+| 业务域 | <如：商品/交易/账户/消息> |
+| 安卓源模块 | <如 feature/goods> |
+| 鸿蒙源模块 | <如 features/goods> |
+| 置信度 | <已读全/部分/骨架> |
+| 转化状态 | <已转化/部分转化/未转化> |
+| 可测试性级别 | <A/B/C（对照 testability-requirements.md T-10）> |
+
+## 1. 功能概述
+<一段话：用户视角这个功能做什么、核心业务价值、入口路径>
+
+## 2. 业务规则（BR）
+| 规则 ID | 规则描述 | 源码依据（安卓） | 源码依据（鸿蒙） | 测试含义 |
+|---|---|---|---|---|
+| BR-01 | <默认值/联动/互斥/守卫> | file.java:L120 | Index.ets:L45 | <翻译成什么断言> |
+| BR-02 | ... | ... | ... | ... |
+
+## 3. 状态机
+| 当前态 | 事件/动作 | 次态 | 可观察效果（断言锚点） |
+|---|---|---|---|
+| <初始态> | <用户操作> | <目标态> | <UI 变化/数据变更/系统事件> |
+
+## 4. 数据流
+| 输入 | 处理 | 输出 | 断言方式 |
+|---|---|---|---|
+| <用户输入/系统事件> | <业务逻辑> | <UI 变化/持久化/网络请求> | <equals/checked/hilog/absent> |
+
+## 5. 断言锚点清单
+| 锚点 | 类型 | 控件 ID / 文本 / hilog | 断言范式 |
+|---|---|---|---|
+| <如：价格文本> | 文本值 | tc_goods_price | equals |
+| <如：加入购物车按钮> | 控件状态 | btn_add_cart | enabled/disabled |
+| <如：加入成功 Toast> | 瞬态浮层 | hilog tag=GoodsVM | hilog_tail |
+| <如：购物车数量> | 结构计数 | goods_item | find_all count |
+
+## 6. 边界与异常
+| 场景 | 输入条件 | 预期行为 | 断言要点 |
+|---|---|---|---|
+| <如：库存为 0> | stock=0 | 购买按钮禁用 | checked/disabled |
+| <如：网络断开> | 离线 | 显示空态页 | exist(EmptyNetwork) |
+| <如：未登录> | token 过期 | 跳登录页 | 路由断言 |
+
+## 7. 测试场景（直接消费）
+| 场景 ID | 场景描述 | test_intent | 断言范式 | 优先级 |
+|---|---|---|---|---|
+| S-01 | <动宾结构描述> | 功能交互类 | 效果断言 | P0 |
+| S-02 | ... | 配置生效类 | 生效链断言 | P0 |
+| S-03 | ... | 导航流转类 | 终点效果 | P1 |
+
+## 8. 依赖与环境
+| 依赖项 | 状态 | 说明 |
+|---|---|---|
+| 登录 | <不需要/Mock 可测/需真实账号> | ... |
+| 网络 | <不需要/Mock Server/真实 API> | ... |
+| 权限 | <无/相机/位置/...> | ... |
+| mock 通道 | <有/无>（如有，说明激活方式） | ... |
+
+## 9. 可测试性缺口
+| 缺口 ID | 缺 TR 编号 | 描述 | 影响 | 建议修复 |
+|---|---|---|---|---|
+| G-01 | TR-0501 | Base URL 硬编码 | 无法切 Mock Server | 加配置变量 |
+```
+
+---
+
+## 填写规则
+
+### BR（业务规则）——从源码推导，不从直觉
+
+| 来源 | ✅ 正确 | ❌ 错误 |
+|---|---|---|
+| 默认值 | `settings.getBoolean('answer', true)` → "默认开启" | "直觉上应该默认关闭" |
+| 联动 | `if (!answer) { allAngles.setEnabled(false) }` → "关闭应答联动禁用任意角度" | "一般这种开关会联动" |
+| 守卫 | `if (stock <= 0) { button.disabled = true }` → "库存≤0 按钮禁用" | "没库存应该不能买" |
+
+> **历史教训**：RTA TC05（守卫条件记错）与 GW 搜索（选中不切主页），两次实证直觉必错。
+
+### test_intent 分类与断言范式选型
+
+| test_intent | 测试目的 | 正确断言范式 | 反例 |
+|---|---|---|---|
+| 资源渲染类 | 图标/文案加载成功 | exist/equals 即目的本身 | — |
+| 功能交互类 | 操作产生业务效果 | 效果断言（值变化/计数增减/checked 翻转） | 仅 exist |
+| 配置生效类 | 设置改变全局行为 | 生效链（改设置→回业务页→断言输出变化） | 仅在设置页断言 |
+| 导航流转类 | 状态迁移到正确目的地 | 终点效果（城市选中→顶栏变新城市名） | 仅"目标页可达" |
+| 状态机类 | 状态转移规律 | 前置态断言→触发→后置态断言（成对） | 只断后置态 |
+| 数据输入类 | 输入被正确处理 | 输入→输出值断言（搜索词→结果计数） | 仅"页面有结果" |
+
+### 优先级
+
+| 级别 | 含义 | 分配原则 |
+|---|---|---|
+| P0 | 核心正向路径 | 每个业务域至少 1 条 |
+| P1 | 重要分支/边界 | 联动/互斥/持久化/异常处理 |
+| P2 | 补充场景 | 边缘功能/极端边界 |
+
+---
+
+## 示例：FS-goods-001 规格选择弹窗（CoolMall 节选）
+
+> 完整版见 `ForgeDemos/CoolMall/docs/functional-spec-goods-001.md`
+
+| 规则 ID | 规则描述 | 测试含义 |
+|---|---|---|
+| BR-01 | 初始未选规格，数量默认 1 | 打开弹窗断言"请选择规格"存在 + 数量=1 |
+| BR-02 | 未选规格或库存≤0 → 购买按钮 disabled | `BY.key('btn_buy').enabled(False)` |
+| BR-03 | 价格 fallback：spec.price → goods.price | 选规格后 equals 新价 |
+
+| 场景 ID | 场景 | test_intent | 断言 | 优先级 |
+|---|---|---|---|---|
+| S-01 | 选中规格后价格/库存/按钮联动 | 功能交互类 | 值变化 + enabled 翻转 | P0 |
+| S-02 | 立即购买跨页一致性 | 配置生效类 | 订单确认页 equals 规格/单价/数量 | P0 |
+| S-03 | stock=0 时购买拦截 | 功能交互类 | disabled + 点击无跳转 | P1 |

package/skills/d2h-hypium-forge/references/official-api.md

@@ -1,135 +1,135 @@
-# Hypium 官方 API 速查（提炼自 developer.huawei.com 应用UI测试（基于Python）文档）
-
-> 源文档：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hypium-python-guidelines（2026-06-05 版）
-> 本文只保留生成脚本高频用到的部分；完整语义以官方文档为准。
-
-## 工程结构
-
-```
-project/
-├── testcases/          # 用例 XXX.py + 同名 XXX.json
-├── resource/           # 模板图片等资源（get_resource_path 优先搜此）
-├── config/user_config.xml
-└── main.py             # 入口
-```
-
-用例生命周期：`setup`（前置）/ `process`（步骤）/ `teardown`（清理）。Step/CheckPoint/MESSAGE 会进报告。测试套模式：TestSuite 类 + TC_ 前缀自动扫描用例。
-
-## 控件定位（BY）
-
-**优先级：属性 > 图片 > 比例坐标**（坐标点击前后各做一次属性断言）。
-
-```python
-from hypium import BY, UiDriver
-from hypium.model import MatchPattern, UiParam, KeyCode
-
-driver.find_component(BY.text("蓝牙"))                    # 第一个匹配
-driver.find_all_components(BY.type("Button"))             # 全部匹配，取 [n]
-driver.touch(BY.text("蓝牙"))                             # 查找并点击
-
-# 模糊匹配（第二个参数）
-BY.text("看过", MatchPattern.CONTAINS)      # 模板文案/长标题必用
-BY.text("今天星期", MatchPattern.STARTS_WITH)
-BY.text(".+", MatchPattern.REGEXP)
-
-# 组合
-BY.text("蓝牙").type("Button").key("bluetooth_switch")
-
-# 相对位置（锚点不可再用相对定位）
-BY.type("Button").isAfter(BY.text("显示通知图标"))   # 控件树前序遍历顺序
-BY.type("Image").isBefore(BY.text("账号"))
-BY.type("Image").within(BY.key("nav_container"))
-BY.text("蓝牙").inWindow("com.huawei.hmos.settings")  # 限定窗口
-
-# XPath（不能与其他属性混用，较慢，兜底用）
-BY.xpath("//*[@text='可用 WLAN']/ancestor::List/ListItemGroup/ListItem[1]//Text/following::Image")
-```
-
-支持属性：text/key/type/hint（支持模糊）；checkable/longClickable/clickable/scrollable/enabled/focused/selected/checked（bool）。
-
-## 图片与坐标
-
-```python
-driver.touch_image("/path/template.jpeg")   # 需 opencv-python；只匹配最佳一处
-b = driver.find_image("template.jpeg")      # 返回 Rect
-driver.touch((0.52, 0.98))                  # 比例坐标
-```
-
-## 窗口
-
-```python
-from hypium.model import WindowFilter
-w = driver.find_window(WindowFilter().bundle_name("com.x").actived(True))
-driver.check_window(WindowFilter().focused(True), bundle_name="com.x")
-```
-
-## 触控
-
-```python
-driver.touch(target, mode=UiParam.NORMAL|LONG|DOUBLE, scroll_target=BY.type("Scroll"), wait_time=0.1)
-# scroll_target：在滚动容器内查找并点击——视口外控件首选，勿手工预滑动
-driver.long_click(target, press_time=2, offset=(0.1, 0.1))   # offset 为控件内比例
-driver.swipe(UiParam.UP, distance=40, area=BY.type("Scroll"), side=UiParam.RIGHT, start_point=(0.8,0.8), swipe_time=0.3)
-# ⚠ distance=滑动区域总长百分比(1-100)，非像素
-driver.slide((100,200), (300,400), slide_time=0.3)           # 精确滑动，起止可为 BY/控件/坐标
-driver.drag(start, end, area=BY.type("Slider"), press_time=1, drag_time=1)
-driver.pinch_in/out(BY.type("Image"), direction="horizontal")
-driver.multi_finger_touch([(0.1,0.2),(0.3,0.4)])
-# 自定义手势
-from hypium.uidriver import Gesture
-g = Gesture().start(pos, 2).move_to(p2).pause(1)
-driver.inject_gesture(g)                  # 多指：inject_multi_finger_gesture([g1,g2])
-```
-
-## 输入与按键
-
-```python
-from hypium.model import InputTextMode
-driver.input_text(BY.type("TextInput"), "hello")   # 默认先清空；中文剪贴板粘贴
-driver.input_text(c, "x", mode=InputTextMode().paste(True).addition(True))
-driver.clear_text(BY.type("TextInput"))
-driver.press_key(KeyCode.POWER, mode=UiParam.LONG)
-driver.press_combination_key(KeyCode.CTRL_LEFT, KeyCode.SHIFT_LEFT, KeyCode.F)
-```
-
-## 应用/设备管理
-
-```python
-driver.start_app(bundle, ability, wait_time=1)
-driver.stop_app(bundle)
-driver.install_app(path, "-r")
-driver.uninstall_app(bundle)
-driver.clear_app_data(bundle)          # 清应用数据（重置持久化状态首选）
-driver.hdc("list targets")
-driver.shell("ls -l")                  # 设备侧
-host.shell("dir")                      # PC 侧
-driver.push_file(local, device_path); driver.pull_file(device, local); driver.has_file(p)
-```
-
-## 断言
-
-```python
-host.check_equal(a, b, "a != b"); host.check_greater(a, b)
-
-driver.check_component_exist(BY.type("Button"), expect_exist=True, wait_time=5,
-                             scroll_target=BY.type("Scroll"))   # 负断言 expect_exist=False
-driver.check_component(BY.key("xxx"), checked=True)             # 属性断言 kwargs: id/text/key/type/
-                                                                 # enabled/focused/clickable/scrollable/checked/checkable
-driver.check_image_exist("t.jpeg", similarity=0.95, timeout=3, mode="template"|"sift")
-```
-
-## 等与轮询
-
-```python
-comp = driver.wait_for_component(BY.text("xx"), 5)   # 秒；找不到返回 None
-```
-
-## 执行与报告
-
-```bash
-python -m hypium          # 交互控制台；run/list/help
-# 常用：run -l Case1;Case2 -sn SN1 -rp report路径 -ta screenshot:true
-# harmonyrun 执行器等价：cd 项目目录 && harmonyrun hypium run . -d SN --case XXX_001
-```
-
-报告：`reports/<时间戳>/`（details/ 步骤截图、result/*.xml、log/、summary_report.html、summary.ini、task_info.record）。xdevice 执行器下为 report_data.json（含逐条耗时）。
+# Hypium 官方 API 速查（提炼自 developer.huawei.com 应用UI测试（基于Python）文档）
+
+> 源文档：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hypium-python-guidelines（2026-06-05 版）
+> 本文只保留生成脚本高频用到的部分；完整语义以官方文档为准。
+
+## 工程结构
+
+```
+project/
+├── testcases/          # 用例 XXX.py + 同名 XXX.json
+├── resource/           # 模板图片等资源（get_resource_path 优先搜此）
+├── config/user_config.xml
+└── main.py             # 入口
+```
+
+用例生命周期：`setup`（前置）/ `process`（步骤）/ `teardown`（清理）。Step/CheckPoint/MESSAGE 会进报告。测试套模式：TestSuite 类 + TC_ 前缀自动扫描用例。
+
+## 控件定位（BY）
+
+**优先级：属性 > 图片 > 比例坐标**（坐标点击前后各做一次属性断言）。
+
+```python
+from hypium import BY, UiDriver
+from hypium.model import MatchPattern, UiParam, KeyCode
+
+driver.find_component(BY.text("蓝牙"))                    # 第一个匹配
+driver.find_all_components(BY.type("Button"))             # 全部匹配，取 [n]
+driver.touch(BY.text("蓝牙"))                             # 查找并点击
+
+# 模糊匹配（第二个参数）
+BY.text("看过", MatchPattern.CONTAINS)      # 模板文案/长标题必用
+BY.text("今天星期", MatchPattern.STARTS_WITH)
+BY.text(".+", MatchPattern.REGEXP)
+
+# 组合
+BY.text("蓝牙").type("Button").key("bluetooth_switch")
+
+# 相对位置（锚点不可再用相对定位）
+BY.type("Button").isAfter(BY.text("显示通知图标"))   # 控件树前序遍历顺序
+BY.type("Image").isBefore(BY.text("账号"))
+BY.type("Image").within(BY.key("nav_container"))
+BY.text("蓝牙").inWindow("com.huawei.hmos.settings")  # 限定窗口
+
+# XPath（不能与其他属性混用，较慢，兜底用）
+BY.xpath("//*[@text='可用 WLAN']/ancestor::List/ListItemGroup/ListItem[1]//Text/following::Image")
+```
+
+支持属性：text/key/type/hint（支持模糊）；checkable/longClickable/clickable/scrollable/enabled/focused/selected/checked（bool）。
+
+## 图片与坐标
+
+```python
+driver.touch_image("/path/template.jpeg")   # 需 opencv-python；只匹配最佳一处
+b = driver.find_image("template.jpeg")      # 返回 Rect
+driver.touch((0.52, 0.98))                  # 比例坐标
+```
+
+## 窗口
+
+```python
+from hypium.model import WindowFilter
+w = driver.find_window(WindowFilter().bundle_name("com.x").actived(True))
+driver.check_window(WindowFilter().focused(True), bundle_name="com.x")
+```
+
+## 触控
+
+```python
+driver.touch(target, mode=UiParam.NORMAL|LONG|DOUBLE, scroll_target=BY.type("Scroll"), wait_time=0.1)
+# scroll_target：在滚动容器内查找并点击——视口外控件首选，勿手工预滑动
+driver.long_click(target, press_time=2, offset=(0.1, 0.1))   # offset 为控件内比例
+driver.swipe(UiParam.UP, distance=40, area=BY.type("Scroll"), side=UiParam.RIGHT, start_point=(0.8,0.8), swipe_time=0.3)
+# ⚠ distance=滑动区域总长百分比(1-100)，非像素
+driver.slide((100,200), (300,400), slide_time=0.3)           # 精确滑动，起止可为 BY/控件/坐标
+driver.drag(start, end, area=BY.type("Slider"), press_time=1, drag_time=1)
+driver.pinch_in/out(BY.type("Image"), direction="horizontal")
+driver.multi_finger_touch([(0.1,0.2),(0.3,0.4)])
+# 自定义手势
+from hypium.uidriver import Gesture
+g = Gesture().start(pos, 2).move_to(p2).pause(1)
+driver.inject_gesture(g)                  # 多指：inject_multi_finger_gesture([g1,g2])
+```
+
+## 输入与按键
+
+```python
+from hypium.model import InputTextMode
+driver.input_text(BY.type("TextInput"), "hello")   # 默认先清空；中文剪贴板粘贴
+driver.input_text(c, "x", mode=InputTextMode().paste(True).addition(True))
+driver.clear_text(BY.type("TextInput"))
+driver.press_key(KeyCode.POWER, mode=UiParam.LONG)
+driver.press_combination_key(KeyCode.CTRL_LEFT, KeyCode.SHIFT_LEFT, KeyCode.F)
+```
+
+## 应用/设备管理
+
+```python
+driver.start_app(bundle, ability, wait_time=1)
+driver.stop_app(bundle)
+driver.install_app(path, "-r")
+driver.uninstall_app(bundle)
+driver.clear_app_data(bundle)          # 清应用数据（重置持久化状态首选）
+driver.hdc("list targets")
+driver.shell("ls -l")                  # 设备侧
+host.shell("dir")                      # PC 侧
+driver.push_file(local, device_path); driver.pull_file(device, local); driver.has_file(p)
+```
+
+## 断言
+
+```python
+host.check_equal(a, b, "a != b"); host.check_greater(a, b)
+
+driver.check_component_exist(BY.type("Button"), expect_exist=True, wait_time=5,
+                             scroll_target=BY.type("Scroll"))   # 负断言 expect_exist=False
+driver.check_component(BY.key("xxx"), checked=True)             # 属性断言 kwargs: id/text/key/type/
+                                                                 # enabled/focused/clickable/scrollable/checked/checkable
+driver.check_image_exist("t.jpeg", similarity=0.95, timeout=3, mode="template"|"sift")
+```
+
+## 等与轮询
+
+```python
+comp = driver.wait_for_component(BY.text("xx"), 5)   # 秒；找不到返回 None
+```
+
+## 执行与报告
+
+```bash
+python -m hypium          # 交互控制台；run/list/help
+# 常用：run -l Case1;Case2 -sn SN1 -rp report路径 -ta screenshot:true
+# harmonyrun 执行器等价：cd 项目目录 && harmonyrun hypium run . -d SN --case XXX_001
+```
+
+报告：`reports/<时间戳>/`（details/ 步骤截图、result/*.xml、log/、summary_report.html、summary.ini、task_info.record）。xdevice 执行器下为 report_data.json（含逐条耗时）。