CodeGraph：为AI编程助手构建代码知识图谱，实现深度代码理解

1. 项目概述：从代码搜索到代码理解

如果你用过 Claude Code、Cursor 或者任何支持 MCP 协议的 AI 编程助手，肯定遇到过这样的场景：你问它“这个UserService被哪些地方调用了？”，它要么得花上几千个 token 去遍历你的整个项目目录，要么就干脆告诉你“我无法访问你的代码库”。即便它能读取文件，也像是在一个漆黑的房间里摸黑找东西——它只能看到你当前打开的那一两个文件，对整个项目的架构、模块间的依赖关系、函数的调用链路一无所知。这种“盲人摸象”式的交互，极大地限制了 AI 助手在复杂项目重构、影响分析或架构理解上的潜力。

CodeGraph 就是为了解决这个问题而生的。它不是一个简单的代码搜索引擎，而是一个代码知识图谱引擎。它的核心思想非常直接：把你的整个代码库，解析成一个包含节点（函数、类、模块、变量）和边（调用、继承、依赖、引用）的图结构，并辅以语义向量嵌入。这样一来，当你的 AI 助手需要理解代码时，它不再需要“grep”或“猜测”，而是可以直接对这个知识图谱进行查询和推理。

想象一下，你的 AI 助手拥有了一个关于你代码的“全局记忆”。当它需要分析修改PaymentProcessor的影响时，它可以直接调用一个agentic_impact工具，这个工具会在图谱中执行一次依赖链追踪，精确地返回所有直接和间接依赖该模块的文件、函数，甚至计算出耦合度指标。这不仅仅是搜索，这是真正的理解。

我花了相当长的时间去配置和测试各种代码索引工具，从传统的ctags、ripgrep配合语义搜索，到一些基于 RAG 的早期方案，它们要么太“浅”（只能做文本匹配），要么太“笨”（无法理解代码的语义和结构）。CodeGraph 的独特之处在于它“图+向量”的双引擎设计，以及那套开箱即用的智能体工具。它把复杂的图遍历、语义匹配和结果合成逻辑封装成了几个简单的工具调用，让你的 AI 助手能像调用一个普通 API 一样，获得深度的代码洞察。

2. 核心架构与设计哲学拆解

2.1 为什么是“图”，而不仅仅是“向量”？

市面上大多数“语义代码搜索”方案，其核心是向量化。它们把代码片段（比如函数体、类定义）转换成高维向量，然后通过计算向量相似度来找到“语义上接近”的代码。这有用，但存在根本性缺陷。

缺陷一：丢失结构信息。一个calculateTotal函数和调用它的processOrder函数在向量空间里可能离得很远，尽管它们在逻辑上紧密相连。纯向量搜索无法回答“谁调用了这个函数？”或“这个类的子类有哪些？”这类结构性问题。

缺陷二：上下文缺失。即使搜索到了User类，你也不知道它属于哪个模块（models/还是entities/？），它导出了哪些方法，又被哪些外部服务依赖。这些信息对于理解代码在架构中的位置至关重要。

CodeGraph 的解决方案是构建一个真实的知识图谱。它的索引管道（Your Code → Build Context → AST + FastML → LSP Resolution → Enrichment → Graph + Embeddings）确保了图谱的丰富性：

1. AST 解析：通过 tree-sitter 生成语法树，提取出基础的代码实体（节点）和关系（边），如函数定义、类继承。
2. LSP 解析：利用语言服务器协议（如rust-analyzer,pyright）进行更精确的符号解析。这能解决 AST 解析的局限性，比如准确识别跨文件的类型定义、引用和跳转。
3. 图谱增强：这一步是精髓。它会添加模块节点、模块间的导入和包含关系、基于数据流的边（如defines,uses,flows_to），甚至将文档中的符号链接进来。最终形成的图谱，不仅包含代码“是什么”，还包含代码“如何连接”和“如何流动”。

当进行搜索时，CodeGraph 执行的是混合搜索：70% 的权重给向量相似度（找语义相关的代码），30% 给词法搜索（找精确匹配的标识符），并且所有这些操作都在图谱的上下文中进行。搜索结果不是一个孤立的代码片段列表，而是一个带着完整关系网络的子图。

