Code Graph Context：为AI编程助手构建代码库的" photographic memory "

本文介绍了一个MCP服务器项目，通过构建TypeScript代码库的语义图谱，使Claude等AI助手不仅能理解单个文件，还能理解整个系统的架构和依赖关系，实现深度代码理解和智能重构。

引言：AI编程助手的上下文困境\n\n随着GitHub Copilot、Claude Code等AI编程助手的普及，开发者已经习惯了让AI帮助编写代码。然而，一个根本性的限制始终存在：AI助手通常只能"看到"当前正在编辑的文件，对整个代码库的全貌缺乏理解。当你问"哪些服务依赖于UserService"或"修改这个函数的波及范围有多大"时，传统AI助手往往无能为力，只能进行耗时的手动搜索。\n\nCode Graph Context项目正是为解决这一痛点而生。作为一个基于Model Context Protocol（MCP）的服务器，它通过构建代码库的语义图谱，赋予AI助手对整个系统的深度理解能力。\n\n## 核心概念：代码图谱的力量\n\n### 什么是代码图谱\n\n代码图谱是一种将代码库表示为图结构的技术。在这个图中：\n\n- 节点代表代码实体：类、函数、接口、变量、模块等\n- 边代表实体间的关系：导入、继承、调用、依赖等\n\n通过将代码库建模为图，我们可以利用图算法回答复杂的代码查询问题，如依赖分析、影响评估、代码搜索等。\n\n### 与传统代码分析的区别\n\n传统代码分析工具通常基于静态分析或简单的文本搜索，而Code Graph Context提供了更深层次的语义理解：\n\n| 传统方法 | Code Graph Context |\n|---------|-------------------|\n| 逐个文件阅读 | 理解整个依赖树 |\n| 手动搜索"谁使用了这个" | 即时影响分析，风险评分 |\n| 重构容易遗漏边界情况 | 图遍历找到每个引用 |\n| 大代码库超出上下文限制 | 语义搜索精确定位相关内容 |\n| 多文件修改容易出错 | 多智能体协调并行修改 |\n\n## 技术架构：从代码到图谱的转换\n\nCode Graph Context的技术架构包含三个核心层次：\n\n### 第一层：AST解析\n\n项目使用ts-morph库进行TypeScript抽象语法树（AST）解析。AST是代码的结构化表示，捕获了代码的语法结构而非仅仅是文本内容。通过AST分析，系统能够：\n\n- 识别类定义、方法声明、导入语句等语法结构\n- 提取类型信息、装饰器、泛型参数等元数据\n- 理解代码的模块组织和命名空间结构\n\n### 第二层：图谱存储\n\n解析后的AST信息被存储到Neo4j图数据库中。Neo4j是一个高性能的图数据库，专门优化了图遍历查询。存储的图谱包含：\n\n- 核心模式（Core Schema）：AST级别的节点类型，如ClassDeclaration、MethodDeclaration、ImportDeclaration等\n- 框架模式（Framework Schema）：语义解释层，如NestController、NestService、HttpEndpoint等\n\n这种双模式设计使系统既能保持AST级别的精确性，又能理解高层架构模式。\n\n### 第三层：向量嵌入\n\n除了结构化的图谱，系统还为代码实体生成向量嵌入。这些嵌入捕获了代码的语义信息，支持基于相似度的语义搜索。项目支持两种嵌入方式：\n\n- 本地嵌入：使用Python sidecar运行sentence-transformers模型，无需API密钥\n- OpenAI嵌入：使用OpenAI的嵌入API，质量更高但需要API密钥\n\n## 核心功能详解\n\n### 多项目支持\n\n系统支持在单一数据库中解析和查询多个项目，并保持完全隔离。这对于在微服务架构或多仓库环境中工作的团队尤为重要。\n\n### 语义搜索\n\n基于向量的语义搜索允许开发者用自然语言描述来查找代码，而非记忆文件路径：\n\n- "找到用户认证令牌验证的代码"\n- "显示数据库连接池逻辑"\n- "查找处理webhook签名验证的代码"\n\n### 影响分析\n\n在重构前评估风险是代码图谱的重要应用。系统可以：\n\n- 识别直接依赖者和传递依赖者\n- 计算风险等级（LOW/MEDIUM/HIGH/CRITICAL）\n- 展示依赖链的可视化图谱\n\n例如，分析UserService.findById()的修改影响：\n\n\n风险等级：HIGH\n\n直接依赖者（12个）：\n└── AuthController.login()\n└── ProfileController.getProfile()\n└── AdminService.getUserDetails()\n└── ... 9个更多\n\n传递依赖者（34个）：\n└── 8个控制器\n└── 15个服务\n└── 11个其他组件\n\n\n### 死代码检测\n\n系统能够识别未被引用的导出，并提供置信度评分。这有助于清理代码库，减少维护负担。\n\n### 重复代码检测\n\n通过AST哈希和嵌入相似度两种方法，系统可以检测结构重复和语义重复的代码，支持代码重构和抽象。\n\n### 增量解析与实时更新\n\n对于大型代码库，系统支持：\n\n- 增量解析：仅重新解析变更的文件\n- 文件监听：实时监测文件变化并更新图谱\n- 流式导入：对100+文件的项目进行分块处理\n- 并行解析：使用Worker线程进行多线程解析\n\n## 框架感知：NestJS支持\n\nCode Graph Context内置了对NestJS框架的深度支持，能够识别：\n\n- 控制器（Controllers）和HTTP端点\n- 服务（Services）及其依赖注入关系\n- 模块（Modules）和提供者（Providers）\n- DTO和数据验证装饰器\n\n更重要的是，系统支持自定义框架模式。通过定义自己的模式，开发者可以捕获领域特定的架构模式、装饰器和关系，使系统适应任何TypeScript框架或自定义架构。\n\n## 多智能体协调：Swarm模式\n\n项目创新性地引入了多智能体协调机制，支持"Swarm"模式：\n\n- pheromone（信息素）机制：智能体通过留下"信息素"标记来协调工作\n- 信息素衰减：旧的信息素逐渐消散，确保协调的动态性\n- 并行变更：多个智能体可以同时处理不同文件，通过信息素避免冲突\n\n这一机制使得大规模重构任务可以分解为多个并行子任务，由多个AI智能体协作完成。\n\n## 部署与使用\n\n### 安装与初始化\n\n项目提供了简单的安装流程：\n\nbash\nnpm install -g code-graph-context\ncode-graph-context init\n\n\ninit命令会自动处理：\n- 通过Docker启动Neo4j容器\n- 创建Python虚拟环境\n- 安装嵌入依赖（PyTorch、sentence-transformers）\n- 下载默认嵌入模型（约3GB）\n\n### 与Claude Code集成\n\n将服务器添加到Claude Code：\n\nbash\nclaude mcp add --scope user code-graph-context -- code-graph-context\n\n\n无需API密钥，重启Claude Code后即可使用。\n\n### 解析项目\n\n在Claude Code中，只需说：\n\n> "Parse this project and build the code graph"\n\nClaude会自动调用parse_typescript_project工具索引代码库。\n\n## 配置选项\n\n项目提供了丰富的环境变量配置：\n\n| 变量 | 必需 | 默认值 | 说明 |\n|-----|------|-------|------|\n| NEO4J_URI | 否 | bolt://localhost:7687 | Neo4j连接URI |\n| NEO4J_USER | 否 | neo4j | Neo4j用户名 |\n| NEO4J_PASSWORD | 否 | PASSWORD | Neo4j密码 |\n| EMBEDDING_MODEL | 否 | codesage/codesage-base-v2 | 本地嵌入模型 |\n| EMBEDDING_DEVICE | 否 | auto | 嵌入设备（自动检测MPS） |\n| OPENAI_EMBEDDINGS_ENABLED | 否 | false | 启用OpenAI嵌入 |\n| OPENAI_API_KEY | 条件 | - | OpenAI API密钥 |\n\n## 应用场景\n\n### 大型代码库导航\n\n对于拥有数百个文件的大型项目，开发者可以通过自然语言查询快速定位代码，无需记忆复杂的文件结构。\n\n### 安全重构\n\n在进行重大重构前，系统可以全面分析影响范围，识别潜在风险点，确保重构的安全性。\n\n### 代码审查辅助\n\n审查者可以利用代码图谱快速理解变更的上下文，评估修改的合理性和完整性。\n\n### 新成员入职\n\n新团队成员可以通过代码图谱快速理解系统架构，加速上手过程。\n\n### 技术债务管理\n\n通过死代码检测和重复代码识别，团队可以持续清理代码库，控制技术债务。\n\n## 局限性与未来方向\n\n### 当前局限\n\n- 语言支持：目前仅支持TypeScript，其他语言需要扩展\n- 资源需求：Neo4j和嵌入模型需要一定的计算资源\n- 初始设置：首次解析大型项目可能需要较长时间\n\n### 未来方向\n\n- 支持更多编程语言（Python、Java、Go等）\n- 集成更多IDE和编辑器\n- 开发可视化界面展示代码图谱\n- 支持更复杂的架构模式识别\n\n## 结语\n\nCode Graph Context项目代表了AI辅助编程向更深层次代码理解演进的重要一步。通过构建代码库的语义图谱，它不仅解决了AI助手"只见树木不见森林"的问题，还为代码分析、重构和协作开辟了新的可能性。随着代码库规模不断增长和架构日益复杂，这种基于图谱的代码理解方法将成为开发者工具箱中的重要组成部分。

