MusicListsGUI v1.1.25 分享版（2026-11-13）
==========================================

一、怎么用
---------
1. 把整个文件夹解压到任意“可写”的位置，例如 D:\MusicListsGUI\；
   不要放在 C:\Program Files、只读 U 盘或系统保护目录。
2. 双击 MusicListsGUI.exe。第一次启动会自己找 PEAK 的插件目录，
   并按下面的模式决定辅助程序放哪跑。
3. 窗口两页：概览（各平台歌单 / 平台状态）、PEAK（当前播放、歌词、辅助进程、日志）。

组成：
  MusicListsGUI.exe   主程序（已内置 Python 运行时与 Tcl/Tk，不需要另装 Python）
  _internal\          运行时与资源（不要删、不要单独移动 exe 出去）
  使用说明.txt        本文件

二、运行环境
-----------
- Windows 10 1809 及以上 / Windows 11，64 位。
- 不需要安装 Python、.NET Framework 运行时、Visual C++ 运行库（已随包带上）。
- 第一次运行如果弹“Windows 已保护你的电脑”：点“更多信息”→“仍要运行”；
  杀软报毒属于 PyInstaller 打包的常见误报，可以把整个文件夹加入白名单。

三、辅助程序放在哪（peak_panel_config.json 里的 helperMode）
--------------------------------------------------------
两个辅助程序 MusicProgressReader.exe / QmLyricsServer.exe 默认随包放在
_internal 里，启动方式二选一：

  "helperMode": "auto"   （默认）
      若找到 PEAK 插件目录，就把两个 exe 复制过去、从那里启动；
      这样和游戏内模组共用同一份歌词缓存（200+ 条历史）和同一份 json。
      已经装过模组的机器上，模组通常自己也起了一个 reader，
      GUI 检测到同名进程在跑就直接复用，不会重复启动。

  "helperMode": "local"
      完全不碰 PEAK 目录：把两个 exe 复制到 GUI 根目录再启动，
      music_progress.json / qq_progress.json / lyrics_cache.txt / 日志
      全部落在 GUI 根目录，整个文件夹可以直接拷走、删除干净。

实测（2026-11-13）：只把 exe 放进普通目录（不带 PEAK 目录里那堆 DLL）
也能正常枚举窗口、锁定播放器、写进度和歌词；
日志里写明 `SMTC ready (play/pause state only, no title/progress used)`，
所以 PEAK 目录里的 Microsoft.Windows.SDK.NET.dll / WinRT.Runtime.dll
是给游戏内模组用的，辅助 exe 不依赖它们。

四、关于歌曲总时长
----------------
进度条和百分比需要 endMs（歌曲总时长）。这个值由辅助程序从播放器/本地数据里取，
有些歌能拿到、有些歌拿不到（实测同一台机器上《半壶纱》有 3:42，《爱情转移》为 0），
与辅助程序放在哪个目录无关。拿不到时界面显示 0:47 / --:--，百分比为空，
其余信息（歌名、歌手、进度、歌词、来源、缓存）不受影响。

五、对外的统一出口（给其他模组/工具用）
-----------------------------------
  GET http://127.0.0.1:<apiPort>/api/all       一次拿全：播放进度 + 歌单 + 平台状态 + 运行态
  GET http://127.0.0.1:<apiPort>/api/progress  只拿当前播放（含歌词解析行、来源、平台、计时器）
  GET http://127.0.0.1:<apiPort>/api/lists?platform=qq
  GET http://127.0.0.1:<apiPort>/api/platforms
  GET http://127.0.0.1:<apiPort>/api/health
  不想开 HTTP 的，可以直接读程序目录下的 music_lists_api.json（约 0.4 秒重写一次）。

  参数：apiPort 默认 8765，被占用顺延 8766-8775，以 /api/all 返回的 apiPort 为准。
  刷新节奏：进度 500ms 一个 tick，HTTP 请求即最新；快照 0.4 秒重写；
  歌单按界面上的“自动刷新 N 秒”抓取，status.dataAgeMs 标明数据多旧。
  无歌在播时 progress 是 {"source":null,"selected":null}，消费前必须判空。

六、已知限制
-----------
1. 进度与歌词依赖两个辅助程序能锁到播放器；没装 PEAK 时只能看歌单，播放区为空。
2. GUI 里的“时间轴微调”只影响 GUI 界面和 /api/progress、/api/all 这条时间轴
   （正数=歌词延后，负数=提前）。游戏内悬浮歌词用的是模组自己的配置
   com.peak.floatinglyrics.cfg 的 [Lyrics] OffsetSeconds，GUI 动不了它。
3. 纯只读工具：不修改歌单、不控制播放；没有 seek/切歌/写微调的接口。
4. 歌单需要各平台登录（QQ 可扫码登录，网易云/酷狗需要本地客户端登录态）。

打包环境：Python 3.13.18 + PyInstaller 6.22.3，未使用 UPX 压缩。

七、雷霆商店版额外说明（游戏内自动启动）
--------------------------------------
本包比普通分享版多了一个 BepInEx 插件 MusicListsGUILauncher.dll（8,704B），
它只做两件事：
  · 进游戏时自动打开 MusicListsGUI.exe（并检测已经在跑的话不再开第二个）；
  · 退出游戏时先正常关闭它（GUI 会顺手停掉两个 helper），3 秒不退再强制结束。

配置：BepInEx\config\com.peak.musiclistsgui.launcher.cfg
  Startup/Enabled        true   进游戏自动打开
  Startup/CloseWithGame  true   退游戏跟着关
  Startup/StartDelaySec  0      延迟几秒再开（0-60）
  Startup/ExtraArgs      ""     额外命令行参数（一般留空）

不想让它自动启动：把 Enabled 改 false，或者直接删掉那个 dll，手动双击
MusicListsGUI.exe 一样能用。插件不注入游戏、不读游戏内存。