io.github.LeonTing1010/haplane

HapLane

鸿蒙 HAP 一键签名 · 调试 · 部署 —— CLI + MCP，agent 可驱动。 封装华为官方工具链（hvigorw / hap-sign-tool / hdc），把散在文档里的命令拼成一条可脚本、可 --dry-run、可让 AI 调用的链。零运行时依赖（纯 Node stdlib）。

开源 MIT · 不破解 · 不逆向 · 签名走你自己的 AGC 凭据。

• 官网：https://leonting1010.github.io/haplane/
• npm：haplane · Gitee：https://gitee.com/LeonTing1010/hap-deploy · GitHub：https://github.com/LeonTing1010/hap-deploy-cli

装

npm i -g haplane          # 已上 npm，国内把 registry 设成 npmmirror 更快
# 或从 Gitee Release 直连下单文件（网络拉不动 npm 时）：
#   https://gitee.com/LeonTing1010/haplane/releases

接入 MCP（挂进你的 AI）

HapLane 是标准 stdio MCP server（JSON-RPC 2.0，协议 2024-11-05）。粘一段配置就接上，支持 Claude Code / Cursor / Cline / DevEco Code 等任意 MCP 客户端。

{
  "mcpServers": {
    "haplane": {
      "command": "npx",
      "args": ["-y", "-p", "haplane", "haplane-mcp"]
    }
  }
}

国内网络拉不动 npm 时，下载 haplane-mcp.mjs 放本地，改成 "command": "node", "args": ["/你的路径/haplane-mcp.mjs"]。

接上后在 AI 里直接说：「把 ./app.hap 签名装到我手机上」——agent 自己调 deploy_to_device，撞 system 权限自动降级重装，装完验签。

13 个 MCP 工具

HapLane 是中性工具,自身不内嵌任何应用内容。 可搜可装的条目来自你订阅的源(registry index.json,apt/sources.list 模型);默认订阅官方源、可退订。工具指向上游权利人官方发布位,不托管/不转存二进制。详见 分发合规边界。

配置与密码走 HAP_DEPLOY_CONFIG 指向的配置文件 + .env（自动加载），不入 MCP 参数；stdout 只出协议 JSON，日志走 stderr。

也能命令行直接用

haplane setup                 # 首次：自动探测 SDK + 生成配置与 .env 模板
haplane doctor                # 体检工具链与签名材料
haplane device                # 列设备 + 打印 UDID
haplane source list           # 看订阅了哪些源(默认官方源,可 add/remove/reset)
haplane source add <url>      # 订阅一个 registry 源(index.json URL)
haplane search 浏览器          # 在订阅源里搜:可装条目直接装,discoveryOnly/HAP Store 给源站链接
haplane deploy --app linysbrowser   # 从订阅源解析 → 上游拉 → sha256 校验 → 签名 → 装机 → 验签
haplane deploy --in app.hap   # 对现成 HAP：签名 → 装机 → 验签
haplane deploy                # 从源码工程全链：hvigorw 打包 → 签名 → 装机 → 验签
haplane deploy --in app.hap --target <设备>   # 多台设备时指定装哪台(设备键用 device 命令看)
haplane sign|install|verify --in app.hap   # 单步执行

全局：--config <path> · --dry-run（只打印命令不真跑，无真机也能看全链）· --verbose · --in <hap> · --target <设备>

配置与密码

复制 hap-deploy.config.example.json 为 hap-deploy.config.json，填 SDK 路径 + 签名材料路径。密码只从环境变量读，绝不入配置 / 日志：

# 写进 .env（自动加载，免 export）
HAP_KEY_PWD=***
HAP_KEYSTORE_PWD=***

认证：三条路，选最白那档

给 AGC 打交道有三种方式，推荐机器密钥：

• 🟢 client_credentials 机器密钥（推荐）：AGC 控制台铸 client_id / secret → 换 Bearer token。无交互登录、可吊销、可审计。凭据走 env AGC_CLIENT_ID + AGC_CLIENT_SECRET（或直接 AGC_TOKEN）。
• 🟡 deveco login 的 cookie 会话：只连 DevEco AI 助手，根本不碰 AGC，与签名无关。
• 🔴 寄生会话（抓登录 session 冒充调网页 API）：不可审计，本工具不用。

关键坑：请求头 client_id 必须匹配 token 的 sub，否则 401。

老实说：它不做什么 · 前提

不做

• 不破解、不绕过签名——只帮你把该走的流程走顺
• 只处理你自己或已授权的设备 / 账号
• 不碰纯血鸿蒙真机的商用根：真机走你自己的 AGC 材料

前提

• 华为开发者账号 + AGC（真机 / 上架签名要）
• 华为 SDK：hdc / hap-sign-tool / java（各平台官方版都有，几 G，华为官网装）
• Node ≥ 18；macOS / Windows / Linux 都行

签名的物理约束（必须知道）

• 纯血鸿蒙真机的信任只有 AGC 能发：证书 / Profile 须链到华为商用根。本工具是「接你 AGC 材料 + 自动化签装验」的适配器，不凭空造信任。
• 模拟器 / OpenHarmony 设备可用 SDK 自带的 OpenHarmony 测试证书本地自签（OpenHarmony.p12 公开密码 123456）——但只对模拟器 / OpenHarmony 有效，纯血真机拒（9568332 sign info inconsistent）。verify 成功不等于真机能装。
• debug 签名要先 hdc 连真机取 UDID（profile 绑该机 UDID）；手机需开发者模式 + USB / 无线调试并弹窗授权。
• 同包名换签名覆盖装会撞 9568332 → 先 hdc uninstall 再装（deploy_to_device 已自动处理）。
• 包名被占（如装已上架 app 撞 205339064）→ rename_bundle 改名再签（⚠️ 改名破坏应用身份，仅侧载 / 自测用）。

已验证

DevEco HarmonyOS 模拟器上，MCP deploy_to_device 五步全绿：

hdc_devices ✓ → hdc_udid ✓ → sign ✓ → install ✓ → verify ✓   （overall ok:true / installed:true / verified:true）

签名走本地 OpenHarmony 自签；纯血真机换 AGC 材料填进同一 config.signing 即走真机路。

License

MIT