@onekeyfe/hardware-cli 1.2.0-alpha.13 → 1.2.0-alpha.130

package/dist/deviceSelection.d.ts

@@ -0,0 +1,3 @@
+export declare function selectSearchDevice<T extends {
+    connectId?: string | null;
+}>(devices: T[], preferredConnectId?: string): T | undefined;

package/dist/deviceSelection.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectSearchDevice = void 0;
+function selectSearchDevice(devices, preferredConnectId) {
+    if (preferredConnectId) {
+        return (devices.find(device => device.connectId === preferredConnectId) ??
+            { connectId: preferredConnectId });
+    }
+    return devices[0];
+}
+exports.selectSearchDevice = selectSearchDevice;

package/dist/deviceStateCommands.d.ts

@@ -0,0 +1,19 @@
+import type { CoreApi, DeviceStateScope } from '@onekeyfe/hd-core';
+type DeviceStateSdk = Pick<CoreApi, 'searchDevices' | 'getDeviceState' | 'getFeatures'>;
+/**
+ * Unified state entry for the new CLI. Resolve the user-facing connectId through
+ * discovery so V1 serial IDs map to the process-local USB path.
+ */
+export declare const getCanonicalDeviceState: (sdk: DeviceStateSdk, connectId: string | undefined, scope: DeviceStateScope) => Promise<import("@onekeyfe/hd-core").Unsuccessful | {
+    success: true;
+    payload: import("@onekeyfe/hd-core").DeviceState;
+}>;
+/**
+ * Legacy CLI only: retain getFeatures for V1 and reuse the discovery projection for V2.
+ * Public SDK.getFeatures remains V1-only.
+ */
+export declare const getCompatibleFeatures: (sdk: DeviceStateSdk, connectId?: string) => Promise<import("@onekeyfe/hd-core").Unsuccessful | {
+    success: true;
+    payload: import("@onekeyfe/hd-core").Features;
+}>;
+export {};

package/dist/deviceStateCommands.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCompatibleFeatures = exports.getCanonicalDeviceState = void 0;
+const createDeviceNotFoundResult = (connectId) => ({
+    success: false,
+    payload: {
+        code: 'DEVICE_NOT_FOUND',
+        error: connectId ? `Device not found: ${connectId}` : 'No device found',
+    },
+});
+const resolveSearchDevice = async (sdk, connectId) => {
+    const searchResult = await sdk.searchDevices();
+    if (!searchResult.success)
+        return searchResult;
+    const devices = searchResult.payload;
+    const device = connectId ? devices.find(item => item.connectId === connectId) : devices[0];
+    if (!device?.connectId)
+        return createDeviceNotFoundResult(connectId);
+    return { success: true, payload: device };
+};
+/**
+ * Unified state entry for the new CLI. Resolve the user-facing connectId through
+ * discovery so V1 serial IDs map to the process-local USB path.
+ */
+const getCanonicalDeviceState = async (sdk, connectId, scope) => {
+    const deviceResult = await resolveSearchDevice(sdk, connectId);
+    if (!deviceResult.success)
+        return deviceResult;
+    if (scope === 'runtime' && deviceResult.payload.state) {
+        return { success: true, payload: deviceResult.payload.state };
+    }
+    const resolvedConnectId = deviceResult.payload.connectId ?? undefined;
+    if (!resolvedConnectId)
+        return createDeviceNotFoundResult();
+    return sdk.getDeviceState(resolvedConnectId, { scope });
+};
+exports.getCanonicalDeviceState = getCanonicalDeviceState;
+/**
+ * Legacy CLI only: retain getFeatures for V1 and reuse the discovery projection for V2.
+ * Public SDK.getFeatures remains V1-only.
+ */
+const getCompatibleFeatures = async (sdk, connectId) => {
+    const deviceResult = await resolveSearchDevice(sdk, connectId);
+    if (!deviceResult.success)
+        return deviceResult;
+    const device = deviceResult.payload;
+    const protocol = device.state?.protocol ?? device.features?.protocol;
+    if (protocol === 'V2') {
+        if (!device.features) {
+            return {
+                success: false,
+                payload: {
+                    code: 'DEVICE_FEATURES_UNAVAILABLE',
+                    error: 'Protocol V2 compatibility features are unavailable',
+                },
+            };
+        }
+        return { success: true, payload: device.features };
+    }
+    return sdk.getFeatures(device.connectId ?? '');
+};
+exports.getCompatibleFeatures = getCompatibleFeatures;

