Skip to content

Commit a412e31

Browse files
wangczclaude
wangcz
and
claude
committed
feat: add HarmonyOS platform support (v2)
Re-implement HarmonyOS platform support on the new architecture after main branch refactoring. Platform implementation (src/platforms/harmonyos/): - Device discovery and management via HDC - App lifecycle (open, close, app state) with launchAbility resolution - UI snapshot with interactive-only filtering for ArkUI - Screenshot capture - Input actions: scroll, rotate, keyboard, double-tap, long-press - System dialog handling - Clipboard, logcat, perf, and recording support Core changes: - Add 'harmonyos' to Platform type and device resolution - Add 'harmonyos.hdc' to backend capabilities - Add harmonyos interactor with gesture stubs - Add harmonyos to command capability matrix - Add cognition command for UI structure analysis Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
1 parent 491ad7e commit a412e31

770 files changed

Lines changed: 310599 additions & 10 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎harmonyos-lab/docs/smart-traverse-workflow.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# HarmonyOS 应用智能遍历方案
2+
3+
## 目标
4+
为大模型提供应用的"认知地图"，避免盲目点击测试
5+
6+
## 工作流程
7+
8+
### 第一步：静态分析生成认知地图
9+
```bash
10+
# 1. 导出UI布局
11+
hdc shell "uitest dumpLayout -p /data/local/tmp/layout.json"
12+
hdc file recv /data/local/tmp/layout.json ./layout.json
13+
14+
# 2. 生成认知地图
15+
node scripts/build-cognition-map.js ./layout.json ./output
16+
```
17+
18+
### 第二步：认知地图示例输出
19+
```
20+
# 应用UI认知地图
21+
22+
## 概览
23+
- 屏幕分辨率: 1260x2720
24+
- UI节点总数: 109
25+
- 树深度: 15层
26+
- 界面复杂度: simple
27+
28+
## UI结构
29+
- 布局模式: navigation-based, horizontal-layout
30+
- 主容器数量: 4
31+
32+
## 交互元素
33+
- 可点击元素: 9个
34+
- 输入框: 0个
35+
- 按钮: 2个
36+
- Tab导航: 0个
37+
38+
## 界面特征
39+
- 可滚动: 是
40+
- 有Tab导航: 是
41+
- 有弹窗: 否
42+
- 有列表: 是
43+
- 有表单: 否
44+
45+
## 测试建议
46+
- 存在导航结构，建议按导航层级遍历
47+
```
48+
49+
### 第三步：大模型基于认知地图制定测试计划
50+
51+
大模型会收到认知地图，然后生成测试计划：
52+
53+
**示例计划（JSON格式）**：
54+
```json
55+
{
56+
"testPlan": {
57+
"priority": "high",
58+
"strategy": "navigation-first",
59+
"steps": [
60+
{
61+
"step": 1,
62+
"action": "check_initial_state",
63+
"target": "root",
64+
"reason": "认知地图显示存在导航结构，先确认初始界面"
65+
},
66+
{
67+
"step": 2,
68+
"action": "identify_navigation",
69+
"target": "tabs_and_buttons",
70+
"reason": "发现9个可点击元素，2个按钮，先识别导航入口"
71+
},
72+
{
73+
"step": 3,
74+
"action": "click_primary_button",
75+
"target": "Button[type=primary]",
76+
"reason": "界面复杂度simple，优先测试主要功能按钮"
77+
},
78+
{
79+
"step": 4,
80+
"action": "verify_navigation",
81+
"target": "new_screen",
82+
"reason": "验证导航跳转是否成功"
83+
},
84+
{
85+
"step": 5,
86+
"action": "scroll_test",
87+
"target": "scrollable_area",
88+
"reason": "认知地图显示可滚动区域，测试滚动功能"
89+
}
90+
]
91+
}
92+
}
93+
```
94+
95+
### 第四步：执行智能遍历
96+
97+
基于大模型的测试计划，执行实际测试：
98+
99+
```bash
100+
# 执行第1步：确认初始界面
101+
node dist/src/cli.js snapshot --session xxx --json
102+
103+
# 执行第2步：识别导航
104+
node dist/src/cli.js snapshot -i --session xxx
105+
106+
# 执行第3步：点击主要按钮
107+
node dist/src/cli.js press @e20 --session xxx
108+
109+
# 执行第4步：验证跳转
110+
node dist/src/cli.js snapshot --session xxx --json
111+
112+
# 执行第5步：测试滚动
113+
node dist/src/cli.js scroll down 0.5 --session xxx
114+
```
115+
116+
## 优势对比
117+
118+
### 传统盲目测试 vs 认知地图引导测试
119+
120+
| 特性 | 盲目测试 | 认知地图引导 |
121+
|-----|---------|------------|
122+
| **效率** | 低（随机点击） | 高（有目标） |
123+
| **覆盖率** | 难保证 | 可规划 |
124+
| **测试深度** | 表层 | 可深入关键路径 |
125+
| **大模型负担** | 重（需要实时分析） | 轻（已有认知基础） |
126+
| **可复用性** | 低 | 高（认知地图可复用） |
127+
128+
## 实际收益
129+
130+
### 认知地图提供的信息
131+
1. **UI结构**：节点数、深度、布局模式
132+
2. **交互元素**：按钮、输入框、Tab等数量和位置
133+
3. **界面特征**：是否可滚动、有弹窗、有列表等
134+
4. **测试建议**：基于复杂度的智能建议
135+
136+
### 大模型使用方式
137+
大模型收到认知地图后：
138+
1. 不需要每次都分析完整UI树
139+
2. 可以制定有策略的测试计划
140+
3. 可以优先测试关键功能
141+
4. 可以避免无效的点击操作
142+
5. 可以更准确地预测测试结果
143+
144+
## 扩展应用
145+
146+
### 多界面认知地图
147+
可以导出多个界面的布局，生成完整的应用地图：
148+
149+
```bash
150+
# 主界面
151+
hdc shell "uitest dumpLayout -p /data/local/tmp/home.json"
152+
153+
# 详情界面（需要先导航进入）
154+
hdc shell "uitest dumpLayout -p /data/local/tmp/detail.json"
155+
156+
# 设置界面
157+
hdc shell "uitest dumpLayout -p /data/local/tmp/settings.json"
158+
159+
# 生成完整应用地图
160+
node scripts/merge-cognition-maps.js ./maps/*.json ./app-map.json
161+
```
162+
163+
### 认知地图应用场景
164+
1. **自动化测试规划**：大模型基于地图制定测试策略
165+
2. **回归测试**：对比新旧版本的认知地图变化
166+
3. **UI一致性检查**：检查UI是否符合设计规范
167+
4. **性能优化**：识别复杂UI结构，优化渲染性能
168+
5. **无障碍测试**：识别缺少标签的交互元素

