📦 Jar Source Reader

AI Skill · 让 AI 直接阅读 jar 依赖源码 · Maven / Gradle 双支持

✨ 项目简介

本项目是一个 Skill。当 AI 需要查看 Maven / Gradle 项目中某个依赖 jar 包的源码，它可以通过此 Skill 直接读取并展示目标类、内部类或指定方法的 Java 源代码，无需你手动去翻阅源码。

💡 它解决了什么问题？

在日常开发中，AI 无法直接访问 jar 包内的源码。当你请求 AI 分析某个第三方库的实现细节时，AI 只能依赖训练数据中的记忆，可能不准确或已过时。本 Skill 让 AI 能够实时从你本地仓库中读取真实源码，给出更精确的分析。

🚀 功能特性

• 🔍 类源码查看 — 支持传入类名或完全限定类名，直接输出目标类的完整源码
• 🪆 内部类支持 — 使用 $ 分隔符可查看嵌套内部类，如 OuterClass$InnerClass
• 🎯 方法级查看 — 精确输出指定方法源码，支持重载方法一并展示
• 📐 智能骨架降级 — 当类源码超过 500 行时，自动输出类结构摘要（字段 + 公开方法签名），引导 AI 进一步精确查询
• 🔎 模糊定位 — 在当前 Maven / Gradle 项目的依赖 jar 中按类名自动定位来源
• 📁 双仓库支持 — 同时搜索 Maven（~/.m2/repository）和 Gradle（~/.gradle/caches）本地仓库
• 🛠️ 自定义仓库路径 — 支持通过参数显式指定仓库根目录

🔬 工作原理

本项目的核心思路其实非常简单：

1. 路径拼接 — 无论是 Maven 还是 Gradle 项目，依赖的 jar 包在本地磁盘上都有固定的存储路径（Maven 在 ~/.m2/repository，Gradle 在 ~/.gradle/caches）。只要知道目标依赖的 groupId、artifactId 和 version，就可以拼接出完整的本地路径，进而找到对应的 *-sources.jar 文件。
2. ZIP 结构定位 — sources.jar 本质上是一个 ZIP 压缩包，而 Java 类的全限定类名天然对应 ZIP 内的文件目录结构（例如 cn.hutool.core.util.IdUtil → cn/hutool/core/util/IdUtil.java）。因此，通过全类名即可精确定位到源码文件在 ZIP 中的位置并读取其内容。
3. AST 解析 — 读取到源码文本后，利用 JavaParser 将其解析为 AST（抽象语法树），从而支持按方法名精确提取、类结构摘要等高级功能。

读取已存在的 sources jar 不依赖 IDE，主要基于本地文件系统操作；fuzzy 模式调用 Maven / Gradle 获取依赖列表时，构建工具可能按项目配置解析尚未缓存的插件或依赖。

🔎 Fuzzy 模式

当 AI 只知道类名、不知道目标类属于哪个依赖时，可以使用 fuzzy 模式自动定位来源 jar。工具会利用 Maven / Gradle 的原生能力遍历当前项目的依赖 jar 包，从中查找目标 Class 文件，再反推出对应的 sources jar。具体流程如下：

1. 获取当前项目所有依赖的 jar 包列表
2. 逐个扫描每个 jar 包，查找是否包含目标 Class 文件
3. 找到后，根据 jar 包的路径反推出 groupId、artifactId、version
4. 最终拼接出 sources.jar 的路径并读取源码

⚠️ 依赖列表获取方式

构建工具	获取依赖列表的难度	说明
Maven	🟢 相对容易	通过 mvnw dependency:build-classpath 或 mvn dependency:build-classpath 获取
Gradle	🔴 较为困难	通过随工具附带的 init script 注入 printAllJar 任务获取

如果你有更好的方案来实现 "根据类名自动定位其所属 jar 包" 这一功能，非常欢迎提交 PR 或在 Issue 中讨论！

📖 安装与使用

1️⃣ 下载 Skill

从 Releases 页面下载最新版本的压缩包。

2️⃣ 放置到 Skills 目录

将下载的文件解压后，放置到以下目录：

~/.claude/skills/jar-source-reader/
├── SKILL.md                            # AI Skill 描述文件
└── tool/
    ├── jar-source-reader.jar           # 工具本体
    └── print-all-jar.gradle            # Gradle 依赖扫描脚本

3️⃣ 下载源代码（Source Jar）

在使用前，你需要确保目标依赖的 sources jar 已下载到本地仓库。

在 IntelliJ IDEA 中，打开 Maven 工具栏，点击 「下载源代码」 按钮即可：

4️⃣ 向 AI 提供目标源码信息

在与 AI 对话时，你需要向 AI 提供你想查看的目标类所在 jar 包的依赖坐标信息（groupId、artifactId、version），AI 就会自动调用此 Skill 读取源码。

⚙️ 参数说明

以下参数由 AI 在调用时自动填充，供开发者参考：

参数	必填	说明
--group-id	✅	Maven Group ID，如 cn.hutool
--artifact-id	✅	Maven Artifact ID，如 hutool-all
--version	✅	依赖版本号，如 5.8.36
--class-name	✅	类名或完全限定类名，如 IdUtil 或 cn.hutool.core.util.IdUtil；内部类使用 $ 分隔
--method-name	❌	方法名，传入后只输出对应方法源码；存在重载时会一并输出
--maven-repo	❌	指定 Maven 仓库根目录，默认 ~/.m2/repository
--gradle-repo	❌	指定 Gradle 仓库根目录，默认 ~/.gradle/caches/modules-2/files-2.1
--ignore-length-limit	❌	忽略 500 行的源码长度限制，强制输出完整源码

📂 项目结构

jar-source-reader/
├── src/
│   ├── main/kotlin/com/yshs/jsr/
│   │   └── Main.kt                # 🚀 程序入口与核心逻辑
│   └── test/                       # 🧪 单元测试
├── SKILL.md                        # 🤖 AI Skill 描述文件
├── print-all-jar.gradle            # 🐘 Gradle 依赖扫描脚本
└── build.gradle.kts                # 🔨 Gradle 构建配置

🛠️ 开发环境

环境	版本要求
☕ JDK	8+
🐘 Gradle	Wrapper 自带

🔗 技术栈

依赖	用途
JavaParser	解析 Java 源码 AST，提取类/方法/字段声明
Clikt	Kotlin 命令行参数解析框架
Shadow	构建 fat jar（包含所有依赖）

📄 许可证

本项目采用 GPL-3.0 开源许可证。