用一个轻量 Rust 工具，把鸿蒙项目的创建、构建、设备调试、运行时安装和模拟器管理串成可脚本化的命令行流程。

为什么做 ark-cli

鸿蒙应用开发并不只发生在 IDE 里：CI 服务器需要无界面构建，远程开发机需要 SSH 操作，自动化脚本需要稳定地安装 HAP、采集日志和管理设备。若每个场景都手动拼接 hvigor、hdc、SDK 和 Emulator，环境准备与命令编排就会变成主要成本。

ark-cli 的目标不是重新实现鸿蒙工具链，而是提供一层统一入口：命令行负责表达工作流，核心库负责配置、构建、下载、HDC 和模拟器等能力，底层工具仍按官方协议工作。

开发思路：先统一能力，再扩展界面

项目采用 Rust workspace，核心逻辑集中在 ark-core，CLI 编排位于 ark-cli，桌面应用则由 Tauri + React/TypeScript 构成。这样做有三个直接收益：

1. 能力复用：CLI 与 GUI 共用配置、构建、HDC 和运行时逻辑，避免两套实现产生行为差异。
2. 边界清晰：commands/ 只做参数解析后的流程编排；设备操作、下载校验、模板生成等细节放进核心模块。
3. 渐进式交付：先在 CLI 中完成并验证核心能力，再通过 Tauri IPC 暴露给 GUI。终端用户无需等待桌面端完善。

把 HDC 作为兼容性底座

设备连接是最容易被环境差异影响的环节，因此 ark-cli 保留了 ark hdc <参数> 的完整透传能力，同时提供 devices、install、shell、logcat、forward 等高频封装。高级命令降低记忆成本，透传命令保留底层能力，二者并不冲突。

用运行时管理降低安装门槛

ark runtime install 将 SDK、hvigor/ohpm/node 与 Emulator 运行时统一放到 ~/.ark-cli/runtime/，并提供状态检查。下载模块负责进度展示、解压和 SHA-256 校验；失败时应暴露明确错误，而不是让后续构建以“找不到命令”结束。

安装

推荐从仓库安装：

git clone https://atomgit.com/nutpi/ark-cli.git
cd ark-cli
bash scripts/install.sh
ark runtime install
ark runtime status

也可以从源码构建：

cargo build --release
cp target/release/ark-cli /usr/local/bin/
ln -sf /usr/local/bin/ark-cli /usr/local/bin/ark

安装后检查：

ark --version
ark config init
ark devices

实际使用前仍需确认目标系统、SDK 版本、设备授权和签名配置满足鸿蒙项目要求。runtime status 用于确认工具是否已就绪，不替代项目自身的签名配置。

第一个完整工作流

1. 创建项目

ark create my-app
# 指定包名或最小模板
ark create my-app --bundle com.example.myapp
ark create my-app --template empty

default 模板适合快速开始，empty 模板适合希望自行组织代码的项目。

2. 构建

ark build
ark build --mode release --product phone
ark build --clean
ark build --watch

--watch 会监视变更并触发增量构建，适合开发期快速反馈；发布构建则应显式选择 release 模式并检查产物。

3. 连接并运行

ark devices
ark run
ark run --device localhost:5555
ark run --no-build
ark run --monitor

ark run 将构建、安装、启动合并为一个流程。多设备环境建议总是使用 --device，避免把应用安装到错误目标。

4. 调试与日志

ark shell getprop ro.build.version.ohos
ark logcat --level error --tag MyApp
ark install ./entry/build/default/outputs/default/entry-default-signed.hap --device localhost:5555
ark uninstall com.example.myapp

需要访问尚未封装的 HDC 能力时，直接使用：

ark hdc list targets -v
ark hdc shell ls /data
ark hdc file send ./local.txt /data/local/tmp/local.txt

适合放进 CI 的最小脚本

set -euo pipefail
ark runtime status
ark config show
ark build --mode release --product phone
ark install ./entry/build/default/outputs/default/entry-default-signed.hap --device "$ARK_DEVICE"

CI 中建议固定运行时与 API 版本，使用 JSON 输出消费设备状态，并将构建日志与 ark logcat 输出作为流水线 artifacts 保存。不要把签名材料或设备凭据写入仓库。

结语

ark-cli 的核心价值是把“工具链能力”组织成稳定、可组合的工作流：Rust 提供单二进制与跨平台基础，ark-core 统一业务逻辑，CLI 和 GUI 共享同一套能力，HDC 透传则保证不会牺牲底层兼容性。对于需要远程开发、自动化构建或轻量设备调试的团队，它可以作为 DevEco Studio 之外的一条终端路径。

仓库地址：https://atomgit.com/nutpi/ark-cli
旋武社区：https://xuanwu.openatom.org