开始之前

一个插件就是跑在 App 内 QuickJS 沙箱里的一段 JavaScript， 通过受权限控制的全局对象 ctx 与宿主交互（读播放状态、发 HTTP、存数据、 挂 UI 扩展点等）。最少只需要两个文件：manifest.json + main.js。完整 API 见 插件规范。

1 写 manifest.json

声明插件身份、申请的权限和要挂载的扩展点。 目录名必须等于 id/version。市场展示用的 tags/targets 等也写在这里——manifest 是唯一元数据源。 字段定义见 schemas/manifest.schema.json。

{
  "id": "com.example.hello",
  "version": "1.0.0",
  "name": "我的插件",
  "description": "干什么用的",
  "tags": ["demo"],
  "targets": ["pc", "mobile", "tv"],
  "permissions": ["ui", "storage", "extensions"],
  "extends": {
    "settingsPages": [{ "id": "settings", "title": "设置", "handler": "openSettings" }]
  }
}

2 写 main.js

顶层代码加载即运行。用 ctx.onEnable 注册扩展点、监听播放事件、 读写存储。下面是一个在首页显示问候、并提供设置页改称呼的最小例子：

'use strict';

async function homeMetric() {
  const name = (await ctx.storage.get('name')) || 'World';
  return { metrics: [{ label: '问候', value: 'Hello, ' + name }] };
}

async function openSettings() {
  const v = await ctx.ui.showForm({
    title: '设置',
    fields: [{ key: 'name', label: '称呼', type: 'text', default: '' }]
  });
  if (!v) return;
  await ctx.storage.set('name', v.name || 'World');
  ctx.ui.showToast('已保存');
}

ctx.onEnable(async () => {
  await ctx.extensions.register('homeStats', { id: 'hi', title: '问候', handler: homeMetric });
});

ctx API 速览

3 打包成 .ipk

把插件放到 plugins/<id>/<version>/ 后，一条命令搞定校验 + 索引 + 打包：

python tools/build.py
# 校验 + 自动生成 registry.json + 打包所有 packages/<id>-<version>.ipk
# 只打单个：python tools/pack_plugin.py plugins/<id>/<version>/

.ipk 就是个 zip（包根含 manifest.json + main.js）。本地自测： App「设置 → 插件 → +」选这个 .ipk 安装，同意权限后启用。

4 发布到市场

流程很短，registry.json 全自动生成、永远不要手改：

1. 插件放到 plugins/<id>/<version>/；
2. 跑 python tools/build.py（自动更新 registry.json + 生成 packages/*.ipk）；
3. git commit 后推送——市场页会自动收录，并给出「下载 .ipk」直链；
4. 要下架某插件/版本：写进 blocked.json（这是唯一需要手动维护的索引）。

示例插件