MCSync 2.0

MCSync 是面向 Minecraft 整合包的启动前 OTA 工具。它在正常模组初始化前检查发布清单，下载并校验变更，然后以事务方式更新客户端。

当前正式版本：2.0.3

运行环境：Java 21

当前清单：mods-v5.json 技术 Mod ID：mcmodsync（为兼容 1.9.x 保留）

更新日志 · Changelog · 文档导航 · English · 发布与运维 · 需求与安全边界 · 开发结构 · 旧版升级

MCSync 管理什么

默认可纳入发布项目：

• mods/
• resourcepacks/
• shaderpacks/
• kubejs/
• tacz/
• tlm_custom_pack/
• 经过明确选择的 config/ 与 defaultconfigs/
• 首次安装用的 options.txt
• 可选的 servers.dat

MCSync 不同步存档状态，也不应管理：

• saves/、世界区块、玩家数据和 SavedData
• Xaero/JourneyMap 探索数据
• 日志、崩溃报告、截图和缓存
• 启动器账户、Java 路径、内存参数和登录凭据
• 服务端密钥、令牌、白名单、OP 列表或私有地址

启动流程

1. MCSync 读取本地 modsync.properties。
2. 获取并严格解析 mods-v5.json；云端不可用时保留本地上次正常状态并放行启动。
3. 检查发布序号，拒绝降级和同序号分叉。
4. 显示新增推荐内容的选择界面。
5. 下载所选变更，并逐文件校验大小与 SHA-256。
6. 创建备份并执行一次原子事务；下载、校验或暂存失败不会改动正式文件。
7. 有 JAR 或启动期配置变化时退出，玩家重新启动后进入游戏。
8. 没有变化时继续正常加载 Minecraft。

MCSync 不承诺在 JVM 已加载 JAR 后热替换模组。涉及模组、KubeJS 启动脚本或启动期配置的更新都需要重启。

在 NeoForge 1.21.1 启动阶段，MCSync 会复用 NeoForge 的早期加载窗口显示检查、下载、缓存和哈希校验进度；不会在 Minecraft 尚未退出时再弹一个同步窗口。为适配 NeoForge 早期窗口的字体限制，这一阶段使用可显示的英文文件/状态标签，完整的中英文信息仍写入日志和 .modsync 状态文件。校验完成后，游戏窗口会显示退出倒计时、实际待提交文件量和预计耗时，并明确提醒玩家不要立刻重新启动。Minecraft 退出后，具备桌面图形环境的 Windows/Linux helper 会显示独立的置顶进度窗口，直到原子提交结束；手机端、Cacio 和无图形环境继续静默运行，并把进度写入启动器日志及 .modsync 状态文件。Minecraft 窗口内的推荐内容选择仍在可用的游戏界面阶段显示。

MCSync 自身使用独立的前置自更新入口 channel/stable/mcsync-bootstrap-v1.json。该文件与完整 mods-v5.json 同目录，由发布工具自动生成；客户端在解析任何玩法文件、模组站或镜像来源之前先检查它。若更新器本体有变化，本轮只下载并双重验证新 MCSync，退出后原子替换当前 JAR 内容，下一次启动再处理完整 OTA，从而避免旧更新器被未来清单格式或下载策略卡死。云端入口临时失败时不会阻止现有客户端启动。

文件身份与上游匹配

文件内容是唯一可靠身份。

• 本地安装、v5 导入、备份和回滚以 SHA-256 为准。
• Modrinth 使用当前 JAR 的 SHA-1 定位固定文件元数据；客户端最终仍以清单中的 SHA-256 验收字节。
• CurseForge fingerprint/fileId 只用于锁定文件元数据，不是字节级证明；发布器不再重复下载每个候选 JAR，客户端下载后以大小与 SHA-256 复核。复核失败时保留旧文件并等待下次重试。
• 文件名、展示名称和版本字符串不用于证明某个下载候选与当前 JAR 字节相同；下载身份仍以锁定哈希为准。版本字符串只参与同 modId 的本地防降级判断，无法可靠比较时闭锁而不覆盖。
• 唯一 modId 只可在版本升级后继承描述、必选状态等编辑元数据。
• 继承元数据后仍会用当前 JAR 重新查询上游，旧下载坐标不会直接沿用。
• 官方、镜像、直链和本地托管下载最终都必须命中 v5 中锁定的大小与 SHA-256。