2.2 智能体工具层：封装复杂性的艺术

这是 CodeGraph 最让我欣赏的设计。它没有暴露复杂的图查询语言给最终用户（或 AI），而是提供了四个高度抽象的“智能体工具”。每个工具背后，都是一个微型的规划-执行-合成智能体。

以agentic_impact为例，当 AI 助手调用它查询“UserService”时，内部发生的事远不止一次搜索：

1. 规划：智能体判断这是一个“影响分析”类查询。
2. 执行链： a. 首先，在图谱中语义搜索UserService节点。 b. 获取该节点的所有直接依赖边（depends_on）。 c. 执行传递闭包查询，找出所有间接依赖。 d. 同时，反向查找哪些节点依赖UserService（被调用者）。 e. 检查这些依赖关系中是否存在循环依赖（cycle_detection）。 f. 计算相关模块的耦合度指标。 g. 识别出图谱中的“枢纽节点”（被大量依赖的关键模块），评估其受影响风险。
3. 合成：将以上所有步骤的结果（文件路径、行号、代码片段、分析结论）整合成一份结构化的 JSON 报告，并附上“下一步建议”。

这个过程，如果让 AI 助手自己通过多次文件读取和逻辑推理来完成，会消耗巨大的上下文窗口，且容易出错。CodeGraph 将这些认知负载转移到了自己优化的图谱查询引擎中，AI 助手只需消耗少量 token 来发起工具调用和接收精炼后的结果，从而能将宝贵的上下文预算留给真正的任务：编写和修改代码。

2.3 分层索引与上下文感知：务实的设计选择

不是所有项目都需要同样深度的分析。为此，CodeGraph 引入了索引分层机制：

• fast（快速）：仅进行基础的 AST 解析，生成节点和核心边。速度快，存储占用小，适合快速原型或巨型代码库的初次探索。
• balanced（平衡）：启用 LSP 符号解析和基础增强（如文档链接）。在分析深度和资源消耗间取得平衡，是大多数“智能体辅助”场景的推荐选择。
• full（完整）：启用所有分析器，包括完整的数据流分析和架构边界检查。提供最丰富的图谱，用于深度架构评审或重构影响分析。

更巧妙的是它的上下文窗口感知功能。你需要通过环境变量CODEGRAPH_CONTEXT_WINDOW告知 CodeGraph 你的 AI 模型（如 Claude-3.5-Sonnet 的 200K，或本地小模型的 4K）的上下文限制。CodeGraph 会根据这个限制，动态调整其智能体工具的行为：

• 提示词优化：对小窗口模型使用更简洁的提示。
• 步骤限制：严格限制智能体推理的最大步骤数（通常 3-8 步），防止陷入无限循环。
• 结果截断：当单个工具返回的结果集过大时，会智能地截断，保留最相关的部分，并标记_truncated: true，让智能体知道信息不完整。

这种设计体现了极强的工程实用性。它承认现实世界的约束（模型能力、成本、速度），并在此基础上提供最佳体验。

3. 从零开始部署与配置实战

3.1 环境准备与编译安装

CodeGraph 是 Rust 项目，编译安装是第一步。官方提供了install-codegraph-full-features.sh脚本，但为了更可控，我推荐手动编译。

# 1. 克隆仓库 git clone https://github.com/Jakedismo/codegraph-rust cd codegraph-rust # 2. 安装 Rust 工具链（如果尚未安装） # 访问 https://rustup.rs/ 获取安装脚本 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh source $HOME/.cargo/env # 3. 安装编译依赖 # 确保你有 C 编译器（gcc/clang）和必要的系统库 # 在 Ubuntu/Debian 上： sudo apt update && sudo apt install -y build-essential pkg-config libssl-dev # 4. 编译并安装 CodeGraph（启用所有特性） cargo install --path . --locked --features cli,server,embedding-ollama,embedding-openai,llm-anthropic,llm-openai