引言：AI编程助手的上下文困境\n\n随着GitHub Copilot、Claude Code等AI编程助手的普及，开发者已经习惯了让AI帮助编写代码。然而，一个根本性的限制始终存在：AI助手通常只能"看到"当前正在编辑的文件，对整个代码库的全貌缺乏理解。当你问"哪些服务依赖于UserService"或"修改这个函数的波及范围有多大"时，传统AI助手往往无能为力，只能进行耗时的手动搜索。\n\nCode Graph Context项目正是为解决这一痛点而生。作为一个基于Model Context Protocol（MCP）的服务器，它通过构建代码库的语义图谱，赋予AI助手对整个系统的深度理解能力。\n\n核心概念：代码图谱的力量\n\n什么是代码图谱\n\n代码图谱是一种将代码库表示为图结构的技术。在这个图中：\n\n- 节点代表代码实体：类、函数、接口、变量、模块等\n- 边代表实体间的关系：导入、继承、调用、依赖等\n\n通过将代码库建模为图，我们可以利用图算法回答复杂的代码查询问题，如依赖分析、影响评估、代码搜索等。\n\n与传统代码分析的区别\n\n传统代码分析工具通常基于静态分析或简单的文本搜索，而Code Graph Context提供了更深层次的语义理解：\n\n| 传统方法 | Code Graph Context |\n|---------|-------------------|\n| 逐个文件阅读 | 理解整个依赖树 |\n| 手动搜索"谁使用了这个" | 即时影响分析，风险评分 |\n| 重构容易遗漏边界情况 | 图遍历找到每个引用 |\n| 大代码库超出上下文限制 | 语义搜索精确定位相关内容 |\n| 多文件修改容易出错 | 多智能体协调并行修改 |\n\n技术架构：从代码到图谱的转换\n\nCode Graph Context的技术架构包含三个核心层次：\n\n第一层：AST解析\n\n项目使用ts-morph库进行TypeScript抽象语法树（AST）解析。AST是代码的结构化表示，捕获了代码的语法结构而非仅仅是文本内容。通过AST分析，系统能够：\n\n- 识别类定义、方法声明、导入语句等语法结构\n- 提取类型信息、装饰器、泛型参数等元数据\n- 理解代码的模块组织和命名空间结构\n\n第二层：图谱存储\n\n解析后的AST信息被存储到Neo4j图数据库中。Neo4j是一个高性能的图数据库，专门优化了图遍历查询。存储的图谱包含：\n\n- 核心模式（Core Schema）：AST级别的节点类型，如ClassDeclaration、MethodDeclaration、ImportDeclaration等\n- 框架模式（Framework Schema）：语义解释层，如NestController、NestService、HttpEndpoint等\n\n这种双模式设计使系统既能保持AST级别的精确性，又能理解高层架构模式。\n\n第三层：向量嵌入\n\n除了结构化的图谱，系统还为代码实体生成向量嵌入。这些嵌入捕获了代码的语义信息，支持基于相似度的语义搜索。项目支持两种嵌入方式：\n\n- 本地嵌入：使用Python sidecar运行sentence-transformers模型，无需API密钥\n- OpenAI嵌入：使用OpenAI的嵌入API，质量更高但需要API密钥\n\n核心功能详解\n\n多项目支持\n\n系统支持在单一数据库中解析和查询多个项目，并保持完全隔离。这对于在微服务架构或多仓库环境中工作的团队尤为重要。\n\n语义搜索\n\n基于向量的语义搜索允许开发者用自然语言描述来查找代码，而非记忆文件路径：\n\n- "找到用户认证令牌验证的代码"\n- "显示数据库连接池逻辑"\n- "查找处理webhook签名验证的代码"\n\n影响分析\n\n在重构前评估风险是代码图谱的重要应用。系统可以：\n\n- 识别直接依赖者和传递依赖者\n- 计算风险等级（LOW/MEDIUM/HIGH/CRITICAL）\n- 展示依赖链的可视化图谱\n\n例如，分析UserService.findById()的修改影响：\n\n\n风险等级：HIGH\n\n直接依赖者（12个）：\n└── AuthController.login()\n└── ProfileController.getProfile()\n└── AdminService.getUserDetails()\n└── ... 9个更多\n\n传递依赖者（34个）：\n└── 8个控制器\n└── 15个服务\n└── 11个其他组件\n\n\n死代码检测\n\n系统能够识别未被引用的导出，并提供置信度评分。这有助于清理代码库，减少维护负担。\n\n重复代码检测\n\n通过AST哈希和嵌入相似度两种方法，系统可以检测结构重复和语义重复的代码，支持代码重构和抽象。\n\n增量解析与实时更新\n\n对于大型代码库，系统支持：\n\n- 增量解析：仅重新解析变更的文件\n- 文件监听：实时监测文件变化并更新图谱\n- 流式导入：对100+文件的项目进行分块处理\n- 并行解析：使用Worker线程进行多线程解析\n\n框架感知：NestJS支持\n\nCode Graph Context内置了对NestJS框架的深度支持，能够识别：\n\n- 控制器（Controllers）和HTTP端点\n- 服务（Services）及其依赖注入关系\n- 模块（Modules）和提供者（Providers）\n- DTO和数据验证装饰器\n\n更重要的是，系统支持自定义框架模式。通过定义自己的模式，开发者可以捕获领域特定的架构模式、装饰器和关系，使系统适应任何TypeScript框架或自定义架构。\n\n多智能体协调：Swarm模式\n\n项目创新性地引入了多智能体协调机制，支持"Swarm"模式：\n\n- pheromone（信息素）机制：智能体通过留下"信息素"标记来协调工作\n- 信息素衰减：旧的信息素逐渐消散，确保协调的动态性\n- 并行变更：多个智能体可以同时处理不同文件，通过信息素避免冲突\n\n这一机制使得大规模重构任务可以分解为多个并行子任务，由多个AI智能体协作完成。\n\n部署与使用\n\n安装与初始化\n\n项目提供了简单的安装流程：\n\nbash\nnpm install -g code-graph-context\ncode-graph-context init\n\n\ninit命令会自动处理：\n- 通过Docker启动Neo4j容器\n- 创建Python虚拟环境\n- 安装嵌入依赖（PyTorch、sentence-transformers）\n- 下载默认嵌入模型（约3GB）\n\n与Claude Code集成\n\n将服务器添加到Claude Code：\n\nbash\nclaude mcp add --scope user code-graph-context -- code-graph-context\n\n\n无需API密钥，重启Claude Code后即可使用。\n\n解析项目\n\n在Claude Code中，只需说：\n\n> "Parse this project and build the code graph"\n\nClaude会自动调用parse_typescript_project工具索引代码库。\n\n配置选项\n\n项目提供了丰富的环境变量配置：\n\n| 变量 | 必需 | 默认值 | 说明 |\n|-----|------|-------|------|\n| NEO4J_URI | 否 | bolt://localhost:7687 | Neo4j连接URI |\n| NEO4J_USER | 否 | neo4j | Neo4j用户名 |\n| NEO4J_PASSWORD | 否 | PASSWORD | Neo4j密码 |\n| EMBEDDING_MODEL | 否 | codesage/codesage-base-v2 | 本地嵌入模型 |\n| EMBEDDING_DEVICE | 否 | auto | 嵌入设备（自动检测MPS） |\n| OPENAI_EMBEDDINGS_ENABLED | 否 | false | 启用OpenAI嵌入 |\n| OPENAI_API_KEY | 条件 | - | OpenAI API密钥 |\n\n应用场景\n\n大型代码库导航\n\n对于拥有数百个文件的大型项目，开发者可以通过自然语言查询快速定位代码，无需记忆复杂的文件结构。\n\n安全重构\n\n在进行重大重构前，系统可以全面分析影响范围，识别潜在风险点，确保重构的安全性。\n\n代码审查辅助\n\n审查者可以利用代码图谱快速理解变更的上下文，评估修改的合理性和完整性。\n\n新成员入职\n\n新团队成员可以通过代码图谱快速理解系统架构，加速上手过程。\n\n技术债务管理\n\n通过死代码检测和重复代码识别，团队可以持续清理代码库，控制技术债务。\n\n局限性与未来方向\n\n当前局限\n\n- 语言支持：目前仅支持TypeScript，其他语言需要扩展\n- 资源需求：Neo4j和嵌入模型需要一定的计算资源\n- 初始设置：首次解析大型项目可能需要较长时间\n\n未来方向\n\n- 支持更多编程语言（Python、Java、Go等）\n- 集成更多IDE和编辑器\n- 开发可视化界面展示代码图谱\n- 支持更复杂的架构模式识别\n\n结语\n\nCode Graph Context项目代表了AI辅助编程向更深层次代码理解演进的重要一步。通过构建代码库的语义图谱，它不仅解决了AI助手"只见树木不见森林"的问题，还为代码分析、重构和协作开辟了新的可能性。随着代码库规模不断增长和架构日益复杂，这种基于图谱的代码理解方法将成为开发者工具箱中的重要组成部分。