enginJie/guoapp

红果鉴 / 真果鉴

Flutter 多端独立短剧应用，原名“短剧库 APP”。站源请求、解析、下载和播放均在设备上完成，不依赖旧项目或自建服务。当前源码版本：0.2.16+22（未验证开发快照）；现有红果鉴 / 真果鉴两份 Android ARM64 Release 安装包仍为 0.2.15+21，尚未包含本轮黄剧站源和榜单位置调整。

按用户 2026-09-21 的要求，暂停测试与回归。0.2.16 接入黄剧分类、分页在线搜索、详情与带签名 Cookie 的媒体请求，榜单图标移到顶部标题栏“排序与筛选”后面。本轮仅实施、整理源码格式和收尾同步，未运行静态分析、构建、自动化、设备或真实站源验证。0.2.15 两版 Android 构建与安装包检查记录保留。

编译方式	应用名称	可用站源
默认，不加参数	红果鉴	仅红果
构建脚本加 --all-sources	真果鉴	红果、黄豆、黄剧、黄果视频、黄果 AI、黄果旧版

全站源版首页提供“全部站源 / 红果 / 黄豆 / 黄剧 / 黄果”；全部站源只汇总当前用户获准的入口。黄剧作为独立站源；黄果统一汇总视频、AI 与旧 API 的分类和内容。六个实际接口保留各自的权限、分页、独立更新和健康检测，可在站源管理中分别维护。已有受限用户不会自动获得新增黄剧权限，管理员可在用户管理中勾选。

这是编译选项，应用内不能切换版本。标题、Android 桌面名称与电视横幅、Windows 窗口与分发文件名、iOS 显示名随编译选项变化。界面、站源调用、原生下载调度同时限制可用站源；红果版不会访问或继续执行其他站源的旧任务。

两版保留原 Android / iOS 应用标识及数据目录；Android 使用同一签名可相互覆盖升级，不能作为两个独立正式应用并排安装。Windows 沿用原内部产品标识与数据目录。切换版本保留追剧、观看记录、用户权限和下载记录；红果版隐藏其他站源内容，恢复全站源版后可继续使用。备份格式也保持兼容。

使用

功能	操作
浏览	标题栏依次提供排序与筛选、榜单图标、多选下载和展开搜索；榜单紧跟排序，窄屏常显。分类保持独立一行，内容区左右滑动切类；支持默认、名称、自然季号、上线日期、热度、播放量排序及连载状态筛选。排序作用于已加载内容，未知值置后；“更新剧库”或下拉执行查新、历史续载与资料补齐，窄屏的更新入口位于“更多”，底部加载更多
搜索	红果合并官网与名称索引，补齐可识别的缺漏季；输入停顿 300 毫秒显示最多 10 条红果联想，正式名称查询独立使用 50 条索引记录。黄剧调用站源在线搜索，按真实页码和总数继续加载；单独搜索黄剧不调用红果联想。部分失败保留有效结果；最近 20 次搜索按用户保存并可清空。其余站源只筛选已加载短剧
推荐	仅红果站源的分类栏在“全部”后显示“推荐”，点选后直接在当前页浏览；可切换真人剧、漫剧、AI 剧，分别记住推荐位置，可刷新或继续推荐。其他站源与“全部站源”不显示此入口。公开推荐不连接官方账号
详情	上方浏览封面、资料、追剧状态与可展开简介；底部固定“立即播放 / 继续播放”和下载入口。选集每组 50 集，可切换范围、定位当前或输入集数跳转；宽屏与电视采用资料、选集分栏
追剧与历史	按想看 / 在看 / 已看 / 有更新筛选追剧；追剧和历史均可搜索。卡片菜单设置状态、标记更新已读或删除单条历史；“继续观看”直达续播。每个用户独立保存，每 5 秒及退出播放时记录真实进度
卡片与批量下载	发现、追剧和历史卡片的“更多”提供收藏、状态和下载选集；电脑也可右键，电视可用菜单键。发现页长按卡片或点标题栏“多选下载”，进入后顶部显示“选择短剧”及文字“清空 / 取消”，底部显示已选数量与“下一步”，进入分集和画质预览后加入下载；一次最多 50 部，首页不再提供全选按钮
VIP	全站源版浏览黄豆或全部站源时显示 VIP 图标，仅过滤黄豆；默认隐藏已确认的 VIP，隐藏时斜线划过 VIP。封面左上角显示 VIP 标记，右上角保留菜单 / 多选。未知、免费、VIP 分别保存，未知不会覆盖已知状态；VIP 视频可能只有试看
手机播放	画面上滑下一集、下滑上一集；长按 350 毫秒临时 3 倍速，松开恢复。竖屏轻点播放 / 暂停，横屏轻点控制条，双击播放 / 暂停；进度条和菜单操作独立于画面手势
弹幕	红果在线播放默认开启；播放器“弹幕 / 设置”或电视播放设置可关闭、查看状态及失败重试。开关按本地用户保存并进入备份，本地播放不加载弹幕
横竖屏	保持视频比例；竖屏上下排列视频与选集，横屏采用视频与选集分栏。横屏视频随手机旋转进入全屏，也可手动全屏；退出后恢复方向跟随。全屏内可选集、调倍速 / 画质和打开设置，竖屏菜单在底部、横屏在侧边
Windows	播放画面获焦时，空格播放 / 暂停，左方向键后退 5 秒，右方向键轻按前进 5 秒、长按临时 3 倍速，上下方向键调音量 5%，M 静音，F / F11 / Ctrl+F 全屏，Esc 退出全屏或返回；按钮、菜单和列表保留自身键盘操作
外观	“更多 → 设置与备份 → 外观主题”选择浅色、深色或跟随系统；默认跟随系统，记住本机手动选择，配置备份也包含主题
下载	按剧分组搜索、筛选，标题栏进入多选 / 全选；支持批量暂停、继续、重试、删除及清理任务但保留视频。“更新本剧”补新增或缺失分集
更多	站源管理、用户管理、设置与备份、界面模式、关于；设置中提供下载偏好及管理员“网络与资源”

站源	浏览与播放	搜索
红果	真人剧、漫剧、AI 剧及分集	联网搜索与官网搜索联想
黄豆（全站源版）	列表、VIP 标记及分集	筛选已加载短剧
黄剧（全站源版）	热门、最新、接口分类、详情及可播放分集；签名 Cookie 接入在线播放、预加载和下载，待验证	站源在线搜索，支持继续加载
黄果视频（全站源版）	列表、详情及分集	筛选已加载短剧
黄果 AI（全站源版）	已接入列表、分类、详情及分集；0.2.12 目录和入口连接超时，历史密钥连接也未通过，播放尚未恢复验收	筛选已加载短剧
黄果旧版（全站源版）	API 分类、列表、详情及分集	筛选已加载短剧

站源可用性、清晰度和区域限制取决于源站及网络；应用不解除源站 VIP 或其他授权限制。

黄剧站源

0.2.16 依据用户提供的 黄剧.js 接入 https://huangju.net 与 https://api.huangju.net。默认“全部”使用热门目录，另提供“最新”及接口实际返回的分类；目录和在线搜索使用响应中的分页信息，失败保留已有结果。详情按真实分集编号排序，跳过明确标为不可播放的分集，保留源站总集数与连载状态；剧目身份沿用脚本的 slug-id，标题、简介、地区、年份和评分按返回资料展示。

原生核心通过 /auth/guest 建立匿名访客会话，并发请求共用一次授权；接口返回有效 JSON 的 401 / 403 时刷新一次，浏览器验证或限流错误仍遵循退避。/play/<分集 ID> 返回的 CloudFront Policy / Signature / Key-Pair-Id 三枚 Cookie 留在当前设备的媒体会话中，仅发送给该播放地址的来源；同来源的播放列表、分片、密钥、预加载及下载请求共用凭证，跨来源重定向不携带这些 Cookie。缺失凭证明确报错；已知到期时间会缩短预加载计划寿命，播放重试与下载继续重新解析地址。

黄剧复用详情回写、站源更新、下载合集、追剧与备份权限。访客令牌和媒体 Cookie 不进入追剧记录、配置备份或局域网同步；推送播放由接收设备自行取流。局域网连接不再限制为五个站源，新版用扩展能力字段交换完整范围，同时保留旧版认识的站源字段；与旧版连接时只同步双方共有的站源，黄剧记录保留在支持它的设备上。上述接口与双端行为尚未集中验证，本轮没有请求站源图片或真实媒体。

主题与导航

浅色主题使用暖白背景、深色文字，首页、追剧、详情、下载、用户和设置同步切换；播放器保持深色，返回后恢复所选主题。切换主题保留当前页面、站源及导航位置。

发现、追剧和最近观看使用一致的海报网格：封面固定 2:3，标题统一预留两行，分类或进度统一预留一行；长文字省略，系统大字同步增加文字区域高度，保持同一行卡片对齐。首页及详情页更新期间刷新图标持续旋转并禁止重复点击，完成或失败后恢复。

手机底部导航使用图标、常显文字和细线标记选中项；系统虚拟按键 / 手势区域延续当前背景，系统图标随主题调整明暗。导航支持系统大字设置、键盘焦点和无障碍选中状态。

0.2.12 将排序 / 筛选和下载多选 / 全选移入对应页面标题栏。详情将追剧与观看状态合为资料区的菜单，主要播放动作固定在底部安全区；简介默认收起，避免长资料挤占选集。详情、下载选集和播放器共用每组 50 集的范围选择、精确跳转与当前集定位，播放页集中提供上一集、选集、下一集，画质 / 倍速在空间不足时从播放设置操作。紧凑视频区域减少重复控制，实际显示和遥控操作尚待平台验证。

0.2.15 按界面反馈移除首页受 50 部上限限制的全选按钮，多选标题栏改用文字“清空 / 取消”。手机多选时以底部操作栏替换底部导航，选中数量靠左、“下一步”靠右，取消后恢复导航；电脑与电视将操作栏固定在内容区底部。空选时显示点选提示，窄屏大字改为上下排列。红果推荐作为“全部”后的专属分类在当前页切换。0.2.16 将榜单改为顶部标题栏图标，紧接“排序与筛选”，移出分类行；窄屏常显榜单，更新可下拉或从“更多”操作。

设计参考 Android 系统栏与边到边布局、Flutter 系统栏适配和 NN/g 图标可用性：处理系统安全区，保留文字标签，并提供颜色之外的选中标记。

缓存与播放恢复

目录条目及页码缓存 15 分钟；过期后先显示缓存再更新，失败保留原列表，手动刷新立即联网。红果总目录和各分类分别保存真实 offset、会话、设备标识及分页签名，续页按保存的位置请求；刷新查新保留历史续载位置。已移除 6000 条和 500 页的静默截断。目录达到 32 MiB 保存上限或写入失败时保留当前内存内容并显示未保存，先重试保存再继续加载，不把未落盘结果标为新鲜缓存。以上为 0.2.9 实现，重启等行为尚待集中验证。搜索联想失败不影响手动搜索；关闭搜索、换词、切换分类或离开页面会取消过期请求。正式搜索设 40 秒总时限，补漏季最多 32 次查询，前台目录 / 搜索等在途请求最多 16 个；不使用网页 totalCount 虚构下一页。

海报在设备内处理和缓存，首页、详情、榜单和追剧共用；有效期 30 天，上限 256 MB / 2000 张，单张上限 20 MB，超限清理较久未使用的图片。过期更新失败时继续显示缓存，失败海报可手动重试。保留 AES / XOR 解码，HEIC 主图片在本地提取后由随包媒体库转成 JPEG，兼容缓存单独限制为 64 MB / 128 张，转换串行执行并清理临时文件。缺失或失效地址会从详情补齐，重复请求合并并设置重试间隔；显式打开详情或播放会通知同一剧集的失败海报重试，后台资料更新按 ID 通知首页、分类、榜单、收藏和历史；新图床无需登记，HTTPS 连接失败可尝试可信 DNS 返回的备用地址。

倍速、画质、自动连播、下一集预加载和弹幕开关按本地用户保存，并纳入配置备份；新开播放器沿用偏好。临时 3 倍速不会改写偏好，切集、弹出菜单、失去焦点、转入后台或退出页面时结束临时倍速。关闭自动连播后，播放结束停在当前集；保存失败会提示重试。

正常播放与下载不转码、不降低清晰度。随包的 media_kit / libmpv 在设备解码；0.2.12 将远程 MP4 与 HLS 统一接入设备内流服务，处理请求头、密钥、预取缓存及应用代理，不经远程中转。本地已下载视频继续读取设备文件。

播放失败或前台连续 20 秒无进度时，优先尝试备用地址。自动画质先试同画质备用地址及兼容编码，再试较低画质；手选画质只切同画质线路。备用地址耗尽后最多重新解析一次，每轮最多自动恢复 3 次，之后提供手动重试。切线保留进度和倍速；暂停、后台不会触发卡顿切线。

下一集预加载与缓冲反馈

0.2.12 默认开启下一集预加载，可在播放设置关闭。前台正常播放至少 2 秒、播放器报告缓冲余量至少 5 秒，且已进入本集后半段或最后 45 秒时，低优先级解析并预取下一集；不启动本地视频预取。关闭、主动切集、播放失败、进入后台或切换用户会取消在途工作并释放过期播放计划，正常连播可接用已就绪计划。

解析时限 15 秒，预取最多 6 秒、4 MiB、8 次请求；HLS 限制列表深度和前两段、约 8 秒媒体，MP4 只取开头并在有效范围及版本校验通过后复用。就绪计划最多保留 2 分钟，0.2.16 对黄剧等返回有效期的计划提前 5 秒停止复用；失败至少间隔 30 秒再试，避免无限预取或反复解析。

播放器优先从 mpv 实际可跳转缓存区间显示连续缓冲时长与范围；无法取得区间时只显示播放器报告的“已缓冲至”，不把单一终点当作连续范围。0.2.12 的实现曾完成静态与核心编译检查，0.2.16 的凭证有效期处理仅完成源码接入与格式整理；预取复用、网络切换和各平台缓存反馈待集中验证。

红果弹幕

0.2.11 为两版应用接入红果在线播放弹幕，默认开启。播放器“弹幕”入口与播放设置共用开关，电视可在播放设置中操作；开关按用户保存、重启恢复并纳入备份，旧备份未包含开关时使用开启状态。

仅显示经过当前播放分集 ID、源站状态和原始毫秒时间戳校验的弹幕文字，过滤重复及无效内容；普通评论不进入弹幕。文字限定在实际视频画面内，暂停和缓冲时停止移动，倍速、跳转和切集按视频时间同步。关闭、切集、切换用户或离开播放器会清理旧内容并取消在途请求；后台隐藏弹幕并停止请求，本地播放不联网加载弹幕。

弹幕使用独立低优先级请求、短超时及有限缓存，按源站真实时间游标续载。失败只在弹幕设置中显示状态与重试入口，播放和下载可继续。Flutter 线性动画负责移动，普通播放进度回报不会重启动画，文字测量仅在内容或布局变化时执行。必要合成测试已通过，真实站源返回和各平台显示效果仍待集中验收。

追剧、更新提醒与历史

