hoyo-env 0.1.0__tar.gz

hoyo_env-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - run: uv python install 3.12
+      - run: uv sync --extra dev --frozen
+      - run: uv run ruff check src tests
+      - run: uv run pytest -q

hoyo_env-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - run: uv python install 3.12
+      - run: uv sync --extra dev --frozen
+      - run: uv run ruff check src tests
+      - run: uv run pytest -q
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@v1.14.2
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

hoyo_env-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

hoyo_env-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qingrui Hu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hoyo_env-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.5
+Name: hoyo-env
+Version: 0.1.0
+Summary: 米哈游游戏版本管理器：安装、切换、启动 hk4e / hkrpg / nap / bh3。下载集中存放，未改动文件不重复占用空间。
+Project-URL: Homepage, https://github.com/invoker-bot/hoyo-env
+Project-URL: Repository, https://github.com/invoker-bot/hoyo-env
+Project-URL: Issues, https://github.com/invoker-bot/hoyo-env/issues
+Author-email: Qingrui Hu <invoker-bot@outlook.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bh3,cli,genshin,hk4e,hkrpg,hoyo,hoyo-env,mihoyo,nap,version-manager
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: pydantic>=2.7
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Requires-Dist: zstandard>=0.23
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hoyo
+
+PyPI 与 GitHub 上的项目名是 [hoyo-env](https://github.com/invoker-bot/hoyo-env)。`pip install hoyo-env` 之后，命令仍是 `hoyo`。
+
+米哈游 PC 游戏版本管理 CLI。支持：
+
+| ID | 游戏 | 别名 | 语音 |
+|----|------|------|------|
+| `hk4e` | 原神 | `genshin`、`yuanshen`、`gi` | 独立语音包 |
+| `hkrpg` | 崩坏：星穹铁道 | `hsr`、`starrail` | 含在本体 |
+| `nap` | 绝区零 | `zzz` | 独立语音包 |
+| `bh3` | 崩坏3 | `hi3`、`honkai3` | 含在本体 |
+
+各版本文件进**该游戏自己的内容寻址仓库**。下载和切换时：
+
+- 已经有的文件（按 SHA-256）**不再下载**
+- 工作副本用 **硬链接** 指向仓库，未改动文件**不复制**
+
+```text
+hoyo games
+hoyo versions hk4e
+hoyo install hk4e 7.1.0
+hoyo install hkrpg 4.6.0
+hoyo install nap 3.2.0 -l ja
+hoyo install bh3 9.1.0
+hoyo switch hk4e 7.1.0
+hoyo set language hk4e ja
+hoyo launch hk4e
+hoyo open hk4e
+```
+
+`genshin install 5.3.0` 对应 `hoyo install hk4e 5.3.0`。`genshin`、`hsr`、`zzz`、`hi3` 只是游戏 ID 的别名。
+
+远程清单来自 [HoyoFiles](https://hoyo-files.amarea.cn/)（`autopatch.amarea.cn`），文件块来自官方 CDN。有直链时优先直链，否则走 Sophon Chunk。清单是国服；`--channel os` 只改写 `config.ini` 里的 `game_biz` / `cps`，不会换成国际服客户端。
+
+下载：
+
+- **断点续传**：直链用 HTTP `Range` 接着 `.part` 写；Sophon chunk 缓存在 `cache/chunks/`
+- **进度条**：Rich 显示总体/单文件进度、速度、剩余时间
+- **并发**：默认同时下 4 个文件（asyncio + httpx），HTTP 连接上限 8。可用 `HOYO_FILE_CONCURRENCY` / `HOYO_HTTP_CONCURRENCY` 调整
+
+原神会写入 `audio_lang_*`，并在 Windows 上更新注册表里的 `deviceVoiceLanguageType` / `deviceLanguageType`。绝区零会另下所选语言的 `Audio_*_pkg_version`，但不会改注册表。星穹铁道和崩坏3没有这份独立语音清单。
+
+## 清单没有覆盖的资源
+
+`hoyo install` 只下载 `pkg_version` 里的文件；原神和绝区零再加所选语言的 `Audio_*_pkg_version`。这是国服安装包的一份快照，不是游戏进程之后还会向服务器请求的全部文件。装完以后，下面没进清单的分类，以及快照之后服务器上新增的热更，仍可能要由游戏自己去下。
+
+对照示例版本（原神 7.1.0、星穹铁道 4.6.0、绝区零 3.2.0、崩坏3 9.1.0）的 Sophon 分类：
+
+- **原神、星穹铁道的游戏资源**，以及**绝区零**清单里另列的主线、场景、活动、口型等分类，都已经写在 `pkg_version` 里，会一起下载。和对应 Sophon 分类相比，通常只少清单文件 `pkg_version` 自己。
+- **崩坏3的 AssetBundle 不在包里。** `pkg_version` 只是约 1.6 GB 的客户端。正文在另一个分类 `asb`（约 34 GB，`BH3_Data/StreamingAssets/Asb/`），当前不会下载。第一次启动需要让游戏向服务器拉取。
+- **星穹铁道的外置语音不在包里。** `Persistent/Audio/.../External*.pck` 属于 Sophon 的 `zh-cn` 等分类，不在本体 `pkg_version` 里，也没有 `Audio_*_pkg_version`。本体里已有的音频银行会下载；这套外置语音不会。进入游戏后仍可能向服务器下载。
+
+## 安装
+
+需要 Python 3.11+。
+
+```powershell
+pip install hoyo-env
+hoyo --help
+```
+
+从本仓库开发：
+
+```powershell
+pip install -e ".[dev]"
+```
+
+## 命令
+
+| 命令 | 作用 |
+|------|------|
+| `hoyo games` | 列出支持的游戏 |
+| `hoyo versions <game>` | 列出清单中的版本 |
+| `hoyo install <game> <version>` | 拉取缺失文件（含当前语言的语音包，若该游戏有独立语音包）；开始前检查磁盘空间 |
+| `hoyo install <game> <version> -l ja` | 安装时指定语音 |
+| `hoyo install <game> <version> --from-dir <path>` | 从本地游戏目录导入 |
+| `hoyo switch <game> <version>` | 把该游戏的当前目录切到该版本 |
+| `hoyo launch <game>` | 启动该游戏当前版本 |
+| `hoyo open <game>` | 在文件管理器中打开当前游戏目录 |
+| `hoyo set language <game> <zh\|en\|ja\|ko>` | 记录语音。原神会同时切文本语言 |
+| `hoyo set data-dir <path>` | 切换共享数据目录（省略参数则显示当前值） |
+| `hoyo list [game]` | 列出已安装版本 |
+| `hoyo status [game]` | 数据目录、当前版本、语音、仓库占用 |
+
+数据目录优先级：`--data-dir` > 环境变量 `HOYO_DATA_DIR` > `hoyo set data-dir` 写入的配置 > 系统默认。
+
+默认数据目录（未 `set` 过时）：
+
+- Windows：`%LOCALAPPDATA%\hoyo`
+- Linux/macOS：`$XDG_DATA_HOME/hoyo` 或 `~/.local/share/hoyo`
+
+持久配置（只存数据目录在哪）：
+
+- Windows：`%APPDATA%\hoyo\config.json`
+- Linux/macOS：`$XDG_CONFIG_HOME/hoyo/config.json` 或 `~/.config/hoyo/config.json`
+
+```powershell
+hoyo set data-dir D:\Games\hoyo
+hoyo set data-dir
+hoyo status
+```
+
+`set data-dir` **不会搬迁**已下载文件。换盘后请自行把旧目录拷到新位置，或重新 `install`。
+
+以前用 `genshin` 时，把旧数据目录里的内容移到新数据目录的 `hk4e` 子目录即可。旧清单没有 `game` 字段也能读。不要把旧的 `config.json` 直接拿来用：那里的 `data_dir` 指的是扁平目录，不是现在的共享根目录。
+
+## 磁盘布局
+
+```text
+<data-dir>/
+  hk4e/
+    blobs/ab/abcd…          # 内容寻址：每个唯一文件只存一份
+    manifests/<version>.json
+    versions/current/       # 唯一的游戏目录（硬链接工作副本）
+    state.json              # 该游戏的当前版本号
+    tmp/
+  hkrpg/
+  nap/
+  bh3/
+```
+
+同一个版本号可以同时存在于不同游戏里，仓库互不混用。每个游戏只有一个可运行目录 `versions/current`，路径里不带版本号；`hoyo switch` 在这个目录里原地换成目标版本。
+
+切换时会对比目标清单与现有目录：哈希相同且已是指向仓库的硬链接则跳过；只增删、替换有变化的路径。
+
+日志、截图一类可变文件会**复制**而不是硬链接，避免游戏写入污染共享仓库。
+
+极早的版本若只剩整包 zip、没有直链/Chunk，目前还不能按文件抽取。

hoyo_env-0.1.0/README.md

@@ -0,0 +1,129 @@
+# hoyo
+
+PyPI 与 GitHub 上的项目名是 [hoyo-env](https://github.com/invoker-bot/hoyo-env)。`pip install hoyo-env` 之后，命令仍是 `hoyo`。
+
+米哈游 PC 游戏版本管理 CLI。支持：
+
+| ID | 游戏 | 别名 | 语音 |
+|----|------|------|------|
+| `hk4e` | 原神 | `genshin`、`yuanshen`、`gi` | 独立语音包 |
+| `hkrpg` | 崩坏：星穹铁道 | `hsr`、`starrail` | 含在本体 |
+| `nap` | 绝区零 | `zzz` | 独立语音包 |
+| `bh3` | 崩坏3 | `hi3`、`honkai3` | 含在本体 |
+
+各版本文件进**该游戏自己的内容寻址仓库**。下载和切换时：
+
+- 已经有的文件（按 SHA-256）**不再下载**
+- 工作副本用 **硬链接** 指向仓库，未改动文件**不复制**
+
+```text
+hoyo games
+hoyo versions hk4e
+hoyo install hk4e 7.1.0
+hoyo install hkrpg 4.6.0
+hoyo install nap 3.2.0 -l ja
+hoyo install bh3 9.1.0
+hoyo switch hk4e 7.1.0
+hoyo set language hk4e ja
+hoyo launch hk4e
+hoyo open hk4e
+```
+
+`genshin install 5.3.0` 对应 `hoyo install hk4e 5.3.0`。`genshin`、`hsr`、`zzz`、`hi3` 只是游戏 ID 的别名。
+
+远程清单来自 [HoyoFiles](https://hoyo-files.amarea.cn/)（`autopatch.amarea.cn`），文件块来自官方 CDN。有直链时优先直链，否则走 Sophon Chunk。清单是国服；`--channel os` 只改写 `config.ini` 里的 `game_biz` / `cps`，不会换成国际服客户端。
+
+下载：
+
+- **断点续传**：直链用 HTTP `Range` 接着 `.part` 写；Sophon chunk 缓存在 `cache/chunks/`
+- **进度条**：Rich 显示总体/单文件进度、速度、剩余时间
+- **并发**：默认同时下 4 个文件（asyncio + httpx），HTTP 连接上限 8。可用 `HOYO_FILE_CONCURRENCY` / `HOYO_HTTP_CONCURRENCY` 调整
+
+原神会写入 `audio_lang_*`，并在 Windows 上更新注册表里的 `deviceVoiceLanguageType` / `deviceLanguageType`。绝区零会另下所选语言的 `Audio_*_pkg_version`，但不会改注册表。星穹铁道和崩坏3没有这份独立语音清单。
+
+## 清单没有覆盖的资源
+
+`hoyo install` 只下载 `pkg_version` 里的文件；原神和绝区零再加所选语言的 `Audio_*_pkg_version`。这是国服安装包的一份快照，不是游戏进程之后还会向服务器请求的全部文件。装完以后，下面没进清单的分类，以及快照之后服务器上新增的热更，仍可能要由游戏自己去下。
+
+对照示例版本（原神 7.1.0、星穹铁道 4.6.0、绝区零 3.2.0、崩坏3 9.1.0）的 Sophon 分类：
+
+- **原神、星穹铁道的游戏资源**，以及**绝区零**清单里另列的主线、场景、活动、口型等分类，都已经写在 `pkg_version` 里，会一起下载。和对应 Sophon 分类相比，通常只少清单文件 `pkg_version` 自己。
+- **崩坏3的 AssetBundle 不在包里。** `pkg_version` 只是约 1.6 GB 的客户端。正文在另一个分类 `asb`（约 34 GB，`BH3_Data/StreamingAssets/Asb/`），当前不会下载。第一次启动需要让游戏向服务器拉取。
+- **星穹铁道的外置语音不在包里。** `Persistent/Audio/.../External*.pck` 属于 Sophon 的 `zh-cn` 等分类，不在本体 `pkg_version` 里，也没有 `Audio_*_pkg_version`。本体里已有的音频银行会下载；这套外置语音不会。进入游戏后仍可能向服务器下载。
+
+## 安装
+
+需要 Python 3.11+。
+
+```powershell
+pip install hoyo-env
+hoyo --help
+```
+
+从本仓库开发：
+
+```powershell
+pip install -e ".[dev]"
+```
+
+## 命令
+
+| 命令 | 作用 |
+|------|------|
+| `hoyo games` | 列出支持的游戏 |
+| `hoyo versions <game>` | 列出清单中的版本 |
+| `hoyo install <game> <version>` | 拉取缺失文件（含当前语言的语音包，若该游戏有独立语音包）；开始前检查磁盘空间 |
+| `hoyo install <game> <version> -l ja` | 安装时指定语音 |
+| `hoyo install <game> <version> --from-dir <path>` | 从本地游戏目录导入 |
+| `hoyo switch <game> <version>` | 把该游戏的当前目录切到该版本 |
+| `hoyo launch <game>` | 启动该游戏当前版本 |
+| `hoyo open <game>` | 在文件管理器中打开当前游戏目录 |
+| `hoyo set language <game> <zh\|en\|ja\|ko>` | 记录语音。原神会同时切文本语言 |
+| `hoyo set data-dir <path>` | 切换共享数据目录（省略参数则显示当前值） |
+| `hoyo list [game]` | 列出已安装版本 |
+| `hoyo status [game]` | 数据目录、当前版本、语音、仓库占用 |
+
+数据目录优先级：`--data-dir` > 环境变量 `HOYO_DATA_DIR` > `hoyo set data-dir` 写入的配置 > 系统默认。
+
+默认数据目录（未 `set` 过时）：
+
+- Windows：`%LOCALAPPDATA%\hoyo`
+- Linux/macOS：`$XDG_DATA_HOME/hoyo` 或 `~/.local/share/hoyo`
+
+持久配置（只存数据目录在哪）：
+
+- Windows：`%APPDATA%\hoyo\config.json`
+- Linux/macOS：`$XDG_CONFIG_HOME/hoyo/config.json` 或 `~/.config/hoyo/config.json`
+
+```powershell
+hoyo set data-dir D:\Games\hoyo
+hoyo set data-dir
+hoyo status
+```
+
+`set data-dir` **不会搬迁**已下载文件。换盘后请自行把旧目录拷到新位置，或重新 `install`。
+
+以前用 `genshin` 时，把旧数据目录里的内容移到新数据目录的 `hk4e` 子目录即可。旧清单没有 `game` 字段也能读。不要把旧的 `config.json` 直接拿来用：那里的 `data_dir` 指的是扁平目录，不是现在的共享根目录。
+
+## 磁盘布局
+
+```text
+<data-dir>/
+  hk4e/
+    blobs/ab/abcd…          # 内容寻址：每个唯一文件只存一份
+    manifests/<version>.json
+    versions/current/       # 唯一的游戏目录（硬链接工作副本）
+    state.json              # 该游戏的当前版本号
+    tmp/
+  hkrpg/
+  nap/
+  bh3/
+```
+
+同一个版本号可以同时存在于不同游戏里，仓库互不混用。每个游戏只有一个可运行目录 `versions/current`，路径里不带版本号；`hoyo switch` 在这个目录里原地换成目标版本。
+
+切换时会对比目标清单与现有目录：哈希相同且已是指向仓库的硬链接则跳过；只增删、替换有变化的路径。
+
+日志、截图一类可变文件会**复制**而不是硬链接，避免游戏写入污染共享仓库。
+
+极早的版本若只剩整包 zip、没有直链/Chunk，目前还不能按文件抽取。

hoyo_env-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hoyo-env"
+version = "0.1.0"
+description = "米哈游游戏版本管理器：安装、切换、启动 hk4e / hkrpg / nap / bh3。下载集中存放，未改动文件不重复占用空间。"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Qingrui Hu", email = "invoker-bot@outlook.com" }]
+keywords = ["hoyo", "hoyo-env", "mihoyo", "hk4e", "hkrpg", "nap", "bh3", "genshin", "version-manager", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Games/Entertainment",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.7",
+    "pydantic-settings>=2.3",
+    "rich>=13",
+    "typer>=0.12",
+    "zstandard>=0.23",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+]
+
+[project.urls]
+Homepage = "https://github.com/invoker-bot/hoyo-env"
+Repository = "https://github.com/invoker-bot/hoyo-env"
+Issues = "https://github.com/invoker-bot/hoyo-env/issues"
+
+[project.scripts]
+hoyo = "hoyo.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hoyo"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

hoyo_env-0.1.0/src/hoyo/__init__.py

@@ -0,0 +1,10 @@
+"""米哈游游戏版本管理器。"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("hoyo-env")
+except PackageNotFoundError:  # pragma: no cover - editable/uninstalled fallback
+    __version__ = "0.1.0"
+
+__all__ = ["__version__"]

hoyo_env-0.1.0/src/hoyo/__main__.py

@@ -0,0 +1,4 @@
+from hoyo.cli import app
+
+if __name__ == "__main__":
+    app()