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

Mod Name: Maid File Manager
Chinese Alias: 车万女仆档案（迁移）管理器
Parent Mod: TLM (Touhou Little Maid)
Author: zgxhzhr (Bilibili: 逐光星火-执火人)
License: MIT
Source Code: https://github.com/zgxhzhr/MaidFileManager

Keywords: Touhou Little Maid, TLM, maid migration, cross-version transfer, maid export, maid import, world transfer, server migration, maid backup, maid data manager, addon data migration SPI, 车万女仆, 女仆迁移, 跨版本转移, 女仆导出, 女仆导入, 整合包转移, 女仆数据管理, 附属数据迁移, 万法皆通, All Methods, Fabric, Forge, NeoForge.

Maid File Manager is an addon for Touhou Little Maid with one core purpose: to let you take your maid with you wherever you go.

Whether you are switching modpacks and starting fresh, or bringing your single-player maid to a multiplayer server, this mod allows you to freely transfer maid data across 1.20 / 1.20.1 / 1.21 / 1.21.1, with full support for Forge, NeoForge, and Fabric.

Note: Fabric versions are based on community unofficial ports of TLM, not officially supported by the Touhou Little Maid mod itself. If you encounter issues on Fabric, please first confirm whether they are caused by the port itself.

Search keywords: Touhou Little Maid addon, maid cross-version transfer, maid world migration, maid export import, TLM maid backup, maid data migration tool, addon migration API, 车万女仆附属模组, 女仆跨版本迁移, 女仆跨存档转移, 女仆导出导入, 女仆数据迁移, 附属模组数据迁移, 换整合包保留女仆, 万法皆通兼容.

Why do you need this mod?

Transferring a maid is far more complicated than it seems. You might think just copy the entity data, but a maid's data — and her "memories" — are actually scattered across at least four unrelated places:

- Entity NBT (inside world save): Model ID, tasks, 4 equipment sets, favor/experience, YSM data, kill records, chess stats, AI chat history. Can travel with the maid? Yes, but only within the same world, and copying it raw means the same entity UUID collides in the destination world.
- File backups (maid_backups): Backup files organized by owner UUID. Can travel with the maid? Possibly, but the directory structure is hard-tied to the owner UUID. Change worlds or servers, the player UUID changes, and the backups become unreadable.
- Player data (Capability / DataAttachment): Maid count, AI token quota. Can travel with the maid? No — completely independent from the maid, so nothing on the maid's side can pull it along.
- Addon storage (independent SavedData / Capability / external databases): This is the invisible part. Many maid addons keep their own values and "memories" OUTSIDE the entity NBT — oath/bond lock flags, mood and affinity values, ability unlocks, favor counters, custom event records — and associate them with the maid purely by her UUID. Copying the entity carries not a single byte of it; in the new world the addon sees a total stranger with a blank slate. There is no common channel for addons to migrate this data, each addon would need its own solution.

This means:
- There is no one-click export/import tool in the base mod.
- Owner UUID is hard-linked. Moving to a new world or server means the maid becomes ownerless.
- There is no official cross-server transfer channel.
- Cross-version migration is risky due to major refactors between 1.20 and 1.21.
- Addon-raised stats and memories are stranded even if you copy the entity by hand.

This mod was created precisely because the base mod makes it so difficult to take your maid with you — and as of v1.4.0 it also offers a standard migration API (SPI) so addon authors can bring their own data along with one registration.

Keywords: maid transfer tool, cross-version maid migration, TLM maid backup manager, maid world transfer, server maid migration, maid addon migration API, 女仆跨服转移, 女仆备份管理, 整合包女仆迁移, 附属数据迁移接口, 1.20 to 1.21 maid transfer, Fabric maid mod.

What Maid File Manager can do?