追剧可设为“想看 / 在看 / 已看”。开始实际观看后，“想看”自动变为“在看”；已知最后一集播放完后自动标为“已看”，发现更多分集时重新变为“在看”。手动“标记已看”独立保存，重看或新集更新不会覆盖该标记，也不会伪造分集和播放进度。

新集数量按已取得的目录或详情中的集数增长计算。加入追剧时记录已知集数，原先未知的集数首次补齐只建立基准；旧资料或临时变少的集数不会降低基准。卡片菜单或详情页可“标记更新已读”，手动标记已看也会将当前已知更新设为已读。进入详情、刷新目录和重启不会自行清除提醒；尚未取得的源站更新不会提前显示。

追剧与历史支持本地搜索剧名、简介和标签，不发起站源搜索。“继续观看”使用真实分集和进度，已看完的分集优先从后续可用集数开始；手动已看标记不影响续播。单条删除或清空历史会移除对应播放进度，追剧状态与更新已读基准保留。新增状态按用户隔离并进入配置备份，旧备份仍可导入。

用户与权限

“更多 → 用户管理”提供独立界面。初始用户为管理员；先设置至少 6 位管理员密码，才能创建其他用户。

管理员可勾选用户能访问的站源，设置“允许下载和本地媒体”。关闭后仅能在线观看，下载、目录、合并和导出入口隐藏，相关调用也检查权限。有密码的用户在切换或冷启动时需要解锁；存在其他用户时不能取消管理员密码。

追剧和观看记录按用户隔离。下载文件在本机共享，有下载权限的用户只能在应用中访问获准站源的内容。这些用户属于当前设备，不是远程服务器账号。

“设置与备份”可导出和恢复用户、密码校验信息、追剧、观看记录和偏好设置。备份不含视频、原生下载密钥或其他插件私有配置；恢复前校验格式并确认覆盖，视频文件保留。密码使用随机盐和 PBKDF2-HMAC-SHA256 校验值，不保存明文。

0.2.9 将用户与记录、播放 / 排序偏好、最近搜索统一作为完整本地快照提交；写入返回 false 或抛错时重新读取并恢复原快照，无法确认恢复则锁定访问。损坏用户配置不会回退成无密码管理员，恢复界面支持导出原始配置、重新读取或使用含管理员密码的备份恢复；视频与插件私有配置不参与快照覆盖。这些失败恢复路径尚未验证。

下载、后台运行与空间

在详情底部点击下载图标，选择分集和画质。“设置与备份 → 下载偏好”按用户保存默认画质及是否包含 VIP，初始为自动高清、排除 VIP，也用于批量下载和“更新本剧”。选集每组 50 集，标题栏提供全选、清空及非 VIP 选择；单次最多选择 500 集，更多分集使用多剧批量下载。VIP 集可能仅有试看，指定画质缺失时使用源站可用版本。

发现页支持多选批量下载，每次最多选择 50 部。预览先逐部读取分集，选择共同画质以及是否包含 VIP，再点击“加入下载”；读取失败的剧可单独保留为待重试，其余剧可继续添加。长剧自动分批加入，不截断超过 500 集的已选内容。重试会跳过已确认加入的分集，已有任务保持去重；停止、退出页面或切换用户后不再添加后续分集，已经提交的批次及队列任务保留。需要指定单集时，使用卡片菜单的“下载选集”。

“下载”按剧分组，支持本地搜索、下载状态和连载状态筛选。标题栏提供筛选、多选、全选当前及本地媒体入口；可按整部剧或分集批量暂停、继续 / 重试、取消 / 删除，失败结果可单独重试。批次最多 500 个任务，停止或退出后不提交后续批次，已经完成的操作保留。

“清理任务，保留视频”只隐藏已完成任务，在“已保留视频”筛选中仍可查看、恢复任务或本地播放；不占用 5000 条未清理下载任务额度，下载索引仍受 32 MiB 保存上限约束。“更新本剧”重新读取分集并更新资料，只添加新增、失败或文件缺失的分集；保留有效已下载文件、进行中的任务及手动暂停状态。每次重新完成下载更新文件版本，供合并恢复与清理核对。

同时下载数量默认 2 集，管理员可在“网络与资源”设为 1–6 集，并选择新任务是否按站源分类保存；旧目录仍可读取，开关不会自动搬动已有视频。播放和切集不会取消下载。源站支持有效的 Range 校验时续传当前文件；文件变化或不支持续传时重新下载该文件，完整 HLS 分片可复用。

• Android 使用前台服务持续下载，通知显示进度并提供“暂停下载”。系统终止进程、关机或后台服务达到系统时限后，保留任务与完整文件，重开应用可手动继续。
• Windows 下载时保持应用运行。iOS 当前采用前台下载，进入后台暂停下载和本地媒体处理，回前台后可继续下载。
• “设置与备份 → 下载目录与空间”查看占用、剩余空间，迁移视频、合并成品和导出内容。迁移前检查下载索引；损坏、超大、非普通文件或条目无效时拒绝迁移，保留原索引与视频。随后暂停下载，复制并保存新位置成功后才清理旧目录；失败保留原文件。
• Android 可选应用内部目录及设备 / SD 卡上的应用专属目录，iOS 可迁移到“文件”App 可见目录，Windows 可选普通文件夹。Android 应用专属目录随卸载或清除应用数据删除。

“本地播放”读取设备文件，可断网、跳转和续播。详情播放也优先用已下载分集；本地损坏时只有手动选择“改为在线播放”才联网。

下载保存原始 MP4 / CENC MP4 及所需密钥；HLS 保存所选画质列表、分片、初始化片段、AES-128 密钥及关联默认音轨 / 字幕。暂不支持直播、未结束的 HLS 和需要额外授权的加密方式。列表缓存不等于已下载视频。

网络与资源设置

管理员从“设置与备份 → 网络与资源”选择自动、直连或手动代理，手动地址支持 HTTP、HTTPS、SOCKS5 / SOCKS5h。设置保存在本机并用于后续请求，代理地址默认遮蔽、不进入用户配置备份；设备内播放服务始终绕过代理。

自动模式读取 Windows 当前用户及 Android / iOS 系统静态代理与排除列表，未配置时使用环境代理或直连；恢复前台及每 30 秒更新。仅配置 PAC 自动脚本而没有可用静态代理时显示配置指引，本版不执行 PAC。代理不会关闭 TLS 校验。Android 桥接已随新版 ARM64 APK 编译，iOS 桥接尚未完成平台构建；实际网络行为仍待验证。

目录请求并发可设 1–6、间隔可设 0–5000 毫秒，默认 3 与 250 毫秒；下载并发默认 2、可设 1–6。设置写盘成功后生效，仍保留前台优先、后台让行、取消、退避及请求数量边界。

局域网互联：追剧同步与推送播放（已接入，待验证）

0.2.13 接入两台设备在同一局域网直连，自动同步追剧记录或接续播放，不依赖账号服务器。同步范围按用户选择确定为追剧列表、观看状态及对应剧目的续播进度。以下描述源码中的行为与使用入口；真实双端通信、系统权限和界面效果尚未验证。

发现与自动连接

“追剧 → 标题栏同步”或“设置与备份 → 设备互联”进入同步页。设备互联按本地用户保存，初始关闭；主动“选择设备”或播放器“推送”会开启本机互联，接收端先开启一次“设备互联”。两端 App 保持前台、当前用户已解锁后发布服务，接收端不弹确认、不要求选择发起端。关闭互联、锁定、切换用户或退到后台后停止发现与接收。

服务类型为 _zgj-link._tcp DNS-SD / mDNS，发现信息仅包含设备名称、稳定设备 ID、端口、协议版本、证书指纹和同步 / 播放能力；按设备 ID 合并多个网卡地址，同一身份出现不同证书时不合并。设备名称可在同步页修改。

开启设备互联后在前台自动发现；打开“同步”或点击播放器“推送”时，优先复用当前有效连接。首次发现留出短暂收集时间：仅有一台符合当前操作要求的设备时自动配对连接；多台时在设备面板显示列表供用户选择；未发现时保留重新搜索和手动地址连接入口。记住已选目标，前台恢复和网络重连后自动重连该设备；其他设备不会抢占现有连接。尚无目标且发现多台时，在用户打开同步 / 推送入口时显示列表，不在后台扫描期间打断播放。设备列表显示手机 / 电脑 / 电视图标、名称和连接状态，连接后提供“切换设备”。

首次配对按用户要求自动完成并记录设备证书，后续连接固定校验该指纹；证书改变不静默替换已记住的设备，可从设备卡片菜单明确“忘记配对”后重新连接。已有其他设备的连接不会被抢占。记录读写使用绑定当前用户与连接的会话令牌，锁定、切换用户或退出接收状态后失效。双方“自动同步”默认开启，连接成功后启动合并；任一端关闭自动同步即停止自动合并，仍可手动同步或推送。覆盖操作及播放交接由对应按钮触发，不因自动重连而再次执行。

入口与同步页面

追剧页标题栏提供“同步”图标，“设置与备份”提供“设备互联”入口。同步页显示本机与已连接设备、双方当前用户、自动同步开关、最近同步状态、各端增删数量和冲突入口。连接状态与同步状态分别呈现，可“立即同步”或取消当前批次；覆盖操作收进“手动同步”次级入口，切换设备、断开和忘记配对均有明确入口。

手动同步面板用纵向单选卡片排列，默认“双向合并”。底部先“查看预览”，再以“开始同步”或所选覆盖方式为主要按钮；覆盖确认只在发起端进行，对方直接接收。选项下代入实际设备名，同时用文字和箭头表达方向。

选项	行为
双向合并	合并双方追剧记录，将同一结果保存到两端
覆盖对方	用本机记录替换对方当前用户在本次范围内的记录
覆盖本机	用对方记录替换本机当前用户在本次范围内的记录

预览显示两端各自新增、更新、移除、冲突及范围外保留数量，覆盖时写明设备、当前用户及移除追剧数，空列表也需查看预览。同步中禁用重复提交并保留取消按钮；手动面板处理期间禁用外部点击 / 拖动 / 返回退出，避免关闭界面后悄悄提交。手机使用安全区底部面板并避让地址输入键盘；宽屏限制面板宽高，TV 使用可聚焦按钮，触控目标至少 48×48。长名称省略或换行，选项可随大字增高，实际布局待验证。

自动同步

自动同步使用双向合并，面向当前连接且用户已选择的设备。首次连接交换版本摘要并合并差异，之后仅发送改动条目与删除标记，不重复传输完整备份。追剧增删、手动状态和已读标记修改短暂合并后发送；正常播放期间约每 10 秒发送最新已保存进度，暂停、切集、退出播放器及推送交接时立即补发，发送失败保留待同步状态。实际时机以生命周期和可用连接为准，移动端退到后台后不承诺持续联网。

断线期间继续在本机记录，前台重新连接后按版本补齐；恢复流程核对双方当前用户和权限，不沿用已经失效的用户会话。接收远端变更不生成新的本地编辑版本，避免两端重复回传；重复请求按操作 ID 与条目版本去重。更换目标设备时重新协商，不将广播发现列表中的全部设备当作自动同步目标。

没有冲突的记录自动合并；无法判断先后的并发修改保留候选并显示待处理数量，其他记录继续同步，播放中不强制弹出冲突窗口。追剧与取消追剧冲突时暂不重新加入列表，其他字段使用稳定候选显示；用户从同步页逐项选择后生成包含全部候选版本的新修改。自动接收进度只更新记录，不跳转、切集或启动播放器。暂停后的播放器不重复把同一位置写成新版本，防止推送后静止的本机进度反复覆盖对方续播。手动覆盖先暂停自动批次，结束后恢复按新版本合并。

记录范围与合并规则

范围为追剧列表、想看 / 在看 / 已看及手动已看状态、新集已读基准，以及对应剧目的续播集数和时间。未追剧的全部观看历史不加入同步；推送播放可独立接续当前剧，不要求先加入追剧。同步仅针对两端当前已解锁用户与双方编译版本 / 用户权限共同允许的站源，范围外记录保留并计入跳过数量，不复制密码、账号权限、设备设置、下载索引、视频文件或密钥。

独立同步记录以站源和原始剧集 ID 定位；追剧成员关系、观看状态与续播进度分别记录版本向量，取消追剧及清空进度保留删除标记。每台设备、每个本地用户使用独立副本标识和递增计数，用版本关系判断先后，不依赖设备时钟或最大播放位置。旧追剧数据在首次使用时补齐同步格式；对应进度不会因普通历史的 300 条显示上限丢失。

• 首次合并保留双方独有的追剧；已知的后续取消操作通过删除标记传播，避免取消过的剧下次又出现。
• 同一字段存在明确先后时保留后一次修改；两端离线同时修改且互不包含时，进入冲突预览，由用户选择保留本机或对方的值。相同值直接合并版本。
• 续播进度沿用这套版本规则，不简单取更大的集数或秒数，保留重看和主动回退的含义。
• 已知集数与已读基准按既有增长规则合并；手动已看状态独立保留。剧名和海报地址等资料更新不当作用户重新修改追剧状态。
• 覆盖操作同样生成包含双方已知版本的新修改；接收端在范围内多出的记录形成删除标记，避免之后双向合并恢复旧记录。

读写继续经过 LocalStore 的串行队列和完整快照提交，写入失败保留原记录。预览包含两端的基础版本，提交前重新核对，期间本地观看或追剧发生变化则重新计算，不覆盖后来产生的改动。每次操作具有唯一 ID 和可查询的保存结果，重复请求不重复应用；双向合并分别确认两端落盘，断线或一端失败时明确显示哪端已完成并可继续处理，不把两台设备的写入描述成一次不可分割的操作。

取消仅停止未提交部分，已经保存的记录保留；提交后丢失回执时先查询最近保存结果，仍无法确认则提示重连后合并补齐。每用户保留最近 64 次保存回执；同步记录含删除标记最多 25000 条、实际追剧最多 20000 部，单字段最多 64 个副本版本与 32 个冲突候选。差异按最多 16 条及字节大小分批，单条不超过 512 KiB，接收暂存总量不超过 12 MiB，超限保留原数据。

配置备份新增 followSync，包含追剧关联进度、历史版本、冲突与删除标记，兼容没有此字段的旧备份。恢复时生成新的本机副本标识，保留记录的历史版本；设备证书、已配对指纹、连接设置与当前副本身份不复制到另一台设备。导入和导出均限制 8 MiB，超限在写出前提示，避免生成自身无法恢复的备份。

播放器“推送”与接续播放

播放器在常规、全屏与 TV 控制区提供投放图标，提示文字为“推送”或“推送到［设备名］”。未连接时打开共用设备选择面板，已连接时直接开始准备；切换已连接目标可从同步页操作。窄屏优先保留推送和主要播放控制，次要选项在播放设置中；独立推送面板显示接收设备、剧名、准备 / 定位 / 成功或失败状态，并提供取消。

