Skip to content

模板 SDK 规范 ​

API Level 1 · 运行时 Rhino 1.9.2(纯 Java,无 native 库、无 DOM、无文件系统)

1. 模板是什么 ​

一个模板 = 一段 JavaScript + 一份清单。

不是参数快照,是可执行代码:

能力由谁决定
用户看到的编辑界面buildUI()
要生成哪几天listDates()
每天产出什么数据generate(date)

脚本不能直接写盘、不能直接发请求,只描述意图,由宿主按 manifest.json 声明的权限统一执行。

为什么不是 QuickJS

quickjs-android 的 JNI 绑定在 x86_64 上会 SIGSEGV 直接杀进程。 Rhino 是纯 Java 实现,能在后台线程安全跑不受信任脚本。

2. 目录结构 ​

files/templates/
└── <模板id>/
    ├── manifest.json   元信息 + 权限(必须)
    ├── main.js         脚本(必须)
    ├── store.json      模板私有 KV(App 维护)
    └── icon.*          可选图标

旧的单文件 templates/<id>.json 已废弃,启动时自动清理。

manifest.json ​

json
{
  "id": "game-day",
  "name": "游戏日",
  "author": "your-name",
  "version": "1.0",
  "description": "工作日晚上集中玩游戏",
  "permissions": ["read:usage", "write:usage"],
  "apiLevel": 1,
  "icon": "icon.png"
}
字段必填说明
id✅唯一标识,等于目录名
name✅列表显示名
permissions✅见第 3 节
apiLevel✅固定 1
author / version / description
icon目录内图标文件名,留空用默认

3. 权限 ​

未声明的调用直接抛异常(fail closed)。

权限允许的 API
read:usagedata.readDay / data.days
write:usagedata.writeDay
networkhttp.*
json
"permissions": ["read:usage", "write:usage"]

4. 生命周期 ​

点进模板
  ↓
注入 __input(permissions / usage / store / templateId / templateName)
  ↓
执行 PRELUDE + main.js
  ↓
onLoad()(可选)
  ↓
buildUI() → 渲染界面
  ↓
用户交互 → 触发回调函数
  ↓
点「生成」
  ↓
listDates() → 日期数组
  ↓
onBeforeGenerate()(可选)
  ↓
对每个日期调用 generate(date)
  ↓
收集 __ops → 宿主统一写盘

三个必需函数 ​

js
function buildUI()   { return { sections: [...] } }  // 界面
function listDates() { return ['2026-11-15'] }       // 生成哪几天
function generate(date) { /* ... */ }                // 一天的数据

listDates 不能省

漏了会提示「模板需要实现 listDates() 返回要生成的日期数组」, 能打开界面但生成不了数据。

可选函数 ​

函数时机用途
onLoad()buildUI 前初始化 state、读 store
onBeforeGenerate()listDates 后批量准备(如拉一次网络)

generate 的两种写法 ​

js
// A(推荐):记录意图
function generate(date) {
  var day = { total: 240, hourly: [...], apps: [], eyes: {...} };
  data.writeDay(date, day, 'overwrite');   // 需要 write:usage
  return day;
}

// B(兼容):直接返回
function generate(date) {
  return { total: 240, hourly: [...], apps: [], eyes: {...} };
}

宿主判定顺序:先看 data.writeDay 意图,有就按意图写,没有才用返回值。

生成时同日期已有记录不弹窗,直接覆盖。

5. 界面 DSL ​

js
function buildUI() {
  return {
    sections: [
      { title: "分组标题", card: [ 组件, 组件 ] },
      { card: [ ... ] }        // 不写 title 就接在上一组后面
    ]
  };
}

所有组件只用默认样式,模板无法自定义颜色和尺寸 —— 保证任何模板生成的界面都和原版 MIUI 观感一致。

组件清单(11 个) ​

type外观关键属性回调
row设置行title value summary arrow onClickonClick()
switch开关行title value summary onChangeonChange(bool)
plusList可增删列表title items onAdd onDeleteonAdd() / onDelete(index)
slider滑条title value min max step onChangeonChange(number)
chart2424 柱状title values onChangeonChange(number[24])
tabs分段控件items value onChangeonChange(index)
bigValue大数字卡title value summary—
dropdown下拉行title options value onChangeonChange(index)
text说明文字text—
button蓝色胶囊按钮text onClickonClick()
divider分隔线——

组件示例 ​

js
{ type: 'row', title: '日均时长', value: util.formatDuration(state.dailyMinutes), onClick: 'editDaily' }

{ type: 'switch', title: '夜间零使用', summary: '0-6 点不出数据', value: state.nightZero, onChange: 'setNight' }

