车万女仆档案（迁移）管理器（Maid File Manager）

# Maid File Manager 1.6.4 — Changelog / 更新日志

> **English** first, then **中文** below.
>
> Minecraft 1.20.1 (Forge / Fabric) · 1.21.1 (NeoForge / Fabric) · Requires **Touhou Little Maid**
> `.maid` file format stays at **v7** — existing files keep working.

---

# Part 1 — English

## What this release is

1.6.4 is a **stability-first** release. Before shipping, the project went through **7 independent code-audit rounds**
across all four loader ports (~57k lines per pass), fixing roughly **340 issues** — **13 of them release blockers**
that would crash the client, disconnect players, or lose data.

It also ships a new UI theme song: **"Journey with Jiu Hu" (与酒狐的旅行)** — 80 BPM · 4/4 · A minor → C major · 4:06,
written by the author.

---

## Highlights

### 🎵 New UI theme song — "Journey with Jiu Hu" (与酒狐的旅行)

- Plays whenever any of this mod's screens is open (default volume 0.15; toggle/adjust with the client config `ui_music` / `ui_music_volume`)
- Vanilla background music is suppressed while it plays
- Transcoded to stereo 44.1 kHz, master loudness −14.0 LUFS
- **This track is NOT covered by the project's MIT license — all rights reserved.** It may be redistributed unmodified as part of this mod only; extracting, redistributing separately, remixing/sampling, or using it in other works is not permitted. See the in-repo *Music Notice*.
- Composed & written by 逐光星火-执火人 · from the album《车万女仆档案管理器 主题曲与配乐》

### 📦 Large files finally transfer on 1.20.x

Vanilla 1.20.x caps a custom payload at **32,767 bytes**, while a `.maid` with an embedded portrait is usually 40–130 KB
(portrait photos up to 128 KiB). On a real server that used to mean an **immediate disconnect with no feedback**.

A chunked channel now covers **import, profile save, and export**:

- Upload direction: 24 KiB per chunk, 8 MiB total per session, max 512 chunks
- Up to 8 concurrent sessions (4 per player), auto-reclaimed after 60 s without progress
- Oversized payloads now return an explicit error instead of failing silently
- Single-player / LAN host (integrated server) uses in-memory transport and was never affected

### 🗑️ "Export and remove" is now reliable

- The server only **registers the maid for deletion**; it deletes her after the client confirms the file was written
- Disk full / permission error / bad path → **the maid is not deleted**, she stays in the world for a retry
- Fixes both "file written but the maid is still there" and "maid gone but no file produced"

### 🖼️ Portraits work properly now

- Saving a profile with a portrait on 1.20.x no longer disconnects
- The "clear photo" button actually works (the server now deletes the photo file instead of just hiding it)
- Source-image cap lowered from 10 MB to 4 MB to reduce stutter while picking (the embedded size limit stays 128 KiB)

### ⚡ No more UI stutter

Five operations that used to run on the render thread were moved to background threads:

| Operation | Previous symptom |
|---|---|
| Photo decode + resize | Picking a large image stuttered badly |
| Backup directory scan | Opening the backup manager froze |
| Backup file read | Exporting a backup froze the screen |
| Batch import read | Importing dozens of files stuttered for seconds |
| Profile snapshot preview | Clicking "profile" dropped a frame |

Also fixed the O(n²) line-wrap computation in the multi-line text editor (long backstories dropped frames)
and excessive suppression of vanilla music.

### 🖱️ Clicking a row now selects that row

- After scrolling, clicking no longer selects an **invisible** maid
- Combined with "delete source file after import", it no longer **deletes the wrong file**
- The "profile" button and row checkboxes now have hitboxes that match where they are drawn
- Collapse / select-all checkbox states and counts are finally consistent

### 🔤 UI text and layout

- Fixed a nasty one: a trailing comma in the language file made Minecraft **skip the entire language table**,
  leaving every screen showing raw keys like `maid_file_manager.gui.xxx`
- The three left-side tool buttons are top-aligned again (they used to slide to the panel bottom on tall windows
  and cover the feedback text)
- On narrow screens (1024×768 at GUI scale 3 → 341×256): buttons no longer overflow and name columns are no longer all "…"

### 🏷️ Custom models show their real names