注意：--locked参数确保使用与Cargo.lock文件一致的依赖版本，避免因依赖更新导致的不兼容问题。--features参数根据你的需要选择。如果你主要用本地 Ollama 做嵌入和推理，就加上embedding-ollama,llm-ollama。

macOS 用户加速编译技巧： Rust 项目的链接阶段有时比较耗时。如果你在 macOS 上，可以尝试使用 LLVM 的lld链接器来加速。

# 安装 LLVM（包含 lld） brew install llvm # 设置环境变量，让 Rust 使用 lld export RUSTFLAGS="-C link-arg=-fuse-ld=$(brew --prefix llvm)/bin/ld64.lld" # 然后再次运行 cargo build 或 cargo install cargo build --release --features cli,server

实测在 M 系列芯片的 Mac 上，链接时间能有显著缩短。

3.2 数据库部署：SurrealDB 的本地与云端选择

CodeGraph 使用 SurrealDB 作为图数据库和向量存储后端。你有两种选择：

方案一：本地运行（推荐用于开发和中小项目）

# 1. 安装 SurrealDB # 使用 curl 下载（以 Linux x86_64 为例） curl -sSf https://install.surrealdb.com | sh # 或者使用包管理器，如 macOS 的 Homebrew brew install surrealdb/tap/surreal # 2. 启动 SurrealDB 服务 # 创建一个持久化数据目录 mkdir -p ~/.codegraph # 启动数据库，指定用户/密码和存储路径 surreal start --bind 0.0.0.0:3004 --user root --pass root file://$HOME/.codegraph/surreal.db

这个命令会在后台启动一个 SurrealDB 实例，监听 3004 端口，数据持久化在~/.codegraph/surreal.db文件中。--user和--pass参数是连接认证所必需的。

方案二：使用 SurrealDB Cloud（免费层可用）对于不想维护数据库，或者需要跨团队共享索引的场景，SurrealDB Cloud 的免费层是个好选择。

1. 访问 surrealdb.com/cloud 注册并创建一个新数据库。
2. 创建后，你会获得一个连接字符串，格式类似：wss://<your-instance>.surrealdb.com
3. 后续在 CodeGraph 配置中，将connection指向这个云端地址即可。

3.3 初始化数据库与导入图谱 schema

数据库服务跑起来后，需要初始化结构。CodeGraph 提供了两种 schema：标准的关系型风格和实验性的图数据库风格。这里我们先使用标准 schema。

# 进入项目 schema 目录 cd /path/to/codegraph-rust/schema # 使用 SurrealDB 命令行工具导入 schema # 确保你的 surreal 命令在 PATH 中，或者使用绝对路径 surreal import --conn ws://localhost:3004 --user root --pass root --ns ouroboros --db codegraph codegraph.surql

这条命令做了以下几件事：

• --conn: 指定连接到我们刚启动的本地数据库。
• --user/--pass: 提供认证信息。
• --ns/--db: 创建并切换到名为ouroboros的命名空间和codegraph的数据库。这是 CodeGraph 的默认配置。
• codegraph.surql: 导入定义表、索引（尤其是用于向量搜索的 HNSW 索引）和函数的 SQL 文件。

关于实验性图 schema： 如果你处理的是超大型代码库（数十万行以上），且查询以复杂的图遍历为主，可以尝试实验性 schema (codegraph_graph_experimental.surql)。它针对图查询做了优化。使用方法类似，但需要先创建一个新的数据库（如codegraph_experimental）并导入该 schema 文件，然后通过环境变量CODEGRAPH_USE_GRAPH_SCHEMA=true和CODEGRAPH_GRAPH_DB_DATABASE=codegraph_experimental来启用。

3.4 配置 CodeGraph：连接模型与数据库

CodeGraph 的配置非常灵活，支持环境变量、命令行参数和配置文件。最方便的是使用全局配置文件~/.codegraph/config.toml。

