cognitx-leyton/graphrag-code

# 🕸️ graphrag-code ***一个 TypeScript 代码库的知识图谱 — 对 NestJS 和 React 代码建立索引，然后使用 Cypher 回答架构问题。***       `graphrag-code` 将 TypeScript/TSX 仓库转化为可查询的 **代码知识图谱** —— 一种用于 **[Claude Code](https://www.anthropic.com/claude-code)**、**Claude** 及其他 **AI 编码代理** 的结构化检索后端。它遍历 AST，识别框架构造（NestJS 控制器、模块、DI；React 组件与 Hook），并将结果加载到 Neo4j。你的代理随后可以通过 Cypher 提问架构级问题 —— 依赖链、端点清单、组件用法、DI 枢纽等，而不是用模糊匹配去检索代码块。 在 **[Leyton CognitX](https://cognitx.leyton.com/)** 构建，旨在让大型 TypeScript 单体仓库对人类、Claude 以及 LLM 代理同样可读。 ## ✨ 亮点 - **框架感知解析** — 不仅仅是导入：包括控制器、可注入项、模块、实体、React 组件与 Hook 作为一等节点。 - **Neo4j 后端支持** — 每一条关系都可以通过 Cypher 查询。依赖遍历、最短路径、DI 链条、孤立节点检测，开箱即用。 - **Claude Code & AI 代理原生** — 类型化的图谱是 Claude Code、Claude 及其他编码代理的结构化检索后端，它们需要架构上下文，而不仅仅是最近邻的代码片段。 - **单体仓库友好** — 可按包范围索引（`twenty-server`、`twenty-front` 等），默认排除构建/测试产物。 - **开箱即用** — Typer CLI（`index`、`query`、`validate`）、Neo4j Docker Compose，以及示例 Cypher 查询库。 ## 📑 目录 - [为什么是代码知识图谱？](#-why-a-code-knowledge-graph) - [与 Claude Code & AI 代理配合使用](#-using-with-claude-code--ai-agents) - [架构](#-architecture) - [快速开始](#-quickstart) - [图谱模式](#-graph-schema) - [示例查询](#-example-queries) - [配置](#-configuration) - [路线图](#-roadmap) - [贡献](#-contributing) - [贡献者](#-contributors) - [Star 历史](#-star-history) - [许可证](#-license) ## 🧠 为什么要使用代码知识图谱？ 在原始代码块上进行向量搜索是一把钝器。它只能找到词法相似的片段，而非 *架构相关* 的片段。像 *“这个控制器会传递依赖哪些服务？”*、*“谁注入了 `AuthService`？”* 或 *“哪些 React 组件使用了这个 Hook？”* 这类问题本质上是图查询，而非相似性查询。 `graphrag-code` 为 LLM（或人类）提供所需的结构化骨架： - **基于 RAG 的检索增强生成**，针对 TypeScript 代码库进行类型化遍历，而非不透明的嵌入。 - **架构审计** — 发现枢纽、环路、孤立节点、纠缠模块。 - **更安全的重构** — 在修改前理解影响范围。 - **新手上路** — 让新成员可以通过 Cypher 查询代码库，而不是逐行阅读文件。 ## 🤖 与 Claude Code & AI 代理配合使用 `graphrag-code` 被设计为代理式编码工作流的即插即用检索后端。典型模式（适用于 [Claude Code](https://www.anthropic.com/claude-code) 及其他 LLM 编码代理 — Cursor、Aider、Continue、自定义 MCP 客户端）： 1. **一次性索引仓库**（参见 [快速开始](#-quickstart)）— `codegraph.cli index` 遍历 AST 并将图谱加载到 Neo4j。 2. **将图谱暴露给代理** — 通过轻量级 MCP 服务器、CLI 包装器（代理可调用），或从工具调用处理器直接使用 Bolt。 3. **让代理在编码前用 Cypher 提问架构问题**。 ### 为何这比仅用于编码代理的嵌入式 RAG 更佳 Claude Code 及其他编码代理在 **结构化、低噪声上下文** 中表现最好。向量搜索会带回“看起来相似”的内容；而类型化图谱能回答代理 *真正* 提出的问题： | 代理问题 | 图谱查询 | | --- | --- | | *“如果重命名 `AuthService`，会有什么影响？”* | 反向 `INJECTS` + `IMPORTS*` 遍历 | | *“`UserController` 暴露了哪些端点？”* | `EXPOSES` 直接查找 | | *“哪些 React 组件使用了 `useAuth`？”* | `USES_HOOK` 查找 | | *“这个文件如何从认证入口点到达？”* | 在 `IMPORTS` 上执行 `shortestPath` | | *“哪些服务是 DI 枢纽，我应将其视为核心？”* | `INJECTS` 聚合 | 所有答案均在个位数毫秒内返回，且不消耗检索无关片段的令牌。 ### 通过 MCP 向 Claude 公开图谱 一个第一类的 **[模型上下文协议](https://modelcontextprotocol.io/)** 服务器包装图谱已在 [路线图](#-roadmap) 中。在此期间，你可以： - 让 Claude Code 通过其 Bash 工具执行 `codegraph query ""`。 - 编写一个小的 MCP 服务器，使用 Neo4j 驱动暴露 `query_graph` 工具。 - 从任何支持自定义工具的代理框架直接查询 Bolt。 ## 🏗️ 架构 ``` TypeScript repo Parser Graph loader Neo4j ┌────────────────┐ ┌──────────────────┐ ┌──────────────┐ ┌──────────┐ │ *.ts / *.tsx │ ───► │ AST walk │ ───► │ Typed nodes │───► │ Property │ │ packages/*/src │ │ + framework │ │ + edges │ │ graph │ └────────────────┘ │ detection │ └──────────────┘ └────┬─────┘ │ (NestJS / React) │ │ └──────────────────┘ ▼ Cypher / RAG ``` 所有索引均在本地进行：你的代码不会离开机器，Neo4j 与 CLI 一起运行在 Docker 容器中。 ## 🚀 快速开始 ``` cd codegraph # 1. Python 环境 python3 -m venv .venv .venv/bin/pip install -r requirements.txt # 2. Neo4j (Docker) docker compose up -d # 浏览器 UI: http://localhost:7475 (neo4j / codegraph123) # Bolt: bolt://localhost:7688 # 3. 索引仓库（限定于您关心的软件包） .venv/bin/python -m codegraph.cli index /path/to/your-monorepo \ --package twenty-server --package twenty-front # 4. 健全性检查加载 .venv/bin/python -m codegraph.cli validate /path/to/your-monorepo # 5. 提问 .venv/bin/python -m codegraph.cli query \ "MATCH (e:Endpoint) RETURN e.method, e.path LIMIT 10" ``` ## 🧩 图谱模式 **节点** | 类型 | 示例/说明 | | --- | --- | | `File` | TS/TSX 文件，包含语言、LOC 以及框架标记（`is_controller`、`is_component` 等） | | `Class` | NestJS 控制器、可注入项、模块、实体、解析器 | | `Function` | 导出函数与 React 组件 | | `Interface` | TypeScript 接口 | | `Endpoint` | 控制器暴露的 HTTP 路由（方法、路径与处理函数） | | `Hook` | React Hook（自定义与内置使用站点） | | `Decorator` | 应用于类/方法的框架装饰器 | | `External` | 从 `node_modules` 导入的符号 | **边** `IMPORTS`、`IMPORTS_EXTERNAL`、`DEFINES_CLASS`、`DEFINES_FUNC`、`DEFINES_IFACE`、`EXPOSES`、`INJECTS`、`EXTENDS`、`IMPLEMENTS`、`RENDERS`、`USES_HOOK`、`DECORATED_BY`。 ## 🔎 示例查询 部分查询位于 [`codegraph/queries.md`](codegraph/queries.md)： ``` // 1. Every HTTP endpoint with its controller MATCH (c:Class {is_controller:true})-[:EXPOSES]->(e:Endpoint) RETURN c.name, e.method, e.path, e.handler ORDER BY c.name, e.path; // 2. Most-injected services (DI hubs) MATCH (svc:Class {is_injectable:true})<-[:INJECTS]-(caller:Class) RETURN svc.name, count(caller) AS injections ORDER BY injections DESC LIMIT 20; // 3. Which React components use a given hook? MATCH (:Hook {name:'useAuth'})<-[:USES_HOOK]-(c:Function) RETURN c.name, c.file; // 4. Transitive dependencies of a file MATCH (:File {path:$start})-[:IMPORTS*1..3]->(d:File) RETURN DISTINCT d.path; ``` 完整目录请参见 [`codegraph/queries.md`](codegraph/queries.md)。 ## ⚙️ 配置 Neo4j 连接通过环境变量控制（默认值与附带的 Docker Compose 一致）： | 变量 | 默认值 | | --- | --- | `CODEGRAPH_NEO4J_URI` | `bolt://localhost:7688` | | `CODEGRAPH_NEO4J_USER` | `neo4j` | | `CODEGRAPH_NEO4J_PASS` | `codegraph123` | 索引默认排除 `node_modules`、`dist`、`build`、`.next`、`.turbo`、`coverage` 以及生成目录。通过 `--package` 可按单体仓库包限定范围。 ## 🛣️ 路线图 - 文件的增量重新索引 - Python 与 Go 语言前端 - 第一类 MCP 服务器，向 LLM 代理公开图谱 - 常见架构问题的预构建 RAG 检索器 ## 🤝 贡献 欢迎提交 PR。仓库使用受保护分支： - **`main`** — 生产就绪代码，所有变更通过 PR 合并。 - **`release`** — 发布候选分支，用于稳定化与打标签。 - **`hotfix`** — 紧急修复，可跳过常规流程。 所有对 `main`、`release` 或 `hotfix` 的 PR 都需要 Code Owner 审核（参见 [`CODEOWNERS`](CODEOWNERS)）。在进行大型重构前请先打开议题以对齐方向。 ## ⭐ Star 历史 如果 `graphrag-code` 帮助你理解了 TypeScript 单体仓库，一枚 Star 也能帮助他人找到它。 ## 📄 许可证 根据 [Apache License 2.0](LICENSE) 授权。版权 © [Leyton CognitX](https://cognitx.leyton.com/) 及其贡献者。

标签：AI编码助手, AST解析, Claude Code, Cypher查询, DI容器, LLM检索, Neo4j, NestJS, React, SEO: AI编码, SEO: Neo4j知识图谱, SEO: TypeScript索引, SEO: 代码图谱, Syscalls, TypeScript, WebSocket, 代码图谱, 代码索引, 依赖分析, 安全插件, 实体, 控制器, 架构理解, 框架感知, 模块, 组件, 结构化存储, 语义查询, 请求拦截, 逆向工具, 钩子