Release v1.1.0

v1.1.0 发布说明

v1.1.0 主要改善两件事：让曲库整理更安全、更容易确认；让来自不同数据源的中文信息可以按需统一为简体中文。

曲库文件整理

歌曲列表现在可以直接发起文件整理。系统会先生成完整预览，展示整理根目录、原路径和目标路径，确认后再创建后台任务。整理只调整文件位置，不修改原文件名、音频内容或标签。

整理支持两种常用布局：

• 第一歌手 / 专辑 / 原文件名
• 第一歌手 / 原文件名

多歌手歌曲使用第一位歌手作为目录名，并保留原文件名。配套的 .lrc 歌词文件会随音频一起移动。目标冲突、无效路径、路径越界和不安全文件会在预览阶段拦截，任务执行前还会检查曲目版本，避免整理过期数据。

整理路径会跟随当前浏览位置：如果正在 M 目录中整理，目标会从 M 开始，例如 M/歌手/专辑/原文件名；从曲库根目录整理时，行为仍然是 歌手/专辑/原文件名。

可选的简体中文输出

数据源设置中新增“自动转为简体”开关。开启后，数据源在输出候选和歌词前会统一转换中文文本，覆盖歌曲名、歌手、专辑、风格以及普通歌词和带时间戳歌词等内容。

该选项已支持 Apple Music、MusicBrainz、LRCLIB、LrcApi、网易云、酷狗和酷我，并按数据源独立保存，默认关闭。关闭时不会改变现有结果；切换开关后也会使用对应的缓存版本，不会混用简体和繁体结果。

使用建议

第一次整理文件时，建议先在当前目录选择少量歌曲查看预览，确认目标路径和整理层级后再创建任务。需要统一中文显示时，可在“设置 → 数据源”中只为需要的数据源开启简体转换。

验证

本版本已通过 Go 全量测试、go vet ./...、前端全量测试、TypeScript 检查和生产构建，并完成曲库子目录整理预览验证；验证过程中未执行真实文件移动。

Release v1.0.5

v1.0.5 发布说明

数据源可用性修复

• 酷狗搜索迁移到当前可用的 songsearch.kugou.com 接口，兼容新的响应字段、搜索高亮和搜索结果内封面；旧 mobilecdn / msearchcdn 配置会自动迁移。
• 酷我封面不再使用证书失效的 *.kwcdn.kuwo.cn，新候选和已缓存的旧封面引用都会安全改写到 img4.kuwo.cn。
• 酷我歌词改用当前 openapi/v1/www/lyric/getlyric 接口，并保留旧 RID 歌词链路作为兼容回退。
• Apple / iTunes 默认 storefront 从当前返回空目录的 CN 调整为 HK；旧 CN 配置会自动迁移，中文和国际曲库搜索恢复正常。
• 远程封面下载器显式启用 HTTP/2，修复部分 Apple、网易云和 Cover Art Archive CDN 响应被误判为损坏 HTTP/1 数据的问题。

歌词与候选质量

• 网易云现在读取并按时间戳合并 lrc 与 tlyric，英文歌曲可以同时获得原文和中文翻译。
• 网易云只为最终可能返回的候选获取歌词，不再为随后丢弃的候选发送额外请求。
• 酷我搜索兼容当前响应中的秒数时长字段，候选时长评分更准确。

批量抓取性能

• 自动批量抓取从每个来源保留 5 个候选调整为 2 个；审核页手动重新匹配仍保留每源 5 个候选。
• 匹配任务使用最多 2 首曲目的受控流水线，在慢来源等待期间继续处理其他来源。
• 每个数据源仍由同一个 Gate 保证最多一个在途请求，曲目流水线不会绕过来源限流。
• 旧 Apple CN 设置会在启动时持久化迁移到 HK，避免每首歌重复触发约 3 秒的空目录回退。

数据源诊断 CLI

• 新增 --test-providers，无需启动 Web 服务或扫描曲库即可测试全部内置来源，包括设置中暂时关闭的实验来源。
• 诊断会绕过搜索缓存，汇总候选、歌词、封面和延迟，并默认真实下载、解码和校验候选封面。
• 支持自定义标题、歌手、专辑、时长、每源候选数，以及 --test-json 机器可读输出。
• 搜索或封面探测失败时退出码为 1；零候选或缺少可选资产记为 warning。

./tagger --data-dir ./data --test-providers

./tagger --data-dir ./data --test-providers \
  --test-title "Easy On Me" \
  --test-artists "Adele" \
  --test-album "30" \
  --test-duration 225 \
  --test-limit 2 \
  --test-json

升级提示

