OneKeyHQ · wabicai · Apr 24, 2026 · Apr 27, 2026 · Apr 27, 2026 · Apr 27, 2026
diff --git a/.codegraph/.gitignore b/.codegraph/.gitignore
@@ -0,0 +1,16 @@
+# CodeGraph data files
+# These are local to each machine and should not be committed
+
+# Database
+*.db
+*.db-wal
+*.db-shm
+
+# Cache
+cache/
+
+# Logs
+*.log
+
+# Hook markers
+.dirty
diff --git a/.eslintignore b/.eslintignore
@@ -13,3 +13,4 @@ packages/connect-examples/react-native-demo/
 packages/connect-examples/native-android-example/
 packages/connect-examples/native-ios-example/
 packages/connect-examples/developer-portal/
+.claude/
diff --git a/.github/templates/404.html b/.github/templates/404.html
@@ -3,7 +3,29 @@
 
 <head>
   <meta charset="UTF-8">
-  <title>Hardware SDK Examples</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>OneKey Developer Playground</title>
+  <meta name="description"
+    content="Interactive playground for OneKey Hardware SDK. Test hardware wallet APIs, manage devices, and explore blockchain integrations.">
+  <meta name="theme-color" content="#000000">
+  <meta property="og:title" content="OneKey Developer Playground">
+  <meta property="og:description"
+    content="Interactive playground for OneKey Hardware SDK. Test hardware wallet APIs and blockchain integrations.">
+  <meta property="og:type" content="website">
+  <meta property="og:url" content="https://hardware-example.onekeytest.com/expo-playground/">
+  <meta property="og:image" content="https://hardware-example.onekeytest.com/expo-playground/og.jpg">
+  <meta property="og:image:secure_url" content="https://hardware-example.onekeytest.com/expo-playground/og.jpg">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+  <meta property="og:image:alt" content="OneKey Developer Playground">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="OneKey Developer Playground">
+  <meta name="twitter:description"
+    content="Interactive playground for OneKey Hardware SDK. Test hardware wallet APIs and blockchain integrations.">
+  <meta name="twitter:creator" content="@OneKeyHQ">
+  <meta name="twitter:site" content="@OneKeyHQ">
+  <meta name="twitter:image" content="https://hardware-example.onekeytest.com/expo-playground/og.jpg">
+  <meta name="twitter:image:alt" content="OneKey Developer Playground">
   <script>
     // 简化的路由分发器
     (function () {

diff --git a/.github/workflows/package-publish.yml b/.github/workflows/package-publish.yml
@@ -62,7 +62,17 @@ jobs:
           echo "🔨 Building packages..."
           yarn build
 
-
+      - name: Commit lockfile changes
+        run: |
+          if [ -n "$(git status --porcelain yarn.lock)" ]; then
+            echo "📦 Committing yarn.lock changes from CI environment..."
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git add yarn.lock
+            git commit -m "chore: update yarn.lock [skip ci]"
+          else
+            echo "✅ yarn.lock is clean"
+          fi
 
       - name: Publish to NPM
         env:

diff --git a/.gitignore b/.gitignore
@@ -80,3 +80,5 @@ packages/connect-examples/expo-example/web-build
 
 # Expo web export
 **/web-build
+.vercel
+.env*.local
diff --git a/.gitmodules b/.gitmodules
@@ -1,3 +1,7 @@
 [submodule "submodules/firmware"]
 	path = submodules/firmware
 	url = https://github.com/OneKeyHQ/firmware.git
+[submodule "submodules/firmware-pro2"]
+	path = submodules/firmware-pro2
+	url = https://github.com/OneKeyHQ/firmware-pro2.git
+	branch = dev
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,8 +1,59 @@
-# OneKey Hardware SDK - Claude 文档指引
+# Claude / Agent 工作入口
 
-## 📚 Context7 文档支持
+这份文件只放协作者入口和工程约束，不承载完整技术说明。详细文档以 `docs/README.md` 为索引。
 
-本项目已在 Context7 上索引，可通过 MCP 工具获取最新文档和代码示例：
+## 先读什么
+
+按任务类型选择入口：
+
+| 任务                                    | 首选文档                                |
+| --------------------------------------- | --------------------------------------- |
+| 了解整体架构                            | `docs/architecture.md`                  |
+| 调试 WebUSB / BLE / TransportManager    | `docs/transport.md`                     |
+| 处理 Pro2 / Protocol V2 / firmware-pro2 | `docs/protocol-v2.md`                   |
+| 链集成、签名、地址派生                  | `docs/chain.md`、`docs/chain-evm.md`    |
+| SLIP39、PIN、设备安全状态               | `docs/slip39.md`、`docs/attachToPin.md` |
+| 设备方法支持矩阵                        | `docs/device-method-support.md`         |
+
+完整目录见 `docs/README.md`。
+
+## 当前架构边界
+
+- Protocol V1 服务 Classic / Mini / Touch / Pro 等现有设备，USB 和 BLE 都支持。
+- Protocol V2 服务 Pro2，USB 和 BLE 都支持。
+- 协议判断必须在连接后主动探测，不能依赖 PID、productName 或 descriptor。
+- WebUSB / Electron BLE / React Native BLE 都通过 `GetProtoVersion` 探测 V2，失败或超时回落 V1。
+- `desktop-web-ble` 是默认 Electron BLE 入口，不再按设备型号拆分 env alias。
+- Protocol V2 不走传统 `Initialize/GetFeatures`，而是 `Ping + DeviceGetDeviceInfo` 后通过 `Protocol V2 feature adapter` 归一成 `Features`；早期固件不支持完整信息时才回退最小 `Features`。
+
+## Protocol V2 改动注意事项
+
+- `messages-protocol-v2.json` 来源是 `submodules/firmware-pro2/sys/protobuf/onekey_protocol/latest`。
+- 当前 Protocol V2 schema 依赖 `firmware-pro2` 的 `origin/dev_romloader_split`，因为该分支包含 `Filesystem*`、`DeviceFirmwareUpdate`、`DeviceReboot` 等消息。
+- Protocol V2 文件操作应使用 `FilesystemFileWrite` / `FilesystemDirMake` 等新消息名。
+- Protocol V2 固件安装应使用 `DeviceFirmwareUpdate.targets` 显式传入 resource、bootloader、firmware 路径。
+- 如果修改 protobuf，优先改生成脚本并重新生成 JSON/types，不要手改生成产物。
+
+## 常用验证命令
+
+根目录目前没有 `build:all` script；全仓构建入口是 `yarn build`（`lerna run build`）。协议和 protobuf 变更建议先按依赖顺序验证：
+
+```bash
+yarn --cwd packages/hd-transport test --runInBand
+yarn --cwd packages/hd-transport build
+yarn --cwd packages/hd-transport-web-device build
+yarn --cwd packages/hd-transport-react-native build
+yarn --cwd packages/hd-common-connect-sdk build
+yarn --cwd packages/core build
+NODE_OPTIONS=--max-old-space-size=8192 yarn lint --quiet
+git diff --check
+```
+
+全仓 lint 容易吃内存，默认加 `NODE_OPTIONS=--max-old-space-size=8192`。
+
+## Context7
+
+本项目可通过 Context7 查询：
 
 ```json
 {
@@ -11,63 +62,23 @@
 }
 ```
 
-**使用方法**：
-- 使用 `mcp__context7__get-library-docs` 工具获取文档
-- Library ID: `/onekeyhq/hardware-js-sdk`
-- 可指定 topic 参数聚焦特定主题，如 `transport`、`signing`、`bip39` 等
-
-## 📁 问题分流指引
-
-根据问题类型，请参考对应的专业文档：
-
-### 🔌 连接与传输问题
-**症状**: WebUSB权限错误、设备连接失败、传输超时
-- 📖 **参考**: [docs/transport.md](./docs/transport.md)
-- 🤖 **Agent**: hardware-sdk-expert
-
-### ⛓️ 区块链集成问题
-**症状**: 签名失败、地址生成错误、交易构建问题
-- 📖 **参考**: [docs/chain.md](./docs/chain.md)
-- 🤖 **Agent**: hardware-sdk-expert
+查询主题建议使用精确 topic，例如 `transport`、`Protocol V2`、`firmware update`、`signing`、`SLIP39`。
 
-### 🔐 助记词与密钥管理
-**症状**: SLIP39恢复失败、密钥派生错误、种子生成问题
-- 📖 **参考**: [docs/slip39.md](./docs/slip39.md)
-- 🤖 **Agent**: hardware-sdk-expert
+## CLI 入口
 
-### 🏗️ 架构与开发问题
-**症状**: 构建失败、依赖问题、monorepo结构疑问
-- 📖 **参考**: [docs/architecture.md](./docs/architecture.md)
-- 🤖 **Agent**: hardware-sdk-expert
+`@onekeyfe/cli` 是完整钱包 CLI：
 
-### 🤖 AI Agent 集成 / CLI 使用
-**症状**: CLI 命令使用、Agent Skill 配置、链支持查询
-- 📖 **文档**: developer-portal 的 `agent-integration.mdx`
-- 🔧 **`@onekeyfe/cli`**（`onekey` 命令）— 全功能钱包 CLI：`auth login` 选择登录方式（mnemonic / app-transfer / hardware），`balance` / `transfer` / `swap` / `device ...` 等业务命令登录后自动沿用该模式
-- 🔧 **`@onekeyfe/hardware-cli`**（`onekey-hw` 命令）— 纯硬件钱包 CLI，AI Agent 直连设备优先选它
-
-如果你要**通过 `onekey` CLI 使用硬件钱包**：
 ```bash
 npm install -g @onekeyfe/cli
-
-# Step 1：登录时选择硬件模式（--hardware 只在 auth login 上有）
 onekey auth login --hardware
-
-# Step 2：登录后的业务命令不需要再加 flag，自动走硬件钱包
 onekey balance --chain eth
 onekey device search
-onekey device firmware
 ```
 
-如果要**只调硬件操作、不走 onekey 账户体系**（更轻、AI Agent 场景友好）：
+`@onekeyfe/hardware-cli` 是纯硬件 CLI，更适合 AI Agent 直连设备：
+
 ```bash
 npm install -g @onekeyfe/hardware-cli
 onekey-hw search
 onekey-hw get-address --chain evm --use-empty-passphrase
 ```
-
-## 🤖 专业Agent
-
-**hardware-sdk-expert** - 硬件SDK架构专家
-- 擅长：三层架构分析、WebUSB/BLE协议、BIP32/BIP39/SLIP39
-- 工作方式：优先查阅相关文档，然后进行代码分析
diff --git a/OneKey_Pro2_Deep_Dive.md b/OneKey_Pro2_Deep_Dive.md
@@ -0,0 +1,162 @@
+# OneKey Pro 1 vs Pro 2 协议深度对比与 SDK 接入指南
+
+## 1. GetFeatures 字段详表与差异分析
+
+下表对比了 Pro 1 (Legacy) 与 Pro 2 (Proto V0) 的 `Features` 消息字段。**加粗部分**表示 Pro 2 中新增、变更或具有重大逻辑差异的字段。
+
+| 字段名 | Pro 1 (Legacy) | Pro 2 (Proto V0) | 说明 |
+| :--- | :--- | :--- | :--- |
+| `vendor` | "onekey.so" | "onekey.so" | 保持一致。 |
+| `major_version` | 固件主版本 | 固件主版本 | 逻辑一致。 |
+| `device_id` | 字符串 (Legacy ID) | **UUID 字符串** | Pro 2 采用标准 UUID 格式。 |
+| `model` | "Pro" | "Pro" | 均为 Pro 系列。 |
+| **`onekey_serial`** | 不支持 | **UUID 硬件序列号** | **Pro 2 新增**，用于唯一标识物理硬件。 |
+| **`se_type`** | 不支持 | **SE 芯片型号枚举** | **Pro 2 新增**，区分 SE608A 等不同 SE 芯片。 |
+| **`se_state`** | 不支持 | **SE 运行状态** | **Pro 2 新增**，标识 SE 处于 Boot 还是 App 模式。 |
+| **`se_ver`** | 字符串 | **结构化版本号** | Pro 2 的 SE 版本信息更详细，支持子系统判定。 |
+| **`ble_ver`** | 字符串 | **结构化版本号** | Pro 2 蓝牙固件版本，用于判定 BLE 功能支持。 |
+| **`bootloader_version`**| 不支持 | **独立版本号** | **Pro 2 新增**，用于判定是否支持极速固件更新。 |
+| `initialized` | bool | bool | 逻辑一致。 |
+| `unlocked` | bool | bool | 逻辑一致。 |
+| **`session_id`** | 随机字符串 | **ZBus Session ID** | Pro 2 中该 ID 与内部实时任务队列绑定。 |
+| **`capabilities`** | 基础功能枚举 | **扩展功能枚举** | Pro 2 增加了对新链（如 Sui, Aptos）的原生支持标识。 |
+| **`request_id`** | **不支持** | **4 字节整型** | **核心差异**：Pro 2 在链路层支持异步请求标识。 |
+
+---
+
+## 2. OnekeyFeatures (10025/10026) 专项对比
+
+`OnekeyFeatures` 是 OneKey 硬件特有的扩展接口，用于提供比标准 `Features` 更深度的硬件全栈状态。
+
+### 2.1 字段深度定义 (Pro 2 强化版)
+在 Pro 2 中，由于采用了 **RTOS + 多子系统** 架构，该接口返回的信息大幅增加。
+
+| 字段分类 | 关键字段 | Pro 1 (Legacy) | Pro 2 (Proto V0) | 说明 |
+| :--- | :--- | :--- | :--- | :--- |
+| **基础信息** | `onekey_device_type` | PRO (5) | PRO (5) | 保持一致。 |
+| **版本控制** | `onekey_boot_version` | 基础版本 | **含 Build ID 的详细版本** | 用于判定固件包兼容性。 |
+| **序列号** | `onekey_serial_no` | 硬件 SN | **UUID 格式 SN** | 物理层面的唯一标识。 |
+| **多 SE 状态** | **`onekey_se01_state`** | 仅支持单 SE | **支持 01-04 四个槽位** | **Pro 2 核心改动**：支持查询多个安全芯片状态。 |
+| | **`onekey_se01_ver`** | 单一字符串 | **结构化版本信息** | 细化了 SE 内部固件版本。 |
+| **连接信息** | `onekey_ble_name` | 蓝牙名称 | 蓝牙名称 | 逻辑一致。 |
+
+### 2.2 Pro 2 内部实现逻辑
+*   **异步获取**：不同于 Pro 1 的静态读取，Pro 2 的 `OnekeyGetFeatures` 会触发一次内部的 **ZBus 广播**。
+*   **任务协同**：`Foreground` 任务接收请求后，会向 `SE Agent` 任务请求最新的安全芯片状态，汇总后再通过 USB 返回。
+*   **SDK 建议**：在 Pro 2 连接后，应**优先调用 `OnekeyGetFeatures`**，以获取最完整的硬件拓扑信息。
+
+---
+
+## 3. 私有协议扩展 (Private Range: 60000+)
+
+Pro 2 引入了一系列专门用于工程测试和文件管理的私有协议（基于 `webusb_test.html` 整理）：
+
+| Message ID | 消息名称 | 用途 |
+| :--- | :--- | :--- |
+| 60206 | `Ping` | 新协议连通性测试。 |
+| 60800 | `FixPermission` | 修复 eMMC 文件系统权限。 |
+| 60801 / 60802 | `PathInfo` / `Query` | 查询设备内部文件信息。 |
+| 60804 / 60805 | `FileRead` / `Write` | **极速文件传输**：单包可达 2048B。 |
+| 61000 | `FirmwareUpdate` | 触发 V3 固件更新流程。 |
+
+---
+
+## 4. 通讯时序图对比
+
+### 2.1 Pro 1: Legacy 64 字节分包模式
+Pro 1 受到物理 HID 报告大小限制，必须进行严格的分包。
+
+```mermaid
+sequenceDiagram
+    participant SDK as hardware-js-sdk
+    participant USB as WebUSB
+    participant MCU as Pro 1 MCU
+
+    Note over SDK: 封装消息 (如 GetAddress)
+    SDK->>SDK: Protobuf 序列化
+    SDK->>SDK: 添加 6 字节 Header (## + Type + Size)
+
+    Note over SDK: 分包 (每包 64 字节)
+    SDK->>USB: transferOut (Packet 1: Header + Data)
+    USB->>MCU: 接收首包，解析总长度
+    SDK->>USB: transferOut (Packet 2: Data)
+    USB->>MCU: 接收续包
+    SDK->>USB: transferOut (Packet 3: Data...)
+
+    Note over MCU: 业务处理...
+
+    MCU->>USB: 返回首包 (## + Type + Size)
+    USB-->>SDK: transferIn (64B)
+    MCU->>USB: 返回续包...
+    USB-->>SDK: transferIn (64B)
+```
+
+### 2.2 Pro 2: Proto V0 长帧模式
+Pro 2 利用新协议消除了分包开销，支持高达 2048 字节的单帧传输。
+
+```mermaid
+sequenceDiagram
+    participant SDK as hardware-js-sdk
+    participant USB as WebUSB
+    participant MCU as Pro 2 MCU (RTOS)
+
+    Note over SDK: 封装消息 (如 GetAddress)
+    SDK->>SDK: Protobuf 序列化
+    SDK->>SDK: 计算全帧 CRC8 (Init: 0x30)
+    SDK->>SDK: 构造帧 [0x5A][Len][CRC_H][Router][Attr][Seq][Payload][CRC_A]
+
+    Note over SDK: 单帧传输 (无需 SDK 分包)
+    SDK->>USB: transferOut (单次最大 2048B)
+    USB->>MCU: 硬件 DMA 直接接收全帧
+
+    Note over MCU: 校验 CRC8 & 任务分发
+    MCU->>MCU: ZBus Dispatch to Crypto Task
+
+    Note over MCU: 返回响应
+    MCU->>USB: 发送响应帧 (0x5A 起始)
+    USB-->>SDK: transferIn (一次性读取完整响应)
+```
+
+---
+
+## 3. SDK 协议自动探测逻辑 (Dynamic Detection)
+
+鉴于 Pro 1 未来也可能升级支持新协议，SDK **不能**仅依赖 PID 来写死协议。建议采用以下探测流程：
+
+### 3.1 探测流程 (Handshake)
+1.  **尝试新协议**：SDK 初始化后，先发送一个 **Proto V0 (0x5A)** 格式的 `GetFeatures`。
+2.  **监听首字节**：
+    *   如果返回数据以 `0x5A` 开头 -> **确认为 Pro 2 协议模式**。
+    *   如果返回数据以 `0x3F` (WebUSB) 开头，且后续为 `0x23 0x23` -> **确认为 Legacy 模式**。
+3.  **持久化标志**：在当前 `Device` 实例中记录 `protocolType`，后续 `Call` 直接调用对应序列化器。
+
+### 3.2 伪代码实现
+```typescript
+async function detectProtocol(device) {
+  try {
+    // 1. 尝试用新协议打招呼
+    const probePacket = Pro2Serializer.buildProbePacket();
+    await device.transferOut(probePacket);
+
+    const res = await device.transferIn(64);
+    const firstByte = res.data.getUint8(0);
+
+    if (firstByte === 0x5A) {
+      return 'PROTO_V0';
+    } else if (firstByte === 0x3F) {
+      return 'LEGACY';
+    }
+  } catch (e) {
+    // 容错处理：默认回退到 Legacy
+    return 'LEGACY';
+  }
+}
+```
+
+## 4. 接入建议
+
+*   **无状态处理**：虽然 Pro 2 内部支持状态，但为了兼容性，SDK 建议依然在 `acquire` 后执行一次协议探测 + `GetFeatures`。
+*   **字节序陷阱**：再次提醒，新协议所有的 `Length` 和 `MessageID` 均为 **Little-Endian (小端)**，这与 Legacy 的大端序完全相反。
+
+---
+*文档版本：2026-03-18*