Kazumi 的鸿蒙原生客户端 —— 不是 Flutter 套壳，不是 WebView 包一层， 是从头用 ArkTS + ArkUI（Stage 模型） 写的 HarmonyOS 应用。 界面按 HarmonyOS Design（HDS）的范式做：渐变沉浸光感标题栏、悬浮玻璃页签条、系统材质、深浅色跟随。

版本 2.4.2.1 ｜ 目标 API 26（另带 API 23 兼容包）｜ 许可证 GPL-3.0

推荐（四档榜单）	沉浸光感标题栏	时间表

番剧详情	播放（AVPlayer）	追番

我的	采集规则	网络 / 接口配置

接口配置（可自定义 Bangumi API）	设置	关于

第二张图就是沉浸光感：列表往上滚，封面会从标题栏下面穿过去， 标题栏用「顶栏底色 → 下缘渐隐」的渐变遮罩 + 轻微失焦把它压住， 文字始终看得清，又不会像一块死板的实色板子把画面切断。 （这是 HarmonyOS 的 HDS 系统材质，不是自己画的假渐变。）

一个看番工具：番剧信息来自 Bangumi， 片源来自你自己导入的采集规则（社区维护的站点解析规则）。 它只负责「找番 → 选源 → 播放 → 下载」，不提供任何片源。

一句话：它是「鸿蒙系统里的一个正常应用」，不是一个搬过来的 App。 返回手势、控制中心、深色模式、状态栏让位、系统超分、画中画……都按系统该有的方式来。

找番

• 推荐：四档榜单随手切 —— 本季新番 / 近半年 / 历史总榜 / 评分最高，再叠 15 个题材筛选，往下翻自动加载。
• 时间表：一周七天放送表，一天一部不缺，切星期不用重新请求。
• 搜索：搜 Bangumi 条目，记得你搜过什么。
• 追番：登录后跟 Bangumi 收藏同步（想看 / 在看 / 看过 / 搁置 / 抛弃）； 没登录就用本机观看记录顶着，不空着。

看番

• 详情页：封面做头图、模糊铺底，评分/排名/放送时间/标签/简介/关联条目/角色/制作人员一屏到底。
• 选源：点「选源」→ 选规则站点 → 站内搜同名 → 命中后出剧集线路。
• 播放器：单击显隐控件、双击左右快进快退 10 秒、长按 3 倍速、横滑找进度、左竖滑调亮度、右竖滑调音量、 全屏横屏 + 锁屏、倍速、画面比例三档、播放中常亮、缓冲/解析/失败都有明确提示。
• 防盗链自动适配：有些 CDN 必须带 Referer，有些见到 Referer 就 404， 应用会自己试探一遍再决定带不带，实在播不了还能一键切「网页播放」。
• 弹幕：接弹弹play，滚动/顶部/底部三种，轨道自动避让，透明度、字号、显示区域可调。
• 下载：直接抓直链存本地，m3u8 的自动分片下载 + 解密 + 拼成一个文件，没网也能看。
• 规则：内置 6 条规则，能导入、能开关、能从规则仓库一键拉取，还能在编辑器里跑真实链路测试（取页 → 解析 → 抓剧集，逐行看诊断）。

其它

• 深浅色跟随系统，三档材质（精致 / 柔和 / 顺滑）。
• 本机观看历史：进度、续播、长按删除。
• 接口可换、代理可填、图片可走加速。

先说结论：api.bgm.tv 在国内很多网络下是打不开的（DNS 污染 / 连不通）， 这不是应用的锅。所以应用默认就带了一条能用的线路，同时也把「换线路」的开关全给你了：

设置 → 网络 → 接口配置：

• 页面里还有线路测速：同一条接口打一遍，谁快用谁。
• 请求失败会自动换线路、冷却掉线的线路、把上一次的结果先顶上（不会白屏）。
• 完全不想用第三方镜像？把上面三项清空，再关掉「镜像加速」，就只连官方地址 —— 前提是你的网络能连上 api.bgm.tv。