• 数据源端点和 Apple storefront 的内置旧值会在启动时自动迁移并持久化，无需手工清空数据库或 Provider 缓存。
• 网易云、酷我和酷狗仍属于实验性网页接口，默认启用状态不变；升级不会替用户打开已关闭的来源。
• 自动批量抓取候选数变为 2；需要查看更多版本时，可在审核页使用手动重新匹配。

验证

• Go 全量测试通过，并对匹配流水线与 Provider Registry 运行 race detector。
• 前端 134 项测试和 TypeScript 检查通过。
• 使用真实端点完成全部来源搜索、歌词与封面诊断；Apple、网易云、酷狗和 LrcApi 封面均完成实际下载校验。

Release v1.0.4

v1.0.4 发布说明

Ogg Vorbis 与 Ogg Opus

• 曲库完整支持 .ogg 和 .opus 文件的扫描、索引、筛选、单曲重扫与目录变化监听。
• Ogg Vorbis 与 Ogg Opus 统一归入 ogg 容器格式，并通过技术信息中的 codec 区分实际编码。
• 标签、歌词 sidecar、嵌入封面、安全写入和历史恢复全部接入现有流程，无需 FFmpeg、CGO 或系统 TagLib。
• 浏览器试听与 Range 请求使用 audio/ogg；未知扩展名会被明确拒绝，不再隐式当作 FLAC 处理。

批量处理上限

• 单次批量曲目上限由固定 1000 首改为后台可配置，默认提高到 2000 首。
• 可在「设置 → 系统与安全」中调整为 1–100000 首，配置写入 SQLite 并立即生效，无需重启。
• 曲目解析、全选、批量匹配、批量补全和批量编辑统一使用同一上限，超限提示会显示当前配置值。

曲库界面与目录树

• 较窄桌面宽度下，右侧曲目信息面板改为显式抽屉，避免覆盖歌曲列表；更窄时左侧目录也切换为抽屉。
• 长目录名不再使用持续滚动动画：默认稳定省略，悬浮或键盘聚焦后在页面顶层显示完整名称与相对路径，不受侧栏裁剪。
• 当前目录使用浅色强调和左侧标记，减少大面积深色选中态带来的视觉干扰。
• 桌面端目录栏支持 210–420px 拖拽调整，宽度会在浏览器中记忆；也支持方向键微调和双击恢复响应式默认值。

审核体验

• 候选来源选择列表现在直接展示歌手；无歌手信息时显示明确占位，减少同名歌曲的误选风险。

升级提示

• 系统设置会自动使用新的 2000 首默认批量上限，不需要数据库迁移或手工修改配置。
• 升级后建议对已有曲库执行一次快速扫描或完整扫描，以便把过去未识别的 .ogg、.opus 文件加入索引。

验证

• Go 全量测试通过。
• 前端全量测试、TypeScript 检查和 Vite 生产构建通过。

Release v1.0.3

v1.0.3 发布说明

跨源智能选择

• 所有已启用数据源的候选结果现在会自动综合成一个「智能选择」方案，排在候选列表首位。
• 系统先对所有候选做录音聚类（标题、艺术家、版本词、稳定标识、时长），再做发行版本聚类（专辑、专辑艺术家、年份、音轨号），然后逐字段择优合并。
• 满足以下全部条件时，智能候选会被自动标记接受，无需手动操作：录音匹配度 ≥ 94%、与次优聚类分差 ≥ 8%、无字段冲突、且存在两个以上独立来源或稳定标识（ISRC / MusicBrainz / AcoustID）确认。
• 每个字段保存主来源及确认来源，审核页逐字段展示真实数据源名称。
• smart 候选展示跨源证据卡：录音匹配分、发行匹配分与分差。
• 保留 ai 候选类型接口；模型服务未配置时显示明确占位状态，不伪造结果。
• LrcApi 聚合适配器可以贡献字段，但不计入自动接受所需的独立来源数。

评分算法改进

• 标题匹配新增版本词分离：live、remix、remaster、acoustic、instrumental 等中英文词组从基础标题中剥离后单独比较，版本词冲突的候选不会进入同一聚类。
• 稳定标识（ISRC / MusicBrainz Track ID / AcoustID）命中时置信度直接提升至 99%；冲突时上限降至 25%。
• 艺术家相似度改用集合交集与字符串相似度的最大值，减少多艺术家拼接的误判。
• 排序优先展示推荐候选，其次按资产质量（有无封面/歌词）和字段完整度排序。

查询与文件名解析

• 匹配搜索时自动携带文件已有的 ISRC、MusicBrainz Track/Release ID、AcoustID，提高稳定标识命中率。
• 文件名路径提示自动剥离音轨序号前缀（如 01 -、02.、CD1 03 -）。
• 文件名分隔符扩展支持全角短横线（–）和全角长横线（—）。

交互改进