# ~/.codegraph/config.toml [embedding] # 嵌入模型提供商，可选：ollama, openai, jina, onnx provider = "ollama" # 模型名称，需要与提供商处的名称一致 model = "nomic-embed-text:latest" # 模型输出的向量维度，必须匹配，否则索引会失败 dimension = 768 [llm] # 用于智能体推理的 LLM 提供商，可选：anthropic, openai, ollama, lmstudio provider = "anthropic" # 模型名称 model = "claude-3-5-sonnet-20241022" # 可选：API 密钥（如果使用云端服务） # api_key = "your-api-key-here" [database.surrealdb] # SurrealDB 连接字符串 connection = "ws://localhost:3004" # 命名空间和数据库名，需与导入 schema 时一致 namespace = "ouroboros" database = "codegraph" [agent] # 设置智能体的上下文窗口大小（单位：token）。必须与你的 LLM 模型匹配！ # 例如：Claude 3.5 Sonnet 是 200000， GPT-4o 是 128000，本地 7B 模型可能是 4096 context_window = 200000 # 选择智能体架构，'rig' 是默认且推荐的 architecture = "rig"

关键配置详解：

1. [embedding]: 这是为代码片段生成语义向量的模型。如果你选择ollama，需要先在本地运行 Ollama 并拉取对应的嵌入模型，例如ollama pull nomic-embed-text:latest。维度的正确性至关重要，错误的维度会导致 HNSW 索引无法工作。
2. [llm]: 这是驱动agentic_*工具进行推理的“大脑”。如果你使用 Claude API，需要配置provider = "anthropic"并设置api_key。如果使用本地 Ollama 模型，则设为provider = "ollama",model = "qwen2.5:7b"等。
3. [agent].context_window:这个配置极其重要且容易被忽略。它直接决定了 CodeGraph 智能体工具的行为策略（步骤数、结果截断阈值）。务必将其设置为与你[llm]中配置的模型实际上下文窗口一致的值。
4. [agent].architecture:rig是默认架构，它内部会根据任务类型自动选择 LATS（树搜索，用于复杂分析）或 ReAct（线性推理，用于直接查询），并具备自动恢复（Reflexion）能力，是目前最稳定和高效的选择。

4. 索引你的代码库：策略与实战

配置完成后，就可以开始构建你的代码知识图谱了。这是最消耗计算资源的步骤。

4.1 基础索引命令

# 进入你的项目目录，或者指定项目路径 cd /path/to/your/rust-project # 运行索引命令 # -r 或 --recursive 表示递归索引子目录 # -l 或 --languages 指定要索引的语言，用逗号分隔 codegraph index . -r -l rust

这个命令会启动索引管道。你会看到类似以下的输出，展示了从解析、LSP 分析到嵌入和存储的各个阶段：

[INFO] Starting indexing for project: /path/to/your/rust-project [INFO] Detected languages: [Rust] [INFO] Building context... (cargo metadata, etc.) [INFO] Parsing AST with tree-sitter... [INFO] Resolving symbols via rust-analyzer... [INFO] Enriching graph with dataflow edges... [INFO] Generating embeddings via Ollama (nomic-embed-text:latest)... [INFO] Storing nodes and edges into SurrealDB... [INFO] Indexing completed. 5423 nodes, 12876 edges indexed.

4.2 索引分层实战与语言服务器配置

如果你的项目很大，或者你只是想快速体验，可以使用--index-tier参数。

# 快速索引，忽略 LSP 和增强分析，速度最快 codegraph index . -r -l rust --index-tier fast # 平衡模式，启用 LSP 和基础增强，推荐用于日常开发 codegraph index . -r -l rust --index-tier balanced # 完整模式，启用所有分析器，用于深度架构审查 codegraph index . -r -l rust --index-tier full

踩坑记录：LSP 解析失败当使用balanced或full层级时，CodeGraph 会调用语言服务器（LSP）来获取精确的符号信息。如果遇到类似Unknown binary 'rust-analyzer' in official toolchain的错误，说明你的rust-analyzer是一个 rustup 的 shim，但没有可执行的二进制文件。

解决方案：

