# 跨端兼容与本轮修复边界

更新：2026-11-07，0.5.0 发布候选验证。本页描述实现和本地验证，不代替真机兼容清单。

## 来源格式

| 输入 | Flutter：Windows / macOS / iOS / iPadOS | 原生 Android 标准版 | Lite |
| --- | --- | --- | --- |
| JSON CMS、XML CMS | 兼容接口可浏览、搜索和解析播放地址；媒体仍受服务与解码器限制 | 已有相应接口实现 | 主要支持 type 1 JSON CMS |
| 多仓目录 | 递归识别 storeHouse / urls / depots，保留主订阅和子仓归属，单个子仓失败不覆盖现有配置 | 同一目录解析协议，支持切换子仓 | 同左，内容仍受 Lite 引擎能力限制 |
| TXT / M3U | 按内容识别兼容直播/点播列表，不以扩展名承诺任意文本可用 | 已有列表解析实现 | 不等同于标准版完整直播功能 |
| PHP 或无扩展名订阅 | 按 HTTP 响应内容解析；必须能够建立连接并取得配置 | 同样依赖实际响应 | 同样依赖实际响应和旧系统网络能力 |
| 独立 JS / PY | 本机 QuickJS 支持 ES module / Cat Spider 协议及异步 req；Python Spider 使用 Skulpt 1.2.0、base.spider、基础 requests / JSON 适配 | 既有 JS 宿主补 Python Spider、包内辅助模块读取 | 保留脚本输入但需要标准版执行环境 |
| Android JAR / csp 插件 | 只有明确适配器或配置提供的兼容 HTTP 后端可用；不是 Android 虚拟机 | 依赖插件、ABI、系统版本及宿主兼容 | 不提供完整插件运行环境 |
| 本地 ZIP | 明确 JSON 入口、包内 JS/PY 静态模块和播放列表；单播放列表 ZIP；其他本地资源按缺失处理 | 分包存储、验证后启用、保留包内相对地址及旧包，支持已实现宿主的资源 | 未适配通用本地包 |
| Emby | 登录、媒体库、搜索、连续分页剧集、PlaybackInfo 直连／HLS 转码协商、播放进度上报 | 同左 | 同一 REST 协议，使用保守的播放能力配置，解码与 HTTPS 受旧系统限制 |
| .js.md5 | Basic 认证、同源下载、MD5 验证后识别独立 Spider 或 CatPaw Node 服务包；CatPaw 在设备本机运行 | 同左 | 可检查摘要与类型，执行需要标准版 |

文件可导入、能浏览目录、能解析播放地址和媒体实际起播是四个不同阶段。豆瓣类目录不保证有剧集。Flutter 详情页只在用户已导入、同隐私范围的可用来源中匹配相同标题/年份；没有匹配时显示无资源，不自动添加外部来源。

Python 使用解释器及已实现的模块接口，含 requests、基础 JSON 和包内 Python 模块。lxml、原生扩展、DRPY 同步宿主及完整 CPython 标准库仍需逐项适配。CatPaw 新增共享 Node 宿主：桌面子进程、iOS 无 JIT 框架、Android 嵌入库；导入、目录、搜索、详情、解析与媒体代理已接入，另有本机配置页入口。移动框架已通过本轮 iOS/Android 构建，设备启动与完整播放仍待验证。原订阅的 YGP 预告片线路已新增本机适配，其他 Guard 插件仍按实际能力处理。

Emby 的设备登录凭据与订阅配置分开保存，常规备份仅含账户引用。恢复到其他设备需重新登录。播放前通过 PlaybackInfo 提交设备能力，使用服务器返回的媒体版本和会话；可直连时使用静态流，否则使用同一服务器范围内的 HLS 转码地址。凭据通过请求头发送，移除转码地址中的令牌参数。鉴权海报由本机账户读取，账户标识使用跨端一致的摘要，海报 URL 与备份均不带令牌。

Flutter、Android 标准版和 Lite 的播放器接入开始、暂停／继续、周期进度及结束上报；切集、返回、失败和过期解析释放旧会话。进度更新合并，服务器响应慢或上报失败不阻断本机播放。Lite 使用稳定剧集标识恢复本机进度，不再把每次生成的播放会话编号作为续播身份。协议回归覆盖直连／转码选择、无权限、媒体版本不匹配、跨站转码拒绝、204 空响应及结束状态不被旧进度覆盖。尚未使用真实 Emby 服务器验证转码媒体的解码、跳转、字幕与多音轨；需要打开实时流的资源尚不支持，不能将协议测试当成这些能力的验收。

## 界面与数据

