OneKeyHQ · cursor · Jul 6, 2026
diff --git a/README.md b/README.md
@@ -6,16 +6,20 @@ Hardware-js-sdk is designed to allow third-party developers to quickly access th
 
 | package                                                                     | description                                                           |
 | --------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| [@onekeyfe/core](./packages/core)                                           | The core process of hardware wallet connection.                       |
+| [@onekeyfe/hd-core](./packages/core)                                        | Core connection flows and chain APIs for OneKey hardware devices.     |
 | [@onekeyfe/hd-web-sdk](./packages/hd-web-sdk)                               | Using the sdk in the web platform.                                    |
 | [@onekeyfe/hd-ble-sdk](./packages/hd-ble-sdk)                               | Using the SDK in BLE communication environment. e.g: iOS / Android    |
-| [@onekeyfe/hd-common-sdk](./packages/hd-common-connect-sdk)                 | Using the SDK in a node or web-usb environment                        |
+| [@onekeyfe/hd-common-connect-sdk](./packages/hd-common-connect-sdk)         | Shared SDK runtime for Node.js and browser transports.                |
 | [@onekeyfe/hd-transport](./packages/hd-transport)                           | Data serialization and deserialization of hardware communication data |
 | [@onekeyfe/hd-transport-http](./packages/hd-transport-http)                 | communication lib for http                                            |
 | [@onekeyfe/hd-transport-react-native](./packages/hd-transport-react-native) | communication lib for React Native                                    |
-| [@onekeyfe/hd-transport-webusb](./packages/hd-transport-webusb)             | communication lib for WebUSB                                          |
+| [@onekeyfe/hd-transport-web-device](./packages/hd-transport-web-device)     | communication lib for WebUSB/WebHID browser environments              |
 | [@onekeyfe/hd-shared](./packages/shared)                                    | Tools, error definitions, constants                                   |
 | [@onekeyfe/hardware-cli](./packages/hd-cli)                                | CLI for AI agent integration (Claude Code, Cursor, etc.)              |
