管理扩展包

安装的基本单位是扩展包，而不是包内的某个 type。扩展包的导出方式见开发者指南 · 扩展包，包级设置的声明方式见开发者指南 · 设置。

安装用于提供能力，添加或启用用于使用能力。 安装脚本后，扩展不会自动显示在首页，也不会自动为播放器启用字幕或弹幕。

页面结构

主界面包含两个标签页：左侧为 Dashboard，右侧为 Extensions。

Dashboard 工具栏通常显示“添加 widget”；进入编辑模式后，该按钮会变为 Done。首页仅显示已添加的 widget 实例。用户为某个实例填写的参数会继续传递给详情和播放扩展，因此从首页卡片进入详情或播放时，使用的是生成该卡片的实例参数。

Extensions 列出已启用的字幕和弹幕服务。选择右上角的 + 可以启用其他实例；选择 shippingbox 图标可打开 Installed 页面，其中包含已安装包列表、版本、type、Settings、卸载功能以及从 URL 或文件安装的入口。

启用字幕和弹幕

Extensions 按 Subtitles 和 Danmu 分区显示已启用的服务。选择 +（或空状态中的 Add Extension）可打开选择器，其中列出已安装包提供的 subtitle / danmu 扩展。如果所属包仍有未填写的必填 Settings，该行会显示 Required settings missing。进入详情并完成 Settings 后，界面才会显示 Add。若扩展包含 params，需先填写参数，再选择 Add。同一 type 可以启用多个实例。左滑删除仅停用对应实例，不会卸载扩展包。

未提供字幕或弹幕扩展的包不会显示在选择器中。播放器会使用已启用的服务，不根据 accepts 进行筛选。

添加 widget

选择首页右上角的 +（或无实例时的 Add Widget）可打开选择器。选择器按已安装包列出 widget 扩展，并使用安装时缓存的 placeholder 示例数据渲染模板预览；如果没有示例数据，则仅显示标题。进入详情后，根据该 widget 声明的字段填写实例配置，再选择 Add。App 会生成稳定的实例 ID，并将该实例添加到首页。同一 type 可以添加多个实例，例如为两台服务器分别添加实例并填写独立配置。

未提供 widget 的包不会显示在选择器中。服务型扩展（详情、播放）不提供独立的配置页。

编辑和删除 widget

在首页长按 widget 卡片可打开操作菜单：

• 编辑：将卡片翻转至背面的配置页，并预填当前值。选择模糊背景可返回正面；修改后的参数会保存，并重新调用 load。
• 编辑 Dashboard：进入编辑模式。所有 widget 会显示类似主屏图标的抖动效果，左上角出现删除按钮；选择 widget 同样会打开该实例的配置页。选择右上角的 Done 退出。编辑模式下，点击海报不会打开详情页。
• 删除：仅从首页移除当前实例，不会卸载扩展包，也不会影响相同 type 的其他实例。

删除全部实例后，首页会显示 No Widgets 并退出编辑模式，用户可以继续添加新实例。

订阅

Installed 页面的 + 菜单中提供添加订阅选项。用户需要填写一个 HTTP(S) 地址，App 将从该地址下载 JSON 清单。清单可包含多个扩展包的标题、说明、版本、更新说明和 .js 下载地址。

选择同一页面顶部的订阅可进入订阅列表。用户可以启用、停用、删除或手动刷新订阅。添加订阅或手动刷新时，清单中尚未安装的包会自动下载并安装。已安装的包不会自动替换；即使清单中的版本更高，也需要用户选择 Update，并通过原有的预览流程确认。安装完成后，扩展不会自动添加到首页，也不会自动启用字幕或弹幕。

App 启动时，如果某个已启用的订阅超过约一天未刷新，App 会重新获取清单，并安装其中尚未安装的包。已停用的订阅不会触发自动安装。每台设备独立记录上次获取时间。

从 URL 或文件安装

