Mirv 扩展 API 三种数据格式详解

总览

Mirv 扩展的核心是返回正确格式的数据。Extension 基类的每个方法都有明确的返回类型，字段不对会导致 Mirv 无法正确渲染。

ListItem — 列表卡片

latest() 和 search() 返回的数组元素：

{
  title: "进击的巨人 第四季",      // 必填，卡片标题
  url: "/bangumi/detail/12345",    // 必填，详情页的唯一标识
  cover: "https://example.com/cover.jpg",  // 必填，封面图
  update: "2026-08-25 更新"       // 可选，最近更新时间 / 集数
}

url 字段很关键——它是后续 detail(url) 和 watch(url) 调用的入参。你可以随便填，但必须能唯一标识这个条目。

Detail — 详情页

detail(url) 的返回值：

{
  title: "进击的巨人 第四季",
  cover: "https://example.com/cover.jpg",
  desc: "人类与巨人的最终决战...",     // 可选，简介
  metadata: {                            // 可选，其他元信息
    "年份": "2023",
    "作者": "谏山创"
  },
  episodes: [                            // 必填，选集/章节列表
    {
      title: "第 1 集 人类最后的堡垒",
      urls: [
        { name: "超清 1080P", url: "/play/1" },
        { name: "高清 720P",  url: "/play/1-hd" }
      ]
    },
    {
      title: "第 2 集",
      urls: [{ name: "默认", url: "/play/2" }]
    }
  ]
}

episodes 字段在三种扩展类型里通用——只是语义上 bangumi 叫"集"、manga 和 fikushon 叫"章节"。

Episode.entries — 选集 / 章节

{
  title: "第 1 集",
  urls: [
    { name: "线路 A", url: "/play/1-a" },
    { name: "线路 B", url: "/play/1-b" }
  ]
}

• title：显示给用户的集 / 章节名称；
• urls：播放 / 阅读入口，支持多条线路。

BangumiWatch — 视频类型 watch() 返回值

{
  type: "hls" | "mp4",   // 必填，两种流式协议
  url: "https://example.com/stream.m3u8"  // 必填，视频地址
}

绝大多数在线视频源都是 HLS（m3u8）。MP4 比较少见但格式更简单。

MangaWatch — 漫画类型 watch() 返回值

{
  urls: [
    "https://example.com/chapter/01.jpg",
    "https://example.com/chapter/02.jpg",
    "https://example.com/chapter/03.jpg"
  ]
}

urls 是该章节所有图片的 URL 数组，按顺序排列。Miru 漫画阅读器会按顺序加载并渲染成翻页视图。

FikushonWatch — 小说类型 watch() 返回值

{
  title: "第五卷 第 12 章 异火",
  subtitle: "斗破苍穹",              // 可选
  content: [
    "萧炎站在悬崖边，望着脚下翻滚的云海...",
    "他的手中握着一枚古老的玉佩...",
    // ...该章节的所有段落，每段一个数组元素
  ]
}

content 数组里每一项是一段完整的文字，不是一行。Miru 阅读器会自动在数组元素之间加段落间距。返回前要把原始 HTML 剥离干净，按段落切分后塞进数组。