发布器会在导出阶段把 Modrinth/CurseForge 的固定版本坐标解析成与当前 JAR 哈希一致的文件 URL。玩家启动时只获取服务器统一发布的 v5 清单并核对本地文件；本地文件正确时不访问模组站，缺失或损坏时才按清单内已经固定的文件候选下载。旧 v5 清单若没有固定 Modrinth 文件 URL，客户端仅为兼容才回退查询版本元数据。

只有直接位于 mods/ 的 JAR 会查询 Modrinth、CurseForge 或其镜像。资源包、光影、KubeJS、配置、TACZ 和女仆模型包不会被误送到模组站匹配。

必须与推荐内容

• 必须：缺失或哈希错误时会尝试修复；云端、下载或平台故障会保留现状并放行启动，只有本地事务无法自动回滚时才阻止启动。
• 推荐：首次出现或推荐集合新增时在 Minecraft 窗口内选择，默认全选；取消后不会强制恢复。
• 资源包和光影包也可以设为可选，并支持一键全选或取消。
• 已从当前客户端删除的 Mod 在导入旧 v5 时不会被复活。
• 非本地托管 Mod 不会把本地可可靠识别的更高版本降级；同 modId 存在本地托管条目时以托管条目为准，冲突 JAR 先进入事务备份。
• 删除不兼容 Mod 必须发布新的 modRemovals OTA 声明，并至少锁定精确版本或 SHA-256。客户端不会因为 Mod 从新清单消失就删除它；命中项会先进入事务备份，提交失败自动回滚，未声明的用户 Mod 保留。
• modRemovals 要求 MCSync 2.0.1。全新 2.0.1 客户端包可直接使用；已有 2.0.0 用户的频道必须先发布一版不含删除声明、但包含必选 MCSync 2.0.1 的 bootstrap，再以上一版完整输出发布删除 OTA。发布器会硬阻止跳过这一步。1.9.x/1.6.x 网关直接携带当前升级器，不受该两阶段限制。

发布一个 v5 版本

1. 准备并完整测试一个客户端根目录。
2. 运行 java -jar MCSync-2.0.3.jar。
3. 在“发布项目”中选择客户端根目录。
4. 在“Mods”页检查必选/推荐、双语描述和上游匹配结果。
5. 在“同步范围”中确认要管理的目录。
6. 扫描会纳入同步范围中声明的 config/、defaultconfigs/ 与 configureddefaults/；凭据、身份、备份及运行态缓存按路径和内容黑名单跳过并在界面报告。所有配置文件及 options.txt 只在本地不存在时安装一次；后续玩法修复或资源包选择调整只能通过带前像和冲突策略的配置项级 OTA 修改指定键，其余玩家设置原样保留。配置操作只接受 phase: prelaunch；文件级 first-install 由范围策略和持久台账负责。resourcepacks/ 与 shaderpacks/ 同样只负责首次安装，玩家随后替换、修改或删除的内容不会被常规发布反复恢复。FancyMenu 的首装内容位于 config/fancymenu/，不是 fancymenu_data/ 的玩家运行态数据。
7. 若下一版确认某个 Mod 不兼容，在 Mods 页选择它并点击“从本版移除并生成 OTA 删除”，或在“Mod OTA 删除”页从上一版缺失项生成声明。发布源目录中的 JAR 不会被 GUI 删除；声明会写入下一版 mods-v5.json 并由客户端事务执行。

