《崩坏：星穹铁道》国服客户端低版本 → 高版本更新器。
用官方 Sophon（chunk） 分发机制，把任意旧版本客户端升到官方当前版本；只用 Python 标准库 + 两个 pip 包，不需要 hpatchz / ldiff / SophonPatcher 等任何外部工具，游戏目录里也不需要预先放任何文件。
⚠️ 仅供学习与个人客户端维护使用。仓库不含任何游戏本体或官方资源，全部文件在运行时从官方 CDN 下载。请自行承担使用风险。
pip install protobuf zstandardPython 3.8+（开发环境为 3.14）。
| 文件 | 用途 |
|---|---|
sophon_update.py |
主程序：升级客户端（可交互、也可命令行） |
voice_pack.py |
只补充语音包（交互运行；测试服/精简客户端常用） |
manifest.proto / manifest_pb2.py |
Sophon 清单的 proto 定义与生成物（日常不用管） |
manifest_ldiff.proto / _pb2.py |
官方差分包清单定义（当前未使用，保留备用） |
gen_pb2.py |
改了 .proto 后才需要跑：重新生成 *_pb2.py（需 pip install grpcio-tools） |
最省事：直接运行，跟着提示走（不带参数就是交互模式）：
python sophon_update.py它会问三件事：客户端根目录（可直接把文件夹拖进窗口）→ 更新到哪个版本 → 更新哪些内容，然后先给你看要下载多少，确认了再动手。
也可以直接用命令行参数：
# 先看要下多少（只看不写，也不联网下大文件）
python sophon_update.py --gamedir "<客户端根目录>" --cn --dry
# ★中文版（推荐）：游戏资源(10054) + 中文语音(10055)，不装英/日/韩
python sophon_update.py --gamedir "<客户端根目录>" --cn
# 全部类别
python sophon_update.py --gamedir "<客户端根目录>"
# 预下载尚未开服的新版本（比正式版高一档，先下好等开服）
python sophon_update.py --gamedir "<客户端根目录>" --cn --branch predownload测试服、精简版客户端常常不带语音包，或者只有部分语言。这个工具直接从官方 CDN 把语音包拉下来写进去：
python voice_pack.py它会先显示客户端现有的语音包状态，然后依次问：要补哪些语言（中/英/日/韩/全部）→ 取哪个版本（已上线 / 预下载）→ 先预览还是直接下载。
也可以用命令行：
python voice_pack.py --gamedir "<客户端根目录>" --lang cn,jp --branch predownload --dry- 语音包会写到客户端的
StarRail_Data/Persistent/Audio/AudioPackage/Windows/<语言>/，和官方布局一致，所以测试服客户端同样适用。 - 单个语言约 11.5～14 GiB，四种全要约 52 GiB。工具会先算给你看再问你确认。
- 它用逐文件 md5 校验：本地已有的语音文件会跳过，只补缺失或损坏的（可中断、重跑接着补）。
语音包这里刻意不用「按版本号做清单比对」——测试服/精简版的版本号常与正式服不同，万一恰好相同，就会被误判成"语音包已存在"而不去补。
| 参数 | 说明 |
|---|---|
--gamedir |
要升级的客户端根目录（含 StarRail_Data\ 的那个文件夹，必填） |
--cn |
中文版模式：只处理 游戏资源(10054) + 中文语音(10055) |
--cat 10054 |
只处理单个类别（优先级高于 --cn） |
--branch predownload |
用官方预下载版本；默认 main = 已上线版本 |
--dry |
只统计体积，不下载不写文件 |
--verify |
强制逐文件 md5 校验（慢，会读整个客户端） |
--force |
跳过客户端根目录结构校验（确认目标目录特殊时才用） |
根目录必须填「含
StarRail_Data\的那个文件夹」本身。 填错本身不危险，但会被当场拦下：工具会从你给的路径一路向上扫到盘符根（拖进来的往往是深层子目录，如...\AudioPackage\Windows\Chinese(PRC)）、再向下扫几层，找出真正含StarRail_Data的目录并建议你改用——交互模式可一键接受，命令行模式直接报错并给出应填的路径（找不到候选就只报错、绝不乱猜；--force可跳过这套检查）。
新版本开服前请务必带上
--branch predownload：米哈游的新版本在开服前只存在于pre_download分支，而main还停在旧版本。少了这个参数，你以为在"补资源"，实际会把客户端升回旧版（工具检测到本地版本比目标新时会警告）。
跑完后工具会自动把 config.ini 的 game_version 写成目标版本；只在 --dry 之外会顺带询问是否清理 manifest 缓存。
| 类别 | 内容 |
|---|---|
| 10054 | 游戏资源（主体，必需） |
| 10055 / 10056 / 10057 / 10058 | 中 / 英 / 日 / 韩 语音 |
只升 10054 游戏就能进；语音包可选，缺了只影响对应语言的配音。
官方 Sophon 按 chunk 分发文件：
getGameBranches→ 拿到目标版本（如4.5.0）的package_id/password/branch/tag。getBuild→ 该版本所有类别的清单，每个文件含它的 chunk 列表、下载基址和 md5。- 每个文件由若干 chunk（zstd 压缩片段）组成，按各自
offset拼起来就是完整文件。
工具遍历清单，对「当前安装里缺失或内容不符」的文件：并发下载 chunk → zstd 解压 → 按偏移组装 → md5 校验 → 写回；已正确的直接跳过。所以删掉「过往资源」也不影响：缺什么就按目标版本清单从官方重建，不依赖本地旧文件。
官方同时给两套目标：main（已上线，能进游戏）和 pre_download（预下载，还没开服）。新版本开服前 main 停在上一版本，新版本只存在于 pre_download。工具默认走 main，因此默认只升到「已上线的最新版」；要提前拿新版就加 --branch predownload。
预下载装完要等官方开服才能进游戏；开服前启动器显示旧版本属正常。
- 只更新「缺失或变化」的文件，下载体积 ≈ 一次真实更新。
- 覆盖前会替换同名文件，建议先备份客户端；进游戏后若还提示补少量资源，交给官方启动器即可。
- 目标版本从官方接口实时读取，同一工具可反复用于后续升级（4.6→4.7、4.7→4.8…），开服自动生效，不用改代码。
- 程序按
hkrpg_cn国服写死（GAME_ID/LAUNCHER_ID/ 语音类别 id）。其它区服或其它米哈游游戏需改文件顶部这几个常量。 - 下载走官方 CDN，速度取决于你的网络；某些地区可能需要代理。
- 控制台回显在真终端下带配色（标题/关键数字/警告分色）；输出被重定向到文件或管道时自动退化为纯文本，不会混入 ANSI 转义码。
--dry默认只按文件大小判断，不读内容 —— 对「大小恰好相同、内容却是旧版」的文件会误判为已是最新。要看真实缺口请加--verify。- 清单比对不适合被改动过的客户端（用
--verify兜底）：若装过汉化 / MOD，被改过的文件会被判为「已是最新」而跳过。 - md5 校验失败的文件会被跳过，下次重跑仍判为「需要更新」而重新下载（不会误标为已完成）。
- 单个文件需整体放进内存（峰值 ≈ 该文件大小）。
manifest_ldiff.proto/manifest_ldiff_pb2.py是官方**差分包（hpatchz）**清单定义，当前主线不用；保留以备后续实现「只下差分补丁」的更省流方案。
MIT，见 LICENSE。仓库内 manifest_ldiff.proto 的注释保留了上游出处（DGP-Studio/Snap.Hutao，MIT）。