# 方法1：通过系统包管理器安装独立的 rust-analyzer # macOS brew install rust-analyzer # Ubuntu/Debian (可能需要添加 PPA) sudo apt install rust-analyzer # 方法2：通过 rustup 安装一个包含二进制文件的工具链组件 rustup component add rust-analyzer --toolchain stable

确保安装后，which rust-analyzer能返回一个有效的路径。其他语言（Python 的pyright， TypeScript 的typescript-language-server）也需要确保在系统 PATH 中可用。

4.3 多语言项目与边界规则

对于多语言项目，直接在-l参数后列出所有语言即可。

codegraph index . -r -l rust,typescript,python,go

CodeGraph 会并行处理不同语言的解析器。

高级功能：架构边界检查如果你的项目有明确的模块边界（例如，domain层不应该直接依赖infrastructure层），你可以通过创建codegraph.boundaries.toml文件来定义规则。

# 放在项目根目录的 codegraph.boundaries.toml [[deny]] from = "app::web" # 来源模块（支持通配符） to = "app::database::internal" # 目标模块 reason = "Web layer must not access internal database details." [[deny]] from = "domain::*" to = "infrastructure::*" reason = "Domain should depend on abstractions, not concrete implementations."

在full索引层级下，CodeGraph 会分析depends_on关系，如果发现违反规则的依赖，会在图谱中创建violates_boundary边，并在后续的agentic_architecture或agentic_quality分析中报告这些架构违规。

4.4 安全与隐私：索引什么，不索引什么

这是一个非常实际的问题。CodeGraph 在索引时自动做了两件事：

1. 尊重.gitignore：所有在.gitignore中列出的文件和目录默认不会被索引。
2. 过滤敏感文件模式：它会主动过滤掉常见的敏感文件，如.env,.env.local,*.pem,*credentials*.json,*secret*.toml等，避免将密钥或令牌嵌入向量或存入数据库。

但是，最佳实践是手动检查。对于包含绝对机密信息的目录（如secrets/），建议在索引前将其移出项目根目录，或者使用--exclude参数：

codegraph index . -r -l rust --exclude "**/secrets/**" --exclude "**/config/prod/*.yaml"

5. 集成 AI 助手：以 Claude Code 为例

索引完成后，你的代码知识图谱就准备好了。现在需要让 AI 助手能够访问它。CodeGraph 通过MCP（Model Context Protocol）协议提供服务，这是 Anthropic 推出的一种让工具安全暴露给 AI 模型的协议，Claude Code、Cursor 等都已支持。

5.1 配置 Claude Code 连接 CodeGraph

Claude Code 的 MCP 配置通常位于~/.config/claude/desktop_config.json（Linux/macOS）或%APPDATA%\Claude\desktop_config.json（Windows）。

编辑这个文件，添加codegraph服务器配置：

{ "mcpServers": { "codegraph": { "command": "/absolute/path/to/codegraph", "args": ["start", "stdio", "--watch"], "env": { "CODEGRAPH_CONTEXT_WINDOW": "200000", "CODEGRAPH_AGENT_ARCHITECTURE": "rig" } } } }

配置解析：

• command: 必须是codegraph二进制文件的绝对路径。你可以通过which codegraph命令来获取。
• args:start stdio表示以标准输入输出模式启动 MCP 服务器。--watch参数至关重要，它启用了守护进程模式，会自动监控项目文件变化并在后台增量更新索引，保持图谱新鲜。
• env: 这里设置的环境变量会覆盖配置文件中的设置。我强烈建议在这里显式设置CODEGRAPH_CONTEXT_WINDOW，确保与 Claude Code 使用的模型窗口一致。

保存配置后，重启 Claude Code 应用。重启后，你应该能在 Claude Code 的聊天界面看到可用的工具列表里出现了agentic_context,agentic_impact,agentic_architecture,agentic_quality这四个工具。

5.2 实战对话：体验“理解”而非“搜索”

现在，让我们在 Claude Code 中与一个已索引的 Rust 项目进行对话。

场景一：快速理解一个陌生函数

