开发者文档
O宝 是 FiimeOPC 的衍生智能产品,基于 DSH 开发,面向 OPC FDE 与企业老板的私人 Agent 助理:模型负责拆步骤,引擎负责把步骤落到手机上。 这份文档写给要往里加东西的人——加一个工具、加一个插件、写一个脚本,或者把引擎接到自己的 App 里。
这份文档覆盖什么
| 层 | 技术栈 | 职责 | 代码位置 |
|---|---|---|---|
| App | Kotlin / Compose | 会话界面、模式选择、脚本市场页、设备能力实现 | app/src/main/java/com/fiimedev/obaby |
| 引擎 | Node 24 / libdshnode.so | 模型接入、工具调度、插件加载、脚本存储与运行 | js/packages |
| 沙箱 | node:worker_threads + vm | 单次脚本执行的隔离上下文 | js/packages/plugin-scripts/worker.js |
| 设备桥 | Kotlin | 读屏、点按、文件、剪贴板等真实设备操作 | capability/invoke |
四层之间只有两条数据通道:引擎向下发 capability/invoke 请求设备能力,
设备桥向上返回文本结果。脚本不直接接触设备桥,它只接触 obaby 对象。
四层架构
每一层只依赖下一层的公开接口,替换其中一层不影响其它层。这个约束是为了让脚本、插件、设备能力可以各自演进。
┌──────────────────── App (Kotlin / Compose) ────────────────────┐
│ 会话界面 Composer「指定脚本」 脚本市场页 设置·扩展入口 │
│ │ │ │ │ │
│ │ android/session/mode │ android/scripts/* │
└─────┼──────────────┼──────────────────┼──────────────┼──────────┘
▼ ▼ ▼ ▼
┌──────────────── Engine (Node 24, libdshnode.so) ────────────────┐
│ plugin-mode plugin-scripts │
│ · 工具过滤 · script_list / read / write / delete │
│ · 模式提示词 · store.js(唯一写入者) │
│ · skills 关闭 · runtime.js + worker.js(隔离执行) │
│ · market.js(索引缓存 / 下载 / 校验) │
└──────────────────────────────┬──────────────────────────────────┘
▼ capability/invoke
┌──────────────────── App 设备能力层 ─────────────────────────────┐
│ screen_* / app_* / file_* / clipboard_* …,按 risk 审批 │
└──────────────────────────────┬──────────────────────────────────┘
▼
https://box.fiime.cn/scripts/index.json
index.json + code/<id>-<version>.js + icons/
唯一写入者原则
脚本文件、index.json、market.json 全部由引擎 plugin-scripts 写入。
App 侧只读,或通过 SDK 方法请求引擎写。这条规则是为了避免 App 与引擎同时改同一个文件导致的覆盖。
为什么沙箱不是安全边界
vm 加 Worker 只做两件事:隔离 API 面、防止脚本阻塞主线程。
它挡不住恶意代码——Node 的 vm 从来不是安全边界。真正的约束在三处:
父进程按声明权限放行、每次运行的一次性审批、市场安装前的人工审核。
三条关键流程
其余功能都从这三条派生。看懂这三条,改动就不会走错层。
A · AI 写脚本并运行
- 会话模式为
script,plugin-mode注入脚本提示词,保留script_*、文件读取、网络与屏幕工具。 - 模型写脚本 →
script_write存到$DSH_HOME/scripts/<id>.js并更新index.json。 - 模型
script_run→ 引擎读文件、解析// @permission→ 发起一次审批(名称 / id / 权限清单)。 - 用户允许 → Worker 执行;每次
obaby.*设备调用先按声明权限组校验,再走设备桥(桥内还有各自的 risk 审批)。 - 返回运行报告:耗时、设备调用次数、
obaby.log输出、最终返回值;失败同样返回文本并附日志。
B · 用户在单条消息上指定脚本
- Composer 加号菜单 →「指定脚本」→ 读
index.json列出脚本(空态引导去市场)。 - 选中后正文上方出现脚本 chip;再次选择可更换或取消。
- 发送时正文前缀「使用脚本 <名称>(<id>)」+ 用户原文;发送成功后 chip 与选择自动清除。
- 当前模式禁用
scripts工具时,已选脚本自动清除。
C · 市场安装
- 市场页 →
android/scripts/market/list(缓存优先,refresh时回源)。 - 用户点安装 → 确认面板展示权限清单、来源、sha256 短码、大小 →
android/scripts/market/install。 - 引擎下载代码 → 校验大小、id、
sha256、// @permission与索引声明一致 →store.saveScript写入 → 记录market.json。 - 返回安装结果;市场页刷新为「已安装 / 可更新」。
目录与数据文件
脚本相关的一切都在 $DSH_HOME/scripts 下。这个目录是引擎的私有区,App 不直接读写。
$DSH_HOME/
└── scripts/
├── <id>.js 脚本代码(单文件,UTF-8)
├── .memo/<name>.json 脚本的去重记录(obaby.memo 写,App 不读)
├── index.json 本地脚本索引(引擎写)
├── market.json 市场安装记录(引擎写)
└── market-cache.json 远端索引缓存(引擎写)
字段规则
| 字段 | 规则 |
|---|---|
| id | 匹配 ^[a-z0-9][a-z0-9_-]{0,47}$,同时是文件名与市场主键 |
| name | ≤ 60 字符 |
| description | ≤ 160 字符 |
| 代码大小 | 本地 ≤ 256 KB;市场 ≤ 64 KB |
| permissions | 由代码头解析得到;索引中的值必须与代码一致,不一致拒绝安装 |
| 脚本数量 | 本地最多 200 个 |
| 缓存有效期 | market-cache.json 超过 10 分钟视为过期 |
index.json
本地脚本索引。引擎在每次写入或删除脚本后重写整份文件。
{
"version": 1,
"scripts": [
{
"id": "daily-checkin",
"name": "每日签到",
"description": "打开淘宝完成签到",
"updatedAt": 1763616000000,
"permissions": ["apps", "screen"],
"bytes": 4821
}
]
}
updatedAt 是毫秒时间戳。bytes 是 UTF-8 字节数,不是字符数。
permissions 是数组,顺序与脚本头声明一致,便于 App 原样展示。
market.json
市场安装记录。只记从市场装进来的脚本,本地手写的不进这里。
{
"version": 1,
"installed": {
"daily-checkin": {
"version": "1.0.2",
"sha256": "<64 位十六进制>",
"source": "https://box.fiime.cn/scripts/code/daily-checkin-1.0.2.js",
"installedAt": 1763616000000
}
}
}
更新判断靠 version 与远端索引比对。sha256 保留是为了在卸载重装前能确认拿到的是同一份代码。
市场索引
索引地址只有一个:https://box.fiime.cn/scripts/index.json。
单源超时 8 秒,总预算 20 秒;DSH_SCRIPTS_MARKET_INDEXES 可用逗号分隔覆盖,便于本地调试。
{
"format": 1,
"updatedAt": 1763616000000,
"entries": [
{
"id": "daily-checkin",
"version": "1.0.2",
"name": { "zh": "每日签到", "en": "Daily check-in" },
"description": { "zh": "打开淘宝完成签到", "en": "Open Taobao and check in" },
"author": "O宝官方",
"category": "daily",
"tags": ["签到", "淘宝"],
"permissions": ["apps", "screen"],
"bytes": 4821,
"sha256": "<64 位十六进制小写>",
"code": "https://box.fiime.cn/scripts/code/daily-checkin-1.0.2.js",
"icon": "https://box.fiime.cn/scripts/icons/daily-checkin.png",
"updatedAt": 1763616000000
}
]
}
分类
分类 id 固定,文案由 App 本地化,不在索引里写中文标签。
| id | 含义 |
|---|---|
| daily | 日常 |
| shopping | 购物 |
| social | 社交 |
| efficiency | 效率 |
| system | 系统 |
| other | 其他 |
发布与撤回
- 内容仓库:
scripts/<id>/<version>.js+meta.json;CI 生成index.json、算sha256、校验 id / 权限 / 大小后发布到 CDN。 - 审核要求:可读源码(禁止混淆压缩)、权限与行为一致、无未声明网络外发、单文件 ≤ 64 KB、版本号递增、附使用说明。
- 撤回:从索引移除条目。已安装副本不受影响,但不再显示更新。
引擎 SDK 方法
沿用 sdk-extensions/resolve 扩展机制,与 plugin-account、plugin-extensions 相同,由 plugin-scripts 注册。
App 通过这套方法读写脚本,不直接碰文件。
| 方法 | 参数 | 返回 |
|---|---|---|
| android/scripts/market/list | { refresh?: boolean } |
{ entries, updatedAt, sources, cached, installed };缓存 ≤ 10 分钟,installed 是 market.json 的映射 |
| android/scripts/market/install | { id, overwrite?: boolean } |
{ id, name, version, permissions };同 id 已存在且未 overwrite 时返回 id-exists |
| android/scripts/remove | { id } |
{ removed: true };删除脚本文件、索引项与市场记录 |
| android/scripts/market/updates | {} |
{ updates: [{ id, current, latest }] } |
script_* 工具
模型直接调用的是工具,不是 SDK 方法。两者一一对应,工具层负责参数校验与审批,SDK 层负责落盘。
| 工具 | 作用 | 审批 |
|---|---|---|
| script_list | 列出本地脚本 | 否 |
| script_read | 读脚本源码 | 否 |
| script_write | 新建或覆盖脚本,写文件 + 更新索引 | 否 |
| script_delete | 删除脚本、索引项、市场记录 | 是 |
| script_run | 执行脚本,按声明的权限发起一次性审批 | 是 |
插件契约
一个插件是一个目录,导出 apply,拿到 ctx 后注册工具、注册 SDK 方法、订阅事件。
插件之间不互相 import,只通过 ctx 暴露的能力通信。
// js/packages/plugin-scripts/index.js(结构示意)
export const name = 'plugin-scripts'
export function apply(ctx) {
// 1) 注册工具:模型能看到的入口
ctx.tool({
name: 'script_list',
description: 'List the scripts saved on this phone.',
parameters: { type: 'object', properties: {} },
risk: 'read',
async run() { /* 读 index.json */ },
})
// 2) 注册 SDK 方法:App 侧的入口
ctx.sdk('android/scripts/remove', async ({ id }) => {
/* 删文件 + 改索引 + 改 market.json */
return { removed: true }
})
// 3) 订阅生命周期
ctx.on('session/stop', () => {
/* 终止运行中的 Worker */
})
}
工具描述的三条硬要求
description写清楚「什么时候该用」,不写「这个工具是什么」。模型靠它做选择。parameters用标准 JSON Schema,必填项进required,不要让模型猜。risk决定审批强度:read不弹卡,write弹一次,danger每次弹且文案要写清后果。
apply 在引擎启动时同步执行。这里抛错会导致整个引擎起不来,插件加载失败只影响它自己。
需要异步初始化的资源放到第一次调用时懒加载。
限制与边界
这些数字写在代码里,改之前先想清楚会不会让某一层失去保护。
| 项 | 值 | 位置 |
|---|---|---|
| 单次运行超时 | 默认 120 秒,上限 600 秒,超时强制 terminate Worker | runtime.js |
| 定时器数量 | 64 个,运行结束统一清理 | worker.js |
| 日志 | 200 行 / 8000 字符,超出丢弃 | runtime.js |
| 单次 sleep | 上限 3 600 000 毫秒(1 小时),负数按 0 | worker.js |
| 脚本代码 | 本地 256 KB / 市场 64 KB | store.js |
| 脚本数量 | 200 个 | store.js |
Worker 里没有的东西
没有 require、没有 process、没有宿主的 fetch、没有文件系统。
只有 obaby 和一小撮标准 Web 对象:setTimeout / setInterval / TextEncoder / URL / AbortController。
需要别的东西,走 obaby.call 要一个工具。
代码包裹方式
脚本体会被包成 (async () => { … })() 再执行,所以顶层 await 可用,
return 的值就是这次运行的返回值。不要写 export,也不要写 import。