推送内容为站源、剧集 ID、分集 ID / 集数、播放位置与播放意图。接收端先匹配并校验自己已下载的同一分集，可用时直接读取本地文件，选集显示接收端已下载分集；否则独立读取站源详情并解析，不使用发起端的临时媒体地址、密钥或路径。推送中的本地文件缺失可转为在线解析，普通本地播放仍保留原有的手动改在线规则。对方没有站源权限或无法播放时返回原因，本机保持播放。仅在本机存在的合并成品不提供推送。

交接分为准备与开始两步：对方准备完成后，本机补发最新位置；接收播放器定位后实际播放、没有缓冲、取得视频尺寸且位置继续前进，才发送开播回执，本机随后保存进度并暂停。失败、超时或取消时本机继续播放；重复请求复用交接 ID，迟到回执不能暂停本机后来切换的分集。接收端主动暂停、跳转或更换内容后，旧取消请求不再控制其后续操作。对方已有其他播放时，只在发起端提示将替换的内容，接收端始终不需要确认或配对码。

技术与平台边界

采用锁定的 Flutter nsd 5.0.1 进行原生服务发现 / 发布；Go 提供独立的局域网 HTTPS 端口，与仅绑定回环地址的媒体服务分开。设备身份保存于设备应用目录，使用 TLS 1.3、双端设备证书和精确指纹校验；只接受私有 / 链路本地地址，互联请求绕过应用代理、拒绝重定向，令牌不放入 URL。Flutter 通过 FFI 处理事件、用户范围、预览、同步和播放器交接，实际写入仍由 LocalStore 完成；没有改动源站 TLS 校验。

Android 手机和 Windows 共用同步协议与界面，TV 接入可聚焦推送控件，iOS 补入 Bonjour 服务声明与局域网用途说明。所有平台仅在前台接收；系统可能要求局域网权限，Windows 需允许应用通过专用网络防火墙。自动发现失败保留私有 IP 与端口的手动连接、本机地址复制和重新搜索，不扫描整个网段。系统权限、原生插件、网络切换与真实双端操作均未验证。

方案阶段参考的开源实现与文档：

• LocalSend 与协议：参考发现、HTTPS 直连、会话和取消流程；本 App 使用 DNS-SD / mDNS 与独立协议，不兼容 LocalSend 文件传输协议。
• nsd：MIT，提供 Flutter 服务发现与发布，支持 Android、Windows 10 1903+、iOS 13+ 的原生接口。
• Syncthing 协议：参考版本向量、删除标记与重复同步的处理思路，不引入完整文件同步引擎。

合并与本地成品

“下载 → 本地媒体 → 合并成品”可一次选择最多 50 部已下载的剧加入合并队列，每部需有 2–10000 集不重复且连续的分集；允许合并连续的部分集数，存在中间缺集时明确提示，成品记录实际范围。队列逐部处理，支持暂停、继续、失败重试、取消及清理已结束记录，最多保留 500 条任务。

1. 先在本地解密或换封装，保留码流。
2. 相同格式直接合并；音轨签名包含 AAC profile 与 extradata，AAC 目标下音轨不一致或有缺失时统一为 AAC LC，仅处理音频。
3. 视频确需统一时，以数量最多的格式为目标，仅转换不一致分集；数量相同时优先保留总时长较长的格式。
4. 无音轨分集按需补静音，不丢掉其他分集的声音；不能可靠转换的编码或混合 HDR 色彩格式会明确失败并保留原文件。

视频转换目标支持 H.264 / HEVC，不会自动把全部视频重新转码。一次处理一个媒体任务，编码线程限制为 2；成品需通过时长检查及从头到尾的解码校验，处理期间禁止迁移目录或删除输入分集。

完整完成的分集准备与转换步骤保存恢复记录；重开应用后任务暂停，手动继续时核对下载版本、文件大小 / 修改时间和媒体签名，复用有效步骤，未完成的单个步骤重新处理。暂停保留中间文件，取消或成功结束清理中间文件；处理中可能同时保留原下载、准备文件、转换文件和合并输出，应预留相应存储空间。

默认保留原分集。“成品校验成功后清理原分集”为可选项，只有完整解码通过且成品索引成功保存后才执行；清理前锁定媒体操作，并在原生队列锁内逐项核对文件版本。清理失败时保留成品和可重试任务；重试可直接继续清理，不必重复合并。切换用户或平台暂停媒体任务后保留恢复进度。这些中断与清理行为仍待集中验证。

成品保存在下载目录的 library，可在“合并成品”播放、续播和删除；合并全部分集时显示“全集播放”。成品进度单独保存，不覆盖原分集进度。

Emby 导出与海报

“下载 → 本地媒体 → Emby 导出”按剧或批量导出已下载分集；“设置与备份 → 下载完成后自动导出 Emby”开启自动处理。

exports/
  剧名 [站源-标识]/
    tvshow.nfo
    Season 01/
      S01E001.mkv
      S01E001.nfo
      S01E002.mkv
      S01E002.nfo
    Season 00/
      S00E001.mkv
      S00E001.nfo

导出保存在下载目录的 exports，无损解密 / 换封装，不重新编码、不依赖临时播放地址。NFO 提供剧名、简介、季 / 集编号、唯一标识及海报 URL，减少对片名自动刮削的依赖。

0.2.12 按剧集 ID 登记并复用导出目录，补资料改名后新增分集继续写入原目录，旧导出可从记录恢复目录关联。本地合并成品的菜单提供“导出到 Emby 特别篇”，写入 Season 00，同一成品复用稳定的特别篇编号；NFO 记录实际合并范围与集数。导出先复制到临时文件并完成解码校验，源合并成品保留；删除最后一个导出条目也不会递归删除整个剧目目录。

默认只写海报 URL；源站海报需要解密或外部读取失败时，可开启“同时导出海报文件”，在后续导出时使用本地处理后的海报。已导出的剧再次手动导出会补齐海报与 NFO，不重复处理视频。

将 exports 加入 Emby 电视节目库并启用实时监控或定时扫描。Emby 在其他设备上时，需共享目录、NAS 或复制文件，手机私有路径不能直接用于另一台机器。本功能不运行媒体服务器，也不将过期站源地址写成长期订阅。

相同任务不重复处理。删除导出文件后该分集不再自动导出，可手动重新导出；导出文件和原下载分集独立，删除一份不影响另一份。

Android TV

手机与电视共用 APK，电视桌面有启动入口；自动识别，也可在“更多 → 界面模式”中手选。聚焦按钮和海报显示亮色边框。

场景	遥控器操作
浏览、弹窗、下载队列	方向键移动、确认选择、返回关闭或返回
控制条隐藏	左右快退 / 快进 10 秒，上下或确认显示控制条
控制条显示	方向键选择播放、切集、选集、设置，确认执行
进度条	左右快退 / 快进，确认暂停 / 继续
选集	每组 50 集，可切换范围、定位当前及输入集数跳转，保留 VIP 标记
播放设置	倍速、画质、追剧、自动连播、预加载和弹幕开关；切画质保留进度和暂停状态，偏好按用户保存
首页返回	先返回发现，再清空搜索；发现且无搜索词时退出

支持专用播放 / 暂停、上一集、下一集按键。播放中无操作 5 秒后隐藏控制条，暂停和操作弹窗时保持可见。竖屏视频保持原比例，不裁剪填满电视。

视频画质增强与超分方案（2026-09-22 调研，待实施）

可以在现有架构上实现。推荐先交付 Android / Windows 共用的 GPU 画质增强，再为 Windows 增加 NVIDIA / Intel 硬件超分；手机上的较重神经网络单独评估。 目标是改善低清真人短剧在实际观看尺寸下的清晰度，同时保持连续播放、音画同步和可接受的发热。首期重点是 SDR 视频约 1.3–2 倍的放大，不以所有视频输出 4倍 / 4K 为目标。

本节是针对当前 0.2.15+21 播放链路的实施方案。当前 App 尚未接入超分，也没有超分按钮；现有“清晰度”选择的是源站画质。2026-09-22 本轮完成源码和公开资料调研，只修改文档，没有运行 App 静态检查、构建、回归或设备测试。下文性能数字注明其原始测试条件，工程阈值是待验证的初始设计，不是本 App 的实测成绩。

场景判断与效果边界

首先保留最高可用源画质和正确解码。红果解析已有选择最高可用候选的逻辑；超分不能替代源站原生高码率版本，也不能把处理后的显示尺寸标成源站提供的 1080P。正常播放仍使用现有设备内流服务和 libmpv，增强发生在设备 GPU，不增加远程处理服务、不转码在线播放内容、不改写下载文件。

短剧的实际问题	优先处理	预期与边界
分辨率低，放大后轮廓和字边发软	高质量缩放、轻量学习型放大，必要时小型 CNN	可以改善边缘和局部细节；恢复的纹理不是可证明的原始细节
码率低，马赛克、蚊噪和重压缩明显	温和去伪影与匹配真实退化的模型	直接加大锐化容易放大噪声；保留皮肤、发丝、衣料，避免塑料感
快速运动、镜头切换、字幕频繁变化	优先时序稳定和播放期限	单张照片看着更锐不代表视频更好；重点防闪烁、拖影和字幕笔画跳动
原片已经被美颜磨皮、失焦或严重压缩	保守增强，保留原画对比	不承诺还原真实面部细节，不默认附加人脸重建模型
实际显示尺寸小于原片，或设备已吃紧	正常缩放 / 自动降级	不为了“超分已开启”额外放大再缩小，浪费算力与电量

Real-ESRGAN 对复杂退化、振铃和过冲建模，RealBasicVSR 指出时序传播也可能放大压缩伪影，说明“先处理退化，再适度重建”比堆叠锐化更符合本场景。SR13、SR14 2026 年针对真实短视频的 UGC 修复挑战也纳入调研，但研究模型的质量成绩不能直接当作手机播放器的可部署性证明。SR20

已核实的播放器接入条件

已核实事实	对实施的要求
项目使用 media_kit 1.2.6、media_kit_video 2.0.1；PlayerScreen 直接创建默认 VideoController。当前没有超分状态、Shader 或相关偏好	沿用现有播放器，在 lib/player_screen.dart、播放偏好和设置菜单中接入统一增强控制器
已安装的 media_kit 初始化时设置 scale=bilinear、dscale=bilinear、correct-downscaling=no，App 没有覆盖	高质量缩放本身就是可实施的第一步，但应明确称为画质增强，不标成神经网络超分
media_kit_video 通常按视频 dw/dh 创建输出纹理；桌面提供 setSize，本版本 Android 的该方法直接抛出 UnsupportedError	先补齐输出尺寸管理。只换 Shader，可能仍然让 Flutter 把原尺寸纹理放大，甚至让按放大比例触发的 Shader 一次也不执行
Android 当前使用 vo=gpu、OpenGL ES 和 hwdec=auto-safe；mpv 的 AImageReader 硬解映射会产生 RGB0 / external OES 纹理	HOOK LUMA 不一定存在。优先提供作用于 MAIN 的 RGB 路线，不能以关闭硬解、逐帧读回 CPU 为代价强行启用亮度 Shader。SR04
Windows 当前是 vo=libmpv 的 OpenGL Render API，经 ANGLE 与 D3D11 纹理交互	它不是独立 mpv 的原生 D3D11 VO。不能直接把网上的 vo=gpu-next / gpu-api=d3d11 配置套进现有控件。SR03
media_kit_libs_windows_video 1.0.11 的构建配置指向 2023-09-24 / 652a1dd；该提交的 d3d11vpp 没有超分缩放参数	NVIDIA / Intel 缩放支持于 2024-08-20 的 PR #14698 合入。Windows 硬件超分必须更新并固定原生库，不能仅更新 Dart 参数。SR05、SR06
新版 mpv 存在 hwdec_d3d11egl，可从 ANGLE 获取 D3D11 设备并注册硬解上下文	Windows 优先验证复用这条互通路径。不能只因“使用 OpenGL”判定完全不可行，也不能据此承诺当前二进制必然可用。SR07

这些结论依据本机锁定依赖源码及 mpv 上游代码，不依赖启动 App 得到的假设。SR01 libmpv Render API 当前公开的后端是 OpenGL 与软件渲染；改成 Vulkan / libplacebo 全新输出涉及原生插件工程，不能作为一个低成本开关处理。SR03

算法与成熟实现的取舍

路线	与真人短剧的匹配程度	成本与限制	本项目建议
mpv 高质量缩放：spline36，有余量再比较 ewa_lanczossharp	适合通用放大，风格较保守	相对轻量，不会重建被抹掉的信息；锐利滤镜也可能振铃	首期基础档，并作为评判其他算法的对照
RAVU：ravu-lite-ar-r2、ravu-r2-rgb、ravu-zoom-ar-r2-rgb	学习型滤波放大，适合先做低成本提升	LUMA 与 RGB 版本入口不同；zoom 支持任意倍率但在目标尺寸计算，并非总比 2倍版本快	首期重点候选；按实际纹理格式、倍率、耗时选一个，不叠加运行。SR08
FSRCNNX x2_8-0-4-1 通用模型	真正的小型神经网络放大，发布说明包含轻度压缩退化训练	是单帧 CNN；默认只作用于 LUMA，需要处理硬解 RGB 路径，不能直接套到所有手机	Windows 神经超分候选；手机后续适配。排除 LineArt 变体作为真人默认。SR09、SR10
ArtCNN / Anime4K	明确面向动漫，与真人皮肤和发丝的目标不同	ArtCNN 文档区分实时 C 系列和较重的 R 系列；Anime4K 主要面向原生 1080P 动漫	仅作为以后独立“动漫增强”选项，不做真人短剧默认。SR11、SR12
NVIDIA RTX / Intel VSR，mpv d3d11vpp	Windows 上值得优先接入的专用视频增强路径	依赖显卡、驱动、D3D11 上下文、输入格式及系统设置，配置成功不等于推理实际启用	Windows 第二批重点；不满足条件立即回到通用增强。SR06、SR23
Real-ESRGAN 通用小模型 / RealBasicVSR	前者考虑真实退化，后者利用多帧信息，适合作为效果对照	全链路开销、显存、帧间闪烁 / 状态管理都高于简单缩放；公开图片工具不是实时播放器插件	后续 Windows 本地离线修复候选，首期不塞进手机每帧路径。SR13、SR14、SR26
2026 Mobile Real-World SR、PLKSR-Rep 等紧凑模型	研究方向贴近真实退化，优于只看动漫或双三次降采样榜单	竞赛测速是小图单帧；仍需模型转换、GPU / NPU 适配和视频稳定性验证	手机第二代神经超分候选，保留可替换后端，不先自训大模型。SR16、SR17
SeedVR2 / FlashVSR 等扩散式修复	能生成丰富细节，适合高算力修复研究	存在细节生成、时间窗口、显存和算力成本；“one-step / streaming”不等于普通设备实时	不纳入在线播放首期；如以后做离线修复，单独评估。SR18、SR19
AMD AMF HQScaler / VideoSR	是额外可研究的 Windows 原生增强路线	接口含 VideoSR1.0 / 1.1；不能把名称含 SR 等同于通用神经网络，多了一套 AMF 互通成本	首期 AMD 使用通用 Shader；后续按实测收益决定是否单独接入。SR35

