简体中文 | English

专为 Jetpack Compose 而生，100% 官方 API，0 Hook & 0 反射 的下一代 Android 插件化框架。
现代、稳定、灵活，助您轻松构建“万物皆可插拔”的动态化应用。

随着 Android 生态的演进，诞生于 View 时代的插件化框架已显得力不从心。它们或已停止维护，或严重依赖充满风险的 非公开API (Hook与反射)，在面临系统频繁更新时，兼容性问题频发，接入和维护成本极高。

ComboLite 的诞生，正是为了终结这一困境。 我们回归官方、拥抱简单，以完全公开的 API 为基石，实现了 * 0 Hook、0 反射* 的纯净架构，从根本上保证了框架的极致稳定与长远兼容性。

示例插件页	示例插件页	示例插件页

安全校验机制	安全校验机制	异常处理机制

🔗 下载示例App: https://github.com/lnzz123/ComboLite/tree/master/app/release/app-release.apk

(说明：插件 APK 托管于 GitHub，若下载缓慢或失败，请尝试开启 VPN。)

ComboLite 的众多优势归纳为四大核心支柱，它们共同构成了框架的独特竞争力。

• 源码级无缝调试：通过配套 Gradle 插件，插件模块可在开发时自动集成进宿主，实现与原生模块完全一致的断点调试体验。彻底告别传统插件开发繁琐的“打包-安装-运行”循环，大幅提升开发迭代效率。
• 为 Compose 而生：原生为 Jetpack Compose 设计，完美拥抱现代 Android UI 工具包。
• 拥抱现代技术栈：深度集成 Kotlin Coroutines, Flow, Koin 等，让您在插件开发中也能享受最前沿的技术栈。

• 绝对稳定的基石：0 Hook & 0 反射：完全基于 Android 官方公开 API 构建，从根本上保证了框架的极致稳定与长远兼容性，让您彻底告别因系统升级导致的兼容性噩梦。
• 精细化权限管控：通过 @RequiresPermission 注解实现对核心 API 的安全分级。高权限操作（如 setPluginEnabled）仅限宿主签名的插件调用 (PermissionLevel.HOST)；部分操作则限制为插件对自身的管理 (PermissionLevel.SELF)，为框架构建了坚实的安全防线。
• 灵活的校验策略：提供 Strict (严格同签)、UserGrant (用户授权)、Insecure (不校验) 等多种签名校验策略，允许宿主根据业务场景，在安全性与开放性之间做出最合适的选择。
• 崩溃熔断与自愈：内置强大的异常处理器，能自动隔离并禁用崩溃的插件，防止应用陷入无限重启。同时提供友好的错误提示 UI 和精细化的回调机制，最大限度保障宿主应用的健壮性。

• 去中心化设计：打破传统“宿主-插件”的强中心化模式，任何插件都可拥有管理其他插件的能力。轻松实现“插件商店”、“按需下载”、“插件自更新”等高级动态化功能。
• “空壳”宿主支持：支持将宿主 App 极致轻量化，所有业务功能和 UI 均由插件动态提供，为模块化解耦和团队协作开发提供了终极方案。
• 智能依赖解析：插件间的依赖关系无需预先配置，框架会在运行时自动发现并构建依赖图。热更新核心插件时，所有依赖它的上游插件均会自动链式重启，确保依赖的绝对一致性。

• 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

ComboLite 已发布至 Maven Central，您可以像集成任何标准库一样轻松地将其引入项目。

我们强烈建议使用 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" }

在项目根目录的 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")
    }
}

在宿主 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)
    // ...
}

在您的插件 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 开发的痛点进行了革新。

• 对比 Hook 方案 (如 VirtualAPK / DroidPlugin)

  • 它们: 通过 Hook 系统核心服务 (AMS/PMS) 来“欺骗”系统，功能强大但极其不稳定，随着系统版本迭代已基本失效，且均已停止维护。
  • 我们: 绝不使用 Hook。ComboLite 采用官方推荐的代理模式，虽然在某些极端 Activity 启动模式上自由度稍逊，但换来的是坚如磐石的稳定性，这是我们最重要的承诺。

• 对比编译期方案 (如 Shadow)

  • 它们: 设计精巧，通过编译期重写代码绕开 Hook，稳定性更高。但其构建系统复杂，学习曲线陡峭，且项目已放缓维护，对新技术栈（如 Compose）支持滞后。
  • 我们: 拥抱简单与现代。ComboLite 保持核心逻辑的清晰透明，与最新的 AGP/Gradle/Compose 工具链完美同步，让开发者能将精力聚焦于业务本身，而非复杂的框架底层。

• 对比 RePlugin (360)

  • 它们: 同样是业界经典，通过 Hook ClassLoader 实现功能，但在新版 Android 对非公开 API 限制愈发严格的今天，其稳定性面临挑战。项目也已基本停止维护，对 Compose 等新技术栈缺乏支持。
  • 我们: 选择面向未来的稳定路线。ComboLite 彻底规避了 Hook 带来的兼容性风险，并原生为 Jetpack Compose 设计，确保在现代技术栈下获得最佳的开发体验和长期维护性。

• 对比 Google Play Feature Delivery

  • 它们: 是一个应用分发方案，旨在减少初始安装包体积，所有模块更新仍需通过应用商店审核和下发，本质上是“冷分发”，无法实现真正的热更新。
  • 我们: 是一个纯粹的热更新框架。ComboLite 赋予 App 在运行时加载任意来源 APK 的能力，可以完全绕开应用商店进行功能迭代和 Bug 修复，这才是动态化的核心价值。

插件化技术没有绝对完美方案，选择即是取舍。ComboLite 的设计哲学是在保证 99% 主流场景的极致稳定与简洁性的前提下，审慎对待那 1% 的边缘场景。

总而言之，如果您正在开发一个面向未来的、使用 Jetpack Compose、且将长期稳定性和可维护性放在首位的项目，ComboLite 将是您的不二之- 选。

我们热切欢迎任何形式的贡献！无论是提交功能建议、报告 Bug、还是发起 Pull Request，都是对社区的巨大帮助。

• 报告 Bug 或提交建议: 请通过 GitHub Issues 提交。
• 贡献代码: Fork 本仓库，完成修改后向上游发起 Pull Request。

ComboLite 是一个免费的开源项目，由我利用业余时间进行开发和维护。如果这个项目对您有帮助，您的支持将是我持续投入的莫大动力。

点击查看赞助方式 (Click to see sponsorship methods)

您的每一份支持都意义非凡。可以通过以下方式请我喝杯咖啡 ☕️：

支付宝 (Alipay)	微信支付 (WeChat Pay)

ComboLite 遵循 Apache-2.0 license 开源许可协议。