{ type: 'plusList', title: '日期', items: state.dates, onAdd: 'addDate', onDelete: 'delDate' }

{ type: 'slider', title: '应用权重', value: state.appWeight, min: 0, max: 1, step: 0.05, onChange: 'setAppWeight' }

{ type: 'chart24', title: '时段权重', values: state.hourWeights, onChange: 'setWeights' }

{ type: 'tabs', items: ['日', '周', '月'], value: state.tab, onChange: 'setTab' }

{ type: 'bigValue', title: '预计日均', value: '4 小时', summary: '已开启夜间零使用' }

{ type: 'dropdown', title: '方案', options: ['默认', '激进', '保守'], value: state.plan, onChange: 'setPlan' }

{ type: 'text', text: '提示:权重越大,该小时数据越多' }
{ type: 'button', text: '恢复默认曲线', onClick: 'resetCurve' }
{ type: 'divider' }

回调约定 ​

onClick / onChange / onAdd / onDelete 填函数名字符串:

js
onClick()          // 无参
onChange(newValue) // switch: bool / slider: number / chart24: number[24] / tabs·dropdown: index
onAdd()            // plusList 点 ⊕
onDelete(index)    // plusList 点 ×

改完 state 后按需 ui.refresh():

情况是否 refresh
影响其他组件显示的值需要
switch / tabs / dropdown 选中态需要
slider / chart24 拖动中不需要(会卡)
只存 store不需要

二级页面 ​

js
ui.push({ sections: [ { title: '详情', card: [{ type: 'text', text: '...' }] } ] });
ui.pop();

ui.push 的 screen 与 buildUI() 返回结构完全一致。

6. API 参考 ​

6.1 calc(纯计算) ​

js
calc.largestRemainder(total, weights)  // 最大余数法,Σ = total
calc.fill(total, weights, cap)         // 带每小时上限,Σ = min(total, Σcap)
calc.capacity(ranges)                  // [{startMinute, endMinute}] → 每小时可用分钟 0..60
calc.jitter(value, percent, seed)      // ±percent% 抖动,seed 可复现
calc.sum(array)                        // 求和
js
calc.largestRemainder(100, [1, 1, 1])  // → [34, 33, 33]
calc.capacity([{ startMinute: 480, endMinute: 1380 }]) // → [0×8, 60×15, 0]

6.2 data(需权限) ​

js
data.days()                            // ["2026-11-01", ...] 升序    [read:usage]
data.readDay("2026-11-15")             // 一天数据或 null            [read:usage]
data.writeDay("2026-11-15", entry, mode)  // 记录意图                [write:usage]
// mode: "overwrite" | "merge" | "skip"

entry 结构 ​

generate 要返回(或写进 writeDay)的一天数据:

js
{
  total: 240,                    // 当天总屏幕分钟
  hourly: [ ...24 个整数... ],    // 每小时分钟,每项 0~60

  apps: [
    {
      pkg: "com.tencent.tmgp.sgame",
      name: "王者荣耀",
      minutes: 120,              // 该应用当天分钟
      hourly: [ ...24 个整数... ], // 该应用每小时分布
      icon: ""                   // 留空由 App 从系统解析
    }
  ],

  eyes: {
    total: 170,                  // 当天用眼分钟
    categories: {                // 5 类拆分
      healthy: 30,
      dimLight: 20,
      lyingDown: 15,
      overUse: 40,
      upClose: 25
    },
    healthyHourly:   [ ...24... ],
    unhealthyHourly: [ ...24... ]
  },

  unlocks: 107,                  // 当天解锁次数
  unlockHourly: [ ...24... ]     // 解锁的时段分布
}

字段约束(必须满足) ​

total              = Σ hourly
Σ apps[].minutes   = total
eyes.total         = Σ eyes.categories[*]
unlocks            = Σ unlockHourly
hourly[i]          ≤ 60

唯一放宽:apps[].hourly 之和不要求等于该小时总量。

不自洽会露馅

展示层不做校验,数据不自洽时会照原样渲染 —— 柱子高度、百分比、排名这类派生显示就会看起来不对。 用 calc.* 分配,别手写随机数。

6.3 store(模板私有,无权限) ​

js
store.get("key")
store.set("key", value)
store.remove("key")

存 templates/<id>/store.json,删模板一起删。

写入有延迟

store.set 是记录意图,本次脚本执行结束后才落盘。 同一轮里 store.get 读到的还是旧值 —— 要读刚写的值请直接读内存里的 state。

6.4 http(需 network,同步) ​

