ComboLite
🚀 为 Jetpack Compose 打造的新一代安卓插件化框架。一个现代、稳定、灵活的插件化解决方案。核心特性：原生Compose支持 | 100%官方API | 0 Hook & 0 反射 | 去中心化架构
Install / Use
/learn @lnzz123/ComboLiteREADME
<details> <summary>📚 <b>目录 (Table of Contents)</b></summary> </details>
🤔 为什么选择 ComboLite？
随着 Android 生态的演进，诞生于 View 时代的插件化框架已显得力不从心。它们或已停止维护，或严重依赖充满风险的 非公开API (Hook与反射)，在面临系统频繁更新时，兼容性问题频发，接入和维护成本极高。
ComboLite 的诞生，正是为了终结这一困境。 我们回归官方、拥抱简单，以完全公开的 API 为基石，实现了 *
0 Hook、0 反射* 的纯净架构，从根本上保证了框架的极致稳定与长远兼容性。
| 示例插件页 | 示例插件页 | 示例插件页 |
|:-------------------------:|:-------------------------:|:-------------------------:|
| 
| 
| 
|
| 安全校验机制 | 安全校验机制 | 异常处理机制 |
|:-------------------------:|:-------------------------:|:-------------------------:|
| 
| 
| 
|
🔗 下载示例App: https://github.com/lnzz123/ComboLite/tree/master/app/release/app-release.apk
<img src="image/preview.gif" width="250" alt="核心功能演示"/>(说明：插件 APK 托管于 GitHub，若下载缓慢或失败，请尝试开启 VPN。)
✨ 核心特性
ComboLite 的众多优势归纳为四大核心支柱，它们共同构成了框架的独特竞争力。
🚀 极致开发体验 (Developer Experience)
- 源码级无缝调试：通过配套 Gradle 插件，插件模块可在开发时自动集成进宿主，实现与原生模块完全一致的断点调试体验。彻底告别传统插件开发繁琐的“打包-安装-运行”循环，大幅提升开发迭代效率。
- 为 Compose 而生：原生为 Jetpack Compose 设计，完美拥抱现代 Android UI 工具包。
- 拥抱现代技术栈：深度集成 Kotlin Coroutines, Flow, Koin 等，让您在插件开发中也能享受最前沿的技术栈。
🛡️ 企业级稳定性与安全 (Stability & Security)
- 绝对稳定的基石：0 Hook & 0 反射：完全基于 Android 官方公开 API 构建，从根本上保证了框架的极致稳定与长远兼容性，让您彻底告别因系统升级导致的兼容性噩梦。
- 精细化权限管控：通过
@RequiresPermission注解实现对核心 API 的安全分级。高权限操作（如setPluginEnabled）仅限宿主签名的插件调用 (PermissionLevel.HOST)；部分操作则限制为插件对自身的管理 (PermissionLevel.SELF)，为框架构建了坚实的安全防线。 - 灵活的校验策略：提供
Strict(严格同签)、UserGrant(用户授权)、Insecure(不校验) 等多种签名校验策略，允许宿主根据业务场景，在安全性与开放性之间做出最合适的选择。 - 崩溃熔断与自愈：内置强大的异常处理器，能自动隔离并禁用崩溃的插件，防止应用陷入无限重启。同时提供友好的错误提示 UI 和精细化的回调机制，最大限度保障宿主应用的健壮性。
🏗️ 灵活的动态化架构 (Flexible Architecture)
- 去中心化设计：打破传统“宿主-插件”的强中心化模式，任何插件都可拥有管理其他插件的能力。轻松实现“插件商店”、“按需下载”、“插件自更新”等高级动态化功能。
- “空壳”宿主支持：支持将宿主 App 极致轻量化，所有业务功能和 UI 均由插件动态提供，为模块化解耦和团队协作开发提供了终极方案。
- 智能依赖解析：插件间的依赖关系无需预先配置，框架会在运行时自动发现并构建依赖图。热更新核心插件时，所有依赖它的上游插件均会自动链式重启，确保依赖的绝对一致性。
⚡ 高性能核心 (High-Performance Core)
- O(1) 类查找：通过建立全局类索引，实现了
O(1)时间复杂度的跨插件类查找，无论应用规模多庞大，类查找都能瞬间完成。 - 透明化资源管理：所有插件的资源会被动态合并，开发者可以像访问宿主自身资源一样，透明地访问所有已加载插件的资源，无需关心其来源。
- Service 实例池：支持将同一个插件
Service类启动为多个相互隔离的实例，为并行任务处理（如下载管理、多路视频流）等复杂场景提供了强大的支持。
🏗️ 架构概览
ComboLite 采用简洁而强大的微核设计，通过分层架构实现高度的内聚和解耦，逻辑清晰，易于扩展。
graph TD
subgraph " "
direction LR
A[宿主应用<br>Host App]
P[插件应用<br>Plugin Apps]
end
subgraph "框架接口层 (Framework API Layer)"
direction LR
IPlugin["插件接口<br>(IPluginActivity, IPluginService...)"]
PluginManagerAPI["PluginManager API"]
BaseClasses["组件基类<br>(BasePluginActivity, BaseHostService...)"]
end
subgraph "核心服务层 (Core Service Layer)"
direction LR
LifecycleManager[生命周期管理<br>PluginLifecycleManager]
InstallerManager[安装与解析<br>InstallerManager]
ResourceManager[资源管理<br>PluginResourcesManager]
end
subgraph "运行时 & 安全层 (Runtime & Security Layer)"
direction LR
Loader["类加载与依赖<br>(PluginClassLoader, DependencyManager)"]
Proxy["组件代理调度<br>ProxyManager"]
Security["安全体系<br>(权限, 签名, 授权, 异常)"]
end
subgraph " "
Android[Android 系统 & ART 虚拟机]
end
A & P --> PluginManagerAPI & IPlugin & BaseClasses
PluginManagerAPI & IPlugin & BaseClasses --> LifecycleManager & InstallerManager & ResourceManager
LifecycleManager & InstallerManager & ResourceManager --> Loader & Proxy & Security
Loader & Proxy & Security --> Android
🚀 快速开始 (Getting Started)
ComboLite 已发布至 Maven Central，您可以像集成任何标准库一样轻松地将其引入项目。
第 1 步: 定义项目依赖 (libs.versions.toml)
我们强烈建议使用 Version Catalog (gradle/libs.versions.toml) 来统一管理依赖。
# in gradle/libs.versions.toml
[versions]
# ...
combolite = "2.0.0" # 建议使用最新稳定版
combolite-aar2apk = "1.1.0" # 建议使用最新稳定版
[libraries]
# ...
combolite-core = { group = "io.github.lnzz123", name = "combolite-core", version.ref = "combolite" }
[plugins]
# ...
combolite-aar2apk = { id = "io.github.lnzz123.combolite-aar2apk", version.ref = "combolite-aar2apk" }
第 2 步: 全局插件配置 (项目根 build.gradle.kts)
在项目根目录的 build.gradle.kts 中，应用插件并进行全局配置。
// in your project's root /build.gradle.kts
plugins {
alias(libs.plugins.combolite.aar2apk)
}
// 在此声明所有插件模块，并配置打包策略与签名信息
aar2apk {
modules {
module(":sample-plugin:common")
module(":sample-plugin:home")
// ... 添加您所有的插件模块
}
signing {
keystorePath.set(rootProject.file("your_keystore.jks").absolutePath)
keystorePassword.set("your_password")
keyAlias.set("your_alias")
keyPassword.set("your_password")
}
}
第 3 步: 宿主 App 配置 (:app/build.gradle.kts)
在宿主 App 的 build.gradle.kts 中，添加核心库并配置开发时的自动集成。
// in your :app/build.gradle.kts
plugins {
// ...
}
// 配置插件自动集成功能，用于源码无缝调试
packagePlugins {
// 启用后，上述声明的插件将在构建时自动打包进宿主 assets
enabled.set(true)
buildType.set(PackageBuildType.DEBUG) // 或 RELEASE
pluginsDir.set("debug_plugins") // 插件在 assets 内的存放目录
}
dependencies {
implementation(libs.combolite.core)
// ...
}
第 4 步: 插件模块配置 (e.g. :sample-plugin:home)
在您的插件 Library 模块中，使用 compileOnly 依赖核心库。
// in your :sample-plugin:home/build.gradle.kts
dependencies {
// 插件模块必须使用 compileOnly，因为框架由宿主在运行时提供
compileOnly(libs.combolite.core)
// ...
}
恭喜您，集成完毕！ 您的项目现在已经具备了 ComboLite 插件化框架的全部能力。
📚 接下来做什么？
环境已经搭建完毕，现在我们强烈建议您阅读以下文档，开始您的插件化开发之旅：
- [必读] 快速开始: 从零到一，构建并运行你的第一个插件。
- [核心] 插件打包指南: 深入了解
aar2apk插件，精通两种打包策略。 - [进阶] 核心 API 用法: 掌握
PluginManager的所有核心功能。 - [进阶] 四大组件指南: 学习如何在插件中使用 Activity, Service, BroadcastReceiver, ContentProvider。
- [原理] 架构与设计: 探索 ComboLite 的内部工作机制。
🆚 框架对比与技术选型
ComboLite 在设计之初，充分借鉴了前辈们的经验，并针对现代 Android 开发的痛点进行了革新。
| 对比维度 | ComboLite (本项目) | Shadow (腾讯) | RePlugin (360) | 经典 Hook 方案 (VirtualAPK 等) | Google Play Feature Delivery |
|:-----------------------|:---------------------------------------------|:----------------------------------|:-------------------------------------|:-----------------------------|:-------------------------------|
| 核心原理 | ✅ 官方公开 API + 代理模式 | 编译期代码重写 + 运行时委托 | ClassLoader Hook + 部分系统Hook | ❌ 重度 Hook 系统服务 (AMS/PMS) | ✅ 系统级原生支持 |
| 系统兼容性 | 🥇 极高，无非公开 API 调用，天然适配 Android 7.0 - 16+ | 🥈 较高，绕开了大部分系统限制 | 🥉 中等，对 ClassLoader 的修改在新系统上存在风险 | 💥 低，对系统版本敏感，新系统上易失效 | 🥇 极高，官方方案 |
| Jetpack Compose 支持 | ✅ 原生支持，核心设计目标 | ❌ 不支持 | ❌ 不支持 | ❌ 不支持 | ✅ 原生支持 |
| 接入与使用成本 | ✨ 极低，微量核心代码，对项目几乎无侵入 | ⚠️ 高，依赖深度定制的 Gradle 插件，构建流程复杂 | ⚠️ 较高，需理解其复杂的组件生命周期管理 | ⚠️ 较高，需继承特定基类，配置繁琐 | ✨ 极低，官方工具链原生支持 |
| 社区活跃度 | 🚀 活跃开发中 | ⚠️ 维护放缓 (约2022年后) | ❌ 基本停滞 (约2020年后) | ❌ 已停滞 | 🚀 Google 官方持续迭代 |
| 主要优势 | 极致稳定、现代技术栈、开发体验好、去中心化架构 | 设计思想精巧，Activity 兼容性好 | 功能全面，曾有大规模验证 | 特定版本下功能强大完备 | 稳定可靠，Google Play 生态集成 |
| 主要权衡 | 代理模式对部分冷门 launchMode 支持受限 | 学习曲线陡峭，构建系统黑盒，已不兼容新版AGP | 侵入性较强，兼容性问题随系统升级增多 | 稳定性差，已不适用于现代开发 | 非热更新，必须通过应用商店发布，无法加载本地 APK |
-
对比 Hook 方案 (如 VirtualAPK / DroidPlugin)
- 它们: 通过 Hook 系统核心服务 (AMS/PMS) 来“欺骗”系统
