Skip to content

Commit 70682ee

Browse files
author
yinxiangzheng3
committed
docs: 优化README
1 parent 356a86a commit 70682ee

1 file changed

Lines changed: 107 additions & 201 deletions

File tree

‎README.md‎

Lines changed: 107 additions & 201 deletions
Original file line numberDiff line numberDiff line change
@@ -1,250 +1,156 @@
1-
# IGraph
1+
<p align="center">
2+
<img src="website/public/logo.svg" width="120" alt="IGraph Logo" />
3+
</p>
24

3-
对代码仓库做 **解析 → 语义化 → 向量化**,构建多模态代码知识图谱的 Node.js CLI 工具。
5+
<h1 align="center">IGraph</h1>
46

5-
IGraph 把一个仓库解析为「符号节点 + 调用关系边」的知识图谱,叠加 LLM 语义摘要与向量索引,再通过双通道(Dense + FTS5)RRF 融合检索能力对外服务;并可挂载 PRD / DB Schema 等多模态资源建立跨模态关联。它还内置 MCP Server,可直接接入 Cursor / Claude Code 等 AI 助手。
7+
<p align="center">
8+
代码知识图谱构建工具 — 解析 → 语义化 → 向量化
9+
</p>
610

7-
## 核心能力
11+
<p align="center">
12+
<a href="https://www.npmjs.com/package/igraph-cli"><img src="https://img.shields.io/npm/v/igraph-cli?color=blue&label=npm" alt="npm version" /></a>
13+
<a href="https://github.com/Ychangqing/IGraph/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Ychangqing/IGraph" alt="license" /></a>
14+
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="node version" /></a>
15+
<a href="https://github.com/Ychangqing/IGraph/actions"><img src="https://img.shields.io/github/actions/workflow/status/Ychangqing/IGraph/deploy-docs.yml?label=docs" alt="docs build" /></a>
16+
<a href="https://github.com/Ychangqing/IGraph/issues"><img src="https://img.shields.io/github/issues/Ychangqing/IGraph" alt="issues" /></a>
17+
</p>
818

9-
- **多语言解析**:TypeScript / JavaScript / Python / Go / Java，tree-sitter 驱动的 5-Pass 流水线,提取函数/类/组件/变量及调用、继承、导入关系。
10-
- **语义摘要**:对文件与符号生成 LLM 摘要(`--no-llm` 时走启发式降级,无需 API Key)。
11-
- **向量检索**:BGE-M3 1024 维向量,SQLite + `sqlite-vec` 存储;Dense 与 FTS5 双通道经 RRF(`rrfK=60`)融合,支持 fallback。
12-
- **多模态挂载**:挂载 PRD(.md/.txt/.pdf/.docx)与 DB Schema(.sql/.json/.xlsx),按语义相似度建立 `describes` / `reads` 关联边。
13-
- **增量构建**:基于 SHA-256 diff 的级联更新,仅重建受影响文件。
14-
- **MCP 集成**:`igraph serve` 以 stdio 暴露 4 个只读检索 tool,供 AI 助手调用。
15-
- **凭据零硬编码**:API Key 等敏感信息通过**全局配置或环境变量**注入,禁止写入项目配置文件。
19+
<p align="center">
20+
<a href="https://ychangqing.github.io/IGraph/">官网文档</a> ·
21+
<a href="https://ychangqing.github.io/IGraph/guide/quick-start">快速开始</a> ·
22+
<a href="https://ychangqing.github.io/IGraph/reference/cli">CLI 参考</a> ·
23+
<a href="https://ychangqing.github.io/IGraph/features/mcp">MCP 集成</a>
24+
</p>
1625

17-
## 环境要求
26+
---
1827

19-
- **Node.js >= 18**
20-
- IGraph 依赖 `better-sqlite3` 与 tree-sitter 系列**原生(native)编译型插件**,安装时会在本机编译。请确保本机具备 C/C++ 构建工具链:
21-
- macOS:Xcode Command Line Tools(`xcode-select --install`)
22-
- Linux:`build-essential`、`python3`
23-
- Windows:`windows-build-tools` 或 Visual Studio Build Tools
28+
## 🎯 简介
2429

25-
## 安装
30+
IGraph 把代码仓库解析为「符号节点 + 调用关系边」的知识图谱，叠加 LLM 语义摘要与向量索引，通过双通道（Dense + FTS5）RRF 融合检索对外服务。支持挂载 PRD / DB Schema 等多模态资源建立跨模态关联，内置 MCP Server 可直接接入 Cursor / Claude Code 等 AI 助手。
2631

