Villoh/morphe-builder

Morphe Builder 会从 Google Play 下载官方的 APK splits，验证其完整性和签名证书，将它们合并，使用 [Morphe](https://github.com/MorpheApp/morphe-desktop) CLI 进行修补，对结果进行签名，并打包非 Root APK 以及确定性的 Magisk/KernelSU 模块。 每个应用、架构、补丁来源和工具版本都在一个单独的 TOML 文件中声明，因此 fork 仓库可以在 CI 中构建自己的发布矩阵，而无需修改 Python 代码。任何不受信任的内容都不会被发布：在 manifest 覆盖率、哈希值、包名、版本、ABI 和签名者全部通过验证之前，下载内容将保留在临时目录中，并且每个发布的集合都带有确定性的出处记录。 Google Play 交付使用来自 PyPI 且固定版本的 [`goopdl`](https://github.com/Villoh/goopdl)，并带有已验证的 `direct`、`archive`、APKMirror 和 Uptodown 回退机制。 ## 要求 | 要求 | 版本 | 说明 | | --- | --- | --- | | [`Python`](https://www.python.org/) | 3.11–3.13 | 标准库 `tomllib` 最低要求 3.11 | | [`Java`](https://openjdk.org/) | 21+ | Morphe CLI、APKEditor 和 uber-apk-signer 必需 | | [`uv`](https://docs.astral.sh/uv/) | 最新 | 仅用于从源码进行开发安装 | 支持 Windows 和 Linux。有关平台限制，请参阅 [`docs/security.md`](docs/security.md)。 ## 功能 - **经过验证的下载**：在发布之前，会检查 Google manifest 覆盖率、安全路径、大小、SHA-256 哈希值、包名、版本、split 要求、ABI 和签名证书。 - **签名者锁定**：YouTube 和 YouTube Music 需要已知的 Google 签名者；任何应用都可以锁定自己的 `expected-signer` SHA-256。 - **提供者回退机制**：固定顺序 `google-play → direct → archive → apkmirror → uptodown`；完整性失败将作为终端错误停止，而不会转而使用后续提供者。 - **配置驱动的矩阵**：应用、架构、密度、补丁集和模块输出都在 TOML 中定义；没有硬编码的应用注册表。 - **针对每个应用的工具链**：每个应用都可以覆盖 Morphe CLI 版本、补丁来源和补丁版本，并按 `owner/repo@tag` 进行解析和缓存。 - **固定且带有哈希校验的工具**：Morphe CLI、patches、APKEditor 和 uber-apk-signer 都会被解析为确切的 tag，并在 `toolchain-provenance.json` 中记录资产哈希值。 - **非 Root APK 和模块**：确定性的 Magisk/KernelSU 模块，可安装匹配的官方包，在重启后依然有效，并从 Magisk 应用接收更新。 - **可重现的出处**：`provenance.json`、`build-summary.json`、`release-manifest.json` 和 `CHANGELOG.md` 会记录每个来源、版本和哈希值。 - **原子发布**：从不覆盖现有输出；失败的任务会删除其临时集合，且不会发布任何内容。 - **经过验证的 CI 发布**：每日更新检查会解析上游版本，跳过未更改的构建，验证每个构建产物，并附带 GitHub 产物证明。 - **设计上保证安全**：没有提交的凭据，没有缓存的 token 或 APK payload，带有已脱敏的错误输出。 ## 无需安装即可构建 将此仓库用作 GitHub 模板或 fork，编辑 [`morphe.toml`](morphe.toml)，然后从 Actions 中运行**手动验证构建**。GitHub runner 会安装工具链，构建经过验证的构建产物并上传它们，而无需在你的计算机上安装 Python、Java、`uv`、`pipx` 或 Morphe Builder。 从此处开始：[`docs/template-usage.md`](docs/template-usage.md)。 ## 安装 本地安装是可选的。Morphe Builder 依赖于来自 PyPI 且经过审查、精确固定版本的 [`goopdl`](https://pypi.org/project/goopdl/)。 全局工具安装： ``` uv tool install morphe-builder ``` 安装到现有环境中： ``` python -m pip install morphe-builder ``` 从源码进行开发安装： ``` git clone https://github.com/Villoh/morphe-builder cd morphe-builder uv sync uv run morphe-builder --help ``` ## 快速开始 ``` morphe-builder auth --arch arm64 morphe-builder tools MORPHE_KEYSTORE_PASSWORD=secret morphe-builder build morphe.toml \ --keystore /path/outside/repository/builder.p12 \ --output build ``` `auth` 将 Google Play 凭据存储在仓库之外，`tools` 会获取并为固定版本的 Java 工具链生成哈希，而 `build` 会根据 [`morphe.toml`](morphe.toml) 生成完整配置的矩阵。 ### Google Play 访问 可靠的直接下载需同时使用两个环境变量： | 变量 | 值 | | --- | --- | | `GOOPDL_ACCOUNT_EMAIL` | 专用的 Google 账户邮箱。 | | `GOOPDL_AAS_TOKEN` | 以 `aas_et/` 开头的持久 AAS token。 | 部分配置会安全失败并终止。如果没有其中任何一个值，`goopdl` 将使用匿名分发器，并在 Play 不可用时通过配置的已验证回退机制继续运行。 通过隔离的浏览器使用 `morphe-builder aastoken --browser` 生成 token。无计算机选项：[`goopdl-auth`](https://github.com/Villoh/goopdl-auth) 可帮助在本地不运行 Morphe Builder、`goopdl` 或 Termux 的情况下创建凭据。完整的本地和 CI 设置：[`docs/authentication.md`](docs/authentication.md)。请像对待密码一样对待 AAS token：切勿将其放入 TOML、argv、提交的文件、缓存、构建产物或日志中。 ### 其他环境变量 | 变量 | 使用方 | 用途 | | --- | --- | --- | | `MORPHE_KEYSTORE_PASSWORD` | `build` | 签名 keystore 密码。必需；切勿在 argv 中传入。 | | `GOOPDL_BROWSER` | `aastoken --browser` | 自动检测失败时使用的浏览器可执行文件。 | | `MORPHE_DISPENSER_URL` | `auth`, `download` | 自定义匿名分发器，仅在未配置 Google 账户时使用。 | | `MORPHE_MODULE_VERSION_CODE` | `build` | 单调递增的模块 `versionCode`。CI 会传入工作流运行编号。 | | `GITHUB_TOKEN` | `tools`, `build`, `list-patches` | 对 GitHub API 调用进行身份验证。绝不会发送给资产下载。 | | `HTTP_PROXY`, `HTTPS_PROXY` | `build` | 用于提供者下载的代理。 | | `XDG_CACHE_HOME`, `LOCALAPPDATA` | 所有缓存的命令 | 覆盖默认的缓存根目录。 | ## 配置 fork 仓库需要更改的所有内容都位于 [`morphe.toml`](morphe.toml) 中。无需修改任何 Python 代码即可构建不同的应用集合。 该文件包含一个带有默认 Morphe CLI 和补丁来源的 `[toolchain]` 表，随后是每个应用的一个按顺序排列的 `[[apps]]` 条目： ``` [toolchain] morphe-source = "MorpheApp/morphe-desktop" morphe-version = "latest" patches-source = "MorpheApp/morphe-patches" patches-version = "latest" # 两者默认均为 false。改为在需要时按应用启用。 include-universal-patches = false include-experimental-versions = false [[apps]] package = "com.google.android.youtube" name = "YouTube" slug = "youtube" patched-package = "app.morphe.android.youtube" version = "auto" build-mode = "apk" arch = "arm64-v8a" density = "xxhdpi" include-patches = ["GmsCore support", "SponsorBlock"] exclude-patches = [] [apps.patch-options."SponsorBlock"] toast-on-connection-error = true [apps.google-play] profile = "D2" country = "US" [apps.fallbacks] apkmirror = ["https://www.apkmirror.com/apk/google-inc/youtube/"] ``` 只有 `package` 和 `name` 是必需的。其他所有内容都有文档说明的默认值： | 设置 | 必需 | 省略时的默认值 | | --- | :---: | --- | | `package` | 是 | 经过验证的 Android 包名。 | | `name` | 是 | 用于发布说明和模块的显示名称。 | | `slug` | 否 | 将 `package` 中的点替换为连字符。控制输出、缓存和模块名称；必须唯一。 | | `patched-package` | 否 | 预期修补后包名不会更改。当 patches 重命名包名时设置它。 | | `version` | 否 | `auto`：每个选定 patch 支持的最高版本。也可接受 `latest` 或确切的版本名称。 | | `version-code` | 否 | 从版本名称解析。需要明确的 `version`；不允许与 `auto` 和 `latest` 一起使用。 | | `build-mode` | 否 | `apk`：仅限非 Root APK。使用 `module` 或 `both` 生成 Magisk/KernelSU 模块。 | | `arch` | 否 | `arm64-v8a`。也可以是 `arm-v7a`、`all` 或 `both`（两个独立的任务）。 | | `density` | 否 | 自动选择配置文件中唯一可用的 density split。 | | `include-patches` | 否 | 空：使用 patch bundle 的默认选择。 | | `exclude-patches` | 否 | 空：不从选择中移除任何内容。 | | `exclusive-patches` | 否 | 未设置。设置后，仅应用这些 patch；不能与 include/exclude 组合使用。 | | `patch-options` | 否 | Patch 默认值。仅限标量值，绝不进行 shell 插值。每个选项必须属于选定的 patch。 | | `expected-signer` | 否 | 未锁定：接受由提供者提供的有效签名者，并记录为 `unpinned signer accepted`。YouTube 和 YouTube Music 始终强制执行内置的 Google 签名者锁定。 | | `include-universal-patches` | 否 | 继承 `[toolchain]` (`false`)。为此应用包含 Universal patches，例如 `Change package name`。 | | `include-experimental-versions` | 否 | 继承 `[toolchain]` (`false`)。解析此应用时包含实验性版本。 | | `expect-corrupted-version-code` | 否 | `false`。针对上游修补 manifest 错误的明确解决方案：预期输出的 `versionCode` 为 `2147483647`，而不是官方代码。 | | `google-play.profile` | 否 | `goopdl` 选择配置文件。如果使用 `arch = "both"` 则留空，因为一个配置文件无法同时覆盖两个 ABI。 | | `google-play.country` | 否 | `goopdl` 账户区域。 | | `google-play.proxy` | 否 | 直接连接。 | | `google-play.dispenser` | 否 | `MORPHE_DISPENSER_URL`，或内置的公共分发器。 | | `fallbacks.*` | 否 | 空：Google Play 是唯一来源，因此 Play 失败会导致任务失败。 | | `patches-source`, `patches-version`, `cli-source`, `morphe-version` | 否 | `[toolchain]` 的值。 | `include-universal-patches` 和 `include-experimental-versions` 也可以在 `[toolchain]` 下设置，以为每个应用建立默认值。两者默认均为 `false`；应用级别的值将覆盖它们。Universal patches 不限制兼容版本的选择。仅包含 Universal patches 的选择将失败，因为它无法确定来源版本。 `expect-corrupted-version-code` 的适用范围是特意缩小的。当前的 `MorpheApp/morphe-patches` 在重新编译受影响的 manifest 时，会将修补后的 `versionCode` 更改为 `2147483647`。仅针对受影响的应用启用它；出处记录中会保留真实的下载版本代码。它同时适用于非 Root APK 和 Root 模块 payload。Root 模块始终禁用 `Change package name`，因为它们必须保留官方包名。 `[toolchain]` 表本身是可选的；省略它将使用 `latest` 的 `MorpheApp/morphe-desktop` 和 `MorpheApp/morphe-patches`。 解析非常严格：在任何下载开始之前，都会拒绝未知的 key、重复的包名、重复的 slug、不支持的值以及冲突的 patch 选择。运行 `morphe-builder list-patches morphe.toml` 可在提交更改之前查看每个应用将解析为哪个版本。 对于 CI 构建的发布版本，请为每个应用声明至少一个 `fallbacks` 条目。从托管的 runner 进行的匿名 Google Play 访问并不稳定，经过验证的 APKMirror 或 Uptodown 来源可以使构建在无凭据的情况下继续进行。 完整的字段参考、版本解析顺序和回退 URL 规则：[`docs/configuration.md`](docs/configuration.md)。 ## 用法 | 命令 | 用途 | | --- | --- | | `auth` | 对 Google Play 进行身份验证并在仓库之外缓存会话。 | | `download` | 下载并验证一个包的 splits 到输出中。 | | `tools` | 解析、下载并为固定版本的 Java 工具链生成哈希。 | | `list-patches` | 显示配置应用的 patch 兼容版本。 | | `build` | 运行完整配置的矩阵：下载、合并、patch、签名、验证、打包。 | | `verify` | 根据包名、架构和版本重新验证现有的 split 集合。 | | `clean` | 仅删除一次性工作缓存；保留受信任的集合和工具。 | ``` morphe-builder download com.example.app --arch arm64 --output downloads morphe-builder list-patches morphe.toml morphe-builder verify trusted/splits com.google.android.youtube \ --arch arm64 --version-name 21.04.223 ``` 所有命令均接受 `--json`（进度输出到 stderr，机器可读的结果输出到 stdout）。`--arch both` 会运行独立的 ARM64 和 ARMv7 任务。Keystore 密码来自 `MORPHE_KEYSTORE_PASSWORD`，绝不是 argv。退出代码根据失败类别保持稳定。 完整参考、退出代码表和缓存语义：[`docs/cli.md`](docs/cli.md)。 ## 文档 | 主题 | 文档 | | --- | --- | | 安装与首次构建 | [`docs/getting-started.md`](docs/getting-started.md) | | 无需本地安装的 GitHub 模板/fork | [`docs/template-usage.md`](docs/template-usage.md) | | 系统架构与信任边界 | [`docs/architecture.md`](docs/architecture.md) | | Google Play 身份验证 | [`docs/authentication.md`](docs/authentication.md) | | CLI 参考和退出代码 | [`docs/cli.md`](docs/cli.md) | | TOML 配置和版本解析 | [`docs/configuration.md`](docs/configuration.md) | | 工具链缓存、锁定和校验和 | [`docs/toolchain.md`](docs/toolchain.md) | | Google Play 交付和完整性检查 | [`docs/google-play-integrity.md`](docs/google-play-integrity.md) | | 提供者回退顺序 | [`docs/providers.md`](docs/providers.md) | | Split 选择和合并策略 | [`docs/merge.md`](docs/merge.md) | | 签名 APK 构建流程 | [`docs/build.md`](docs/build.md) | | Magisk/KernelSU 模块格式 | [`docs/modules.md`](docs/modules.md) | | 威胁模型和平台限制 | [`docs/security.md`](docs/security.md) | | CI、发布验证和发布流程 | [`docs/releases.md`](docs/releases.md) | | 第三方许可 | [`docs/THIRD_PARTY.md`](docs/THIRD_PARTY.md) | | 故障排除 | [`docs/troubleshooting.md`](docs/troubleshooting.md) | | 贡献者指南 | [`docs/contributing.md`](docs/contributing.md) | | 面向贡献者和智能体的仓库规则 | [`docs/rules/README.md`](docs/rules/README.md) | | 活跃路线图 | [`docs/roadmap/ROADMAP.md`](docs/roadmap/ROADMAP.md) | | 已完成的里程碑和证据 | [`docs/roadmap/COMPLETED.md`](docs/roadmap/COMPLETED.md) | ## 许可证 Morphe Builder 基于 [MIT 许可证](LICENSE) 发布。下载的 Morphe 工具仍然单独受 GPL-3.0 许可，且不包含在 Python 发行版中。请参阅 [`docs/THIRD_PARTY.md`](docs/THIRD_PARTY.md)。 ## 致谢 - [`MorpheApp/morphe-desktop`](https://github.com/MorpheApp/morphe-desktop) 和 [`MorpheApp/morphe-patches`](https://github.com/MorpheApp/morphe-patches)：此构建器调度的 patch CLI 和 patch bundle。Morphe 负责执行 patch；本项目仅准备经过验证的官方输入并打包输出。 - [`j-hc/revanced-magisk-module`](https://github.com/j-hc/revanced-magisk-module)：Magisk/KernelSU 模块方法和 CI 构建矩阵的现有技术。在 GPL-3.0 下作为设计上下文进行了审查；未复制任何代码。请参阅 [`docs/modules.md`](docs/modules.md)。 - [`REAndroid/APKEditor`](https://github.com/REAndroid/APKEditor) 和 [`patrickfav/uber-apk-signer`](https://github.com/patrickfav/uber-apk-signer)：split 合并和 APK 签名工具。 - [ReVanced](https://revanced.app/)：Morphe 构建所基于的 patch 生态系统；可以通过 `patches-source` 为每个应用选择兼容 ReVanced 的 patch bundle。

标签：APK构建, JS文件枚举, Python, Python安全, ReVanced, 云资产清单, 安卓, 无后门, 自动化CI/CD, 逆向工具, 逆向工程