技能介绍

解决什么问题

Android 工程里，真正出问题的代码常常不在你自己的 src/main/java，而在几百 MB 的依赖里。grep 和 IDE 的 Find Usages 只能搜工作区，找不到 com.google.gson.Gson 的定义；线上崩溃栈顶指向 OkHttp 的某个类，手头只有 .aar 或 .jar；想确认某个回调接口的线程模型和异常类型，只能去翻 Maven 页面甚至猜。本文这套技能把「读依赖源码」做成 Agent 可以直接调用的动作，而不是每次靠人肉去 Gradle 缓存里翻。

它如何工作

核心能力主要有五项：按全限定类名读取源码、按 Maven 坐标抽取整个库、在已抽取源码中检索关键词、列出库的包结构与文件清单，以及从 build.gradle 或 gradle/libs.versions.toml 自动解析项目实际使用的版本。

查找分两层。第一层是 -sources.jar 抽取：多数开源库会同时发布源码包，Gradle 同步时已经拉到本地缓存，直接解压即可，路径最干净。第二层是兜底反编译：没有源码包时，对 .jar 或 AAR 内的 classes.jar 做反编译。反编译按 jadx → CFR → Fernflower 的顺序选择；其中 jadx 命中即用且失败不再降级，CFR 与 Fernflower 互为回退。

首次使用时，Agent 应先检查类名索引是否存在。没有索引时先跑初始化检查环境，再跑 index-all 建立全量索引；索引完成后，find-class 走二分查找，响应时间从扫描缓存的十几秒降到 0.1 秒左右。版本解析支持四种形态：版本变量引用、直接写死的字符串、Version Catalog 里的内联 version，以及通过 version.ref 指向的 [versions] 条目。命中情况会明确输出 VERSION_MATCH 或 VERSION_WARN，方便判断这次看到的源码是否真的对应项目里跑的那版。

适用边界与注意点

反编译得到的是还原结果，不是作者原始源码：泛型擦除、内联后的控制流、资源与 AndroidManifest 都可能与真实行为有偏差。遇到混淆产物时，优先确认是否有可读的 -sources.jar，不要只依赖反编译结果下结论。

必须核对版本。项目实际加载的库版本以 build.gradle 和 gradle.lockfile 为准；跨大版本改 API 的情况很常见，拿错版本读源码比不读更危险。

AAR 与 JAR 要区分处理。AAR 内含 classes.jar、资源和清单文件，需要先拆出 classes 再反编译。缓存目录默认在 ~/.gradle/android-lib-reader/，跨会话保留；如果配置了非默认的 GRADLE_USER_HOME，要显式设置同名环境变量，否则可能扫到错误的缓存。

适用场景很明确：工作区里找不到类定义、栈帧落在依赖中、需要确认第三方 API 的签名或线程保证、用户直接要求「读库源码」时，第一反应应该是调用这套技能，而不是回复找不到类。