推荐组合：高质量缩放兜底 → 适合当前纹理的轻量 RAVU → 已验收设备上的小型 CNN 或 Windows 硬件超分。 同一帧只选一套增强主算法，避免 RAVU、CNN、RTX 和强锐化连续叠加。锐化 / FSR1 类空间缩放与神经网络超分分别命名。FSR2 等游戏时序方案需要深度、运动矢量、相机抖动等输入，普通解码视频不能直接复用其接入方式。SR36

论文数字和社区经验应如何使用

已读资料	实际证据	不能据此推导的结论
Mobile AI 2021 手机视频超分挑战正文	OPPO Find X2 / 骁龙 865 / Adreno 650，REDS 双三次退化；320×180 → 1280×720，报告最高约 80 FPS	不能当作 720P 输入、真实重压缩短剧、Flutter 合成和持续发热条件下的播放帧率。SR15
NTIRE 2026 Mobile Real-World SR 正文与官方代码	天玑 8400、FP16，速度测 128×128 → 512×512；PLKSR-Rep 总分第一、质量分第八，113.85倍是相对 OSEDiff 的加速	不能把 113.85倍写成 FPS，也不能把综合冠军当作画质最好的模型或整帧实时承诺。SR16、SR17
NTIRE 2025 Efficient SR 正文	双三次退化的图像任务，报告使用 RTX A6000 测时	“高效”榜单不能代替手机实机与真实压缩域的评估。SR38
FlashVSR 正文 Table 2 与代码说明	单张 A100、768×1408，约 17 FPS、约 11.1 GB 峰值显存，仍有 8 帧 lookahead；消费级 GPU 兼容性另有说明	不满足普通手机或常见 25–30 FPS 短剧的通用实时要求；8 帧前视也不等于零延迟。SR18
Artoriuz 的 mpv 放大博文	明确说明使用单张动漫图和人工降采样比较，并讨论训练域、下采样与抗振铃	可以学习评测方法，不能把该排名当作真人短剧或所有 GPU 的排名。SR22
Microsoft Edge VSR 工程博文	按分辨率选择模型、对电池供电和设备能力做限制，讨论每帧计算期限	可以借鉴分档和功耗策略；Edge 自有模型不是可直接移植的开源播放器组件，文中的限制也不是所有 VSR 实现的通用限制。SR24
Kazumi 的实际播放器代码	Flutter 通过 NativePlayer.command 切换 Shader，先等待播放器 / 视频控制器初始化，并把资源放到应用目录；项目使用自己的 media-kit 分支	可以借鉴集成方式，不能认为使用相同包名就有相同渲染能力，也不能照抄动漫预设作为真人效果。SR21

建议的设备端架构

flowchart LR
    A[源站原画或本地文件] --> B[现有 libmpv 解码]
    B --> C[输入格式与显示尺寸判断]
    C --> D[通用 GPU 缩放或 Shader]
    C --> E[Windows 硬件超分]
    D --> F[输出尺寸与色彩处理]
    E --> F
    F --> G[Flutter 视频纹理]
    G --> H[控制界面与弹幕叠加]

d3d11vpp 位于 mpv 视频滤镜阶段，GLSL 位于渲染阶段，上图表示可选路径，不表示两者使用相同 API。保持 Go 的媒体请求、缓存、下载及局域网协议职责不变。每帧图像留在原生 GPU 路径，不经 Dart 字节数组、截图接口、PNG 临时文件或本地 HTTP 转码再回送播放器。

建议模块与修改位置：

模块	责任与边界
VideoEnhancementController，从 lib/player_screen.dart 接入	负责选档、输入变化、状态、错误恢复和释放；复用当前播放生命周期，操作携带播放器实例与分集代次，丢弃过期结果
VideoOutputSizeAdapter	分开保存原视频尺寸与目标纹理尺寸；处理设备像素比、横竖屏、窗口大小和 Surface 生命周期，避免输出尺寸反写为源视频尺寸
增强后端	基础缩放、GLSL、Windows VPP 分别实现能力查询、应用与恢复；每次仅一个后端拥有增强配置
PlaybackPreferences、LocalStore	保存用户选择并兼容旧备份；设备能力、实测档位、驱动失效记录留在本机，不随局域网进度同步到另一台设备
lib/player_menu.dart、lib/television_controls.dart	共用选项和当前状态；手机、桌面及 TV 均有可发现入口，不依赖手势才能操作
原生适配与资源	必要改动维护在本项目 packages/ / 平台源码，Shader 放 assets/；这些根目录已在同步脚本收录范围内，新增构建输入时继续核对导出清单

Shader 从随包资源释放到应用私有目录，以版本和 SHA256 校验后原子替换，不以“文件存在”判定永远不用更新。不要求访问下载目录或手动导入 Shader。初始化后通过 NativePlayer 的属性 / 命令接口应用完整、有序的受控配置，传参使用结构化参数，处理 Windows 盘符和路径分隔规则。SR02、SR21 不在 libmpv 渲染回调内阻塞调用普通播放器 API，避免线程互相等待。SR03

输出尺寸必须先做正确：

1. 根据原始 w/h、dw/dh、SAR、旋转信息及实际视频绘制矩形，计算物理像素目标。Flutter 的逻辑像素先乘设备像素比；黑边、面板、整个桌面宽度都不算视频内容尺寸。
2. 例如 720×1280 竖屏短剧在 1920×1080 横屏桌面上完整显示时，内容约 608×1080，属于缩小，无需超分；在 1080×1920 内容区域才是 1.5倍放大。
3. 桌面通过尺寸适配器驱动 setSize；Android 补齐 Surface / Texture 的目标尺寸支持，保留原插件初始化顺序与硬解连接。窗口拖动、旋转和连续尺寸通知去抖，仅在目标改变时调整，不按每个 UI 帧重建 Surface。
4. 单独预算 CNN 的 2倍中间纹理。最终只显示 1080P，不代表中间张量也只有 1080P；720×1280 的 2倍中间图已经是 1440×2560。倍率不足或资源不够时直接换任意倍率缩放 / 轻量档，不强行运行大中间图再缩回去。

Shader 的格式与触发条件：

• 初始通用基线比较 scale=spline36、保守的色度缩放与合适的下采样；仅在基线通过后考虑更锐的 EWA 滤镜。不要套用可能一并改变其他渲染行为的整套 gpu-hq 配置。
• 对 YUV / LUMA 路径，比较 ravu-lite-ar-r2.hook 与小型 FSRCNNX；对 Android RGB 硬解路径，优先比较作用于 MAIN 的 ravu-r2-rgb.hook / ravu-zoom-ar-r2-rgb.hook。后续移植 CNN 时，亮度提取与色彩重建单独实现、检查，不能只把 HOOK LUMA 改名为 MAIN。
• 原版 RAVU 的部分 2倍 Shader 在两边放大比例超过约 √2 时才执行，FSRCNNX 发布版本的条件是两边超过 1.3倍。必须结合 WHEN 和实际输出尺寸判断生效，不能只看配置列表非空。SR08、SR10
• 根目录普通 Shader、gather 和 compute 版本的图形能力要求不同。首期优先兼容路径；只有确认 OpenGL ES 版本、采样精度、半浮点纹理及所需扩展后才启用更高要求的实现。
• 首期神经 / 专用超分限定经过验证的 SDR 路径。HDR、Dolby Vision、10-bit 或色彩信息不完整的内容维持原播放器处理，不为适配 nv12 强制截成 8-bit；不全局覆盖 BT.601 / BT.709、范围或传递函数。

Windows 专用超分：

先固定包含缩放接口和后续格式修复的 libmpv / FFmpeg / ANGLE 组合，再确认 d3d11vpp 能力和共享的 D3D11 设备。优先复用 hwdec_d3d11egl，检查混合显卡笔记本上解码、处理、显示的适配器是否一致，避免帧经过 CPU 下载 / 再上传。SR07

d3d11vpp=scale=1.5:scaling-mode=nvidia:format=nv12 仅是 SDR、相应上下文已就绪时 的参数示例；Intel 使用相应的 intel 模式。倍率由显示目标计算，滤镜需要自己的标签，卸载只移除本功能拥有的配置。未经能力确认不向当前 2023 年内核发送这组参数。mpv 文档明确指出，这些模式只启用相应驱动扩展，实际效果依赖硬件与驱动设置。SR06

第一选择是 mpv / 驱动现有路径。若改用独立 NVIDIA SDK，需要另行核对运行库、支持平台和再分发条件；调研时原 RTX Video SDK 入口已转向 NVIDIA AI for Media，不能假设旧教程中的下载与授权条件仍然成立。SR39 不把独立 MPC、浏览器或商业离线软件作为本 App 的运行依赖。

分档、性能控制与交互

首批未验证开发快照默认关闭增强。集中验证后，对通过的设备 / 后端组合开放“自动”；未知设备从保守基础档开始。判断设备时使用实际渲染后端与能力，不只根据 Android 版本、显卡品牌或旗舰机名称判断。

平台 / 条件	初始自动策略
Android 手机	实际需要放大时，先用已通过的基础缩放 / RGB 轻量路线；神经网络初始候选限制输入约不超过 540×960、输出约不超过 2.1 百万像素、倍率不超过 2，再根据整条链路数据调整
Windows 核显、AMD 或不支持专用接口的显卡	同一套基础缩放与通用 Shader；具备 LUMA、算力和显存余量时可用小型 CNN
Windows 已验收 NVIDIA / Intel 组合	可选专用超分，按目标倍率与资源余量启用；驱动升级、上下文变化或异常后重新判定
电池节省模式、发热、2倍 / 3倍播放、多个高负载任务	降低算法或输出上限，必要时关闭；插电不代表可以忽略发热
Android TV	第二优先级；复用已通过的保守策略，不能因电视输出 4K 就默认启用 4倍或重型 CNN
iOS	最后实施；单独评估 Metal / Core ML 和现有原生输出，当前不宣称支持

按 帧预算 = 1000 /（源帧率 × 播放倍速） 毫秒做保守估算：30 FPS 原速约 33.3 ms，2倍约 16.7 ms，3倍约 11.1 ms；实际还需区别按解码帧执行的滤镜与按显示帧执行的渲染 Pass。初始目标为增强新增耗时 P95 不超过该预算的约 25%，给解码、同步和 Flutter 合成留出余量；不是允许整个 App 每帧都用满这个时间。

自动降级采用持续窗口与回差：过滤切集、seek、网络缓冲及正常倍速调度后，连续约 10 秒出现明显超时 / 新增丢帧（初始候选阈值 1%），或温控恶化，就逐级降低；首期同一播放会话只自动降级，避免反复升降导致画面风格跳动。新分集或用户主动重选时才重新评估升档。异常状态和用户手动关闭立即生效。

Android 使用可用的 Thermal API、供电与省电状态辅助决策；getThermalHeadroom 不超过每 10 秒一次，处理 NaN / 不支持，不能把始终返回“无发热”的设备当作无限预算。SR29 Windows 优先根据实际渲染耗时、掉帧和供电状态判定，不依赖所有机器都能取得 GPU 温度。

显存预算包括中间特征图、纹理池和重复缓冲，不用模型文件大小代替峰值显存。例如 1080×1920 的一张 RGBA16F 纹理约 15.8 MiB，8 张已约 126.6 MiB。手机可从“新增纹理 / 张量预算约 128 MiB”作为待校准上限起步，超过预算先换档；不把该数字当作所有手机都应分配的额度。

拟定入口：播放器 → 播放设置 → 画质增强（超分），并在“清晰度”面板提供直达项。选项采用“关闭 / 自动 / 省电增强 / 清晰优先”，由设备选择具体后端；不在普通用户流程堆放模型名、Shader 路径和图形 API 名称。实际信息显示“轻量增强”“神经超分”或“已因发热降低增强”等，与用户选择的偏好分开。

提供独立“原画对比”按钮，切换同一播放器的增强状态，保持位置、倍速、音量、源画质和相同的显示尺寸，不新建第二个播放器。不要占用已有的画面长按 3倍速手势。字幕控件和 Flutter 弹幕在增强后叠加；片源本身烧录的字幕无法单独排除，需纳入质量验收。TV 入口和对比按钮均可被遥控焦点到达。

失败恢复与实际生效判定

已知问题 / 上游经验	应落实的行为
Shader 编译失败、缺少扩展、精度或半浮点格式不兼容	撤回本功能的配置，恢复基础播放并给出一次轻提示；不能把增强错误一律送入现有网络解析重试流程
glsl-shaders 已写入，但没有可用的 LUMA 或未满足 WHEN	状态标为未生效 / 当前无需增强，不显示“AI 超分正在运行”；有条件时通过实际 render pass 及新帧样本确认
GLES 精度导致偏色	media-kit #1438 是 Linux GLES 的实际报告，不是本 App Android 已复现的结论；用来建立跨后端颜色检查项，不盲目全局改精度。SR30
驱动超分日志提示 enabled，画面却没变化	mpv #15700 说明配置 / 日志不能单独证明实际效果；核对目标尺寸、输入格式、驱动活动与受控对比。SR32
d3d11vpp 因输入格式或上下文不兼容被禁用	#14758 涉及上传格式与 nv12 修正；2026 年 #18301 关于缺少 D3D11 上下文的补丁仍为 open，不能按已发布能力设计。失败及时撤回，不允许留下“只有声音没有画面”。SR31、SR33
Android TV / GPU 后端差异	mpv-android #824 的 Shield TV gpu-next 紫屏报告说明不能把统一升级 Vulkan 当作普适解决方法。SR40
seek、切集、旋转、后台、用户切换、局域网交接、播放器销毁	取消过期配置任务并释放资源；保持原有播放意图与进度，接收端按自身能力增强。增强失败不能再次推送或改写播放记录

日志以有界的版本、GPU / 后端、输入与目标尺寸、实际档位、失败阶段和耗时为主，不保存媒体地址、访问令牌或视频帧。使用 current-vo、hwdec-current、video-params / video-out-params、avsync、掉帧计数，以及支持时的 vo-passes。后者区分 fresh / redraw、单位为纳秒，并需按 mpv 的结构化 Node 接口读取；不是所有 VO 都实现，缺失不能解释为“耗时为 0”。Flutter 自身帧率不等于视频增强的 GPU 耗时。SR37

分批实施与集中验收

所有阶段目前均为待实施，不变更前面已有功能的验收状态。仍按先完整实现当前交付范围、后由用户安排集中验证的节奏推进；本轮不启动下面的测试。