一句话：你可以自己填 Bangumi API，也能自己搭一个反代填进来。

去 Releases 下载：

装错包最典型的症状就是「点安装没反应 / 提示版本不兼容」： 6.1 的平板请用 -23+ 那个，别装不带后缀的（它是给 API 26 系统的）。

关于设备类型：包里声明的是 phone / tablet / 2in1。 华为现在把带「电脑桌面」的大屏平板（MatePad Pro 系列）和 MateBook E 这类设备归到 2in1， 只要 deviceTypes 里没有它，系统就会以「应用不支持当前设备类型」直接拒绝安装 —— 这一项已经加上了。

关于签名（真机装不上的头号原因）：这里发的是未签名包。 模拟器允许装未签名 HAP，真机不允许（会报签名校验失败）。 真机安装请任选一种：

1. 用 DevEco Studio 打开工程 → Project Structure → Signing Configs → 勾选 Automatically generate signature（需登录华为账号、平板要先用数据线连上，UDID 要进调试证书白名单）→ 重新 Build；
2. 用自己的发布证书签名（AGC 上建应用 → 申请发布证书 + Profile），再用 java -jar hap-sign-tool.jar sign-app ... 或 DevEco 的 Build → Generate Signed HAP 出包。

包名 app.kazumi.harmony，同签名的包可以直接覆盖升级，不会丢数据。

上游 Predidit/Kazumi 是 Flutter 的， 鸿蒙分支 ErBWs/Kazumi 用 CPF 把 Flutter 搬到鸿蒙（已暂停更新）。 本项目没有复用一行 Flutter 代码，只对齐功能语义和数据契约，界面按鸿蒙原生重画。

注：下载功能已经能用（直链、HLS 拼接都验过），但「直链暂停后续传」和「AES-128 加密源」还没有真实站点样本做过完整回归，遇到问题请提 issue。

Q：打开一片空白 / 一直转圈？ A：先看设置 → 网络 → 接口配置，点「测试连通性」。默认镜像挂了就手动换一条，或者填自己的 API。

Q：有声音没画面 / 黑屏 0:00？ A：多数是防盗链。播放页右上「更多」→「网页播放」先看，再回「播放器自检」看是哪一环失败。

Q：首页封面出不来？ A：换「封面图片」模板（{path} / wsrv 查询式都可以），或者关掉图片加速直连。