Core Features:
- One-click Export: Press U in-game to open the GUI, select your maid, and export her data with one click.
- One-click Import: Press U, choose a file, and restore your maid to the current world instantly.
- Batch Operations: Select multiple maids or files at once for bulk export or import, with per-file failure reasons listed in the summary.
- Open Export Folder: Open the maid_exports folder directly from the GUI for easy file management.
- Cross-Version Migration: Seamless data transfer between versions 1.20, 1.20.1, 1.21, and 1.21.1.
- Duplicate Import Protection: the same maid cannot be imported twice; a clear message explains the rejection. Different players importing the same file on a server never conflict; re-importing works normally after the maid dies or is dismissed.
- No Residue: Uninstalling the mod does not affect maids that have already been imported.

New in v1.4.0:

Addon Migration API (SPI):
- New: A unified migration interface (MaidMigrationProvider + MaidMigrationRegistry). Addons register one provider to export/import their own maid-linked data; the .maid format carries it in the new extras field.
- Soft dependency: data from addons that are not installed is skipped silently; a failing addon never aborts the whole import.
- Old .maid files (v1 through v5) import without any conversion.

Duplicate Import Prevention:
- New: Imported entity UUID is derived deterministically from (source maid UUID + importing player UUID). Re-importing the same file as the same player is detected across all dimensions and unloaded chunks, and rejected with a specific reason.
- Multiplayer-safe: players sharing one .maid file each get their own maid; cross-world import and re-import after death/dismissal are unaffected.
- Note: a maid sealed inside a Soul Talisman is technically offline. Importing again will spawn, but the talisman can no longer release its maid (same UUID) — the talisman is not a duplication route.

Fairness and Stability Fixes:
- Imported maids' base health/attack unconditionally reset to TLM's vanilla values by favorability level (including the Tribulation bonus). Inflated base stats from global mob-health mods no longer carry across saves; legitimate bauble/affix bonuses are restored after spawn.
- Fixed full-health maids with HP baubles/affixes losing health after import (bounded ~1s per-tick recalibration window).

Existing Features (v1.3.0 and earlier):

Platform Support:
- Forge, NeoForge and Fabric official builds. Since v1.4.0 minor versions share one JAR per loader (see Supported Versions).

Potion Effect Migration:
- Cross-version potion effect migration. Export saves both vanilla NBT (active_effects) and cross-version normalized data; import auto-recovers based on target version.
- All Methods permanent buff protection. On servers with potion effects disabled, the 11 fixed permanent effects of All Methods structural maids (minecraft:regeneration/strength/resistance/speed, irons_spellbooks:vigor/blight/true_invisibility/abyssal_shroud, goety:save_effects/leeching, youkaishomecoming:native_god_bless) are preserved to the persistent tag by the dual condition "effect ID in whitelist AND Duration=-1".
- Pure effect judgment (whitelist + Duration=-1), no dependency on maid entity identity.

Accessory System:
- Supported accessory sources: Touhou Little Maid base mod + Touhou Little Maid All Methods accessories.
- All carried accessories are generated via new ItemStack, with no enchantments and no durability.
- Safely skips missing registered items in the target world without crashing.

Advancement System:
- Advancement import toggle, configurable whether to restore maid achievement progress.

Post-Import Cleanup:
- Delete source files after import toggle (disabled by default). Only deletes the batch confirmed successful by the server; failed files are retained as-is.

Multiplayer Features:
- Server host can configure whether to allow client-side maid import, accessories, advancements and potion effects (four toggles, auto-synced to clients).
- Server unified export: OP-only, grouped by player, exports each player's tamed maids within 128 blocks; never removes maids.
- Network deserialization capped at 16 MiB to prevent GZIP bombs.

Other Existing Features:
- AI chat persona and chat history import/export.
- Automatic filtering of accessories, inventory, main/off-hand items during export to prevent duplication exploits.
- Full support for Touhou Little Maid: All Methods.

Keywords: maid exporter, maid importer, TLM maid utility, Minecraft maid migration, Touhou maid backup, 女仆导出器, 女仆导入器, TLM女仆工具, 我的世界女仆迁移, Fabric女仆模组.

