AetherGate v0.13.3-preview 更新日志

⚠️ 此为预览版，主要优化米哈游音乐模块。

本次为 v0.13.2 的预览版本，聚焦音乐体验升级：专辑播放修复、下载歌曲自动写入元数据标签（标题/专辑/艺术家/年份/音轨/封面）、专辑缓存降低 API 调用频率、下载后跨线程报错修复、歌单列表滚动修复。

✨ 新功能

🎵 下载歌曲自动写入音乐元数据标签

从「米哈游音乐」下载的 MP3 文件现在会自动写入完整的 ID3 标签，导入本地播放器（如 iTunes、Foobar2000、Windows Media Player）后可正确显示歌曲信息。

• 标题：歌曲名称
• 专辑：所属专辑名称
• 艺术家：专辑全部艺术家，多人用 ; 分隔（如 HOYO-MiX; 蔡近翰）
• 年份：从专辑发布日期提取
• 音轨号：歌曲在专辑中的曲目序号
• 封面：专辑封面图，自动压缩至最长边 ≤ 1000 像素、体积 ≤ 800KB

📦 专辑信息本地缓存

专辑详情（含歌曲列表、媒体地址、封面等）现在会缓存到本地磁盘，同一专辑的多首歌曲下载仅需 1 次 API 请求。

• 缓存有效期 7 天，最长保留 30 天后自动清理
• 大幅降低 API 调用频率，避免触发服务端限流
• 跨专辑下载时自动加入 300ms 间隔，进一步保护服务端

🐛 Bug 修复

🔴 专辑内歌曲无法播放

修复打开专辑后点击播放提示 Invalid URI: The format of the URI could not be determined 的问题。

• 根因：服务端返回的音频地址为相对路径（如 /api/v1/song/{id}/stream），播放器直接使用导致 URI 解析失败
• 修复：下载与播放时自动将相对路径拼接为本站域名，转为绝对地址

🟡 歌单列表无法滚动

修复「我的歌单」与「他人公开的歌单」内容较多时无法滚动、底部歌单被截断的问题，现已正确显示垂直滚动条。

🔧 兼容性说明

• 本版本为预览版，仅向开启「预览版通道」的用户推送
• 无数据库迁移，无配置变更
• 系统要求：Windows 10 1809（17763）及以上版本

📦 安装与升级

• 下载地址：https://www.aethergate.cn
• 自动升级：开启预览版通道的用户启动主程序后会自动提示升级
• 系统要求：Windows 10 1809（17763）及以上版本
• 迁移说明：无数据库迁移，无配置变更

💡 v0.13.3-preview 是一次以音乐体验为核心的预览版本：专辑播放恢复正常、下载的歌曲自带完整元数据标签、专辑缓存让批量下载更顺畅。欢迎预览版用户体验并反馈问题。

AetherGate v0.13.2-preview 更新日志

⚠️ 重要：正式开放预览版通道！

本次为正式开放预览版更新通道——开启后可提前体验新版本，切回正式版时会自动清理预览版残留文件。*

✨ 新功能

🚀 预览版更新通道正式开放

设置中开启「预览版更新」后，即可接收预览版（版本号带预发布后缀，如 0.14.0-preview.1）推送，提前体验新功能；关闭开关则回到正式版通道。

• 通道完全隔离：正式版与预览版的安装包、压缩文件、更新清单分别部署，互不影响；正式版用户不会收到任何预览版推送
• 预览转正自动收敛：预览版用户切回正式版通道后，客户端自动按全量清单同步文件，并清理预览版独有的残留文件与空目录，保证安装目录与正式版完全一致，无需手动重装
• 版本比较遵循 SemVer：正式版版本号恒高于同号预览版（0.14.0 > 0.14.0-preview.1），正式版发布后预览版用户会正常收到转正更新

AetherGate v0.13.2 更新日志

⚠️ 重要：此版本修复了差量更新链路，同时正式开放预览版通道，建议所有用户升级！

