Kazumi 快速上手：四条命令跑起规则驱动的番剧聚合播放器，再开启实时超分

Kazumi 快速上手：四条命令跑起规则驱动的番剧聚合播放器，再开启实时超分

【免费下载链接】Kazumi基于自定义规则的番剧采集APP，支持流媒体在线观看，支持弹幕，支持实时超分辨率。项目地址: https://gitcode.com/gh_mirrors/ka/Kazumi

Kazumi 是一款基于 Flutter 的跨平台番剧聚合应用，用几行 XPath 选择器就能把动漫站点变成可搜索、可播放的数据源，支持 Anime4K 实时超分与弹幕，适合番剧观众，也适合想拆解规则引擎的 Flutter 开发者。

🎯 Kazumi 解决了什么问题

在没有这类工具之前，看小站番剧的体验是这样的：

  1. 网页不能直接播——大量小站只有详情页和网页播放器，没有接口、没有下载地址，得打开网页等广告，再翻页面源码找真实地址。
  2. 资源没有统一入口——每部番对应一个站点，搜索页、分页、封面格式各不相同，想对比多个来源只能挨个开浏览器标签。
  3. 画质停在源站水平——源站给 480p 就只能看 480p，大屏幕上像素感明显，也没有任何补救手段。

Kazumi 的思路是不写代码：你提供 XPath 选择器说明"去哪搜、列表在哪、标题在哪"，检索和播放交给程序。同时把元数据与播放拆开：封面、标签、评分走 Bangumi API（lib/request/apis/bangumi_api.dart），视频流走你的规则，两边互不干扰。

🚀 最短路径跑起来 Kazumi

环境要求：

  • Flutter SDK 3.47.7（Dart >=3.10），版本锁定在pubspec.yaml
  • 目标平台工具链已配置（Android SDK 等）
  • 良好网络：依赖来自 pub.dev、MavenCentral、GitHub 等多处
git clone https://gitcode.com/gh_mirrors/ka/Kazumi cd Kazumi flutter pub get flutter run

跑起来后你会看到首次启动向导，按顺序处理免责声明、镜像、规则源、更新源（lib/pages/onboarding/steps/）。之后进入带封面与标签的推荐页，底部是"推荐/时间表/追番/我的"四个 Tab。注意：还没装规则时搜索页搜不出东西，先去规则管理里装几条再试。

🧩 规则引擎原理：从关键词到播放页的五步

一条规则就是一个 JSON，核心字段是searchURL、searchList、searchName、searchResult（搜索用）和chapterRoads、chapterResult（剧集用）。规则分 XPath 与 API 两种模式，引擎按searchMode分发到对应策略。执行流程：

  1. 加载规则：启动时 PluginsController 读取应用支持目录里的plugins.json，逐条解析为 Plugin 模型（lib/plugins/plugins_controller.dart）。
  2. 构建 URL：把searchURL中的@keyword替换为编码后的关键词；开启usePost时查询参数转入表单体。
  3. 发出请求：RuleEngine 附带 Cookie 与自定义 User-Agent 发送，先做反爬探测，命中验证码则抛出CaptchaRequiredException，转 WebView 验证流程。
  4. XPath 解析：用searchList取列表节点，再在每个节点内用searchName/searchResult提取标题与链接。
  5. 统一输出与播放：转成 SearchItem 进入列表；详情页复用同一套流程取剧集，视频源解析器产出 M3U8/MP4 地址，交给 media-kit 播放。

关键代码在 XPath 策略的 URL 构建处（lib/services/plugin/xpath_rule_strategy.dart）：

final queryUrl = config.searchUrl.replaceAll('@keyword', Uri.encodeQueryComponent(keyword)); ... if (!config.usePost) { return PreparedRuleRequest( method: 'GET', url: queryUrl, includeCookies: true); } return PreparedRuleRequest( method: 'POST', url: uri.replace(query: null).toString(), bodyType: 'form', body: uri.queryParameters, includeCookies: true);