+| [@onekeyfe/hwk-adapter-core](./packages/hwk-adapter-core)                   | Shared types, events, and error contracts for hardware adapters       |
+| [@onekeyfe/hwk-ledger-adapter](./packages/hwk-ledger-adapter)               | Vendor-neutral Ledger adapter with chain methods and retry handling   |
+| [@onekeyfe/hwk-ledger-connector-webhid](./packages/hwk-ledger-connector-webhid) | WebHID connector for Ledger devices in browser environments       |
+| [@onekeyfe/hwk-ledger-connector-ble](./packages/hwk-ledger-connector-ble)   | React Native BLE connector for Ledger devices                         |
 
 ## Documentation
 

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -7,7 +7,7 @@ OneKey Hardware SDK 采用三层架构设计：
 ```
 应用层 (DApps)
     ↓
-SDK接口层 (@onekeyfe/core) 
+SDK接口层 (@onekeyfe/hd-core)
     ↓
 传输抽象层 (@onekeyfe/hd-transport)
     ↓
@@ -23,7 +23,7 @@ SDK接口层 (@onekeyfe/core)
 - **`@onekeyfe/hd-transport`** - 传输层抽象
 
 ### 传输层
-- **`@onekeyfe/hd-transport-webusb`** - WebUSB传输（浏览器）
+- **`@onekeyfe/hd-transport-web-device`** - WebUSB / WebHID 传输（浏览器）
 - **`@onekeyfe/hd-transport-usb`** - Node.js USB传输（CLI/服务端，基于 libusb）
 - **`@onekeyfe/hd-transport-http`** - HTTP Bridge传输
 - **`@onekeyfe/hd-transport-lowlevel`** - 低层传输（BLE 插件模式）
@@ -32,6 +32,14 @@ SDK接口层 (@onekeyfe/core)
 - **`@onekeyfe/hd-web-sdk`** - Web平台SDK
 - **`@onekeyfe/hd-ble-sdk`** - 移动端BLE SDK
 
+### Ledger 适配层（`hwk-*`）
+- **`@onekeyfe/hwk-adapter-core`** - 多厂商硬件适配层的共享类型、事件、错误码与 connector contract
+- **`@onekeyfe/hwk-ledger-adapter`** - Ledger 的统一钱包接口实现，封装设备发现、链方法调用、重试与指纹校验
+- **`@onekeyfe/hwk-ledger-connector-webhid`** - 浏览器 WebHID 连接器
+- **`@onekeyfe/hwk-ledger-connector-ble`** - React Native BLE 连接器
+
+这套 `hwk-*` 栈与 `@onekeyfe/hd-core` 主 SDK 并行存在，主要用于接入 Ledger 等多厂商设备；它不是 `hd-core` 的 transport 插件。宿主应用通常先选择 connector（WebHID 或 BLE），再创建 `LedgerAdapter`，并处理 `ui-request-device-permission`、`ui-request-device-connect`、`ui-request-install-app` 等交互事件。
+
 ### 示例应用
 - **`@onekeyfe/connect-examples`** - 集成示例
   - `expo-example` - Web集成示例
@@ -88,7 +96,7 @@ abstract class BaseMethod<Request, Response> {
 ```typescript
 // 根据环境选择传输方式
 switch(env) {
-  case 'webusb': return new WebUsbTransport();       // 浏览器 WebUSB
+  case 'web-device': return new WebUsbTransport();      // 浏览器 WebUSB / WebHID
   case 'node-usb': return new NodeUsbTransport();      // Node.js libusb (CLI)
   case 'lowlevel': return new LowlevelTransport();    // BLE 插件模式
   case 'http': return new HttpTransport();             // HTTP Bridge
@@ -106,12 +114,24 @@ switch(env) {
     │   └── @onekeyfe/hd-transport
     │
     └── 传输层实现
-        ├── @onekeyfe/hd-transport-webusb      (浏览器)
+        ├── @onekeyfe/hd-transport-web-device  (浏览器)
         ├── @onekeyfe/hd-transport-usb          (Node.js CLI)
         ├── @onekeyfe/hd-transport-lowlevel     (BLE 插件)
         └── @onekeyfe/hd-transport-http         (Bridge)
 ```
 
+Ledger 适配层（并行架构）：
+
+```text
+宿主应用
+├── @onekeyfe/hwk-ledger-adapter
+│   └── @onekeyfe/hwk-adapter-core
+│
+└── 连接器实现
+    ├── @onekeyfe/hwk-ledger-connector-webhid   (Browser WebHID)
+    └── @onekeyfe/hwk-ledger-connector-ble      (React Native BLE)
+```
+
 ## 🔧 开发工具
 
 - **Lerna** - Monorepo管理

diff --git a/packages/hd-transport-web-device/README.md b/packages/hd-transport-web-device/README.md
@@ -1,6 +1,6 @@
-# `@onekeyfe/hd-transport-webusb`
+# `@onekeyfe/hd-transport-web-device`
 
-`@onekeyfe/hd-transport-webusb` is a library that implements transport communication by WebUSB.
+`@onekeyfe/hd-transport-web-device` is a library that implements browser transport communication over WebUSB/WebHID.
 
 ## What is the purpose
 

diff --git a/packages/hwk-ledger-adapter/README.md b/packages/hwk-ledger-adapter/README.md
@@ -0,0 +1,116 @@
+# `@onekeyfe/hwk-ledger-adapter`
+
+`@onekeyfe/hwk-ledger-adapter` exposes a vendor-neutral hardware wallet interface for Ledger devices. It sits on top of a transport-specific connector and handles device discovery, request/response UI events, chain-method dispatch, retry logic, and device fingerprint checks.
+
+## Related packages
+
+- `@onekeyfe/hwk-adapter-core` - shared types, event constants, and error codes
+- `@onekeyfe/hwk-ledger-connector-webhid` - browser connector for WebHID
+- `@onekeyfe/hwk-ledger-connector-ble` - React Native connector for BLE
+
+## Installation
+
+```bash
+npm install @onekeyfe/hwk-adapter-core @onekeyfe/hwk-ledger-adapter @onekeyfe/hwk-ledger-connector-webhid
+```
+
+Use `@onekeyfe/hwk-ledger-connector-ble` instead of the WebHID connector when you integrate in React Native over BLE.
+
+## Quick start
+
+```ts
+import { UI_REQUEST, UI_RESPONSE } from '@onekeyfe/hwk-adapter-core';
+import { LedgerAdapter } from '@onekeyfe/hwk-ledger-adapter';
+import { createLedgerWebHidConnector } from '@onekeyfe/hwk-ledger-connector-webhid';
+
+const connector = createLedgerWebHidConnector();
+const hw = new LedgerAdapter(connector, {
+  autoInstallApp: true,
+});
+
+hw.on(UI_REQUEST.REQUEST_DEVICE_PERMISSION, () => {
+  // Reply only after your browser or native permission flow succeeds.
+  hw.uiResponse({
+    type: UI_RESPONSE.RECEIVE_DEVICE_PERMISSION,
+    payload: { granted: true },
+  });
+});
+
+hw.on(UI_REQUEST.REQUEST_INSTALL_APP, () => {
+  // Replace this with a real user confirmation in your app UI.
+  hw.uiResponse({
+    type: UI_RESPONSE.RECEIVE_INSTALL_APP,
+    payload: { confirmed: true },
+  });
+});
+
+const devices = await hw.searchDevices();
+if (!devices.length) {
+  throw new Error('No Ledger device found');
+}
+
+const [{ connectId, deviceId = '' }] = devices;
+
+await hw.connectDevice(connectId);
+
+const result = await hw.evmGetAddress(connectId, deviceId, {
+  path: "m/44'/60'/0'/0/0",
+  showOnDevice: false,
+});
+
+if (!result.success) {
+  throw new Error(result.payload.error);
+}
+
+console.log(result.payload.address);
+
+await hw.dispose();
+```
+
+## What the adapter provides
+
+- Transport-agnostic `IHardwareWallet` methods for `evm`, `btc`, `sol`, and `tron`
+- Automatic permission and reconnect request events
+- Optional app installation flow through `autoInstallApp`
+- Batched `allNetworkGetAddress(...)` calls with fingerprint verification
+- `cancel(connectId?)` for aborting the active operation
+
+## Integration notes
+
+### UI request / response flow is required
+
+The adapter emits request events such as:
+
+- `ui-request-device-permission`
+- `ui-request-device-connect`
+- `ui-request-install-app`
+
+Your host app must answer them through `hw.uiResponse(...)`. If `ui-request-device-permission` is never answered, the request times out instead of waiting forever.
+
+### Pick the connector for the host platform
+
+- Use `createLedgerWebHidConnector()` in browser environments.
+- Use `createLedgerBleConnector()` in React Native BLE environments.
+- BLE flows require an explicit `connectId` returned by discovery. The adapter does not auto-pick a BLE device.
+
+### Do not persist `connectId`
+
+`connectId` is a transport-session identifier. It can change after USB replug or WebHID rediscovery. If you need a stable identity for later verification, derive and persist a chain fingerprint with `getChainFingerprint(...)` after the first successful device call.
+
+## Troubleshooting
+
+### No device found
+
+Listen for `ui-request-device-connect` and prompt the user to connect and unlock the Ledger device before retrying.
+
+### Multiple USB devices connected
+
+The adapter refuses to auto-pick between multiple Ledger USB devices and returns `DeviceOneDeviceOnly`. Ask the user to leave a single device connected or add an explicit device selection step in your host app.
+
+### Wrong app open or app missing
+
+Chain calls can fail with `WrongApp` or `AppNotInstalled`. If you enable `autoInstallApp`, also handle `ui-request-install-app` and the forwarded `ui-event` progress updates.
+
+### Permission request keeps failing
+
+The permission response must reflect the real browser or native permission result. Reply with `granted: false` when the platform denies access so your app can surface the correct failure reason.