夜雨聆风https://github.com/colbymchenry/codegraph
它的核心作用是什么？
当 AI 助手在大型项目中探索代码时，通常会像人类一样使用 grep、find 或逐个读取文件来寻找上下文。这种方式不仅极其耗时，还会消耗大量的 Token。
CodeGraph 通过提前扫描整个代码库，将其转换为包含代码符号（函数、类、变量）、调用图和代码结构的语义知识图谱，并保存在本地的 SQLite 数据库中。这样，AI 在分析复杂后端架构或尝试梳理系统调用链路时，可以直接通过 MCP（Model Context Protocol）工具瞬间查询图谱，而无需盲目地扫描文件。
主要特性
大幅降低 Token 与时间消耗：官方基准测试显示，在执行复杂的代码库提问时，它平均能减少约 92% 的工具调用，并将 AI 探索代码的速度提升 70% 以上。
完美适配终端工作流：它可以在你的集成开发环境（比如 GoLand 的 Terminal）中通过一行 npx 命令快速安装。它与 Claude Code 的集成尤为顺畅，会自动为项目注入必要的底层系统提示词。
支持 19+ 种编程语言：底层基于 tree-sitter 解析 AST，全面支持 Golang、Python、Java、TypeScript 等主流语言。跨语言的项目也能顺畅追踪依赖。
后端框架路由感知：能够自动识别常见后端 Web 框架的路由文件，将 URL 路径直接映射到对应的 Handler 函数或控制器上。
完全本地化与实时同步：所有解析和存储都在本地机器上完成，零数据泄露风险。同时，它利用操作系统的原生文件系统事件（如 macOS 的 FSEvents）进行无感知的实时同步，你敲击代码的同时，知识图谱就在后台自动更新。
实际应用场景
如果你经常编写复杂的 Prompt，让 AI “扮演架构师”根据源码自动推导并生成诸如 agent.md 这类的全局架构参考指南，或是输出高层设计（HLD）、底层设计（LLD）等技术规格说明书，CodeGraph 能够为 AI 提供极具结构化的全局视野。
它提供的工具（如 codegraph_impact 和 codegraph_callers）支持直接追踪代码的影响范围和跨层调用栈。这意味着 AI 可以瞬间获取“从 API 路由层一直追踪到数据库调用层”的完整上下文，从而生成更准确、更具深度的架构文档。
这份详细使用手册基于 CodeGraph 的官方文档提取，涵盖了从快速安装、项目初始化到命令行工具（CLI）使用的完整工作流。你完全可以直接在 GoLand 的内置终端中执行这些步骤。
一、 快速启动（推荐）
最简单的方式是通过 npx 运行交互式安装脚本，它会自动完成大部分配置工作。
1. 运行安装程序 在终端中执行以下命令：
npx @colbymchenry/codegraph
安装程序会引导你完成以下步骤：
自动检测你系统中已安装的 AI 助手（如 Claude Code、Cursor、Codex CLI 等）。
询问是否将 codegraph 安装到系统的 PATH 中（确保 AI 助手能顺利启动 MCP 服务）。
询问配置是应用于“全局”还是仅当前“本地项目”。
自动为选中的 AI 助手写入 MCP 服务器配置和系统提示词文件（例如 Claude 的 CLAUDE.md 或 Cursor 的 .cursor/rules/codegraph.mdc）。
如果你主要使用 Claude Code，它还会帮你设置工具的自动允许（Auto-allow）权限。
2. 重启 AI 助手 完成安装后，彻底关闭并重启你的 AI 助手（如重启 Claude Code 或 Cursor），以便它们加载刚刚配置好的 MCP 服务。
3. 初始化你的代码项目 进入你需要分析的代码仓库目录，执行初始化：
cd your-project
codegraph init -i
这会在当前项目中构建代码知识图谱索引，并生成一个 .codegraph/ 隐藏目录。只要该目录存在，你的 AI 助手就会自动利用图谱工具来探索代码。
二、 手动安装与配置（以 Claude Code 为例）
如果你更喜欢手动掌控配置细节，或者想在特定的 macOS 环境下自定义安装，可以按照以下步骤操作：
1. 全局安装
npm install -g @colbymchenry/codegraph
2. 配置 MCP 服务器 编辑或创建 ~/.claude.json 文件，将 CodeGraph 注册为 MCP 服务：
{
"mcpServers": {
"codegraph": {
"type": "stdio",
"command": "codegraph",
"args": ["serve", "--mcp"]
}
}
}
3. 配置自动权限（可选） 为了避免 Claude 每次调用工具时都弹窗询问，可以在 ~/.claude/settings.json 中添加权限白名单：
{
"permissions": {
"allow": [
"mcp__codegraph__codegraph_search",
"mcp__codegraph__codegraph_context",
"mcp__codegraph__codegraph_callers",
"mcp__codegraph__codegraph_callees",
"mcp__codegraph__codegraph_impact",
"mcp__codegraph__codegraph_node",
"mcp__codegraph__codegraph_status",
"mcp__codegraph__codegraph_files"
]
}
}
三、 核心 CLI 命令详解
除了配合 AI 助手，CodeGraph 本身也是一个强大的命令行工具，非常适合在重构后端架构或排查跨层调用时手动执行查询。
基础管理
codegraph init [path]：在项目中初始化并建立索引（加 --index 参数立即索引）。
codegraph uninit [path]：从项目中移除 CodeGraph。
codegraph status [path]：查看当前索引的健康状态和统计信息（例如索引了多少个节点和文件）。
数据同步
codegraph index [path]：执行全量重新索引。
codegraph sync [path]：执行增量更新（通常 CodeGraph 会利用操作系统的原生文件事件在后台自动静默同步，但在必要时可手动触发）。
代码查询
codegraph query <search>：在整个代码库中全局搜索函数、类或变量等代码符号。
codegraph context <task>：为特定的开发任务（task）自动组装相关的代码上下文。
codegraph files [path]：快速展示已索引的文件结构，比使用 ls 或 find 扫描文件系统快得多。
依赖与影响分析（极具实用性）
codegraph affected [files...]：追踪依赖关系，找出修改了某几个源文件后，哪些测试文件会受到影响。这对于保障后端稳定性非常有帮助。
示例：结合 Git 使用，找出当前修改影响了哪些测试文件： git diff --name-only HEAD | codegraph affected --stdin --quiet
四、 AI 助手的最佳实践逻辑
当 CodeGraph 就绪后，系统会默认给 AI 注入一套交互规则。了解这些规则有助于你更好地设计 Prompt：
探索模式 (Explore)：面对宏观问题（如“解释 Kafka 消息队列的消费逻辑是如何实现的？”），AI 会启动一个“探索代理”。该代理首选调用 codegraph_explore 工具，一次性拉取整个调用链条的源码上下文，彻底避免低效的全局文本正则匹配 (grep)。
精准模式 (Targeted)：对于主会话中的微观操作，AI 会使用轻量级工具：
codegraph_callers / codegraph_callees：追踪谁调用了这个函数，或者这个函数调用了谁。
codegraph_impact：在修改核心业务逻辑或数据库接口前，确认修改的“爆炸半径”。
codegraph_node：精确获取某个具体符号的定义细节。
