codegraph是目前最成熟的本地代码知识图谱引擎专为解决AI编码代理反复扫描文件、Token消耗爆炸、上下文混乱的行业痛点而生。它预先将任意代码库构建为可交互的结构化知识图谱让Claude Code、Gemini、Cursor等8主流AI工具直接查询代码结构而非逐行扫描文件平均节省60-90% Token消耗同时大幅提升AI回答的准确性和响应速度且所有操作100%在本地完成代码永不泄露。一、项目核心信息项目地址github.com/colbymchenry/codegraph开发语言TypeScript核心定位预索引代码知识图谱为所有主流AI编码工具提供代码结构感知能力三大核心功能自动知识图谱构建将任意代码库转为可搜索、可问答的交互式知识图谱极致成本优化预索引机制消除AI对代码库的重复扫描节省60-90% Token消耗全平台兼容原生支持Claude Code、Codex、Cursor、Gemini、OpenCode等8主流编码代理适用场景AI编码代理增强、大型代码库维护、团队知识管理、开发者效率提升、遗留系统现代化二、环境要求Node.js18.17.0 版本推荐20.x LTS兼容性最佳包管理器npm 9 或 pnpm 8pnpm速度更快推荐使用支持的AI客户端✅ Claude Code原生集成体验最佳✅ Cursor 0.45✅ Google Gemini CLI✅ GitHub CopilotVS Code扩展✅ OpenCode✅ DeepSeek-TUI✅ Windsurf 1.5✅ JetBrains AI Assistant支持的编程语言TypeScript/JavaScript、Python、Java、C/C、Rust、Go、C#、PHP操作系统Windows 10/11、macOS 12、Linux(Ubuntu 22.04)硬件要求8GB以上内存推荐16GB索引10万行代码约需1GB磁盘空间三、安装方法3种方案方案1NPM全局安装推荐所有用户# 使用pnpm安装推荐pnpmadd-gcodegraph/cli# 使用npm安装npminstall-gcodegraph/cli# 验证安装codegraph--version方案2VS Code扩展一键安装打开VS Code扩展市场搜索codegraph点击安装安装完成后会自动配置CLI工具和环境变量方案3从源码编译开发者/自定义修改gitclone https://github.com/colbymchenry/codegraph.gitcdcodegraphpnpminstallpnpmbuildpnpmlink--global四、初始配置与索引生成1. 全局配置首次使用前配置你常用的大模型API密钥# 打开配置文件codegraph config edit在配置文件中添加你的API密钥# 默认模型推荐Claude 3.5 Sonnet知识图谱构建效果最佳defaultModel:claude-3-5-sonnet-20240620# 支持的模型列表models:claude-3-5-sonnet:apiKey:your-anthropic-api-keygpt-4o:apiKey:your-openai-api-keygemini-1.5-pro:apiKey:your-google-api-keydeepseek-v4:apiKey:your-deepseek-api-key2. 生成项目索引核心步骤进入你的项目根目录运行以下命令生成代码知识图谱# 生成当前项目的完整索引codegraph index# 只索引指定目录codegraph index src/ include/# 排除不需要的目录推荐codegraph index--excludenode_modules/ build/ dist/ third_party/# 强制重新生成所有索引codegraph index--force# 显示详细索引过程codegraph index--verbose索引时间参考小型项目(1万行)10-30秒中型项目(1-10万行)1-5分钟大型项目(10-100万行)5-30分钟超大型项目(100万行)30分钟以上五、核心功能使用1. 与AI编码代理无缝集成这是codegraph最强大的功能集成后AI会自动使用知识图谱回答问题无需任何额外操作。Claude Code原生集成无需配置Claude Code会自动检测项目中的codegraph索引当你询问关于代码库的问题时它会优先查询知识图谱而不是扫描文件。Cursor 集成打开Cursor设置 → AI → 高级设置开启「Enable codegraph integration」重启Cursor即可生效Gemini CLI 集成# 生成Gemini配置文件codegraph integrate gemini# 启动带codegraph支持的Geminicodegraph run gemini其他AI客户端# 通用集成命令会生成对应客户端的配置codegraph integrate[client-name]# 支持的客户端copilot, opencode, deepseek, windsurf, jetbrains2. 命令行直接查询你可以直接在终端中查询代码知识图谱无需打开AI客户端# 查询函数的所有调用位置codegraph queryfind all calls to the init_uart function# 查询类的继承关系codegraph queryshow the inheritance tree of the GPIO_Driver class# 查询所有使用了某个库的文件codegraph querywhich files import the HAL library# 生成项目架构概述codegraph querydescribe the overall architecture of this project# 查找可能的Bugcodegraph queryfind potential memory leaks in the codebase3. 交互式Web界面启动Web界面可视化探索代码知识图谱# 启动Web服务器默认端口3000codegraph serve# 指定端口codegraph serve--port8080访问http://localhost:3000即可打开交互式界面你可以查看项目的整体架构图浏览所有类、函数和变量的详细信息可视化函数调用链和数据流向进行语义搜索和自然语言问答导出图谱为图片或PDF文件六、性能与成本优化效果官方在多个不同规模的项目上进行了实测结果如下项目规模无codegraph平均Token有codegraph平均Token节省比例响应时间提升小型(1万行)2,10042080%65%中型(10万行)12,4003,10075%58%大型(50万行)48,70019,50060%52%超大型(200万行)186,00018,60090%78%平均效果节省60-90% Token消耗减少70%以上的工具调用次数响应速度提升50-80%。七、高级使用技巧1. 增量索引与自动更新# 只索引修改过的文件大幅节省时间codegraph index--incremental# 自动监控文件变化实时更新索引codegraphwatch# 设置自动更新间隔单位分钟codegraph configsetauto_update_interval302. 多项目管理# 列出所有已索引的项目codegraph projects list# 切换到另一个项目codegraph projects switch my-embedded-project# 导出项目索引与团队共享codegraphexportstm32-driver-index.cg# 导入团队共享的索引codegraphimportstm32-driver-index.cg3. 零文件读取模式对于高度敏感的代码库可以开启零文件读取模式让AI完全依赖索引回答问题永远不会读取任何实际代码文件# 开启零文件读取模式codegraph configsetzero_file_readtrue# 关闭零文件读取模式codegraph configsetzero_file_readfalse4. 自定义索引规则在项目根目录创建codegraph.config.json文件自定义索引行为{include:[src/**/*.c,src/**/*.h,drivers/**/*.c],exclude:[**/test/**,**/examples/**,**/build/**],indexer:{c:{enableMacroExpansion:true,maxDepth:10}}}八、常见问题与解决方案索引生成失败检查Node.js版本是否≥18.17.0增加Node.js内存限制export NODE_OPTIONS--max-old-space-size16384排除大型第三方库和二进制文件目录尝试使用--force参数强制重新生成AI不使用codegraph索引确认AI客户端版本支持codegraph集成重启AI客户端重新生成索引codegraph index --force在提问时明确要求使用codegraph索引回答这个问题查询结果不准确运行增量更新codegraph index --incremental切换到能力更强的模型如Claude 3.5 Sonnet使用更具体的查询语句查看详细日志codegraph config set log_level debug性能问题使用SSD存储索引文件升级到16GB以上内存分模块索引大型项目关闭不必要的后台应用九、重要注意事项绝对隐私所有代码分析、索引生成和查询都100%在本地完成你的代码永远不会上传到任何服务器完全符合企业和军工级安全要求定期更新项目处于高速开发阶段建议每周运行一次npm update -g codegraph/cli获取最新功能和性能优化大型项目最佳实践对于超过100万行的项目建议先索引核心模块再逐步扩展到其他模块团队协作可以将索引文件导出共享给团队成员避免每个人都重复构建索引节省大量时间开源协议本项目采用MIT许可证可以自由用于个人和商业项目社区支持遇到问题可以在GitHub Issues提交作者响应非常及时平均24小时内回复
【AI开源】codegraph 完整使用教程（2026最新版）
发布时间：2026/5/27 18:35:30
codegraph是目前最成熟的本地代码知识图谱引擎专为解决AI编码代理反复扫描文件、Token消耗爆炸、上下文混乱的行业痛点而生。它预先将任意代码库构建为可交互的结构化知识图谱让Claude Code、Gemini、Cursor等8主流AI工具直接查询代码结构而非逐行扫描文件平均节省60-90% Token消耗同时大幅提升AI回答的准确性和响应速度且所有操作100%在本地完成代码永不泄露。一、项目核心信息项目地址github.com/colbymchenry/codegraph开发语言TypeScript核心定位预索引代码知识图谱为所有主流AI编码工具提供代码结构感知能力三大核心功能自动知识图谱构建将任意代码库转为可搜索、可问答的交互式知识图谱极致成本优化预索引机制消除AI对代码库的重复扫描节省60-90% Token消耗全平台兼容原生支持Claude Code、Codex、Cursor、Gemini、OpenCode等8主流编码代理适用场景AI编码代理增强、大型代码库维护、团队知识管理、开发者效率提升、遗留系统现代化二、环境要求Node.js18.17.0 版本推荐20.x LTS兼容性最佳包管理器npm 9 或 pnpm 8pnpm速度更快推荐使用支持的AI客户端✅ Claude Code原生集成体验最佳✅ Cursor 0.45✅ Google Gemini CLI✅ GitHub CopilotVS Code扩展✅ OpenCode✅ DeepSeek-TUI✅ Windsurf 1.5✅ JetBrains AI Assistant支持的编程语言TypeScript/JavaScript、Python、Java、C/C、Rust、Go、C#、PHP操作系统Windows 10/11、macOS 12、Linux(Ubuntu 22.04)硬件要求8GB以上内存推荐16GB索引10万行代码约需1GB磁盘空间三、安装方法3种方案方案1NPM全局安装推荐所有用户# 使用pnpm安装推荐pnpmadd-gcodegraph/cli# 使用npm安装npminstall-gcodegraph/cli# 验证安装codegraph--version方案2VS Code扩展一键安装打开VS Code扩展市场搜索codegraph点击安装安装完成后会自动配置CLI工具和环境变量方案3从源码编译开发者/自定义修改gitclone https://github.com/colbymchenry/codegraph.gitcdcodegraphpnpminstallpnpmbuildpnpmlink--global四、初始配置与索引生成1. 全局配置首次使用前配置你常用的大模型API密钥# 打开配置文件codegraph config edit在配置文件中添加你的API密钥# 默认模型推荐Claude 3.5 Sonnet知识图谱构建效果最佳defaultModel:claude-3-5-sonnet-20240620# 支持的模型列表models:claude-3-5-sonnet:apiKey:your-anthropic-api-keygpt-4o:apiKey:your-openai-api-keygemini-1.5-pro:apiKey:your-google-api-keydeepseek-v4:apiKey:your-deepseek-api-key2. 生成项目索引核心步骤进入你的项目根目录运行以下命令生成代码知识图谱# 生成当前项目的完整索引codegraph index# 只索引指定目录codegraph index src/ include/# 排除不需要的目录推荐codegraph index--excludenode_modules/ build/ dist/ third_party/# 强制重新生成所有索引codegraph index--force# 显示详细索引过程codegraph index--verbose索引时间参考小型项目(1万行)10-30秒中型项目(1-10万行)1-5分钟大型项目(10-100万行)5-30分钟超大型项目(100万行)30分钟以上五、核心功能使用1. 与AI编码代理无缝集成这是codegraph最强大的功能集成后AI会自动使用知识图谱回答问题无需任何额外操作。Claude Code原生集成无需配置Claude Code会自动检测项目中的codegraph索引当你询问关于代码库的问题时它会优先查询知识图谱而不是扫描文件。Cursor 集成打开Cursor设置 → AI → 高级设置开启「Enable codegraph integration」重启Cursor即可生效Gemini CLI 集成# 生成Gemini配置文件codegraph integrate gemini# 启动带codegraph支持的Geminicodegraph run gemini其他AI客户端# 通用集成命令会生成对应客户端的配置codegraph integrate[client-name]# 支持的客户端copilot, opencode, deepseek, windsurf, jetbrains2. 命令行直接查询你可以直接在终端中查询代码知识图谱无需打开AI客户端# 查询函数的所有调用位置codegraph queryfind all calls to the init_uart function# 查询类的继承关系codegraph queryshow the inheritance tree of the GPIO_Driver class# 查询所有使用了某个库的文件codegraph querywhich files import the HAL library# 生成项目架构概述codegraph querydescribe the overall architecture of this project# 查找可能的Bugcodegraph queryfind potential memory leaks in the codebase3. 交互式Web界面启动Web界面可视化探索代码知识图谱# 启动Web服务器默认端口3000codegraph serve# 指定端口codegraph serve--port8080访问http://localhost:3000即可打开交互式界面你可以查看项目的整体架构图浏览所有类、函数和变量的详细信息可视化函数调用链和数据流向进行语义搜索和自然语言问答导出图谱为图片或PDF文件六、性能与成本优化效果官方在多个不同规模的项目上进行了实测结果如下项目规模无codegraph平均Token有codegraph平均Token节省比例响应时间提升小型(1万行)2,10042080%65%中型(10万行)12,4003,10075%58%大型(50万行)48,70019,50060%52%超大型(200万行)186,00018,60090%78%平均效果节省60-90% Token消耗减少70%以上的工具调用次数响应速度提升50-80%。七、高级使用技巧1. 增量索引与自动更新# 只索引修改过的文件大幅节省时间codegraph index--incremental# 自动监控文件变化实时更新索引codegraphwatch# 设置自动更新间隔单位分钟codegraph configsetauto_update_interval302. 多项目管理# 列出所有已索引的项目codegraph projects list# 切换到另一个项目codegraph projects switch my-embedded-project# 导出项目索引与团队共享codegraphexportstm32-driver-index.cg# 导入团队共享的索引codegraphimportstm32-driver-index.cg3. 零文件读取模式对于高度敏感的代码库可以开启零文件读取模式让AI完全依赖索引回答问题永远不会读取任何实际代码文件# 开启零文件读取模式codegraph configsetzero_file_readtrue# 关闭零文件读取模式codegraph configsetzero_file_readfalse4. 自定义索引规则在项目根目录创建codegraph.config.json文件自定义索引行为{include:[src/**/*.c,src/**/*.h,drivers/**/*.c],exclude:[**/test/**,**/examples/**,**/build/**],indexer:{c:{enableMacroExpansion:true,maxDepth:10}}}八、常见问题与解决方案索引生成失败检查Node.js版本是否≥18.17.0增加Node.js内存限制export NODE_OPTIONS--max-old-space-size16384排除大型第三方库和二进制文件目录尝试使用--force参数强制重新生成AI不使用codegraph索引确认AI客户端版本支持codegraph集成重启AI客户端重新生成索引codegraph index --force在提问时明确要求使用codegraph索引回答这个问题查询结果不准确运行增量更新codegraph index --incremental切换到能力更强的模型如Claude 3.5 Sonnet使用更具体的查询语句查看详细日志codegraph config set log_level debug性能问题使用SSD存储索引文件升级到16GB以上内存分模块索引大型项目关闭不必要的后台应用九、重要注意事项绝对隐私所有代码分析、索引生成和查询都100%在本地完成你的代码永远不会上传到任何服务器完全符合企业和军工级安全要求定期更新项目处于高速开发阶段建议每周运行一次npm update -g codegraph/cli获取最新功能和性能优化大型项目最佳实践对于超过100万行的项目建议先索引核心模块再逐步扩展到其他模块团队协作可以将索引文件导出共享给团队成员避免每个人都重复构建索引节省大量时间开源协议本项目采用MIT许可证可以自由用于个人和商业项目社区支持遇到问题可以在GitHub Issues提交作者响应非常及时平均24小时内回复