列表右上角的 + 会打开“从 URL 安装”和“从文件安装”菜单；空状态下则并列显示两个按钮。两种方式均仅支持包含一次 definePackage 调用的 .js 文件，不支持 ZIP 文件或目录。

从 URL 安装：填写直接指向 .js 文件的 HTTP 或 HTTPS 地址。地址无效时，界面会立即提示并取消下载。下载过程中会显示进度；如果服务器未返回文件大小，则仅显示活动指示器，不显示百分比。

从文件安装：打开系统文件选择器并选择 .js 文件。取消选择不会执行安装。选择后，App 会立即读取文件，不会长期占用原始路径；解析失败时可以重新选择。

下载或读取完成后，两种安装方式都会显示标题、版本、type、包内扩展和 Settings 的预览。如果相同 ID 的包已安装，Settings 会预填当前保存的值。选择保存后，扩展包将写入本地并显示在列表中。新安装的包不会自动添加到首页。如果开发者声明了 widget placeholderData 或实现了 placeholder，App 会在安装或版本变化时采集并缓存示例数据，供后续添加 widget 时预览。

如果可见的必填 Settings 仍为空，界面会显示提示：选择取消可留在预览页继续填写；选择忽略并安装则继续安装。未填写的必填项之后仍会在包列表中显示 Required settings missing。

再次安装相同 ID 的包时，App 会比较版本：版本更高时，预览按钮显示为更新，确认后覆盖现有版本；版本相同时，App 会询问是否覆盖（取消 / 覆盖）；版本更低时，App 会提示已安装更新版本，并询问是否继续（取消 / 忽略并安装）。覆盖后，脚本和包信息会更新，已填写的扩展参数会保留；Settings 以本次预览提交的内容为准，未修改的键保持原值。如果必填项仍为空，App 会再次要求确认是否忽略并安装。

包设置

进入包详情页后，顶部显示 Settings。此处用于填写包级共享配置，例如 Demo 的 Title tag / Uppercase titles。媒体服务器或账号信息不应在此处填写，而应在添加对应 widget 实例时配置。同一份脚本可以添加多个实例，并分别连接不同服务器。

当包级必填项仍为空时，包列表会显示 Required settings missing。未声明 settings 的包不会显示此区域。

扩展参数

开发者可以声明以下配置控件：

控件	用途
单行文本	普通字符串
数字	数量、上限等数值
开关	启用或停用选项
单选	从开发者预设的选项中选择

当前不支持文件选择或日期控件。添加 widget 时，界面仅显示该扩展声明的字段。开发者标记为必填的字段会在标签旁显示 Required，空文本框或数字框中也会显示相同提示。即使未填写必填项，用户仍可添加实例；后续刷新时会继续使用已保存的值。

调试扩展

在包详情页的扩展列表中，长按某一行可进入调试页；普通点击仍用于配置该扩展的参数。

调试页根据 type 提供本次调用的输入字段：widget / search 使用参数，search 还包含关键词；详情、播放、字幕和弹幕使用 MediaRef，播放、字幕和弹幕还可填写季、集，弹幕还可填写标题。选择 Run 后，App 会执行该 type 的主 handler。调用成功时显示 JSON 输出，失败时显示错误。页面下方显示本次调用产生的 console.log / info / warn / error 日志。包级 Settings 使用已保存的值，不会在调试页重复显示。

卸载

可以在列表中侧滑删除，或在包详情页选择 Uninstall。卸载后，首页将停止使用该包，通过 URL 或文件安装的脚本也会被删除。如果没有任何已安装包，首页将为空，播放和搜索也不再提供扩展数据。

加回 Demo

卸载全部扩展包后，可以在 Installed 空状态中选择“添加 Demo”，重新安装内置演示包。该操作会同时添加一个 Demo Grid，并启用 Demo 的字幕和弹幕。也可以添加订阅，App 会自动安装清单中尚未安装的包。