{
  "markdown": "# HapLane\n\n> 鸿蒙 HAP 一键签名 · 调试 · 部署 —— **CLI + MCP，agent 可驱动**。\n> 封装华为官方工具链（`hvigorw` / `hap-sign-tool` / `hdc`），把散在文档里的命令拼成一条可脚本、可 `--dry-run`、可让 AI 调用的链。零运行时依赖（纯 Node stdlib）。\n>\n> 开源 MIT · 不破解 · 不逆向 · 签名走你自己的 AGC 凭据。\n\n- 官网：https://leonting1010.github.io/haplane/\n- npm：`haplane` · Gitee：https://gitee.com/LeonTing1010/hap-deploy · GitHub：https://github.com/LeonTing1010/hap-deploy-cli\n\n## 装\n\n```bash\nnpm i -g haplane          # 已上 npm，国内把 registry 设成 npmmirror 更快\n# 或从 Gitee Release 直连下单文件（网络拉不动 npm 时）：\n#   https://gitee.com/LeonTing1010/haplane/releases\n```\n\n## 接入 MCP（挂进你的 AI）\n\nHapLane 是标准 stdio MCP server（JSON-RPC 2.0，协议 2024-11-05）。粘一段配置就接上，支持 Claude Code / Cursor / Cline / DevEco Code 等任意 MCP 客户端。\n\n```json\n{\n  \"mcpServers\": {\n    \"haplane\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"-p\", \"haplane\", \"haplane-mcp\"]\n    }\n  }\n}\n```\n\n国内网络拉不动 npm 时，下载 [`haplane-mcp.mjs`](https://gitee.com/LeonTing1010/haplane/releases) 放本地，改成 `\"command\": \"node\"`, `\"args\": [\"/你的路径/haplane-mcp.mjs\"]`。\n\n接上后在 AI 里直接说：「把 `./app.hap` 签名装到我手机上」——agent 自己调 `deploy_to_device`，撞 system 权限自动降级重装，装完验签。\n\n### 13 个 MCP 工具\n\n> **HapLane 是中性工具,自身不内嵌任何应用内容。** 可搜可装的条目来自你**订阅的源**(registry index.json,apt/sources.list 模型);默认订阅官方源、可退订。工具指向上游权利人官方发布位,不托管/不转存二进制。详见 [分发合规边界](https://gitee.com/LeonTing1010/haplane-registry)。\n\n| 工具 | 作用 |\n|---|---|\n| **`deploy_to_device`** | **核心编排**：连设备 → 取 UDID → 读包名 → 签名 → 装机 → 验签，一步到位。`app:<id>` 从订阅源解析→上游拉取直接装；撞 `9568332` 签名不一致自动卸旧重装；撞 `9568289` 权限被拒**自动降级**（逐个剥掉被拒权限重签重装，实测 3 连剥后装上） |\n| `doctor` | 自检工具链（hvigorw/java/hap-sign-tool/hdc）与签名材料是否就位 |\n| `hdc_devices` | 列联机设备 |\n| `search_hap` | 在你**订阅的源**里搜 HAP 资源（可多源，结果带 `registryId` 标来源）：非 `discoveryOnly` 条目可直接 `deploy_to_device{app:id}` 从上游拉 + sha256 校验 + 签装 + HAP Store 开放接口（只发现给源站链接，不代下不转存不绕登录） |\n| `list_sources` | 列出当前订阅的 registry 源（只读）；增删订阅走 CLI `haplane source add/remove/reset` |\n| `hdc_udid` | 取设备 UDID（真机 debug 签名 / Profile 绑定所需） |\n| `sign` | `hap-sign-tool sign-app` 签名 |\n| `install` | `hdc install -r` 装到设备 |\n| `verify` | `hap-sign-tool verify-app` 验签 |\n| `gen_signing_material` | 生成 OpenHarmony 本地自签材料（绑包名 + UDID） |\n| `rename_bundle` | 包名全局占用时改 HAP 的 bundleName 再签（纯 Node 重打包） |\n| `agc_status` | 用 client_credentials 查 AGC：appId / 设备用量 / 现有 Profile |\n| `agc_provision` | 只读计划器：自检还差哪几步一次性配置 |\n\n配置与密码走 `HAP_DEPLOY_CONFIG` 指向的配置文件 + `.env`（自动加载），**不入 MCP 参数**；stdout 只出协议 JSON，日志走 stderr。\n\n## 也能命令行直接用\n\n```bash\nhaplane setup                 # 首次：自动探测 SDK + 生成配置与 .env 模板\nhaplane doctor                # 体检工具链与签名材料\nhaplane device                # 列设备 + 打印 UDID\nhaplane source list           # 看订阅了哪些源(默认官方源,可 add/remove/reset)\nhaplane source add <url>      # 订阅一个 registry 源(index.json URL)\nhaplane search 浏览器          # 在订阅源里搜:可装条目直接装,discoveryOnly/HAP Store 给源站链接\nhaplane deploy --app linysbrowser   # 从订阅源解析 → 上游拉 → sha256 校验 → 签名 → 装机 → 验签\nhaplane deploy --in app.hap   # 对现成 HAP：签名 → 装机 → 验签\nhaplane deploy                # 从源码工程全链：hvigorw 打包 → 签名 → 装机 → 验签\nhaplane deploy --in app.hap --target <设备>   # 多台设备时指定装哪台(设备键用 device 命令看)\nhaplane sign|install|verify --in app.hap   # 单步执行\n```\n\n全局：`--config <path>` · `--dry-run`（只打印命令不真跑，无真机也能看全链）· `--verbose` · `--in <hap>` · `--target <设备>`\n\n## 配置与密码\n\n复制 `hap-deploy.config.example.json` 为 `hap-deploy.config.json`，填 SDK 路径 + 签名材料路径。**密码只从环境变量读，绝不入配置 / 日志**：\n\n```bash\n# 写进 .env（自动加载，免 export）\nHAP_KEY_PWD=***\nHAP_KEYSTORE_PWD=***\n```\n\n## 认证：三条路，选最白那档\n\n给 AGC 打交道有三种方式，推荐机器密钥：\n\n- 🟢 **`client_credentials` 机器密钥（推荐）**：AGC 控制台铸 `client_id` / `secret` → 换 Bearer token。无交互登录、可吊销、可审计。凭据走 env `AGC_CLIENT_ID` + `AGC_CLIENT_SECRET`（或直接 `AGC_TOKEN`）。\n- 🟡 `deveco login` 的 cookie 会话：只连 DevEco AI 助手，**根本不碰 AGC**，与签名无关。\n- 🔴 寄生会话（抓登录 session 冒充调网页 API）：不可审计，本工具不用。\n\n> 关键坑：请求头 `client_id` 必须匹配 token 的 `sub`，否则 401。\n\n## 老实说：它不做什么 · 前提\n\n**不做**\n- 不破解、不绕过签名——只帮你把该走的流程走顺\n- 只处理你自己或已授权的设备 / 账号\n- 不碰纯血鸿蒙真机的商用根：真机走你自己的 AGC 材料\n\n**前提**\n- 华为开发者账号 + AGC（真机 / 上架签名要）\n- 华为 SDK：`hdc` / `hap-sign-tool` / `java`（各平台官方版都有，几 G，华为官网装）\n- Node ≥ 18；macOS / Windows / Linux 都行\n\n## 签名的物理约束（必须知道）\n\n- **纯血鸿蒙真机的信任只有 AGC 能发**：证书 / Profile 须链到华为商用根。本工具是「接你 AGC 材料 + 自动化签装验」的适配器，不凭空造信任。\n- **模拟器 / OpenHarmony 设备**可用 SDK 自带的 OpenHarmony 测试证书本地自签（`OpenHarmony.p12` 公开密码 `123456`）——但**只对模拟器 / OpenHarmony 有效，纯血真机拒**（`9568332 sign info inconsistent`）。`verify` 成功不等于真机能装。\n- **debug 签名要先 hdc 连真机取 UDID**（profile 绑该机 UDID）；手机需开发者模式 + USB / 无线调试并弹窗授权。\n- 同包名换签名覆盖装会撞 `9568332` → 先 `hdc uninstall` 再装（`deploy_to_device` 已自动处理）。\n- 包名被占（如装已上架 app 撞 `205339064`）→ `rename_bundle` 改名再签（⚠️ 改名破坏应用身份，仅侧载 / 自测用）。\n\n## 已验证\n\nDevEco HarmonyOS 模拟器上，MCP `deploy_to_device` 五步全绿：\n```\nhdc_devices ✓ → hdc_udid ✓ → sign ✓ → install ✓ → verify ✓   （overall ok:true / installed:true / verified:true）\n```\n签名走本地 OpenHarmony 自签；纯血真机换 AGC 材料填进同一 `config.signing` 即走真机路。\n\n## License\n\nMIT\n",
  "bytes": 4742,
  "sha": "8afaaf4c6f378a9dac6e27b585e903312f3bffd142b663f5d0ac9872b0bf2867",
  "repo_slug": "leonting1010/hap-deploy-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_leonting1010_haplane_1ac030f4/readme"
}