Supported Versions

Since v1.4.0, minor versions share one JAR per loader:

| Loader | Minecraft Versions | JAR |
|---|---|---|
| Forge | 1.20, 1.20.1 | maid_file_manager-forge-1.20.1 |
| NeoForge | 1.21.1 only | maid_file_manager-neoforge-1.21.1 |
| Fabric | 1.20, 1.20.1 | maid_file_manager-fabric-1.20.1 |
| Fabric | 1.21, 1.21.1 | maid_file_manager-fabric-1.21.1 |

Note: NeoForge for 1.21 release is not provided because NeoForge 21.0 and 21.1 are binary-incompatible; players on 1.21 please update to 1.21.1.

How to Use

- Export: Press U in-game, select your maid(s), and click Export.
- Import: Press U, choose a file, and click Import (optionally check "Delete source files after import").
- Open Folder: Click the Open Export Folder button in the GUI.
- Server Unified Export: Only visible to OPs. Click the "Unified Export All" button to export each player's tamed maids within 128 blocks, grouped by player.
- Exported files are saved in the maid_exports folder inside your Minecraft instance directory; server unified export saves to the server's maid_exports/<player name>/ folder.

Requirements

- TLM (Touhou Little Maid) must be installed.
- Corresponding Forge, NeoForge, or Fabric environment.
- To use the accessory carrying feature, Touhou Little Maid: All Methods is required.
- Fabric versions require the corresponding Fabric API.

Notes

- When importing across versions, ensure that the corresponding model exists on your client or the server; otherwise, the maid will appear as Reimu.
- Importing the same maid twice is intentionally rejected with an explicit message; there is no need for any workaround. A maid inside a Soul Talisman cannot be used to bypass this either — a second copy would block the talisman from releasing (same UUID).
- About server unified export scope: Many players think this feature can package all maids on the entire server at once, but it is constrained by design. On one hand, allowing players to directly view others' maid lists could lead to privilege escalation and export disputes; on the other hand, some maids may be in unloaded chunks, or sealed in Soul Talismans, photos, film rolls, and other containers, which unified aggregation cannot technically cover. Therefore, the actual scheme is: each player's exportable scope is limited to maids tamed by themselves within a 128-block radius; server unified export essentially aggregates each player's visible list and hands it to the server host—only when the player is online and the maid is within their loaded range can it be included in unified export. For modpack switches or disaster recovery backups, please notify players in advance to gather at the main city or bring their maids to themselves.
- Fixed in v1.1.1: Resolved the issue where the 20 bonus HP gained from Tribulation Transcendence would disappear after export/import.
- Fixed in v1.1.2: Resolved the issue where imported HP was capped at 20 and abnormal potion effects after import.
- Fixed in v1.2.0: Resolved the NBT export failure caused by the Anchoring Core from All Methods and the resulting blank maid issue.
- Fixed in v1.3.0: Potion effect migration — vanilla NBT and normalized dual data storage; All Methods permanent buffs no longer lost on potion-disabled servers.
- Fixed in v1.4.0: Full-health maids with HP baubles/affixes no longer lose health after import; duplicate imports are explicitly rejected with clear reasons (including batch failure details).
- Fabric versions are based on community unofficial ports of TLM. If you encounter issues on Fabric, please first confirm whether they are caused by the port itself.

Links

- Source Code: https://github.com/zgxhzhr/MaidFileManager
- Issue Tracker: https://github.com/zgxhzhr/MaidFileManager/issues
- Author's Bilibili: 逐光星火-执火人

Author: zgxhzhr
License: MIT

Keywords: Touhou Little Maid, TLM, 车万女仆, maid migration, cross-version, 跨版本, 女仆转移, maid export, maid import, 女仆导出, 女仆导入, world transfer, 跨存档, server migration, 服务器迁移, maid backup, 女仆备份, maid data manager, 女仆数据管理, addon migration SPI, 附属数据迁移, All Methods, 万法皆通, maid cross-world, 女仆跨服, Minecraft maid, 我的世界女仆, Forge maid mod, NeoForge maid mod, Fabric maid mod.