Q：为什么没有评论？ A：见上面的表 —— /p1/** 这条路径目前没有可用的公共中转。

• 语言：ArkTS（TypeScript 子集，禁用 any、限制动态特性）
• 框架：ArkUI 声明式 UI，Stage 模型，API 26（compat23 产物降到 6.1.0(23)）
• 依赖：零三方库，全部是系统 Kit（@kit.ArkUI @kit.ArkWeb @kit.MediaKit @kit.UIDesignKit @kit.NetworkKit @kit.BasicServicesKit @kit.AbilityKit）
• 播放：系统 AVPlayer + XComponent(SURFACE)，HLS/MP4 交给系统
• 解析：XPath 交给 ArkWeb 的 Chromium（DOMParser + document.evaluate）

entry/src/main/ets/
├── api/            Endpoints / EndpointRules（请求规则）/ BangumiApi（多线路竞速）
│                   Mirror（线路改写）/ Cache（TTL）/ LineStats（线路健康）/ DandanApi
├── common/         Http / Ui / Text / Logger / Diag / Prefs
│                   ImmersiveWindow（安全区）/ SystemMaterial（材质）/ HdsBars（标题栏·页签条）
├── components/     BangumiCard / Common（状态页·设置行·胶囊）/ DanmakuLayer / ArrayDataSource
├── model/          Bangumi / Plugin（规则）/ Download / Danmaku
├── navigation/     Routes + 强类型参数
├── pages/          Index（HDS 外壳 + 两个隐藏 Web）
├── screens/        Popular / Timeline / Collect / Mine / Search / Info / Video / Download
│                   Plugin / PluginEdit / History / Settings* / ApiSettings / EndpointRules
│                   Login / Character / EpisodeComments / DanmakuSearch
├── services/       XPathBridge（ArkWeb 求值）/ RuleEngine（XPath + JSONPath）
│                   VideoResolver（抓地址 + Referer 校准）/ PlayerController（AVPlayer 状态机）
│                   Downloader（队列 + HLS）/ PlayerSelfTest
└── state/          Settings / PluginStore / HistoryStore / CollectStore / DownloadStore / DanmakuMap

三件事叠在一起：

1. HdsNavigation + titleBar 样式 scrollEffectOpts = { enableScrollEffect: true, scrollEffectType: GRADIENT_BLUR }， originalStyle 透明，scrollEffectStyle 给「顶栏底色 + maskExtraHeight + blurRadius」—— 滚动后标题栏不是一块实色，而是从上往下渐隐的遮罩，下面滚过去的内容会被轻微失焦。
2. 系统材质：hdsMaterial.SystemMaterialParams（材质类型 ADAPTIVE + 三档 level）， 交给系统按当前壁纸/主题算光感，而不是自己调透明度。
3. 内容必须从标题栏下面穿过去 页面顶部占位放在滚动内容内部（List/Grid 的第一项），而不是外层容器的 padding。 用外层 padding 把列表压到标题栏下面，视觉上就变成「一刀切」的实色板 —— 这一版专门修的就是这个。

页签条用 HdsTabs + barOverlap(true) + HdsTabsFloatingStyle（圆角胶囊 + 系统材质）， 底部安全区由 ImmersiveWindow 统一注入到 AppStorage。

• XPath 模式：ArkWeb 里 DOMParser.parseFromString(html, 'text/html') 建惰性文档（不执行脚本、不拉图片）， 再 document.evaluate 求值 —— 与上游 xpath_selector 语义一致（含 [n] 位置谓词、@attr='v'、contains()、startsWith()）。
• JS 桥：javaScriptProxy 暴露 report()，runJavaScript 回传结果；注意返回值多一层 JSON 引号。
• API 模式：GET/POST + JSONPath 取值，支持自定义 Header / Body。
• 反爬识别：文本 / 正则 / XPath 三种验证页特征。
• 规则编辑器：能选一条规则跑真实链路（取页 → 求值 → 补全链接 → 抓剧集），逐行打印诊断。

选源 → 剧集页 URL
   ↓ 隐藏 Web（javaScriptOnDocumentStart 注入钩子）+ JS 桥回报 + HTML 兜底正则
媒体地址
   ↓ Range: bytes=0-1 逐个候选探测 Referer（规则 referer → 不带 → iframe → 剧集页 → 站点根，预算 4s）
带 UA/Referer/Cookie 的 PlaybackStrategy
   ↓ createAVPlayer → setMediaSource → 等 initialized → 设 surfaceId + prepare()
出图（prepared 之后才设 videoScaleType / 速度 / 超分）

两个坑，写在这里省得后来人再踩：

• 解析器是全局单例（Index.ets 里那个 1×1 的 Web），必须按「会话」隔离： 每次解析前 loadUrl('about:blank') 并轮询确认，旧文档的 setInterval 才不会把上一部番的地址塞进新会话。
• 每个 await 之后都要确认「我还属于这一页」：VideoPage.playSeq / PlayerController.openSeq 双重校验， 否则换集会出现「B 的播放页放 A」。

• 队列并发 2，解析时优先级让给播放。
• 直链（mp4/flv/mkv）走 request.agent 后台下载；m3u8 自己拉播放列表、逐片下载、AES-128 解密、顺序拼成一个 .ts。
• 进度每 10s 落盘；暂停保留句柄，继续才是真续传（不是从头下）。
• 本地播放必须用 fdSrc：给 file:// 会黑屏 0:00 且不报错。

四层防御：

1. 线路改写：Mirror.map() / Mirror.chain() —— 自定义优先、官方兜底、内置镜像垫底。
2. 阶梯竞速：主线路先发，3.5s 没结果再发下一条，谁先成功用谁（race()）。
3. TTL 缓存 + 并发合并：同 key 只发一次，失败回退过期值，不白屏。
4. 线路健康：LineStats 记延迟/失败，掉线只排队尾不删除（HTTP 4xx/5xx 不计）。

再叠一个「请求规则」：10 个接口的 base / method / path / headers / body 全部可改，保存只记 diff，解析失败自动回默认。

# DevEco Studio 26.0（SDK 26.0.0.105），命令行要显式给 SDK / Node
export DEVECO_SDK_HOME="/path/to/DevEco/sdk"
export NODE_HOME="/path/to/DevEco/tools/node"

# 默认包（API 26）
"$DEVECO_SDK_HOME/../tools/hvigor/bin/hvigorw" \
  --mode module -p product=default -p module=entry@default assembleHap --no-daemon

# 兼容包（API 23）
"$DEVECO_SDK_HOME/../tools/hvigor/bin/hvigorw" \
  --mode module -p product=compat23 -p module=entry@default assembleHap --no-daemon

产物在 entry/build/<product>/outputs/default/entry-default-unsigned.hap。 BUILD SUCCESSFUL 不等于类型检查通过 —— 还要确认没有 ArkTS Compiler Error 和 COMPILE RESULT:FAIL。

安装（模拟器可直接装未签名包）：

cd entry/build/default/outputs/default     # hdc 的本地路径按 cwd 解析，必须先切目录
hdc install -r entry-default-unsigned.hap
hdc shell aa start -a EntryAbility -b app.kazumi.harmony

2.4.2.1（本版）

• deviceTypes 增加 2in1：带「电脑桌面」的 MatePad Pro 系列、MateBook E 不再被「应用不支持当前设备类型」拦下
• 装机文档写清两个包各自对应的 API 门槛（API 26 / API 23）与真机签名要求
• 版本号 2.4.2.1（versionCode 2040201）

2.4.2

• 修复推荐页标题栏「渐变沉浸光感」丢失：列表重新从标题栏下方穿过，滚动态改用「底色渐隐 + 失焦」遮罩
• 关于页：项目主页指向本仓库，社群改为 QQ 群；新增「上游鸿蒙分支」入口
• 应用名统一为 kazuhomo

2.4.1 及更早（同一工程内的迭代）

• 番剧下载（直链 / HLS 拼接 / 本地 fd 播放）、解析会话隔离（修「B 的播放页放 A」）
• 接口请求规则可编辑、四档榜单口径、网络层竞速与缓存
• 播放器控件重排、选集改系统菜单、浅色主题与投影体系

• Predidit/Kazumi —— 上游主仓库（Flutter）。功能语义、数据契约、规则格式都来自这里，本项目是它在鸿蒙上的重写。
• ErBWs/Kazumi —— 上游鸿蒙分支。本项目参考了它的鸿蒙适配思路（尤其是媒体与网络在 OHOS 上的坑），但没有复用其代码。
• Predidit/KazumiRules —— 采集规则库，规则格式与内置规则均沿用此处。
• chen7chen —— 感谢提供大量 token，本项目开发与联调期间几乎全部接口调用都靠这些额度撑着。
• Bangumi（番组计划）提供公开 API；弹弹play 提供弹幕接口。

GPL-3.0。与上游保持一致：你可以在 GPL-3.0 下自由使用、修改、分发，但衍生作品必须同样开源。

免责声明：本项目是第三方非官方客户端，与 Bangumi、弹弹play 及任何片源站点均无关， 不提供、不存储、不分发任何影视内容，仅用于学习与个人使用。 番剧内容、商标、图标版权归原权利人所有。请支持正版。