rust_hdc：用纯 Rust 重写鸿蒙设备连接器（HDC），一颗 3MB 二进制替代整个 C++ 工具链

程序媛夏天

112人浏览 · 2026-09-12 15:33:59

程序媛夏天 · 2026-09-12 15:33:59 发布

rust_hdc：用纯 Rust 重写鸿蒙设备连接器（HDC），一颗 3MB 二进制替代整个 C++ 工具链

标签： Rust, OpenHarmony, HarmonyOS, 鸿蒙, HDC, 开发者工具, 开源

项目地址： https://atomgit.com/jianguoxu/rust_hdc （MIT 协议，欢迎共建）

一、这个项目是什么

rust_hdc（命令行工具名 rhdc）是 OpenHarmony 设备连接器 HDC 协议的纯 Rust 实现。

用过鸿蒙开发的人对 hdc 都不陌生——它就是鸿蒙世界的 adb：装 HAP、推拉文件、看 hilog、进设备 shell，全靠它。官方实现 developtools_hdc 用 C++ 编写，宿主机端客户端 + server + 设备守护进程加起来 10 万行代码，必须依赖完整的 OpenHarmony SDK 构建体系（gn + ninja + 工具链）才能编译。

rust_hdc 做的事情一句话概括：

把 HDC 协议从零到一在 Rust 里重新实现，产出一个约 3MB 的单一二进制，零 C/C++ 依赖、零 FFI、零外部进程调用，协议兼容官方 hdc server，开箱即用。

# 一键安装（macOS / Linux）
curl -fsSL https://atomgit.com/jianguoxu/rust_hdc/raw/main/install.sh | sh

# 用法和官方 hdc 一致
rhdc list targets
rhdc shell 'uname -a'
rhdc install my_app.hap

它同时是一个 Rust 库——use rust_hdc::... 就能把完整的 HDC 客户端能力嵌进你自己的 Rust 工具链，这是官方 C++ 实现给不了的。

二、为什么要开发它

2.1 官方 C++ hdc 的三个痛点

痛点	官方 C++ hdc	rust_hdc
构建门槛	gn/ninja，需要完整 OH SDK 构建环境	`cargo build`，仅需 Rust 工具链
内存安全	手动内存管理	编译期保证内存安全
跨平台	每个平台一套 SDK 构建	一个 `--target` 交叉编译到任意 Rust 支持的平台

这不仅是工程洁癖。真实场景里有三群人被这些痛点困住：

鸿蒙 PC / OpenHarmony 原生用户。官方 hdc 没有适配 OHOS 目标（aarch64-unknown-linux-ohos），在鸿蒙 PC 上没法编译运行设备调试工具。rust_hdc 可以直接编译到 OHOS 目标，交互式 shell（带历史记录和 Tab 补全）直接跑在鸿蒙 PC 上——用鸿蒙设备调试鸿蒙设备，这是本项目最独特的价值点。
CI/CD 与自动化工具作者。在 CI 容器里装官方 hdc，意味着拖着 SDK 构建产物跑；rust_hdc 一个 3MB 静态二进制扔进去就行。
想把设备调试能力嵌进自己产品的开发者。IDE 插件、设备管家、自动化测试框架……用 C++ 版你得链接它的库、处理 FFI；用 rust_hdc，cargo add rust_hdc 完事。

2.2 为什么是 Rust 而不是别的语言

协议层是性能敏感 + 安全敏感的：HDC 走 TCP/USB 批量传输，分包、握手、并发会话，Tokio 异步运行时天然匹配；
跨平台一致性：macOS（IOKit）、Linux（libusb）、Windows、OHOS，同一套代码一个 flag 切换目标；
产出即库：Rust 生态的 crate 分发让"工具"和"库"天然合一，crates.io 发布后 cargo install rhdc 即用。

2.3 生态空位

官方仓库其实已经有一个 Rust 重写的设备端守护进程（hdc_rust），但宿主机端客户端仍然是 C++。rust_hdc 填补的正是这个空位：完整的纯 Rust 宿主机端客户端。

三、它是怎么工作的

rhdc 支持两种设备通信模式：

模式 1 — 通过官方 hdc server（默认，稳定）

┌─────────────┐     TCP           ┌────────────┐     USB/TCP     ┌────────┐
│  rhdc (CLI) │ ◄───────────────► │ hdc server │ ◄─────────────► │ 设备   │
│  或库调用   │  127.0.0.1:8710   │  (官方)    │                 │ (OHOS) │
└─────────────┘                   └────────────┘                 └────────┘

协议栈完全自己实现，四层拆解：

