@buaa_smat/hometrans 0.1.0 → 0.1.2

package/skills/hmos-ui-align/references/android-to-harmonyOS-ui-layout-mapping-reference.md

@@ -0,0 +1,117 @@
+# Android-to-HarmonyOS UI Layout Mapping Reference
+
+<!-- TODO: Fill in the actual UI layout mapping content -->
+<!-- This reference maps Android layout containers to HarmonyOS ArkUI layout equivalents -->
+<!-- Covers: LinearLayout→Column/Row, FrameLayout→Stack, ConstraintLayout→RelativeContainer, RecyclerView→List+LazyForEach, ScrollView→Scroll, etc. -->
+
+
+## 布局容器映射
+
+| 安卓部分UI | 对应鸿蒙部分UI | 其他说明 |
+|-----------|---------------|---------|
+| `LinearLayout` (vertical) | `Column` 组件 | 纵向线性布局，支持 `.justifyContent()`、`.alignItems()` |
+| `LinearLayout` (horizontal) | `Row` 组件 | 横向线性布局 |
+| `FrameLayout` | `Stack` 组件 | 层叠布局，支持 `.alignContent()` |
+| `RelativeLayout` | `RelativeContainer` 组件 | 相对布局，通过 `.alignRules()` 设置定位规则 |
+| `ConstraintLayout` | `RelativeContainer` / 自定义布局 | 约束布局，复杂场景可用自定义 `onMeasureSize`/`onPlaceChildren` |
+| `FlexboxLayout` | `Flex` 组件 | 弹性布局，支持 `FlexDirection`/`FlexWrap`/`FlexAlign` 标准 Flexbox |
+| `GridLayout` | `Grid` 组件 | 网格布局，通过 `.columnsTemplate('1fr 1fr 1fr')` 定义列 |
+| `TableLayout` | `Grid` 组件 | 表格布局，使用 `Grid` 组件模拟表格结构 |
+| `CoordinatorLayout` | 组合 `Scroll` + `Column` + 动画 | 无直接对应，需组合模拟 AppBar 折叠效果 |
+| `AppBarLayout` / `CollapsingToolbarLayout` | `Navigation` 标题栏 + `titleMode` | 折叠工具栏，`NavigationTitleMode.Full`→`.Mini` 自动切换 |
+| `ScrollView` | `Scroll` 组件 | 滚动容器，通过 `Scroller` 控制器编程式滚动 |
+| `HorizontalScrollView` | `Scroll` + `ScrollDirection.Horizontal` | 横向滚动 |
+| `NestedScrollView` | `Scroll` + `.nestedScroll()` | 嵌套滚动策略配置 |
+| `ViewPager` / `ViewPager2` | `Swiper` 组件 | 页面滑动切换，支持 `.autoPlay()`、`.indicator()`、`.loop()` |
+| `SwipeRefreshLayout` | `Refresh` 组件 | 下拉刷新，通过 `.onRefreshing()` 回调处理刷新 |
+| `RecyclerView` | `List` 组件 | 高性能列表，使用 `List` + `ForEach`/`LazyForEach` 渲染子组件 |
+| `RecyclerView` (GridLayoutManager) | `Grid` 组件 | 网格布局，通过 `.columnsTemplate()` 设置列数 |
+| `RecyclerView` (StaggeredGridLayoutManager) | `WaterFlow` 组件 | 瀑布流布局 |
+| `ListView` | `List` 组件 | 传统列表，使用 `List` 组件实现 |
+| `GridView` | `Grid` 组件 | 网格视图，使用 `Grid` 组件实现 |
+| `DrawerLayout` / `NavigationView` | `SideBarContainer` 组件 | 侧边栏/抽屉 |
+| `TabLayout` + `ViewPager` | `Tabs` 组件 | 标签页，`Tabs` 整合标签栏和内容页切换 |
+| `BottomNavigationView` | `Tabs` + `BarPosition.End` | 底部导航栏 |
+| `CardView` | `Card` 组件 / `Container` + 样式 | 卡片视图，使用 `Card` 组件或自定义样式实现 |
+| `Space` | `Blank` 组件 | 空白间隔，使用 `Blank` 组件实现 |
+| `FragmentContainerView` | `NavDestination` / `@Component` | 片段容器视图，映射到 `NavDestination` 或自定义组件 |
+| `RecyclerViewFastScroller` | 自定义组件 | 列表快速滚动条，需自定义实现 |
+| `MySearchMenu` (自定义) | `Search` 组件 + 自定义菜单 | 自定义搜索菜单，使用 `Search` 组件并添加自定义菜单 |
+| `MyViewPager` (自定义) | `Swiper` 组件 | 自定义视图分页器，使用 `Swiper` 组件实现 |
+| `MyRecyclerView` (自定义) | `List` 组件 | 自定义 RecyclerView，使用 `List` 组件实现 |
+| `MyTextView` (自定义) | `Text` 组件 | 自定义 TextView，使用 `Text` 组件实现 |
+| `MyAppCompatCheckbox` (自定义) | `Checkbox` 组件 | 自定义 Checkbox，使用 `Checkbox` 组件实现 |
+
+## 布局属性映射
+
+| 安卓部分UI | 对应鸿蒙部分UI | 其他说明 |
+|-----------|---------------|---------|
+| `layout_weight` | `.layoutWeight()` / `.flexGrow()` | 权重分配 |
+| `padding` / `margin` | `.padding()` / `.margin()` | 支持统一或分别指定 `{ top, right, bottom, left }` |
+| `View.GONE` / `View.INVISIBLE` | `Visibility.None` / `Visibility.Hidden` | `None`=不占位（GONE）；`Hidden`=占位不显示（INVISIBLE） |
+| `android:id` | `.id('xxx')` / 组件引用变量 | 组件标识 |
+| `android:background` | `.backgroundColor()` / `.backgroundImage()` | 背景 |
+| `android:alpha` | `.opacity()` | 透明度 0~1 |
+| `android:elevation` | `.shadow({ radius, color, offsetX, offsetY })` | 阴影 |
+| `android:rotation` | `.rotate({ angle: xxx })` | 旋转 |
+| `android:scaleX/Y` | `.scale({ x: xxx, y: xxx })` | 缩放 |
+| `android:translationX/Y` | `.translate({ x: xxx, y: xxx })` | 平移 |
+| `android:clipToOutline` | `.clip(true)` / `.clipShape()` | 裁剪 |
+| `setEnabled(false)` | `.enabled(false)` | 禁用状态 |
+| `android:focusable` | `.focusable(true)` | 可聚焦 |
+| `android:focusableInTouchMode` | `.focusable(true)` + `.focusOnTouch(true)` | 触摸模式下可聚焦 |
+| `android:clickable` | `.enabled(true)` + `.onClick()` | 可点击 |
+| `android:longClickable` | `.gesture(LongPressGesture())` | 可长按 |
+| `android:scrollbars` | `.scrollBar()` | 滚动条 |
+| `android:fadeScrollbars` | `.scrollBar().fade(true)` | 滚动条自动隐藏 |
+| `android:overScrollMode` | `.overScrollMode()` | 过度滚动模式 |
+| `GradientDrawable` | `.linearGradient()` / `.radialGradient()` | 渐变背景 |
+| `CardView` radius | `.borderRadius()` | 圆角 |
+| `GradientDrawable.setStroke()` | `.border({ width, color, radius })` | 边框 |
+| `android:layout_width` / `android:layout_height` | `.width()` / `.height()` | 宽高设置，支持具体数值、百分比、`'match_parent'`/`'wrap_content'` |
+| `android:gravity` | `.alignItems()` / `.justifyContent()` | 内容对齐方式 |
+| `android:layout_gravity` | `.alignSelf()` | 子组件在父容器中的对齐方式 |
+| `android:orientation` (LinearLayout) | `Column` / `Row` | 布局方向 |
+| `android:divider` (LinearLayout) | `Divider` 组件 | 分隔线 |
+| `android:showDividers` (LinearLayout) | `Divider` 组件位置 | 分隔线显示位置 |
+
+## 页面结构映射
+
+| 安卓部分UI | 对应鸿蒙部分UI | 其他说明 |
+|-----------|---------------|---------|
+| `Activity` | `PageAbility` | 主UI容器 |
+| `Fragment` | `NavDestination` / `@Component` | 通过 Navigation + NavDestination 实现子页面路由 |
+| `Service` | `ServiceAbility` | 后台服务 |
+| `BroadcastReceiver` | `EventHub` + `@Event` | 广播接收器，使用事件订阅机制 |
+| `ContentProvider` | `DataAbility` | 内容提供者 |
+| `Toolbar` / `ActionBar` | `Navigation` 标题栏 | 通过 `.title()` 和 `.menus()` 配置 |
+| `Intent` | `router` 模块 | 页面导航，使用 `router.push()`、`router.replace()` 等 |
+| `Bundle` | `router.push({ params: {} })` | 页面间传递数据 |
+| `onActivityResult` | `router.push()` + 回调 | 页面返回结果 |
+| `startActivityForResult` | `router.push()` + 回调 | 启动页面并获取结果 |
+
+## 列表与可滚动组件映射
+
+| 安卓部分UI | 对应鸿蒙部分UI | 其他说明 |
+|-----------|---------------|---------|
+| `RecyclerView.Adapter` | `LazyForEach` + `IDataSource` | 数据适配器，实现 `IDataSource` 接口配合 `LazyForEach` 懒加载 |
+| `RecyclerView.ViewHolder` | `@Builder` / `@Component` | 声明式 UI 无需 ViewHolder 模式 |
+| `LinearLayoutManager` | `List` 默认布局 | 纵向列表，`.listDirection(Axis.Horizontal)` 切换横向 |
+| `GridLayoutManager` | `Grid` 组件 | 网格布局管理器 |
+| `StaggeredGridLayoutManager` | `WaterFlow` 组件 | 瀑布流布局管理器 |
+| `ItemTouchHelper` (swipe) | `ListItem.swipeAction()` | 列表项滑动操作菜单 |
+| `ItemTouchHelper` (drag) | `ListItem.dragable()` | 列表项拖拽排序 |
+| `DiffUtil` | `IDataSource` 的 `DataChangeListener` | 差异通知，`onDataAdd`/`onDataDelete`/`onDataChange` |
+| `PagerAdapter` / `FragmentStateAdapter` | `Swiper` + `ForEach`/`LazyForEach` | 无需 Adapter 模式，直接循环渲染子页面 |
+| `ListAdapter` | `LazyForEach` + `IDataSource` | 带 DiffUtil 的适配器 |
+| `ArrayAdapter` | `ForEach` + 数组 | 数组适配器 |
+| `BaseAdapter` | `ForEach` / `LazyForEach` | 基础适配器 |
+
+## 迁移注意事项
+
+1. **范式转换**：Android 使用命令式 UI（XML 布局 + Java/Kotlin 操作）；ArkUI 使用声明式 UI（ArkTS 组件树 + 状态驱动渲染）
+2. **Adapter 模式消除**：`RecyclerView.Adapter`、`PagerAdapter` 等被 `ForEach`/`LazyForEach` + `IDataSource` 替代
+3. **Fragment → NavDestination**：Fragment 模块化 UI 能力映射到 `Navigation` + `NavDestination` 路由
+4. **布局属性调整**：Android 的布局属性需要转换为 ArkUI 的链式调用语法
+5. **性能优化**：使用 `LazyForEach` 进行懒加载，避免一次性渲染大量数据
+6. **响应式布局**：使用 `Flex` 和 `Grid` 组件实现响应式布局，适应不同屏幕尺寸