- 设置一级保留分类标题，说明和当前选择进入二级显示。Flutter 竖屏 Dock 接入 Scaffold 底部区域，提示避让；Android 提示按实际 Dock 和可见窗口避让，横竖屏焦点标签分别定位。
- Flutter 线路管理支持拖动排序、单条删除并保存；原生 Android / Lite 用上移、下移、置顶及删除适配遥控器和触屏。分组计数不再使用独立圆形底色。
- Flutter 删除订阅以持久化订阅列表为准（包括空列表），旧单配置不会在重启或下一次导入时重新出现；清理早期首次粘贴导入的重复记录。多仓目录保存到各自订阅，删除其他订阅不丢目录；删除线路用原始源标识，避免同名源消失后别名变化导致线路复活。保存失败会提示并允许重试，失效的异步目录／直播／搜索响应不会重新填回页面。
- Flutter 备份包含多个公开订阅、开关、线路调整、播放与外观设置；普通备份排除私密来源。恢复前校验格式，保留本机私密订阅。不同平台只能保证各自已实现字段，不能将手动备份称为自动同步。
- 移动 Dock 拖动在松手后确认切页；Android 首页保存滚动位置。TV 保留已加载影片元数据，海报按最多 120 张的窗口显示，提供前后窗口入口。
- Lite 补充分类/搜索返回上下文和最近一次播放续播，不等同于完整片库及多条历史。
- 修复海报、高清升级及分集元数据任务在清理映射时等待自身的完成阻塞，普通及 Emby 海报回归通过。
- 删除无真实数据依据的 TMDB/豆瓣评分装饰。私密影片暂不开放离线下载，避免进入公共下载列表；这不等于本地文件加密。

- 换源弹窗线路名称改为自适应高度并完整换行，窄屏和放大字体下保留偏好入口；Flutter 首页窄屏入口分行，横屏弹窗的筛选与列表可一起滚动。
- 支持默认偏好源和默认播放线路。临时切换不覆盖偏好，观看记录优先续播，偏好无效时回退到可用选择。Flutter 普通备份带公开偏好源；原生端偏好目前保存在本机。
- Windows 图标改为包含 16–256px 的九档透明 ICO，Android 使用五档透明启动图标，清除原来的不透明矩形底。
- TV 分类区域增加类型、国家 / 地区、年份筛选。优先使用来源提供的筛选键和值，CSP / JS / HTTP 请求及后续分页携带选项；没有对应接口时按已读取影片资料筛选并明示范围，空结果仍能继续翻页。
- TV 详情返回复用原首页视图，保留条件、已加载页、海报窗口、滚动和焦点。尺寸、字体、外观或配置发生变化时重建布局，原浏览状态仍保留；配置变化会重新获取相应来源。导航中的浏览快照不因五分钟缓存到期而自动刷新。

## Glasswork

