用户脚本 API 参考

API 级别：1（StarX.apiLevel）
语言：Rhino ES6（Context.VERSION_ES6），优化级别 -1（纯解释执行，不生成字节码）
每个脚本一个独立全局作用域，全局上挂有 StarX、console、setTimeout、setInterval、clearTimeout、clearInterval

全局对象

`StarX.apiLevel`

整数，当前为 1。

`StarX.version`

模块版本号字符串，如 1.5.4。

`StarX.script`

本脚本的元数据，加载完成后可用：

{
  id: 'my_script',
  name: '我的脚本',
  namespace: 'local',
  version: '1.0.0',
  description: '说明',
  author: 'you',
  scopes: ['exam', 'work'],
  matches: [],
  runAt: 'document-end',
  env: 'native'
}

`StarX.device`

{
  sdkInt: 36,
  packageName: 'com.chaoxing.mobile',
  processName: 'com.chaoxing.mobile',
  isMainProcess: true,
  appVersionName: '7.0.4',
  appVersionCode: 700004,
  moduleVersion: '1.5.4',
  hookApiAvailable: true,
  onMainThread: true
}

通用方法

方法	说明
`StarX.now()`	毫秒时间戳
`StarX.random()`	`[0, 1)` 随机数
`StarX.sleep(ms)`	同步阻塞当前脚本线程，上限 120000 ms
`StarX.toast(msg)`	弹一条 Toast（受模块提示总开关影响）
`StarX.dump(value)`	把任意值转成字符串 / JSON 文本，调试用
`StarX.log(...)`	写日志，等价于 `StarX.console.log`

StarX.console 提供 log / info / warn / error / debug，全部写入 scripts/logs/<id>.log 与 logcat。

定时器

var id = StarX.setTimeout(fn, ms);
var id = StarX.setInterval(fn, ms);
StarX.clearTimeout(id);
StarX.clearInterval(id);

定时器跑在脚本自己的执行器线程上；脚本停用或重载时全部清除。

`StarX.storage`

按脚本隔离的键值存储，落盘于 scripts/data/<id>.json。

方法	说明
`get(key, def)`	取字符串，缺省返回 `def`
`set(key, value)`	存值（非字符串先转字符串）
`getJson(key, def)`	取值并 `JSON.parse`
`setJson(key, value)`	`JSON.stringify` 后存
`remove(key)`	删除单个键
`keys()`	返回全部 key 的数组
`clear()`	清空

`StarX.http`

var r = StarX.http.request({
  url: 'https://example.com/api',
  method: 'POST',                  // 默认 GET
  body: 'a=1&b=2',                 // 字符串；对象请自己 JSON.stringify
  headers: { 'X-Token': 'x' },
  timeout: 15000                   // 毫秒，取值区间 1000..60000
});
// 成功：r = { ok: true, status: 200, body: '...', headers: { ... } }
// 失败：r = { ok: false, status: 0, body: '', error: '...' }

简写：StarX.http.get(url, headers)、StarX.http.post(url, body, headers)。
默认 User-Agent 为 Mozilla/5.0 (Linux; Android <系统版本>; StarX/<模块版本>)。
不带宿主 Cookie；需要登录态请自行在 headers 里传。

`StarX.clipboard`

方法	说明
`get()`	读取剪贴板文本
`set(text)`	写入剪贴板文本

`StarX.ai`

方法	返回
`isConfigured()`	布尔，模块是否已配置可用 AI
`ask(question, type, options)`	字符串或 `null`
`askImage(base64, mime)`	字符串或 `null`
`ocr(base64, mime)`	字符串或 `null`

type 用题型编码，缺省 -1。
options 可为字符串，也可为数组 / 对象（会 JSON 序列化后传给模型）。
未配置 AI 时一律返回 null，不抛异常。

`StarX.tiku`

StarX.tiku.query(question, type, options) → 字符串或 null。调用第三方题库接口。

`StarX.answer`

StarX.answer.query(question, type, options, images) → { answer, source } 或 null。

与模块自身答题使用同一条链路（题库优先、AI 兜底）。
images 为 base64 字符串数组，可省略。
内部超时 20 秒并阻塞调用线程；放在 question 回调里会拖慢这一题的作答。

`StarX.question`

方法	说明
`last()`	最近一次 `question` 事件的负载，可能为 `null`
`publish(payload)`	手工把一道题广播给所有 `global` 脚本
`answer(value)`	在 `question` 回调里作答，返回 `true` / `false`

answer 的归一规则：字符串直接使用；数字与布尔转字符串；数组在全为单字符元素时拼接（如 AC），否则逗号连接。

`StarX.hook`

要求框架 API ≥ 102，用 StarX.hook.available() 判断。

if (StarX.hook.available()) {
  var id = StarX.hook.method('com.example.Foo', 'bar', {
    arity: 1,                       // 参数个数，-1 表示不限制
    before: function (ctx) {
      ctx.args[0] = 'replaced';     // 改参数
      // ctx.skip = true;           // 跳过原方法
      // ctx.result = 'fake';       // 与 skip 搭配，作为返回值
    },
    after: function (ctx) {
      return ctx.result + '!';      // 返回非 undefined 则替换返回值
    }
  });
  StarX.hook.unhook(id);
}

拦截器上下文：

{
  method: 'bar',
  class: 'com.example.Foo',
  args: [ ... ],
  this: <实例>,
  result: <仅 after 阶段存在>
}

返回 handleId 字符串；类或方法不存在、或框架 API < 102 时返回 null。
两个回调都必须同步返回，运行在拦截发生的那条线程上。
脚本卸载 / 重载 / 停用时注册的 Hook 会全部解除。

其它：StarX.hook.classExists(name)、StarX.hook.unhookAll()。

`StarX.page`

方法	说明
`list()`	当前被跟踪的 WebView URL 数组
`inject(js)`	向活动 WebView 注入一段 JS，返回注入到的 WebView 数量

事件总线

StarX.on(name, fn);         // 订阅，返回回调本身
StarX.off(name, fn);        // 取消订阅；不传 fn 则清空该事件
StarX.emit(name, payload);  // 广播给其它脚本（不回送自己）

回调签名：fn(payload, eventName, fromId)。

框架事件的名称、负载与触发时机见用户脚本指南第 6 节。

错误处理

任何 API 调用失败都返回 null / false，不抛异常到脚本。
事件回调抛异常 → 记一条 event <name> handler failed: <msg>，其它回调继续执行。
脚本加载期抛异常 → 该脚本标记失败，错误信息显示在脚本卡片上。

版本与兼容

StarX.apiLevel 供脚本做能力判断；API 级别只增不改。
新增 API 不改变已有 API 语义，破坏性变更会提升 apiLevel。

用户脚本 API 参考

用户脚本 API 参考

目录

全局对象

StarX.apiLevel

StarX.version

StarX.script

StarX.device

通用方法

定时器

StarX.storage

StarX.http

StarX.clipboard

StarX.ai

StarX.tiku

StarX.answer

StarX.question

StarX.hook

StarX.page

事件总线

错误处理

版本与兼容

`StarX.apiLevel`

`StarX.version`

`StarX.script`

`StarX.device`

`StarX.storage`

`StarX.http`

`StarX.clipboard`

`StarX.ai`

`StarX.tiku`

`StarX.answer`

`StarX.question`

`StarX.hook`

`StarX.page`