Mirv 扩展文件结构与元数据注释

一个完整扩展的骨架

Mirv 扩展由两部分组成：

元数据注释块：// ==MiruExtension== ... // ==/MiruExtension== 之间的内容；
Extension 子类：导出一个继承自 Extension 基类的类，重写需要的方法。

完整模板：

// ==MiruExtension==
// @name My First Extension
// @version v0.0.1
// @author YourName
// @lang zh-cn
// @icon https://example.com/icon.png
// @package com.example.myext
// @type bangumi
// @webSite https://example.com
// ==/MiruExtension==

export default class extends Extension {
  async load() { /* 初始化 */ }
  async latest(page) { /* 最近更新列表 */ }
  async search(kw, page) { /* 搜索 */ }
  async detail(url) { /* 详情页 */ }
  async watch(url) { /* 观看内容 */ }
}

元数据字段详解

字段	必填	说明
@name	✅	扩展显示名称，用户在 Mirv 界面看到的名字
@version	✅	扩展版本号，格式 `v0.0.1`
@webSite	✅	扩展目标站点的 URL，Mirv 用于展示和请求头 Referer
@package	✅	扩展唯一标识，必须和文件名一致（如 `com.example.myext` → 文件名必须是 `com.example.myext.js`）
@type	✅	`bangumi`（视频）/ `manga`（漫画）/ `fikushon`（小说）三选一
@author	❌	作者名
@lang	❌	扩展主要语言，如 `zh-cn` / `en`
@icon	❌	扩展图标 URL

@package 为什么和文件名必须一致

Mirv 在加载扩展时会校验 @package 字段和文件名。这个机制的目的：

防止重复加载：同一个 @package 只加载一次；
安全隔离：每个扩展的缓存、状态文件用 @package 区分；
扩展更新：新版本扩展覆盖旧版本时，用 @package 匹配。

如果你忘记了 @package 或文件名对不上，Mirv 会加载失败并在日志里提示。

@type 决定消费端

@type 是 Mirv 扩展里最重要的字段之一——它决定了 Mirv 用哪个消费端来渲染你的扩展返回的数据：

@type bangumi   → 视频播放器  → watch() 返回 { type: "hls" | "mp4", url }
@type manga     → 漫画阅读器  → watch() 返回 { urls: string[] }
@type fikushon  → 小说阅读器  → watch() 返回 { content: string[], title, subtitle }

一个扩展文件只能声明一种 @type。想同时做视频和漫画源？写两个扩展文件，各自声明 @type。

注释格式注意

元数据注释块必须用精确的格式：

开头 // ==MiruExtension==（注意 == 是分隔符，前面有空格）；
每个字段一行，格式 // @field value；
结尾 // ==/MiruExtension==；
中间不能有空行、不能有其他 JS 代码。

Mirv 用正则表达式解析这一段注释，格式稍微错一点就可能解析失败。