顺序	完整交付范围	完成条件
SR-1：Android / Windows 共用基础	输出尺寸适配、保守高质量缩放、RGB / LUMA 轻量 Shader、偏好与备份、菜单 / 对比、状态、温控降级及错误隔离	两个平台都能明确判断实际生效；关闭和失败恢复正常播放；开发快照继续标 unverified
SR-2：Windows 专用与神经档	固定原生库、检查 ANGLE / D3D11 互通，接入 NVIDIA / Intel VPP 与小型 FSRCNNX 候选、设备与版本失效处理	不依赖外置播放器；分别验收支持、不支持和混合显卡设备，不按品牌直接放行
SR-3：手机第二代 CNN	依据首批实测挑选 FSRCNN 系或 2026 紧凑真实退化模型，完成 RGB Shader 或原生推理后端、模型资源和持续负载控制	同时胜过高质量缩放基线并满足持续播放预算，才替换自动档；ncnn / LiteRT 支持 GPU 不代表已经打通解码纹理零 CPU 往返路径。SR27、SR28
SR-4：Android TV	电视尺寸上限、遥控入口与对比、低功耗 SoC 和实际显示效果	与手机分别记录设备结论，避免电视模式默认重负载
后续可选：Windows 本地离线修复	借鉴 Video2X 的原生队列管线，输出独立增强副本，保留原文件、音轨、时序和失败恢复	单独列入后续开发范围；不改变当前下载和合并语义，不是本次实时增强的前置条件。SR25
最后：iOS	原生媒体输出和 Metal / Core ML 专项	在 iOS 独立验收后才标支持

恢复验证后的集中验收矩阵：

维度	必须覆盖
图像与内容	合成的分辨率、渐变、斜线、运动和字幕夹具；需要评价真人皮肤 / 发丝时另用用户明确提供或授权的非站源素材。本轮及后续默认验证不下载或分析站源图片
退化与时序	双三次缩小与实际编码压缩分别测；轻度 / 重度压缩、运动、切镜、暗部、硬字幕。不要仅测一张静态动漫图
尺寸与格式	360 / 480 / 720P，9:16 与 16:9，旋转 / SAR / 非整数设备像素比；显示小于源尺寸、1.25倍、1.5倍、2倍；H.264 / HEVC、RGB / YUV，以及 HDR / 10-bit 的安全回退
性能与播放	24 / 25 / 30 / 60 FPS、1 / 2 / 3倍速；首帧、切集、seek、全屏、窗口连续缩放、预加载、弹幕和同步交接；比较开启 / 关闭后的耗时 P50 / P95、峰值显存、额外丢帧和 A/V 偏差
持续负载	固定亮度、供电和环境条件，运行约 20–30 分钟，记录热稳定后的行为，不能以冷机最初几秒作为性能结论
设备	Android 至少覆盖 Adreno / Mali 和较低性能档；Windows 覆盖 Intel 核显、NVIDIA RTX、AMD、混合显卡 / 软件渲染回退；TV / iOS 独立记录
生命周期与失败	Shader 缺失 / 版本过期、编译失败、VPP 不支持、设备重置、显存不足、后台 / 恢复、锁定 / 切换用户、快速开关、已排队任务过期、偏好保存失败
质量判定	与原画及高质量缩放基线做同尺寸、同帧率对比；配对夹具可用 PSNR / SSIM，感知与视频稳定性另外评估。面部改变、塑料感、重边、字幕破坏或新增闪烁即为失败，不能只凭无参考评分或模型排名通过

分发时逐项记录代码、Shader、权重和运行库许可，固定版本 / 哈希并携带必要声明。已核对 RAVU Shader 为 LGPLv3，FSRCNNX 1.1 发布 Shader 的文件头为 LGPLv3+（其训练仓库的根许可证并不相同），ArtCNN / Anime4K 为 MIT；Kazumi 代码为 GPL-3.0。参考架构不意味着直接搬入整个项目，权重与 SDK 的再分发条件也不能从仓库代码许可证自动推导。

调研来源与证据索引

检索日期为 2026-09-22。查阅了论文摘要及相关正文、官方文档、公开项目源码、工程博文和 issue 讨论；没有访问站源图片或视频。部分通用搜索入口触发验证码 / 限流，以下结论以直接读到的公开资料为依据。单个 issue 只作为回归场景来源，不推断所有设备都有同一缺陷。

来源	类型与本方案采用的证据
SR01 media-kit	已安装锁定版本的 NativePlayer、Android / NativeVideoController、Windows VideoOutput / ANGLE 源码；对应项目上游入口
SR02 mpv GLSL 文档	Hook 阶段、格式依赖、WHEN、路径列表与自定义渲染 Pass
SR03 libmpv Render API	支持后端、OpenGL 上下文与线程约束
SR04 mpv AImageReader 源码	MediaCodec 映射为 RGB0 / external OES，解释 LUMA Shader 兼容问题
SR05 mpv 652a1dd 滤镜文档	对照本项目 Windows 2023 构建，确认当时没有 VPP 超分缩放参数
SR06 mpv PR #14698 / 当前文档	缩放扩展于 2024 年合入；实际启用依赖硬件和驱动
SR07 mpv hwdec_d3d11egl	ANGLE 设备取得、NV12 / P010 与 D3D11 硬解上下文注册
SR08 mpv-prescalers / RAVU	RGB / LUMA、2倍 / 任意倍率、抗振铃、图形能力与许可证
SR09 FSRCNN，ECCV 2016	在低分辨率特征域计算、小网络及后置放大的设计依据
SR10 FSRCNNX 1.1 发布说明与 Shader	通用 / LineArt 区别、轻度压缩训练、实际 Hook / WHEN 和文件许可
SR11 ArtCNN	明确的动漫目标、实时 C 系列与离线 R 系列区别
SR12 Anime4K	主要优化原生 1080P 动漫；低清重退化与真人并非默认目标
SR13 Real-ESRGAN，ICCVW 2021	高阶退化、振铃 / 过冲与真实图像修复
SR14 RealBasicVSR，CVPR 2022	清理模块、传播伪影和视频训练 / 推理取舍
SR15 Mobile AI 2021 视频超分挑战	手机 GPU 推理可行性与 180P → 720P 测试条件
SR16 NTIRE 2026 Mobile Real-World SR	天玑 8400、小图速度测试、质量 / 速度综合排名与公开代码
SR17 PLKSR-Rep，CVPRW 2026	紧凑 CNN、真实退化训练及竞赛加速比的实际含义
SR18 FlashVSR 论文 / 项目	A100 上约 17 FPS、显存和前视延迟，区分 streaming 与零延迟
SR19 SeedVR2 项目	3B / 7B 一步扩散修复与实际依赖，作为高算力路线对照
SR20 NTIRE 2026 Short-form UGC Video Restoration	与真实短视频更接近的修复研究范围
SR21 Kazumi 播放控制源码	已有 Flutter 应用如何管理 Shader、初始化和播放器生命周期
SR22 Artoriuz mpv upscaling 博文	训练域、下采样、抗振铃和单图评测边界
SR23 MPC Video Renderer D3D11VP 源码	已有播放器中 NVIDIA / Intel 驱动扩展的实际接入
SR24 Microsoft Edge VSR 工程博文	分辨率分档、供电限制、模型耗时与帧预算
SR25 Video2X	原生 C/C++ 视频修复、队列与离线处理路线
SR26 Real-ESRGAN-ncnn-vulkan 源码	公开实现包含上传、分块、同步等待和输出，不能等同解码纹理直接推理
SR27 ncnn Vulkan notes	GPU 能力、统一内存映射与 CPU / GPU 边界
SR28 LiteRT Android GPU 文档	GPU delegate 的线程和运行方式；独立于播放器纹理接入问题
SR29 Android Thermal API	热状态、headroom、采样频率与设备差异
SR30 media-kit #1438	Linux GLES 复杂 Shader 的采样精度 / 偏色报告
SR31 mpv #14758	VPP 上传格式失败、NV12 处理与只剩声音的后续报告
SR32 mpv #15700	“已启用”日志不足以证明 RTX VSR 实际生效
SR33 mpv PR #18301	缺少 D3D11 设备时的滤镜失败；调研时仍未合入
SR34 mpv #8137	多帧 / 持久纹理需求；普通 GLSL 配置不等于已有时序 VSR 框架
SR35 AMD AMF HQScaler	VideoSR / FSR 枚举与额外原生处理路线
SR36 FidelityFX FSR2 文档	游戏时序重建所需深度、运动矢量和抖动等输入
SR37 mpv 属性文档	render pass 统计、计时单位、掉帧和音画同步属性的边界
SR38 NTIRE 2025 Efficient SR 正文	A6000 图像基准与双三次退化，说明性能数据需带上下文
SR39 NVIDIA AI for Media	RTX Video SDK 旧入口的当前目标，独立 SDK 选型与授权需重新核对
SR40 mpv-android #824	Shield TV 切换 gpu-next 后紫屏的设备兼容报告

安装包与平台状态

0.2.15+21 已完成两版 Android ARM64 打包与安装包检查，签名与 0.2.10+16、0.2.14+20 一致，ARM64 分包版本码递增至 2021，可直接覆盖升级。此版本包含启动导航修复与首页多选、推荐、榜单的布局调整。Windows / iOS 完整应用仍待相应平台构建，本轮没有进行设备运行确认。

0.2.16+22 的两版 Android 三种架构 APK、两版未签名 iOS IPA 和两版 Windows 完整包已由 GitHub Actions 构建，APK 使用固定发布证书签名并在构建中校验证书指纹，可从发布仓库的 Release 直接下载。构建通过只代表编译和打包完成，尚未进行设备安装、运行和真实站源验收。

平台	包与状态
Android 8.0+ 手机	0.2.15+21 提供两版 arm64-v8a APK；ARMv7 / x86_64 构建脚本保留，目前仅有历史版本安装包
Windows 10/11 x64	完整 ZIP 解压后运行 hongguojian.exe，全站源版为 zhenguojian.exe，保留所有 DLL 和 data；局域网原生发现依赖 Windows 10 1903+。0.2.16+22 已由 Actions 构建并检查包内文件，运行器的自检在播放器开始播放一步超时（无音频和图形设备），未做设备验收
Android TV	与手机共用 APK，旧版电视界面与遥控有自动化记录；0.2.12 选集 / 设置及 0.2.13 同步 / 推送操作未验证，待电视实机验收
iOS 15.1+	已加入工程、Go 核心链接、媒体依赖、文件管理、系统代理桥接、Bonjour / 局域网权限和构建脚本；Actions 已产出未签名 IPA，需用自签工具安装，尚无已签名 IPA 和真机验收

当前版本	安装包	大小
红果鉴，仅红果	dist/android/hongguojian-0.2.15+21-arm64-v8a.apk	30.9 MB
真果鉴，全部站源	dist/android/zhenguojian-0.2.15+21-arm64-v8a.apk	30.9 MB

两份安装包的 SHA256 校验值保存在 dist/android/SHA256SUMS.txt。应用名称、包名、版本、签名、包 CRC、ZIP 对齐和对应原生核心均已核对；实际运行行为仍待安装验收。

从 0.2.6 起，Android APK 默认压缩原生 .so 库，对红果版和全站源版同时生效。系统在安装时解压原生库后加载，缩小安装包下载体积；安装后仍需保留解压后的原生库空间。

INSTALL_FAILED_NO_MATCHING_ABIS 表示 APK 与设备架构不匹配，请更换对应架构安装包。

GitHub Actions

将 guoapp 源码发布到仓库根目录，保留 .github、锁文件、native 和平台工程；不用上传 SDK、依赖目录、SO、DLL 或缓存。

推送 main / master、v* 标签、提交 PR，或手动运行 Build app packages，会先检查再构建：

红果版 Artifact	全站源版 Artifact	内容
hongguojian-android	zhenguojian-android	三种架构 APK 和 SHA256
hongguojian-windows	zhenguojian-windows	完整 ZIP 和 SHA256；从解压包检查原生核心、FFprobe、换封装及播放器启动
hongguojian-ios-unsigned	zhenguojian-ios-unsigned	未签名 .ipa 和 SHA256，需用 AltStore / Sideloadly / TrollStore 等工具自签后安装

Actions 分别传入默认参数与 --all-sources 构建两版，Flutter 和 Go 回归也覆盖两种编译配置。产物保留 14 天；main 分支的 Android 和 iOS 构建成功后，release 任务把两版安装包发布到 GitHub Release（标签 app-v<版本号>，例如 app-v0.2.16-22），Windows 包在通过时一并发布，Release 附件长期保留且无需登录即可下载，重复构建会覆盖同名附件。当前发布仓库为 https://github.com/chenweitian423/guoapp，下载页 https://github.com/chenweitian423/guoapp/releases。附件名以 hongguojian-（红果鉴）或 zhenguojian-（真果鉴）开头，Android 按架构以 arm64-v8a、armeabi-v7a、x86_64 结尾，SHA256SUMS.txt 为校验清单。

Android 正式发布持续使用同一签名并递增构建号，在仓库 Secrets 配置：

Secret	内容
ANDROID_KEYSTORE_BASE64	JKS 文件 Base64
ANDROID_KEYSTORE_PASSWORD	签名文件密码
ANDROID_KEY_ALIAS	密钥别名
ANDROID_KEY_PASSWORD	密钥密码

未配置时生成预览 APK，不同构建机的预览签名可能无法相互覆盖。当前发布签名文件为 guoapp-release.jks，别名 guoapp，证书 SHA-256 为 3F:DC:07:A2:29:74:21:37:36:07:C0:98:F9:B8:47:C1:37:7D:92:66:EE:07:00:3B:9D:7F:DA:8C:4B:58:1D:8A；更换签名文件会导致老版本无法覆盖升级。Android 构建后会自动校验 APK 的签名证书指纹，与上面不一致时直接失败。创建签名文件并保存到项目外：

keytool -genkeypair -v -keystore guoapp-release.jks -storetype JKS -alias guoapp -keyalg RSA -keysize 2048 -validity 10000

本地不入库的 android/key.properties：

storeFile=/absolute/path/guoapp-release.jks
storePassword=你的密码
keyAlias=guoapp
keyPassword=你的密码

开发与构建

Flutter 3.47.4、Dart 3.12+、Go 1.24.1+、Python 3.10+。Android 需要 JDK 17、SDK 36、NDK 28.2.13676358；Windows 需要 Visual Studio 的 C++ 桌面组件及 MinGW-w64 x64；iOS 需要 macOS、完整 Xcode 和 CocoaPods。

将 Flutter、Go、Python 加入 PATH，Android 设置 ANDROID_HOME。构建脚本对子进程默认设置 GOPROXY=https://goproxy.cn,direct、GOSUMDB=off，不改全局配置；同名环境变量可覆盖。

python3 scripts/build_android.py
python3 scripts/build_android.py --all-sources
python3 scripts/build_android.py --abi arm64-v8a
python3 scripts/build_android.py --cn-mirrors

首条默认生成红果鉴，第二条生成含全部站源的真果鉴。--all-sources 可以与 --abi、--cn-mirrors 组合，例如 python3 scripts/build_android.py --all-sources --abi arm64-v8a --cn-mirrors。

Windows PowerShell：

.\scripts\build_windows.ps1
.\scripts\build_windows.ps1 -AllSources
.\scripts\build_windows.ps1 -ChinaMirrors

Windows 也可运行 python scripts/build_windows.py --all-sources；省略参数为红果版。

国内构建可使用以上镜像开关：Flutter/pub 使用 storage.flutter-io.cn / pub.flutter-io.cn，Android 的 Google、Maven Central 和 Gradle 插件依赖优先使用阿里云镜像，同时保留官方仓库。已有环境变量优先；镜像配置仅作用于本次构建，保留锁定的依赖版本与 SHA256 校验值；结束后恢复原锁文件并清理临时 Gradle 配置，不改全局代理。GitHub Actions 默认使用官方源。镜像可能有同步延迟，遇到镜像缺失或异常可去掉开关重试；此开关不替代 Flutter SDK 和 Gradle 发行包的初次安装。