• 候选列表和候选选择器按「推荐方案」/「原始数据源」分组呈现。
• 工具栏「接受所有高置信」改为「接受所有自动推荐」，判断依据统一由后端 autoAccept 标志决定，不再在前端硬编码分数阈值。
• 审核页加载失败与空结果各有独立错误状态页，支持一键重试。

Release v1.0.2

v1.0.2 发布说明

数据源与封面

• MusicBrainz 增加独立的 Internet Archive 下载基址配置，默认仍为 https://archive.org。
• Cover Art Archive 返回的 archive.org/download/... 重定向可以安全改写到 HTTPS 镜像，也支持 https://proxy.example/https/archive.org 这类带路径前缀的通用代理。
• 数据源测试、候选封面预览、后台写入和磁盘缓存统一使用配置感知的封面下载入口，并继续执行主机白名单、重定向和图片内容校验。

任务状态与安全写入

• 统一任务计数与终态：全部失败使用 failed，成功和失败并存才使用 partial；100% 明确表示处理进度而不是成功率。
• 写入和批量编辑详情分别显示已处理、成功、失败数量，并保留最近一次失败原因。
• 新增任务计数不变量检查和 SQLite migration，自动修正旧版本中“成功 0、失败 N，却显示部分完成”的历史任务。
• 批量写入与批量编辑入队前真实探测每个目标目录能否创建同级临时文件，不可写时直接返回可操作的权限提示，不创建注定失败的任务。
• 修复标签写入成功、后续封面失败时同一曲目被同时计入成功和失败的问题；已发生的标签变更仍会重新索引并写入历史。
• 重试覆盖取消前缺失或仍为 pending 的项目，并把总数更新为实际重试项数量；失败/部分完成的匹配任务仍可重新打开审核。

Docker 部署

• 镜像继续默认以非 root 的 10001:10001 运行。
• README 增加 Docker --user UID:GID、Compose user:、UID/GID 查询、共享组及 /music、/data 权限说明，便于适配宿主机和 NAS 的目录所有权。

Tagger v1.0.1 — 首个公开版本

Tagger v1.0.1 — 首个公开版本

Tagger 是一个面向个人音乐档案的本地元数据工作台，用于浏览、匹配、审核并安全地修改音乐文件标签。

这是 Tagger 的首个公开发行版本。

核心能力

• 浏览和编辑 MP3、FLAC、WAV 的标签、歌词、封面及技术信息。
• 支持标题、艺术家、专辑、专辑艺术家、音轨号、年份、风格、BPM、ISRC、MusicBrainz ID 等常用字段。
• 管理多个本地音乐库，并通过目录、格式、状态和关键词筛选曲目。
• 使用服务端分页浏览大型曲库，避免一次性将所有曲目载入浏览器。
• 文件变更实时索引，并通过任务中心展示扫描、匹配和写入进度。
• 提供跨页面音频预览、响应式界面、主题和字体设置。

多数据源匹配

Tagger 可以从多个数据源查询标签、歌词和封面候选：

• MusicBrainz
• LRCLIB
• Apple / iTunes
• 网易云音乐
• 酷我音乐
• 酷狗音乐
• 可自行部署的 LrcApi

候选结果不会直接覆盖文件。你可以查看本地值与候选值的差异，逐字段选择需要采用的内容，再创建写入任务。

标签兼容性

首个版本内置针对播放器和媒体服务器的标签兼容性检查：

• 音频标签与文件名、目录推断结果完全分离。
• 文件名推断只作为可选提示，不会自动写入文件。
• 检查缺少标题、艺术家、专辑和专辑艺术家等问题。
• 检测“专辑艺术家疑似写成专辑名”等异常值。
• MP3 写入使用并验证 TIT2、TPE1、TALB、TPE2 等标准 ID3 字段。
• 改善 Navidrome 等媒体服务器对艺术家和专辑信息的识别。

安全写入与历史恢复

• 写入前检查文件 revision，防止覆盖外部修改。
• 在临时副本上写入并重新读取验证。
• 验证通过后再原子替换原文件。
• 保存字段差异、标签快照和封面历史。
• 支持预览并恢复历史版本。
• 批量任务支持取消、失败项重试和服务重启恢复。

下载与运行

Release 发布后将自动生成 Linux x86_64 二进制：

• tagger_1.0.1_linux_amd64.tar.gz
• 对应的 SHA-256 校验文件

同时提供 linux/amd64 和 linux/arm64 Docker 镜像：

docker pull ghcr.io/ericwyn/tagger:1.0.1

也可以使用：

docker pull ghcr.io/ericwyn/tagger:latest

容器支持通过以下环境变量配置：

• TAGGER_MUSIC_DIR
• TAGGER_DATA_DIR
• TAGGER_LISTEN
• TAGGER_AUTH_TOKEN