android-device-hub

Android Device Hub（CLI 短名：adh）——本机跑的 Android 设备工具箱。 抓 logcat、跑 adb 命令、投屏镜像、批量操作多机、与 App 内白盒通信。所有控制都在本机完成，没有公网回传设备数据。

公网 SPA（只托管前端）： https://andevhub.pages.dev
浏览器打开该站 → 本机跑 adh（127.0.0.1:10987）→ 只操作你自己连上的手机。互不共享设备。部署说明见 docs/deploy-hub.md。

快速开始

前置：Node.js ≥ 18（nodejs.org 下 LTS）。

推荐：公网 SPA + 本机 adh

1. 浏览器打开 https://andevhub.pages.dev
2. 本机启动 adh（npm 包暂未上架时从仓库构建）：

git clone <本仓库 URL> && cd android-device-hub
yarn install && yarn build
node bin/adh-desktop.js

3. USB / 无线连上手机后，在公网 SPA 里操作。

npm 全局安装（包发布后）

npm i -g android-device-hub
adh setup

adh setup 会一次性帮你做完：停掉旧 helper → 注册 adh:// URL Scheme → 在后台启动 helper（日志见 ~/AndroidDeviceHub/logs/helper.log）→ 可到公网 SPA 或本机服务页使用。

升级 = 重跑：

npm i -g android-device-hub@latest && adh setup

临时试用，不装到本机：

npx -y android-device-hub@latest setup

卸载：

adh unregister                          # 撤销 adh:// URL Scheme
npm uninstall -g android-device-hub
# 可选: rm -rf ~/.adh ~/Downloads/deviceManager   # 清用户数据 + 截图

国内网络慢、内网离线、用自己的 adb、PWA 装到桌面，详见 [docs/desktop-helper.md](./docs/desktop-helper.md)。

装好以后能干嘛

打开 http://127.0.0.1:10987/ 进入 Web 面板。路由：

| 路径 | 干啥 | | --------------------------- | -------------------------------------------------------------------- | | /devices | 设备总览，多机并列；点设备进入详情 | | /devices/:serial/commands | 35+ 条 ADB 命令的可视化表单，每条都有 JSON Schema | | /devices/:serial/apps | 应用维度面板：装/卸/清数据/导 APK/启动 Activity/权限管理/多用户 | | /devices/:serial/network | 网络一键切换：Wi-Fi / 移动数据 / 飞行模式 / 代理 / Private DNS / 安装根证书 | | /devices/:serial/logs | logcat 实时流 + 过滤 + 落盘 | | /devices/:serial/files | 设备文件树 + 拉取 / 推送 | | /devices/:serial/control | 通过 device-control v1 协议 跟 App 内 SDK 通信 | | /batch | 多机并发：批量装包 / 卸载 / 清数据 / 跑同一条 ADB | | /registry | 命令注册中心：所有设备×App 的命令清单、版本 diff、漂移监控、导出 Markdown / MCP |

镜像（投屏控制）是悬浮窗，由设备卡片的镜像按钮拉起。详见 [docs/refs/web-platform.md](./docs/refs/web-platform.md)。

模块详情：Apps 设计 · Network 设计 · 批量执行 · Registry 设计。

CLI 速查

adh 也是一个完整的命令行工具。常用：

adh setup                                   # 一键初始化（首装 / 升级后跑一次）
adh serve --port 10987 --open               # 前台跑 helper

adh adb device.info                         # 跑一条 ADB 工具箱命令
adh adb input.tap '{"x":500,"y":1000}'
adh shot ./out.png                          # 顶层快捷键 == adh adb screen.capture

adh capture --serial emulator-5554 \
            --tags hot.rct.native.Log \
            --format jsonl --out logs.ndjson

adh listen --port 10987                     # 当 device-control v1 的 host
adh cmd biz.echo '{"x":42}' --port 10987    # 单发一帧
adh wait --port 10987                       # 等设备 client 接上

adh adb-catalog --format md > cmds.md       # 导出工具箱命令清单

完整子命令清单见 adh --help 或 [docs/refs/cmd-catalog-host.md](./docs/refs/cmd-catalog-host.md)。

作为库使用

android-device-hub 同时是个可程序化的 npm 包。三个高频入口：

1. 抓 logcat

import { startCapture } from 'android-device-hub';

const handle = await startCapture({
  serial: 'emulator-5554',
  packageName: 'com.example.app',
  tags: ['hot.rct.native.Log', 'NORMAL'],
  format: 'jsonl',
  out: './captures/logcat.ndjson',
  onLine: (line) => {},
});

await handle.stop();

返回 CaptureHandle：stop() / getLines() / getDeviceSerial()。详见 src/capture.ts JSDoc。

