JS 编写文档
一个脚本就是一个 .js 文件。没有 import,没有构建,没有依赖清单。
写进去、存下来、点运行,它就在手机上动手。
obaby 一个对象。你能用的 API 全在它下面,没有别的东西可以 import。
最小可用脚本
打开淘宝,等首页出来,点一下签到,写一行日志。
// @permission apps, screen
// @name 每日签到
await obaby.app.launch('com.taobao.taobao')
await obaby.screen.waitFor('首页', 20000)
await obaby.screen.tap('签到')
obaby.log('签到完成')
return { ok: true }
四步落地
- 写文件头:
// @permission声明要用的能力组,// @name给人看的名字。只扫前 20 行。 - 存成脚本:在会话里让它写,或自己用
script_write工具存。id 就是文件名,只能是a-z0-9_-。 - 跑一次:
script_run会弹一次审批,列出脚本名、id、要用的权限。允许之后才开始动。 - 看报告:运行结束返回耗时、设备调用次数、
obaby.log全部输出、以及return的值。
为什么第一个脚本里要 waitFor
app.launch 返回只代表「启动请求发出去了」,不代表界面画好了。
紧接着 tap 大概率点在启动画面上。用 waitFor 等一个只会在首页出现的文字,是唯一稳的做法。
脚本头指令
注释形式,只扫描文件前 20 行。写在后面不生效,不是解析错误——是静默忽略,容易踩。
| 指令 | 作用 | 示例 |
|---|---|---|
| // @permission | 声明要用的权限组,逗号分隔。写 all 表示全部,安装和运行时都会显著提示。 |
// @permission screen, apps |
| // @name | 显示名称,最长 60 字符。不写就用 id。 | // @name 每日签到 |
| // @description | 一句话说明,最长 160 字符。市场列表里显示的就是它。 | // @description 打开淘宝完成签到 |
// @permission screen, apps, clipboard
// @name 批量收藏
// @description 在当前列表页把可见条目逐条收藏,结果写进剪贴板
// ↑ 这三行必须在文件开头 20 行内
运行时与限制
脚本跑在独立的 Worker 线程里,包成 (async () => { … })()。所以顶层 await 能用,
return 的值就是这次运行的返回值。
| 项 | 限制 | 超了会怎样 |
|---|---|---|
| 单次运行 | 默认 120 秒,上限 600 秒 | 强制 terminate Worker,返回已产生的日志 |
| 定时器 | 最多 64 个 | 第 65 个 setTimeout 抛错 |
| 日志 | 200 行 / 8000 字符 | 超出部分丢弃,不报错 |
| 单次 sleep | 1 小时 | 超过按 3600000 毫秒处理 |
| 代码大小 | 本地 256 KB / 市场 64 KB | 写入或安装被拒 |
能用的全局对象
setTimeout / setInterval / clearTimeout / clearInterval /
TextEncoder / TextDecoder / URL / URLSearchParams /
AbortController / console(等同 obaby.log)。
没有 require、没有 process、没有 fetch、没有 Buffer、没有文件系统。
要发请求用 obaby.http,要读文件用 obaby.files。
循环里一定要 sleep
每次 screen.read() 都是一次跨进程调用,开销在几十毫秒量级。
循环里不 sleep 会连续打满设备桥,后面的调用排队超时。批量操作里 await obaby.sleep(500) 不是保守,是必需。
权限模型
权限是声明式的:脚本在文件头写清楚要什么,引擎在每次设备调用前对照。 没声明就调,那一次调用失败并返回明确错误,已经完成的调用不回滚。
一次运行一次审批
script_run 发起一次审批,展示脚本名、id、权限清单。用户允许后整个运行期不再重复弹卡。
设备桥自身按工具 risk 的审批策略保持不变——那是另一层。
十组权限
| 权限组 | 覆盖能力 | 安装时给用户看的文案 |
|---|---|---|
| files | 文件列表 / 读取 / 写入 | 读写手机应用目录内的文件 |
| apps | 应用列表、启动、深链 | 查看并启动已安装应用 |
| screen | 读屏、点按、输入、滑动、等待 | 读取屏幕内容并模拟操作 |
| system | 系统设置类工具 | 修改系统设置 |
| notifications | 通知读取与操作 | 读取和处理通知 |
| comms | 短信 / 联系人 / 通话类工具 | 访问通讯录、短信与通话 |
| media | 相机、相册、录音类工具 | 使用相机、相册与麦克风 |
| clipboard | 剪贴板读写 | 读写剪贴板 |
| browser | 内置浏览器 / 网页自动化 | 控制内置浏览器 |
| rules | 自动化规则 | 创建与修改自动化规则 |
未声明会怎样
调用被拒绝,抛出的错误文案是:
screen_tap needs the "screen" permission;
add "// @permission screen" to the script header
文案里直接告诉你该补哪一行。所以正确的调试姿势不是猜,是把这句话读出来。
权限组与工具前缀的对应
| 工具前缀 | 权限组 |
|---|---|
| screen_* | screen |
| app_* | apps |
| file_* | files |
| clipboard_* | clipboard |
用 obaby.call(tool, args) 直接调工具时,同样按前缀走这套映射。
它绕过了封装,没有绕过权限。
API 参考
下面这些条目从 api.json 渲染,展开看参数、返回值和可直接复制的示例。
顶部搜索框可以按方法名、参数名或描述过滤。
完整示例
三个能直接跑的例子,覆盖「读屏判断 → 批量操作 → 汇总输出」这条最常见的链路。
先给每一页起个名字,再让引擎判断现在在哪。比一串 if (await find(...)) 好读,也好改。
// @permission screen, apps
// @name 发布一条动态
const PAGES = {
feed: { any: ['推荐', '关注'], none: ['发布作品'] },
mine: { all: ['喜欢'], any: ['作品', '收藏'] },
sheet: { any: ['说点什么'] },
done: { any: ['发布成功'] },
}
await obaby.app.launch('com.example.social')
await obaby.page.wait(PAGES, 20000)
// 切到「我的」
await obaby.screen.tap('我')
await obaby.page.wait({ mine: PAGES.mine }, 10000)
// 打开发布面板
await obaby.screen.tap('发布')
const sheet = await obaby.page.wait({ sheet: PAGES.sheet }, 10000)
obaby.log('面板出现,元素数', sheet.elements.length)
await obaby.screen.type('今天跑通了脚本')
await obaby.screen.tap('发布')
// 等弹窗关掉、等成功提示
await obaby.page.waitGone('sheet', PAGES, 15000)
const ok = await obaby.page.wait({ done: PAGES.done }, 15000)
obaby.log('发布结果', ok.state)
return { ok: true }
memo.mark 第一次返回 true,之后返回 false。
把「要不要处理」交给它,脚本就不需要自己维护去重表。
// @permission screen, clipboard
// @name 逐条收藏
const TABLE = 'collected'
let done = 0
for (let page = 0; page < 5; page += 1) {
const rows = await obaby.screen.findAll('收藏')
obaby.log('本页可操作', rows.length)
for (const row of rows) {
// 用元素坐标当 key:同一条目在同一位置重复出现时只处理一次
const key = `${row.x},${row.y}`
if (!(await obaby.memo.mark(TABLE, key))) continue
await obaby.screen.tap(row.id)
done += 1
await obaby.sleep(600)
}
await obaby.screen.scroll('down')
await obaby.sleep(800)
}
const total = await obaby.memo.count(TABLE)
await obaby.clipboard.set(`本次 ${done} 条,累计 ${total} 条`)
obaby.log('本次', done, '累计', total)
return { done, total }
读屏拿文本、正则抠数字、本地汇总、HTTP 上报。四步拆开写,哪一步失败日志里一眼能看出来。
// @permission screen, files
// @name 价格汇总
const rows = await obaby.screen.findAll(/¥\s*\d+/)
obaby.log('抓到', rows.length, '个价格')
const prices = rows
.map(r => Number(String(r.text).replace(/[^\d.]/g, '')))
.filter(n => Number.isFinite(n) && n > 0)
if (prices.length === 0) {
obaby.warn('页面上没有价格,可能还没加载完')
return { ok: false, reason: 'no-price' }
}
const stat = {
count: prices.length,
min: Math.min(...prices),
max: Math.max(...prices),
avg: Math.round(prices.reduce((a, b) => a + b, 0) / prices.length),
}
// 落到文件,方便下次比对
await obaby.files.write(
'/sdcard/Download/price-report.json',
JSON.stringify({ at: Date.now(), ...stat }, null, 2),
)
const res = await obaby.http('https://httpbin.org/post', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: stat,
})
obaby.log('上报', res.status, res.ok ? '成功' : '失败')
return stat
调试与日志
没有断点,没有单步。能用的只有日志、返回值和错误文案——所以日志要写得像证据。
三个日志级别
obaby.log('第', page, '页,找到', rows.length, '条') // 普通
obaby.warn('价格没读到,走备用路径') // 值得注意
obaby.error('登录态失效,停止') // 决定中止
多个参数用空格拼接。传对象会转成 JSON,传 Error 会转成 Name: message。
超过 200 行或 8000 字符后新日志被丢弃——别在循环里逐条打日志,打摘要。
把中间状态塞进返回值
return 的值会出现在运行报告里,比翻日志快。
调试阶段直接 return { pages: seen, hits },看一眼就知道卡在哪一页。
先降级,再报错
设备上的失败大多是「还没准备好」,不是「做不了」。先 waitFor、再 find 重试、
最后才抛错。抛错时把当前屏幕的关键文本带上,下一次调试能少跑一轮。
async function tapWithRetry(text, times = 3) {
for (let i = 1; i <= times; i += 1) {
const hit = await obaby.screen.find(text)
if (hit !== undefined) {
await obaby.screen.tap(hit.id)
return true
}
obaby.warn(`第 ${i} 次没找到「${text}」,等 800ms`)
await obaby.sleep(800)
}
const snapshot = await obaby.screen.read()
throw new Error(`找不到「${text}」,当前屏幕前 200 字:${snapshot.slice(0, 200)}`)
}
发布到市场
市场里的脚本用户点一下就能装。要进市场,先过这几条硬门槛。
| 要求 | 说明 |
|---|---|
| 源码可读 | 禁止混淆、压缩。用户有权看到自己要跑的东西 |
| 权限与行为一致 | 声明了什么就只做什么;声明外的网络外发一律拒绝 |
| 单文件 ≤ 64 KB | 超过说明该拆成多个脚本,或者该做成插件 |
| 版本号递增 | 语义化版本,1.0.2 这种 |
| 附使用说明 | 适用哪些 App、哪些页面、需要什么前置条件 |
| id 合法 | ^[a-z0-9][a-z0-9_-]{0,47}$,发布后不改 |
仓库结构
scripts/
└── daily-checkin/
├── 1.0.2.js 脚本本体
├── meta.json 名称、描述、分类、标签、权限
└── icon.png 128×128,可选
# CI 读取上面的内容,生成 index.json:
# 算 sha256、校验 id / 权限 / 大小、按分类归档
# 发布到 https://box.fiime.cn/scripts/
meta.json
{
"name": { "zh": "每日签到", "en": "Daily check-in" },
"description": { "zh": "打开淘宝完成签到", "en": "Open Taobao and check in" },
"author": "O宝官方",
"category": "daily",
"tags": ["签到", "淘宝"],
"permissions": ["apps", "screen"]
}
category 只能用固定 id:daily / shopping / social /
efficiency / system / other。中文名由 App 本地化,不要写进 meta。
更新与撤回
- 更新:加一个新的版本文件、改
meta.json的版本、让 CI 重算 sha256 与索引。用户端显示「可更新」,由用户确认后才装。 - 撤回:从索引移除条目。已装副本继续能用,但不再收到更新提示。
- 首版没有自动更新。这是刻意的:脚本能点屏幕,不该在用户不知情时换掉。
script_run 直接跑。本地脚本和市场脚本的运行时完全一样。