扩展包

每份脚本导出一个包。包是安装、权限、设置和版本管理的基本单位；扩展是按 type 实现 protocol 的基本单位。

当前 runtime 会注入 definePackage，脚本可直接调用该函数。由于 JavaScriptCore 不支持 export default，ESM 形式的 export default definePackage(...) 将由后续打包器支持。

definePackage({
  id: "conflux.bangumi",
  title: "动漫数据",
  version: "1.0.0",
  engine: 1,
  permissions: { network: ["https://example.com"] },
  settings: [],
  extensions: [ /* Extension[] */ ],
});

目录生成器仅解析字面量，不执行 handler。

包字段

字段	必填	含义
id	是	采用 reverse-DNS 格式且全局唯一，例如 conflux.bangumi
title	是	展示名
description / author / site / icon	否	展示
version	是	包 semver。目录中的版本必须取自该字段
engine	是	仅支持整数 1
permissions	视情况	见 运行时
settings	否	包级用户配置，每个包仅有一份。字段结构见数据模型 · 用户字段，通过 ctx.settings 读取。服务器地址应存放在 widget 实例的 params 中，详见开发者指南 · 参数
extensions	是	至少一项

扩展公共字段

各 type 的专属字段请参阅对应文档。以下字段由所有扩展共用：

字段	必填	含义
type	是	widget / search / detail / playback / subtitle / danmu
id	是	在包内唯一。完全限定 ID 为 {packageId}/{type}/{id}
title	是	展示名（加到桌面时、服务选择器里）
description	否	说明
cache	否	{ ttlSeconds, staleWhileRevalidateSeconds? }

服务型扩展（detail / playback / subtitle / danmu）另有：

字段	含义
accepts	{ sources, mediaTypes? }。App 在调用 detail / playback 前使用该字段进行解析并控制按钮显示。播放器不会据此筛选 subtitle / danmu，详见 subtitle 和 danmu

同一包可以导出多个相同 type 的扩展，例如使用不同模板的多个 widget。

同一包内相同 type 的扩展参与服务解析时，如果多个扩展的 accepts 均匹配，App 会选择数组中的第一个扩展；如需明确指定，可由用户在设置中选择默认项。