js
http.get(url, options)          // → { status, body, headers }
http.post(url, body, options)
http.put(url, body, options)
http.delete(url, options)
http.getJson(url, options)      // GET + JSON.parse
http.postJson(url, obj, opts)   // POST JSON + 解析响应
options说明
headers请求头对象
timeout毫秒,默认 15000,范围 1000 ~ 60000

限制:只支持 http/https;响应体上限 1 MB;自动跟随重定向;UA 固定 MiFakeTime-Template/1.0。

超时预算 = 3 秒 + 已用网络时间,所以 30 秒的 AI 调用不会被误判成死循环。

6.5 ui ​

js
ui.refresh()                                        // 重绘
ui.push(screen)                                     // 开二级页
ui.pop()                                            // 返回
ui.input(title, value, hint, callback)              // → callback(字符串)
ui.pick(title, items, value, callback)              // → callback(下标)
ui.confirm(title, message, positive, negative, callback)  // → callback(bool)
ui.alert(title, message, callback)
ui.pickDate(callback)                               // → callback([{start, end}])
ui.pickTime(callback)                               // → callback([startMinute, endMinute])

callback 同样是函数名字符串。

6.6 util ​

js
util.today()              // "2026-11-15"
util.pad2(7)              // "07"
util.formatDuration(237)  // "3 小时 57 分"
util.formatDuration(45)   // "45 分钟"

6.7 注入的只读变量 ​

变量内容
__usage{ "日期": {一天数据} }
__storeData模板 store 内容
__perms权限数组
__ops写操作队列(API 追加,宿主读取)

一般用 data.* / store.* 即可,不需要直接碰这些。

7. 限制与错误 ​

限制值
脚本执行超时3 秒 + 网络耗时(死循环会被真正中断)
HTTP 单请求超时默认 15s,最大 60s
HTTP 响应上限1 MB
JS 引擎Rhino 1.9.2(ES5 为主,部分 ES6)
无文件系统 / DOM / window只能用本文档列出的 API
无 console没有 console.log,调试用 ui.alert

错误对照 ​

提示原因
模板缺少函数 buildUI没实现 buildUI
模板缺少函数 listDates没实现 listDates
模板需要实现 listDates() 返回要生成的日期数组返回空数组或抛错
模板未声明权限 write:usage调了受限 API
脚本执行超时(>3000ms),可能有死循环死循环 / 同步阻塞
日期 2026-11-15 生成失败:...generate 抛错
js
try {
  var r = data.readDay('2026-11-15');
} catch (e) {
  // e.message 形如「模板未声明权限 read:usage」
}

8. 调试 ​

没有 console.log,要看中间值用弹窗:

js
function debugShow() { ui.alert('调试', JSON.stringify(state.hourWeights)); }

推荐先用最小模板验证三个函数:

js
function buildUI() { return { sections: [{ card: [{ type: 'text', text: 'hello' }] }] }; }
function listDates() { return [util.today()]; }
function generate(d) {
  var h = []; for (var i = 0; i < 24; i++) h.push(0);
  h[12] = 60;
  return { total: 60, hourly: h, apps: [], eyes: { total: 0, categories: {} }, unlocks: 0, unlockHourly: h.slice() };
}

删掉 store.json 等于清空模板设置。

9. 导入 / 导出 ​

模板以 zip 分发:

游戏日.zip
├── manifest.json
├── main.js
├── store.json    (可选)
└── icon.png      (可选)

导入规则:manifest.json 和 main.js 必须有;zip 条目名做路径穿越检查;导入会新建副本(目录名 tpl_<时间戳>),不覆盖已有模板。

10. 让 AI 写模板 ​

App 内 AI 输出一个动作块:

json
{"action":"write","file":"templates/<id>/main.js","content":"完整文件内容"}

约束:content 必须完整可运行且不用反引号包裹;不要输出 manifest.json(客户端自动建);<id> 用简短英文小写 + 短横线。

AI 自动创建的模板默认权限是 write:usage,需要读数据或联网要手动补 manifest.json。

自己写 prompt ​

用 MiFakeTime 模板 SDK v1 写一个模板,需求:<描述>。

约束:
- 必需函数:buildUI() / listDates() / generate(date)
- UI 只能:row / switch / plusList / slider / chart24 / tabs / bigValue / dropdown / text / button / divider
- 回调填函数名字符串(onClick: 'fnName')
- 算法只能用 calc.*
- 写数据用 data.writeDay(date, entry, mode)
- 数据必须自洽:total = Σhourly、Σapps[].minutes = total、
  eyes.total = Σcategories、unlocks = ΣunlockHourly、每小时 ≤ 60
- 没有 console,调试用 ui.alert
- 单文件,无 import

输出:main.js 全文 + manifest.json

仅供学习与界面体验使用