SkyStream 是一款跨平台的开源媒体串流客户端，支持 Android、iOS、Windows、macOS 和 Linux。除了播放本身，它还内置了完整的追剧记录多端同步能力：只需在设置中一次连接 Trakt、AniList 或 MyAnimeList（MAL），手机、电脑、电视上的观看进度就能通过第三方追踪服务互相同步。本文是一份面向新手的完整设置指南，带你在 5 分钟内完成全部配置。

为什么需要多端同步？

想象这个场景：你在手机上看到一半，晚上回到电脑前想看剩下的部分——进度应该直接续上，而不是从头找。

SkyStream 的同步逻辑是：

• 播放时：开始、暂停、停止播放都会向已登录的追踪服务上报（Scrobble）
• 观看完毕：自动标记为"已看完"（Mark as Watched）
• 换新设备打开：首页会出现 "Synced from Trakt" 同步进度板块，点一下就能搜索并续看

同步的核心逻辑在 sync_manager.dart 中：开始/暂停事件是"临时"的，丢失也不影响；而停止播放（scrobbleStop）和标记已看（markWatched）会被持久化，即使当时断网，也会在网络恢复后自动重发，确保进度不丢。

第一步：进入账号设置页面

1. 打开 SkyStream，进入Settings（设置）
2. 点击"Accounts, Network & Downloads"入口（副标题写着 Subtitles, tracking, network, DNS & downloads）

对应的设置入口代码在 settings_screen.dart：

第二步：连接四个追踪服务

账号页面（account_settings_screen.dart）中有四个同步服务开关，点击后显示连接状态（Connected / Not logged in）：

1️⃣ Trakt —— 影视记录主力

Trakt 支持设备码（Device PIN）登录，适合没有键盘的电视端：

• 点击 Trakt 条目，弹出验证对话框
• 扫码或点击链接打开验证页面，在 Trakt 官网输入屏幕上显示的验证码
• 授权成功后，条目状态变为 Connected ✅

这个 QR 码 + 验证码弹窗的实现见 tracking_auth_dialog.dart，验证码会自动复制到剪贴板，输入更方便。

💡 Trakt 的访问令牌有效期为 7 天，SkyStream 会提前 1 天自动刷新（见 trakt_service.dart），只要隔段时间打开过 App，就永远不需要重新登录。

2️⃣ AniList / 3️⃣ MyAnimeList —— 动漫记录二选一

这两个服务使用OAuth 授权流程，且直接在SkyStream 内置浏览器中完成登录，无需跳转到系统浏览器：

1. 点击 AniList（或 MyAnimeList）条目
2. 内置浏览器打开授权页面，用账号登录并同意授权
3. App 会在本地拦截授权回调（重定向地址为http://localhost），自动保存令牌，无需任何额外操作

授权流程细节可参考 tracker_sign_in.dart——MAL 采用 OAuth 授权码 + PKCE，AniList 采用 Implicit 授权，token 都只存在本机安全存储里。

4️⃣ Simkl —— 跨平台 ID 桥梁

Simkl 同时收录影视和动漫，SkyStream 主要用它来解析作品在各平台之间的 ID 映射（sync_manager.dart）。即使你只连 Trakt，也可以把 Simkl 一并连上，让 ID 解析更准确、覆盖更全。

第三步：验证同步是否生效

连接成功后，开始播放任意一集剧集：

播放到一半退出（或看完），然后：

• 到 Trakt 官网 / AniList 个人主页查看，应该能看到对应的观看记录
• 回到 SkyStream首页，会出现"Synced from Trakt"板块（home_screen.dart），里面是其他设备上报的观看进度
• 点击某项即可跳转搜索并继续播放；长按卡片还能删除该条进度（synced_progress_card.dart）

多端切换示意——手机上看到一半，回到桌面端接着看：

常见问题 FAQ

Q：同步会重复计数吗？不会。每次播放会话只会发送一个终态事件（要么 markWatched 要么 scrobbleStop），且会按会话去重，避免同一集被记两次（playback_tracker.dart）。

Q：断网时进度会丢吗？不会。终态写入先进入本地"发件箱"（sync_outbox.dart），联网后按退避策略自动重发，进度值随记录一起保存，重放时依然正确。

Q：想断开某个服务怎么办？再次点击已连接的条目，确认"Disconnect"即可，令牌会从本机安全存储中清除。

Q：登录一直转圈/失败？设备码流程有超时，长时间不授权会提示连接失败，重新点击该服务条目即可再次发起；MAL/AniList 若浏览器中登录成功但 App 提示失败，请检查网络或重试一次。

小结

整个服务连接状态的判断逻辑非常直观，见 tracking_auth_provider.dart——四个服务各自独立登录、独立上报，全部并行同步。现在打开你的 SkyStream，跟着上面的步骤操作，几分钟就能让追剧记录在所有设备上无缝接力 🎬