feat: add HarmonyOS platform support (v2)

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

@@ -0,0 +1,168 @@
+# HarmonyOS 应用智能遍历方案
+
+## 目标
+为大模型提供应用的"认知地图"，避免盲目点击测试
+
+## 工作流程
+
+### 第一步：静态分析生成认知地图
+```bash
+# 1. 导出UI布局
+hdc shell "uitest dumpLayout -p /data/local/tmp/layout.json"
+hdc file recv /data/local/tmp/layout.json ./layout.json
+
+# 2. 生成认知地图
+node scripts/build-cognition-map.js ./layout.json ./output
+```
+
+### 第二步：认知地图示例输出
+```
+# 应用UI认知地图
+
+## 概览
+- 屏幕分辨率: 1260x2720
+- UI节点总数: 109
+- 树深度: 15层
+- 界面复杂度: simple
+
+## UI结构
+- 布局模式: navigation-based, horizontal-layout
+- 主容器数量: 4
+
+## 交互元素
+- 可点击元素: 9个
+- 输入框: 0个
+- 按钮: 2个
+- Tab导航: 0个
+
+## 界面特征
+- 可滚动: 是
+- 有Tab导航: 是
+- 有弹窗: 否
+- 有列表: 是
+- 有表单: 否
+
+## 测试建议
+- 存在导航结构，建议按导航层级遍历
+```
+
+### 第三步：大模型基于认知地图制定测试计划
+
+大模型会收到认知地图，然后生成测试计划：
+
+**示例计划（JSON格式）**：
+```json
+{
+  "testPlan": {
+    "priority": "high",
+    "strategy": "navigation-first",
+    "steps": [
+      {
+        "step": 1,
+        "action": "check_initial_state",
+        "target": "root",
+        "reason": "认知地图显示存在导航结构，先确认初始界面"
+      },
+      {
+        "step": 2,
+        "action": "identify_navigation",
+        "target": "tabs_and_buttons",
+        "reason": "发现9个可点击元素，2个按钮，先识别导航入口"
+      },
+      {
+        "step": 3,
+        "action": "click_primary_button",
+        "target": "Button[type=primary]",
+        "reason": "界面复杂度simple，优先测试主要功能按钮"
+      },
+      {
+        "step": 4,
+        "action": "verify_navigation",
+        "target": "new_screen",
+        "reason": "验证导航跳转是否成功"
+      },
+      {
+        "step": 5,
+        "action": "scroll_test",
+        "target": "scrollable_area",
+        "reason": "认知地图显示可滚动区域，测试滚动功能"
+      }
+    ]
+  }
+}
+```
+
+### 第四步：执行智能遍历
+
+基于大模型的测试计划，执行实际测试：
+
+```bash
+# 执行第1步：确认初始界面
+node dist/src/cli.js snapshot --session xxx --json
+
+# 执行第2步：识别导航
+node dist/src/cli.js snapshot -i --session xxx
+
+# 执行第3步：点击主要按钮
+node dist/src/cli.js press @e20 --session xxx
+
+# 执行第4步：验证跳转
+node dist/src/cli.js snapshot --session xxx --json
+
+# 执行第5步：测试滚动
+node dist/src/cli.js scroll down 0.5 --session xxx
+```
+
+## 优势对比
+
+### 传统盲目测试 vs 认知地图引导测试
+
+| 特性 | 盲目测试 | 认知地图引导 |
+|-----|---------|------------|
+| **效率** | 低（随机点击） | 高（有目标） |
+| **覆盖率** | 难保证 | 可规划 |
+| **测试深度** | 表层 | 可深入关键路径 |
+| **大模型负担** | 重（需要实时分析） | 轻（已有认知基础） |
+| **可复用性** | 低 | 高（认知地图可复用） |
+
+## 实际收益
+
+### 认知地图提供的信息
+1. **UI结构**：节点数、深度、布局模式
+2. **交互元素**：按钮、输入框、Tab等数量和位置
+3. **界面特征**：是否可滚动、有弹窗、有列表等
+4. **测试建议**：基于复杂度的智能建议
+
+### 大模型使用方式
+大模型收到认知地图后：
+1. 不需要每次都分析完整UI树
+2. 可以制定有策略的测试计划
+3. 可以优先测试关键功能
+4. 可以避免无效的点击操作
+5. 可以更准确地预测测试结果
+
+## 扩展应用
+
+### 多界面认知地图
+可以导出多个界面的布局，生成完整的应用地图：
+
+```bash
+# 主界面
+hdc shell "uitest dumpLayout -p /data/local/tmp/home.json"
+
+# 详情界面（需要先导航进入）
+hdc shell "uitest dumpLayout -p /data/local/tmp/detail.json"
+
+# 设置界面
+hdc shell "uitest dumpLayout -p /data/local/tmp/settings.json"
+
+# 生成完整应用地图
+node scripts/merge-cognition-maps.js ./maps/*.json ./app-map.json
+```
+
+### 认知地图应用场景
+1. **自动化测试规划**：大模型基于地图制定测试策略
+2. **回归测试**：对比新旧版本的认知地图变化
+3. **UI一致性检查**：检查UI是否符合设计规范
+4. **性能优化**：识别复杂UI结构，优化渲染性能
+5. **无障碍测试**：识别缺少标签的交互元素

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