本次为 v0.13.1 的升级版本，重点修复安装进度显示不准、安装中断后重试校验失败等问题，并正式开放预览版更新通道——开启后可提前体验新版本，切回正式版时会自动清理预览版残留文件。v0.13.0 / v0.13.1 用户升级至 v0.13.2 后，后续小版本更新将只下载变化的文件，更新包体积显著减小。

✨ 新功能

🚀 预览版更新通道正式开放

设置中开启「预览版更新」后，即可接收预览版（版本号带预发布后缀，如 0.14.0-preview.1）推送，提前体验新功能；关闭开关则回到正式版通道。

• 通道完全隔离：正式版与预览版的安装包、压缩文件、更新清单分别部署，互不影响；正式版用户不会收到任何预览版推送
• 预览转正自动收敛：预览版用户切回正式版通道后，客户端自动按全量清单同步文件，并清理预览版独有的残留文件与空目录，保证安装目录与正式版完全一致，无需手动重装
• 版本比较遵循 SemVer：正式版版本号恒高于同号预览版（0.14.0 > 0.14.0-preview.1），正式版发布后预览版用户会正常收到转正更新

🐛 Bug 修复

🟡 差量更新下载进度显示不准

修复差量更新时进度条以「未压缩总大小」为分母、而实际下载的是压缩文件，导致进度长期卡在低位后突然跳到 100% 的问题。

• 修复：进度总量改为按实际下载项（去重后）的压缩字节数累加；兼容旧清单（压缩大小为 0 时自动回退为未压缩大小），新装与全量更新的进度逻辑保持不变

🟡 安装中断后重试可能提示校验失败

修复安装过程中断（网络失败 / 手动取消）后重新安装时，已下载的临时分片可能被误判为完整文件而跳过，最终报文件校验失败（Checksum failed）的问题。

• 根因：断点续传判断时误将「压缩后大小」传入与「解压后临时文件长度」比较，导致已写入分片被当作完整文件
• 修复：改用未压缩文件大小参与续传判断，未下载完整的分片会正确续传，完整分片正常跳过，不再重复下载

🔧 兼容性说明

• 无数据库迁移，无配置变更；预览版开关沿用既有设置项，升级后默认保持关闭（正式版通道）
• 旧版本（v0.13.1 及更早）与 v0.13.2 之间仍走全量清单更新；自 v0.13.2 起发布的后续版本之间方可使用修复后的差量更新

📦 安装与升级

• 下载地址：https://www.aethergate.cn
• 自动升级：已安装 v0.13.0 / v0.13.1 的用户启动主程序后会自动提示升级
• 系统要求：Windows 10 1809（17763）及以上版本
• 迁移说明：无数据库迁移，无配置变更

💡 v0.13.2 是一次以更新链路修复为核心的版本：差量更新自此真正可用，日常小版本升级更快更省流量；同时预览版通道正式开放，愿意尝鲜的用户可在设置中开启。如有任何异常，欢迎通过「反馈问题」渠道提交日志以便快速定位。

AetherGate v0.13.1 更新日志

⚠️ 重要：此版本包含米哈游音乐模块的关键修复，使用音乐功能的用户请立即升级！

本次为 v0.13.0 的修复升级版本，主要解决音乐服务端歌单标识规则变更后，客户端打开「他人公开的歌单」时报错「加载他人公开歌单失败 / The JSON value could not be converted to System.Int32」、无法浏览与收藏的问题。正在使用 v0.13.0 的用户务必升级至 v0.13.1，否则公开歌单、收藏到歌单等功能将无法正常使用。

🐛 Bug 修复

🔴 米哈游音乐：公开歌单加载失败（歌单 ID 类型变更适配）

修复打开米哈游音乐页面时，「他人公开的歌单」区域报错 加载他人公开歌单失败：响应解析失败：The JSON value could not be converted to System.Int32（$.data.playlists[0].id） 的问题。