package/dist/pinentry.d.ts

@@ -20,5 +20,6 @@ export declare function findPinentry(): string | null;
 export interface PinentryResult {
     value: string;
     passphraseOnDevice: boolean;
+    attachPinOnDevice?: boolean;
 }
 export declare function promptPassphraseViaPinentry(): Promise<PinentryResult>;

package/dist/sdk.d.ts

@@ -5,10 +5,11 @@
  * Passphrase flow aligns with app-monorepo CLI:
  *   - Standard wallet: --use-empty-passphrase, auto-respond
  *   - Hidden wallet: interactive 1/2/3 selection (standard / pinentry / on-device)
- *   - Session caching: passphraseState + sessionId stored in OS keychain,
- *     preloaded via preloadSessionCache on next invocation
+ *   - Legacy session caching: existing OS keychain entries may still be preloaded,
+ *     but public SDK responses never expose new device session ids
  */
 import HardwareSDK from '@onekeyfe/hd-common-connect-sdk';
+import type { PinentryResult } from './pinentry';
 export interface SDKOptions {
     connectId?: string;
     passphraseState?: string;
@@ -16,6 +17,13 @@ export interface SDKOptions {
     debug?: boolean;
     transport?: 'usb' | 'ble';
 }
+/**
+ * Prompt user to select wallet type (aligns with app-monorepo flow):
+ *   1. Standard wallet (no passphrase)
+ *   2. Hidden wallet — enter passphrase via pinentry (secure OS dialog)
+ *   3. Hidden wallet — enter passphrase on device screen
+ */
+export declare function resolvePassphraseByChoice(choice: '1' | '2' | '3' | '4'): Promise<PinentryResult>;
 export declare function createSDK(opts: SDKOptions): Promise<typeof HardwareSDK>;
 /**
  * Release the SDK and clear the singleton. Must be called before the CLI

package/dist/sdk.js

@@ -6,8 +6,8 @@
  * Passphrase flow aligns with app-monorepo CLI:
  *   - Standard wallet: --use-empty-passphrase, auto-respond
  *   - Hidden wallet: interactive 1/2/3 selection (standard / pinentry / on-device)
- *   - Session caching: passphraseState + sessionId stored in OS keychain,
- *     preloaded via preloadSessionCache on next invocation
+ *   - Legacy session caching: existing OS keychain entries may still be preloaded,
+ *     but public SDK responses never expose new device session ids
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.disposeSDK = exports.createSDK = void 0;
+exports.disposeSDK = exports.createSDK = exports.resolvePassphraseByChoice = void 0;
 const readline = __importStar(require("node:readline"));
 const hd_common_connect_sdk_1 = __importDefault(require("@onekeyfe/hd-common-connect-sdk"));
 const hd_core_1 = require("@onekeyfe/hd-core");
@@ -76,8 +76,15 @@ function resolvePassphraseByChoice(choice) {
         return Promise.resolve({ value: '', passphraseOnDevice: false });
     if (choice === '2')
         return (0, pinentry_1.promptPassphraseViaPinentry)();
+    if (choice === '4')
+        return Promise.resolve({
+            value: '',
+            passphraseOnDevice: false,
+            attachPinOnDevice: true,
+        });
     return Promise.resolve({ value: '', passphraseOnDevice: true });
 }
+exports.resolvePassphraseByChoice = resolvePassphraseByChoice;
 function promptPassphraseMode() {
     if (!process.stdin.isTTY) {
         return Promise.resolve({ value: '', passphraseOnDevice: true });
@@ -94,16 +101,17 @@ function promptPassphraseMode() {
                 '  1. Standard wallet (no passphrase)',
                 '  2. Hidden wallet — enter passphrase on this computer (pinentry)',
                 '  3. Hidden wallet — enter passphrase on device screen',
+                '  4. Attach PIN wallet — enter Attach PIN on device screen',
                 '',
             ].join('\n'));
             rl.question('Enter selection [1/2/3]: ', answer => {
                 const n = answer.trim();
-                if (n === '1' || n === '2' || n === '3') {
+                if (n === '1' || n === '2' || n === '3' || n === '4') {
                     rl.close();
                     resolvePassphraseByChoice(n).then(resolve);
                     return;
                 }
-                process.stderr.write('Invalid selection. Enter 1, 2, or 3.\n');
+                process.stderr.write('Invalid selection. Enter 1, 2, 3, or 4.\n');
                 prompt();
             });
         };
@@ -147,6 +155,7 @@ function registerEventHandlers(sdk) {
                     payload: {
                         value: result.value,
                         passphraseOnDevice: result.passphraseOnDevice,
+                        attachPinOnDevice: result.attachPinOnDevice,
                         save: false,
                     },
                 });
@@ -168,12 +177,12 @@ function registerEventHandlers(sdk) {
             process.stderr.write('[onekey-hw] Please confirm the action on your device...\n');
         }
     });
-    sdk.on(hd_core_1.DEVICE.CONNECT, (device) => {
+    sdk.on(hd_core_1.DEVICE.CONNECT, ({ device }) => {
         const name = device?.label || device?.name;
         if (name)
             process.stderr.write(`[onekey-hw] Device connected: ${name}\n`);
     });
-    sdk.on(hd_core_1.DEVICE.DISCONNECT, (device) => {
+    sdk.on(hd_core_1.DEVICE.DISCONNECT, ({ device }) => {
         const name = device?.label || device?.name;
         if (name)
             process.stderr.write(`[onekey-hw] Device disconnected: ${name}\n`);
@@ -222,7 +231,7 @@ async function disposeSDK() {
         return;
     try {
         const sdk = await sdkReadyPromise;
-        sdk.dispose();
+        await Promise.resolve(sdk.dispose());
     }
     catch {
         // ignore errors during cleanup

package/dist/session.d.ts

@@ -1,21 +1,14 @@
 /**
  * Passphrase session management for hd-cli.
  *
- * Aligns with app-monorepo's CLI pattern:
- *   Login:   getPassphraseState → passphraseState + sessionId → keychain
- *   Command: keychain → preloadSessionCache → SDK call (no passphrase prompt)
- *   Stale:   error 112 → clear keychain → re-prompt → retry
- *   Logout:  keychain delete
+ * Existing keychain entries remain readable for compatibility, but the public
+ * SDK no longer exposes new device session ids for persistence.
  */
 /**
  * Load passphraseState + sessionId from keychain and call preloadSessionCache.
  * Non-fatal: returns the loaded passphraseState or undefined.
  */
 export declare function preloadSessionFromKeychain(deviceId: string): Promise<string | undefined>;
-/**
- * Save passphraseState + sessionId to keychain for next CLI invocation.
- */
-export declare function saveSessionToKeychain(deviceId: string, passphraseState: string, sessionId: string): Promise<void>;
 /**
  * Clear cached session from keychain.
  */

package/dist/session.js

@@ -2,14 +2,11 @@
 /**
  * Passphrase session management for hd-cli.
  *
- * Aligns with app-monorepo's CLI pattern:
- *   Login:   getPassphraseState → passphraseState + sessionId → keychain
- *   Command: keychain → preloadSessionCache → SDK call (no passphrase prompt)
- *   Stale:   error 112 → clear keychain → re-prompt → retry
- *   Logout:  keychain delete
+ * Existing keychain entries remain readable for compatibility, but the public
+ * SDK no longer exposes new device session ids for persistence.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.clearSessionFromKeychain = exports.saveSessionToKeychain = exports.preloadSessionFromKeychain = void 0;
+exports.clearSessionFromKeychain = exports.preloadSessionFromKeychain = void 0;
 const hd_core_1 = require("@onekeyfe/hd-core");
 const storage_1 = require("./storage");
 // Keychain key format: scoped by deviceId for multi-device support
@@ -50,22 +47,6 @@ async function preloadSessionFromKeychain(deviceId) {
     return undefined;
 }
 exports.preloadSessionFromKeychain = preloadSessionFromKeychain;
-/**
- * Save passphraseState + sessionId to keychain for next CLI invocation.
- */
-async function saveSessionToKeychain(deviceId, passphraseState, sessionId) {
-    try {
-        const storage = getStorage();
-        await Promise.all([
-            storage.set(psKey(deviceId), Buffer.from(passphraseState, 'utf-8')),
-            storage.set(sidKey(deviceId), Buffer.from(sessionId, 'utf-8')),
-        ]);
-    }
-    catch {
-        // Non-fatal — session still works in-memory for this invocation
-    }
-}
-exports.saveSessionToKeychain = saveSessionToKeychain;
 /**
  * Clear cached session from keychain.
  */

package/dist/transports/nobleBlePlugin.js

@@ -3,13 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createNobleBlePlugin = void 0;
 const hd_shared_1 = require("@onekeyfe/hd-shared");
 const ONEKEY_SERVICE_UUIDS = [hd_shared_1.ONEKEY_SERVICE_UUID];
-const PRO2_ADVERTISEMENT_SERVICE_UUID_KEYS = new Set(['fffd']);
-const NORMALIZED_WRITE_UUID = '0002';
-const NORMALIZED_NOTIFY_UUID = '0003';
-const NORMALIZED_ONEKEY_SERVICE_UUIDS = new Set([
-    ...ONEKEY_SERVICE_UUIDS.map(uuid => getBleUuidKey(uuid)),
-    '0001',
-]);
+const ONEKEY_SERVICE_UUID_ALIASES = (0, hd_shared_1.createKnownBleUuidAliases)(hd_shared_1.ONEKEY_SERVICE_UUID);
+const ONEKEY_WRITE_UUID_ALIASES = (0, hd_shared_1.createKnownBleUuidAliases)(hd_shared_1.ONEKEY_WRITE_CHARACTERISTIC_UUID);
+const ONEKEY_NOTIFY_UUID_ALIASES = (0, hd_shared_1.createKnownBleUuidAliases)(hd_shared_1.ONEKEY_NOTIFY_CHARACTERISTIC_UUID);
 const BLUETOOTH_INIT_TIMEOUT = 10000;
 const DEVICE_SCAN_TIMEOUT = 8000;
 const CONNECTION_TIMEOUT = 8000;
@@ -24,24 +20,14 @@ const connectedDevices = new Map();
 const deviceCharacteristics = new Map();
 const notificationStates = new Map();
 const notificationGenerations = new Map();
-function getBleUuidKey(uuid) {
-    const normalized = (uuid ?? '').replace(/-/g, '').toLowerCase();
-    return normalized.length >= 8 ? normalized.substring(4, 8) : normalized;
-}
-function isGenericBleService(uuid) {
-    return ['1800', '1801', '180a', '180f'].includes(getBleUuidKey(uuid));
-}
-function hasOneKeyAdvertisementService(peripheral) {
-    const serviceUuids = peripheral.advertisement?.serviceUuids ?? [];
-    return serviceUuids.some(uuid => {
-        const uuidKey = getBleUuidKey(uuid);
-        return (NORMALIZED_ONEKEY_SERVICE_UUIDS.has(uuidKey) ||
-            PRO2_ADVERTISEMENT_SERVICE_UUID_KEYS.has(uuidKey));
-    });
-}
 function isOneKeyPeripheral(peripheral) {
-    const deviceName = peripheral.advertisement?.localName || null;
-    return (0, hd_shared_1.isOnekeyDevice)(deviceName, peripheral.id) || hasOneKeyAdvertisementService(peripheral);
+    const serviceUuids = peripheral.advertisement?.serviceUuids;
+    return ((0, hd_shared_1.hasOnekeyCommunicationService)(serviceUuids) &&
+        (0, hd_shared_1.isOnekeyBluetoothDevice)({
+            id: peripheral.id,
+            localName: peripheral.advertisement?.localName,
+            serviceUuids,
+        }));
 }
 function enqueueNotification(deviceId, generation, data) {
     const state = notificationStates.get(deviceId);
@@ -171,7 +157,7 @@ async function scanDevices(targetDeviceId) {
         const onDiscover = (peripheral) => {
             if (targetDeviceId && peripheral.id !== targetDeviceId)
                 return;
-            if (!targetDeviceId && !isOneKeyPeripheral(peripheral))
+            if (!isOneKeyPeripheral(peripheral))
                 return;
             discoveredDevices.set(peripheral.id, peripheral);
             found.set(peripheral.id, peripheral);
@@ -220,13 +206,7 @@ async function discoverCharacteristics(peripheral) {
             resolve(discoveredServices);
         });
     });
-    let service = services.find(s => NORMALIZED_ONEKEY_SERVICE_UUIDS.has(getBleUuidKey(s.uuid)));
-    if (!service) {
-        service =
-            services.find(s => PRO2_ADVERTISEMENT_SERVICE_UUID_KEYS.has(getBleUuidKey(s.uuid))) ||
-                services.find(s => !isGenericBleService(s.uuid)) ||
-                services[0];
-    }
+    const service = services.find(s => (0, hd_shared_1.matchesKnownBleUuid)(s.uuid, ONEKEY_SERVICE_UUID_ALIASES));
     if (!service) {
         throw hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.BleServiceNotFound, 'No BLE service found');
     }