27-
```bash
28-
# 全局安装(提供 igraph 命令)
29-
npm install -g igraph-cli
30-
```
32+
## ✨ 核心能力
3133

32-
或在项目中本地安装:
34+
| 能力 | 说明 |
35+
|------|------|
36+
| 🌳 多语言解析 | tree-sitter 驱动 5-Pass 流水线，支持 TypeScript / JavaScript / Python / Go / Java |
37+
| 🧠 语义摘要 | LLM 为文件与符号生成摘要，`--no-llm` 时走启发式降级 |
38+
| 🔍 双通道检索 | BGE-M3 向量 + FTS5 全文检索，经 RRF 融合 |
39+
| 📎 多模态挂载 | PRD 文档、DB Schema 按语义相似度建立跨模态关联 |
40+
| ⚡ 增量构建 | 基于 SHA-256 diff 的级联更新，仅重建受影响文件 |
41+
| 🤖 MCP 集成 | 一条命令接入 Cursor / Claude Code |
42+
43+
## 📦 安装
44+
45+
**环境要求：** Node.js >= 18，C/C++ 构建工具链（原生编译依赖）
3346

3447
```bash
48+
# 全局安装
49+
npm install -g igraph-cli
50+
51+
# 或项目本地安装
3552
npm install igraph-cli
3653
```
3754

38-
> 全局选项:`-v, --verbose`(调试日志)、`-q, --quiet`(仅错误日志)、`-V, --version`(版本号)。
55+
<details>
56+
<summary>构建工具链安装</summary>
57+
58+
- **macOS：** `xcode-select --install`
59+
- **Linux：** `sudo apt install build-essential python3`
60+
- **Windows：** Visual Studio Build Tools
3961

40-
## 快速开始
62+
</details>
4163

42-
以下是从初始化到 MCP 服务的完整流程:
64+
## 🚀 快速开始
4365

4466
```bash
45-
# 1. 初始化配置文件 .igraph/config.json
67+
# 1. 初始化
4668
igraph init
4769

4870
# 2. 注入凭据（全局配置，一次设置所有项目共享）
4971
igraph config set apiKey sk-...
50-
# - 或通过环境变量：export IGRAPH_API_KEY="sk-..."
5172

52-
# 3. 构建图谱:解析 → 落库 → 摘要 → 向量化
73+
# 3. 构建图谱
5374
igraph build
54-
# - 无凭据时可用启发式降级(跳过向量化):
55-
igraph build --no-llm
56-
# - 仅预览解析统计,不写库:
57-
igraph build --dry-run
58-
59-
# 4.(可选)挂载多模态资源
60-
igraph mount prd docs/需求文档.md
61-
igraph mount db schema/db.sql
62-
63-
# 5. 检索:自然语言查询
64-
igraph query "用户鉴权在哪里实现"
65-
igraph query "JWT 校验" --top-k 5 --json
66-
67-
# 6. 查看图谱状态
68-
igraph status
6975

70-
# 7. 注册 MCP Server 到 AI 助手（自动检测 Claude Code / Cursor）
76+
# 4. 注册 MCP Server 到 AI 助手
7177
igraph register
7278

73-
# 8. 或手动启动 MCP Server
74-
igraph serve
75-
```
76-
77-
首次 `build` 后再次运行会**自动增量更新**(基于文件 diff)。若需推倒重建:
78-
79-
```bash
80-
igraph rebuild # 清空并全量重建
81-
igraph rebuild --no-llm # 启发式降级重建
82-
igraph rebuild --dry-run # 仅预览,不删库不写库
83-
```
84-
85-
## 配置说明
86-
87-
`igraph init` 在当前目录生成 `.igraph/config.json`,图谱数据库位于 `.igraph/igraph.db`。配置含五节:
88-
89-
```jsonc
90-
{
91-
"embedding": {
92-
"baseURL": "http://localhost:8080/v1",
93-
"model": "bge-m3",
94-
"dimensions": 1024,
95-
"batchSize": 32
96-
},
97-
"llm": {
98-
"baseURL": "https://api.openai.com/v1",
99-
"model": "gpt-4o-mini",
100-
"fileSummaryModel": "gpt-4o",
101-
"temperature": 0,
102-
"maxConcurrency": 5,
103-
"promptVersion": "v1.0"
104-
},
105-
"parser": {
106-
"languages": ["typescript", "javascript"],
107-
"include": ["**/*"],
108-
"exclude": ["node_modules/**", "dist/**", "**/*.test.*", "**/*.spec.*", "**/*.d.ts"]
109-
},
110-
"retrieval": {
111-
"fileTopK": 10,
112-
"nodeTopK": 10,
113-
"fallbackThreshold": 0.75,
114-
"graphHops": 2,
115-
"fusion": "rrf",
116-
"rrfK": 60,
117-
"denseWeight": 1.0,
118-
"ftsWeight": 1.0
119-
},
120-
"multimodal": {
121-
"strongLinkThreshold": 0.85,
122-
"weakLinkThreshold": 0.7,
123-
"llmConfirmWeakLinks": false
124-
}
125-
}
126-
```
127-
128-
### 凭据管理(重要)
129-
130-
**凭据零硬编码**:API Key 等敏感信息禁止写入项目级 `.igraph/config.json`（防止提交到 git）。
131-
132-
推荐方式 — 全局配置（一次设置，所有项目共享）：
133-
134-
```bash
135-
igraph config set apiKey sk-xxx
136-
igraph config set embedding.baseURL http://my-embedding:8080/v1
137-
```
138-
139-
也可通过环境变量提供：
140-
141-
```bash
142-
export IGRAPH_API_KEY="sk-..."
79+
# 5. 自然语言查询
80+
igraph query "用户鉴权在哪里实现"
14381
```
14482