• 根因：音乐服务端已将歌单标识从「数字自增 ID」升级为 16 位 Base62 随机分享码（share_code，如 8wkxjVz6UnoGWDt1），以防止歌单被数字 ID 遍历刷库；而 v0.13.0 客户端仍按 int 解析歌单 id，字符串无法转整数，导致整个歌单列表响应反序列化失败
• 修复：将歌单标识在全链路统一改为不透明字符串透传（拼链接、回调接口原样传递，不再假设其为数字），覆盖：
  • 数据模型 Playlist.Id（int → string）
  • 音乐客户端 6 个歌单接口（歌单歌曲列表 / 公开歌单歌曲 / 新建 / 改名 / 删除 / 加入歌曲 / 移除歌曲）
  • 收藏歌单归属缓存、默认歌单查找、新建歌单选择器等 ViewModel 逻辑
  • 收藏选择对话框的「刚新建歌单」选中状态
• 不受影响：歌曲 ID、专辑 ID 仍为数字（音乐平台 ID），用户 ID 仍为数字，均保持原类型不变
• 影响范围：公开歌单列表、打开他人公开歌单、我的歌单、收藏歌曲到歌单、新建 / 改名 / 删除歌单、从歌单移除歌曲

🔧 兼容性说明

• 旧的数字歌单 ID 链接在服务端已统一返回 404（不做兼容），本次客户端改为字符串分享码后与服务端最新 API（2026-09-09 版）完全对齐
• 收藏状态缓存为运行时内存数据，升级后重新登录 / 刷新即可重建，无数据库迁移、无配置变更

📦 安装与升级

• 下载地址：https://www.aethergate.cn
• 自动升级：已安装 v0.13.0 的用户启动主程序后会自动提示升级
• 系统要求：Windows 10 1809（17763）及以上版本
• 迁移说明：无数据库迁移，无配置变更

💡 v0.13.1 是一次针对米哈游音乐模块的紧急修复版本，重点解决了服务端歌单分享码升级带来的兼容性问题。请务必升级至 v0.13.1，否则将无法浏览公开歌单与使用收藏功能。如有任何异常，欢迎通过「反馈问题」渠道提交日志以便快速定位。

AetherGate v0.13.0 更新日志

⚠️ 重要：此版本为全量更新，包含米哈游音乐模块的架构级改造与多项关键修复，请所有用户升级！

本次更新主要围绕 米哈游音乐模块 展开：鉴权体系从 Bearer Token 迁移到 PHP Session Cookie（与服务端最新 API 对齐）、修复歌曲封面不显示、修复退出后进程残留等问题。同时对侧边栏音乐图标进行了更新。正在使用 v0.12.x 的用户请升级至 v0.13.0 以获得完整的音乐播放体验。

✨ 新功能

🎵 米哈游音乐

鉴权体系全面适配服务端最新 API（2026-09-07 版），与 Web 前端共用会话。

• Session Cookie 自动管理：登录后服务端下发的 PHPSESSID 由 CookieContainer 自动持有并随请求携带，无需手动附加 Authorization 头
• 跨重启会话恢复：登录成功后将 Session Cookie 序列化持久化到本地配置，下次启动时自动恢复并调用 auth/user 验证登录态
• 会话失效检测：服务端返回 1003（未登录）/ 1005（凭据无效）时清除本地会话并提示重新登录；网络抖动 / 5xx / 限流等瞬时错误不会误判为掉线

🔧 功能调整

🎵 米哈游音乐：模型与接口对齐最新 API

根据服务端最新 API 文档对数据模型与接口调用进行全面对齐。

• MusicSource 模型补齐：新增 id、priority、supportedQualities、isEnabled 字段，与 /app-config 接口返回结构一致
• SongListResponse 增加 playlist 字段：歌单详情接口返回的歌单元数据（名称、封面等）现可正确接收
• UpdatePlaylistAsync 精简：请求体移除不支持的 description 字段，仅保留 name 与 is_public
• 专辑排序参数修正：首页"最新专辑"的 sort 参数从无效的 publish_date 修正为文档合法值 latest，确保专辑按发布时间倒序排列

🎨 侧边栏图标更新