iOS 未签名构建、只生成核心、或额外生成模拟器核心（不会启动模拟器）：

python3 scripts/build_ios.py
python3 scripts/build_ios.py --all-sources
python3 scripts/build_ios.py --core-only
python3 scripts/build_ios.py --core-only --simulator

签名 IPA 使用自己在 Xcode 配置的签名身份、描述文件与 ExportOptions：

python3 scripts/build_ios.py --export-options /path/to/ExportOptions.plist

产物在 dist/android、dist/windows、dist/ios，红果版以 hongguojian- 开头，全站源版以 zhenguojian- 开头。iOS 脚本将 Go 核心生成 XCFramework，再经 CocoaPods 链接并检查 FFI 导出符号；媒体库随应用打包。

首次 Android 调试先编译对应架构核心：

python3 scripts/build_native.py --platform android --abi arm64-v8a
flutter pub get --enforce-lockfile
flutter run

Windows 对应 --platform windows 和 flutter run -d windows。

直接使用 Flutter 命令调试全站源版时，先给 build_native.py 加 --all-sources，再运行 flutter run --dart-define=ALL_SOURCES=true；iOS 对应 build_ios.py --core-only --all-sources。切回默认版同样重新构建默认核心，Flutter 参数省略或设为 --dart-define=ALL_SOURCES=false。脚本会同步设置 Dart 常量和 Go 编译参数，应用启动时检查二者是否一致，避免混装原生库。

播放器使用 media_kit / libmpv，合并和导出使用 FFmpegKit min-gpl，含 FFmpeg、x264 / x265 等 GPL 媒体组件，各组件适用上游许可证。FFmpegKit 不参与正常播放或下载的转码；系统 FFmpeg 只用于开发验证，用户不用另装。

集中检查与真机回归

按用户最新要求，本轮只实施功能、整理源码格式并执行收尾同步；以下静态检查、构建、自动化及设备回归命令保留供以后集中安排，不表示当前快照已执行：

python3 -m unittest discover -s scripts -p 'test_*.py'
dart format --output=none --set-exit-if-changed lib test integration_test test_driver
dart analyze --fatal-infos lib test integration_test test_driver
flutter test --dart-define=DISABLE_REMOTE_IMAGES=true
flutter test --dart-define=DISABLE_REMOTE_IMAGES=true --dart-define=ALL_SOURCES=true
cd native
go test -race ./...
go test -race -ldflags="-X duanjuapp/native/core.buildAllSources=true" ./...

合成媒体验证需要开发机安装 ffmpeg / ffprobe。测试覆盖权限隔离、备份校验、搜索防抖与旧结果、仅少数分集转码、CENC 解密换封装、Emby 元数据及删除原文件后的完整解码，不请求站源图片。

Android 回归使用独立 .debug 包。连接并授权 USB 调试、保持设备解锁：

python3 scripts/create_test_media.py
python3 scripts/serve_test_media.py

另一终端运行：

adb reverse tcp:38473 tcp:38473
flutter drive --driver=test_driver/playback.dart --target=integration_test/playback_test.dart --dart-define=DISABLE_REMOTE_IMAGES=true --dart-define=FIXTURE_BASE_URL=http://127.0.0.1:38473

多设备时指定序列号，可加 --dart-define=CHECK_LIVE_CATALOG=true 检查红果目录元数据。用例覆盖 MP4 / AES HLS / CENC、切线、切集、横屏、离线下载、合并 / 导出及最小化后的后台下载。结果在 build/device-test/results/；结束后停服务并执行 adb reverse --remove tcp:38473。

源码同步与恢复

每次完成任务并通过必要检查后执行：

python3 scripts/finish_task.py --message "本次实际完成的变更"
python3 scripts/sync_source.py --check

尚未完成集中验证和平台验收时，使用带 unverified 的开发快照 tag。本轮黄剧站源与榜单位置调整的源码快照为 v0.2.16-unverified，表示源码可恢复，不标为完成验收的正式版本。首页布局与 Android 打包快照 v0.2.15-unverified、启动修复快照 v0.2.14-unverified、局域网同步与推送快照 v0.2.13-unverified、界面与媒体流程快照 v0.2.12-unverified、红果弹幕快照 v0.2.11-unverified、0.2.10 功能快照 v0.2.10-unverified 与打包修复 v0.2.10-unverified-task-20260921-055042 保留。源码同步一致性确认仍执行。

局域网自动连接、记录自动同步与推送播放的早期方案文档快照 v0.2.12-unverified-lan-design 保留；该历史快照仅有设计，0.2.13 才接入实现。

脚本同步纯源码到同级 ../guoapp，保留 .git 历史，创建本地提交和带说明的 tag；默认 v<版本号>，同版本后续修复加时间后缀，不覆盖旧标签，不自动推送 GitHub。

只同步用 python3 scripts/sync_source.py；在 guoapp 内工作时跳过向自身同步。保留必要源码、资源、锁文件、测试、平台工程和 Actions，排除依赖、SDK、缓存、产物、签名及个人配置。

恢复示例：

cd ../guoapp
git switch -c restore-v0.2.3 v0.2.3

从恢复分支继续工作，避免用尚未还原的开发目录再次覆盖；安装包和个人配置不属于源码恢复点。

目录	内容
lib	页面、播放器、本地用户、FFI、下载和媒体处理
native/core、native/bridge	独立站源核心、缓存、下载、目录迁移及 C ABI
android、windows、ios	平台工程与必要资源
scripts、.github/workflows	构建、签名、验证、同步和版本快照
test、integration_test	自动化与设备回归

功能 TODO：与旧短剧库对照

以下对照 ../短剧库 与红果专用版 ../果果剧库 的功能和近期修复，基于 2026-09-21 的 0.2.6 审查，并更新至 App 0.2.16+22 的源码实施状态。已有解析辅助代码不代表 App 已接入功能；未完成集中验证与平台验收的项目保持未勾选，标明实际实施与检查范围。同时记录 App 自身的数据与恢复边界缺陷。Android 手机和 Windows 同为首要平台，设备验收单独记录。

共 31 项：3 项沿用历史已完成标记，26 项已实现但待集中验证，1 项为黄果 AI 播放恢复的外部连接阻塞，1 项为已调研、待实施的视频画质增强与超分。0.2.12 已补入原清单最后六项可独立实施的功能及界面调整；0.2.13 接入新增 P3-2 / P3-3，2026-09-22 新增 P3-4 调研方案；0.2.16 接入 P1-9 黄剧站源。新增功能均保留未验证状态，功能范围与验收状态分别记录。

旧项目的“黄果”包含多个独立入口，需逐个对照：

旧项目入口	App 对应入口	当前状态
红果 hongguo	红果	已接入；默认版唯一开放站源
黄豆 huangdou	黄豆	已接入，仅全站源版开放
黄果网页 huangguoai	黄果 AI	已接入候选域名切换、逐站更新和健康检测
黄果备用网页 huangguo-video	黄果视频	已接入浏览器会话、网页 / 媒体请求区分、真实播放页 Referer、预览令牌、逐站更新和分阶段健康检测
黄果旧 API cloudfront	黄果旧版	已接入候选域名探测 / 自动发现 / 失效重选、独立访客会话、分页目录、分集、播放和下载；仅全站源版开放

从首页“更多 → 站源管理”或设置进入独立管理页。每个入口显示缓存数量、分页位置、最近更新时间、任务阶段和错误，可分别更新、继续一页、补齐资料、停止任务和检测；检测结果持久保存。更新合并新增内容并保留目录页码和其他站源缓存，每轮补齐最多 8 部资料；已完成的条目留在缓存，重复点击不启动重复任务。0.2.7 已修复补齐后的分类副本与菜单持久化；0.2.9 已补齐红果游标持久化并移除静默截断，待以后集中验证，见 P1-R1～P1-R2。Android 使用现有前台服务维持后台任务；进程终止后显示中断状态，可再次继续。站源任务只面向编译版本和当前用户获准的入口。

0.2.10 将首页刷新统一为“更新剧库”，复用上述 update 任务：更新当前站源组，“全部站源”更新本版本与当前用户获准的所有入口。保留当前分类、搜索和列表，紧凑提示栏显示阶段、失败和停止入口，离开首页后原生任务继续；重复点击不重复提交。任务结束后读取本地目录与真实分页位置，更新列表、追剧资料和新集数量，不再额外请求一次首页。每轮查新、继续一页历史内容并补齐最多 8 部待补资料，可再次更新继续推进。

“检测连接与播放”依次检查目录解析、分集、播放地址 / 播放列表、密钥和媒体连接；“仅检测目录”明确标注播放未检测。默认抽取当前站源一部免费剧集，从播放 / 详情错误页进入则检测当前剧集；媒体探测最多读取开头 1 KB，不下载整集、不请求海报。面板显示失败阶段、HTTP 状态、检测时间、重试倒计时，支持复制不含凭证的诊断结果。检测通过代表抽样连接正常，不代表所有剧集均可播放。

0.2.8 为检测详情增加展开 / 收起箭头，点击检测摘要即可切换；收起后仍显示检测结论、时间及复制入口。进入站源管理时历史详情默认收起，主动发起连接或目录检测时展开当前站源。各站源独立记录本次页面中的展开状态，手动收起后，轮询、检测完成及其他更新不会将详情重新展开。

0.2.4 修复黄果视频把 M3U8 当作网页导航发送、丢失真实播放页 Referer 的问题。播放列表、分片、密钥和下载共用媒体请求链路；媒体 URL 的签名参数及最终重定向地址保留。源站 /api/hls_key/ 使用独立预览令牌和浏览器 Cookie 会话，令牌到期可刷新一次，不向其他域名发送。CF 拒绝和 HTTP 200 验证页仍按失败处理，倒计时不再受原生核心时区影响。若网络或源站策略仍要求交互验证，诊断会显示失败；本版没有交互式浏览器验证器，不承诺任意网络均可通过 CF。

海报加载没有手工维护的图床域名白名单，合法 HTTP / HTTPS 地址按站源权限访问，新图床无需登记。黄果浏览器兼容请求保留图片 Accept、请求类型和 Referer；开发验证不请求站源图片。

0.2.7 将站源、榜单与搜索按钮收进标题栏；搜索默认收起，下方只有一行横向分类。黄果只显示一个站源，汇总视频、AI 与旧 API 的内容和分类，同名分类合并；各接口独立保存分页，部分失败时保留其他成功结果并重试失败页。分类合并站源菜单与本机已缓存剧库中的细分类，补读 category_name、typeName / type_name、sortName / sort_name，真人剧 / 漫剧 / AI 剧不再遮蔽都市等细分类。细分类范围与 Go 版一样取决于已更新资料；初装尚未更新完整剧库时，分类数量不会等同于已经长期更新的 Go 剧库。资料补齐及详情回写会同步已有分类副本，写盘保留分类菜单。

黄果 AI 密钥与媒体连接遇到 EOF 时，设备端会尝试可信 DNS 返回的备用公网地址，保留原 Host、TLS 主机校验、签名参数、Referer 和代理路径，成功地址按 DNS 有效期复用。旧版相对封面路径改用图片 CDN，已缓存和收藏中的旧错误地址会在加载时修正；继续兼容 XOR 与黄果 AES 封面格式。旧版单个剧集返回 404 不再将整个 API 域名停用。

上述 DNS 回退已通过合成用例，但 0.2.5 对截图同剧的线上检查仍在密钥 CDN 的 TLS 握手阶段失败；目录、分集和播放列表正常。不能据此认定 AI 已恢复播放，也不能认定源站在所有网络均不可用。此问题继续保留在待办中。

0.2.12 的只读连接诊断中，AI 目录请求超时，huangguoai.com、ttvoij.ediayikma.cc、thu.agdkczeyx.cc 的入口连接也超时，尚未进入密钥和媒体检查。当前开发环境缺少可通的入口，P1-4 保持阻塞；这不代表所有用户网络均不可用，也没有降低 TLS 校验来绕过连接失败。

优先修复：分页、资料与近期协议差异

“两版”指默认红果鉴与全站源真果鉴；黄豆、黄果专项仅用于全站源版。保留原有功能编号，资料模型与搜索问题分别归入 P1-7 / P2-8、P1-8，不另建重复待办。

编号	范围	已确认问题与代码依据	修复验收
P1-R1	[ ] 已实现，待验证；两版	0.2.9 按总目录与分类保存实际 offset、会话、设备标识、分页签名及最后 ID；与目录在同一快照落盘。保留查新与历史续载位置，会话过期重新申请，重复 / 不前进的页保留旧位置	待集中覆盖重启 offset=18、会话过期、重叠页和分类独立续载
P1-R2	[ ] 已实现，待验证；两版	0.2.9 移除 6000 条和 500 页静默上限，按 ID 合并并持久保存；真实 32 MiB 保存限制会明确报错并暂停继续请求，保留待保存数据	待集中覆盖第 6001 条、第 501 页、重启和跨分类去重
P1-R3	[x] 0.2.7 两版	详情及资料补齐按 ID 更新已有目录和分类副本，补齐写盘保留 Categories；分类菜单与本机细分类合并	使用合成资料检查字段别名、详情回写和重启恢复；设备操作由用户安装验证
P1-R4	[ ] 已实现，待验证；两版	0.2.9 补齐黄果网页与旧 API 详情字段，贯通 Go / Dart 资料；详情与播放动作通知同 ID 的列表及失败海报，按 ID 合并收藏 / 历史。红果日期、黄豆缺失热度等资料独立低优先级补充，不阻塞播放	待集中覆盖跨页面回写、同 URL 失败重试、附加资料失败和旧缓存
P1-R5	[ ] 已实现，待验证；全站源版黄豆	0.2.9 优先识别合法明文 JSON，再走 AES 解码，保留 gzip 兼容；使用 UseNumber 保留长 ID	待使用纯文字夹具集中覆盖明文、密文、异常载荷
P1-R6	[x] 0.2.7 全站源版，黄豆	海报 Referer 跟随 API 当前实际入口，保留站点自身图片的来源规则	合成地址检查备用入口来源头；没有请求真实图片
P1-R7	[ ] 已实现，待验证；两版	0.2.9 索引加载失败时禁止迁移与重写；先检查普通文件、大小、条目、重复 ID 和状态，拒绝 null 索引，保留原文件；复制及提交前检查取消	待集中覆盖损坏 / 超大索引、写盘失败、迁移中断及重启
P1-R8	[ ] 已实现，待验证；两版	0.2.9 将目录及站源记录的写入失败传回页面 / 任务，标明尚未保存，保留可用内存数据；提供重试保存，未保存前不继续推进游标。推荐内容与位置共用同一持久化边界	待集中覆盖文件冲突、空间 / 权限失败、32 MiB 限制和重启
P1-R9	[ ] 已实现，待验证；两版	0.2.9 区分首次启动与配置损坏；异常用户记录、丢失用户配置或不完整快照锁定访问。提供原始配置导出、重新读取及管理员密码验证后的备份恢复，不降级管理员保护	待集中覆盖访客 / 管理员损坏、冷启动及恢复流程
P1-R10	[ ] 已实现，待验证；两版	0.2.9 所有用户设置与记录检查保存结果，串行提交完整快照；失败重读并回滚原快照，无法确认时锁定。备份一次替换完整用户快照，视频和插件私有键保持独立	待集中覆盖 false、异常写入、恢复中断、用户隔离和重启一致性

