澜音：AI 歌词翻译、缓存与调用统计
开启与入口
安装更新后，先强制停止并重新打开 Apple Music，让宿主加载新版模块。
进入 澜音模块设置 → 歌词管理 → AI 歌词翻译与缓存，开启歌词替换和 AI 翻译，填写兼容 OpenAI 的接口地址、模型和需要的 API Key。启用功能后按提示重开 Apple Music。在线歌词补全可以关闭，AI 翻译不再以该开关为前提。
歌词管理和 AI 设置顶部会显示 API 请求、成功/失败、缓存歌曲和命中次数。点击 API 调用与翻译缓存 查看完整记录、缓存列表和操作按钮。
实际翻译哪份歌词
先按现有优先级选择手动、在线或原生歌词，再为选中的文档补充翻译；AI 不会通过另一份原生歌词覆盖用户选择的来源。已有译文、中文歌词、缺少逐行/逐字时间轴或不支持的格式会跳过，并记录原因。
后台翻译与手动操作共用同一缓存和按歌曲去重的请求通道。同一首歌的并发操作会优先等待已有请求，再复用结果；等待中的过期播放任务可以取消，不阻塞新歌曲。
直接验证功能
在统计页面选择：
- 立即翻译当前歌曲：使用当前已观察到的歌词；若未加载原生歌词，请先播放歌曲并打开歌词页面。
- 选择已配置歌曲翻译：选择已经导入或获取的歌词，无需等待播放器重新拉取。
翻译通过 TTML 校验后立即保存，与播放器是否仍持有原生指针分开处理。成功后通知当前播放器刷新。手动提交的任务会在后台完成，关闭统计页面不会丢弃译文。
在 已缓存的翻译歌词 中可查看歌曲、模型、保存时间和缓存大小；点击歌曲可预览前几句译文。再次翻译相同来源和配置时使用缓存，API 请求次数不应增加。删除指定缓存后，后续使用可重新请求；删除缓存不删除手动导入的原歌词。
更新与复用
每次准备选中歌词时，对比完整原歌词 TTML 的 SHA-256。文字、时间轴等变化会使旧缓存失效。接口、模型或有效思考配置变化也会重新翻译；仅轮换 API Key 不影响复用。
检测依据是本次实际提供的原歌词，不单独轮询远端。在线歌词来源的刷新仍按在线补全策略进行。每首歌保留一份当前缓存，最多保留最近使用的 100 首；切换来源或模型可能替换该歌曲的缓存。
调用记录与统计口径
| 项目 | 含义 |
|---|---|
| API 请求 | 实际提交的歌词翻译及连接测试请求，包含失败和取消的尝试；输入不合法、跳过和缓存命中不计入 |
| 成功 / 失败 / 取消 / 进行中 | 请求结果；播放器解析或文件保存失败独立记录，不伪装成 API 失败 |
| 缓存歌曲 | 当前磁盘上有效的翻译条目，与“已配置”的原歌词列表分开 |
| 缓存命中 | 使用已有翻译，未发起新的 API 请求 |
| Token | 接口返回的输入、输出和总量；没有返回时显示“—”，不推算费用 |
| 请求详情 | 类型、歌曲或 ID、模型、服务主机、时间、耗时、HTTP 状态与固定错误原因 |
| 缓存与播放诊断 | 保存成功/失败、来源或配置变更、跳过原因、播放器未接收等状态 |
统计从此版本启用后或上次清空后累计，不能还原旧版 API 调用。最近 200 条事件保存在本机；累计计数独立于记录条数。清除已完成记录和统计会保留进行中的请求。
日志不记录 API Key、认证头、接口返回正文、提示词和歌词原文；完整歌词只存在功能本身的本地缓存中。记录不会上传到本项目服务器。
没有译文时看哪里
- 请求数为 0，显示跳过：检查歌词是否已有译文、为中文或缺少时间轴。
- 暂无可用原歌词：先加载歌词，或选择已配置歌曲。
- 401 / 403：检查密钥与接口地址；404 检查路由与模型；429 等待限流恢复。
- HTTP 成功但格式不符：模型未返回约定的完整行翻译，保留原歌词，不保存残缺结果。
- 已生成但保存失败：检查可用空间与存储状态；API 调用成功不等于缓存已写入。
- 已缓存但播放器未接收：缓存可预览，但当前宿主的原生解析未通过；重开歌词并检查宿主版本兼容性。
真实设备的宿主版本适配与显示结果仍需实际播放验证。反馈问题时可提供不含密钥的状态、HTTP 码和模型信息。