‎harmonyos-lab/docs/snapshot -i --platform harmonyos.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# 文档已迁移
2+
3+
本文件内容已整理至：
4+
5+
**[wangcz_文档记录/](./wangcz_文档记录/)**
6+
7+
- 索引：[README.md](./wangcz_文档记录/README.md)
8+
- 终端实录：[附录-终端实录-snapshot-i弹窗场景.md](./wangcz_文档记录/附录-终端实录-snapshot-i弹窗场景.md)
9+
- 快照说明：[02-snapshot-i与鸿蒙快照.md](./wangcz_文档记录/02-snapshot-i与鸿蒙快照.md)
10+
11+
请以后在 `wangcz_文档记录/` 目录维护问答与修改记录。

‎harmonyos-lab/docs/wangcz_文档记录/01-CLI与仓库用法.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# CLI 与仓库用法
2+
3+
## 1. 前置条件
4+
5+
```bash
6+
cd <agent-device-src>
7+
pnpm install
8+
pnpm build # 生成 dist/，本地 mjs 才能用
9+
```
10+
11+
- Node >= 22
12+
- HarmonyOS：`hdc` 可用，设备已连接（`hdc list targets`）
13+
- 首次操作建议：`node bin/agent-device.mjs help workflow`
14+
15+
---
16+
17+
## 2. 命令入口
18+
19+
| 方式 | 命令 | 说明 |
20+
|------|------|------|
21+
| 全局安装 | `agent-device …` | `npm install -g agent-device` 后 |
22+
| **本仓库（推荐）** | `node bin/agent-device.mjs …` | 与当前分支代码一致 |
23+
| 快捷 | `pnpm ad …` | 等同上一行 |
24+
25+
未 build 时会报错：`Missing dist build. Run pnpm build`。
26+
27+
---
28+
29+
## 3. 标准会话闭环
30+
31+
```bash
32+
# 可选：确认设备与应用
33+
node bin/agent-device.mjs devices --platform harmonyos
34+
node bin/agent-device.mjs apps --platform harmonyos
35+
36+
# 1. 打开应用（必须先 open，才有 session）
37+
node bin/agent-device.mjs open <包名> --platform harmonyos --session hs1
38+
39+
# 2. 看当前可交互元素
40+
node bin/agent-device.mjs snapshot -i --platform harmonyos --session hs1
41+
42+
# 3. 操作（二选一或组合）
43+
node bin/agent-device.mjs press 'label="微信登录"' --platform harmonyos --session hs1
44+
node bin/agent-device.mjs press @e10 --platform harmonyos --session hs1
45+
46+
# 4. 结束（必须 close，释放 session）
47+
node bin/agent-device.mjs close --platform harmonyos --session hs1
48+
```
49+
50+
**习惯用法**：探索用 `@eN`（来自上一步 `-i`）；稳定脚本用 `'label="…"'` / `'id="…"'`。
51+
52+
---
53+
54+
## 4. 子命令速查
55+
56+
| 类别 | 命令 | 用途 |
57+
|------|------|------|
58+
| 会话 | `open` / `close` / `appstate` | 拉起应用、结束会话、看前台包名 |
59+
| 观测 | `snapshot`、`-i`、`--json`、`--raw`、`-s @eN` | 读 UI；详见 [02](./02-snapshot-i与鸿蒙快照.md) |
60+
| 交互 | `press` / `click` / `fill` / `scroll` / `back` | 点按、输入、滚动、返回 |
61+
| 断言 | `is` / `get` / `find` / `wait` | 验证文案、状态、等待 |
62+
| 规划 | `cognition --json` | 单屏 UI 结构概览（给模型做计划） |
63+
64+
---
65+
66+
## 5. 两条技术路线（勿混用）
67+
68+
```text
69+
路线 A — 会话内手动/Agent 操作
70+
agent-device open → snapshot -i → press @eN 或 label=… → close
71+
72+
路线 B — 批量智能遍历（写 traverse-output 报告）
73+
run-smart-traverse-app.sh → hdc dumpLayout 全量 JSON → 坐标 press → 报告
74+
```
75+
76+
| 对比项 | 路线 A | 路线 B |
77+
|--------|--------|--------|
78+
| UI 数据 | daemon `snapshot` | `uitest dumpLayout` 完整 JSON |
79+
| 典型点击 | ref / selector | `press cx cy` |
80+
| 产物 | 终端输出 | `smart-traverse-report.md` 等 |
81+
82+
路线 B 见 [06-traverse-output报告生成全流程.md](./06-traverse-output报告生成全流程.md)。

