红果鉴 / 真果鉴

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

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

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

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

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

使用

站源可用性、清晰度和区域限制取决于源站及网络；应用不解除源站 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，电视桌面有启动入口；自动识别，也可在“更多 → 界面模式”中手选。聚焦按钮和海报显示亮色边框。

支持专用播放 / 暂停、上一集、下一集按键。播放中无操作 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，不增加远程处理服务、不转码在线播放内容、不改写下载文件。

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

已核实的播放器接入条件

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

算法与成熟实现的取舍

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

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

建议的设备端架构

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 转码再回送播放器。

建议模块与修改位置：

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 版本、显卡品牌或旗舰机名称判断。

按 帧预算 = 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 入口和对比按钮均可被遥控焦点到达。

失败恢复与实际生效判定

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

分批实施与集中验收

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

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

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

调研来源与证据索引

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

安装包与平台状态

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 直接下载。构建通过只代表编译和打包完成，尚未进行设备安装、运行和真实站源验收。

两份安装包的 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，会先检查再构建：

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 配置：

未配置时生成预览 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

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

功能 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 黄剧站源。新增功能均保留未验证状态，功能范围与验收状态分别记录。

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

从首页“更多 → 站源管理”或设置进入独立管理页。每个入口显示缓存数量、分页位置、最近更新时间、任务阶段和错误，可分别更新、继续一页、补齐资料、停止任务和检测；检测结果持久保存。更新合并新增内容并保留目录页码和其他站源缓存，每轮补齐最多 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，不另建重复待办。

功能完善

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

对照证据与验收边界

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

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

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

近期 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.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 执行结果：

构建和包检查记录在 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 的源码接入，当时的检查结果：

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：

构建日志为 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 成品独立解码检查已通过。平台状态单独记录，不将待验收项目混入上面的功能移植顺序。