refactor(harmony): update app name mapping and improve device handling logic

Author: quanru

packages/harmony/src/appNameMapping.ts

@@ -33,26 +33,10 @@ export const defaultAppNameMapping: Record<string, string> = {
   天气: 'com.huawei.hmos.weather',
   Weather: 'com.huawei.hmos.weather',
 
-  // Common third-party apps
-  微信: 'com.tencent.mm',
-  WeChat: 'com.tencent.mm',
-  支付宝: 'com.eg.android.AlipayGphone',
-  淘宝: 'com.taobao.taobao',
-  京东: 'com.jingdong.app.mall',
+  // Common third-party apps (HarmonyOS NEXT bundle names)
   抖音: 'com.ss.hm.ugc.aweme',
-  小红书: 'com.xingin.xhs',
-  bilibili: 'tv.danmaku.bili',
-  QQ: 'com.tencent.mobileqq',
-  微博: 'com.sina.weibo',
-  高德地图: 'com.autonavi.minimap',
-  百度地图: 'com.baidu.BaiduMap',
-  美团: 'com.sankuai.meituan',
-  饿了么: 'me.ele',
-  飞书: 'com.ss.android.lark',
-  豆包: 'com.larus.nova',
-  网易云音乐: 'com.netease.cloudmusic',
-  QQ音乐: 'com.tencent.qqmusic',
-  知乎: 'com.zhihu.android',
-  今日头条: 'com.ss.android.article.news',
-  Keep: 'com.gotokeep.keep',
+  支付宝: 'com.alipay.mobile.client',
+  高德地图: 'com.amap.hmapp',
+  百度: 'com.baidu.baiduapp',
+  携程: 'com.ctrip.harmonynext',
 };

packages/harmony/src/device.ts

@@ -36,6 +36,8 @@ export type { HarmonyDeviceOpt } from '@midscene/core/device';
 const defaultScrollUntilTimes = 10;
 const defaultSwipeSpeed = 600;
 const defaultFastSwipeSpeed = 2000;
+const maxScrollDistance = 9999999;
+const scrollQuadrantDivisions = 4;
 
 const debugDevice = getDebug('harmony:device');
 