‎harmonyos-lab/docs/wangcz_文档记录/02-snapshot-i与鸿蒙快照.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# snapshot -i 与鸿蒙快照
2+
3+
## 1. 这条命令在做什么
4+
5+
```bash
6+
node bin/agent-device.mjs snapshot -i --platform harmonyos --session hs1
7+
```
8+
9+
| 片段 | 含义 |
10+
|------|------|
11+
| `snapshot` | 抓取当前界面的 UI 树（鸿蒙侧：`hdc uitest dumpLayout` → 解析） |
12+
| `-i` | **interactiveOnly**：只保留与「下一步操作」相关的节点 |
13+
| `--platform harmonyos` | 走 ArkUI 后端 |
14+
| `--session hs1` | 绑定已 `open` 的会话（设备、前台应用） |
15+
16+
输出不是截图，而是**带 `@eN` 引用的文本列表**，供 `press @eN` 或人工阅读。
17+
18+
---
19+
20+
## 2. 一行输出怎么读
21+
22+
```text
23+
@e11 [text] "微信登录"
24+
@e10 [button] "5388"
25+
@e8 [scroll] "5379" [scrollable]
26+
@e1 [navdestination] "9322" [focused]
27+
```
28+
29+
| 部分 | 说明 |
30+
|------|------|
31+
| `@e11` | 本快照内临时编号；界面变化后需重新 `snapshot -i` |
32+
| `[text]` / `[button]` | ArkUI 组件类型 |
33+
| `"微信登录"` | 显示名：优先 text/description；无文案则为内部 id |
34+
| `[focused]` | 焦点在该节点或其层 |
35+
| `[scrollable]` | 可滚动容器 |
36+
37+
**点击建议**：有 `[button]` 时优先点 button 或 `press 'label="微信登录"'`；单独 `[text]` 可能只是标签，不一定接收点击。
38+
39+
---
40+
41+
## 3. 引号里是数字（如 9329、5388）时
42+
43+
表示该节点**没有可读文案**，退化为 `id` / `key` / `accessibilityId`。
44+
45+
- `@e3 [stack] "9329"` → 布局壳，一般**不要**当业务按钮
46+
- `@e10 [button] "5388"` + `@e11 [text] "微信登录"` → 业务上点「微信登录」或 `@e10`
47+
48+
---
49+
50+
## 4. `-i` 不是完整树
51+
52+
完整数据在设备上的 **嵌套 JSON**（`attributes` + `children[]`），字段含 `type`、`text`、`clickable`、`bounds`、`focused`、`visible` 等。
53+
54+
**需要更多细节时的升级路径**：
55+
56+
| 命令 | 何时用 |
57+
|------|--------|
58+
| `snapshot -i` | 日常点按、省 token |
59+
| `snapshot -i --json` | 看 `hittable`、`rect`、`identifier` |
60+
| `snapshot -s @e10` | 展开某个 ref 子树 |
61+
| `snapshot -c` / 无 `-i` | 更多可见结构 |
62+
| `snapshot --raw` | 接近全量节点 |
63+
| `hdc … dumpLayout` | 与智能遍历脚本相同的完整树 |
64+
65+
**结论**：过滤只影响默认打印内容，不删除设备上的完整树。Agent 可按需升级视图，见 [03-agent-device封装思路.md](./03-agent-device封装思路.md)。
66+
67+
---
68+
69+
## 5. 与 Android 的 `-i` 差异
70+
71+
| 维度 | Android | HarmonyOS（改前） | HarmonyOS（改后，2026-05-27） |
72+
|------|---------|-------------------|-------------------------------|
73+
| 过滤思路 | 祖先/后代可交互 + 结构类型 | 有 text/id 就保留 → **偏松** | 仅交互上下文 + focused 弹窗 scope |
74+
| 终端观感 | 较像「关键可点列表」 | 节点多、易含背景 | 节点少；弹窗场景以当前层为主 |
75+
| 实现文件 | `ui-hierarchy.ts` | `arkui-hierarchy.ts` | 同左 |
76+
77+
---
78+
79+
## 6. 过滤效果（实测量级）
80+
81+
| 场景 | 大约 nodes | 说明 |
82+
|------|------------|------|
83+
| 登录页，改前 | ~88 | 大量布局 + 文案噪音 |
84+
| 登录页，改后 | ~23–36 | 收敛到交互相关 |
85+
| 隐私弹窗 + **未** build 新代码 | ~49 | 仍含背景「微信登录」等（旧 dist） |
86+
| 隐私弹窗 + **已** build + scope | ~13 | mainly `navdestination [focused]` 子树 |
87+
88+
弹窗场景终端对比见 [附录-终端实录-snapshot-i弹窗场景.md](./附录-终端实录-snapshot-i弹窗场景.md)。
89+
90+
代码说明见 [04-鸿蒙代码修改记录.md](./04-鸿蒙代码修改记录.md)。

0 commit comments

Comments
 (0)