@@ -0,0 +1,11 @@
+# 文档已迁移
+
+本文件内容已整理至：
+
+**[wangcz_文档记录/](./wangcz_文档记录/)**
+
+- 索引：[README.md](./wangcz_文档记录/README.md)
+- 终端实录：[附录-终端实录-snapshot-i弹窗场景.md](./wangcz_文档记录/附录-终端实录-snapshot-i弹窗场景.md)
+- 快照说明：[02-snapshot-i与鸿蒙快照.md](./wangcz_文档记录/02-snapshot-i与鸿蒙快照.md)
+
+请以后在 `wangcz_文档记录/` 目录维护问答与修改记录。

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

@@ -0,0 +1,82 @@
+# CLI 与仓库用法
+
+## 1. 前置条件
+
+```bash
+cd <agent-device-src>
+pnpm install
+pnpm build    # 生成 dist/，本地 mjs 才能用
+```
+
+- Node >= 22  
+- HarmonyOS：`hdc` 可用，设备已连接（`hdc list targets`）  
+- 首次操作建议：`node bin/agent-device.mjs help workflow`
+
+---
+
+## 2. 命令入口
+
+| 方式 | 命令 | 说明 |
+|------|------|------|
+| 全局安装 | `agent-device …` | `npm install -g agent-device` 后 |
+| **本仓库（推荐）** | `node bin/agent-device.mjs …` | 与当前分支代码一致 |
+| 快捷 | `pnpm ad …` | 等同上一行 |
+
+未 build 时会报错：`Missing dist build. Run pnpm build`。
+
+---
+
+## 3. 标准会话闭环
+
+```bash
+# 可选：确认设备与应用
+node bin/agent-device.mjs devices --platform harmonyos
+node bin/agent-device.mjs apps --platform harmonyos
+
+# 1. 打开应用（必须先 open，才有 session）
+node bin/agent-device.mjs open <包名> --platform harmonyos --session hs1
+
+# 2. 看当前可交互元素
+node bin/agent-device.mjs snapshot -i --platform harmonyos --session hs1
+
+# 3. 操作（二选一或组合）
+node bin/agent-device.mjs press 'label="微信登录"' --platform harmonyos --session hs1
+node bin/agent-device.mjs press @e10 --platform harmonyos --session hs1
+
+# 4. 结束（必须 close，释放 session）
+node bin/agent-device.mjs close --platform harmonyos --session hs1
+```
+
+**习惯用法**：探索用 `@eN`（来自上一步 `-i`）；稳定脚本用 `'label="…"'` / `'id="…"'`。
+
+---
+
+## 4. 子命令速查
+
+| 类别 | 命令 | 用途 |
+|------|------|------|
+| 会话 | `open` / `close` / `appstate` | 拉起应用、结束会话、看前台包名 |
+| 观测 | `snapshot`、`-i`、`--json`、`--raw`、`-s @eN` | 读 UI；详见 [02](./02-snapshot-i与鸿蒙快照.md) |
+| 交互 | `press` / `click` / `fill` / `scroll` / `back` | 点按、输入、滚动、返回 |
+| 断言 | `is` / `get` / `find` / `wait` | 验证文案、状态、等待 |
+| 规划 | `cognition --json` | 单屏 UI 结构概览（给模型做计划） |
+
+---
+
+## 5. 两条技术路线（勿混用）
+
+```text
+路线 A — 会话内手动/Agent 操作
+  agent-device open → snapshot -i → press @eN 或 label=… → close
+
+路线 B — 批量智能遍历（写 traverse-output 报告）
+  run-smart-traverse-app.sh → hdc dumpLayout 全量 JSON → 坐标 press → 报告
+```
+
+| 对比项 | 路线 A | 路线 B |
+|--------|--------|--------|
+| UI 数据 | daemon `snapshot` | `uitest dumpLayout` 完整 JSON |
+| 典型点击 | ref / selector | `press cx cy` |
+| 产物 | 终端输出 | `smart-traverse-report.md` 等 |
+
+路线 B 见 [06-traverse-output报告生成全流程.md](./06-traverse-output报告生成全流程.md)。

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

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