FiimeOPC 衍生智能产品 · 基于 DSH 开发 opc.fiime.cn

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 等一个只会在首页出现的文字,是唯一稳的做法。

运行时与限制

脚本跑在独立的 Worker 线程里,包成 (async () => { … })()。所以顶层 await 能用, return 的值就是这次运行的返回值。

项限制超了会怎样
单次运行默认 120 秒,上限 600 秒强制 terminate Worker,返回已产生的日志
定时器最多 64 个第 65 个 setTimeout 抛错
日志200 行 / 8000 字符超出部分丢弃,不报错
单次 sleep1 小时超过按 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 直接跑。本地脚本和市场脚本的运行时完全一样。