• 你：“agentic_context一下，这个项目里的validate_transaction函数是做什么的？它在哪个模块？”
• Claude Code（调用工具后）：“validate_transaction函数位于crates/ledger/src/validation.rs的第 87 行。它是一个公开函数，主要职责是验证交易数据的完整性和业务规则。从图谱看，它被process_payment和batch_verify两个函数调用。函数签名显示它接收一个Transaction引用，返回Result<(), ValidationError>。相关的数据流边表明它会检查amount非负、from和to地址有效等。需要我展示具体的代码实现吗？”

场景二：评估重构影响

• 你：“我打算重构EmailService的发送接口，用agentic_impact分析一下会影响哪些地方。”
• Claude Code：“调用agentic_impact工具分析EmailService... 分析完成。EmailService是一个位于crates/notification/src/email.rs的结构体。直接依赖它的有 12 处，包括UserRegistration、OrderShipped等处理器。传递依赖分析显示，修改其公共接口send(&self, to: &str, subject: &str, body: &str)可能会影响 3 个下游服务模块。耦合度分析显示它与TemplateRenderer模块耦合度较高（0.7）。建议：1. 先更新接口的单元测试。2. 考虑引入一个EmailSendertrait 来解耦。这是详细的依赖列表和代码位置...”

场景三：获取架构全景

• 你：“给我这个项目的整体架构视图，用agentic_architecture。”
• Claude Code：“调用agentic_architecture工具... 这是你的项目my-app的架构分析：核心模块：1.domain/(领域层)，包含User、Order等聚合根。2.application/(应用层)，包含用例服务。3.infrastructure/(基础设施层)，包含数据库和外部 API 客户端。4.api/(接口层)，提供 REST 和 GraphQL 端点。关键依赖流向：api/->application/->domain/<-infrastructure/，符合清洁架构。API 表面：共 24 个公共 REST 端点，主要围绕用户和订单管理。检测到一个潜在的架构异味：infrastructure::cache模块直接引用了domain::value_objects，这违反了你在codegraph.boundaries.toml中定义的边界规则。”

可以看到，AI 助手的回答不再是基于单个文件的猜测，而是基于整个代码库图谱的推理结果。它知道了代码的“位置”、“关系”和“上下文”。

5.3 守护进程模式与实时更新

启动时添加的--watch参数让 CodeGraph 运行在守护进程模式。它会监听项目文件系统的变化（通过notify库）。当你修改、添加或删除文件时，CodeGraph 会在短暂的防抖延迟后，自动对变更的文件进行增量索引，更新图谱中的节点和边。

这意味着你的 AI 助手几乎总是基于最新的代码状态与你对话，无需手动触发重新索引。你可以在终端单独运行codegraph daemon status来查看守护进程的状态和日志。

6. 高级技巧与故障排查

6.1 性能调优：针对大型代码库

如果你的项目有几十万行代码，索引和查询可能会变慢。以下是一些优化思路：

1. 分模块索引：如果项目由多个相对独立的子项目（crate/package）组成，可以分别索引，甚至使用不同的 SurrealDB 数据库。通过环境变量CODEGRAPH_PROJECT_ID来区分。

   # 索引核心库 CODEGRAPH_PROJECT_ID=core_lib codegraph index ./core -r -l rust --index-tier balanced # 索引 Web 服务 CODEGRAPH_PROJECT_ID=web_api codegraph index ./services/api -r -l rust,typescript --index-tier balanced

   在查询时，AI 助手可以通过focus参数或对话上下文来限定范围，但工具本身目前主要针对单个项目 ID 进行查询。未来版本可能支持跨项目分析。

2. 调整嵌入模型：nomic-embed-text质量不错但速度中等。如果你追求极速索引，可以尝试更小的模型，如all-minilm:l6-v2(维度 384)，但需在配置中相应调整dimension = 384，并且重建索引（需要清空数据库或使用新数据库）。

3. 使用实验性图 Schema：如前所述，对于超大规模图谱的复杂遍历查询，实验性 schema (codegraph_graph_experimental) 可能有更好的性能。切换后需要重新索引。