• 主导航中“USM导出”、“MBTI”、"米哈游音乐" 的图标，功能语义更贴合。

🐛 Bug 修复

🔴 程序退出后进程残留挂起

修复关闭程序后，任务管理器中仍残留 AetherGate.exe 进程，导致无法重新编译或启动的问题。

• 根因：MihoyoMusicPlayer 启用了 SystemMediaTransportControls（SMTC），退出时未调用 Dispose()，其持有的前台线程 / COM 对象阻止进程终止；SystemTrayWindow 拦截了自身 Closing 事件导致窗口无法真正关闭
• 修复：
  • App.Exit() 中调用 MihoyoMusicPlayer.Dispose() 释放播放器与 SMTC
  • SystemTrayWindow 新增 ForceClose() 方法，退出流程中先解除 Closing 拦截再关闭窗口
  • 释放 _gcTimer（GC 定时器）
  • 兜底调用 Environment.Exit(0) 确保进程一定终止

📦 安装与升级

• 下载地址：https://www.aethergate.cn
• 安装方式：本次为全量更新，请下载完整安装包 AetherGate.Setup.exe 重新安装；已安装旧版本直接更新安装即可
• 系统要求：Windows 10 1809（17763）及以上版本
• 迁移说明：
  • 无数据库迁移

💡 v0.13.0 是一次以米哈游音乐模块改造为核心的全量更新。如遇任何异常，欢迎通过「反馈问题」渠道提交日志以便快速定位。

AetherGate v0.13.1 更新日志

⚠️ 重要：此版本包含米哈游音乐模块的关键修复，使用音乐功能的用户请立即升级！

本次为 v0.13.0 的修复升级版本，主要解决音乐服务端歌单标识规则变更后，客户端打开「他人公开的歌单」时报错「加载他人公开歌单失败 / The JSON value could not be converted to System.Int32」、无法浏览与收藏的问题。正在使用 v0.13.0 的用户务必升级至 v0.13.1，否则公开歌单、收藏到歌单等功能将无法正常使用。

🐛 Bug 修复

🔴 米哈游音乐：公开歌单加载失败（歌单 ID 类型变更适配）

修复打开米哈游音乐页面时，「他人公开的歌单」区域报错 加载他人公开歌单失败：响应解析失败：The JSON value could not be converted to System.Int32（$.data.playlists[0].id） 的问题。

• 根因：音乐服务端已将歌单标识从「数字自增 ID」升级为 16 位 Base62 随机分享码（share_code，如 8wkxjVz6UnoGWDt1），以防止歌单被数字 ID 遍历刷库；而 v0.13.0 客户端仍按 int 解析歌单 id，字符串无法转整数，导致整个歌单列表响应反序列化失败
• 修复：将歌单标识在全链路统一改为不透明字符串透传（拼链接、回调接口原样传递，不再假设其为数字），覆盖：
  • 数据模型 Playlist.Id（int → string）
  • 音乐客户端 6 个歌单接口（歌单歌曲列表 / 公开歌单歌曲 / 新建 / 改名 / 删除 / 加入歌曲 / 移除歌曲）
  • 收藏歌单归属缓存、默认歌单查找、新建歌单选择器等 ViewModel 逻辑
  • 收藏选择对话框的「刚新建歌单」选中状态
• 不受影响：歌曲 ID、专辑 ID 仍为数字（音乐平台 ID），用户 ID 仍为数字，均保持原类型不变
• 影响范围：公开歌单列表、打开他人公开歌单、我的歌单、收藏歌曲到歌单、新建 / 改名 / 删除歌单、从歌单移除歌曲

🔧 兼容性说明

• 旧的数字歌单 ID 链接在服务端已统一返回 404（不做兼容），本次客户端改为字符串分享码后与服务端最新 API（2026-09-09 版）完全对齐
• 收藏状态缓存为运行时内存数据，升级后重新登录 / 刷新即可重建，无数据库迁移、无配置变更

📦 安装与升级