Third-party model packs (geckolib models under `tlm_custom_pack`) used to show internal short IDs like `zhiban_hanfu`;
they now display the proper name from the model pack.

---

## Full fix list (by category)

### Crashes / disconnects / data loss (13)

| # | Issue |
|---|---|
| 1 | 1.20.x: importing a `.maid` with a portrait got the client disconnected (32,767-byte cap, no precheck, no chunking) |
| 2 | 1.20.x: saving a profile with a portrait disconnected as well |
| 3 | Renaming a `.maid` into certain patterns crashed the client every frame when opening the import tab |
| 4 | The OP "server export" flow always exported 0 maids while reporting "request sent" |
| 5 | NeoForge disconnected on every login (config-sync payload wrote one field less than it read) |
| 6 | NeoForge: non-OP players could run `exportall` (duplicate root-command registration dropped the permission gate) |
| 7 | fabric-1.20.1: networking completely dead (payload released before encoding) |
| 8 | fabric-1.21.1: "export and remove" always broken (ack payload never registered) |
| 9 | fabric: both ports crashed on startup |
| 10 | neoforge: batch imports above 24 KiB were silently dropped |
| 11 | Export never wrote the file yet reported success → combined with "export and remove", maids were lost permanently |
| 12 | Released jars did not match the source tree / README (an intermediate build was shipped) |
| 13 | Trailing comma in the language file made Minecraft skip the whole language table |

### Features that were actually unusable (fixed)

- "Export and remove" did not work at all on 3 of the 4 ports
- The "clear photo" / "clear portrait" buttons did nothing
- The server's "pack config failed to parse" verdict could not reach the client (server denied everything, client still showed allowed)
- `bauble_import.json` with a mistyped field **failed open** (allow-list silently emptied)
- fabric-1.21.1: profile save failed 100% of the time (`VarInt` written, `readInt` read)
- Missing version migration for backup `.dat` files
- Bauble block-list screen fully covered by its background; buttons off-screen at 480×270
- Server-export confirm screen pushed its buttons off-screen at 341×192

### Data integrity

- 1.21 → 1.20 bauble attribute downgrade wrote the wrong attribute format (missing `AttributeName`, wrong `Operation` type,
  wrong UUID format, wrong slot key)
- Same-version imports also permanently dropped 4 kinds of addon data (sub-config / skill data / task maps / model variables)
- Advancement application did not filter by namespace (crafted `.maid` files could grant arbitrary advancements)
- A single malformed Curios entry wiped the whole bauble list
- Backup files' Mojang data version was written into the internal format version, corrupting version checks
- Count fields were cast to `byte`, overflowing above 127

### Networking & protocol

- Config lists longer than 256 entries misaligned the packet
- The 1.20.x S2C 1 MiB limit was measured differently on both ends (30–50 bytes apart), so boundary packets disconnected
- Chunk sessions had no cap; pending-deletion state was not cleared on disconnect; the client never cleared download sessions
- The legacy single-packet channel bypassed rate limiting
- Both fabric ports had no protocol version check
- The protocol version was stuck at `"1"` while the channel set had changed (now `"2"` — so **1.6.3 and 1.6.4 cannot play together over a remote server**; single-player is unaffected)

### UI & interaction

- Scrolled lists selected the wrong entry; the import list had no hitbox cleanup
- On narrow screens the name column shrank to 4 px, showing only "…"
- The backup manager did not refresh after a local scan (always showed "no maid backups found")
- Async player-name resolution never landed (uncached players showed short UUIDs forever)
- Picking an image failed without closing the overlay (message hidden); finishing after the screen closed leaked a texture
- On the "by mod" tab, toggling a row immediately re-sorted the list, so double-clicking hit two different mods

### Safety & robustness

- Three high-frequency request handlers had no rate limit (any player could loop packets and stall the server) → request throttling added
- One reflection failure blacklisted bauble parsing for the rest of the process
- In-flight states for import / export / server-export now have timeouts and self-healing (buttons no longer get stuck)
- Import submission is de-duplicated while in flight (double-clicking no longer spawns duplicate maids)
- All third-party SPI extension points are wrapped in exception guards

### Performance

- Five render-thread operations moved to background threads (see table above)
- Line-wrap computation went from O(n²) to linear
- Backup scanning limited to 200 directories per dimension with a warning
- Photo source-image cap tightened to 4 MB
- Chunk progress logging lowered from per-chunk INFO to debug