层	实现	说明
分包层	`protocol/packet.rs`	4 字节大端长度前缀 + 载荷
通道层	`protocol/channel.rs`	握手：`OHOS HDC` banner + 连接密钥（32 字节联合体）
命令层	`protocol/command.rs`	u16 小端命令码，50+ 种命令类型
传输层	`client.rs` / `transport/usb.rs`	TCP 模式（127.0.0.1:8710）/ USB 直连（bulk 端点）

模式 2 — rhdc server 直接 USB 连接（实验性）：Rust 版 server 通过 IOKit/libusb 直接枚举 USB 设备、处理控制/批量传输，对外暴露与官方 server 相同的 TCP 接口——这条链路上不再需要任何官方 hdc 二进制。

核心协议只有约 500 行 + 命令层约 400 行。逆向协议的过程本身也很规律：抓包官方 client 与 server 的通信流量，逐字段对齐联合体定义，再用 31 个协议级单测（分包编解码、命令编解码、通道握手往返）锁住行为。

四、现在的进度

项目已完成 v0.1.0 首个公开版本（2026-01），当前处于活跃迭代期。

已完成

协议层：分包编解码、通道握手、50+ 命令码，31 个协议级测试全绿；
客户端（约 25 个命令）：设备管理（list/tconn/tmode/wait）、应用管理（install/uninstall）、文件传输（file send/recv，目录自动 zip）、Shell（单次执行 + 交互式 Tab 补全）、hilog 过滤、端口转发（fport）、截图、getprop/setprop、dumpsys 等；
真机验证：Mate 60 Pro（HongMeng Kernel 1.12.0）+ v3.2.0d server 实测，20+ 命令正常工作；
跨平台：macOS / Linux / Windows / HarmonyOS PC（aarch64-unknown-linux-ohos）；
工程化：一键安装脚本（sh / ps1）、shell 补全（bash/zsh/fish/powershell）、中英双语 README 与 CONTRIBUTING、CI 流水线、TUI 终端模式（ratatui 三栏界面）、bridge 模式 USB 断线自动重连；
rhdc-gui（Tauri 图形界面）已起步。

已知边界（如实告知）

基于 v3.2.0d server 实测，少数命令尚有缺口：

命令	状态
`bugreport`	⚠️ 部分可用（server 响应格式有差异，协议待深挖）
`keygen`	❌ 请暂用官方 `hdc keygen`
`tconn --remove`	❌ 断连协议不匹配
`shell -b` bundle 模式	🔧 计划中

这些边界都写进了 README 的"已知问题"一节——做逆向实现，如实标注不可用比假装可用更重要。

路线图方向

补齐上述缺口命令的协议细节；
rhdc server（纯 Rust server 替代官方 server）从实验性走向稳定；
crates.io 正式发布；
rhdc-gui 图形界面完善。

五、欢迎一起共建

这是一个协议逆向 + 工程实现的社区项目，很多工作天然适合分工协作：

你可以做什么

方向	具体内容	适合谁
协议逆向	`bugreport`/`tconn --remove`/`keygen` 等缺口命令的抓包分析	熟悉抓包、对二进制协议好奇的人
多设备实测	手里有平板/车机/开发板？跑一遍 20+ 命令，把结果回填到兼容性表格	任何有 OHOS 设备的人（零代码门槛）
命令补全	对齐 awesome-hdc 的 100% 命令清单	想练 Rust 的入门贡献者
平台适配	Windows USB 后端（当前 bridge 模式以 macOS IOKit / Linux libusb 为主）、BSD 等	有对应平台环境的开发者
rhdc-gui	Tauri 界面的功能完善	前端 / 桌面端开发者
文档翻译	英文文档润色、其他语种翻译	不写代码也能贡献

参与路径

浏览 CONTRIBUTING.zh.md——环境搭建、编码规范、测试要求、PR 流程都写清楚了；
从 cargo check && cargo clippy && cargo test 开始，31 个协议测试不需要真机就能跑；
提交遵循 Conventional Commits，提交信息需带 Signed-off-by（DCO 校验）；
有疑问先提 Issue，标注 good first issue 的任务适合入门。

为什么值得参与

学习价值：完整走一遍"抓包 → 逆向协议 → Rust 实现 → 测试锁定"的流程，协议栈每一层都小而完整，是学习二进制协议设计和 Rust 异步编程的绝佳练习场；
生态价值：鸿蒙工具链的 Rust 生态还很早期，越早参与，你的名字越容易出现在贡献者列表前排；
真实用户：鸿蒙 PC 生态刚起步，原生设备调试工具是刚需，你的 PR 会真的被用上。