phonebase-cli-sdk

English | 中文

phonebase-cli 的 Node.js SDK — 在 skill 脚本中自动化 Android 云手机。

安装

npm install phonebase-cli-sdk

Skill 脚本无需手动安装。 SDK 已预装在 ~/.phonebase/node_modules/phonebase-cli-sdk/，所有 skill 脚本中直接 require('phonebase-cli-sdk') 即可使用。

快速上手

const pb = require('phonebase-cli-sdk');
const { waitForActivity, success } = require('phonebase-cli-sdk/utils');

(async () => {
  // 连接设备
  await pb.call('connect', { target: '192.168.180.24' });

  // 启动应用
  await pb.call('launch', { package_name: 'com.example.app' });
  await waitForActivity('com.example.app');

  // 交互
  await pb.call('tap', { x: 540, y: 960 });
  await pb.call('text', { text: '你好' });

  // 读取界面
  const tree = await pb.dump();
  success({ nodes: tree });
})();

API

pb.call(command, [subcommand], [args])

调用任意能力，返回 Promise。

// 命令 + 参数
await pb.call('tap', { x: 540, y: 960 });

// 命令 + 子命令 + 参数
await pb.call('package', 'info', { package_name: 'com.example' });

// 原始接口路径
await pb.call('input/click', { x: 100, y: 200 });

连接

// 通过 IP 连接
await pb.call('connect', { target: '192.168.180.24' });

// 通过设备码连接
await pb.call('connect', { target: 'my-device-code' });

// 断开连接
await pb.call('disconnect');

// 查看已连接设备（含延迟和 API 版本）
const result = await pb.call('devices', 'list', { connected: true });

设备控制

| 命令 | 示例 | |------|------| | tap | pb.call('tap', {x, y}) | | swipe | pb.call('swipe', {start_x, start_y, end_x, end_y}) | | text | pb.call('text', {text}) | | keyevent | pb.call('keyevent', {key_code}) | | launch | pb.call('launch', {package_name}) | | force-stop | pb.call('force-stop', {package_name}) | | top-activity | pb.call('top-activity') | | screencap | pb.call('screencap') / pb.call('screencap', {base64: true}) | | clipboard | pb.call('clipboard') / pb.call('clipboard', {text}) | | shell | pb.call('shell', {command}) | | browse | pb.call('browse', {url}) | | packages | pb.call('packages') | | node | pb.call('node', {text: '...', click: true}) | | proxy | pb.call('proxy') / pb.call('proxy', {url: [...]}) |

截图

// 保存到默认路径（.phonebase/screencap/）
const result = await pb.call('screencap');
// { mode: "file", path: ".../.phonebase/screencap/20260526/device-20260526172506.jpg", size: 177160, format: "jpg" }

// 保存到指定文件（格式从扩展名推断）
await pb.call('screencap', { output: '/tmp/shot.webp' });

// 保存到目录（自动生成文件名）
await pb.call('screencap', { output: '/tmp/', format: 'png' });

// 返回 base64 字符串（不保存文件）
const img = await pb.call('screencap', { base64: true });
// { mode: "base64", data: "iVBOR...", size: 177160, format: "jpg" }

// 指定质量和尺寸
await pb.call('screencap', { format: 'webp', quality: 50, width: 720 });

| 参数 | 类型 | 默认 | 说明 | |------|------|------|------| | output | string | 自动生成 | 保存路径（文件或目录） | | format | string | "jpg" | 图片格式：jpg、webp、png | | quality | int | 80 | JPG/WebP 质量 1-100 | | width | int | - | 缩放宽度 | | height | int | - | 缩放高度 | | base64 | bool | false | 返回 base64 字符串，不保存文件 |

UI 层级

| 方法 | 返回 | 说明 | |------|------|------| | pb.dump() | Object | 完整 UI 层级，解析后的 JSON 对象 | | pb.dumpc() | Object | 精简 UI 层级，解析后的 JSON 对象 | | pb.dumpText() | string | 完整 UI 层级，XML 字符串 |

pb.close()

关闭 WebSocket 连接。skill 脚本不需要调用 — 进程退出时连接自动关闭。

工具函数

const { sleep, waitForNode, waitForNodeAction, waitForActivity, findNode, findAll, randomPointInBounds, success, failure } = require('phonebase-cli-sdk/utils');

| 函数 | 说明 | |------|------| | sleep(ms) | 延时 | | waitForNode(selector, timeout?, interval?) | 等待 UI 节点出现 | | waitForNodeAction(selector, action, timeout?, interval?) | 等待节点 + 执行操作 | | waitForActivity(activity, timeout?, interval?) | 等待 Activity 到前台 | | findNode(tree, matcher) | 查找第一个匹配的节点 | | findAll(tree, matcher) | 查找所有匹配的节点 | | randomPointInBounds(bounds) | 在节点 bounds 内生成随机坐标 {x, y} | | success(data, msg?) | 输出成功 JSON 并退出 | | failure(err, code?) | 输出错误 JSON 并退出 |

Skill 开发

Skill 脚本使用预装的 SDK：

const pb = require('phonebase-cli-sdk');
const { waitForNode, success, failure } = require('phonebase-cli-sdk/utils');

Skill 脚本中可用的环境变量：

| 变量 | 说明 | |------|------| | SKILL_RUNTIME_NAME | 当前 skill 名称 | | SKILL_RUNTIME_DIR | skill 目录路径 | | SKILL_RUNTIME_DEVICE_ID | 已连接的设备 ID | | SKILL_RUNTIME_LOCALE | 客户端语言 | | SKILL_META_* | SKILL.md frontmatter 字段 |

环境要求

• Node.js >= 18
• PhoneBase CLI 已安装（npm install -g phonebase-cli）