### Documentation

- README: added the full 1.6.4 fix inventory grouped by severity
- Format spec: corrected the `data_version` fallback rule, switch count (five → six), same-UUID import gate, advancement merge gates
- Music notice: added track details and licensing scope
- Removed stale version numbers, line references and self-contradictory statements

---

## Compatibility & upgrading

| Item | Notes |
|---|---|
| `.maid` format | Still **v7** — files exported by 1.6.3 import normally |
| Data migration SPI | Unchanged signature; addons do not need a rebuild |
| Config files | Format unchanged; existing configs carry over |
| **Remote multiplayer** | **1.6.3 and 1.6.4 cannot connect to each other** (protocol bumped to `"2"`); single-player and LAN are unaffected |
| Upgrading | Just replace the old jar |

## Downloads

| Loader | MC version | File |
|---|---|---|
| Forge | 1.20 / 1.20.1 | `maid_file_manager-forge-1.20.1-1.6.4.jar` |
| NeoForge | 1.21 / 1.21.1 | `maid_file_manager-neoforge-1.21.1-1.6.4.jar` |
| Fabric | 1.20 / 1.20.1 | `maid_file_manager-fabric-1.20.1-1.6.4.jar` |
| Fabric | 1.21 / 1.21.1 | `maid_file_manager-fabric-1.21.1-1.6.4.jar` |

## Known issues

- In the server-side `/maidfile` command feedback, custom model names still show the internal short ID — Touhou Little Maid's
  server-side model table only registers packs it knows about. The **client UI** shows proper names.
- A few layout edge cases at extremely small GUI scales remain, intentionally deferred.

---

# Part 2 — 中文

## 这一版做了什么

1.6.4 是一次**以稳固为主**的版本：发布前经历了 **7 轮独立代码审查**，四个加载器工程各约 5.7 万行代码被逐行看过一遍，
累计修复 **约 340 项**问题，其中 **13 项是会导致崩溃、掉线或丢数据的严重缺陷**。

同时换上了新的界面主题曲 —— **《与酒狐的旅行》**（80 BPM · 4/4 · A 小调 → C 大调 · 4:06），由 **逐光星火-执火人** 原创。

---

## 重点变化

### 🎵 新的界面主题曲《与酒狐的旅行》

- 打开本模组任意界面时播放（默认音量 0.15，可在客户端配置 `ui_music` / `ui_music_volume` 关闭或调整）
- 播放期间自动压制原版背景音乐
- 立体声 44.1 kHz 转码，母带响度 −14.0 LUFS
- **该曲目不适用本模组的 MIT 许可证，保留所有权利**：可随本模组原样分发，但不得单独提取、再分发、二次创作或用于其它作品。详见仓库内《音乐版权声明》
- 作曲 / 作词：逐光星火-执火人 · 收录于《车万女仆档案管理器 主题曲与配乐》

### 📦 大档案终于能传过去了（1.20.x）

1.20.x 的原版网络包有 **32767 字节**硬上限，而带内嵌头像的 `.maid` 通常 40~130 KB、档案照片可达 128 KiB。
此前这类数据在**真联机**下会被服务端直接断连、且不给任何提示。

现在新增分片通道，覆盖 **导入、保存档案、导出** 三条路径：

- 上传方向：单片 24 KiB，单会话总量上限 8 MiB，最多 512 片
- 同时最多 8 个分片会话（每玩家 4 个），60 秒无进展自动回收
- 超限时给出明确回执，不再静默失败
- 单人世界 / 局域网主机的集成服务器走内存直连，本来就不受该限制

### 🗑️ 「导出并移除」现在真的可靠

- 服务端**先登记待删**，等客户端确认写盘成功才删除女仆
- 客户端写盘失败、磁盘满、权限不足、路径异常 → **女仆不会被删**，留在世界里等重试
- 修掉了「档案导出成功、女仆却还在」和「女仆没了、文件也没生成」两种情况

### 🖼️ 头像功能修好了

- 1.20.x 保存带头像的档案不再掉线
- 「清空照片」按钮真正生效（服务端会删除照片文件，不再只是界面上消失）
- 档案照片源图上限 10 MB → 4 MB，减少选图时的卡顿（内嵌体积仍是 128 KiB 上限）