145-
| 来源 | 优先级 | 说明 |
146-
|------|--------|------|
147-
| 环境变量 | 最高 | `IGRAPH_API_KEY`、`IGRAPH_EMBEDDING_BASE_URL`、`IGRAPH_LLM_BASE_URL` |
148-
| 全局配置 | 中 | `~/.igraph/config.json`（`igraph config set` 写入） |
149-
| 项目配置 | 低 | `.igraph/config.json`（禁止含凭据字段） |
83+
> 无 API Key 时可用 `igraph build --no-llm` 走启发式降级，`query` / `serve` 自动降级为仅 FTS5 检索。
15084
151-
凭据优先级:**环境变量 > 全局配置 > 项目配置**。
85+
更多用法请查看 [官网文档](https://ychangqing.github.io/IGraph/guide/quick-start)。
15286

153-
> 未提供 API Key 时:`build`/`rebuild` 可加 `--no-llm` 走启发式降级并跳过向量化;`query`/`eval`/`serve` 会自动降级为**仅 FTS5 通道**检索,离线仍可用。
154-
155-
## 支持的语言与文件格式
156-
157-
| 类别 | 语言 / 类型 | 扩展名 |
158-
| --------- | ---------------- | -------------------------------- |
159-
| 代码 | TypeScript | `.ts` `.tsx` `.mts` `.cts` |
160-
| 代码 | JavaScript | `.js` `.jsx` `.mjs` `.cjs` |
161-
| 代码 | Python | `.py` `.pyi` |
162-
| 代码 | Go | `.go` |
163-
| 代码 | Java | `.java` |
164-
| 多模态 | PRD 文档 | `.md` `.markdown` `.txt` `.pdf` `.docx` |
165-
| 多模态 | DB Schema | `.sql` `.ddl` `.json` `.xlsx` |
166-
167-
## MCP 集成
168-
169-
`igraph serve` 以 MCP stdio 传输暴露 4 个只读检索 tool：`igraph_explore`、`igraph_node`、`igraph_file`、`igraph_related`。
170-
171-
### 自动注册（推荐）
87+
## 🤖 MCP 集成
17288

17389
```bash
174-
# 自动检测已安装的 AI 助手并注册 MCP Server
90+
# 自动检测已安装的 AI 助手并注册
17591
igraph register
17692

177-
# 指定目标助手
93+
# 指定目标
17894
igraph register --target claude
17995
igraph register --target cursor
180-
igraph register --target claude,cursor
181-
182-
# 注册到全局配置（所有项目共享）
183-
igraph register --global
18496

18597
# 注销
18698
igraph unregister
18799
```
188100

189-
`igraph register` 会自动将 MCP Server 配置写入对应助手的配置文件：
190-
191-
| 助手 | 项目级 | 全局 |
192-
|------|--------|------|
193-
| Claude Code | `.mcp.json` | `~/.claude.json` |
194-
| Cursor | `.cursor/mcp.json` | `~/.cursor/mcp.json` |
195-
196-
### 手动配置
197-
198-
也可以手动在 AI 助手的 MCP 配置文件中添加：
199-
200-
```json
201-
{
202-
"mcpServers": {
203-
"igraph": {
204-
"type": "stdio",
205-
"command": "igraph",
206-
"args": ["serve"]
207-
}
208-
}
209-
}
210-
```
211-
212-
> `IGRAPH_API_KEY` 从用户 shell 环境自动继承，无需在配置中指定。未提供时 `igraph_explore` 自动降级为仅 FTS5 检索。
213-
214-
各 tool 的参数、返回结构与调用示例详见 [docs/mcp-tools.md](docs/mcp-tools.md)。
215-
216-
## 命令速查表
217-
218-
| 命令 | 说明 | 常用选项 |
219-
| ------------------- | ------------------------------------------ | --------------------------------------- |
220-
| `igraph init` | 初始化 `.igraph/config.json` | `-f, --force` |
221-
| `igraph build` | 构建图谱(首次全量,后续自动增量) | `--incremental` `--dry-run` `--no-llm` |
222-
| `igraph rebuild` | 清空并从零全量重建 | `--full` `--dry-run` `--no-llm` |
223-
| `igraph status` | 查看图谱状态(规模/向量/资源/进度) | — |
224-
| `igraph query` | 自然语言检索(双通道 RRF + 图谱展开) | `--top-k <n>` `--json` |
225-
| `igraph eval` | 评测检索质量(Recall@K / MRR / 耗时) | `--test-set <path>` `--top-k <n>` |
226-
| `igraph serve` | 启动 MCP Server（stdio） | — |
227-
| `igraph register` | 注册 MCP Server 到 AI 助手配置 | `--target <targets>` `--global` |
228-
| `igraph unregister` | 从 AI 助手配置中移除 MCP Server 注册 | `--target <targets>` `--global` |
229-
| `igraph mount prd` | 挂载 PRD 文档并关联代码文件 | `--top-k <n>` |
230-
| `igraph mount db` | 挂载 DB Schema 并关联代码文件 | `--top-k <n>` |
231-
| `igraph config set` | 设置全局配置项（如 apiKey、embedding.baseURL）| `<key> <value>` |
232-
| `igraph config get` | 获取全局配置项 | `<key>` |
233-
| `igraph config list`| 列出全部全局配置 | — |
234-
235-
## 开发
101+
注册后 AI 助手可直接调用 4 个只读检索 Tool：
102+
103+
| Tool | 说明 |
104+
|------|------|
105+
| `igraph_explore` | 自然语言检索，附带图谱上下文展开 |
106+
| `igraph_node` | 按符号名获取节点详情 |
107+
| `igraph_file` | 按文件路径获取文件图谱信息 |
108+
| `igraph_related` | 展开某符号的关联资源 |
109+
110+
详见 [MCP Tool 文档](https://ychangqing.github.io/IGraph/reference/mcp-tools)。
111+
112+
## 📋 命令速查
113+
114+
| 命令 | 说明 |
115+
|------|------|
116+
| `igraph init` | 初始化配置 |
117+
| `igraph build` | 构建图谱（自动增量） |
118+
| `igraph rebuild` | 清空并全量重建 |
119+
| `igraph status` | 查看图谱状态 |
120+
| `igraph query` | 自然语言检索 |
121+
| `igraph eval` | 评测检索质量 |
122+
| `igraph serve` | 启动 MCP Server |
123+
| `igraph register` | 注册到 AI 助手 |
124+
| `igraph mount prd` | 挂载 PRD 文档 |
125+
| `igraph mount db` | 挂载 DB Schema |
126+
| `igraph config` | 管理全局配置 |
127+
128+
## 🗂 支持的语言与格式
129+
130+
| 类别 | 语言 / 类型 | 扩展名 |
131+
|------|------------|--------|
132+
| 代码 | TypeScript | `.ts` `.tsx` `.mts` `.cts` |
133+
| 代码 | JavaScript | `.js` `.jsx` `.mjs` `.cjs` |
134+
| 代码 | Python | `.py` `.pyi` |
135+
| 代码 | Go | `.go` |
136+
| 代码 | Java | `.java` |
137+
| 多模态 | PRD 文档 | `.md` `.txt` `.pdf` `.docx` |
138+
| 多模态 | DB Schema | `.sql` `.ddl` `.json` `.xlsx` |
139+
140+
## 🛠 开发
236141

237142
```bash
238-
npm run dev # tsup watch 模式
239-
npm test # vitest 运行
143+
npm run dev # watch 模式
144+
npm test # vitest
240145
npm run lint # eslint
241-
npm run format # prettier
242-
npm run typecheck # tsc --noEmit
243-
npm run build # tsup 构建
146+
npm run typecheck # 类型检查
147+
npm run build # 构建
244148
```
245149

246-
发布前会自动执行 `prepublishOnly`(typecheck → test → build)校验并产出 `dist`。
150+
## 🤝 贡献
151+
152+
欢迎提交 Issue 和 Pull Request！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详情。
247153

248-
## License
154+
## 📄 License
249155

250-
MIT
156+
[MIT](LICENSE) © 2024-present IGraph

0 commit comments

Comments
 (0)