功能完善

顺序	功能	实施状态与待验证内容
P1-4	[ ] 外部连接阻塞：黄果 AI 播放恢复	0.2.12 目录及三个已知入口在当前开发网络超时；此前截图同剧的密钥连接仍为 TLS 握手断开。需可通的入口与密钥 / 媒体链路后再检查真实播放，不能以目录或 M3U8 成功代替播放成功
P1-5	[x] 0.2.7 榜单	红果总热播 / 真人剧 / 漫剧 / AI 剧四榜；全站源版另有黄豆总榜 / 魔改 / 搜索 / 收藏 / 完结榜和黄果热播 / 推荐 / 潜力榜。保留源站名次与顺序，支持分页、刷新、详情播放；缓存持久化，5 分钟内复用，请求失败可回退 24 小时内的旧榜单，明确提示未更新。编译版本及当前用户权限同时生效；0.2.16 榜单图标位于顶部标题栏“排序与筛选”后面，窄屏常显，移出分类行，新布局待验证
P1-6	[ ] 已实现，待验证：红果分类推荐	0.2.9 接入真人剧 / 漫剧 / AI 剧推荐，独立保存推荐游标、会话、近 540 条请求去重记录及完整已取得条目。刷新开启新一轮，继续推荐恢复位置；编译版本及用户权限生效，失败保留当前内容，不含官方账号个性化同步。0.2.15 入口移至红果分类“全部”后的“推荐”，内嵌当前页显示，其他站源不显示；推荐选择不会作为站源分类 ID 发往目录接口
P1-7	[ ] 已实现，待验证：排序与完整资料	0.2.9 透传、持久保存热度、播放量、日期、标签和连载状态；首页增加名称、自然季号、日期、热度、播放量排序及状态筛选，未知置后；全站源版加入“全部站源”。排序 / 筛选偏好按用户保存并进入备份；附加资料独立异步补齐。0.2.12 排序 / 筛选移至标题栏，详情资料和主要操作重新布局
P1-8	[ ] 已实现，待验证：搜索完整性	0.2.9 红果合并官网及名称索引，按 ID 去重并保留同名不同 ID，补识别到的漏季；加入归一化、分词匹配、相关度和自然季号排序、最近 20 次搜索。联想 10 条与正式索引 50 条独立；总时限 40 秒、补漏季最多 32 次，保留部分成功结果，不虚构下一页。目录 / 搜索取消贯通 FFI，前台在途上限 16；0.2.16 新增黄剧在线分页搜索，其余站源仅筛选已加载内容
P1-9	[ ] 已实现，待验证：黄剧站源	0.2.16 依据用户提供的黄剧脚本接入访客授权、热门 / 最新 / 实际分类、分页目录与在线搜索、详情及真实分集；CloudFront 签名 Cookie 限定媒体来源，贯通播放、预加载、下载和健康检测。复用用户权限、资料回写与局域网共同站源协商。未进行真实接口、播放、下载、双端或平台验证，仅全站源版开放
P2-1	[ ] 已实现，待集中验证：追剧与历史完善	0.2.10 接入想看 / 在看 / 已看筛选、独立手动已看、新集数量与已读基准、直接续播、本地追剧 / 历史搜索和单条删除；状态按用户保存并纳入兼容旧格式的备份。针对性检查覆盖进度独立、旧记录读取、增长 / 回退 / 未知集数、重启、备份、写入失败和用户隔离；平台行为待验收
P2-2	[ ] 已实现，待集中验证：剧库管理与统一更新	0.2.10 首页复用站源 update 任务，接通查新、历史续载、最多 8 部资料补齐、阶段提示与停止；结束后只读取缓存并保留分页。卡片加入收藏 / 状态 / 下载操作，发现页支持最多 50 部多选、分集预览、画质 / VIP 选择、分批加入及部分失败重试。0.2.15 移除首页全选，顶部使用文字清空 / 取消，底部固定选择提示和下一步。历史针对性检查覆盖任务去重、编译范围、停止、用户切换、重复任务、第 501 集后继续添加与窄屏大字；新布局、P1-R1～P1-R4 和平台完整行为仍待集中验证
P2-3	[ ] 已实现，待集中验证：红果弹幕	0.2.11 接入设备端独立请求、分集与原始毫秒时间校验、有界分页缓存及 Flutter 线性渲染；同步暂停、缓冲、倍速、跳转、切集和后台状态。手机 / 电脑及 TV 设置提供开关、状态和重试，开关按用户保存并进入备份；普通进度回报不重启动画，布局变化时才测量文字。两版针对性检查覆盖取消、迟到结果、失败隔离、动画、备份、用户切换和大字界面，真实源站及平台效果仍待验收
P2-4	[ ] 已实现，待验证：下一集预加载与缓冲反馈	0.2.12 接入低优先级解析、最多 6 秒 / 4 MiB / 8 次请求的预取、HLS 前两段和 MP4 前缀复用；计划超时、失败退避、切集 / 后台取消及用户开关已接通。读取 mpv 实际可跳转区间显示连续缓冲，降级只显示缓冲终点；待验证取消、版本 / Range 校验、连播复用和平台反馈
P2-5	[ ] 已实现，待验证：下载合集与批量操作	0.2.12 按剧分组、搜索及任务 / 连载状态筛选，支持合集或分集多选暂停、继续、删除、重试及部分失败重试。更新本剧补新增 / 缺失分集，保留有效文件与暂停状态；可清理已完成任务但保留视频，恢复或本地播放。任务状态先保存再取消 / 删除；待验证批次中断、文件缺失、索引失败和用户切换
P2-6	[ ] 已实现，待验证：下载偏好与目录组织	0.2.12 按用户保存默认画质 / VIP 选择并纳入备份，接入单剧、多剧及合集更新；管理员可设下载并发 1–6、按站源保存新任务，兼容原扁平目录。待验证重启、备份、目录迁移和并发调整
P2-7	[ ] 已实现，待验证：合并流程完善	0.2.12 音轨签名加入 AAC profile / extradata，不兼容的 AAC 音轨统一到 LC，成品完整解码通过后才登记。接入连续集数检查、多剧串行队列、分集处理检查点与中断恢复、可选校验后清理原分集；清理锁定媒体操作并原子核对下载版本，失败保留成品。待合成媒体、混合 AAC、取消恢复、空间不足和原文件保护验证
P2-8	[ ] 已实现，待验证：黄豆 VIP 资料补齐	0.2.9 贯通未知 / 免费 / VIP 三态，未知不覆盖已知；旧缓存无法区分的 false 恢复为未知，避免当作已确认免费。站源管理显示待识别数量并支持每批最多 8 部补齐，未知返回有重试间隔；隐藏 VIP 只排除已确认 VIP。0.2.12 开关使用 VIP / 划线 VIP 图标，封面 VIP 移至左上角避开菜单
P2-9	[ ] 已实现，待验证：Emby 导出完善	0.2.12 按剧集 ID 持久保存稳定目录，兼容旧导出；合并成品导出到 Season 00，稳定编号及 NFO 记录实际范围，复制后完整解码，保留源成品。删除最后一个导出条目不递归删除剧目目录；待验证改名后补集、重复导出、编号恢复和 Emby 扫描
P2-10	[ ] 已实现，待验证：播放偏好与全屏交互	0.2.9 保存画质、倍速和自动连播，按用户隔离并纳入备份；补全全屏选集 / 倍速 / 画质 / 设置及 Go 版长按和键盘规则，临时倍速在松手、切集、菜单、后台和失焦时复原。0.2.12 统一每组 50 集、范围切换 / 精确跳转 / 当前定位，紧凑布局整合切集和播放控制；待集中覆盖重开、重启、备份、布局及输入边界
P2-11	[ ] 已实现，待验证：资料失败后继续推进	0.2.9 保存失败重试时间和扫描位置；单剧 404 冷却 24 小时、其他失败 5 分钟，保留整站退避。每批最多 8 部，连续失败停止当前批后，后续批次从后面的条目推进；待集中覆盖前两部失败而第三部有效的情况
P3-1	[ ] 已实现，待验证：应用网络与资源设置	0.2.12 增加管理员设置面板、本机原子保存、直连 / 自动 / 手动代理、目录并发 1–6 与间隔 0–5000 毫秒。系统静态代理支持 Windows / Android / iOS 桥接及定时刷新，PAC 需手动配置；远程播放通过本机流服务应用代理，保持 TLS 校验与本地绕过。待验证各平台代理、下载 / 播放在途切换及原生平台构建
P3-2	[ ] 已实现，待验证：局域网追剧与续播同步	0.2.13 接入 DNS-SD / mDNS、固定证书的 HTTPS 直连、单设备自动连接及多设备选择，接收端无需确认。按用户同步追剧 / 状态 / 对应进度，默认自动增量合并，手动提供双向合并 / 覆盖对方 / 覆盖本机及预览；版本向量、删除标记、冲突选择、原子保存、回执及断线补齐已接入。Android / Windows / TV / iOS 的发现、权限、取消、备份和真实双端同步均待验证
P3-3	[ ] 已实现，待验证：局域网推送播放	0.2.13 在常规、全屏及 TV 播放控件接入推送，复用设备连接；对方优先使用自己的完整下载，否则独立读取详情 / 解析，准备完成后接收最新位置，实际定位并播放后发起端暂停。取消 / 超时 / 失败保留本机播放，处理重复请求、迟到回执、用户切换和接收端后续操作；不传媒体地址、密钥或文件。真实双端接续与各平台布局未验证
P3-4	[ ] 已调研，待实施：视频画质增强与超分	2026-09-22 完成论文、文档、issues 与成熟源码调研。方案见本 README“视频画质增强与超分方案”：Android / Windows 共用尺寸适配与轻量 GPU 增强，Windows 增加硬件超分，手机 CNN 分阶段评估；包含拟定入口、实际生效判定、热降级和集中验收矩阵。当前没有超分实现、按钮或本 App 效果 / 性能测试结论

旧项目的 Docker / HTTP 服务、浏览器注册与远程账号、跨设备服务端记录、在线 STRM 签名网关和远程 Emby 定时同步依赖常驻服务器，不直接照搬为本 App 的缺失功能。当前对应能力是设备内用户与备份、原生播放器、本地媒体和 Emby 文件导出；0.2.13 另接入不依赖服务器的局域网设备直连、追剧同步与播放接续。普通评论在旧项目中也未接入，不列为遗漏的已完成功能。

对照证据与验收边界

以下是修改前的历史问题证据，0.2.9 没有重新执行这些检查。对应修复是否通过，以将来集中验证结果为准。

2026-09-21 对真实 App Go 核心做了 9 项定向行为对照，通过临时 overlay 注入检查、内存文字响应隔离网络，均复现预期行为尚未实现；这是用于定位差距的 9 项预期失败检查，不代表全量回归有 9 项失败。未将这些失败检查加入正式测试集；实施修复时应将对应夹具整理为能通过的回归。

对应待办	文字夹具或函数检查结果
P1-R1	推进到 offset=18 后重建客户端，实际请求序列为 [0, 0]，预期为 [0, 18]
P1-R2	第 201 页返回第 6001 条，重启后页码仍为 201，但新 ID 不在缓存中；500 页上限另外由代码确认
P1-R3	总目录资料更新后分类仍旧，写盘后 Categories 消失；两项现象由同一检查覆盖
P1-R4	详情返回新标题，再读目录仍是旧标题；跨页面海报重试缺口另由代码确认
P1-R5	合法明文配合固定文字密钥向量进入 AES 分支，最终 JSON 解析失败
P1-R6	实际 API 备用入口与构造的海报 Referer 主机不同；没有发送图片请求
P1-7 / P2-8	两项独立检查：五类资料字段在原生接口丢失；未知 VIP 覆盖已知 true
P1-8	官网返回第一季、名称索引提供第二季，正式搜索只返回第一季

续核另用 3 项 Go 文字 / 文件夹具与 3 项 Flutter 内存偏好夹具，复现以下 5 类边界问题。连同首轮共 15 项定向行为对照，均只用于确认待修复行为；没有运行全量回归，没有使用真实用户数据或真实媒体。

对应待办	续核操作与结果
P1-R7	放入无法解析的下载索引再迁移：调用返回成功，索引变为 []，原目录删除，loadErr 清空
P1-R8	用临时同名目录阻止 catalogs.json 写入：返回 Fresh=true、无警告；内存有 1 条，重启后为 0 条
P1-R9	密码管理员旁加入一个无效访客条目再初始化：管理员 protected=false、未锁定、可下载，原收藏仍可见
P1-R10：写入失败	模拟偏好平台保存收藏返回 false：操作正常结束，内存有 1 条，重新读取持久数据后为 0 条
P1-R10：恢复中断	恢复备份时在写收藏处抛错：历史已是新备份，收藏仍是旧数据，重启后混合状态保留
P2-11	前两部详情固定返回 404，第 3 部有效；连续补齐 3 轮，请求次数分别为 3、3、0

近期 Go 修复同步情况：9 月 18 日红果搜索补漏季已在 0.2.9 接入，待验证；9 月 20 日黄果 Salted__ / 非整分组 AES 和旧 XOR 兼容在 App 已有实现，不能列为整项缺失；详情 / 播放触发失败海报重试已在 0.2.9 贯通，待验证；9 月 21 日黄豆明文 JSON 优先识别已在 0.2.9 同步，待验证；备用入口海报来源头已在 0.2.7 同步。App 通过 FFI 返回设备文件，没有旧 Go 的 /api/ui/image 地址登记网关，应按 P1-R4 处理资料回写，不能照搬服务端 403 路由修复。

0.2.7 已迁移 Go 版 HEIC 容器解析与方向处理，通过随包 FFmpeg 转成 JPEG 后再交给 Flutter；AVIF 仍使用平台图片解码。使用合成容器与本地合成 JPEG 检查边界、串行转换、去重、缓存和失败清理；未请求站源图片，也未验证各平台真实设备的图片解码效果。本轮不启动设备、模拟器或远程 Actions。

后续每次移植在本 README 更新对应编号、Go 修复日期、App 状态及实际验证范围；分别覆盖默认 / 全站源构建。保留设备本地文件、FFI 和原生播放器的实现方式，不整目录覆盖旧项目，也不改动两份旧 Go 项目。

历史已完成的功能

本表保留 0.2.8 及此前状态；0.2.9 及之后新增内容以上方“已实现，待验证”的项目为准。