@@ -128,7 +130,7 @@ export class HarmonyDevice implements AbstractInterface {
           await this.scrollUntilLeft(startingPoint);
         } else if (scrollToEventName === 'singleAction' || !scrollToEventName) {
           if (param?.direction === 'down' || !param || !param.direction) {
-            await this.scrollDown(param?.distance || undefined, startingPoint);
+            await this.scrollDown(param?.distance ?? undefined, startingPoint);
           } else if (param.direction === 'up') {
             await this.scrollUp(param.distance || undefined, startingPoint);
           } else if (param.direction === 'left') {
@@ -257,7 +259,6 @@ export class HarmonyDevice implements AbstractInterface {
     }
 
     this.connecting = (async () => {
-      let error: Error | null = null;
       debugDevice(`Initializing HDC with device ID: ${this.deviceId}`);
       try {
         this.hdc = new HdcClient({
@@ -273,16 +274,10 @@ export class HarmonyDevice implements AbstractInterface {
         return this.hdc;
       } catch (e) {
         debugDevice(`Failed to initialize HDC: ${e}`);
-        error = new Error(`Unable to connect to device ${this.deviceId}: ${e}`);
+        throw new Error(`Unable to connect to device ${this.deviceId}: ${e}`);
       } finally {
         this.connecting = null;
       }
-
-      if (error) {
-        throw error;
-      }
-
-      throw new Error('HDC initialization failed unexpectedly');
     })();
 
     return this.connecting;
@@ -320,8 +315,9 @@ export class HarmonyDevice implements AbstractInterface {
         const bundleName = this.resolvePackageName(uri) ?? uri;
         try {
           await hdc.startAbility(bundleName, 'EntryAbility');
-        } catch {
-          // EntryAbility failed, auto-discover the main ability
+        } catch (e: any) {
+          if (!e.message?.includes('resolve ability')) throw e;
+          // EntryAbility not found, auto-discover the main ability
           const mainAbility = await hdc.queryMainAbility(bundleName);
           if (!mainAbility) {
             throw new Error(
@@ -480,7 +476,7 @@ export class HarmonyDevice implements AbstractInterface {
   async keyboardPress(key: string): Promise<void> {
     // HarmonyOS uitest only accepts Back/Home/Power as string names.
     // All other keys must use numeric keycodes.
-    const keyMap: Record<string, string> = {
+    const harmonyKeyCodeMap: Record<string, string> = {
       Enter: '2054',
       Backspace: '2055',
       Tab: '2049',
@@ -495,14 +491,14 @@ export class HarmonyDevice implements AbstractInterface {
     };
 
     const normalizedKey = this.normalizeKeyName(key);
-    const harmonyKey = keyMap[normalizedKey] || key;
+    const harmonyKey = harmonyKeyCodeMap[normalizedKey] ?? key;
 
     const hdc = await this.getHdc();
     await hdc.keyEvent(harmonyKey);
   }
 
   private normalizeKeyName(key: string): string {
-    const keyMap: Record<string, string> = {
+    const keyNameAliasMap: Record<string, string> = {
       enter: 'Enter',
       backspace: 'Backspace',
       tab: 'Tab',
@@ -522,7 +518,7 @@ export class HarmonyDevice implements AbstractInterface {
     };
 
     const lowerKey = key.toLowerCase();
-    return keyMap[lowerKey] || key;
+    return keyNameAliasMap[lowerKey] ?? key;
   }
 
   async scroll(deltaX: number, deltaY: number, speed?: number): Promise<void> {
@@ -531,7 +527,7 @@ export class HarmonyDevice implements AbstractInterface {
     }
 
     const { width, height } = await this.size();
-    const n = 4;
+    const n = scrollQuadrantDivisions;
 
     const startX = Math.round(deltaX < 0 ? (n - 1) * (width / n) : width / n);
     const startY = Math.round(deltaY < 0 ? (n - 1) * (height / n) : height / n);
@@ -553,7 +549,7 @@ export class HarmonyDevice implements AbstractInterface {
 
   async scrollDown(distance?: number, startPoint?: Point): Promise<void> {
     const { height } = await this.size();
-    const scrollDistance = Math.round(distance || height);
+    const scrollDistance = Math.round(distance ?? height);
 
     if (startPoint) {
       const hdc = await this.getHdc();
@@ -569,7 +565,7 @@ export class HarmonyDevice implements AbstractInterface {
 
   async scrollUp(distance?: number, startPoint?: Point): Promise<void> {
     const { height } = await this.size();
-    const scrollDistance = Math.round(distance || height);
+    const scrollDistance = Math.round(distance ?? height);
 
     if (startPoint) {
       const hdc = await this.getHdc();
@@ -585,7 +581,7 @@ export class HarmonyDevice implements AbstractInterface {
 
   async scrollLeft(distance?: number, startPoint?: Point): Promise<void> {
     const { width } = await this.size();
-    const scrollDistance = Math.round(distance || width);
+    const scrollDistance = Math.round(distance ?? width);
 
     if (startPoint) {
       const hdc = await this.getHdc();
@@ -601,7 +597,7 @@ export class HarmonyDevice implements AbstractInterface {
 
   async scrollRight(distance?: number, startPoint?: Point): Promise<void> {
     const { width } = await this.size();
-    const scrollDistance = Math.round(distance || width);
+    const scrollDistance = Math.round(distance ?? width);
 
     if (startPoint) {
       const hdc = await this.getHdc();
@@ -636,7 +632,7 @@ export class HarmonyDevice implements AbstractInterface {
     }
 
     await repeat(defaultScrollUntilTimes, () =>
-      this.scroll(0, -9999999, defaultFastSwipeSpeed),
+      this.scroll(0, -maxScrollDistance, defaultFastSwipeSpeed),
     );
     await sleep(1000);
   }
@@ -655,7 +651,7 @@ export class HarmonyDevice implements AbstractInterface {
     }
 
     await repeat(defaultScrollUntilTimes, () =>
-      this.scroll(0, 9999999, defaultFastSwipeSpeed),
+      this.scroll(0, maxScrollDistance, defaultFastSwipeSpeed),
     );
     await sleep(1000);
   }
@@ -681,7 +677,7 @@ export class HarmonyDevice implements AbstractInterface {
     }
 
     await repeat(defaultScrollUntilTimes, () =>
-      this.scroll(-9999999, 0, defaultFastSwipeSpeed),
+      this.scroll(-maxScrollDistance, 0, defaultFastSwipeSpeed),
     );
     await sleep(1000);
   }
@@ -700,7 +696,7 @@ export class HarmonyDevice implements AbstractInterface {
     }
 
     await repeat(defaultScrollUntilTimes, () =>
-      this.scroll(9999999, 0, defaultFastSwipeSpeed),
+      this.scroll(maxScrollDistance, 0, defaultFastSwipeSpeed),
     );
     await sleep(1000);
   }

packages/harmony/src/hdc.ts

@@ -1,4 +1,5 @@
 import { execFile } from 'node:child_process';
+import { accessSync, constants as fsConstants } from 'node:fs';
 import { promisify } from 'node:util';
 import { getDebug } from '@midscene/shared/logger';
 
@@ -27,7 +28,7 @@ function resolveHdcPath(hdcPath?: string): string {
   ];
   for (const p of commonPaths) {
     try {
-      require('node:fs').accessSync(p, require('node:fs').constants.X_OK);
+      accessSync(p, fsConstants.X_OK);
       debugHdc(`Found HDC at: ${p}`);
       return p;
     } catch {}
@@ -43,8 +44,8 @@ export class HdcClient {
 
   constructor(options: HdcOptions) {
     this.hdcPath = resolveHdcPath(options.hdcPath);
-    this.deviceId = options.deviceId || '';
-    this.timeout = options.timeout || 60000;
+    this.deviceId = options.deviceId ?? '';
+    this.timeout = options.timeout ?? 60000;
   }
 
   private buildArgs(args: string[]): string[] {
@@ -191,33 +192,29 @@ export class HdcClient {
   }
 
   async queryMainAbility(bundleName: string): Promise<string | undefined> {
-    try {
-      const output = await this.shell(`bm dump -n ${bundleName}`);
-      const names: string[] = [];
-      for (const match of output.matchAll(/"name"\s*:\s*"([^"]+)"/g)) {
-        names.push(match[1]);
-      }
-      // Prefer: EntryAbility > MainAbility > {bundleName}.MainAbility > first *Ability
-      for (const candidate of [
-        'EntryAbility',
-        'MainAbility',
-        `${bundleName}.MainAbility`,
-      ]) {
-        if (names.includes(candidate)) return candidate;
-      }
-      // Fallback: find first ability-like name that isn't the bundle itself
-      return names.find(
-        (n) =>
-          n !== bundleName &&
-          n.endsWith('Ability') &&
-          !n.includes('Extension') &&
-          !n.includes('Service') &&
-          !n.includes('Form') &&
-          !n.includes('Dialog'),
-      );
-    } catch {
-      return undefined;
+    const output = await this.shell(`bm dump -n ${bundleName}`);
+    const names: string[] = [];
+    for (const match of output.matchAll(/"name"\s*:\s*"([^"]+)"/g)) {
+      names.push(match[1]);
+    }
+    // Prefer: EntryAbility > MainAbility > {bundleName}.MainAbility > first *Ability
+    for (const candidate of [
+      'EntryAbility',
+      'MainAbility',
+      `${bundleName}.MainAbility`,
+    ]) {
+      if (names.includes(candidate)) return candidate;
     }
+    // Fallback: find first ability-like name that isn't the bundle itself
+    return names.find(
+      (n) =>
+        n !== bundleName &&
+        n.endsWith('Ability') &&
+        !n.includes('Extension') &&
+        !n.includes('Service') &&
+        !n.includes('Form') &&
+        !n.includes('Dialog'),
+    );
   }
 
   async forceStop(bundleName: string): Promise<void> {

packages/harmony/src/mcp-server.ts

@@ -4,7 +4,7 @@ import {
   type Tool,
   createMCPServerLauncher,
 } from '@midscene/shared/mcp';
-import { HarmonyAgent } from './agent';
+import type { HarmonyAgent } from './agent';
 import { HarmonyMidsceneTools } from './mcp-tools.js';
 
 declare const __VERSION__: string;
@@ -42,9 +42,7 @@ export async function mcpKitForAgent(agent: Agent | HarmonyAgent): Promise<{
 }> {
   const toolsManager = new HarmonyMidsceneTools();
 
-  const harmonyAgent =
-    agent instanceof HarmonyAgent ? agent : (agent as HarmonyAgent);
-  toolsManager.setAgent(harmonyAgent);
+  toolsManager.setAgent(agent as HarmonyAgent);
   await toolsManager.initTools();
 
   return {

packages/harmony/src/utils.ts

@@ -3,13 +3,13 @@ import { HdcClient } from './hdc';
 
 const debugUtils = getDebug('harmony:utils');
 
-export interface HarmonyDevice {
+export interface HarmonyDeviceInfo {
   deviceId: string;
 }
 
 export async function getConnectedDevices(
   hdcPath?: string,
-): Promise<HarmonyDevice[]> {
+): Promise<HarmonyDeviceInfo[]> {
   try {
     const hdc = new HdcClient({ hdcPath });
     const targets = await hdc.listTargets();