package/skills/hmos-ui-align/scripts/app_feature_verify.py

@@ -0,0 +1,443 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+应用页面导航工具 —— 使用 PhoneAgent 按指定路径操作设备，导航到目标页面。
+
+支持 Android (ADB) 和 HarmonyOS (HDC) 两种设备类型。
+
+依赖: pip install openpyxl phone-agent
+运行前需确保: 设备已连接 (HDC/ADB)、模型 API 可用
+
+用法:
+  # 自由 prompt 导航
+  python app_feature_verify.py --device adb --app Gallery --package com.example.gallery --prompt "打开相册，进入设置页面"
+
+  # 按功能路径导航
+  python app_feature_verify.py --app 简单图库 --package com.simplemobiletools.gallery.pro --task "L1相册详情L2更多L3筛选媒体文件"
+"""
+
+import argparse
+import re
+import sys
+import os
+from pathlib import Path
+
+# 强制设置 UTF-8 编码以避免 Windows GBK 编码问题
+if sys.platform == 'win32':
+    import io
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace')
+    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8', errors='replace')
+
+
+# ---------------------------------------------------------------------------
+# Excel 功能清单解析
+# ---------------------------------------------------------------------------
+
+def parse_app_feature(
+    file_path: str | Path | None = None,
+    sheet_name: str | int = 0,
+) -> list[dict]:
+    """解析功能清单 Excel，返回功能清单列表。"""
+    import openpyxl
+
+    file_path = Path(file_path)
+    if not file_path.exists():
+        raise FileNotFoundError(f"文件不存在: {file_path}")
+
+    wb = openpyxl.load_workbook(file_path, read_only=True, data_only=True)
+
+    if isinstance(sheet_name, int):
+        sheet = wb.worksheets[sheet_name]
+    else:
+        sheet = wb[sheet_name]
+
+    rows = list(sheet.iter_rows(values_only=True))
+    wb.close()
+
+    if not rows:
+        return []
+
+    headers = [str(h) if h is not None else f"col_{i}" for i, h in enumerate(rows[0])]
+
+    result = []
+    for row in rows[1:]:
+        row_dict = {}
+        for i, val in enumerate(row):
+            key = headers[i] if i < len(headers) else f"col_{i}"
+            row_dict[key] = val
+        result.append(row_dict)
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Markdown 功能清单解析
+# ---------------------------------------------------------------------------
+
+def parse_app_feature_md(file_path: str | Path) -> list[dict]:
+    """解析 Markdown 测试用例文件，返回场景列表。"""
+    file_path = Path(file_path)
+    if not file_path.exists():
+        raise FileNotFoundError(f"文件不存在: {file_path}")
+
+    text = file_path.read_text(encoding="utf-8")
+    lines = text.splitlines()
+
+    results: list[dict] = []
+    current_feature = ""
+    current_scenario: dict | None = None
+    collecting_sub_items: str | None = None
+
+    for line in lines:
+        stripped = line.strip()
+
+        feat_match = re.match(r"^##\s+Feature:\s*(.+)$", stripped)
+        if feat_match:
+            if current_scenario is not None:
+                results.append(current_scenario)
+                current_scenario = None
+            current_feature = feat_match.group(1).strip()
+            collecting_sub_items = None
+            continue
+
+        scen_match = re.match(r"^###\s+Scenario:\s*(.+)$", stripped)
+        if scen_match:
+            if current_scenario is not None:
+                results.append(current_scenario)
+            scenario_name = scen_match.group(1).strip()
+            feature_name = re.sub(r"^FEA-\d+\s*", "", current_feature)
+            current_scenario = {
+                "feature": current_feature,
+                "scenario": scenario_name,
+                "preconditions": [],
+                "actions": [],
+                "expectations": [],
+                "L1": feature_name,
+                "L2": scenario_name,
+                "L3": "",
+            }
+            collecting_sub_items = None
+            continue
+
+        if current_scenario is None:
+            continue
+
+        if re.match(r"^-\s*前置条件[：:]", stripped):
+            collecting_sub_items = "preconditions"
+            continue
+
+        action_match = re.match(r"^-\s*动作[：:]\s*(.+)$", stripped)
+        if action_match:
+            collecting_sub_items = None
+            current_scenario["actions"].append(action_match.group(1).strip())
+            continue
+
+        expect_match = re.match(r"^-\s*预期结果[：:]\s*(.+)$", stripped)
+        if expect_match:
+            collecting_sub_items = None
+            current_scenario["expectations"].append(expect_match.group(1).strip())
+            continue
+
+        sub_match = re.match(r"^\s+-\s+(.+)$", line)
+        if sub_match and collecting_sub_items == "preconditions":
+            current_scenario["preconditions"].append(sub_match.group(1).strip())
+            continue
+
+        if stripped and not stripped.startswith("-"):
+            collecting_sub_items = None
+
+    if current_scenario is not None:
+        results.append(current_scenario)
+
+    return results
+
+
+# ---------------------------------------------------------------------------
+# 应用注册
+# ---------------------------------------------------------------------------
+
+def register_app(app_name: str, package: str, device_type: str, ability: str = "EntryAbility") -> None:
+    """将应用注册到 phone-agent 的配置中。"""
+    if device_type == "hdc":
+        from phone_agent.config import apps_harmonyos
+        apps_harmonyos.APP_PACKAGES[app_name] = package
+        apps_harmonyos.APP_ABILITIES[package] = ability
+    else:
+        from phone_agent.config import apps
+        apps.APP_PACKAGES[app_name] = package
+
+
+# ---------------------------------------------------------------------------
+# 功能路径提取
+# ---------------------------------------------------------------------------
+
+def _get_feature_path(item: dict) -> tuple[str, str]:
+    """从功能项提取层级路径和叶子节点名称。"""
+    keys = [k for k in ("L1", "L2", "L3") if k in item]
+    if not keys:
+        keys = [k for k in ("一级", "二级", "三级") if k in item]
+    if not keys:
+        keys = list(item.keys())[:3]
+
+    parts = []
+    for k in keys:
+        v = item.get(k)
+        if v is not None and str(v).strip():
+            parts.append(str(v).strip())
+
+    if not parts:
+        return "", ""
+    return " > ".join(parts), parts[-1]
+
+
+# ---------------------------------------------------------------------------
+# 构建导航 prompt
+# ---------------------------------------------------------------------------
+
+def _build_navigate_prompt(app_name: str, path_str: str, leaf: str, app_hints: str | None = None) -> str:
+    """构建导航到目标页面的 prompt。"""
+    prompt = (
+        f"打开{app_name}，按照以下路径依次点击导航到目标页面：{path_str}。"
+        f"最终目标是到达「{leaf}」所在的页面。"
+        "注意："
+        "1. 鸿蒙手机浅色/深色模式切换路径：设置->显示与亮度"
+        "2. '更多'组件可能表示为 三横 或者 三点。"
+        "3. '设置'组件可能表示为 齿轮。"
+        "到达目标页面后请回复'已到达'，无法到达请回复'未找到'。"
+    )
+    if app_hints:
+        prompt += f"\n补充提示: {app_hints}"
+    return prompt
+
+
+# ---------------------------------------------------------------------------
+# 判断是否到达目标页面
+# ---------------------------------------------------------------------------
+
+def _judge_reached(msg: str) -> bool:
+    """根据 agent 回复判断是否到达了目标页面。"""
+    if not msg:
+        return False
+    reached_keywords = ("已到达", "到达", "存在", "找到", "完成", "成功", "已确认", "已进入", "已打开")
+    failed_keywords = ("未找到", "不存在", "无法找到", "无法到达", "没有", "失败", "未到达")
+    first_line = msg.split('\n')[0]
+    if any(kw in first_line for kw in failed_keywords):
+        return False
+    if any(kw in first_line for kw in reached_keywords):
+        return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# phone-agent runtime patches (idempotent)
+# ---------------------------------------------------------------------------
+
+def _apply_phone_agent_patches():
+    """Monkey-patch phone_agent bugs so the skill works on an unpatched install."""
+    if getattr(_apply_phone_agent_patches, '_done', False):
+        return
+    _apply_phone_agent_patches._done = True
+
+    import math
+    import time as _time
+
+    # Patch 1: HarmonyOS swipe — last arg should be velocity (pps), not duration (ms)
+    import phone_agent.hdc.device as _hdc
+    if not getattr(_hdc.swipe, '_patched', False):
+        def _swipe(start_x, start_y, end_x, end_y,
+                   duration_ms=None, device_id=None, delay=None):
+            if delay is None:
+                delay = _hdc.TIMING_CONFIG.device.default_swipe_delay
+            hdc_prefix = _hdc._get_hdc_prefix(device_id)
+            distance = math.sqrt((start_x - end_x) ** 2 + (start_y - end_y) ** 2)
+            if duration_ms is None:
+                duration_ms = int(distance ** 2 / 1000)
+            duration_ms = max(500, min(duration_ms, 1000))
+            velocity = int((distance / duration_ms) * 4000)
+            velocity = max(500, min(velocity, 40000))
+            _hdc._run_hdc_command(
+                hdc_prefix + [
+                    "shell", "uitest", "uiInput", "swipe",
+                    str(start_x), str(start_y), str(end_x), str(end_y),
+                    str(velocity),
+                ],
+                capture_output=True,
+            )
+            _time.sleep(delay)
+        _swipe._patched = True
+        _hdc.swipe = _swipe
+
+    # Patch 2: parse_action — regex fallback when do() contains unescaped quotes
+    import phone_agent.actions.handler as _handler
+    if not getattr(_handler.parse_action, '_patched', False):
+        _orig_parse = _handler.parse_action
+        def _parse_action(response):
+            try:
+                return _orig_parse(response)
+            except ValueError as e:
+                if 'Failed to parse do() action' in str(e):
+                    m = re.search(
+                        r'do\s*\(\s*action\s*=\s*"([^"]*)"\s*,\s*message\s*="(.*)"\s*\)\s*$',
+                        response.strip(), re.DOTALL,
+                    )
+                    if m:
+                        msg = m.group(2)
+                        msg = msg.replace("\\n", "\x0a").replace("\\t", "\x09").replace("\\r", "\x0d")
+                        msg = msg.replace('\\"', '"')
+                        return {"_metadata": "do", "action": m.group(1), "message": msg}
+                raise
+        _parse_action._patched = True
+        _handler.parse_action = _parse_action
+
+
+# ---------------------------------------------------------------------------
+# 核心导航逻辑
+# ---------------------------------------------------------------------------
+
+def navigate(
+    model_config,
+    app_name: str,
+    package: str,
+    device_type: str = "hdc",
+    prompt: str | None = None,
+    single_task: str | None = None,
+    feature_file: str | Path = "",
+    sheet_name: int = 0,
+    offset: int = 1,
+    limit: int | None = None,
+    max_steps: int = 30,
+    verbose: bool = True,
+    app_hints: str | None = None,
+) -> None:
+    """按指定路径操作设备导航到目标页面，输出是否到达。"""
+    _apply_phone_agent_patches()
+    register_app(app_name, package, device_type)
+
+    from phone_agent import PhoneAgent
+    from phone_agent.agent import AgentConfig
+    from phone_agent.device_factory import set_device_type, DeviceType
+
+    agent_config = AgentConfig(max_steps=max_steps, verbose=verbose)
+    set_device_type(DeviceType.HDC if device_type == "hdc" else DeviceType.ADB)
+    agent = PhoneAgent(model_config=model_config, agent_config=agent_config)
+
+    # 收集要导航的目标列表: [(prompt_text, display_label), ...]
+    tasks: list[tuple[str, str]] = []
+
+    if prompt:
+        full_prompt = f"打开{app_name}，{prompt}"
+        tasks.append((full_prompt, prompt))
+    elif single_task:
+        level_parts = re.split(r'(L[123])', single_task)
+        item = {}
+        for j in range(1, len(level_parts) - 1, 2):
+            key = level_parts[j]
+            val = level_parts[j + 1].strip()
+            if val:
+                item[key] = val
+        path_str, leaf = _get_feature_path(item)
+        if path_str:
+            tasks.append((_build_navigate_prompt(app_name, path_str, leaf, app_hints), path_str))
+    else:
+        feature_path = Path(feature_file)
+        if feature_path.suffix.lower() == ".md":
+            features = parse_app_feature_md(file_path=feature_file)
+        else:
+            features = parse_app_feature(file_path=feature_file, sheet_name=sheet_name)
+        if offset > 1:
+            features = features[offset - 1:]
+        if limit is not None:
+            features = features[:limit]
+        for item in features:
+            path_str, leaf = _get_feature_path(item)
+            if path_str:
+                tasks.append((_build_navigate_prompt(app_name, path_str, leaf, app_hints), path_str))
+
+    for i, (task_prompt, label) in enumerate(tasks):
+        if len(tasks) > 1:
+            print(f"\n[{i + 1}/{len(tasks)}] 导航: {label}")
+        else:
+            print(f"导航: {label}")
+
+        try:
+            result_msg = agent.run(task_prompt)
+            reached = _judge_reached(result_msg)
+        except Exception:
+            reached = False
+
+        if reached:
+            print("到达目标页面")
+        else:
+            print("未找到目标页面")
+
+        if i < len(tasks) - 1:
+            agent.reset()
+
+
+# ---------------------------------------------------------------------------
+# CLI 入口
+# ---------------------------------------------------------------------------
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="按指定路径操作设备导航到目标页面（支持 Android / HarmonyOS）"
+    )
+    parser.add_argument("--device", choices=["hdc", "adb"], default="hdc",
+                        help="设备类型: hdc=HarmonyOS, adb=Android（默认 hdc）")
+    parser.add_argument("--app", type=str, required=True, help="应用名称")
+    parser.add_argument("--package", type=str, required=True, help="应用包名")
+    parser.add_argument("--task", type=str, default=None,
+                        help="功能路径，格式: 'L1xxxL2xxxL3xxx'")
+    parser.add_argument("--prompt", type=str, default=None,
+                        help="直接注入给 Agent 的自然语言导航指令")
+    parser.add_argument("--feature", type=str, default=None,
+                        help="功能清单文件路径（.xlsx / .md）")
+    parser.add_argument("--limit", type=int, default=None, help="仅导航前 N 条")
+    parser.add_argument("--offset", type=int, default=1, help="从第几条开始（1-based）")
+    parser.add_argument("--sheet", type=int, default=0, help="Excel 工作表索引")
+    parser.add_argument("--api-key", type=str, default="", help="智谱 API Key")
+    parser.add_argument("--max-steps", type=int, default=30, help="Agent 最大步数")
+    parser.add_argument("--app-hints", type=str, default=None, help="应用上下文提示")
+    parser.add_argument("-q", "--quiet", action="store_true", help="减少输出")
+    args = parser.parse_args()
+
+    if not args.prompt and not args.task and not args.feature:
+        parser.error("必须指定 --feature、--task 或 --prompt 之一")
+
+    api_key = args.api_key or os.environ.get("GLM_API_KEY", "")
+    if not api_key and not args.quiet:
+        print("提示: 未设置 API Key，请通过 --api-key 或环境变量 GLM_API_KEY 配置")
+        print("继续运行可能因鉴权失败而报错\n")
+
+    from phone_agent.model import ModelConfig
+
+    model_config = ModelConfig(
+        base_url="https://open.bigmodel.cn/api/paas/v4",
+        api_key=api_key,
+        model_name="autoglm-phone",
+        temperature=0.1,
+    )
+
+    device_label = "ADB (Android)" if args.device == "adb" else "HDC (HarmonyOS)"
+    print(f"设备: {device_label}, 应用: {args.app} ({args.package})")
+    print("-" * 50)
+
+    navigate(
+        model_config=model_config,
+        app_name=args.app,
+        package=args.package,
+        device_type=args.device,
+        prompt=args.prompt,
+        single_task=args.task,
+        feature_file=args.feature or "",
+        sheet_name=args.sheet,
+        offset=args.offset,
+        limit=args.limit,
+        max_steps=args.max_steps,
+        verbose=not args.quiet,
+        app_hints=args.app_hints,
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/hmos-ui-align/scripts/navigation-capure.md

@@ -0,0 +1,37 @@
+Create a timestamped output directory under `capture_output_dir`:
+```
+task_dir = capture_output_dir / "task_{timestamp}"
+android_capture_dir = task_dir / "android_page_{i}_{name}"
+hmos_capture_dir = task_dir / "hmos_page_{i}_{name}"
+```
+Each paired hmos-android page-pair should have the same `i`
+
+## Navigation prompt rules
+
+Each page's `android_nav_path` / `hmos_nav_path` is used as the `--prompt` for `app_feature_verify.py`.
+The `--prompt` mode auto-prepends "打开{app_name}，" so do not include "打开{app_name}" in the prompt.
+
+## Navigate to Android page and Capture (If navigated Success)
+```bash
+PYTHONIOENCODING=utf-8 python ./app_feature_verify.py \
+  --device adb \
+  --app "{android.app_name}" \
+  --package "{android.package}" \
+  --prompt "{pages[i].android_nav_path}" \
+  --api-key "{glm_api_key}" \
+  --max-steps 15
+```
+
+**Capture Android page** (if navigation succeeded)
+```bash
+PYTHONIOENCODING=utf-8 python ./page_capture.py --device adb -o "{android_capture_dir}"
+```
+
+## Navigate & Capture HarmonyOS Pages
+
+Same as Andorid but with `--device hdc` and HarmonyOS config values. Directory pattern:
+```
+hmos_capture_dir = task_dir / "hmos_page_{i}_{name}"
+```
+For pages missed in harmony OS app, navigation will certainly fail — `hmos_capture_dir` will be empty, which is expected. Skip navigation for these pages and leave the directory empty.
+