@onekeyfe/hd-core 1.2.0-alpha.2 → 1.2.0-alpha.21

package/dist/utils/tracing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/utils/tracing.ts"],"names":[],"mappings":"AAmBA,wBAAgB,qBAAqB,IAAI,MAAM,CAI9C;AASD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAK/E;AAOD,MAAM,WAAW,cAAc;IAE7B,UAAU,EAAE,MAAM,CAAC;IAEnB,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,UAAU,EAAE,MAAM,CAAC;IAEnB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,SAAS,EAAE,MAAM,CAAC;IAElB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,WAAW,CAAC;IAEnE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAKD,MAAM,WAAW,iBAAiB;IAEhC,aAAa,EAAE,MAAM,CAAC;IAEtB,SAAS,EAAE,MAAM,CAAC;IAElB,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC7C;AAWD,wBAAgB,uBAAuB,IAAI,iBAAiB,CAW3D;AAQD,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;IACR,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GACA,cAAc,CAyBhB;AAKD,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI,CAK/F;AAKD,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAuB9E;AAOD,wBAAgB,iCAAiC,CAAC,gBAAgB,EAAE,MAAM,GAAG,cAAc,EAAE,CAI5F;AAOD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAmBpE;AAOD,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAW9D"}
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/utils/tracing.ts"],"names":[],"mappings":"AAmBA,wBAAgB,qBAAqB,IAAI,MAAM,CAI9C;AASD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAK/E;AAOD,MAAM,WAAW,cAAc;IAE7B,UAAU,EAAE,MAAM,CAAC;IAEnB,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,UAAU,EAAE,MAAM,CAAC;IAEnB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,SAAS,EAAE,MAAM,CAAC;IAElB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,WAAW,CAAC;IAEnE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAKD,MAAM,WAAW,iBAAiB;IAEhC,aAAa,EAAE,MAAM,CAAC;IAEtB,SAAS,EAAE,MAAM,CAAC;IAElB,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC7C;AAWD,wBAAgB,uBAAuB,IAAI,iBAAiB,CAW3D;AAQD,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;IACR,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GACA,cAAc,CAyBhB;AAKD,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI,CAK/F;AAKD,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAyB9E;AAOD,wBAAgB,iCAAiC,CAAC,gBAAgB,EAAE,MAAM,GAAG,cAAc,EAAE,CAI5F;AAOD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAmBpE;AAOD,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAW9D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/hd-core",
-  "version": "1.2.0-alpha.2",
+  "version": "1.2.0-alpha.21",
   "description": "Core processes and APIs for communicating with OneKey hardware devices.",
   "author": "OneKey",
   "homepage": "https://github.com/OneKeyHQ/hardware-js-sdk#readme",
@@ -25,8 +25,8 @@
     "url": "https://github.com/OneKeyHQ/hardware-js-sdk/issues"
   },
   "dependencies": {
-    "@onekeyfe/hd-shared": "1.2.0-alpha.2",
-    "@onekeyfe/hd-transport": "1.2.0-alpha.2",
+    "@onekeyfe/hd-shared": "1.2.0-alpha.21",
+    "@onekeyfe/hd-transport": "1.2.0-alpha.21",
     "axios": "1.15.2",
     "bignumber.js": "^9.0.2",
     "bytebuffer": "^5.0.1",
@@ -44,5 +44,5 @@
     "@types/w3c-web-usb": "^1.0.10",
     "@types/web-bluetooth": "^0.0.21"
   },
-  "gitHead": "6c183b7f7027f4b4d3db4f427f6360351a6c6680"
+  "gitHead": "efe594367fb3b196a5126baee7e2aba3e94986cd"
 }

package/src/api/BaseMethod.ts

@@ -1,15 +1,18 @@
 import semver from 'semver';
 import {
+  ERRORS,
+  HardwareErrorCode,
   createDeviceNotSupportMethodError,
   createNeedUpgradeFirmwareHardwareError,
 } from '@onekeyfe/hd-shared';
+import { Enum_SafetyCheckLevel } from '@onekeyfe/hd-transport';
 
 import { createDeviceMessage } from '../events/device';
 import { UI_REQUEST } from '../constants/ui-request';
 import { DEVICE, FIRMWARE, createFirmwareMessage, createUiMessage } from '../events';
 import { getHDPath, toHardened } from './helpers/pathUtils';
 import { getBleFirmwareReleaseInfo, getFirmwareReleaseInfo } from './firmware/releaseHelper';
