内容
# 库见解 🔍
AI 编码助手经常根据旧文档、最新的网络示例或与项目中安装的版本不同的版本来猜测 Java/Kotlin 库 API。这导致出现缺失方法、已弃用用法、错误签名和调试时间浪费。
库见解通过扫描您使用的确切 JAR/AAR、Gradle 输出或 Maven 版本来解决这个问题。它读取编译的 `.class` 结构（使用 ASM）和 Kotlin `@Metadata` 注解（使用 `kotlin-metadata-jvm`）以构建一个可搜索的、版本正确的公共 API 索引。
在以下情况下使用它：
- 添加库到项目后，了解如何正确使用它。
- 检查已安装版本中存在哪些类、方法、构造函数和属性。
- 阻止 AI 使用新版本、旧版本或未文档化的版本中的示例。
- 查找已弃用的 API，并在重写代码前比较版本。
- 为 AI 助手提供确切的签名，而无需将大量文档文件转储到上下文中。
> **核心思想：** AI 应该根据您实际使用的库版本进行编码，而不是它从网络上记住的版本。
---
## 主要功能
- **MCP 服务器**：连接到 Cursor、Claude Desktop 或任何兼容 MCP 的 IDE。它们直接调用 `scan_library`、`search_symbols` 和 `explain_class`，无需离开编辑器。
- **多格式支持**：读取 JAR、AAR（包括嵌套 JAR）、目录和 Gradle 构建输出。
- **版本正确的 API 查询**：扫描您指定的确切构件，以便 AI 代理和开发人员看到该依赖项版本的真实公共 API。
- **深入的元数据提取**：类、构造函数、方法、属性、泛型、Kotlin 元数据、`suspend` 关键字、注解。
- **迁移顾问**：比较两个版本，并报告已删除、已弃用和替换的 API — 适用于 Retrofit、OkHttp、Compose 和 Kotlin 升级。
- **依赖项 API 审计**：扫描项目 Gradle 依赖项，并报告已安装字节码中发现的已弃用 API。
- **依赖项图**：从 POM 描述符渲染传递依赖项的递归视觉树。
- **SemVer 检查器**：检查实际代码更改的版本提升，以捕获未提升的破坏性更改。
- **搜索 Maven Central**：在无需离开终端的情况下查找坐标和最新版本。
- **格式导出器**：将 API 索引转换为结构化的 **JSON** 或可读的 **Markdown** 参考文档。
- **AI 上下文导出器**：为 LLMs 生成紧凑的、令牌高效的 `ai-context/` 目录 — 比原始转储小 95%+。
---
## 为什么存在
当您添加依赖项时，第一个问题很简单：“如何正确使用此版本的库？”
在实际项目中，答案通常很混乱：
- AI 可能为最新版本编写代码，而您的项目使用的是较旧版本。
- AI 可能复制旧博客帖子中的方法名称，但该方法名称不再存在。
- 官方文档可能不完整或未针对您安装的版本更新。
- 已弃用方法可能仍出现在示例中，而替换方法隐藏在发行说明或源注释中。
- 大型生成的文档浪费 AI 上下文，使一个类难以查找。
库见解将编译后的库本身变成真相的来源。扫描依赖项，然后使用 `search`、`explain`、`diff` 或 `ai-export` 为人类和 AI 代理提供确切的、版本感知的 API 信息。
---
## 架构与模块化设计
库见解遵循 **Clean Architecture** 原则。下面是模块化依赖流的示意图：
```mermaid
graph TD
subgraph CLI Layer
CLI[library-insight-cli]
end
subgraph Orchestration Layer
CORE[library-insight-core]
end
subgraph Processing Modules
PARSER[library-insight-parser]
KOTLIN[library-insight-kotlin]
SEARCH[library-insight-search]
EXPORT[library-insight-export]
end
subgraph Data & Common Utility Base
MODEL[library-insight-model]
COMMON[library-insight-common]
end
CLI --> CORE
CORE --> PARSER
CORE --> KOTLIN
CORE --> SEARCH
CORE --> EXPORT
PARSER --> MODEL
KOTLIN --> MODEL
SEARCH --> MODEL
EXPORT --> MODEL
MODEL --> COMMON
COMMON --> ASM[ASM Bytecode Reader]
COMMON --> KTOR[Ktor HTTP Client]
```
系统由以下模块组成：
- `library-insight-common`：ZIP/JAR/AAR 提取、Ktor 异步 HTTP 引擎和文件系统操作的实用程序类。
- `library-insight-model`：表示 API 索引模式的不可变 Kotlin 序列化结构。
- `library-insight-parser`：使用 **ASM** 和 JVM 签名解析的原始字节码结构提取。
- `library-insight-kotlin`：Kotlin 元数据解析（`kotlin-metadata-jvm`）和 JVM 字节码增强。
- `library-insight-search`：索引搜索和查询匹配逻辑。
- `library-insight-export`：JSON、Markdown 和 AI 上下文格式化程序。
- `library-insight-core`：协调扫描流程并实现语义 API 差异引擎。
- `library-insight-cli`：使用 **Clikt** 的命令行界面定义。
---
## 安装与设置
### 要求
- JDK 17 或更高版本（执行 Java/Kotlin 运行时引擎所需）
### 选项 A：通过一行 Shell 安装程序安装（推荐）
您可以使用安装脚本在系统上全局安装 CLI：
```bash
curl -fsSL https://raw.githubusercontent.com/Coding-Meet/Library-Insight/main/install.sh | bash
```
_（安装后，您可以直接从任何文件夹执行 `library-insight` 命令。）_
### 选项 B：从源代码手动构建
如果您只想在不进行全局注册的情况下运行本地构建：
```bash
./gradlew installDist
```
可执行二进制文件将在以下路径生成：
`./library-insight-cli/build/install/library-insight/bin/library-insight`
### 卸载
要干净地删除全局 CLI 二进制文件、安装文件和已注册的 AI 代理技能：
```bash
curl -fsSL https://raw.githubusercontent.com/Coding-Meet/Library-Insight/main/uninstall.sh | bash
```
---
## AI 代理技能集成
库见解捆绑了一个自定义 AI 代理技能 (`SKILL.md`)，用于教导 AI 助手（例如 Claude、Gemini、Cursor、Copilot、Junie 等）在编写代码前验证实际依赖项 API。
该技能围绕一个规则设计：当可以扫描安装的库版本时，不要从网络示例中猜测。
代理应该使用 `search`、`explain`、`diff` 和 `ai-export` 来确认实际构件中存在什么。
### 1. 全局自动集成
当您通过 **选项 A** (`install.sh`) 全局安装 CLI 时，安装脚本会自动将代理技能文件复制到您的用户配置文件中：
- `~/.cursor/skills/library-insight`
- `~/.gemini/config/skills/library-insight`
- `~/.claude/skills/library-insight`
- `~/.agents/skills/library-insight`
- `~/.copilot/skills/library-insight`
- `~/.junie/skills/library-insight`
任何在您的计算机上运行的活动 AI 代理都将立即发现并利用 `library-insight` 命令树。
### 2. 项目工作区范围
如果您只想将技能安装到当前项目目录（工作区特定范围）中，可以运行：
```bash
library-insight init
# 或
library-insight skills add
```
这会在项目根目录中创建 `.agents/skills/library-insight/SKILL.md`，使工作区范围的代理可以访问该工具。
---
## 快速入门
> [!NOTE]
> 这些示例假设您已全局安装 CLI。 从任意文件夹运行 `library-insight <command>`。
```bash
# 1. 从 Maven Central 扫描库（或从 Gradle 缓存中选择）
library-insight scan com.squareup.retrofit2:retrofit:2.11.0
# 2. 按名称查找类
library-insight search Retrofit
# 3. 检查类的完整 API 签名和文档
library-insight explain Retrofit
# 4. 比较两个版本 — 查看添加、删除或更改的内容
library-insight diff com.squareup.retrofit2:retrofit:2.9.0 com.squareup.retrofit2:retrofit:2.11.0
# 5. 获取迁移报告，并建议替换 API
library-insight migrate com.squareup.retrofit2:retrofit:2.9.0 com.squareup.retrofit2:retrofit:2.11.0
# 6. 审计所有项目依赖项的已弃用 API
library-insight audit
# 7. 启动 MCP 服务器（通过 Cursor、Claude Desktop 等连接）
library-insight mcp
```
→ 查看 **[docs/CLI.md](docs/CLI.md)** 以获取完整的命令参考（所有 16 个命令均附有示例和输出）。
---
## 仓库目录结构
以下是库见解项目的主要文件夹和组件的目录结构：
```
Library-Insight/
├── .agents/ # 本地工作区 AI 代理自定义
│ └── skills/
│ └── library-insight/
│ ├── SKILL.md # 主自定义 AI 代理技能文件
│ └── scripts/
│ └── install-cli.sh # 全局安装 CLI 二进制文件的脚本
├── buildSrc/ # Gradle 预编译脚本插件，用于约定构建
│ ├── src/main/kotlin/
│ │ └── kotlin-jvm.gradle.kts # 共享的 Kotlin JVM 约定
│ └── build.gradle.kts
├── gradle/
│ ├── wrapper/
│ │ ├── gradle-wrapper.jar
│ │ └── gradle-wrapper.properties
│ └── libs.versions.toml # Gradle 版本目录，用于共享依赖项
├── gradle.properties # Gradle 构建和配置缓存参数
├── library-insight-cli/
│ ├── src/
│ │ └── main/
│ │ └── kotlin/
│ │ └── com/
│ │ └── meet/
│ │ └── libraryinsight/
│ │ └── cli/
│ │ ├── DatabaseHelper.kt
│ │ ├── Main.kt
│ │ └── commands/
│ │ ├── AiExportCommand.kt
│ │ ├── AuditCommand.kt
│ │ ├── CheckCompatCommand.kt
│ │ ├── ClearCacheCommand.kt
│ │ ├── DiffCommand.kt
│ │ ├── DoctorCommand.kt
│ │ ├── ExplainCommand.kt
│ │ ├── ExportCommand.kt
│ │ ├── GraphCommand.kt
│ │ ├── InitCommand.kt
│ │ ├── McpCommand.kt
│ │ ├── MigrateCommand.kt
│ │ ├── ScanCommand.kt
│ │ ├── SearchCommand.kt
│ │ ├── SearchCentralCommand.kt
│ │ └── SkillsCommand.kt
│ └── build.gradle.kts
├── library-insight-common/
│ ├── src/
│ │ └── main/
│ │ └── kotlin/
│ │ └── com/
│ │ └── meet/
│ │ └── libraryinsight/
│ │ └── common/
│ │ └── ArchiveUtils.kt
│ └── build.gradle.kts
├── library-insight-core/
│ ├── src/
│ │ ├── main/
│ │ │ └── kotlin/
│ │ │ └── com/
│ │ │ └── meet/
│ │ │ └── libraryinsight/
│ │ │ └── core/
│ │ │ ├── diff/
│ │ │ └── LibraryAnalyzer.kt
│ │ └── test/
│ │ └── kotlin/
│ │ └── com/
│ │ └── meet/
│ │ └── libraryinsight/
│ │ └── core/
│ │ └── diff/
│ └── build.gradle.kts
├── library-insight-export/
│ ├── src/
│ │ └── main/
│ │ └── kotlin/
│ │ └── com/
│ │ └── meet/
│ │ └── libraryinsight/
│ │ └── export/
│ │ ├── AiExporter.kt
│ │ ├── JsonExporter.kt
│ │ └── MarkdownExporter.kt
│ └── build.gradle.kts
├── library-insight-kotlin/
│ ├── src/
│ │ └── main/
│ │ └── kotlin/
│ │ └── com/
│ │ └── meet/
│ │ └── libraryinsight/
│ │ └── kotlin/
│ │ ├── KotlinMetadataEnricher.kt
│ │ └── KotlinMetadataParser.kt
│ └── build.gradle.kts
├── library-insight-model/
│ ├── src/
│ │ └── main/
│ │ └── kotlin/
│ │ └── com/
│ │ └── meet/
│ │ └── libraryinsight/
│ │ └── model/
│ │ └── LibraryApiIndex.kt
│ └── build.gradle.kts
├── library-insight-parser/
│ ├── src/
│ │ ├── main/
│ │ │ └── kotlin/
│ │ │ └── com/
│ │ │ └── meet/
│ │ │ └── libraryinsight/
│ │ │ └── parser/
│ │ │ ├── BytecodeParser.kt
│ │ │ ├── RawClassData.kt
│ │ │ └── SignatureParser.kt
│ │ └── test/
│ │ └── kotlin/
│ │ └── com/
│ │ └── meet/
│ │ └── libraryinsight/
│ │ └── parser/
│ │ └── SignatureParserTest.kt
│ └── build.gradle.kts
├── library-insight-search/
│ ├── src/
│ │ └── main/
│ │ └── kotlin/
│ │ └── com/
│ │ └── meet/
│ │ └── libraryinsight/
│ │ └── search/
│ │ └── SearchEngine.kt
│ └── build.gradle.kts
├── sample/
│ ├── src/
│ │ └── main/
│ │ ├── java/
│ │ │ └── com/
│ │ │ └── meet/
│ │ │ └── sample/
│ │ │ └── JavaLibrary.java
│ │ └── kotlin/
│ │ └── com/
│ │ └── meet/
│ │ └── sample/
│ │ └── SampleLibrary.kt
│ └── build.gradle.kts
├── ai-context.json
├── build.gradle.kts
├── gradlew
├── gradlew.bat
├── local.properties
├── metadata-jvm.md
├── README.md
└── settings.gradle.kts
```
---
## 许可证
Copyright 2026 Library Insight Authors. Licensed under the Apache License, Version 2.0.
连接信息
猜你喜欢
暂无推荐服务器