device-agent

device-agent 是远程设备平台中的设备侧 CLI，负责扫描本地设备、管理外部连接进程，并把在线设备注册到 Nacos。

当前已支持通过 npm 安装后的 CLI 方式运行。

功能概览

• 初始化配置文件
• 检查运行依赖
• 启动 agent 主流程
• 停止本地 agent 管理的运行态
• 扫描 Android 设备
• 管理 sonic-android-supply 进程
• 向 Nacos 注册、发送心跳、注销设备实例

运行依赖

在启动前请确保目标机器已准备：

• Node.js 20+
• npm 或 pnpm
• adb
• sonic-android-supply
• 可访问的 Nacos 服务

安装方式

方式一：源码目录内运行

cd device-agent
pnpm install
pnpm dev start --config ./device-agent.config.json

方式二：通过 npm 官方仓库安装 CLI

直接安装：

npm install -g remote-device-agent

安装后可直接执行：

remote-device-agent init
remote-device-agent doctor --config ./device-agent.config.json
remote-device-agent start --config ./device-agent.config.json
remote-device-agent stop --config ./device-agent.config.json

初始化配置

生成默认配置文件：

remote-device-agent init

默认会在当前目录生成：

device-agent.config.json

也可以显式指定路径：

remote-device-agent init --config ./configs/device-agent.config.json

如果目标目录不存在，命令会自动创建父目录。

常用命令

检查环境

remote-device-agent doctor --config ./device-agent.config.json

启动 agent

remote-device-agent start --config ./device-agent.config.json

停止 agent

remote-device-agent stop --config ./device-agent.config.json

配置说明

建议从示例配置开始：

• device-agent.config.example.json

关键配置项包括：

• agent.host：agent 对外可访问地址
• agent.heartbeatIntervalSeconds：心跳间隔
• agent.scanIntervalSeconds：扫描间隔
• nacos.scheme/host/port/namespace/serviceName/groupName：Nacos 连接配置
• nacos.username/password：Nacos 鉴权配置
• android.adbPath：本机 adb 路径
• android.supplyPath：本机 sonic-android-supply 路径

后台运行建议

当前不内建 daemon 模式，建议通过外部进程管理器后台运行。

使用 pm2

pm2 start "remote-device-agent start --config ./device-agent.config.json" --name remote-device-agent

停止：

pm2 stop remote-device-agent

查看日志：

pm2 logs remote-device-agent

发布前验证

可使用以下命令验证当前版本可发布到 npm 官方仓库：

pnpm publish:check

该命令会先构建，再执行：

npm publish --dry-run

发布到 npm 官方仓库

发布前准备：

1. 先使用 npm 账号完成登录：

npm login

2. 确保本次发布版本号已更新，npm 不支持覆盖同版本。

发布步骤：

pnpm test
pnpm publish:check
npm publish --access public

发布成功后，可在其他机器上直接安装：

npm install -g remote-device-agent

测试

pnpm test

当前边界

• 当前优先支持 Android 主链路
• adb 与 sonic-android-supply 仍需由目标机器自行准备
• 当前不内建后台守护、自恢复与系统服务安装能力