主题
模板 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:usage | data.readDay / data.days |
write:usage | data.writeDay |
network | http.* |
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 onClick | onClick() |
switch | 开关行 | title value summary onChange | onChange(bool) |
plusList | 可增删列表 | title items onAdd onDelete | onAdd() / onDelete(index) |
slider | 滑条 | title value min max step onChange | onChange(number) |
chart24 | 24 柱状 | title values onChange | onChange(number[24]) |
tabs | 分段控件 | items value onChange | onChange(index) |
bigValue | 大数字卡 | title value summary | — |
dropdown | 下拉行 | title options value onChange | onChange(index) |
text | 说明文字 | text | — |
button | 蓝色胶囊按钮 | text onClick | onClick() |
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