• 下载地址：https://www.aethergate.cn
• 自动升级：已安装 v0.13.0 的用户启动主程序后会自动提示升级
• 系统要求：Windows 10 1809（17763）及以上版本
• 迁移说明：无数据库迁移，无配置变更

💡 v0.13.1 是一次针对米哈游音乐模块的紧急修复版本，重点解决了服务端歌单分享码升级带来的兼容性问题。请务必升级至 v0.13.1，否则将无法浏览公开歌单与使用收藏功能。如有任何异常，欢迎通过「反馈问题」渠道提交日志以便快速定位。

AetherGate v0.13.0 更新日志

⚠️ 重要：此版本为全量更新，包含米哈游音乐模块的架构级改造与多项关键修复，请所有用户升级！

本次更新主要围绕 米哈游音乐模块 展开：鉴权体系从 Bearer Token 迁移到 PHP Session Cookie（与服务端最新 API 对齐）、修复歌曲封面不显示、修复退出后进程残留等问题。同时对侧边栏音乐图标进行了更新。正在使用 v0.12.x 的用户请升级至 v0.13.0 以获得完整的音乐播放体验。

✨ 新功能

🎵 米哈游音乐

鉴权体系全面适配服务端最新 API（2026-09-07 版），与 Web 前端共用会话。

• Session Cookie 自动管理：登录后服务端下发的 PHPSESSID 由 CookieContainer 自动持有并随请求携带，无需手动附加 Authorization 头
• 跨重启会话恢复：登录成功后将 Session Cookie 序列化持久化到本地配置，下次启动时自动恢复并调用 auth/user 验证登录态
• 会话失效检测：服务端返回 1003（未登录）/ 1005（凭据无效）时清除本地会话并提示重新登录；网络抖动 / 5xx / 限流等瞬时错误不会误判为掉线

🔧 功能调整

🎵 米哈游音乐：模型与接口对齐最新 API

根据服务端最新 API 文档对数据模型与接口调用进行全面对齐。

• MusicSource 模型补齐：新增 id、priority、supportedQualities、isEnabled 字段，与 /app-config 接口返回结构一致
• SongListResponse 增加 playlist 字段：歌单详情接口返回的歌单元数据（名称、封面等）现可正确接收
• UpdatePlaylistAsync 精简：请求体移除不支持的 description 字段，仅保留 name 与 is_public
• 专辑排序参数修正：首页"最新专辑"的 sort 参数从无效的 publish_date 修正为文档合法值 latest，确保专辑按发布时间倒序排列

🎨 侧边栏图标更新

• 主导航中“USM导出”、“MBTI”、"米哈游音乐" 的图标，功能语义更贴合。

🐛 Bug 修复

🔴 程序退出后进程残留挂起

修复关闭程序后，任务管理器中仍残留 AetherGate.exe 进程，导致无法重新编译或启动的问题。

• 根因：MihoyoMusicPlayer 启用了 SystemMediaTransportControls（SMTC），退出时未调用 Dispose()，其持有的前台线程 / COM 对象阻止进程终止；SystemTrayWindow 拦截了自身 Closing 事件导致窗口无法真正关闭
• 修复：
  • App.Exit() 中调用 MihoyoMusicPlayer.Dispose() 释放播放器与 SMTC
  • SystemTrayWindow 新增 ForceClose() 方法，退出流程中先解除 Closing 拦截再关闭窗口
  • 释放 _gcTimer（GC 定时器）
  • 兜底调用 Environment.Exit(0) 确保进程一定终止

📦 安装与升级

• 下载地址：https://www.aethergate.cn
• 安装方式：本次为全量更新，请下载完整安装包 AetherGate.Setup.exe 重新安装；已安装旧版本直接更新安装即可
• 系统要求：Windows 10 1809（17763）及以上版本
• 迁移说明：
  • 无数据库迁移

💡 v0.13.0 是一次以米哈游音乐模块改造为核心的全量更新。如遇任何异常，欢迎通过「反馈问题」渠道提交日志以便快速定位。