### ⚡ 界面不再卡顿

五处原本在渲染线程同步执行的耗时操作移到后台线程：

| 操作 | 之前的症状 |
|---|---|
| 照片解码 + 缩放 | 选一张大图明显卡帧 |
| 备份目录扫描 | 打开备份管理界面冻住 |
| 备份读盘 | 导出备份时整屏僵住 |
| 导入读盘（批量） | 一次导入几十份卡数秒 |
| 档案快照预览 | 点「档案」按钮卡一帧 |

另外修掉了长文本编辑框的 O(n²) 换行计算（长背景故事时掉帧）与背景音乐压制过度的问题。

### 🖱️ 点哪行就是哪行

- 列表滚动后点击，不会再勾中「看不见的另一只女仆」
- 配合「导入后删除源文件」时**不会再删错文件**
- 「档案」按钮、行内勾选框的命中区与显示位置一致
- 折叠 / 全选的勾选状态与计数完全一致

### 🔤 界面文字与布局

- 修掉了一个隐蔽的致命问题：语言文件末尾多一个逗号会让 Minecraft **整份跳过语言表**，
  导致所有界面显示 `maid_file_manager.gui.xxx` 这样的原始键名
- 左侧三行工具按钮改回顶部对齐（窗口较高时不再跑到面板底部压住提示文字）
- 窄屏（1024×768 + GUI scale 3，逻辑 341×256）下：按钮不再溢出、文字区不再是「…」

### 🏷️ 自定义模型显示正式名称

第三方模型包（`tlm_custom_pack` 里的 geckolib 模型）此前在列表里会显示成 `zhiban_hanfu` 这样的内部短名，
现在会显示模型包自带的正式名称。

---

## 完整修复清单（按类型）

### 崩溃 / 掉线 / 丢数据（13 项）

| # | 问题 |
|---|---|
| 1 | 1.20.x 导入带头像的档案会被服务端断连（32767 字节上限，无预检无分片） |
| 2 | 1.20.x 保存带头像的档案同样断线 |
| 3 | 把 `.maid` 重命名成某些格式后打开导入页，客户端每帧抛异常崩溃 |
| 4 | 统一导出流程必然导出 0 条，却提示「请求已发送」 |
| 5 | NeoForge 每次登录必断连（配置同步包编码漏写一个字段） |
| 6 | NeoForge 非 OP 可以执行 `exportall`（根命令重复注册导致权限门槛丢失） |
| 7 | fabric-1.20.1 网络整体不可用（数据包在编码前被释放） |
| 8 | fabric-1.21.1「导出并移除」必坏（回执通道未注册） |
| 9 | fabric 两端启动即崩 |
| 10 | neoforge 超过 24 KiB 的批量导入静默丢失 |
| 11 | 导出永不落盘却回报成功 → 配合「导出并移除」会永久丢女仆 |
| 12 | 发布的 jar 与源码 / README 不一致（发布了中间态构建） |
| 13 | 语言文件尾逗号导致整份语言表被跳过（全界面显示原始键名） |

### 功能实际不可用（已修复）

- 「导出并移除」在 3/4 个分发上完全不生效
- 「清空照片 / 清空头像」按钮无效
- 服务端「整合包配置解析失败」的判定无法同步给客户端（服务端已拒绝、客户端仍显示允许）
- 整合包 `bauble_import.json` 字段类型写错时**失败开放**（白名单静默失效）
- fabric-1.21.1 保存档案 100% 失败（`VarInt` 写、`readInt` 读）
- 备份 `.dat` 的版本迁移缺失，跨版本备份导入异常
- 饰品禁用界面整屏被背景遮住、480×270 下按钮出屏
- 统一导出确认屏在 341×192 下按钮整体出屏

### 数据完整性

- 1.21 → 1.20 的饰品属性降级写错格式（缺 `AttributeName`、`Operation` 类型错、UUID 格式错、槽位键名错）
- 同版本导入时也会永久丢弃 4 类附属数据（子配置 / 游戏技能 / 任务数据 / 换模变量）
- 成就应用端未按命名空间过滤（构造过的档案可写入任意成就）
- Curios 列表元素类型异常时整个饰品列表被静默清空
- 备份文件里的 Mojang 数据版本被写进内部格式版本，导致版本判定错乱
- 数量字段用 `byte` 强转，超过 127 时溢出为负数