代表功能逐个看

实时超分：480p 源观感拉近 1080p

  • 用户看到的效果：播放设置里选"效率档/质量档"，画面线条变锐利，低分辨率源观感明显改善。
  • 实现位置：assets/shaders/下是 10 个 Anime4K GLSL 文件；lib/services/shaders/shader_asset_service.dart 负责首次启动时把着色器复制到应用可写目录；三态开关（关闭/效率/质量）在lib/pages/player/controller/player_super_resolution.dart。
  • 工程细节：着色器只复制一次，已存在的文件直接跳过，后续启动不重复写盘；两档差异在于加载的着色器组合不同，集显设备跑效率档帧率更稳。

多源聚合搜索：一次关键词，多规则出结果

  • 用户看到的效果：输入关键词，多个已装规则同时返回条目，附封面、标签、评分，可翻页。
  • 实现位置：lib/pages/search/search_controller.dart，元数据经 BangumiApi 补齐，以图搜番走 trace.moe 接口（lib/request/apis/trace_api.dart）。
  • 工程细节：控制器内部维护_searchGeneration代际号，每次新搜索让上一轮的异步结果作废，快速连续搜索时新旧结果不会串页。

弹幕：与播放时间轴同步

  • 用户看到的效果：边播边发弹幕，支持滚动/顶部/底部类型与颜色，同一弹幕源的弹幕跨设备一致。
  • 实现位置：数据模型在 lib/modules/danmaku/danmaku_module.dart，渲染依赖 canvas_danmaku 包。
  • 工程细节：DanmakuEntry的p字段以逗号分隔存"时间,类型,颜色,来源"，颜色压成 RGB 整数，与弹弹 play 开放平台格式对齐，导出导入不丢信息。

目录结构与扩展入口

lib/plugins/ 规则模型 Plugin 与规则库 PluginsController，写规则的第一入口 lib/services/plugin/ RuleEngine、XPath/API 策略、规则有效性追踪 lib/pages/plugin_editor/ 规则编辑器、规则商店、规则测试页 lib/pages/search/ 聚合搜索页与以图搜番 lib/pages/video/ 播放宿主页、选集面板 lib/services/video_source/ 视频源解析与 WebView 嗅探池 lib/modules/ + lib/repositories/ 数据模型与 Hive 本地仓储 test/ 单元测试示例，改引擎前先看这里怎么写的

想加一条新规则：从lib/pages/plugin_editor/的编辑器入手，跑通后再对照lib/services/plugin/里的策略类。想改播放行为：看lib/pages/player/controller/下的细分控制器。

⚠️ 上手前必知

  1. XPath 支持是受限子集：目前只支持以//开头的选择器，写规则前先照着示例来；能检索但放不了时，关掉规则里的"内置播放器"可回退 WebView 播放。
  2. 编译需要好网络：依赖托管在 MavenCentral、GitHub、SourceForge 等处，大陆网络下要先配镜像再pub get。
  3. 超分有硬件门槛：质量档对 GPU 要求高，集显设备建议效率档，否则容易卡顿。
  4. 广告来自视频源而非应用：本项目自身不插广告，看到广告请换源。
  5. 播放内存占用偏高：Kazumi 会尽量把视频缓进内存保流畅，内存紧张的设备在播放设置里开低内存模式。

如果你只想看番，装几条规则即可直接上手；想读代码，从lib/plugins/和lib/services/plugin/入手，先写一条自己的规则跑通，再对照 RuleEngine 源码会顺畅很多。发现 bug 或想加功能，按 static/doc/CONTRIBUTING.md 的约定提交 Issue/PR——要求 Conventional Commits，且flutter test与flutter analyze都要通过。仓库地址：git clone https://gitcode.com/gh_mirrors/ka/Kazumi

【免费下载链接】Kazumi基于自定义规则的番剧采集APP，支持流媒体在线观看，支持弹幕，支持实时超分辨率。项目地址: https://gitcode.com/gh_mirrors/ka/Kazumi

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考