@@ -243,11 +223,10 @@ async function discoverCharacteristics(peripheral) {
     let writeCharacteristic;
     let notifyCharacteristic;
     for (const characteristic of characteristics) {
-        const uuidKey = getBleUuidKey(characteristic.uuid);
-        if (uuidKey === NORMALIZED_WRITE_UUID) {
+        if ((0, hd_shared_1.matchesKnownBleUuid)(characteristic.uuid, ONEKEY_WRITE_UUID_ALIASES)) {
             writeCharacteristic = characteristic;
         }
-        else if (uuidKey === NORMALIZED_NOTIFY_UUID) {
+        else if ((0, hd_shared_1.matchesKnownBleUuid)(characteristic.uuid, ONEKEY_NOTIFY_UUID_ALIASES)) {
             notifyCharacteristic = characteristic;
         }
     }
@@ -335,30 +314,39 @@ function createNobleBlePlugin() {
                 throw hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.DeviceNotFound, `BLE device not found: ${uuid}`);
             }
             await connectPeripheral(peripheral);
-            const characteristics = await discoverCharacteristics(peripheral);
-            const notificationState = createNotificationState(uuid);
+            let characteristics;
             try {
+                characteristics = await discoverCharacteristics(peripheral);
+                const notificationState = createNotificationState(uuid);
                 await subscribeNotifications(uuid, notificationState.generation, characteristics.notify);
+                connectedDevices.set(uuid, peripheral);
+                deviceCharacteristics.set(uuid, characteristics);
             }
             catch (error) {
                 clearNotificationState(uuid, `BLE notification subscription failed: ${uuid}`);
+                if (characteristics) {
+                    characteristics.notify.removeAllListeners('data');
+                    await waitForNobleCleanup(callback => characteristics?.notify.unsubscribe(callback));
+                }
+                if (peripheral.state !== 'disconnected') {
+                    await waitForNobleCleanup(callback => peripheral?.disconnect(callback));
+                }
                 throw error;
             }
-            connectedDevices.set(uuid, peripheral);
-            deviceCharacteristics.set(uuid, characteristics);
         },
         async disconnect(uuid) {
             await disconnectDevice(uuid);
         },
-        async send(uuid, data) {
+        async send(uuid, data, options) {
             const characteristics = deviceCharacteristics.get(uuid);
             if (!characteristics) {
                 throw hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.BleCharacteristicNotFound, `BLE device is not connected: ${uuid}`);
             }
             const buffer = Buffer.from(data, 'hex');
+            const withoutResponse = options?.withoutResponse ?? true;
             for (let offset = 0; offset < buffer.length; offset += BLE_PACKET_SIZE) {
                 const chunk = buffer.subarray(offset, Math.min(offset + BLE_PACKET_SIZE, buffer.length));
-                await writeCharacteristic(characteristics.write, chunk, true);
+                await writeCharacteristic(characteristics.write, chunk, withoutResponse);
             }
         },
         async receive(uuid) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/hardware-cli",
-  "version": "1.2.0-alpha.13",
+  "version": "1.2.0-alpha.130",
   "description": "OneKey hardware wallet CLI for testing device communication",
   "author": "OneKey",
   "license": "Apache-2.0",
@@ -23,6 +23,7 @@
     "start": "node dist/cli.js",
     "search": "node dist/cli.js search",
     "get-features": "node dist/cli.js get-features",
+    "get-state": "node dist/cli.js get-state",
     "get-address": "node dist/cli.js get-address",
     "ping": "node dist/cli.js ping",
     "lint": "eslint .",
@@ -30,12 +31,12 @@
     "test": "jest"
   },
   "dependencies": {
-    "@onekeyfe/hd-common-connect-sdk": "1.2.0-alpha.13",
-    "@onekeyfe/hd-core": "1.2.0-alpha.13",
-    "@onekeyfe/hd-shared": "1.2.0-alpha.13",
-    "@onekeyfe/hd-transport-usb": "1.2.0-alpha.13",
+    "@onekeyfe/hd-common-connect-sdk": "1.2.0-alpha.130",
+    "@onekeyfe/hd-core": "1.2.0-alpha.130",
+    "@onekeyfe/hd-shared": "1.2.0-alpha.130",
+    "@onekeyfe/hd-transport-usb": "1.2.0-alpha.130",
     "@stoprocent/noble": "2.3.16",
     "commander": "^12.0.0"
   },
