@midscene/harmony 1.10.11 → 1.10.12-beta-20260812055946.0

package/dist/es/bin.mjs

@@ -60,6 +60,23 @@ function _define_property(obj, key, value) {
 }
 const execFileAsync = promisify(execFile);
 const debugHdc = getDebug('harmony:hdc');
+const supportedStringKeyEvents = new Set([
+    'Back',
+    'Home',
+    'Power'
+]);
+const numericKeyEventPattern = /^\d+$/;
+const uiInputErrorPattern = /(?:(?:Invalid parameters|Missing parameter|Too many parameters)\.?|Please confirm that the coordinate values are correct\.?)/i;
+const minUiInputSpeed = 200;
+const maxUiInputSpeed = 40000;
+function roundUiCoordinate(value, name) {
+    if (!Number.isFinite(value) || value < 0) throw new Error(`HDC ${name} coordinate must be a non-negative finite number`);
+    return Math.round(value);
+}
+function roundUiInputSpeed(value, operation) {
+    if (!Number.isFinite(value) || value < minUiInputSpeed || value > maxUiInputSpeed) throw new Error(`HDC ${operation} speed must be a finite number between ${minUiInputSpeed} and ${maxUiInputSpeed}`);
+    return Math.round(value);
+}
 function resolveHdcPath(hdcPath) {
     if (hdcPath) return hdcPath;
     if (process.env.HDC_HOME) {
@@ -121,6 +138,26 @@ class HdcClient {
     async shell(command) {
         return this.exec('shell', command);
     }
+    assertUiInputSucceeded(operation, output, detail) {
+        const errorMatch = output.match(uiInputErrorPattern);
+        if (!errorMatch) return;
+        const detailText = detail ? ` for ${detail}` : '';
+        throw new Error(`HDC uiInput ${operation} failed${detailText}: ${errorMatch[0]}`);
+    }
+    async runUiInput(operation, args, detail) {
+        const output = await this.shell(`uitest uiInput ${operation} ${args}`);
+        this.assertUiInputSucceeded(operation, output, detail);
+    }
+    buildPointerMovementArgs(operation, fromX, fromY, toX, toY, speed) {
+        const args = [
+            roundUiCoordinate(fromX, 'fromX'),
+            roundUiCoordinate(fromY, 'fromY'),
+            roundUiCoordinate(toX, 'toX'),
+            roundUiCoordinate(toY, 'toY')
+        ];
+        if (void 0 !== speed) args.push(roundUiInputSpeed(speed, operation));
+        return args.join(' ');
+    }
     async fileSend(localPath, remotePath) {
         await this.exec('file', 'send', localPath, remotePath);
     }
@@ -138,63 +175,49 @@ class HdcClient {
         return output.slice(jsonStart);
     }
     async click(x, y) {
-        await this.shell(`uitest uiInput click ${Math.round(x)} ${Math.round(y)}`);
+        await this.runUiInput('click', `${roundUiCoordinate(x, 'x')} ${roundUiCoordinate(y, 'y')}`);
     }
     async doubleClick(x, y) {
-        await this.shell(`uitest uiInput doubleClick ${Math.round(x)} ${Math.round(y)}`);
+        await this.runUiInput('doubleClick', `${roundUiCoordinate(x, 'x')} ${roundUiCoordinate(y, 'y')}`);
     }
     async longClick(x, y) {
-        await this.shell(`uitest uiInput longClick ${Math.round(x)} ${Math.round(y)}`);
+        await this.runUiInput('longClick', `${roundUiCoordinate(x, 'x')} ${roundUiCoordinate(y, 'y')}`);
     }
     async swipe(fromX, fromY, toX, toY, speed) {
-        const args = [
-            Math.round(fromX),
-            Math.round(fromY),
-            Math.round(toX),
-            Math.round(toY)
-        ];
-        if (void 0 !== speed) args.push(Math.round(speed));
-        await this.shell(`uitest uiInput swipe ${args.join(' ')}`);
+        await this.runUiInput('swipe', this.buildPointerMovementArgs('swipe', fromX, fromY, toX, toY, speed));
     }
     async fling(fromX, fromY, toX, toY, speed) {
-        const args = [
-            Math.round(fromX),
-            Math.round(fromY),
-            Math.round(toX),
-            Math.round(toY)
-        ];
-        if (void 0 !== speed) args.push(Math.round(speed));
-        await this.shell(`uitest uiInput fling ${args.join(' ')}`);
+        await this.runUiInput('fling', this.buildPointerMovementArgs('fling', fromX, fromY, toX, toY, speed));
     }
     async drag(fromX, fromY, toX, toY, speed) {
-        const args = [
-            Math.round(fromX),
-            Math.round(fromY),
-            Math.round(toX),
-            Math.round(toY)
-        ];
-        if (void 0 !== speed) args.push(Math.round(speed));
-        await this.shell(`uitest uiInput drag ${args.join(' ')}`);
+        await this.runUiInput('drag', this.buildPointerMovementArgs('drag', fromX, fromY, toX, toY, speed));
     }
     async inputText(x, y, text) {
         const escapedText = text.replace(/'/g, "'\\''");
-        await this.shell(`uitest uiInput inputText ${Math.round(x)} ${Math.round(y)} '${escapedText}'`);
+        await this.runUiInput('inputText', `${roundUiCoordinate(x, 'x')} ${roundUiCoordinate(y, 'y')} '${escapedText}'`);
     }
     async keyEvent(...keys) {
-        await this.shell(`uitest uiInput keyEvent ${keys.join(' ')}`);
+        if (keys.length < 1 || keys.length > 3) throw new Error('HDC keyEvent requires between 1 and 3 keys');
+        if (keys.length > 1 && keys.some((key)=>supportedStringKeyEvents.has(key))) throw new Error('HDC system key events cannot be combined');
+        for (const key of keys)if (!supportedStringKeyEvents.has(key) && !numericKeyEventPattern.test(key)) throw new Error(`Invalid HDC key event: ${key}`);
+        const joinedKeys = keys.join(' ');
+        await this.runUiInput('keyEvent', joinedKeys, joinedKeys);
     }
     async clearTextField(length = 100) {
-        if (length <= 0) return;
-        const MAX_KEYS_PER_CALL = 3;
+        if (!Number.isSafeInteger(length) || length < 0) throw new Error('HDC clearTextField length must be a non-negative safe integer');
+        if (0 === length) return;
+        const maxKeysPerCall = 3;
+        const backspaceKeyCode = '2055';
         const cmds = [];
         let remaining = length;
         while(remaining > 0){
-            const n = Math.min(MAX_KEYS_PER_CALL, remaining);
-            const codes = Array(n).fill('2055').join(' ');
+            const n = Math.min(maxKeysPerCall, remaining);
+            const codes = Array(n).fill(backspaceKeyCode).join(' ');
             cmds.push(`uitest uiInput keyEvent ${codes}`);
             remaining -= n;
         }
-        await this.shell(cmds.join(';'));
+        const output = await this.shell(cmds.join(';'));
+        this.assertUiInputSucceeded('clearTextField', output);
     }
     async startAbility(bundleName, abilityName) {
         const output = await this.shell(`aa start -a ${abilityName} -b ${bundleName}`);
@@ -258,6 +281,96 @@ class HdcClient {
         this.timeout = options.timeout ?? 60000;
     }
 }
+const namedHarmonyKeyCodeMap = {
+    Enter: '2054',
+    Backspace: '2055',
+    Tab: '2049',
+    Escape: '2070',
+    Home: 'Home',
+    ArrowUp: '2012',
+    ArrowDown: '2013',
+    ArrowLeft: '2014',
+    ArrowRight: '2015',
+    Space: '2050',
+    Delete: '2071',
+    Alt: '2045',
+    Shift: '2047',
+    Control: '2072',
+    Meta: '2076',
+    Back: 'Back',
+    Power: 'Power'
+};
+const keyNameAliasMap = new Map([
+    [
+        'return',
+        'Enter'
+    ],
+    [
+        'esc',
+        'Escape'
+    ],
+    [
+        'up',
+        'ArrowUp'
+    ],
+    [
+        'down',
+        'ArrowDown'
+    ],
+    [
+        'left',
+        'ArrowLeft'
+    ],
+    [
+        'right',
+        'ArrowRight'
+    ],
+    [
+        'ctrl',
+        'Control'
+    ]
+]);
+const caseInsensitiveNamedKeyCodeMap = new Map(Object.entries(namedHarmonyKeyCodeMap).map(([key, code])=>[
+        key.toLowerCase(),
+        code
+    ]));
+function numericKeyCode(value) {
+    return String(value);
+}
+function resolveSingleHarmonyKeyCodes(keyName) {
+    const trimmedKeyName = keyName.trim();
+    if (!trimmedKeyName) {
+        if (0 === keyName.length) throw new Error('Unsupported HarmonyOS key: empty key name');
+        throw unsupportedKeyboardPressKey(keyName);
+    }
+    const alias = keyNameAliasMap.get(trimmedKeyName.toLowerCase());
+    const normalizedKeyName = alias ?? trimmedKeyName;
+    if (/^[0-9]$/.test(normalizedKeyName)) return [
+        numericKeyCode(2000 + Number(normalizedKeyName))
+    ];
+    const letterKeyMatch = normalizedKeyName.match(/^[a-z]$/i);
+    if (letterKeyMatch) {
+        const alphabetIndex = letterKeyMatch[0].toUpperCase().charCodeAt(0) - 65;
+        return [
+            numericKeyCode(2017 + alphabetIndex)
+        ];
+    }
+    const namedCode = caseInsensitiveNamedKeyCodeMap.get(normalizedKeyName.toLowerCase());
+    if (namedCode) return [
+        namedCode
+    ];
+    throw unsupportedKeyboardPressKey(keyName);
+}
+function unsupportedKeyboardPressKey(keyName) {
+    return new Error(`Unsupported HarmonyOS keyboardPress key: ${JSON.stringify(keyName)}. Use typeText() for text input, or pass a supported key name such as "Enter", "A", or "1".`);
+}
+function resolveHarmonyKeyCodes(keyName) {
+    const trimmedKeyName = keyName.trim();
+    if (!trimmedKeyName && ' ' !== keyName) return resolveSingleHarmonyKeyCodes(keyName);
+    if ('+' === trimmedKeyName) return resolveSingleHarmonyKeyCodes(keyName);
+    if (trimmedKeyName.includes('+')) throw new Error(`HarmonyOS keyboardPress does not support key combinations: ${JSON.stringify(keyName)}`);
+    return resolveSingleHarmonyKeyCodes(keyName);
+}
 function device_define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -316,37 +429,6 @@ function pickFieldByPoint(fields, point) {
 function pickLongestField(fields) {
     return fields.reduce((a, b)=>b.text.length > a.text.length ? b : a);
 }
-const harmonyKeyCodeMap = {
-    Enter: '2054',
-    Backspace: '2055',
-    Tab: '2049',
-    Escape: '2070',
-    Home: 'Home',
-    ArrowUp: '2012',
-    ArrowDown: '2013',
-    ArrowLeft: '2014',
-    ArrowRight: '2015',
-    Space: '2050',
-    Delete: '2071'
-};
-const keyNameAliasMap = {
-    enter: 'Enter',
-    backspace: 'Backspace',
-    tab: 'Tab',
-    escape: 'Escape',
-    esc: 'Escape',
-    home: 'Home',
-    space: 'Space',
-    delete: 'Delete',
-    arrowup: 'ArrowUp',
-    arrowdown: 'ArrowDown',
-    arrowleft: 'ArrowLeft',
-    arrowright: 'ArrowRight',
-    up: 'ArrowUp',
-    down: 'ArrowDown',
-    left: 'ArrowLeft',
-    right: 'ArrowRight'
-};
 class device_HarmonyDevice {
     actionSpace() {
         const mobileActionContext = {
@@ -590,10 +672,9 @@ class device_HarmonyDevice {
         }
     }
     async pressKey(key) {
-        const normalizedKey = keyNameAliasMap[key.toLowerCase()] ?? key;
-        const harmonyKey = harmonyKeyCodeMap[normalizedKey] ?? key;
+        const keyCodes = resolveHarmonyKeyCodes(key);
         const hdc = await this.getHdc();
-        await hdc.keyEvent(harmonyKey);
+        await hdc.keyEvent(...keyCodes);
     }
     async scroll(deltaX, deltaY, speed) {
         if (0 === deltaX && 0 === deltaY) throw new Error('Scroll distance cannot be zero in both directions');
@@ -748,13 +829,13 @@ class device_HarmonyDevice {
     }
     async recentApps() {
         const hdc = await this.getHdc();
-        await hdc.keyEvent('RecentApps');
+        await hdc.keyEvent('10011');
     }
     async hideKeyboard(options) {
         const hdc = await this.getHdc();
         const keyboardDismissStrategy = options?.keyboardDismissStrategy ?? this.options?.keyboardDismissStrategy ?? 'esc-first';
-        const key = 'back-first' === keyboardDismissStrategy ? 'Back' : harmonyKeyCodeMap.Escape;
-        await hdc.keyEvent(key);
+        if ('back-first' === keyboardDismissStrategy) return void await hdc.keyEvent('Back');
+        await hdc.keyEvent(...resolveHarmonyKeyCodes('Escape'));
     }
     async getDeviceLocalTimeString(format = 'YYYY-MM-DD HH:mm:ss') {
         const hdc = await this.getHdc();

package/dist/es/cli.mjs

@@ -58,6 +58,23 @@ function _define_property(obj, key, value) {
 }
 const execFileAsync = promisify(execFile);
 const debugHdc = getDebug('harmony:hdc');
+const supportedStringKeyEvents = new Set([
+    'Back',
+    'Home',
+    'Power'
+]);
+const numericKeyEventPattern = /^\d+$/;
+const uiInputErrorPattern = /(?:(?:Invalid parameters|Missing parameter|Too many parameters)\.?|Please confirm that the coordinate values are correct\.?)/i;
+const minUiInputSpeed = 200;
+const maxUiInputSpeed = 40000;
+function roundUiCoordinate(value, name) {
+    if (!Number.isFinite(value) || value < 0) throw new Error(`HDC ${name} coordinate must be a non-negative finite number`);
+    return Math.round(value);
+}
+function roundUiInputSpeed(value, operation) {
+    if (!Number.isFinite(value) || value < minUiInputSpeed || value > maxUiInputSpeed) throw new Error(`HDC ${operation} speed must be a finite number between ${minUiInputSpeed} and ${maxUiInputSpeed}`);
+    return Math.round(value);
+}
 function resolveHdcPath(hdcPath) {
     if (hdcPath) return hdcPath;
     if (process.env.HDC_HOME) {
@@ -119,6 +136,26 @@ class HdcClient {
     async shell(command) {
         return this.exec('shell', command);
     }
+    assertUiInputSucceeded(operation, output, detail) {
+        const errorMatch = output.match(uiInputErrorPattern);
+        if (!errorMatch) return;
+        const detailText = detail ? ` for ${detail}` : '';
+        throw new Error(`HDC uiInput ${operation} failed${detailText}: ${errorMatch[0]}`);
+    }
+    async runUiInput(operation, args, detail) {
+        const output = await this.shell(`uitest uiInput ${operation} ${args}`);
+        this.assertUiInputSucceeded(operation, output, detail);
+    }
+    buildPointerMovementArgs(operation, fromX, fromY, toX, toY, speed) {
+        const args = [
+            roundUiCoordinate(fromX, 'fromX'),
+            roundUiCoordinate(fromY, 'fromY'),
+            roundUiCoordinate(toX, 'toX'),
+            roundUiCoordinate(toY, 'toY')
+        ];
+        if (void 0 !== speed) args.push(roundUiInputSpeed(speed, operation));
+        return args.join(' ');
+    }
     async fileSend(localPath, remotePath) {
         await this.exec('file', 'send', localPath, remotePath);
     }
@@ -136,63 +173,49 @@ class HdcClient {
         return output.slice(jsonStart);
     }
     async click(x, y) {
-        await this.shell(`uitest uiInput click ${Math.round(x)} ${Math.round(y)}`);
+        await this.runUiInput('click', `${roundUiCoordinate(x, 'x')} ${roundUiCoordinate(y, 'y')}`);
     }
     async doubleClick(x, y) {
-        await this.shell(`uitest uiInput doubleClick ${Math.round(x)} ${Math.round(y)}`);
+        await this.runUiInput('doubleClick', `${roundUiCoordinate(x, 'x')} ${roundUiCoordinate(y, 'y')}`);
     }
     async longClick(x, y) {
-        await this.shell(`uitest uiInput longClick ${Math.round(x)} ${Math.round(y)}`);
+        await this.runUiInput('longClick', `${roundUiCoordinate(x, 'x')} ${roundUiCoordinate(y, 'y')}`);
     }
     async swipe(fromX, fromY, toX, toY, speed) {
-        const args = [
-            Math.round(fromX),
-            Math.round(fromY),
-            Math.round(toX),
-            Math.round(toY)
-        ];
-        if (void 0 !== speed) args.push(Math.round(speed));
-        await this.shell(`uitest uiInput swipe ${args.join(' ')}`);
+        await this.runUiInput('swipe', this.buildPointerMovementArgs('swipe', fromX, fromY, toX, toY, speed));
     }
     async fling(fromX, fromY, toX, toY, speed) {
-        const args = [
-            Math.round(fromX),
-            Math.round(fromY),
-            Math.round(toX),
-            Math.round(toY)
-        ];
-        if (void 0 !== speed) args.push(Math.round(speed));
-        await this.shell(`uitest uiInput fling ${args.join(' ')}`);
+        await this.runUiInput('fling', this.buildPointerMovementArgs('fling', fromX, fromY, toX, toY, speed));
     }
     async drag(fromX, fromY, toX, toY, speed) {
-        const args = [
-            Math.round(fromX),
-            Math.round(fromY),
-            Math.round(toX),
-            Math.round(toY)
-        ];
-        if (void 0 !== speed) args.push(Math.round(speed));
-        await this.shell(`uitest uiInput drag ${args.join(' ')}`);
+        await this.runUiInput('drag', this.buildPointerMovementArgs('drag', fromX, fromY, toX, toY, speed));
     }
     async inputText(x, y, text) {
         const escapedText = text.replace(/'/g, "'\\''");
-        await this.shell(`uitest uiInput inputText ${Math.round(x)} ${Math.round(y)} '${escapedText}'`);
+        await this.runUiInput('inputText', `${roundUiCoordinate(x, 'x')} ${roundUiCoordinate(y, 'y')} '${escapedText}'`);
     }
     async keyEvent(...keys) {
-        await this.shell(`uitest uiInput keyEvent ${keys.join(' ')}`);
+        if (keys.length < 1 || keys.length > 3) throw new Error('HDC keyEvent requires between 1 and 3 keys');
+        if (keys.length > 1 && keys.some((key)=>supportedStringKeyEvents.has(key))) throw new Error('HDC system key events cannot be combined');
+        for (const key of keys)if (!supportedStringKeyEvents.has(key) && !numericKeyEventPattern.test(key)) throw new Error(`Invalid HDC key event: ${key}`);
+        const joinedKeys = keys.join(' ');
+        await this.runUiInput('keyEvent', joinedKeys, joinedKeys);
     }
     async clearTextField(length = 100) {
-        if (length <= 0) return;
-        const MAX_KEYS_PER_CALL = 3;
+        if (!Number.isSafeInteger(length) || length < 0) throw new Error('HDC clearTextField length must be a non-negative safe integer');
+        if (0 === length) return;
+        const maxKeysPerCall = 3;
+        const backspaceKeyCode = '2055';
         const cmds = [];
         let remaining = length;
         while(remaining > 0){
-            const n = Math.min(MAX_KEYS_PER_CALL, remaining);
-            const codes = Array(n).fill('2055').join(' ');
+            const n = Math.min(maxKeysPerCall, remaining);
+            const codes = Array(n).fill(backspaceKeyCode).join(' ');
             cmds.push(`uitest uiInput keyEvent ${codes}`);
             remaining -= n;
         }
-        await this.shell(cmds.join(';'));
+        const output = await this.shell(cmds.join(';'));
+        this.assertUiInputSucceeded('clearTextField', output);
     }
     async startAbility(bundleName, abilityName) {
         const output = await this.shell(`aa start -a ${abilityName} -b ${bundleName}`);
@@ -256,6 +279,96 @@ class HdcClient {
         this.timeout = options.timeout ?? 60000;
     }
 }
+const namedHarmonyKeyCodeMap = {
+    Enter: '2054',
+    Backspace: '2055',
+    Tab: '2049',
+    Escape: '2070',
+    Home: 'Home',
+    ArrowUp: '2012',
+    ArrowDown: '2013',
+    ArrowLeft: '2014',
+    ArrowRight: '2015',
+    Space: '2050',
+    Delete: '2071',
+    Alt: '2045',
+    Shift: '2047',
+    Control: '2072',
+    Meta: '2076',
+    Back: 'Back',
+    Power: 'Power'
+};
+const keyNameAliasMap = new Map([
+    [
+        'return',
+        'Enter'
+    ],
+    [
+        'esc',
+        'Escape'
+    ],
+    [
+        'up',
+        'ArrowUp'
+    ],
+    [
+        'down',
+        'ArrowDown'
+    ],
+    [
+        'left',
+        'ArrowLeft'
+    ],
+    [
+        'right',
+        'ArrowRight'
+    ],
+    [
+        'ctrl',
+        'Control'
+    ]
+]);
+const caseInsensitiveNamedKeyCodeMap = new Map(Object.entries(namedHarmonyKeyCodeMap).map(([key, code])=>[
+        key.toLowerCase(),
+        code
+    ]));
+function numericKeyCode(value) {
+    return String(value);
+}
+function resolveSingleHarmonyKeyCodes(keyName) {
+    const trimmedKeyName = keyName.trim();
+    if (!trimmedKeyName) {
+        if (0 === keyName.length) throw new Error('Unsupported HarmonyOS key: empty key name');
+        throw unsupportedKeyboardPressKey(keyName);
+    }
+    const alias = keyNameAliasMap.get(trimmedKeyName.toLowerCase());
+    const normalizedKeyName = alias ?? trimmedKeyName;
+    if (/^[0-9]$/.test(normalizedKeyName)) return [
+        numericKeyCode(2000 + Number(normalizedKeyName))
+    ];
+    const letterKeyMatch = normalizedKeyName.match(/^[a-z]$/i);
+    if (letterKeyMatch) {
+        const alphabetIndex = letterKeyMatch[0].toUpperCase().charCodeAt(0) - 65;
+        return [
+            numericKeyCode(2017 + alphabetIndex)
+        ];
+    }
+    const namedCode = caseInsensitiveNamedKeyCodeMap.get(normalizedKeyName.toLowerCase());
+    if (namedCode) return [
+        namedCode
+    ];
+    throw unsupportedKeyboardPressKey(keyName);
+}
+function unsupportedKeyboardPressKey(keyName) {
+    return new Error(`Unsupported HarmonyOS keyboardPress key: ${JSON.stringify(keyName)}. Use typeText() for text input, or pass a supported key name such as "Enter", "A", or "1".`);
+}
+function resolveHarmonyKeyCodes(keyName) {
+    const trimmedKeyName = keyName.trim();
+    if (!trimmedKeyName && ' ' !== keyName) return resolveSingleHarmonyKeyCodes(keyName);
+    if ('+' === trimmedKeyName) return resolveSingleHarmonyKeyCodes(keyName);
+    if (trimmedKeyName.includes('+')) throw new Error(`HarmonyOS keyboardPress does not support key combinations: ${JSON.stringify(keyName)}`);
+    return resolveSingleHarmonyKeyCodes(keyName);
+}
 function device_define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -314,37 +427,6 @@ function pickFieldByPoint(fields, point) {
 function pickLongestField(fields) {
     return fields.reduce((a, b)=>b.text.length > a.text.length ? b : a);
 }
-const harmonyKeyCodeMap = {
-    Enter: '2054',
-    Backspace: '2055',
-    Tab: '2049',
-    Escape: '2070',
-    Home: 'Home',
-    ArrowUp: '2012',
-    ArrowDown: '2013',
-    ArrowLeft: '2014',
-    ArrowRight: '2015',
-    Space: '2050',
-    Delete: '2071'
-};
-const keyNameAliasMap = {
-    enter: 'Enter',
-    backspace: 'Backspace',
-    tab: 'Tab',
-    escape: 'Escape',
-    esc: 'Escape',
-    home: 'Home',
-    space: 'Space',
-    delete: 'Delete',
-    arrowup: 'ArrowUp',
-    arrowdown: 'ArrowDown',
-    arrowleft: 'ArrowLeft',
-    arrowright: 'ArrowRight',
-    up: 'ArrowUp',
-    down: 'ArrowDown',
-    left: 'ArrowLeft',
-    right: 'ArrowRight'
-};
 class HarmonyDevice {
     actionSpace() {
         const mobileActionContext = {
@@ -588,10 +670,9 @@ class HarmonyDevice {
         }
     }
     async pressKey(key) {
-        const normalizedKey = keyNameAliasMap[key.toLowerCase()] ?? key;
-        const harmonyKey = harmonyKeyCodeMap[normalizedKey] ?? key;
+        const keyCodes = resolveHarmonyKeyCodes(key);
         const hdc = await this.getHdc();
-        await hdc.keyEvent(harmonyKey);
+        await hdc.keyEvent(...keyCodes);
     }
     async scroll(deltaX, deltaY, speed) {
         if (0 === deltaX && 0 === deltaY) throw new Error('Scroll distance cannot be zero in both directions');
@@ -746,13 +827,13 @@ class HarmonyDevice {
     }
     async recentApps() {
         const hdc = await this.getHdc();
-        await hdc.keyEvent('RecentApps');
+        await hdc.keyEvent('10011');
     }
     async hideKeyboard(options) {
         const hdc = await this.getHdc();
         const keyboardDismissStrategy = options?.keyboardDismissStrategy ?? this.options?.keyboardDismissStrategy ?? 'esc-first';
-        const key = 'back-first' === keyboardDismissStrategy ? 'Back' : harmonyKeyCodeMap.Escape;
-        await hdc.keyEvent(key);
+        if ('back-first' === keyboardDismissStrategy) return void await hdc.keyEvent('Back');
+        await hdc.keyEvent(...resolveHarmonyKeyCodes('Escape'));
     }
     async getDeviceLocalTimeString(format = 'YYYY-MM-DD HH:mm:ss') {
         const hdc = await this.getHdc();
@@ -1093,7 +1174,7 @@ class HarmonyMidsceneTools extends BaseMidsceneTools {
 const tools = new HarmonyMidsceneTools();
 runToolsCLI(tools, 'midscene-harmony', {
     stripPrefix: 'harmony_',
-    version: "1.10.11",
+    version: "1.10.12-beta-20260812055946.0",
     extraCommands: createReportCliCommands()
 }).catch((e)=>{
     process.exit(reportCLIError(e));