OneKeyHQ · cursor · May 18, 2026
diff --git a/README.md b/README.md
@@ -6,14 +6,14 @@ 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)                                        | The core process of hardware wallet connection.                       |
 | [@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-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)     | device transport entrypoints for web runtimes                         |
 | [@onekeyfe/hd-shared](./packages/shared)                                    | Tools, error definitions, constants                                   |
 | [@onekeyfe/hardware-cli](./packages/hd-cli)                                | CLI for AI agent integration (Claude Code, Cursor, etc.)              |
 
@@ -36,6 +36,7 @@ Run a dev build:
 - `yarn dev:ble` (react-native sdk)
 - `yarn dev:core` (core package)
 - `yarn dev:transport-http` (transport-http package)
+- `yarn dev:transport-web-device` (web device transport package)
 - `yarn dev:shared` (shared package)
 
 ### Development with example desktop app (Recommend)

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`** - Web 设备传输入口（WebUSB / Electron BLE）
 - **`@onekeyfe/hd-transport-usb`** - Node.js USB传输（CLI/服务端，基于 libusb）
 - **`@onekeyfe/hd-transport-http`** - HTTP Bridge传输
 - **`@onekeyfe/hd-transport-lowlevel`** - 低层传输（BLE 插件模式）
@@ -32,6 +32,12 @@ SDK接口层 (@onekeyfe/core)
 - **`@onekeyfe/hd-web-sdk`** - Web平台SDK
 - **`@onekeyfe/hd-ble-sdk`** - 移动端BLE SDK
 
+### Ledger 集成（HWK）
+- **`@onekeyfe/hwk-adapter-core`** - Connector 抽象、桥接接口与通用类型
+- **`@onekeyfe/hwk-ledger-adapter`** - Ledger 链适配与 signer 封装
+- **`@onekeyfe/hwk-ledger-connector-webhid`** - 基于 WebHID 的 Ledger `IConnector` 实现
+- **`@onekeyfe/hwk-ledger-connector-ble`** - 基于 React Native BLE 的 Ledger `IConnector` 实现
+
 ### 示例应用
 - **`@onekeyfe/connect-examples`** - 集成示例
   - `expo-example` - Web集成示例
@@ -106,12 +112,56 @@ switch(env) {
     │   └── @onekeyfe/hd-transport
     │
     └── 传输层实现
-        ├── @onekeyfe/hd-transport-webusb      (浏览器)
+        ├── @onekeyfe/hd-transport-web-device  (WebUSB / Electron BLE)
         ├── @onekeyfe/hd-transport-usb          (Node.js CLI)
         ├── @onekeyfe/hd-transport-lowlevel     (BLE 插件)
         └── @onekeyfe/hd-transport-http         (Bridge)
 ```
 
+## 🔌 Ledger Connector 接口
+
+HWK 包统一实现 `IConnector` 接口，公共调用面如下：
+
+```typescript
+interface IConnector {
+  searchDevices(): Promise<ConnectorDevice[]>;
+  connect(deviceId?: string): Promise<ConnectorSession>;
+  disconnect(sessionId: string): Promise<void>;
+  call(sessionId: string, method: string, params: unknown): Promise<unknown>;
+  cancel(sessionId: string): Promise<void>;
+  uiResponse(response: UiResponseEvent): void;
+  on(event, handler): void;
+  off(event, handler): void;
+  reset(): void;
+}
+```
+
+典型接入方式：
+
+```typescript
+import { createLedgerWebHidConnector } from '@onekeyfe/hwk-ledger-connector-webhid';
+
+const connector = createLedgerWebHidConnector();
+const [device] = await connector.searchDevices();
+
+if (!device) {
+  throw new Error('No Ledger device found');
+}
+
+const session = await connector.connect(device.deviceId);
+```
+
+已实现的交互事件（`ui-event`）包括：
+- `searching`
+- `confirm-open-app`
+- `unlock-device`
+- `confirm-on-device`
+- `interaction-complete`
+
+使用约束：
+- WebHID Connector 面向浏览器 / 桌面 WebHID 场景。
+- BLE Connector 面向 React Native，包本身声明了 `react-native` peer dependency。
+
 ## 🔧 开发工具
 
 - **Lerna** - Monorepo管理

diff --git a/packages/hd-transport-web-device/README.md b/packages/hd-transport-web-device/README.md
@@ -1,28 +1,19 @@
-# `@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` provides device-facing transport entrypoints for web runtimes.
 
-## What is the purpose
+## Exports
 
-- translate JSON payloads to binary messages using protobuf definitions comprehensible to OneKey devices
-- chunking and reading chunked messages according to the [OneKey protocol](./protocol.md)
-- exposing single API for various transport methods:
-  - Http Transport
-  - React Native Transport
-  - WebUSB
-- Create and expose typescript definitions based on protobuf definitions.
+- `WebUsbTransport` - browser transport implemented in `src/webusb.ts`
+- `ElectronBleTransport` - Electron BLE transport implemented in `src/electron-ble-transport.ts`
 
-### The short version
+## Development
 
-In order to be able to use new features of onekey-firmware you need to update protobuf definitions.
+Run the package in watch mode from the repository root:
 
-1. `git submodule update --init --recursive` to initialize git submodules.
-1. `yarn update-submodules` to update firmware submodule
-1. `yarn update:protobuf` to generate new `./messages.json` and `./src/types/messages.ts`
-
-git submodule update --init --recursive to initialize firmware submodule
-yarn update-submodules to update firmware submodule
-yar update:protobuf to generate new ./messages.json and ./src/types/messages.ts
+```bash
+yarn dev:transport-web-device
+```
 
 ## Docs