-  "gitHead": "a907a7ec140123107f6188b37550a7143f1e0d91"
+  "gitHead": "287003096bc4df3a5824f2bea77e50f7fdc20565"
 }

package/src/__tests__/cli-version.test.ts

@@ -0,0 +1,8 @@
+import packageJson from '../../package.json';
+import { program } from '../cli';
+
+describe('CLI 版本', () => {
+  test('与发布包 package.json 使用同一个版本来源', () => {
+    expect(program.version()).toBe(packageJson.version);
+  });
+});

package/src/__tests__/device-selection.test.ts

@@ -0,0 +1,29 @@
+import { selectSearchDevice } from '../deviceSelection';
+
+describe('selectSearchDevice', () => {
+  it('多设备环境优先选择显式 connectId 对应的设备', () => {
+    const devices = [
+      { connectId: 'first-device', name: 'Pro A9CA' },
+      { connectId: 'target-device', name: 'Pro2 6136' },
+    ];
+
+    expect(selectSearchDevice(devices, 'target-device')).toEqual(devices[1]);
+  });
+
+  it('未指定 connectId 时保持选择第一台设备的兼容行为', () => {
+    const devices = [
+      { connectId: 'first-device', name: 'Pro2 6136' },
+      { connectId: 'second-device', name: 'Pro2 C445' },
+    ];
+
+    expect(selectSearchDevice(devices)).toEqual(devices[0]);
+  });
+
+  it('显式 connectId 暂未出现在扫描结果时仍保留该目标', () => {
+    const devices = [{ connectId: 'other-device', name: 'Pro2 C445' }];
+
+    expect(selectSearchDevice(devices, 'target-device')).toEqual({
+      connectId: 'target-device',
+    });
+  });
+});