——————————————————————————————————————————————

模组名称：Maid File Manager
中文别称：车万女仆档案（迁移）管理器
归属模组：TLM 车万女仆 (Touhou Little Maid)
作者：zgxhzhr（B站：逐光星火-执火人）
开源协议：MIT
源码地址：https://github.com/zgxhzhr/MaidFileManager

搜索关键词：车万女仆，TLM，女仆迁移，跨版本转移，女仆导出，女仆导入，跨存档转移，服务器迁移，女仆备份，女仆数据管理，附属数据迁移，万法皆通，All Methods，整合包转移，女仆跨服，我的世界女仆，Forge女仆模组，NeoForge女仆模组，Fabric女仆模组。

Maid File Manager 是一款车万女仆的附属模组，核心功能只有一个：把你的女仆打包带走。

无论你是想换个整合包重新开始，还是把单机养成的女仆带到服务器里，这个模组都能让你在 1.20 / 1.20.1 / 1.21 / 1.21.1 之间自由迁移女仆数据，同时支持 Forge、NeoForge 与 Fabric 三大加载器。

注：Fabric 版本基于社区非官方移植的 TLM，非车万女仆本体官方支持。如有相关 Bug，请先确认是否为移植版自身问题。

为什么需要这个模组？

转移女仆这件事，远比想象中复杂。你可能以为把实体数据拷走就行，但实际上女仆的数据——以及她的各种"记忆"——至少分散在四个互不相干的地方：

- 实体 NBT（世界存档内）：模型 ID、任务、4 套物品栏、好感度/经验、YSM 数据、击杀记录、棋类战绩、AI 聊天历史。能随女仆走，但只限于同一存档内；而且直接原样拷贝，实体会带着同一个 UUID 到目标世界引发冲突。
- 文件备份（maid_backups）：按主人 UUID 归档的备份文件。可以拷贝，但目录结构与主人 UUID 硬绑定——换了存档或服务器，玩家 UUID 一变，这些备份就谁也读不出来了。
- 玩家数据（Capability / DataAttachment）：女仆数量、AI token 配额。完全独立于女仆，女仆侧没有任何办法把它一起带走。
- 附属存储（独立 SavedData / Capability / 外部数据库）：这是最隐形的一块。不少女仆附属会把自己的数值与"记忆"存在实体 NBT 之外——誓约/羁绊锁定值、心情与好感类数值、能力解锁、计数器、自定义事件记录等等——仅靠女仆 UUID 与女仆关联。只拷实体，这些数据一个字节都带不走；到了新世界，附属眼里就是一只白纸般的陌生女仆。而且这些数据没有统一迁移通道，每装一个附属都可能踩一次同样的坑。

这意味着：本体没有一键导出导入工具；主人 UUID 是硬关联，换世界就成了无主女仆；跨服没有官方通道；1.20 到 1.21 的大重构让跨版本迁移风险很高；哪怕你手工拷贝实体，附属养成的数值与记忆也会被丢下。

正因为本体在把女仆带走这件事上有这么多不方便的地方，才有了这个模组；v1.4.0 起更进一步，提供标准迁移接口（SPI），附属模组只需一次注册，就能让自己的数据随 .maid 一起搬家。

Maid File Manager 能做什么？

核心功能：
- 一键导出：游戏内按 U 键唤出面板，勾选女仆即可导出。
- 一键导入：同样按 U 键，选择文件即可还原到当前世界。
- 批量操作：同时处理多个女仆或文件，导入汇总中逐条列出失败原因。
- 一键打开导出文件夹：面板中直接打开 maid_exports 文件夹。
- 跨版本迁移：1.20 ↔ 1.20.1 ↔ 1.21 ↔ 1.21.1 数据互通。
- 防重复导入：同一位女仆无法导入两次，拒绝时给出明确原因；不同玩家在服务器导入同一文件互不冲突，女仆死亡或解散后可正常重新导入。
- 无残留：卸载模组不影响已导入的女仆。

