Morphe Desktop 是一款用于给 Android 应用打补丁的开源命令行 + GUI 工具，本攻略将带你掌握它的补丁来源（Patch Source）管理：如何在 GitHub、GitLab 仓库与本地 .mpp 文件之间切换与组合多源加载，并理解来源列表中的加载优先级机制，让补丁应用又快又稳。

一、什么是补丁来源？

Morphe Desktop 本身只是"执行引擎"，真正决定能修补哪些应用、支持哪些功能的，是外部的补丁包（.mpp 文件）。补丁来源就是 Morphe 获取这些补丁包的渠道，内置四种类型：

对应的数据模型定义在 src/main/kotlin/app/morphe/gui/data/model/AppConfig.kt 中的PatchSource类，每个来源还带有enabled（是否启用）、usePreRelease（是否使用预发布版）等开关。

💡 默认来源指向官方MorpheApp/morphe-patches仓库，这一常量定义在 src/main/kotlin/app/morphe/engine/patches/RemotePatchSourceFactory.kt。

二、GUI 中查看与添加补丁来源

在 Expert（专家）模式下，窗口顶栏中央有一个来源胶囊（Sources pill），显示当前已加载补丁的版本号和"N sources"数量，每个来源用一颗彩色 LED 表示其解析到的发布渠道：

点击来源胶囊即可打开来源管理器（Source manager），支持添加、删除、刷新、拖拽排序：

添加远程来源时，你可以直接粘贴仓库地址；Morphe 会自动识别 GitHub、GitLab 域名、Release 标签链接，甚至 Pull Request 链接——解析逻辑在 src/main/kotlin/app/morphe/engine/patches/RemotePatchSourceFactory.kt 中，只写owner/repo简写形式时默认按 GitHub 处理。

选择来源之后进入发布版本选择界面，Morphe 会把仓库里的 Release 标注为Latest / Stable / Dev / Cached（已缓存），选中后点 Download 即可拉取：

三、加载优先级：列表顺序就是加载顺序

这是多源管理中最关键的规则：来源列表的上下顺序 = 加载优先级。

• 拖动来源前的把手即可调整位置，顺序会被持久化保存（见 src/main/kotlin/app/morphe/gui/data/repository/PatchSourceManager.kt 的reorderSources方法）。
• 列表靠前的来源先被加载。
• 如果两个来源包含同名类的补丁（两个 fork 版本时很常见），先加载的那个获胜。

👉 实用建议：把最信任的主来源（通常是官方来源）放在列表最上方，这是最安全的默认策略。

四、CLI 中指定补丁来源：-p/--patches参数速查

命令行模式下，用-p（即--patches）指定来源，它的威力比想象中更大：

1. 本地 .mpp 文件或目录

java -jar morphe-desktop-*-all.jar patch --patches patches-*.mpp your_app.apk java -jar morphe-desktop-*-all.jar patch --patches /path/to/patches/ your_app.apk

传目录时，Morphe 会自动定位其中最新的 .mpp。

2. 远程仓库（GitHub / GitLab）

java -jar morphe-desktop-*-all.jar patch --patches MorpheApp/morphe-patches your_app.apk

直接写owner/repo简写即可，无需完整 URL；也支持带 Release 标签的地址来锁定特定版本。

3. GitHub Pull Request 来源：传 PR 链接即可从 PR 的构建产物下载补丁。注意：这需要配置一个具有public_repo权限的GitHub PAT，可设置环境变量GITHUB_TOKEN，或在 GUI 的Settings → GitHub Personal Access Token中填写。

4. 一次组合多个来源：-p可以重复使用，每个-p开启一个新补丁包（bundle）：

java -jar morphe-desktop-*-all.jar patch -p patches-a.mpp -p patches-b.mpp your_app.apk

此时-e/-d/-O等按名称选择的参数只对紧随其后的那个 bundle生效，而--ei/--di索引选择则针对所有 bundle 合并后的全局编号。

5. 追新 Dev 版：加--prerelease会拉取最新预发布补丁；若仓库没有 Dev 版则自动回退到最新稳定版。

完整的参数说明可在 docs/documentation.md 的 CLI 章节查阅。

五、多源并行加载机制：源码视角

多个来源是怎么被"装进"一次补丁运行的？核心是 src/main/kotlin/app/morphe/engine/MultiSourceLoader.kt：

1. 并行加载：每个来源的.mpp会先生成一份临时影子副本，再由协程并发读取，互不阻塞；
2. 去重合并：完全相同的补丁只保留一份，同时记录它来自哪些来源（patchToSourceIds映射），方便 UI 展示归属；
3. 容错隔离：某个来源加载失败（版本不兼容、解析出错等）只会标记该来源为错误，不会拖垮其他来源；
4. 独立类加载器：多个补丁包使用互相隔离的类加载器，避免不同 fork 之间的类冲突。

远程来源还有一层缓存保护——src/main/kotlin/app/morphe/engine/patches/PatchRepository.kt 中：

• Release 列表内存缓存5 分钟（TTL），短时间内反复打开界面不会重复请求；
• 下载好的.mpp会写入磁盘缓存，下次运行直接复用（GUI 里显示为Cached标记）；
• 网络失败时自动回退到"过期的旧缓存"，尽量保证可用。

加载完成后，所有来源的补丁会在选择界面按 bundle 分组展示，你可以按来源逐组勾选、搜索和配置选项：

六、来源加载失败怎么办？

Morphe 不会在某个来源上无限转圈。一旦拉取或解析失败：

• 该来源的 LED 与渠道徽章变为红色；
• 界面顶部弹出错误横幅，明确写出是哪个来源、什么原因（仓库 404、网络超时、补丁包与 Patcher 版本不兼容等）；
• 其他来源照常加载，你可以立即修复（改 URL）或删除坏来源。

遇到失败界面大致如下：

常见排查思路：

1. 网络问题→ 稍后重试或更换来源；远程仓库地址拼写错误是最常见原因；
2. PR 来源失败→ 检查 PAT 是否已配置且未过期；
3. 版本不兼容→ 换用更新（或匹配当前 Morphe Patcher）的补丁包版本。

七、本地来源进阶：文件夹模式

如果你是补丁开发者，在Settings → Developer options中开启开发者选项后，本地来源可以指向一个文件夹而非单个文件——Morphe 每次都会自动加载其中最新的 .mpp，重新构建补丁后无需重新选文件，来源管理器右上角的刷新按钮还可随时重新扫描（*-sources.mpp、*-javadoc.mpp等构建副产物会被自动忽略）。

小结

掌握"来源类型 + 加载优先级 + 缓存机制"这三点，你就已经用好了 Morphe Desktop 的多源补丁体系。更多细节（含完整参数表）请参考官方文档：docs/documentation.md。