4. 增加 LSP 超时：对于非常大的文件或复杂的类型解析，LSP 服务器可能超时。可以通过环境变量调整超时时间（秒）：

   CODEGRAPH_LSP_REQUEST_TIMEOUT_SECS=1200 codegraph index . -r -l rust --index-tier full

6.2 常见问题与解决方案

问题一：索引卡在 “Resolving symbols via LSP...” 很久不动。

• 可能原因：LSP 服务器启动失败、项目依赖未正确解析（如Cargo.toml有问题）、或者遇到了一个极其复杂的文件。
• 排查：
  1. 检查对应语言的 LSP 服务器是否安装且能在命令行运行（如rust-analyzer --version）。
  2. 尝试先用--index-tier fast跳过 LSP 阶段，看是否能成功。如果能，则问题出在 LSP 配置或项目环境上。
  3. 查看 CodeGraph 的详细日志：CODEGRAPH_LOG=debug codegraph index ...。
  4. 临时调高CODEGRAPH_LSP_REQUEST_TIMEOUT_SECS。

问题二：AI 助手调用工具后返回 “Tool error: context window overflow”。

• 原因：工具返回的结果总量超过了CODEGRAPH_CONTEXT_WINDOW设置的安全阈值（默认是窗口的 80% * 4，为 token 开销留了余量）。
• 解决：
  1. 确认配置：确保CODEGRAPH_CONTEXT_WINDOW的值与你实际使用的 LLM 模型上下文窗口一致。如果你在用 Claude 3.5 Sonnet (200K)，这里就应该是 200000。
  2. 优化查询：让 AI 助手提出更具体的问题。例如，不用“分析整个项目”，而用“分析src/auth/目录下的耦合情况”。
  3. 调整工具焦点：某些工具支持focus参数来缩小范围，例如agentic_architecture可以只关注"api_surface"。

问题三：语义搜索的结果感觉不准确。

• 原因：嵌入模型不适合代码，或者代码块分块（chunking）策略不佳。
• 解决：
  1. 尝试不同的嵌入模型：CodeGraph 支持多种。对于代码，jina-embeddings-v3或text-embedding-3-small可能比通用文本模型效果更好。切换模型后需要重新索引。
  2. 检查分块：CodeGraph 默认基于 AST 节点进行分块（如函数、类）。这通常比固定长度的滑动窗口更好。但如果你的代码风格特殊（比如超长函数），可以关注项目 Issue，看是否有自定义分块策略的选项。

问题四：SurrealDB 连接失败。

• 错误信息：Connection refused或Failed to connect to database。
• 排查：
  1. 确认 SurrealDB 服务正在运行：ps aux | grep surreal。
  2. 确认连接字符串正确：如果是本地，通常是ws://localhost:3004；如果是 SurrealDB Cloud，是wss://xxx.surrealdb.com。
  3. 检查认证信息：配置文件或环境变量中的user和pass必须与启动 SurrealDB 时指定的匹配。
  4. 检查防火墙或网络策略是否阻止了连接。

6.3 与其他工具链的整合思路

CodeGraph 的核心价值在于其图谱和智能体工具。你可以将它集成到更广泛的开发工作流中：

1. CI/CD 流水线：在 CI 中运行codegraph index --index-tier full，然后使用agentic_quality工具生成代码质量报告（复杂度热点、耦合度），作为 Merge Request 的检查项。甚至可以定义规则，如果发现新的架构边界违规，则阻断合并。
2. 文档生成：利用agentic_context和agentic_architecture的输出，可以自动生成或更新项目的模块依赖图、API 目录文档。
3. 新人 onboarding：新成员可以通过向集成了 CodeGraph 的 AI 助手提问，快速了解代码库结构、核心流程和修改影响，大幅降低熟悉成本。

CodeGraph 目前处于活跃开发阶段，它的插件系统和更丰富的分析器值得期待。它代表了一种方向：未来的开发工具，尤其是 AI 辅助工具，将越来越依赖对代码语义和结构的深度理解，而不仅仅是文本匹配。将它接入你的工作流，就像是给你的 AI 搭档装上了一副“透视眼镜”，让它能真正看清你代码世界的脉络与连接。