功能	当前实现
站源管理与完整黄果入口	0.2.4 加入逐站任务、健康检测、CF 诊断和黄果旧 API；修复黄果视频取流请求与密钥凭证；0.2.8 检测详情可独立展开 / 收起，后台刷新保留手动选择
站源分组与内容分类	0.2.7 首页黄果统一展示，合并接口分类与已缓存细分类，各接口独立续页；补齐分类字段和资料回写；AI 实际播放仍待恢复
榜单与封面兼容	0.2.7 接入三站 12 个真实榜单；HEIC 本地转 JPEG，封面地址补齐及新图床 DNS 回退
版本编译开关	0.2.3 加入默认红果鉴 / --all-sources 真果鉴，贯通原生核心、Flutter、平台名称、分发文件与 Actions
在线播放闭环	独立站源浏览、搜索、详情、选集、播放、错误重试；0.2.16 全站源版首页显示红果 / 黄豆 / 黄剧 / 黄果四个站源组，底层保留六个接口供独立管理
播放与记录	画质、倍速、切集、横竖屏、自动连播、自动切线、收藏和本地续播
界面与主题	默认跟随系统，浅色 / 深色选择；旋转刷新按钮、统一海报尺寸、黄豆专属 VIP 筛选、下载页布局调整
离线与媒体	下载与续传、Android 后台服务、离线播放、目录迁移、合并、本地成品及分集 Emby 导出
本地用户	站源 / 下载权限、独立记录、密码校验与备份恢复
平台工程	Android 三架构、Windows / iOS 构建脚本、TV 布局与遥控、国内依赖镜像、源码版本快照

当前检查与平台状态

0.2.16+22 接入黄剧站源，包含访客授权、动态分类、热门 / 最新、目录与搜索分页、详情和签名 Cookie 媒体链路；榜单图标移到顶部标题栏“排序与筛选”后面，分类行不再显示榜单。新增站源纳入既有权限、下载、资料和局域网互联范围；旧版设备通过共同站源协商保留兼容。

本轮完成变更 Dart / Go 源码格式整理与源码镜像同步，未运行静态分析、构建、自动化测试、回归、设备 / 模拟器、真实站源或双端验证，也未请求站源图片。现有两份 Android APK 仍为 0.2.15+21。26 项已实现待验证的状态保持未勾选，实际运行结论等待集中验证。

以下保留历史版本的实施与检查记录。

0.2.15+21 根据首页截图调整多选与导航入口：移除首页全选，展开后显示文字“清空 / 取消”，底部固定已选数量及“下一步”；仅红果分类在“全部”后提供内嵌推荐，当时将“榜单”放在分类栏右侧，位置已在 0.2.16 调整。

变更 Dart / Go 源码完成格式整理，两版 Android ARM64 Release 构建与包检查通过。版本码为 2021，签名与 0.2.10 / 0.2.14 一致；每份 17 个 ARM64 原生库采用 ZIP DEFLATE，安装时解压、CRC、ZIP 对齐、应用名称 / 包名、对应原生核心及两份 APK 的 SHA256 均已核对。构建与包检查记录保存在 build/packages-0215/。

0.2.15 未执行静态分析、自动化测试、回归、设备 / 模拟器或真实局域网验证，也未请求站源图片；该版布局、切换推荐与多选操作的实际运行效果待用户安装确认。

0.2.14+20 根据用户提供的“正在打开红果鉴”截图修复启动导航。0.2.13 为接收播放加入固定导航 key 后，初始化前后改变了 MaterialApp 的父节点层级，保留下来的根路由继续引用旧应用状态。现在初始化前后都使用同一层 AnimatedBuilder，保持应用与导航状态连续，使首页能够接替初始化页，并保留推送接收导航。定位依据为截图与源码，尚未在设备上确认启动效果。

打包同时补齐 lan_screen.dart 对 LocalStoreSync 扩展的导入，解决 Release 编译失败。0.2.14 执行结果：

检查	结果与范围
源码格式	变更 Dart / Go 文件完成格式整理
Android Release 构建	默认红果版、--all-sources 全站源版均通过，ARM64，版本 0.2.14+20
安装与升级信息	应用名称、包名、版本码 2020、最低 Android 8.0 和非调试标记正确；签名有效，且与 0.2.10 / 0.2.13 一致
包完整性	每份 17 个原生库均为 ARM64 ELF、ZIP DEFLATE；包 CRC、ZIP 对齐和安装时解压配置通过
编译配置与校验值	两版各自的原生核心与构建记录一致，Dart 与原生二进制分别区分两版；两份 APK 与 SHA256SUMS.txt 一致

构建和包检查记录在 build/packages-0214/，包括两版 release-*-arm64.log、apk-*-verification.log 和 apk-verification.json。0.2.14 没有运行静态分析、自动化测试、回归、设备 / 模拟器或真实局域网验证，没有请求站源图片；包检查不代表启动、同步、推送或其他运行行为已经验收。

0.2.13+19 接入 P3-2 / P3-3：局域网自动连接、追剧与对应续播进度的增量同步 / 手动覆盖、冲突处理和播放推送。功能实施阶段暂停验证，当时只执行：

• flutter pub get：取得 nsd 5.0.1 及平台依赖，更新 pubspec.lock。
• Dart / Go 源码格式整理。
• 收尾同步、创建本地 v0.2.13-unverified 快照及源码镜像一致性确认。

该功能实施阶段没有运行 Dart 静态分析、Go 编译、自动化测试、回归、完整平台构建、真实局域网通信或设备 / 模拟器操作，也没有请求站源图片。后续按用户要求打包，并在收到启动问题反馈后交付上述 0.2.14 修复包。Android / Windows / TV / iOS 的设备发现、权限、并发同步、取消与回执恢复、推送定位和控件布局仍待集中验证。

以下历史版本的检查结果不能作为后续新增功能的验证结论。

0.2.12+18 完成界面调整及 P2-4 / P2-5 / P2-6 / P2-7 / P2-9 / P3-1 的源码接入，当时的检查结果：

检查	结果与范围
源码格式	Dart lib 与变更 Go 文件完成格式整理
Dart 静态分析	dart analyze --fatal-infos lib 通过，无问题
本机 Go 核心编译	在 native 执行 go build ./core 通过
Android ARM64 核心编译	GOOS=android GOARCH=arm64 CGO_ENABLED=0 go build ./core 通过
Windows x64 核心编译	GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build ./core 通过

0.2.12 没有执行自动化测试、回归、真实媒体播放或设备 / 模拟器验证，也没有构建新 APK、Windows 完整包或 iOS 应用。上述 Go 检查只覆盖核心源码编译，不代表平台桥接、随包媒体库、界面或合并输出已验收。当时黄果 AI 仅做入口与目录的只读连接诊断，结果超时；未请求站源图片。

以下 0.2.11 及更早版本的检查和安装包记录，也不作为后续新增功能的验证结论。

0.2.11+17 完成 P2-3 红果弹幕的源码接入，Go / Dart 格式与 Dart 静态检查通过。默认红果版和全站源版各通过 6 项 Go 定向测试（含竞态检测）及 18 项 Flutter 定向测试。原生检查使用内存文字响应，覆盖原始时间戳、分集身份、异常时间窗口、缓存去重、取消和播放会话隔离；Flutter 使用合成数据，覆盖分页与有界缓存、失败重试、迟到结果、暂停 / 缓冲 / 倍速 / 跳转、连续动画、开关持久化与备份兼容、用户切换、窄屏大字及 TV 设置。

0.2.11 只运行以下弹幕测试，Go 命令在 native 目录执行，Flutter 命令在项目根目录执行：

go test -race ./core -run '^(TestHongguoDanmaku|TestNativeDanmaku)' -count=1 -timeout=60s
go test -race ./core -ldflags='-X duanjuapp/native/core.buildAllSources=true' -run '^(TestHongguoDanmaku|TestNativeDanmaku)' -count=1 -timeout=60s
flutter test --no-pub --dart-define=DISABLE_REMOTE_IMAGES=true test/danmaku_test.dart test/danmaku_widget_test.dart
flutter test --no-pub --dart-define=DISABLE_REMOTE_IMAGES=true --dart-define=ALL_SOURCES=true test/danmaku_test.dart test/danmaku_widget_test.dart

Flutter 记录在 build/danmaku-0211/flutter-default.log 与 flutter-all-sources.log。0.2.11 未进行回归、真实站源弹幕请求、设备或模拟器验证，也未请求站源图片；Android、Windows 与 TV 的实际播放效果待平台验收。0.2.11 当时未单独打包，弹幕实现已包含在新版 APK 中。

0.2.10+16 完成 P2-1 与 P2-2 的源码接入，Dart 格式与静态检查通过。默认红果版和全站源版各通过 26 项新增功能针对性测试，使用合成文字与分集数据，禁用远程图片；覆盖追剧记录与实际播放进度分离、已读基准、备份兼容与失败保留、用户隔离、共享更新任务与缓存续页、批量下载重试 / 停止，以及 360×640 和 1100×720 的大字布局。

0.2.10 功能实施阶段执行了以下三份测试文件：

flutter test --no-pub --dart-define=DISABLE_REMOTE_IMAGES=true test/follow_state_test.dart test/library_workflow_test.dart test/library_features_widget_test.dart
flutter test --no-pub --dart-define=DISABLE_REMOTE_IMAGES=true --dart-define=ALL_SOURCES=true test/follow_state_test.dart test/library_workflow_test.dart test/library_features_widget_test.dart

0.2.10 打包时移除了 app_cover_metadata.go 中遗留的 parseHuangguoSortDetail 重复定义，统一复用详情元数据解析实现；Go 格式整理和 TestNativeCoverMetadataRejectsOtherDramaAndKeepsCurrentHost 定向测试通过，测试只解析合成元数据，不请求图片。

0.2.10 的红果鉴 / 真果鉴两份 ARM64 Release 构建和安装包检查已通过。每份 APK 的 17 个原生库均为 ARM64 ELF 并使用 ZIP DEFLATE 压缩，清单启用安装时解压；签名与 0.2.8 一致，包 CRC、ZIP 对齐、应用名称、包名、版本 0.2.10、ARM64 分包版本码 2016 和对应原生核心均正确。两份包及 SHA256SUMS.txt 已校验，构建与检查记录在 build/packages-0210/，对应 release-default-arm64.log、release-all-sources-arm64.log、apk-default-verification.log 和 apk-all-sources-verification.log。

0.2.10 打包没有执行全量 Flutter / Go 回归、设备或模拟器测试，也没有请求站源图片。构建成功不代表新增功能已经完成平台验收。

0.2.9 接入的播放器交互、分页 / 保存 / 本地用户恢复、红果推荐、资料模型、排序、全部站源和完整搜索等，仍按各待办行保留原有验收状态。0.2.10 / 0.2.11 的针对性测试不代表这些功能已完成集中验证；Android、Windows 原生行为与新增 TV 操作仍待平台验收。

黄果 AI 的实际密钥连接与播放仍未恢复。0.2.13 已接入原清单中可独立实施的功能以及新增 P3-2 / P3-3；AI 待可通的入口后继续处理连接与播放问题，集中验证继续按用户安排执行。

0.2.8 已通过 Dart 格式与静态检查，默认红果版和全站源版各通过 5 项站源界面定向检查。使用合成数据覆盖历史详情默认收起、两种主动检测展开、手动收起后跨请求返回 / 轮询 / 检测完成保持状态、完成后再次展开与收起，以及窄屏大字的失败诊断。记录在 build/sources-028/。

0.2.7 已通过 Dart 格式与静态检查、相关 Go 定向检查（含竞态检测），另验证默认红果版的权限、分类和合成 HEIC。Flutter 定向检查默认版通过 14 项、全站源版通过 15 项；覆盖紧凑布局、大字体、展开搜索、黄果聚合 / 分类去重、独立分页与失败页重试、过期响应隔离、真实榜单名次、VIP 筛选及海报尺寸。合成 HEIC 还经过真实原生准备接口与开发机 FFmpeg 转成 JPEG，验证旋转后尺寸由 64×96 变为 96×64；此项不等同于 Android 原生插件实机验收。检查记录在 build/sources-027/。

0.2.7 / 0.2.8 按当时要求没有运行整套回归、启动设备或模拟器，也未请求任何站源图片；各平台实际显示与播放效果仍需安装验证。0.2.6 的待办审查与边界问题证据保留在上文，以下保留历史版本验证结论。

0.2.6 已完成红果鉴 / 真果鉴两份 ARM64 Release 构建。每份 APK 的 17 个原生库均采用 ZIP DEFLATE 压缩，最终清单已启用安装时解压；包 CRC、ZIP 对齐、应用名称、版本、签名和内置核心对比均通过。两份签名与 0.2.5 一致。全站源包由 67.4 MB 缩小到 30.1 MB，减少约 55.3%；第三方原生库解压后的内容与 0.2.5 一致。记录在 build/sources-026/。

0.2.5 已通过 Dart 格式与静态检查、5 项定向 Go 检查（含竞态检测）和 1 项分类界面检查，覆盖分类分页 / 缓存隔离、旧 API 单剧 404、封面地址与合成解码、密钥 EOF 后备用 DNS 连接，以及分组切换和过期分类响应隔离。按用户要求不运行整套回归，记录在 build/sources-025/。

0.2.5 线上文本检查取得黄果视频和旧版的实际分类；旧版独立更新成功，返回 100 部剧，全部封面 URL 已避免误用视频 CDN。仅核对地址元数据，封面解码只用合成图片，未请求站源图片。记录在 build/sources-025/live-fixes.log。

黄果 AI 截图同剧《神瞳觉醒 第一季》的目录、21 集分集与 M3U8 均正常，但密钥请求仍在 TLS 握手时断开；换用备用公网地址及浏览器兼容连接后仍失败，没有证明媒体可播放。诊断记录在 build/sources-025/key-probe.log、asset-probe.log 和 alias-probe.log。此前 0.2.4 黄果视频“母女日常”的目录、分集、播放列表、密钥和媒体连接抽样通过，记录在 build/sources-024/live-huangguo.log；该结果不能代表黄果 AI 或 Android 实机播放。

0.2.8 已生成两份 ARM64 Release 安装包，可覆盖升级。每份的 17 个原生库均使用 ZIP DEFLATE，清单启用安装时解压；签名与 0.2.7 一致，包 CRC、ZIP 对齐、应用名称、版本和内置核心对比均通过，记录在 build/sources-028/apk-verification.log 与 apk-default-verification.log：

版本	安装包	大小
红果鉴，仅红果	dist/android/hongguojian-0.2.8+14-arm64-v8a.apk	30.2 MB
真果鉴，全部站源	dist/android/zhenguojian-0.2.8+14-arm64-v8a.apk	30.2 MB

构建日志为 build/sources-028/release-default-arm64.log 和 release-arm64.log，包校验记录为同目录的 apk-default-verification.log 和 apk-verification.log。其他架构的构建开关和脚本保留，0.2.8 未生成其他架构安装包。

按用户要求，由用户自行安装体验，不执行手机 / 电视实机测试或启动模拟器。Windows 完整包需 Windows / Actions；本机缺少 iPhoneOS SDK，iOS 尚未完成 Xcode 构建，也没有已签名 IPA。本轮不运行远程 Actions，不请求或处理站源图片。

此前的合成 CENC 换封装、少数分集合并转码和 Emby 成品独立解码检查已通过。平台状态单独记录，不将待验收项目混入上面的功能移植顺序。