2. ADB 工具箱（本机直接调用，不走 WS）

import { createAdbToolbox } from 'android-device-hub';

const adb = createAdbToolbox({ serial: 'auto' });
await adb.run('device.info');
await adb.run('input.tap', { x: 500, y: 1000 });
await adb.run('screen.capture', { outPath: './shot.png' });

adb.getCatalog(); // CommandSpec[] - JSON Schema 可读

命名空间：system.* device.* app.* screen.* input.* lifecycle.* fs.* net.* prop.* logcat.* shell.*。完整规范 [docs/refs/cmd-spec.md](./docs/refs/cmd-spec.md)。

3. device-control v1（host ↔ App 内 SDK）

WebSocket + JSON 的双向通道，跑在 App 进程里。Host 端：

import { ControlServer } from 'android-device-hub';

const server = new ControlServer({ port: 10987, host: '127.0.0.1' });
server.on('hello', (pkg, h) => console.log(`hello from ${pkg}`, h.app));
await server.start();

await server.waitForAnyClient(15_000);
const reply = await server.send(server.solePackage(), 'biz.echo', { x: 42 });
console.log(reply.result); // { x: 42 }

App / 设备端：

• Android Java/Kotlin：[clients/android/](./clients/android/) + 可装 demo APK [clients/android/sample-app/](./clients/android/sample-app/)
• React Native (TS)：[clients/rn-ts/](./clients/rn-ts/)
• 纯 Node：直接 import { ControlClient } from 'android-device-hub'

协议规范 [docs/refs/protocol-v1.md](./docs/refs/protocol-v1.md)，6 个推荐 namespace（debugFlag/state/config/scene/event/mock）见 [docs/refs/ws-namespaces.md](./docs/refs/ws-namespaces.md)。

2026 改版：一台手机上多 App 共存。ControlServer 以 (serial, package) 寻址，SPA /registry 聚合所有 (serial × package) 的命令清单 + 历史 diff + 漂移监控。详见 [docs/ws-app-contrl/06-registry-page.md](./docs/ws-app-contrl/06-registry-page.md)。

开发 / 贡献

git clone https://github.com/ronindong/android-device-hub.git
cd android-device-hub
yarn install
yarn build:all                          # Node 端 + Vite SPA
yarn test                               # vitest run
yarn web:dev                            # SPA dev server (Vite HMR)
npm i -g .                              # 把当前 checkout 软链到全局 adh

仓库结构：

src/                    Node 端（CLI / server / ADB toolbox / control 协议）
web/                    Vite + React SPA
clients/android/        Android SDK（含 sample-app demo）
clients/rn-ts/          React Native client
bin/                    分发到 npm 包的 launcher（adh-desktop / adh-launch）
scripts/                构建 / 发布脚本 + postinstall（拉 platform-tools，自动注册 adh:// 协议）
docs/refs/              规范类参考文档（协议、配置、CLI catalog）
docs/ws-app-contrl/     device-control v1 设计稿

测试是 Node 内 server + client loopback，不依赖真机。

发布新版到 npm registry

# 1. 改版本号（不让 npm version 自动 git tag，避免和 release.sh 抢）
npm version patch --no-git-tag-version

# 2. commit + push 源
git commit -am "release v$(node -p 'require(\"./package.json\").version')"
git push origin main

# 3. release.sh 全程负责：构建 + 校验 tarball + git tag + push tag + npm publish
./scripts/release/release.sh

# 仅打包不发布
./scripts/release/release.sh --dry-run

# 预发布通道（不影响 latest，用户要 @beta 显式拿）
./scripts/release/release.sh --npm-tag beta

scripts/release/pack.sh 可单独跑，只构建 + 打包 + 校验 tarball 内容（产物在 release-packs/），用于 CI 或本地 smoke test。

配置文件 / 环境变量

helper 启动时按以下优先级解析配置：CLI flag > 环境变量（ADH_*） > ~/.adh/adh.config.json > 仓库内 adh.defaults.json。完整字段表 [docs/refs/config.md](./docs/refs/config.md)。

常见 env：

| Var | 作用 | | ------------------- | --------------------------------------------- | | ADH_WEB_PORT | helper HTTP 端口（默认 10987） | | ADH_DEVICES_DIR | 设备文件根目录（截图 / 录屏 / logcat / APK 导出） | | ADH_ADB_PATH | 强制指定 adb 路径，否则按 vendored → PATH 兜底 | | ADH_LOG_LEVEL | trace / debug / info / warn / error | | ADH_ENABLE_AGENTS | 默认开（阶段 B）；=0 强制关闭 USB Agent ingress |

License

MIT