下载采用纯文件并发：最多 128 个文件工作线程，每个文件固定使用一条 HTTP 连接，不进行 Range 分段、分段槽位分配或目录重排。同一 SHA-256 的并发请求只执行一次实际下载。界面分别显示已完成文件数量和当前活动文件，最终始终按清单大小和 SHA-256 验收。 7. 如需服务器列表同步，选择经过测试的 servers.dat。 8. 在“验证与导出”中消除全部阻断项后导出。 9. 先上传不可变文件，再最后上传 mods-v5.json。

第一次发布时留空上一版基线，MCSync 会生成完整的 SHA-256 内容对象库。托管文件保存为 objects/sha256/<前两位>/<完整哈希>，发布序号只用于防降级，不再成为云端目录名；相同内容即使对应多个逻辑路径也只保存一次。每次发布另写入 manifests/<releaseId>.json 完整历史清单，并把相同内容复制到稳定入口。以后选择上一版完整输出、单个 v5 清单或 ZIP 时，只复用已验证的平台证据和已存在的哈希对象；差分 UPLOAD-PLAN.json 不能代替完整终态索引。输出根目录同时生成机器计划与内容等价的中英文指南。

客户端应用 schema-v5 发布时会校验完整终态清单，但只暂存、备份和写入实际变化的文件，不会因为发布序号更新而重写所有正确文件。Minecraft 退出前会显示预计提交文件数、数据量和耗时范围；该估算以实际写集合为基础，大量小文件或较慢磁盘可能超出范围。

重新发布时可以只在 Mods 页导入旧 mods-v5.json。它只继承可安全对应的模组元数据，不改变其他发布设置；随后按当前 JAR 重新计算哈希和匹配来源。

直接点击“扫描并识别升级”时，当前 mods/ 会作为权威集合重新建立 Mods 表格。唯一 modId 的新版 JAR 会替换旧行并继承必须/推荐、双语描述、作用端和平台限制；下载来源仍按新版 JAR 的哈希重新匹配。若同一 modId 同时存在多个不同 JAR/版本，GUI 会把所有相关行标为冲突并阻止导出。

推荐的云端布局

channel/stable/mods-v5.json
manifests/<releaseId>.json
objects/sha256/<前两位>/<完整SHA256>
server-list/serverlist.txt
server-list/servers.dat

旧 1.6.x、1.7 和 1.9.x 客户端使用的升级材料应继续留在它们原来的 URL。新 v5 目录不需要旁挂 v4 文件。参见旧版升级指南。

发布工作台的“远端与旧版升级”页提供两种方式：完整发布时勾选“生成永久升级入口”，会把 legacy/ 一起写入发布目录；已经完成 v5 发布时，可指定一个新的空目录并点击“仅生成旧版入口上传包”，它不会重新扫描客户端或重建对象库。独立包会生成 legacy-artifacts.json、SHA256SUMS.txt 以及中英文上传说明。上传后永久入口为：

<公开根地址>/legacy/1.9/mods-v4.txt
<公开根地址>/legacy/1.6/mods.txt

旧客户端从上述入口安装 MCSync 和配置引导；退出、完成替换并重新启动后，才会切换到 <公开根地址>/channel/stable/mods-v5.json。

最小客户端配置

manifest=https://files.example.com/minecraft/channel/stable/mods-v5.json
language=auto
strict=true
requireManifest=true
syncResourcePacks=false
syncServerList=false
connectTimeoutSeconds=15
requestTimeoutSeconds=300
fileOperationRetries=12

真实地址和凭据不得提交到公开源码仓库。

构建与测试

Windows PowerShell：

.\build.ps1

构建会运行完整测试并生成：

• out/MCSync-2.0.3.jar
• out/MCSync-2.0.3-source.zip
• 中文说明与示例配置

兼容性说明

产品名已经改为 MCSync，但以下技术入口为旧客户端升级保留：

• mcmodsync Mod ID
• modsync.properties
• .modsync/
• MCModSync-Config.jar
• v1-v4 清单解析
• 1.9.x 升级链

不要仅为统一命名而删除这些入口。

License

见 LICENSE。