v1.4.0 新增：

附属数据迁移接口（SPI）：
- 新增：统一迁移接口（MaidMigrationProvider + MaidMigrationRegistry），附属注册一个 provider 即可把自身的女仆关联数据导出/导入，.maid 文件新增 extras 字段承载。
- 软依赖：对应附属未安装时其数据静默跳过；单个附属导入失败不影响整体流程。
- 旧版 .maid 文件（v1～v5）无需任何转换即可导入。

防重复导入：
- 新增：导入实体 UUID 由「源女仆 UUID + 导入玩家 UUID」确定性派生。同一玩家重复导入同一文件时，全维度（含未加载区块的驯服女仆）均可识别并拦截，提示具体原因。
- 多人安全：多位玩家分享同一份 .maid 文件各得各的女仆；跨存档导入、死亡/解散后重新导入均不受影响。
- 注意：收入魂符的女仆在技术上处于离线状态，此时重复导入虽会生成副本，但魂符内女仆与副本同 UUID，魂符将无法再放出——魂符不是复制手段。

公平性与稳定性修复：
- 导入女仆的血量/攻击力基础值无条件回归车万女仆按好感等级（含渡劫加成）计算的白板值。全局生物血量倍率类模组抬升的虚高数值不再跨存档迁移；饰品、词条等合法加成在入世界后自动恢复。
- 修复满血且携带血量饰品/词条的女仆导入后掉血的问题（入世界后约 1 秒有界窗口逐 tick 校准）。

v1.3.0 及更早的已有功能：

平台支持：
- Forge、NeoForge、Fabric 均有正式构建。v1.4.0 起同一加载器的小版本合并为单个 jar（见支持版本表）。

药水效果迁移：
- 药水效果跨版本迁移，导出时同时保存原版 NBT（active_effects）与跨版本标准化数据，导入按目标版本自动恢复。
- 万法皆通药水效果保护：禁药水服务器下，万法皆通结构女仆的 11 种固定常驻效果（minecraft:regeneration/strength/resistance/speed、irons_spellbooks:vigor/blight/true_invisibility/abyssal_shroud、goety:save_effects/leeching、youkaishomecoming:native_god_bless）按「效果 ID 命中白名单 AND Duration=-1」双条件写入持久化标签保留。
- 纯效果判定（白名单 + Duration=-1），不依赖女仆实体身份。

饰品系统：
- 允许携带的饰品范围：车万女仆本体 + 车万女仆：万法皆通的饰品。
- 携带的饰品一律 new ItemStack 全新生成，无附魔无耐久。
- 目标世界缺注册物品时安全跳过，不崩溃。

进度系统：
- 进度导入开关，可配置是否还原女仆成就进度。

导入后清理：
- 导入后删除源文件开关（默认关闭），仅删除服务端确认生成成功的那批文件，失败文件原样保留。

联机功能：
- 联机宿主可配置是否允许客户端导入女仆、是否允许携带饰品、进度、药水效果（四项开关，客户端自动同步）。
- 服务端统一导出：仅 OP 可用，按玩家分组导出各自周围 128 格内驯服的女仆，只导出不移除。
- 网络反序列化上限 16 MiB，防 GZIP 炸弹。

其他已有功能：
- AI 聊天人设及历史记录导入导出。
- 导出时自动过滤饰品、背包、主副手，防止刷取。
- 完整支持车万女仆：万法皆通模组。

支持版本

v1.4.0 起同一加载器的小版本合并为单个 jar：

