chore: migrate repository to standard knowledge base layout

tools/external/MCPlayerTransfer/docs/使用文档.md

@@ -0,0 +1,243 @@
+# MC Player Transfer 使用文档
+
+## 简介
+
+MC Player Transfer 是一个 Minecraft 基岩版角色转移工具，可以像泰拉瑞亚一样，将角色从一个世界完整转移到另一个世界。
+
+### 支持转移的数据
+
+- ✅ 背包全部物品
+- ✅ 末影箱全部物品
+- ✅ 潜影盒及其内部物品
+- ✅ 装备栏（头盔、胸甲、护腿、靴子）
+- ✅ 副手物品
+- ✅ 经验等级
+- ✅ 生命值 / 饥饿值
+- ✅ 玩家坐标位置
+- ✅ 游戏模式
+- ✅ 物品附魔、耐久度等 NBT 数据
+
+---
+
+## 环境要求
+
+- Python 3.8 或更高版本
+- Windows 10/11（WSL 环境）
+
+---
+
+## 安装步骤
+
+### 1. 安装 Python 依赖
+
+打开命令行，进入项目目录，执行：
+
+```bash
+pip install -r requirements.txt
+```
+
+或手动安装：
+
+```bash
+pip install amulet-core
+```
+
+### 2. 验证安装
+
+```bash
+python main.py
+```
+
+如果显示帮助信息，说明安装成功。
+
+---
+
+## 使用方法
+
+### 方法一：提取角色数据
+
+将 `.mcworld` 文件中的角色数据提取为独立的 `.dat` 文件。
+
+**步骤：**
+
+1. 将你的 `.mcworld` 存档文件放入 `input/` 文件夹
+
+2. 执行命令：
+   ```bash
+   python main.py extract "input/你的世界.mcworld"
+   ```
+
+3. 提取的角色数据会保存到 `output/` 文件夹，文件名格式：`世界名_时间戳.dat`
+
+**示例：**
+
+```bash
+python main.py extract "input/World (2).mcworld"
+```
+
+输出：
+```
+正在解压: input/World (2).mcworld
+找到数据库: /tmp/xxx/db
+
+✓ 提取成功!
+  世界名称: World (2)
+  数据大小: 50617 bytes
+  输出文件: output/World (2)_20251216_084843.dat
+```
+
+---
+
+### 方法二：导入角色数据
+
+将 `.dat` 角色文件导入到另一个 `.mcworld` 存档中。
+
+**步骤：**
+
+1. 准备好目标世界的 `.mcworld` 文件
+
+2. 准备好之前提取的 `.dat` 角色文件
+
+3. 执行命令：
+   ```bash
+   python main.py import "目标世界.mcworld" "output/角色数据.dat"
+   ```
+
+4. 生成的新存档文件名为 `目标世界_imported.mcworld`
+
+**示例：**
+
+```bash
+python main.py import "我的世界.mcworld" "output/World (2)_20251216_084843.dat"
+```
+
+输出：
+```
+读取角色数据: 50617 bytes
+正在解压: 我的世界.mcworld
+✓ 角色数据已写入
+正在打包: 我的世界_imported.mcworld
+
+✓ 导入成功!
+  输出文件: 我的世界_imported.mcworld
+```
+
+---
+
+## 完整使用流程示例
+
+### 场景：将角色从「生存世界」转移到「新世界」
+
+```bash
+# 第一步：提取生存世界的角色
+python main.py extract "input/生存世界.mcworld"
+
+# 第二步：导入到新世界
+python main.py import "input/新世界.mcworld" "output/生存世界_20251216_120000.dat"
+
+# 第三步：将生成的 新世界_imported.mcworld 导入游戏
+```
+
+---
+
+## 如何获取 .mcworld 文件
+
+### 方法一：从游戏导出
+
+1. 打开 Minecraft 基岩版
+2. 进入「设置」→「存储」
+3. 选择要导出的世界
+4. 点击「导出世界」
+5. 选择保存位置，得到 `.mcworld` 文件
+
+### 方法二：从存档文件夹打包
+
+Windows 存档位置：
+```
+C:\Users\用户名\AppData\Local\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\games\com.mojang\minecraftWorlds\
+```
+
+将整个世界文件夹压缩为 `.zip`，然后改后缀为 `.mcworld`。
+
+---
+
+## 如何导入 .mcworld 文件到游戏
+
+1. 双击 `.mcworld` 文件，游戏会自动导入
+2. 或者将文件拖入游戏窗口
+3. 或者手动解压到存档目录
+
+---
+
+## 项目目录结构
+
+```
+MCPlayerTransfer/
+├── main.py                 # 主程序入口
+├── requirements.txt        # Python 依赖
+├── README.md               # 简要说明
+├── src/                    # 源代码
+│   ├── __init__.py
+│   ├── extract_player.py   # 提取模块
+│   └── import_player.py    # 导入模块
+├── docs/                   # 文档
+│   └── 使用文档.md
+├── input/                  # 输入文件夹（放 .mcworld 文件）
+└── output/                 # 输出文件夹（生成 .dat 文件）
+```
+
+---
+
+## 常见问题
+
+### Q: 提示找不到 leveldb 模块？
+
+A: 执行 `pip install amulet-core`，这个包包含了所需的 leveldb 支持。
+
+### Q: 提示找不到本地玩家数据？
+
+A: 确保 `.mcworld` 文件是有效的基岩版存档，且曾经在单人模式下游玩过。
+
+### Q: 导入后角色位置不对？
+
+A: 角色数据包含坐标信息，导入后会保留原来的位置。如果新世界该位置是虚空，角色可能会掉落。建议先在新世界创建一个安全的出生点。
+
+### Q: 可以转移多人服务器的角色吗？
+
+A: 本工具只支持本地玩家（`~local_player`）。服务器玩家数据存储方式不同，暂不支持。
+
+### Q: 原存档会被修改吗？
+
+A: 不会。提取操作只读取数据，导入操作会生成新的 `_imported.mcworld` 文件，不修改原文件。
+
+---
+
+## 注意事项
+
+⚠️ **重要提醒：**
+
+1. **操作前务必备份存档**
+2. **关闭游戏后再进行操作**
+3. **导入会完全覆盖目标存档的本地玩家数据**
+4. **建议先在测试存档上验证**
+
+---
+
+## 技术原理
+
+Minecraft 基岩版使用 LevelDB 数据库存储世界数据。玩家数据存储在 key 为 `~local_player` 的条目中，格式为 NBT 二进制数据。
+
+本工具的工作原理：
+1. 解压 `.mcworld` 文件（本质是 ZIP 压缩包）
+2. 打开 `db/` 目录中的 LevelDB 数据库
+3. 读取或写入 `~local_player` 数据
+4. 重新打包为 `.mcworld` 文件
+
+---
+
+## 更新日志
+
+### v1.0.0 (2024-12-16)
+- 初始版本
+- 支持提取和导入本地玩家数据
+- 支持 .mcworld 文件格式