package/src/__tests__/device-state-commands.test.ts

@@ -0,0 +1,118 @@
+import { getCanonicalDeviceState, getCompatibleFeatures } from '../deviceStateCommands';
+
+const createSdkMock = () => ({
+  searchDevices: jest.fn(),
+  getDeviceState: jest.fn(),
+  getFeatures: jest.fn(),
+});
+
+describe('设备状态 CLI 兼容层', () => {
+  test('Protocol V2 直接返回 SDK 搜索结果中的兼容 features', async () => {
+    const sdk = createSdkMock();
+    const features = {
+      protocol: 'V2',
+      deviceType: 'pro2',
+      deviceId: 'device-id',
+    };
+    sdk.searchDevices.mockResolvedValue({
+      success: true,
+      payload: [
+        {
+          connectId: 'pro2-connect-id',
+          state: { protocol: 'V2' },
+          features,
+        },
+      ],
+    });
+
+    await expect(getCompatibleFeatures(sdk as never, 'pro2-connect-id')).resolves.toEqual({
+      success: true,
+      payload: features,
+    });
+    expect(sdk.getFeatures).not.toHaveBeenCalled();
+  });
+
+  test('Protocol V1 继续调用公共 getFeatures 保持旧行为', async () => {
+    const sdk = createSdkMock();
+    const response = {
+      success: true,
+      payload: { protocol: 'V1', label: 'Classic' },
+    };
+    sdk.searchDevices.mockResolvedValue({
+      success: true,
+      payload: [
+        {
+          connectId: 'classic-connect-id',
+          state: { protocol: 'V1' },
+        },
+      ],
+    });
+    sdk.getFeatures.mockResolvedValue(response);
+
+    await expect(getCompatibleFeatures(sdk as never, 'classic-connect-id')).resolves.toBe(response);
+    expect(sdk.getFeatures).toHaveBeenCalledWith('classic-connect-id');
+  });
+
+  test('未显式指定设备时选择搜索结果中的第一台设备', async () => {
+    const sdk = createSdkMock();
+    const response = { success: true, payload: { protocol: 'V1' } };
+    sdk.searchDevices.mockResolvedValue({
+      success: true,
+      payload: [{ connectId: 'first-device', state: { protocol: 'V1' } }],
+    });
+    sdk.getFeatures.mockResolvedValue(response);
+
+    await expect(getCompatibleFeatures(sdk as never)).resolves.toBe(response);
+    expect(sdk.getFeatures).toHaveBeenCalledWith('first-device');
+  });
+
+  test('显式 connectId 不在搜索结果时返回结构化错误', async () => {
+    const sdk = createSdkMock();
+    sdk.searchDevices.mockResolvedValue({
+      success: true,
+      payload: [{ connectId: 'another-device', state: { protocol: 'V1' } }],
+    });
+
+    await expect(getCompatibleFeatures(sdk as never, 'missing-device')).resolves.toEqual({
+      success: false,
+      payload: {
+        code: 'DEVICE_NOT_FOUND',
+        error: 'Device not found: missing-device',
+      },
+    });
+    expect(sdk.getFeatures).not.toHaveBeenCalled();
+  });
+
+  test('get-state 将 firmware scope 传给 SDK', async () => {
+    const sdk = createSdkMock();
+    const response = { success: true, payload: { protocol: 'V2' } };
+    sdk.searchDevices.mockResolvedValue({
+      success: true,
+      payload: [{ connectId: 'pro2-connect-id', state: { protocol: 'V2' } }],
+    });
+    sdk.getDeviceState.mockResolvedValue(response);
+
+    await expect(
+      getCanonicalDeviceState(sdk as never, 'pro2-connect-id', 'firmware')
+    ).resolves.toBe(response);
+    expect(sdk.getDeviceState).toHaveBeenCalledWith('pro2-connect-id', {
+      scope: 'firmware',
+    });
+    expect(sdk.searchDevices).toHaveBeenCalledTimes(1);
+  });
+
+  test('get-state 未指定 connectId 时搜索并选择第一台设备', async () => {
+    const sdk = createSdkMock();
+    const state = { protocol: 'V2', revision: 2 };
+    sdk.searchDevices.mockResolvedValue({
+      success: true,
+      payload: [{ connectId: 'pro2-connect-id', state }],
+    });
+
+    await expect(getCanonicalDeviceState(sdk as never, undefined, 'runtime')).resolves.toEqual({
+      success: true,
+      payload: state,
+    });
+    expect(sdk.getDeviceState).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/firmware-update-legacy-command.test.ts

@@ -0,0 +1,18 @@
+import { getLegacyFirmwareConnectTimeout, program } from '../cli';
+
+describe('firmware-update-legacy CLI command', () => {
+  test('提供 Classic/Pure 的本地固件升级命令', () => {
+    const command = program.commands.find(item => item.name() === 'firmware-update-legacy');
+
+    expect(command).toBeDefined();
+    expect(command?.description()).toBe('Update Classic/Pure firmware through the legacy protocol');
+    expect(command?.options.find(option => option.long === '--binary')?.mandatory).toBe(true);
+    expect(command?.options.some(option => option.long === '--device-name')).toBe(true);
+    expect(command?.options.some(option => option.long === '--update-type')).toBe(true);
+  });
+
+  test('USB Classic 固件升级使用足够的设备探测超时', () => {
+    expect(getLegacyFirmwareConnectTimeout('usb')).toBe(90_000);
+    expect(getLegacyFirmwareConnectTimeout('ble')).toBeUndefined();
+  });
+});