CrossWatch 播放进度管理指南：没看完的剧，跨平台无缝续看

CrossWatch 是一款开源媒体同步工具，它的播放进度管理功能可以把你在 Plex、Emby、Jellyfin、Trakt 等平台上"看到一半"的电影和剧集汇总到同一个列表，并支持跨平台同步进度。不管你在哪台设备、哪个平台追剧，进度都不会断档。

一、什么是 CrossWatch 播放进度（Playback Progress）

很多工具只能记录"看过了什么"，却记不住"看到第几分钟"。CrossWatch 的播放进度模块专门解决"没看完"这一类内容：

• 汇总各平台的未看完内容：电影和剧集的进度百分比、剩余时长、最后观看时间，统一展示在 Profile 页的进度列表中；
• 实时状态叠加：正在播放、缓冲中的内容会实时标记为 "Playing now" / "Buffering now"，进度条跟着当前播放状态刷新；
• 能力自适应：不同平台对进度的读写能力不同（读取、标记已看、修改进度、删除进度、批量操作），CrossWatch 会按平台能力自动启用或禁用对应按钮，不会发出平台不支持的操作。

相关源码位于 services/playback_progress/，其中 models.py 定义了播放记录、平台能力与操作结果的数据结构，service.py 负责聚合、去重与实时状态叠加，api/playbackProgressAPI.py 则对外暴露 /api/playback_progress 系列接口。

二、没看完的剧，如何跨平台续看

步骤 1：连接你的媒体平台

在 Settings 中分别添加媒体服务器（Plex / Emby / Jellyfin）和追踪平台（Trakt、SIMKL 等）。每个已连接的平台实例都会出现在进度模块的"能力清单"里，告诉你它支持哪些操作（详见 capabilities() 的实现）。

步骤 2：打开"进行中"列表

进入用户 Profile 页，播放进度标签页会列出所有未看完的内容，支持按以下条件过滤：

过滤维度	说明
平台 / 实例	只看某个服务器或追踪平台的进度
媒体类型	只看电影或只看剧集
进度区间	例如 10%–90% 之间，精准找到"卡住"的剧
搜索 / 排序	按标题搜索，按最后更新时间排序

步骤 3：让进度自动同步

在 Sync Hub 中，播放进度与 watchlist、ratings、history 一样是独立的同步项（界面上标记为 progress）。执行同步后，你在 A 平台更新到 60% 的进度，会按配置的方向写入 B 平台：

两个实用细节：

• 路径匹配兜底：当 ID 匹配失败时，可启用 General → Matching → Match by file path，让不同路径下的同一文件也能对上，播放进度同样受该兜底保护，规则见 docs/path-matching.md；
• 安全编辑范围：修改进度时，CrossWatch 默认只允许写入 2%–100% 之间的值（见 models.py 的 editable_progress_min_percent），避免把"没看"误标成"看了一半"。

三、5 个高频操作速查

1. 标记已看完：进度卡在一部不想再追的剧上？一键 mark_watched，把它从"进行中"移入历史；
2. 手动修正进度：服务器偶尔丢失进度上报，可用 update_progress 手动把进度设回正确百分比；
3. 清除进度：看完后想重新追一遍，remove_progress 可删除该条记录；
4. 批量处理：以上操作均支持一次选中多条记录批量执行（/actions/bulk 接口）；
5. 命令行管理：不打开网页也能操作，cli/commands/progress.py 提供了一整套子命令：

cw progress list --min 10 --max 90   # 列出进度在 10%~90% 的内容
cw progress watched <KEY> --yes      # 批量标记为已看
cw progress set <KEY> 60            # 把某条进度设为 60%
cw progress remove <KEY> --yes      # 删除某条播放进度

四、源码导航：想深入看看

模块	路径	作用
进度聚合服务	services/playback_progress/service.py	汇总各平台记录、实时状态叠加、过滤排序
数据模型	services/playback_progress/models.py	播放记录、平台能力、操作结果定义
平台适配器	services/playback_progress/adapters/	Trakt、SIMKL、FlickList、FLOPPY 等平台的读写适配
API 接口	api/playbackProgressAPI.py	进度查询与操作接口
前端页面逻辑	assets/js/profile-page.js	进度列表渲染、实时状态展示
CLI 命令	cli/commands/progress.py	命令行查询与批量操作
路径匹配文档	docs/path-matching.md	ID 匹配失败时的文件路径兜底规则

五、小结

CrossWatch 的播放进度管理，本质上是给"没看完的内容"做了一层跨平台的中转站：汇总 → 实时跟踪 → 手动修正 → 自动同步。从此不必再纠结"上次是 45% 还是 60%"，在哪开始就在哪继续，这就是跨平台无缝续看的完整体验。