-import { LoggerNames, getFirmwareType, getLogger, isMethodVersionRangeUnsupported } from '../utils';
+import { LoggerNames, getLogger, isMethodVersionRangeUnsupported } from '../utils';
 import { generateInstanceId } from '../utils/tracing';
 import { DeviceModelToTypes } from '../types';
 
@@ -17,9 +20,13 @@ import type { Device } from '../device/Device';
 import type DeviceConnector from '../device/DeviceConnector';
 import type { DeviceFirmwareRange, KnownDevice } from '../types';
 import type { CoreMessage } from '../events';
+import type { ProtocolV2InteractionDescriptor } from '../protocols/protocol-v2/uiInteraction';
 import type { RequestContext } from '../utils/tracing';
 import type { CoreContext } from '../core';
 
+export type UnlockPolicy = 'none' | 'retry-on-locked';
+export type ProtocolV2UiMode = 'auto' | 'none';
+
 const Log = getLogger(LoggerNames.Method);
 
 const isEvmLedgerLegacyPathWithHighIndex = (path: unknown) => {
@@ -48,6 +55,8 @@ const isEvmLedgerLegacyPathWithHighIndex = (path: unknown) => {
 const EVM_LEDGER_LEGACY_METHODS = ['evmGetAddress', 'evmGetPublicKey'];
 
 export abstract class BaseMethod<Params = undefined> {
+  abortSignal?: AbortSignal;
+
   responseID: number;
 
   // @ts-expect-error
@@ -155,13 +164,31 @@ export abstract class BaseMethod<Params = undefined> {
   strictCheckDeviceSupport = false;
 
   /**
-   * 方法是否仅支持 Protocol V2 设备（Pro2）。
-   * core 调度在设备协议确定（acquire + initialize）后统一守卫，
-   * 非 V2 设备直接抛出 NotSupport 错误，方法内部不必重复判断。
+   * Whether this method supports Protocol V2 devices (Pro2) only.
+   * Core enforces this after the protocol is established during acquire and initialize,
+   * so implementations do not need to repeat the check.
    * @default false
    */
   requireProtocolV2 = false;
 
+  /** Core unlocks and retries Protocol V2 business methods once when the device is locked. */
+  unlockPolicy: UnlockPolicy = 'retry-on-locked';
+
+  /** Non-blocking Protocol V2 interaction synthesized by the SDK. */
+  protocolV2UiInteraction?: ProtocolV2InteractionDescriptor;
+
+  /** Special background methods may suppress all synthesized Protocol V2 UI events. */
+  protocolV2UiMode: ProtocolV2UiMode = 'auto';
+
+  protected throwIfAborted() {
+    if (this.abortSignal?.aborted) {
+      throw ERRORS.TypedError(
+        HardwareErrorCode.CallQueueActionCancelled,
+        'Hardware operation cancelled'
+      );
+    }
+  }
+
   // @ts-expect-error: strictPropertyInitialization
   postMessage: (message: CoreMessage) => void;
 
@@ -225,11 +252,11 @@ export abstract class BaseMethod<Params = undefined> {
   }
 
   checkFirmwareRelease() {
-    // 固件 release 元数据（DataManager remote config）目前只覆盖 Protocol V1 设备；
-    // Pro2 的更新流程由 firmwareUpdateV4 自行管理，这里显式跳过而不是依赖 features 为空。
+    // DataManager release metadata currently covers Protocol V1 devices only.
+    // firmwareUpdateV4 manages Pro2 updates, so skip them explicitly.
     if (!this.device || this.device.isProtocolV2()) return;
     if (!this.device.features) return;
-    const firmwareType = getFirmwareType(this.device.features);
+    const firmwareType = this.device.getCurrentFirmwareType();
     const releaseInfo = getFirmwareReleaseInfo(this.device.features, firmwareType);
     this.postMessage(
       createFirmwareMessage(FIRMWARE.RELEASE_INFO, {
@@ -333,10 +360,10 @@ export abstract class BaseMethod<Params = undefined> {
     if (this.shouldPromptSafetyCheckForEvmLedgerLegacyPath()) {
       checkFlag = true;
     }
-    if (checkFlag && this.device.getCurrentSafetyChecks() === 'Strict') {
+    if (checkFlag && this.device.getCurrentSafetyChecks() === Enum_SafetyCheckLevel.Strict) {
       Log.debug('will change safety_checks level');
       await this.device.commands.typedCall('ApplySettings', 'Success', {
-        safety_checks: 'PromptTemporarily',
+        safety_checks: Enum_SafetyCheckLevel.PromptTemporarily,
       });
       this.temporarySafetyCheckPrompted = true;
       return true;

package/src/api/CheckBootloaderRelease.ts

@@ -1,7 +1,6 @@
 import { BaseMethod } from './BaseMethod';
 import { UI_REQUEST } from '../constants/ui-request';
 import { getBootloaderReleaseInfo } from './firmware/releaseHelper';
-import { getFirmwareType } from '../utils';
 
 import type { CheckBootloaderReleaseParams } from '../types/api/checkBootloaderRelease';
 
@@ -19,7 +18,7 @@ export default class CheckBootloaderRelease extends BaseMethod {
     const { features } = this.device;
     const payload = this.payload as CheckBootloaderReleaseParams;
 
-    const deviceFirmwareType = getFirmwareType(features);
+    const deviceFirmwareType = this.device.getCurrentFirmwareType();
     const firmwareType = payload.firmwareType ?? deviceFirmwareType;
 
     const releaseInfo = getBootloaderReleaseInfo({

package/src/api/CheckFirmwareRelease.ts

@@ -1,7 +1,6 @@
 import { BaseMethod } from './BaseMethod';
 import { UI_REQUEST } from '../constants/ui-request';
 import { getFirmwareReleaseInfo } from './firmware/releaseHelper';
-import { getFirmwareType } from '../utils';
 
 import type { CheckFirmwareReleaseParams } from '../types/api/checkFirmwareRelease';
 
@@ -20,7 +19,7 @@ export default class CheckFirmwareRelease extends BaseMethod {
     const payload = this.payload as CheckFirmwareReleaseParams;
 
     if (this.device.features) {
-      const deviceFirmwareType = getFirmwareType(this.device.features);
+      const deviceFirmwareType = this.device.getCurrentFirmwareType();
       const firmwareType = payload.firmwareType ?? deviceFirmwareType;
 
       const releaseInfo = getFirmwareReleaseInfo(this.device.features, firmwareType);

package/src/api/ClearSessionCache.ts

@@ -0,0 +1,28 @@
+import { BaseMethod } from './BaseMethod';
+import { deviceWalletSessionStore } from '../device/DeviceWalletSessionStore';
+
+import type { ClearSessionCacheParams } from '../types/api/sessionCache';
+
+export default class ClearSessionCache extends BaseMethod<ClearSessionCacheParams> {
+  init() {
+    this.useDevice = false;
+    this.useDevicePassphraseState = false;
+    this.skipForceUpdateCheck = true;
+    this.params = {
+      deviceId: this.payload.deviceId,
+      passphraseState: this.payload.passphraseState,
+    };
+  }
+
+  run() {
+    const { deviceId, passphraseState } = this.params;
+    if (!deviceId) {
+      deviceWalletSessionStore.clear();
+    } else if (!passphraseState) {
+      deviceWalletSessionStore.deleteDevice(deviceId);
+    } else {
+      deviceWalletSessionStore.delete(deviceId, passphraseState);
+    }
+    return Promise.resolve({ cleared: true as const });
+  }
+}

package/src/api/DirList.ts

@@ -1,7 +1,7 @@
 import { BaseMethod } from './BaseMethod';
 import {
-  validateNonEmptyString,
   validateOptionalNonNegativeInteger,
+  validateProtocolV2FilesystemPath,
 } from './helpers/filesystemValidation';
 
 export type DirListParams = {
@@ -11,12 +11,14 @@ export type DirListParams = {
 
 export default class DirList extends BaseMethod<DirListParams> {
   init() {
-    // Protocol V2 (Pro2) 专属方法，core 调度层统一做非 V2 设备守卫
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
     this.requireProtocolV2 = true;
     this.skipForceUpdateCheck = true;
     this.useDevicePassphraseState = false;
     this.params = {
-      path: validateNonEmptyString(this.payload.path, 'path'),
+      path: validateProtocolV2FilesystemPath(this.payload.path, 'path', {
+        allowVolumeRoot: true,
+      }),
       depth: validateOptionalNonNegativeInteger(this.payload.depth, 'depth'),
     };
   }

package/src/api/DirMake.ts

@@ -1,5 +1,5 @@
 import { BaseMethod } from './BaseMethod';
-import { validateNonEmptyString } from './helpers/filesystemValidation';
+import { validateProtocolV2FilesystemPath } from './helpers/filesystemValidation';
 
 export type DirMakeParams = {
   path: string;
@@ -7,11 +7,11 @@ export type DirMakeParams = {
 
 export default class DirMake extends BaseMethod<DirMakeParams> {
   init() {
-    // Protocol V2 (Pro2) 专属方法，core 调度层统一做非 V2 设备守卫
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
     this.requireProtocolV2 = true;
     this.skipForceUpdateCheck = true;
     this.useDevicePassphraseState = false;
-    this.params = { path: validateNonEmptyString(this.payload.path, 'path') };
+    this.params = { path: validateProtocolV2FilesystemPath(this.payload.path, 'path') };
   }
 
   async run() {

package/src/api/DirRemove.ts

@@ -1,5 +1,5 @@
 import { BaseMethod } from './BaseMethod';
-import { validateNonEmptyString } from './helpers/filesystemValidation';
+import { validateProtocolV2FilesystemPath } from './helpers/filesystemValidation';
 
 export type DirRemoveParams = {
   path: string;
@@ -7,11 +7,11 @@ export type DirRemoveParams = {
 
 export default class DirRemove extends BaseMethod<DirRemoveParams> {
   init() {
-    // Protocol V2 (Pro2) 专属方法，core 调度层统一做非 V2 设备守卫
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
     this.requireProtocolV2 = true;
     this.skipForceUpdateCheck = true;
     this.useDevicePassphraseState = false;
-    this.params = { path: validateNonEmptyString(this.payload.path, 'path') };
+    this.params = { path: validateProtocolV2FilesystemPath(this.payload.path, 'path') };
   }
 
   async run() {

package/src/api/FileDelete.ts

@@ -1,5 +1,5 @@
 import { BaseMethod } from './BaseMethod';
-import { validateNonEmptyString } from './helpers/filesystemValidation';
+import { validateProtocolV2FilesystemPath } from './helpers/filesystemValidation';
 
 export type FileDeleteParams = {
   path: string;
@@ -7,11 +7,11 @@ export type FileDeleteParams = {
 
 export default class FileDelete extends BaseMethod<FileDeleteParams> {
   init() {
-    // Protocol V2 (Pro2) 专属方法，core 调度层统一做非 V2 设备守卫
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
     this.requireProtocolV2 = true;
     this.skipForceUpdateCheck = true;
     this.useDevicePassphraseState = false;
-    this.params = { path: validateNonEmptyString(this.payload.path, 'path') };
+    this.params = { path: validateProtocolV2FilesystemPath(this.payload.path, 'path') };
   }
 
   async run() {

package/src/api/FileRead.ts

@@ -1,15 +1,15 @@
 import {
-  PROTOCOL_V2_BLE_FILE_CHUNK_SIZE,
+  PROTOCOL_V2_BLE_FILE_READ_CHUNK_SIZE,
   PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE,
 } from '@onekeyfe/hd-transport';
 import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
 
 import { BaseMethod } from './BaseMethod';
 import {
-  validateNonEmptyString,
   validateNonNegativeInteger,
   validateOptionalNonNegativeInteger,
   validateOptionalPercentage,
+  validateProtocolV2FilesystemPath,
 } from './helpers/filesystemValidation';
 import { hexToBytes, isHexString, stripHexPrefix } from './helpers/hexUtils';
 import { DataManager } from '../data-manager';
@@ -27,7 +27,7 @@ const MIN_FILE_READ_CHUNK_SIZE = 64;
 function getProtocolV2FileReadChunkLimit() {
   const env = DataManager.getSettings('env');
   if (env && DataManager.isBleConnect(env)) {
-    return PROTOCOL_V2_BLE_FILE_CHUNK_SIZE;
+    return PROTOCOL_V2_BLE_FILE_READ_CHUNK_SIZE;
   }
   return PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE;
 }
@@ -69,13 +69,30 @@ function toUint8Array(value: unknown): Uint8Array {
   return new Uint8Array(0);
 }
 
+function getDeviceTransferProgress(
+  bytesBeforeChunk: number,
+  bytesAfterChunk: number,
+  totalBytes: number
+) {
+  if (!Number.isFinite(totalBytes) || totalBytes <= 0) {
+    return 100;
+  }
+  if (bytesBeforeChunk <= 0 && bytesAfterChunk < totalBytes) {
+    return 0;
+  }
+  if (bytesAfterChunk >= totalBytes) {
+    return 100;
+  }
+  return Math.min(Math.max(Math.ceil((bytesAfterChunk / totalBytes) * 100), 1), 99);
+}
+
 export default class FileRead extends BaseMethod<FileReadParams> {
   init() {
-    // Protocol V2 (Pro2) 专属方法，core 调度层统一做非 V2 设备守卫
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
     this.requireProtocolV2 = true;
     this.skipForceUpdateCheck = true;
     this.useDevicePassphraseState = false;
-    const path = validateNonEmptyString(this.payload.path, 'path');
+    const path = validateProtocolV2FilesystemPath(this.payload.path, 'path');
     this.params = {
       path,
       offset: validateNonNegativeInteger(this.payload.offset, 'offset', 0),
@@ -123,8 +140,7 @@ export default class FileRead extends BaseMethod<FileReadParams> {
       const readLen = Math.min(chunkSize, totalLength - read);
       const offset = startOffset + read;
       const progress =
-        this.params.uiPercentage ??
-        Math.min(Math.ceil(((read + readLen) / Math.max(totalLength, 1)) * 100), 99);
+        this.params.uiPercentage ?? getDeviceTransferProgress(read, read + readLen, totalLength);
       const res = await this.device.commands.typedCall('FilesystemFileRead', 'FilesystemFile', {
         file: {
           path: this.params.path,

package/src/api/FileWrite.ts

@@ -1,19 +1,13 @@
-import {
-  PROTOCOL_V2_BLE_FILE_CHUNK_SIZE,
-  PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE,
-} from '@onekeyfe/hd-transport';
-import { ERRORS, HardwareErrorCode } from '@onekeyfe/hd-shared';
-
 import { BaseMethod } from './BaseMethod';
 import {
-  validateNonEmptyString,
   validateNonNegativeInteger,
   validateOptionalNonNegativeInteger,
   validateOptionalPercentage,
+  validateProtocolV2FilesystemPath,
   validateRequiredData,
 } from './helpers/filesystemValidation';
+import { writeProtocolV2File } from './helpers/protocolV2FileWrite';
 import { UI_REQUEST, createUiMessage } from '../events/ui-request';
-import { DataManager } from '../data-manager';
 
 export type FileWriteParams = {
   path: string;
@@ -24,74 +18,19 @@ export type FileWriteParams = {
   chunkLen?: number;
   overwrite?: boolean;
   append?: boolean;
+  emitProgress?: boolean;
   uiPercentage?: number;
   timeoutMs?: number | string;
 };
 
-const MIN_FILE_CHUNK_SIZE = 64;
-
-function getProtocolV2FileChunkLimit() {
-  const env = DataManager.getSettings('env');
-  if (env && DataManager.isBleConnect(env)) {
-    return PROTOCOL_V2_BLE_FILE_CHUNK_SIZE;
-  }
-  return PROTOCOL_V2_WEBUSB_FILE_CHUNK_SIZE;
-}
-
-async function dataToUint8Array(data: FileWriteParams['data'] | Blob): Promise<Uint8Array> {
-  if (typeof data === 'string') {
-    return new TextEncoder().encode(data);
-  }
-
-  if (data instanceof ArrayBuffer) {
-    return new Uint8Array(data);
-  }
-
-  if (ArrayBuffer.isView(data)) {
-    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
-  }
-
-  if (typeof Blob !== 'undefined' && data instanceof Blob) {
-    return new Uint8Array(await data.arrayBuffer());
-  }
-
-  throw ERRORS.TypedError(
-    HardwareErrorCode.CallMethodInvalidParameter,
-    'Unsupported FilesystemFileWrite data'
-  );
-}
-
-function normalizeChunkSize(value: unknown, maxChunkSize: number): number {
-  const numeric = Number(value);
-  if (!Number.isFinite(numeric) || numeric <= 0) return maxChunkSize;
-  return Math.min(Math.max(Math.floor(numeric), MIN_FILE_CHUNK_SIZE), maxChunkSize);
-}
-
-function getConfirmedProgress(
-  processedByte: number,
-  totalSize: number,
-  written: number,
-  dataLength: number
-) {
-  if (Number.isFinite(processedByte) && Number.isFinite(totalSize) && totalSize > 0) {
-    if (processedByte >= totalSize) return 100;
-    return Math.min(Math.max(Math.floor((processedByte / totalSize) * 100), 0), 99);
-  }
-  if (dataLength > 0) {
-    if (written >= dataLength) return 100;
-    return Math.min(Math.max(Math.floor((written / dataLength) * 100), 0), 99);
-  }
-  return 100;
-}
-
 export default class FileWrite extends BaseMethod<FileWriteParams> {
   init() {
-    // Protocol V2 (Pro2) 专属方法，core 调度层统一做非 V2 设备守卫
+    // Protocol V2 (Pro2) only; Core rejects non-V2 devices.
     this.requireProtocolV2 = true;
     this.skipForceUpdateCheck = true;
     this.useDevicePassphraseState = false;
     validateRequiredData(this.payload.data, 'data');
-    const path = validateNonEmptyString(this.payload.path, 'path');
+    const path = validateProtocolV2FilesystemPath(this.payload.path, 'path');
     const offset = validateNonNegativeInteger(this.payload.offset, 'offset', 0);
     this.params = {
       path,
@@ -102,115 +41,31 @@ export default class FileWrite extends BaseMethod<FileWriteParams> {
       chunkLen: validateOptionalNonNegativeInteger(this.payload.chunkLen, 'chunkLen'),
       overwrite: this.payload.overwrite ?? offset === 0,
       append: this.payload.append ?? false,
+      emitProgress: this.payload.emitProgress ?? true,
       uiPercentage: validateOptionalPercentage(this.payload.uiPercentage, 'uiPercentage'),
       timeoutMs: validateOptionalNonNegativeInteger(this.payload.timeoutMs, 'timeoutMs'),
     };
   }
 
   async run() {
-    const data = await dataToUint8Array(this.params.data);
-    const dataLength = data.byteLength;
-    const offsetValue = Number(this.params.offset ?? 0);
-    const startOffset = Number.isFinite(offsetValue) && offsetValue > 0 ? offsetValue : 0;
-    const payloadTotalSize = Number(this.params.totalSize);
-    const totalSize =
-      Number.isFinite(payloadTotalSize) && payloadTotalSize > 0
-        ? payloadTotalSize
-        : startOffset + dataLength;
-
-    if (totalSize < startOffset + dataLength) {
-      throw ERRORS.TypedError(
-        HardwareErrorCode.RuntimeError,
-        `FilesystemFileWrite totalSize ${totalSize} is smaller than offset + data length ${
-          startOffset + dataLength
-        }`
-      );
-    }
-
-    const chunkSize = normalizeChunkSize(
-      this.params.chunkSize ?? this.params.chunkLen,
-      getProtocolV2FileChunkLimit()
-    );
-    const overwrite = this.params.overwrite ?? false;
-    const append = this.params.append ?? false;
-    let written = 0;
-    let chunkIndex = 0;
-    let lastMessage: Record<string, unknown> | undefined;
-    const startTime = Date.now();
-    const timeoutMs =
-      this.params.timeoutMs === undefined ? undefined : Number(this.params.timeoutMs);
-
-    while (written < dataLength) {
-      const chunkEnd = Math.min(written + chunkSize, dataLength);
-      const chunk = data.slice(written, chunkEnd);
-      const offset = startOffset + written;
-      const isFirstChunk = chunkIndex === 0;
-      const progress =
-        this.params.uiPercentage ??
-        Math.min(Math.ceil(((written + chunk.byteLength) / dataLength) * 100), 99);
-
-      const res = await this.device.commands.typedCall(
-        'FilesystemFileWrite',
-        'FilesystemFile',
-        {
-          file: {
-            path: this.params.path,
-            offset,
-            total_size: totalSize,
-            data: chunk,
-          },
-          overwrite: isFirstChunk ? overwrite : false,
-          append,
-          ui_percentage: progress,
-        },
-        {
-          timeoutMs,
-        }
-      );
-
-      lastMessage = res.message;
-      const processedByte = Number(res.message?.processed_byte);
-      if (Number.isFinite(processedByte) && processedByte > offset) {
-        written = processedByte - startOffset;
-      } else {
-        written += chunk.byteLength;
-      }
-
-      if (written > dataLength) {
-        throw ERRORS.TypedError(
-          HardwareErrorCode.RuntimeError,
-          `FilesystemFileWrite invalid processed_byte ${processedByte}`
-        );
-      }
-
-      const confirmedProcessedByte =
-        Number.isFinite(processedByte) && processedByte > offset
-          ? processedByte
-          : startOffset + written;
-      if (typeof this.postMessage === 'function') {
-        const elapsedMs = Date.now() - startTime;
-        const transferredBytes = Math.min(written, dataLength);
-        this.postMessage(
-          createUiMessage(UI_REQUEST.DEVICE_PROGRESS, {
-            progress: getConfirmedProgress(confirmedProcessedByte, totalSize, written, dataLength),
-            transferredBytes,
-            totalBytes: dataLength,
-            rateBytesPerSecond:
-              elapsedMs > 0 ? Math.round((transferredBytes / elapsedMs) * 1000) : undefined,
-            elapsedMs,
-          })
-        );
-      }
-      chunkIndex += 1;
-    }
-
-    return Promise.resolve({
-      ...lastMessage,
+    return writeProtocolV2File({
+      commands: this.device.commands,
       path: this.params.path,
-      offset: startOffset,
-      total_size: totalSize,
-      processed_byte: startOffset + written,
-      chunks: chunkIndex,
+      data: this.params.data,
+      offset: this.params.offset,
+      totalSize: this.params.totalSize,
+      chunkSize: this.params.chunkSize,
+      chunkLen: this.params.chunkLen,
+      overwrite: this.params.overwrite,
+      append: this.params.append,
+      uiPercentage: this.params.uiPercentage,
+      timeoutMs: this.params.timeoutMs === undefined ? undefined : Number(this.params.timeoutMs),
+      throwIfAborted: () => this.throwIfAborted(),
+      onProgress: payload => {
+        if (this.params.emitProgress && typeof this.postMessage === 'function') {
+          this.postMessage(createUiMessage(UI_REQUEST.DEVICE_PROGRESS, payload));
+        }
+      },
     });
   }
 }

package/src/api/FirmwareUpdate.ts

@@ -14,7 +14,7 @@ import { uploadFirmware } from './firmware/uploadFirmware';
 import { createUiMessage } from '../events';
 import { DeviceModelToTypes, type KnownDevice } from '../types';
 import { isEnteredManuallyBoot } from './firmware/bootloaderHelper';
-import { LoggerNames, getDeviceUUID, getLogger, wait } from '../utils';
+import { LoggerNames, getLogger, wait } from '../utils';
 import { DataManager } from '../data-manager';
 import { DevicePool } from '../device/DevicePool';
 
@@ -133,7 +133,7 @@ export default class FirmwareUpdate extends BaseMethod<Params> {
     const { features, commands } = device;
     const deviceType = device.getCurrentDeviceType();
 
-    // Protocol V2 (Pro2) 固件升级走 DeviceFirmwareUpdate 流程，禁止进入 legacy 入口
+    // Protocol V2 (Pro2) uses DeviceFirmwareUpdate and must not enter this legacy flow.
     if (device.isProtocolV2()) {
       throw ERRORS.TypedError(
         HardwareErrorCode.RuntimeError,
@@ -142,7 +142,7 @@ export default class FirmwareUpdate extends BaseMethod<Params> {
     }
 
     if (!device.isBootloader() && features) {
-      const uuid = getDeviceUUID(features);
+      const serialNo = device.getCurrentSerialNo();
       // should go to bootloader mode manually
       if (isEnteredManuallyBoot(features, params.updateType)) {
         return Promise.reject(ERRORS.TypedError(HardwareErrorCode.FirmwareUpdateManuallyEnterBoot));
@@ -161,7 +161,7 @@ export default class FirmwareUpdate extends BaseMethod<Params> {
 
         // force clean classic device cache so that the device can initialize again
         if (DeviceModelToTypes.model_classic.includes(deviceType)) {
-          DevicePool.clearDeviceCache(uuid);
+          DevicePool.clearDeviceCache(serialNo);
         }
         delete DevicePool.devicesCache[''];
         await this.checkPromise?.promise;