### 网络与协议

- 配置列表超过 256 条时整包错位
- 1.20.x 服务端 → 客户端的 1 MiB 上限口径差 30~50 字节，边界包会断连
- 分片会话无数量上限；断线后不清理待删登记；客户端不清理下载会话
- 旧版单发通道没有频次限制（可绕过限流）
- fabric 两端缺少协议版本校验
- 协议版本号恒为 `"1"`，与实际的通道变化不符（1.6.4 起为 `"2"`，因此 **1.6.3 ↔ 1.6.4 远程联机互拒**，单人世界不受影响）

### 界面与交互

- 滚动后点行选中错误条目；导入列表无命中区清理
- 窄屏下列表文字区只剩 4px，名字全是「…」
- 备份管理在本机模式下扫描完成后不刷新（恒显示「未找到任何女仆备份」）
- 备份屏玩家名异步解析永远不生效（非缓存玩家只显示短 UUID）
- 选图失败时浮层不关闭，提示被遮住；选图异步完成时界面已关会泄漏纹理
- 「按模组」页勾选后行立即重排，连点会改到两个不同模组

### 安全与稳定性

- 三个高频请求 handler 无频次限制（普通玩家即可循环发包卡服）→ 新增请求频控
- 饰品反射缓存一次失败后本进程永久不再解析
- 导入 / 导出 / 统一导出的在途状态补上超时与自愈，不会永久卡住按钮
- 导入提交增加在途去重（连点两次不再重复生成女仆）
- 所有第三方模组扩展点调用包了异常保护，第三方 mod 出错不会拖垮导入流程

### 性能

- 五处主线程耗时操作改为后台线程（见上文表格）
- 长文本编辑框换行计算 O(n²) → 线性
- 备份扫描限制每个维度最多 200 个目录，超出打警告
- 档案照片源图上限收紧到 4 MB
- 分片进度日志从逐片 INFO 降为 debug，避免刷屏淹没真正的错误

### 文档

- README 增加 1.6.4 完整修复明细（按严重级别分类）
- 《女仆文件格式规范》：修正 `data_version` 缺失规则、开关数量（五项 → 六项）、同 UUID 导入闸门、成就合并的两道闸门
- 《音乐版权声明》：补充曲目信息与授权范围
- 清理过期的版本号、行号与自相矛盾表述

---

## 兼容性与升级

| 项 | 说明 |
|---|---|
| `.maid` 文件格式 | 仍为 **v7**，1.6.3 导出的档案可直接导入 |
| 数据迁移 SPI | 签名未变，附属模组无需重新构建 |
| 配置 | 客户端 / 服务端配置文件格式未变，旧配置直接沿用 |
| **远程联机** | **1.6.3 与 1.6.4 无法互连**（协议版本升到 `"2"`）；单人世界、局域网主机不受影响 |
| 升级方式 | 直接用新 jar 替换旧 jar 即可 |

## 下载

| 加载器 | MC 版本 | 文件 |
|---|---|---|
| Forge | 1.20 / 1.20.1 | `maid_file_manager-forge-1.20.1-1.6.4.jar` |
| NeoForge | 1.21 / 1.21.1 | `maid_file_manager-neoforge-1.21.1-1.6.4.jar` |
| Fabric | 1.20 / 1.20.1 | `maid_file_manager-fabric-1.20.1-1.6.4.jar` |
| Fabric | 1.21 / 1.21.1 | `maid_file_manager-fabric-1.21.1-1.6.4.jar` |

## 已知问题

- 服务端 `/maidfile` 命令回执里的自定义模型名仍显示内部短 ID —— 车万女仆服务端模型表只登记它认识的模型包；**客户端界面已正常显示中文名**
- 极少数极端分辨率下的布局问题（仅原版 GUI 缩放下限附近可达）按低优先级保留

---

*Code and docs are MIT licensed. The UI theme song《与酒狐的旅行》is not covered by MIT — all rights reserved, see the Music Notice.*
*代码与文档遵循 MIT 许可证；界面背景音乐《与酒狐的旅行》不适用 MIT，保留所有权利，详见《音乐版权声明》。*