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

开发者文档

O宝 是 FiimeOPC 的衍生智能产品,基于 DSH 开发,面向 OPC FDE 与企业老板的私人 Agent 助理:模型负责拆步骤,引擎负责把步骤落到手机上。 这份文档写给要往里加东西的人——加一个工具、加一个插件、写一个脚本,或者把引擎接到自己的 App 里。

想直接写脚本,不用读这一页,去 JS 编写文档。 这里讲的是脚本运行的那一层,以及它下面和上面的东西。

这份文档覆盖什么

层技术栈职责代码位置
AppKotlin / 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 Workerruntime.js
定时器数量64 个,运行结束统一清理worker.js
日志200 行 / 8000 字符,超出丢弃runtime.js
单次 sleep上限 3 600 000 毫秒(1 小时),负数按 0worker.js
脚本代码本地 256 KB / 市场 64 KBstore.js
脚本数量200 个store.js

Worker 里没有的东西

没有 require、没有 process、没有宿主的 fetch、没有文件系统。 只有 obaby 和一小撮标准 Web 对象:setTimeout / setInterval / TextEncoder / URL / AbortController。 需要别的东西,走 obaby.call 要一个工具。

代码包裹方式

脚本体会被包成 (async () => { … })() 再执行,所以顶层 await 可用, return 的值就是这次运行的返回值。不要写 export,也不要写 import。