| 加载器 | Minecraft 版本 | jar |
|---|---|---|
| Forge | 1.20、1.20.1 | maid_file_manager-forge-1.20.1 |
| NeoForge | 仅 1.21.1 | maid_file_manager-neoforge-1.21.1 |
| Fabric | 1.20、1.20.1 | maid_file_manager-fabric-1.20.1 |
| Fabric | 1.21、1.21.1 | maid_file_manager-fabric-1.21.1 |

注：不提供 1.21 原版的 NeoForge 版——NeoForge 21.0 与 21.1 二进制不兼容，停留在 1.21 原版的玩家请更新到 1.21.1。

使用方法

- 导出：游戏内按 U 唤出面板 → 勾选女仆 → 点击导出。
- 导入：游戏内按 U 唤出面板 → 选择文件 → 点击导入（可勾选「导入后删除源文件」）。
- 打开文件夹：面板中点击「打开导出文件夹」按钮。
- 服务端统一导出：仅 OP 面板上可见「统一导出全员」按钮，点击后按玩家分组导出各自周围 128 格内驯服的女仆。
- 导出文件保存在版本文件夹下的 maid_exports 文件夹中；服务端统一导出保存在服务端 maid_exports/<玩家名>/ 文件夹。

前置要求

- 必须安装 车万女仆 (Touhou Little Maid)。
- 对应的 Forge、NeoForge 或 Fabric 环境。
- 如需使用饰品携带功能，需安装 车万女仆：万法皆通。
- Fabric 版本需对应 Fabric API。

注意事项

- 跨版本导入时，请确保本端或联机主端有对应模型，否则会变成博丽灵梦。
- 同一女仆重复导入是被有意拒绝的，并有明确提示，无需任何"变通方法"；把女仆收进魂符也无法绕过——再导入一份会导致魂符因 UUID 相同无法放出。
- 关于服务端统一导出的范围说明：很多玩家以为这个功能可以一次性打包整个服务器的所有女仆，但实际上它受设计约束。一方面，若允许玩家直接查看他人女仆列表，可能带来越权与导出纠纷；另一方面，部分女仆可能身处未加载区块，或被封进魂符、相片、胶卷等容器内，统一汇总在技术上无法覆盖这些场景。因此实际方案是：每位玩家能导出的范围仅限其半径 128 格以内、由自己驯服的女仆；服务端统一导出本质上就是把每位玩家各自能看到的这份列表汇总后交给联机宿主——只有玩家在线、且女仆在其加载范围内，才能被纳入统一导出。换整合包或灾备备份时，请提前通知玩家集中到主城或各自把女仆带到身边。
- v1.1.1 已修复：渡劫增加的 20 点血量上限在导入导出后消失的问题。
- v1.1.2 已修复：导入后血量上限被锁 20 及药水效果异常的问题。
- v1.2.0 已修复：万法皆通锚定核心导致导出 NBT 失败及由此导致的导入白板女仆问题。
- v1.3.0 已修复：药水效果迁移——原版 NBT 与标准化双份数据存储，跨版本恢复不再异常；万法皆通常驻 buff 在禁药水服务器下不再丢失。
- v1.4.0 已修复：满血带血量饰品/词条的女仆导入后掉血；重复导入（含批量导入）现在有明确的失败原因提示。
- Fabric 版本基于社区非官方移植，相关问题请先确认是否为移植版自身原因。

相关链接

- 源码：https://github.com/zgxhzhr/MaidFileManager
- 问题反馈：https://github.com/zgxhzhr/MaidFileManager/issues
- 作者 B站：逐光星火-执火人

Author：zgxhzhr
License：MIT

搜索关键词：车万女仆，TLM，女仆迁移，跨版本转移，女仆导出，女仆导入，跨存档转移，服务器迁移，女仆备份，女仆数据管理，附属数据迁移，万法皆通，All Methods，整合包转移，女仆跨服，我的世界女仆，Forge女仆模组，NeoForge女仆模组，Fabric女仆模组，女仆导出器，女仆导入器，TLM女仆工具，女仆数据迁移，附属迁移接口，换整合包保留女仆。