From c80470a525b68767ae64b1bc1efb2ff4f2ebb210 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Mon, 13 Jul 2026 16:04:53 +0000
Subject: [PATCH] docs: refresh architecture guide for hwk trezor stack

Co-authored-by: Leon <lixiao.dev@gmail.com>
---
 docs/architecture.md | 74 ++++++++++++++++++++++++++++++++------------
 1 file changed, 54 insertions(+), 20 deletions(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index a0f1544f0..46b2059cc 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -5,15 +5,15 @@
 OneKey Hardware SDK 采用三层架构设计：
 
 ```
-应用层 (DApps)
+应用层 (DApps / CLI / Demo apps)
     ↓
-SDK接口层 (@onekeyfe/core) 
+SDK接口层 (@onekeyfe/hd-core / HWK adapters)
     ↓
-传输抽象层 (@onekeyfe/hd-transport)
+传输抽象层 (@onekeyfe/hd-transport / vendor connectors)
     ↓
-平台适配层 (WebUSB/BLE/HTTP)
+平台适配层 (WebUSB / BLE / HTTP / Bridge)
     ↓
-硬件设备层 (OneKey设备)
+硬件设备层 (OneKey / third-party hardware)
 ```
 
 ## 🏗️ 核心包结构
@@ -23,19 +23,28 @@ SDK接口层 (@onekeyfe/core)
 - **`@onekeyfe/hd-transport`** - 传输层抽象
 
 ### 传输层
-- **`@onekeyfe/hd-transport-webusb`** - WebUSB传输（浏览器）
+- **`@onekeyfe/hd-transport-web-device`** - Web 与 Electron 设备传输（WebUSB / Electron BLE）
 - **`@onekeyfe/hd-transport-usb`** - Node.js USB传输（CLI/服务端，基于 libusb）
 - **`@onekeyfe/hd-transport-http`** - HTTP Bridge传输
 - **`@onekeyfe/hd-transport-lowlevel`** - 低层传输（BLE 插件模式）
+- **`@onekeyfe/hd-transport-react-native`** - React Native 侧的设备传输注册
+- **`@onekeyfe/hd-transport-electron`** - Electron 平台传输适配
 
 ### 平台SDK
 - **`@onekeyfe/hd-web-sdk`** - Web平台SDK
 - **`@onekeyfe/hd-ble-sdk`** - 移动端BLE SDK
 
 ### 示例应用
-- **`@onekeyfe/connect-examples`** - 集成示例
-  - `expo-example` - Web集成示例
-  - `expo-playground` - 开发测试平台
+- **`packages/connect-examples/expo-example`** - Web 集成示例
+- **`packages/connect-examples/expo-playground`** - 开发测试平台
+- **`packages/connect-examples/hwk-demo`** - HWK 多厂商硬件接入示例
+
+### HWK 多厂商适配层
+- **`@onekeyfe/hwk-adapter-core`** - 定义跨厂商的 `IConnector` / `IHardwareWallet` 接口、事件常量，以及 `createBridgedConnector()`、`createCombinedConnector()` 这类组合能力。
+- **`@onekeyfe/hwk-trezor-adapter`** - 将应用层方法映射到 Trezor 连接器；当前公开覆盖 EVM、BTC、SOL、TRON 以及 `getFeatures`、`deviceSettings`、`setBrightness`、`changePin`、`wipeDevice` 等设备方法。
+- **`@onekeyfe/hwk-trezor-connector-webusb`** - 浏览器侧 Trezor WebUSB 连接器；`requestDevice()` 必须在用户手势里调用，选中的设备才会出现在后续 `searchDevices()` 结果中。
+- **`@onekeyfe/hwk-trezor-connector-rn-ble`** / **`@onekeyfe/hwk-trezor-connector-electron-ble`** - React Native 与 Electron 的 BLE 连接器实现。
+- **`@onekeyfe/hwk-trezor-connector`** / **`@onekeyfe/hwk-trezor-core`** - Trezor 方法分发与会话层；前者把 `btcGetAddress`、`evmSignTransaction` 这类方法映射为设备调用，后者负责消息分帧、分块读写，以及 THP / legacy v1 会话初始化。
 
 ## 🔄 API调用流程
 
@@ -52,6 +61,26 @@ Transport.send()
 硬件设备响应
 ```
 
+```typescript
+// HWK / Trezor WebUSB 最小接入
+import { TrezorAdapter } from '@onekeyfe/hwk-trezor-adapter';
+import { TrezorWebUsbConnector } from '@onekeyfe/hwk-trezor-connector-webusb';
+
+const connector = new TrezorWebUsbConnector({
+  thp: { hostName: 'OneKey', appName: 'My App' },
+});
+const hw = new TrezorAdapter(connector);
+
+await connector.requestDevice(); // Must run in a click/tap handler.
+const [device] = await hw.searchDevices();
+const features = await hw.getFeatures(device.connectId);
+```
+
+#### HWK 接入约束
+- **WebUSB 前置条件：** 浏览器必须暴露 `navigator.usb`，并且 `requestDevice()` 只能在点击/触摸等用户手势中触发。
+- **React Native BLE 前置条件：** 需要先拿到系统蓝牙/定位权限，并确保蓝牙处于 `PoweredOn` 状态，适配层才会对 `REQUEST_DEVICE_PERMISSION` 给出 `granted: true`。
+- **当前示例范围：** `packages/connect-examples/hwk-demo` 目前只接通了 Trezor；传入 `ledger` 会直接抛出 `HWK_BRAND_NOT_WIRED`，因此它更适合做 Trezor 接入样例，而不是完整的多厂商演示。
+
 ## 🎯 设计原则
 
 ### 分层解耦
@@ -101,15 +130,17 @@ switch(env) {
 应用层
 ├── @onekeyfe/hd-web-sdk
 ├── @onekeyfe/hd-ble-sdk
-    │
-    ├── @onekeyfe/hd-core ←── 核心层
-    │   └── @onekeyfe/hd-transport
-    │
-    └── 传输层实现
-        ├── @onekeyfe/hd-transport-webusb      (浏览器)
-        ├── @onekeyfe/hd-transport-usb          (Node.js CLI)
-        ├── @onekeyfe/hd-transport-lowlevel     (BLE 插件)
-        └── @onekeyfe/hd-transport-http         (Bridge)
+├── @onekeyfe/hwk-trezor-adapter
+│   ├── @onekeyfe/hwk-adapter-core
+│   ├── @onekeyfe/hwk-trezor-connector-webusb / rn-ble / electron-ble
+│   └── @onekeyfe/hwk-trezor-connector → @onekeyfe/hwk-trezor-core
+│
+└── @onekeyfe/hd-core ←── 核心层
+    └── @onekeyfe/hd-transport
+        ├── @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)
 ```
 
 ## 🔧 开发工具
@@ -127,6 +158,9 @@ yarn install
 # 构建项目
 yarn build
 
-# 启动示例
-yarn workspace @onekeyfe/connect-examples start
+# 启动 Web 示例
+yarn example
+
+# 启动 HWK Demo
+cd ./packages/connect-examples/hwk-demo && yarn start
 ```
\ No newline at end of file