参考 [Glasswork](https://github.com/kubai087/glasswork) 提交 `4f0b674` 的材质、边缘折射、色散、背景适应和可读性设计。仓库没有 `SKILL.md`，采用其安装说明和实现文件作为适配依据，保留 MIT 许可。

Flutter 在支持 shader 图像滤镜的渲染器上使用折射效果；其他环境使用模糊和高光边缘回退，减少透明度使用实色。原生 Android 的 Dock、海报顶部控件、弹窗和提示接入有上限的背景采样／边缘折射，原生视频 SurfaceView 通过 PixelCopy 读取小尺寸画面，TextureView 使用对应采样；不可读画面与 Lite API14 使用暗色材质回退；TV／手机外观二级设置提供减少透明效果。详情见 [Glasswork 接入记录](GLASSWORK_ADAPTATION.md)。不得将各端样式更新描述为像素一致或已完成设备性能验收。

## 更新和系统兼容

- 原生 Android 按 TV/mobile edition 选择更新包，安装前再检查 edition，避免手机版变成电视界面。
- Windows 更新需要可信下载地址、大小和 SHA-256；失败会尝试备用清单，不假称已是最新版。安装器由用户正常操作，客户端不提前退出。
- Flutter 固定 3.38.9，并锁定依赖；iOS 打包验证 Mach-O 和 Framework 的真实最低系统要求，禁止修改最低版本字段伪装兼容。
- iOS 14.5 巨魔安装后闪退按用户要求暂缓，等待新版用户实测反馈，不再作为本次发布阻塞项。打包保护检查通过不代表这条闪退已修复；当前没有对应实机启动证据。
- Android 标准版跳片头/片尾控件目前最大 180 秒；其他客户端取值范围不同，不宣称全端统一 300 秒。

## 本轮验证

- 15 组 Java 离线逻辑套件、15 项镜像元数据检查及 7 项平台配置/图标测试通过（其中 6 项为 iOS 包保护）。新增 Glasswork 像素对比、尺寸限制和减少透明效果的设置校验。
- Flutter 75 项自动测试通过（72 项公开测试和 3 项私有样本检查），涵盖解析、搜索取消、目录匹配、订阅管理、备份、更新、Emby 登录与播放协商／会话上报、JS/Python 宿主、本地包、摘要认证及 Dock 提示避让。新增多仓切换归属/备份、偏好持久化、长名称与横竖屏大字体弹窗，以及 12 项删除数据回归和 1 项实际页面流程测试（删除后数量更新、拒绝旧请求回填）。私有检查包含原订阅解析、待适配线路清点和真实 CatPaw 导入／目录，样本不随源码发布。
- Windows 调试构建、Android TV/mobile 开发签名构建及 Lite API14 构建通过。Windows 实际界面使用隔离测试配置验证设置菜单、分组计数、排序及单条删除。
- 实际网络检查取得急救、兔小贝、一个 B 站来源和 YGP 预告片的 MP4 数据。YGP 的部分预告返回无资源或网络超时，按单条结果处理。
- 用户提供的多仓地址在 Flutter 和原生解析器实测取得 12 个目录条目及首个子仓的 48 条来源；这不代表 48 条均可播放。
- TV 筛选增加 11 项离线协议回归；HomeProbe 增加三维筛选、同一视图恢复、返回零目录请求的设备用例，已编译，尚未在设备执行。
- 固定 Flutter 引擎的原始 iOS arm64 二进制部署目标实测为 iOS 13.0。
- 本轮 Android TV/mobile/Lite、Windows 和 macOS 构建通过（Actions 42344960487）；iOS/iPadOS 在修复插件链接后构建通过（Actions 42345680892）。macOS 成品检查确认应用与 Node 均含 Intel/Apple Silicon 架构、宿主和 fetch 资源及本机网络权限。仍未完成真实来源全链路播放、iOS 14.5 启动或 TV/手机/旧 Android 实机交互验收。现有分析器仍有未使用代码与弃用 API 提示，不声称静态检查零警告。

## CatPaw 本机运行补齐（发行前验证中）

- 用户导入的服务包保存在应用目录，MD5 校验传输内容，SHA-256 对应不可变本机文件；不随公开源码或安装包附带第三方服务包。保存的线路是稳定逻辑地址，不保存临时端口和访问会话。包更新保留作者的线路标识，避免同一线路的排序和偏好失效。
- 每个服务包使用独立 Node worker；播放代理只监听回环地址。配置页由用户主动打开，使用单独回环端口、一次性入口和 HttpOnly 会话，播放接口不暴露配置路径。源包仍是可执行代码，worker 与回环访问限制不是完整安全沙箱。
- 本机配置入口用于来源自己的网盘登录、启用线路和参数，来源自己的登录与 Marco 现有账号中心分别保存。当前不自动迁移第三方账号数据，也不把没有登录的网盘当成可播放。
- Node 22 常规／无 JIT 与 Node 18 无 JIT 模式各 9 项宿主回归通过；修复 Node 22 无 JIT 下惰性网络组件初始化触发 WebAssembly 的启动失败。真实用户包读取 56 条线路、玩偶 8 个分类与 70 条目录项；玩偶抽查详情返回零剧集，星芽抽查取得 HTTP 206 的 video/mp4 数据，均不作为完整播放器解码验收。合成来源回归覆盖导入、搜索、详情、解析、媒体字节、服务重启和配置会话。
- CatPaw 播放结果支持多画质列表、逐画质请求头和分离音轨。Flutter 切换画质保留进度，原生 Media3 合并外部音轨；真实分离音视频的解码和跳转仍待设备验证。
- iOS 桥接库显式链接 NodeMobile，平台准备脚本保留 Flutter 和插件原有链接参数；不通过修改二进制最低版本来冒充旧系统兼容。Lite 正式构建支持指定既有签名并核对证书，错误证书测试确认阻断输出。
- 当前 Android CatPaw 上游二进制使用 4 KB 页对齐；16 KB 页设备给出明确不支持提示，避免直接加载造成崩溃，尚未完成该运行组件的 16 KB 适配。Lite 不编译或打包此运行组件。
- 镜像同步完整校验 TV APK；超过镜像单文件限制时使用官方发行下载地址，移动端顶部入口与更新清单一致。正式发行同时更新正式与预览清单，测试包不覆盖正式清单。
- Android 新增视频帧采样，所有玻璃控件共享最多每 100ms 一次、最长边 320px 的画面；控件隐藏/播放结束后不持续采样。设备性能、HDR 画面采样色调及移动端配置页尚待验证。
- 原订阅仍有 33 条 Guard 插件缺少对应跨平台实现；CatPaw 的加入不等于这些二进制插件已经移植。这些未适配项不属于 0.5.0 的已支持能力。