Codegraph Rust

CodeGraph（持续更新）

理解你的代码库。

提示

为你的编码 Agent 提供持久的项目记忆。

认识一下 CodeGraph Agent Memory， 这是我们的姊妹项目，它基于 CodeGraph 构建，为架构决策、发现、失败的方案和可复用流程提供持久记忆。启用记忆检索后，Agent 工作流便能在不同会话中结合当前代码证据，获取这些知识。

探索 Agent 记忆指南 →

CodeGraph 会将整个代码库转换为可进行语义搜索的知识图谱，让 AI Agent 真正能够推理，而不只是用 grep 搜索。

准备好开始了吗？ 前往安装指南，查看分步设置说明。

已经完成设置？ 查看使用指南，了解如何通过 AI 助手充分利用 CodeGraph。

更喜欢使用 Shell 命令？ 运行 codegraph agent context "your question"。同样的四种 Agent 工具也可通过 CLI 使用，并支持项目本地的 Claude Code/Codex 钩子。 codegraph init 可设置钩子，并会在索引前添加 Agent 指令。

---

问题所在

AI 编码助手功能强大，但它们对代码库一无所知。它们一次只能查看一个文件，使用 grep 搜索模式，还要耗费大量令牌来理解你的架构。每次对话都得从零开始。

如果你的 AI 助手已经了解你的代码库，会怎样？

---

CodeGraph 的不同之处

1. 图谱 + 嵌入 = 真正的理解

大多数语义搜索工具创建嵌入后就止步于此。CodeGraph 会构建一个真正的知识图谱：

Your Code → Build Context → AST + FastML → LSP Resolution → Enrichment → Graph + Embeddings
              ↓               ↓              ↓              ↓              ↓         ↓
          Packages        Nodes/edges    Type-aware     API surface      Graph    Semantic
          Features        Fast patterns  linking        Module graph   traversal   search
          Targets         Spans          Definitions    Dataflow/Docs             (hybrid)

搜索时，你获得的不只是“相似代码”，而是保留关联关系的代码：与查询匹配的函数，以及调用它的内容、它依赖的内容，还有它在架构中的位置。

索引增强功能包括：

• 模块节点和模块级导入/包含边，支持跨文件导航
• Rust 局部数据流边（defines、uses、flows_to、returns、mutates），用于影响分析
• 文档/规范节点，与 README.md、docs/**/*.md 和 schema/**/*.surql 中以反引号括起的符号相连
• 架构信号（包循环依赖 + 可选的边界违规）

索引层级（速度与丰富度）

索引分为多个层级，让你可以在速度、存储空间和图谱丰富度之间进行选择。默认层级为 fast。

层级	功能	典型用途
fast	仅包含 AST 节点和核心边（不使用 LSP 或增强功能）	快速索引，存储占用低
balanced	LSP 符号、文档/增强功能和模块链接	以适中的分析器开销获得更丰富的导航和文档
full	所有分析器、LSP 定义、数据流和架构	最大程度地丰富图谱并覆盖分析器

Agent 答案准确度单独评估；请参阅 CLI 准确度结果。

层级行为详情：

• fast：禁用构建上下文、LSP、增强功能、模块链接、数据流、文档/契约和架构；过滤掉 Uses/References 边。
• balanced：启用构建上下文、LSP 符号、增强功能、模块链接和文档/契约；过滤掉 References 边。
• full：启用所有分析器和 LSP 定义；不进行边过滤。

配置层级：

• CLI：codegraph index /path/to/project --index-tier balanced
• 环境变量：CODEGRAPH_INDEX_TIER=balanced
• 配置：[indexing] tier = "balanced"

默认情况下，目录索引会扫描子目录，因此 codegraph index --languages Rust --index-tier balanced . 会查找工作区 crate 中的 Rust 源文件。若要有意仅扫描根目录，请使用 --no-recursive；-r/--recursive 仍受支持。 codegraph estimate 使用相同的遍历默认值。

索引前提条件（启用 LSP 的层级）

当层级启用 LSP（balanced/full）时，如果缺少所需的外部工具，索引会立即失败。 Rust 索引还会在解析前，于目标项目中运行 rust-analyzer --version： 存在 rustup shim 并不代表其当前使用的工具链包含该组件。 使用 rustup 时，请在该项目目录中运行 rustup component add rust-analyzer， 然后通过 rust-analyzer --version 验证。语言服务器故障会保留 stderr 的末尾 4 KiB， 以便启动和运行时错误包含服务器诊断信息。

各语言所需工具：

• Rust：rust-analyzer
• TypeScript/JavaScript：node 和 typescript-language-server
• Python：node 和 pyright-langserver
• Go：gopls
• Java：jdtls
• C/C++：clangd

常驻的语言服务器会话会保留带版本的文档，并对定义请求进行去重和流水线处理。 符号和定义请求遇到临时的 ContentModified （-32801）响应时，会在单个 30 秒时限内采用退避策略，最多重试五次。 文档版本发生变化、重试次数用尽或出现其他错误时，索引仍会失败， 诊断信息中会包含请求方法和文件 URI。CODEGRAPH_LSP_REQUESTS 限制 每个服务器的未完成请求数（默认值为 32）。CODEGRAPH_ANALYZERS=0 可独立于层级禁用分析器。 CODEGRAPH_SCIP_INDEX=/path/index.scip 可用编译器索引替代 LSP；源代码验证和 sidecar 要求详见 索引实现指南。

增量索引与推理策略

--batch-size 设置本地和云端提供商每批处理的嵌入文本最大数量。显式指定的值优先于 CODEGRAPH_EMBEDDINGS_BATCH_SIZE、其旧版别名 CODEGRAPH_EMBEDDING_BATCH_SIZE，以及 TOML 中的 [embedding] batch_size，优先级依次递减；默认值为 64。基于内存的调优不会更改显式指定的值，包括 --batch-size 100。

codegraph index --languages Rust --index-tier balanced --batch-size 512 .

令牌／字节预算、缓存命中和提供商 API 限制可能导致实际请求更小。如需发送更大的请求，可按需调整 CODEGRAPH_EMBEDDING_BATCH_TOKENS（默认值至少为已解析的输入上下文，本地／远程下限分别为 8192／32768）和 CODEGRAPH_EMBEDDING_BATCH_BYTES（默认值为 1 MiB）。 日志会分别显示这些推理限制和数据库写入批次大小；CODEGRAPH_CHUNK_DB_BATCH_SIZE 默认最多为 32 行，上限为 512。 Ollama 和 LM Studio 没有额外的固定 256 条文本上限。

全量、单文件和监视索引共用完整的项目协调机制。未更改的源文件会复用缓存的 AST／分析器工件，同时完整目录会在编辑、重命名和删除后继续保留调用方信息。只会写入已更改的图记录和文件元数据。源快照、解析、推理和写入器队列分别设有资源上限；只有在收到持久化确认并完成最终输入检查后，才会标记完成。 --force 会重新准备并协调数据，而不信任之前的目录。

嵌入和语义解析工作独立于提取层级。每项工作都支持 sync（编译了相应功能时的默认值）、deferred 或 off：

CODEGRAPH_EMBEDDING_POLICY=deferred CODEGRAPH_SEMANTIC_RESOLUTION=off \
  codegraph index /path/to/project --index-tier fast --stats-json indexing.json
codegraph index /path/to/project --complete-deferred --stats-json completed.json

延迟运行会持久化可恢复的作业，并区分图就绪状态和待处理的推理任务。预处理文本嵌入缓存包含模型／任务／分词器／运行时标识；分块会保留 Unicode，并强制遵守提供商的令牌预算。可变模型别名会过期；CODEGRAPH_MODEL_REVISION 用于声明不可变版本。

嵌入输入与分块

分块规划从 AST 节点源代码范围开始，例如函数和类。能完整纳入输入预算的单元会保持完整。超出预算的单元会先按 Tree-sitter 语句／块边界拆分，然后合并相邻片段，直到达到预算。过大的叶节点和不受支持的语法会使用 UTF-8 安全的行／令牌拆分。 Unicode 和结构空白会保留；重叠部分按令牌数计算。

对于 Ollama，预算依据模型元数据和服务上下文确定。Qwen3 embedding 模型支持32K 输入；nomic-embed-text-v2-moe支持 512 个令牌。计数包含文档／查询前缀和特殊令牌。Nomic 文本模型会接收 search_document: ／search_query: ；Qwen3 查询会接收检索指令。每个 Ollama 请求都使用 truncate=false： 上下文不匹配时会明确报错，而不是静默丢弃源代码。

系统会自动为已识别的模型加载相应发布方的分词器，缓存 tokenizer.json，并在文件不存在时于首次使用时下载。不会下载模型权重。自定义／离线模型可通过 CODEGRAPH_TOKENIZER_PATH 提供分词器；未知模型需要提供该路径或 CODEGRAPH_TOKENIZER_REPO。

控制项	行为
CODEGRAPH_CHUNK_MAX_TOKENS	降低完整输入目标；上限受服务上下文限制。旧版 CODEGRAPH_MAX_CHUNK_TOKENS 的优先级较低。
CODEGRAPH_CHUNK_SMART_SPLIT=0	对超大单元使用 Token 切分，而非 AST 边界。默认：AST 切分。
CODEGRAPH_CHUNK_OVERLAP_TOKENS	后缀重叠的最大 Token 数；默认值为 64，设为 0 可禁用。会缩减以适配下一个输入。
CODEGRAPH_EMBEDDING_SKIP_CHUNKING=1	保持节点完整；如果任何节点超过配置的输入上限，则在推理前失败。
CODEGRAPH_OLLAMA_NUM_CTX	设置请求上下文，上限为模型最大值。否则，使用已报告的 Modelfile/运行时上下文。
CODEGRAPH_MODEL_MAX_TOKENS	补充缺失的模型上下文元数据，或降低公布的最大值。
CODEGRAPH_TOKENIZER_PATH	使用匹配的本地 tokenizer.json，不下载文件。
CODEGRAPH_TOKENIZER_REPO、CODEGRAPH_TOKENIZER_REVISION	覆盖发布方的 Tokenizer 仓库/修订版本；默认修订版本为 main。
CODEGRAPH_EMBEDDING_DOCUMENT_PREFIX、CODEGRAPH_EMBEDDING_QUERY_PREFIX	为自定义模型覆盖检索前缀。

--batch-size 控制每个推理请求处理的文本数量，与分块长度无关。 默认请求 Token 预算会增长，以适应解析后的输入上下文 （本地下限为 8192；远程下限为 32768）。显式设置的 CODEGRAPH_EMBEDDING_BATCH_TOKENS 和 CODEGRAPH_EMBEDDING_BATCH_BYTES 仍是独立限制；如果输入超过其中一项， 操作将失败，并提示提高该限制或降低分块目标。

升级后请重新索引：Tokenizer、任务、上下文和分块策略的更改会使 旧产物和嵌入失效。离线模拟会验证准备流程和请求限制； 检索质量和索引速度仍需在你的项目上测量。

CODEGRAPH_VECTOR_INDEX_MODE=all|selected|deferred|off 控制新建嵌入式存储的 HNSW 构建。 默认保留所有架构维度；selected 构建活动维度，deferred 在持久化摄取后构建， off 则报告向量尚未就绪。现有共享索引会保留。其他切分器、候选项上限 以及运行时/精度选项仍需选择启用。

参见配置和不变量以及 可复现的速度/质量基准测试。离线调试 测试装置的结果可验证行为；生产吞吐量和模型质量需要使用有代表性的样本进行测量。

语义关系评分会缓存向量范数，并在现有的工作线程数受限 CPU 池中， 对独立的未解析名称进行评分；这些操作在异步运行时工作线程之外执行。 候选项顺序、余弦阈值和歧义平局处理均保持不变。--stats-json 现在会在关系解析过程中分别统计精确/词法匹配、语义候选项选择、符号嵌入、 CPU 评分以及边准备/写入。

如果 LSP 解析立即失败，且错误中包含类似 Unknown binary 'rust-analyzer' in official toolchain ... 的内容，那么你的 rust-analyzer 是一个 rustup 垫片，但尚未安装对应的二进制文件。请安装可运行的 rust-analyzer（例如通过 brew install rust-analyzer 安装，或切换到提供该程序的工具链）。

可选的架构边界规则

如果你希望 CodeGraph 标记被禁止的包依赖，请在项目根目录添加 codegraph.boundaries.toml：

[[deny]]
from = "your_crate"
to = "forbidden_crate"
reason = "explain the boundary"

当 depends_on 关系匹配某条拒绝规则时，索引过程会生成 violates_boundary 边。

2. Agentic 工具，而不只是搜索

CodeGraph 不会只返回一列文件，然后让你自求多福。它提供 4 个整合式 Agentic 工具，负责思考：

工具	实际功能
agentic_context	收集所需上下文——搜索代码、构建全面上下文、回答语义问题
agentic_impact	梳理变更影响——依赖链、调用流程，以及修改某项内容会导致什么问题
agentic_architecture	全局视图——系统结构、API 表面和架构模式
agentic_quality	风险评估——复杂度热点、耦合度指标和重构优先级

需要更精确时，每个工具都可以使用可选的 focus 参数：

工具	Focus 值	默认行为
agentic_context	"search"、"builder"、"question"	根据查询自动选择
agentic_impact	"dependencies"、"call_chain"	同时分析两者
agentic_architecture	"structure"、"api_surface"	同时提供两者
agentic_quality	"complexity"、"coupling"、"hotspots"	全面评估

每个工具都会运行一个推理 Agent，负责规划、搜索、分析图关系并综合答案。它提供的不是搜索结果，而是一个答案。

查看 Agent 上下文收集流程 - 交互式图示，展示 Agent 如何使用图工具收集上下文。

Agent 架构

CodeGraph 的 Agent 基于 Rig 框架构建。运行哪个 Agent，由 CODEGRAPH_AGENT_ARCHITECTURE 在运行时决定（在 .env 或环境变量中设置）：

• react（默认；rig 也可作为别名）：通过图工具进行工具调用循环。
• lats：针对候选方案进行树搜索，这些候选方案调用的图工具与 ReAct 相同。每个分支都会保留自己的观察结果；评估器会根据这些证据为分支评分，由选中的分支提供答案。如果没有成功的图观察结果，运行就会失败。
• reflexion：在 ReAct 外包裹一次重试，并将前一次错误反馈给 Agent。

无论选择哪个 Agent，失败的运行都会自动重试，并将错误作为上下文。

# Default: ReAct
./codegraph start stdio

# Tree search with graph-tool grounding
CODEGRAPH_AGENT_ARCHITECTURE=lats ./codegraph start stdio

所有 Agent 都提供相同的 4 个整合式 Agentic 工具，并使用按层级区分的提示词。 LATS 每次扩展都会探索 3 个候选方案，并调用评估器，因此可能比 ReAct 花费更多、耗时更长。其层级预算会限制搜索扩展次数、深度和每个候选方案的工具循环；候选方案共享本次运行的结果大小预算。 CLI 的整个工作流截止时间仍然适用。请参阅架构与限制。

3. 按层级调整智能能力

这里有个巧妙之处：CodeGraph 会根据你为 codegraph Agent 配置的大模型上下文窗口，自动调整行为。

运行小型本地模型？获取聚焦、高效的查询。

使用上下文窗口为 200K 的模型？获取全面的探索式分析。

使用上下文窗口为 1-2M 的 gpt-6、Opus-5.5 或 Grok-4.7？获取详细分析和智能结果管理。

Agent 只会执行生成答案所需的步骤数，因此工具执行时间会因查询和数据库中索引的数据量而异。

在开发过程中，Agent 平均使用 3-6 个步骤来回答测试场景中的问题。

Agent 是无状态的，只有在工具执行期间才会保留对话记忆；它不会在多个链式工具调用之间累积上下文或记忆。这由你选择的客户端处理，它会累积上下文，因此 CodeGraph 只需提供答案。

你的模型	CodeGraph 的行为
< 50K 个 token	简洁提示词，最多 3 步
50K-150K	均衡分析，最多 5 步
150K-500K	详细探索，最多 6 步
> 500K（gpt-6 等）	全面分析，最多 8 步

硬性上限： 无论层级如何，最多 8 步。这既能防止成本失控和上下文溢出，也能进行充分分析。

同一款工具，会根据你的配置自动优化。

4. 上下文溢出保护

Agent 收到的每个工具结果都会在后续每一轮中重新发送给模型，因此 CodeGraph 会从三个层面限制一次运行在模型上下文中占用的空间：

内容片段。 结果行中的长 content（如整篇文档或一个 impl 块）会被截取为开头片段，默认长度为 2,000 个字符，并标记为 content_truncated，同时记录原始长度。该行会保留文件路径和行范围，因此客户端可以读取剩余内容。

单个结果限制。 单个工具结果的大小限制为 context_window × 2 字节，上限为 200 KB，无论上下文窗口有多大。超出大小的数组结果会保留开头的条目，并附带 _truncated 元数据。

单次运行预算。 一次 Agent 运行中的所有工具结果共享约为上下文窗口三分之一的预算（按每个 token 4 字节计算），范围在 48 KB 到 600 KB 之间。若某个结果会超出剩余预算，则会被裁剪以适应限制，并附带 _budget 说明；预算用尽后，后续调用会返回说明，提示 Agent 根据现有证据作答。

通过环境变量配置：

# Set this to match your agent LLM's real context window
CODEGRAPH_CONTEXT_WINDOW=128000            # default: 128K

# Optional overrides
CODEGRAPH_TOOL_CONTENT_CHARS=2000          # snippet length per row; 0 disables shortening
CODEGRAPH_AGENT_RESULT_BUDGET_BYTES=400000 # per-run tool-result budget

为何重要： 在本仓库的完整层级索引上，单次语义搜索在应用这些限制前可能返回 228 KB；一次运行中进行十几次搜索，会让每次模型请求都包含数 MB 数据，直到模型调用卡住。

5. 真正有效的混合搜索

我们不在“嵌入与关键词”的争论中选边站。CodeGraph 会结合：

• 70% 向量相似度（语义理解）
• 30% 词法搜索（精确匹配很重要）
• 图遍历（关系和上下文）
• 可选重排（交叉编码器精度）

结果如何？搜索“登录逻辑”时能找到 handleUserAuth——搜索“handleUserAuth”时也能找到它。

---

这对 AI 编码为何重要

将 CodeGraph 连接到 Claude Code、Cursor 或任何兼容 MCP 的 Agent 后：

之前： 你的 AI 会逐个读取文件、到处 grep，在收集上下文时消耗 token。

之后： 你的 AI 调用 agentic_impact({"query": "UserService"})，就能立即知道重构会造成哪些影响。

这不是渐进式改进，而是让 AI 从仅仅搜索代码，转变为真正理解代码。

这为何能增强编码 Agent 的能力

CodeGraph 将认知负担（搜索、相关性判断和依赖推理）转移到 CodeGraph 的 Agent 工具中，让你的编码 Agent 能将上下文预算用于实现改动，而不是发现要改什么。

Agent 工具的返回内容（示例）

agentic_impact 返回结构化输出（文件路径、行号以及有界代码片段／重点内容）和分析：

{
  "analysis_type": "dependency_analysis",
  "query": "RigAgentBuilder",
  "structured_output": {
    "analysis": "…what depends on RigAgentBuilder and why…",
    "highlights": [
      { "file_path": "crates/codegraph-mcp-rig/src/agent/builder.rs", "line_number": 48, "snippet": "pub struct RigAgentBuilder { … }" }
    ],
    "next_steps": ["…"]
  },
  "steps_taken": "5",
  "tool_use_count": 5
}

否则代码 Agent 必须完成的工作

如果没有 CodeGraph 的 Agent 工具，代码 Agent 通常需要进行多次“单一用途”调用，才能获得同等把握：

• 搜索符号（通常需要采用多种策略：文本搜索、语义搜索和类似 ripgrep 的搜索）
• 打开并阅读多个文件（定义、用法、调用方及相关模块）
• 根据不完整的证据在脑中还原依赖图／调用图
• 猜错时重新来过（读取更多内容，消耗更多令牌）

这会迅速耗尽上下文：仅阅读少数几个中等大小的文件及周边上下文，就很容易消耗数万个令牌；大型代码库则可能消耗数十万个令牌，具体取决于载入上下文的代码量。

使用 CodeGraph，Agent 可以获得精确的位置和关系（以及有界上下文），从而在上下文窗口中留出更多空间，用于规划和实现变更。

---

快速开始

1. 安装

# Clone and build with all features
git clone https://github.com/Jakedismo/codegraph-rust
cd codegraph-rust
./install-codegraph-full-features.sh

macOS 上更快的构建（LLVM lld）

如果你在 macOS 上开发，可以选择使用 LLVM 的 lld 链接器来加快链接速度：

# Install LLVM so ld64.lld is on PATH (Homebrew)
brew install llvm

# Use the repo-provided Makefile targets
make build-llvm
make test-llvm

2. 配置你的提供商

CodeGraph 需要一个用于索引的嵌入模型，以及一个供 Agent 工具使用的大模型。将设置写入项目中的 .env 文件（或导出这些设置）；codegraph init 会加载该文件。

# Embeddings
CODEGRAPH_EMBEDDING_PROVIDER=ollama          # ollama | lmstudio | jina | openai | onnx
CODEGRAPH_EMBEDDING_MODEL=qwen3-embedding:0.6b
CODEGRAPH_EMBEDDING_DIMENSION=1024

# Agent LLM
CODEGRAPH_LLM_PROVIDER=anthropic             # ollama | lmstudio | anthropic | openai | xai | openai-compatible
CODEGRAPH_LLM_MODEL=claude-sonnet-4
CODEGRAPH_CONTEXT_WINDOW=200000              # your model's real limit; selects the prompt tier
ANTHROPIC_API_KEY=sk-ant-...

请明确设置模型：如果未设置，Agent 会请求其提供商内置的默认模型。也可以将相同设置放在配置文件的 [llm] 部分（参见配置）；环境变量优先。.env.example 列出了所有受支持的变量，AI_PROVIDERS.md 则提供了各提供商的示例。

对于 Jina v5 嵌入，请使用受支持的检索任务：

CODEGRAPH_EMBEDDING_PROVIDER=jina
CODEGRAPH_EMBEDDING_MODEL=jina-embeddings-v5-text-small
CODEGRAPH_EMBEDDING_DIMENSION=1024
JINA_API_KEY=...
JINA_API_TASK=retrieval.passage
JINA_TRUNCATE=true
JINA_NORMALIZED=true

也会遵循显式设置的 JINA_API_TASK=retrieval.query。JINA_API_TASK 的优先级高于旧版 JINA_TASK 和 TOML [embedding] jina_task。如果未设置任务，v3/v5 默认使用 retrieval.passage，v4 默认使用 code.passage；搜索会使用对应的查询任务。V5 支持检索、文本匹配、分类和聚类任务，详见 Jina 的 API 架构。HTTP 422 等永久性嵌入 API 错误会立即失败并显示详细信息；临时故障仍会重试。更改任务或请求选项后，请重新索引，以替换按先前策略生成的向量。

可选的重排序功能会在查询时优化语义搜索结果，并且可以使用与嵌入不同的提供商。对于 Jina，请将以下内容写入 .env：

CODEGRAPH_RERANK_PROVIDER=jina
JINA_API_KEY=...
# JINA_RERANKING_MODEL=jina-reranker-v3  # default; no model setting required
# JINA_RERANKING_TOP_N=10

也可以在 .codegraph.toml 中选择提供商；其嵌套配置为可选：

[rerank]
provider = "jina"  # jina | ollama | none
top_n = 10

# [rerank.jina]
# model = "jina-reranker-v3"
# api_key_env = "JINA_API_KEY"
# api_base = "https://api.jina.ai/v1"

对于 Ollama，请设置 CODEGRAPH_RERANK_PROVIDER=ollama，并可选设置 CODEGRAPH_OLLAMA_RERANK_MODEL 和 CODEGRAPH_OLLAMA_URL。Jina 的 JINA_API_BASE 也会覆盖其重排序端点。环境设置会覆盖 TOML；CODEGRAPH_RERANK_PROVIDER 会覆盖旧版 JINA_ENABLE_RERANKING 开关，而 CODEGRAPH_ENABLE_RERANKING=false 会禁用所有重排序。旧版 CODEGRAPH_RERANKING_CANDIDATES 会覆盖 top_n，该参数控制重排序后保留的结果数。使用 codegraph config show --json 查看解析后的提供商／模型。对于文件名不带前导点的配置文件，请使用 --config codegraph.toml 或 CODEGRAPH_CONFIG_PATH=codegraph.toml。重排序器变更在重启命令行或服务后生效，无需重新索引。

3. 数据库

无需启动任何服务。SurrealDB 嵌入在 codegraph 中运行，每个项目都有自己的 SurrealKV 存储，位于 <project>/.codegraph/db。首次建立索引时，会使用随附的架构文件（schema/codegraph_v2.surql）创建该存储。该目录中会写入 .gitignore，因此不会纳入版本控制。

由于存储按项目划分，一个项目的数据绝不会与其他项目混在一起；删除某个项目的索引只需运行 rm -rf <project>/.codegraph/db。

同一时间只能有一个进程打开某个项目的存储。MCP 服务会在首次调用工具时打开存储，并一直保持打开状态，直到进程退出。因此，在同一项目上运行 codegraph index 前，请先停止正在运行的 codegraph start，并确保每个项目只连接一个客户端。

对于希望共用一个数据库的团队，仍然支持使用共享的 SurrealDB 服务（可自托管或使用 Surreal Cloud）：设置 CODEGRAPH_SURREALDB_URL 并自行应用架构。请参阅设置 SurrealDB。

4. 初始化并为项目建立索引

codegraph init /path/to/project

初始化时会先询问是否为项目添加本地钩子，可选择 Claude Code、Codex、两者或都不选。 它会保留现有设置，并在 CodeGraph 钩子已配置时跳过此提示。接下来，它会在 AGENTS.md 和 CLAUDE.md 中添加由它管理的 # codegraph 部分，保留其他指令， 然后递归为项目建立索引。指引会建议 Agent 使用 CodeGraph 的上下文、影响分析、 架构和质量命令行工具开始探索，并根据当前源代码核实发现。

对于脚本，请明确传入钩子选项；也可以在不建立索引的情况下运行设置：

codegraph init /path/to/project --hooks both --index-tier balanced
codegraph init /path/to/project --hooks none --no-index
# Existing index-only workflow, with explicit language filters:
codegraph index /path/to/project -r -l rust,typescript,python

--hooks none 会保留现有钩子，并继续更新这两个指令文件。设置过程绝不会修改用户级的运行环境配置。请确保 codegraph 位于运行环境的 PATH 中，并在设置后重新加载或检查项目钩子；请参阅初始化和钩子详情。

建立索引后，运行 python3 test_cli_agentic.py，即可使用与 test_http_mcp.py 相同的八个问题测试全部四个命令行 Agent 工具，打印完整答案，并将响应和耗时保存到 test_output_cli/。运行 python3 test_cli_agentic.py --replay test_output_cli，即可重放已保存的答案，无需发起新查询。请参阅命令行测试选项。

🔒 安全提示： 建立索引时会自动遵循 .gitignore，并过滤常见的机密信息模式（.env、credentials.json、*.pem、API 密钥等）。机密信息不会嵌入索引或暴露给 Agent。

5. 连接到 Claude Code

将以下内容添加到 MCP 配置中：

{
  "mcpServers": {
    "codegraph": {
      "command": "/full/path/to/codegraph",
      "args": ["start", "stdio", "--watch"]
    }
  }
}

就这么简单。 现在，你的 AI 已能理解你的代码库。

---

不同索引层级下的 Agent 命令行准确性

命令行评估使用与 HTTP MCP 测试相同的八个问题，问题定义见 agentic_test_cases.py。这些问题涵盖全部四种 Agent 工具的配置加载、 提示词选择、缓存、依赖关系、调用链、架构、公共 API 和复杂度。test_cli_agentic.py 会保存完整响应，便于手动对照源代码。

下方的快速入口早于当前针对模型的分词器、上下文和分块策略。 今后的层级比较应使用相同的当前输入策略和模型设置； 历史记录仍会保留，作为该次运行的记录。

索引层级	LLM / 请求模型	评估日期	CLI 响应检查	手动准确性发现
fast	gpt-6-luna（由项目所有者确认；运行器未记录）	2026-10-06	8/8 OK	情况不一：发现了一些有用信息，但答案不完整，且至少有两条经源代码确认的错误答案；未给出总体准确性评分
balanced（原始版）	gpt-6-luna（明确指定的请求模型）	2026-10-06	8/8 OK	配置、缓存、调用链方面的回答以及公共方法列表颇有帮助；直接调用方分类有误，Hub 结果不完整，指标说明存在不足；未给出总体准确性评分
balanced（刷新版）	gpt-6-luna（明确指定的请求模型）	2026-10-06	8/8 OK	Hub 排名、比例计算和包装器说明已修正；提示词、缓存和调用链覆盖不完整，遗漏了一个 API 方法；API 案例耗时 587.5 秒；未给出总体准确性评分
full（原始版）	gpt-6-luna（明确指定的请求模型）	2026-10-06	7/8 OK，1 个 TIMEOUT	配置、缓存、调用链和公共 API 的回答与源代码一致，且位置已验证；对缺失符号的替代回答较弱；无法获得 Hub 排名，且不稳定性数值不可靠；层级感知提示词案例两次超时；未给出总体准确性评分
full（刷新版）	gpt-6-luna（明确指定的请求模型）	2026-10-06	8/8 OK	提示词回答、Hub 排名和不稳定性计算现已正常；缓存细节不完整，遗漏了两个 API 方法，并重复了过时的 LATS 注释；架构案例耗时 546.4 秒；未给出总体准确性评分

OK 衡量的是命令/响应是否成功，而非事实是否正确。 这表示命令返回了有效的 JSON 答案，且未报告超时或部分结果标记。它不要求每个内部图工具都成功。尽管存在事实错误，fast 层级的全部八个响应仍通过了此检查。响应字段 tier: Massive 描述的是 Agent 的上下文窗口预算，与索引层级无关。

对 fast 层级答案的源代码审查发现：

• 调用链（案例 5）：活动实现不正确。 答案选中了 #[cfg(not(feature = "ai-enhanced"))] 错误桩 execute_agentic_workflow，并得出工作流不会调用图工具的结论。启用 AI 的实现 会创建 GraphToolExecutor 并调用 Rig Agent 执行器。答案未区分这两种条件编译实现。
• 公共 API（案例 7）：API 不完整，且使用结论有误。 答案称 GraphToolExecutor 没有直接用法，并认为相关变更彼此隔离、风险较低。其公共方法 包括构造函数、execute、缓存控制和工具元数据访问器；它被服务端工作流 和 Rig 工具工厂 使用。
• LRU 缓存（案例 3）：有用但不完整。 答案正确指出了按函数和参数缓存工具结果，但未说明问题要求的缓存命中、未命中、淘汰或清除行为。
• 缺失符号（案例 4）：恰当地表达了不确定性。 答案报告称找不到 PromptSelector，没有编造其依赖项。审查的源代码中不存在名为 PromptSelector 的 Rust 定义；解读结果时需要说明这一点。 平衡运行 20261006_041913_884481 通过 CODEGRAPH_LLM_MODEL 明确选择了 gpt-6-luna。全部八条命令均在 462.8 秒内返回了答案。 存储的索引报告包含 250 个文件、22,496 个节点、48,224 条边和 22,496 个代码块， 嵌入和语义阶段均已就绪。该运行使用 Ollama qwen3-embedding:0.6b 生成 1,024 维向量，并解析出 32,768 个 token 的服务上下文。 完整的平衡答案、运行详情和源代码审查 单独保留，不纳入 README 摘要。

对原始显式指定模型的平衡答案进行源代码审查后发现：

• 配置、提示词和缓存（案例 1–3）：有用且符合源码的说明。 答案涵盖了多种配置系统、dotenv/TOML 优先级、当前使用的 Rig 提示词构建器，以及缓存命中/未命中、成功结果插入、逐出、清除和无 TTL 等内容。提示词答案还指出了服务端/Rig 各自独立的层级解析路径。其关于八轮“硬上限”的说法需要加以限定：公开的构建器重载 接受其他值。
• 缺失符号和调用链（案例 4–5）：注意事项恰当，流程符合当前实现。 答案没有臆造 PromptSelector，说明了其替代目标，并区分了启用 AI 的工作流和禁用该功能时的存根实现。它追踪了当前调用路径：从 Rig 工具经过 CountingExecutor、GraphToolExecutor 和 GraphFunctions，最终到达 SurrealDB。
• 公开 API（案例 7）：方法名称完整，调用方分类错误。 答案列出了全部十个公开固有方法，并识别出真实的使用方。 但是，它将八个 Rig 工具适配器称为 GraphToolExecutor::execute 的直接调用方。它们调用的是 CountingExecutor::execute， 后者再委托给 GraphToolExecutor；因此，这些适配器属于间接调用方。
• 架构/指标（案例 6–7）：尽管状态为 OK，证据仍不完整。 Hub 查询在这两个案例中共失败五次，原因是 SurrealDB 的 array::concat() 超过了 1,048,576 字节的限制。架构答案说明了缺失的 hub 排名，并指出耦合值不一致以及结构体级计数为零却容易造成误导。 例如，报告的 Ca=19/Ce=66 与 instability=0.0 并不符合预期的 Ce/(Ca+Ce) 比率。这些指标不足以支持可靠的稳定性结论。
• 复杂度（案例 8）：报告的排名有参考价值，但有测量局限。 答案将 reconcile_project 排在首位，复杂度为 108，风险为 1,404。 查询 在预先筛选高复杂度候选项后，将风险计算为复杂度 ×（传入依赖边数量 + 1）。 这是一种启发式指标，并非经过校准的失败概率，也不保证是全局风险排名；传入边数量也不一定等于不同调用方的数量。

更新后的平衡运行 20261006_151920_418410 再次明确请求了 gpt-6-luna。全部八个案例均在 1,053.3 秒内返回 OK，共进行了 131 次工具调用 并汇总出 177 个位置。该运行使用新摄取的索引（238 个文件、 21,832 个节点、43,266 条边、23,387 个代码块）、Jina jina-embeddings-v5-text-small （1,024 维）、512-token AST 分块策略，以及当前的 600 秒截止时间。 更新后的审查和全部八个新答案 与原始运行一同保留。

• 已验证的改进： 架构案例现在可以返回中心性排名，不再出现之前的 array::concat 故障；显示的 7 个不稳定性比率经四舍五入后均与 Ce/(Ca+Ce) 一致。API 答案正确说明了 Rig 适配器通过 CountingExecutor 间接使用这些功能。8 条命令中没有记录图工具故障或 Jina 422 错误。
• 仍存在的准确性／覆盖范围缺口： 提示词答案遗漏了默认轮次预算和提示词构建器细节；缓存答案无法确认插入／截断是否成功，也遗漏了淘汰／清除操作；调用链在工具分发前的 RigExecutor::new 处中止。这些细节在原先平衡的答案中均有涵盖。API 列表遗漏了 graph_functions，缺失符号答案中有一行导入语句不正确。热点计算无误，但答案遗漏了候选范围和入边行的限定说明。
• 仍存在的延迟： API 命令耗时 587.5 秒。首次搜索完成后，日志中记录了 510.6 秒 的间隔，发生在下一次工具调用之前，即 Agent／模型轮次期间。尚未确定服务提供商一侧的原因。8 次成功响应并不能证明延迟问题已解决。
• 比较限制： 本次运行更改了嵌入、分块策略、二进制文件、索引内容、结果数量上限和截止时间。先前的评估文档中包含与这些问题相同的答案，并在案例 1–4 中被检索到。本次是结合源代码审查的运行冒烟测试，不是留出准确率基准测试，也不是对不同层级效果的受控测量。

原始完整运行 20261006_060847_378162 也明确选择了 gpt-6-luna。7 条命令返回了答案，案例 2（感知层级的提示词）触及 300 秒截止时间；包括这次超时在内，运行耗时 648.4 秒。存储的索引报告包含 238 个文件、34,494 个节点、104,224 条边和 34,494 个分块，并标记为已完成，嵌入和语义阶段已就绪，且包含数据流、LSP、模块和文档分析器的输出。嵌入设置与原始平衡运行相同。 完整答案、运行详情和源代码审查另行保存。

本次评估之后，默认的整个 Agent CLI 截止时间以及 CLI／HTTP 共用的测试用例截止时间均从 300 秒提高到 600 秒。--timeout-secs 仍可覆盖 CLI 预算。原始完整层级表格中的条目仍保留 300 秒截止时间；两次完整的刷新运行均使用 600 秒。原先记录的停滞发生在图调用返回后等待模型响应期间。

对原始完整层级答案的源代码审查发现：

• 配置、缓存、调用链和公共 API（案例 1、3、5、7）：与源码一致， 所有核查位置均匹配。 配置答案列出了主加载器、dotenv 初始化、Agent 的 [llm] 覆盖层、MCP-core 和高级配置加载器、JSON 管道加载器以及直接读取环境变量的代码；但主加载器的调用方列表不完整。缓存答案涵盖命中、未命中、截断后插入、驱逐和清除，但有一处行号范围偏移了一个函数。调用链答案追踪的是启用 AI 的工作流，而不是禁用该功能时的存根。API 答案列出了全部 10 个公共方法；与原先平衡的答案不同，它正确地将 Rig 适配器描述为通过 CountingExecutor 间接调用。
• 分层提示词（案例 2）：无答案。 本次运行和单案例重跑中，命令都超时了。两次运行中，Agent 均在一分钟内完成工具调用，剩余时间都花在等待模型响应上。原因尚未查明；平衡运行在 72 秒内回答了此案例。
• 缺失的符号（案例 4）：如实说明其不存在，但替代内容较弱。 答案指出 PromptSelector 不存在，随后分析了 prompt_selection，即 codegraph init 的钩子选择提示词，这与分层提示词无关。答案对该函数的描述是正确的。
• 架构（案例 6）：结构准确，未能对枢纽排序。 两次枢纽查询都因与平衡运行相同的 array::concat() 1,048,576 字节限制而失败；在此索引上直接调用该函数也会重现此故障。答案披露了这一缺陷，并指出对于具有出向依赖的节点，稳定性会报告为 0.0。对抽样的 5 个节点直接调用，结果均为 0.0：该表达式（现已修正）将两个整数计数相除，而整数除法会截断比率。 耦合计数不受影响，但无法据此得出稳定性结论。
• 复杂度（案例 8）：算术一致，排序不同。 所有 20 个风险分数都符合复杂度 ×（入向依赖边数量 + 1）。解析器的 walk 函数现在排名靠前（Rust 遍历器：复杂度为 31，有 100 条入向边，风险分数为 3,131），而 reconcile_project 降至第 8 位，因为完整索引的边数是之前的两倍以上，且查询统计的是边记录，而非不同的调用方。

案例 2 超时、枢纽查询失败以及 0.0 稳定性值，均可追溯到现已修复的缺陷：工具结果没有大小限制（一次搜索可能返回 228 KB，且单次运行没有总量限制）、枢纽查询超出了 array::concat 的大小限制，以及稳定性比率使用整数相除。在同一索引上应用修复后重跑案例 2 和 6，分别在 79 秒和 106 秒后返回 OK，并得到了枢纽排序和非零稳定性；其他案例没有重跑。请参阅后续章节。

刷新后的完整运行 20261006_162918_871171 明确指定了 gpt-6-luna。全部 8 个案例均返回 OK，耗时 901.8 秒，共进行了 99 次工具调用，涉及 172 个位置。目录记录了 239 个文件、34,998 个节点、100,107 条边和 36,600 个分块，其中包括 LSP 定义和数据流输出。它使用了与刷新后的平衡运行相同的已安装二进制文件、Jina v5 嵌入和分块策略，以及 Agent 设置。完整的刷新后评审和全部 8 个答案与原始完整运行并列保留。

• 已验证的改进： 提示词案例在 82.9 秒后返回，现在涵盖提示词组合、构建器接线以及 3/5/6/8 的默认轮次预算。Hub 排名成功，显示的全部八个架构不稳定性比率均符合 Ce/(Ca+Ce)。日志中没有图工具故障或 Jina 422 错误。对于不存在的符号，回答明确拒绝用无关的钩子提示词替代。
• 尚存的准确性／覆盖范围缺口： 缓存插入／淘汰以及截断后的存储情况仍未得到证实。API 列表遗漏了 graph_functions 和 clear_cache。调用链到达图调度，但重复了一条过时的枚举注释，称 LATS 无法使用工具；当前实现实际上可以。该注释、环境示例和安装指南已在运行后更正；保存的回答未变，索引中仍包含过时文本。
• 指标说明： 耦合度对相邻图节点去重；Hub 度数和热点风险按依赖边行计数。两者都包含数据流关系，而不只是调用。显示的全部 20 项风险计算和声明起始位置均正确，但风险只是对高复杂度候选集的启发式评估，并非有保证的全局风险排名，也不代表不同调用方的数量。
• 尚存的延迟问题： 架构案例耗时 546.4 秒，其中搜索完成后到下一次工具调用之间，在一次 Agent／模型轮次中有 479.6 秒的间隔。尚未确定提供方侧的原因。API 案例在 69.4 秒后返回；延迟只是在不同案例间转移，并未得到普遍解决。
• 比较限制： 检出版本、图内容和文件数量仍有差异，且模型推理和缓存热度未受控。案例 1–3 检索到了之前评估文档，因此这并非留出准确性基准测试。此次 ReAct 运行使用的二进制版本早于 LATS 修复，且未对 LATS 进行实时验证。

所有 7 个已完成的原始完整层级案例和所有 8 个原始均衡案例都记录了类型化答案解析警告；服务端改为从工具轨迹合成结构化证据。运行器接受了生成的 JSON 响应。刷新后的均衡和完整运行也会为文字回答合成要点；现在回退会记录在 DEBUG 级别。这些回退和内部工具错误都不能作为事实准确性评分。初始均衡诊断运行 20261006_041408_086869 单独保留，因为它未明确选择预期的请求模型。

快速基准是本地运行 20261006_013512_392882。其索引层级来自测试会话，gpt-6-luna 模型标签来自项目所有者；运行器不会自动记录这两项设置。在均衡评估期间，源码审查发现 Rig 适配器从 CODEGRAPH_LLM_MODEL，再从 CODEGRAPH_AGENT_MODEL 选择模型；当时它不会读取核心配置中的 CODEGRAPH_MODEL，因此如果只设置后者，OpenAI Rig 路径默认会请求 gpt-4o。（此后已修改适配器，使其回退到 CODEGRAPH_MODEL，再回退到 [llm] model。）快速运行保存的响应未记录请求模型，因此该标签依据所有者的确认。 为确保 Agent 比较可复现，请明确设置 CODEGRAPH_LLM_MODEL。这些标签表示已配置／请求的模型；运行器不会验证提供方侧的路由情况。

这些观察无法将索引层级的影响与模型推理效果区分开来，也无法确定数值准确率。各次运行在检出版本、已安装的二进制文件、文件数量、嵌入／输入策略、结果限制和截止时间方面也存在差异。后续比较时，请保持问题、模型、Agent 上下文预算和推理设置一致；记录源码修订版本和索引配置，并说明不同运行之间的变更。分配准确性评分前，请检查源码位置、当前生效的条件代码、完整性以及缺乏依据的结论。

---

架构

查看交互式架构图 - 通过可点击的组件和分层筛选，探索完整的工作区结构。

┌─────────────────────────────────────────────────────────────────┐
│                         Claude Code / MCP Client                │
└─────────────────────────────────┬───────────────────────────────┘
                                  │ MCP Protocol
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                        CodeGraph MCP Server                     │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                    Agentic Tools Layer                    │  │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐  │  │
│  │  │  ReAct  │ │  LATS   │ │Reflexion│ │ Tool Execution  │  │  │
│  │  │  (Rig)  │ │  (Rig)  │ │  (Rig)  │ │    Pipeline     │  │  │
│  │  └────┬────┘ └────┬────┘ └────┬────┘ └────────┬────────┘  │  │
│  └───────┼───────────┼───────────┼───────────────┼───────────┘  │
│          └───────────┴───────────┴───────────────┘              │
│                              │                                  │
│  ┌───────────────────────────┼───────────────────────────────┐  │
│  │                  Inner Graph Tools                        │  │
│  │  ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐   │  │
│  │  │ Transitive   │ │    Call      │ │     Coupling     │   │  │
│  │  │ Dependencies │ │   Chains     │ │     Metrics      │   │  │
│  │  └──────────────┘ └──────────────┘ └──────────────────┘   │  │
│  │  ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐   │  │
│  │  │   Reverse    │ │    Cycle     │ │       Hub        │   │  │
│  │  │    Deps      │ │  Detection   │ │      Nodes       │   │  │
│  │  └──────────────┘ └──────────────┘ └──────────────────┘   │  │
│  └───────────────────────────┬───────────────────────────────┘  │
└──────────────────────────────┼──────────────────────────────────┘
                               │
┌──────────────────────────────┼──────────────────────────────────┐
│                         SurrealDB                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   Nodes     │  │    Edges    │  │   Chunks + Embeddings   │  │
│  │  (AST +     │  │  (calls,    │  │   (HNSW vector index)   │  │
│  │   FastML)   │  │   imports)  │  │                         │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
│                                                                 │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │              SurrealQL Graph Functions                     │ │
│  │   fn::semantic_search_nodes_via_chunks                     │ │
│  │   fn::semantic_search_chunks_with_context                  │ │
│  │   fn::get_transitive_dependencies                          │ │
│  │   fn::trace_call_chain                                     │ │
│  │   fn::calculate_coupling_metrics                           │ │
│  └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

关键见解： Agentic 工具不会只调用一个函数。它们会对要执行哪些图操作进行推理，将这些操作串联起来，并综合结果。一次 agentic_impact 调用可能会：

1. 通过语义搜索查找目标组件
2. 获取其直接依赖项
3. 追踪传递依赖项
4. 检查是否存在循环依赖
5. 计算耦合指标
6. 找出可能受到影响的枢纽节点
7. 将所有发现综合成可执行的答案

---

支持的语言

CodeGraph 使用 tree-sitter 进行初始解析，并通过 FastML 算法增强结果，支持：

Rust • Python • TypeScript • JavaScript • Go • Java • C++ • C • Swift • Kotlin • C# • Ruby • PHP • Dart

---

提供商灵活性

嵌入

使用维度为 384-4096 的任意模型：

• 本地： Ollama、LM Studio、ONNX Runtime
• 云端： OpenAI、Jina AI

LLM（用于 Agentic 推理）

• 本地： Ollama、LM Studio
• 云端： Anthropic Claude、OpenAI、xAI Grok、OpenAI Compliant

数据库

• SurrealDB 3.x 嵌入式（SurrealKV，每个项目使用一个存储，无需运行服务），支持 HNSW 向量索引
• 可选：共享 SurrealDB 服务，或通过 CODEGRAPH_SURREALDB_URL 使用 Surreal Cloud

---

配置

构建需要 Rust 1.95 或更高版本，并使用 2024 版。直接依赖项指向当前稳定版本；Cargo.lock 记录解析后的依赖关系图。Bincode 使用 2.0.1，这是其最后一个可正常使用的版本；3.0.0 会有意导致编译失败。ONNX Runtime 绑定使用最新候选发布版 2.0.0-rc.13，因为目前还没有稳定的 2.0 版本。

CLI 会在启动工作线程前加载项目或用户的 dotenv 配置。 库的调用方应在进程启动时初始化环境；ConfigManager::load() 只读取配置，不会更改进程环境。

codegraph init 会配置所选项目，并在索引前加载其环境。codegraph config init 是用于创建全局应用配置的独立命令；项目初始化不会配置模型提供商。

配置文件依次从 ./.codegraph.toml（项目）和 ~/.codegraph/config.toml （用户）读取；工作目录中的 .env 文件和 CODEGRAPH_* 环境变量会覆盖它们：

[embedding]
provider = "ollama"
model = "qwen3-embedding:0.6b"
dimension = 1024

[llm]
provider = "anthropic"
model = "claude-sonnet-4"
context_window = 200000

[indexing]
tier = "fast"

内置 Agent 会分三步解析每项 LLM 设置：先读取环境变量（项目 .env 也算），再读取配置文件 [llm] 部分中的键，最后使用默认值。若 [llm] 中的 enabled = false，Agent 会忽略该部分；API 密钥只从环境中读取。codegraph config agent-status 会显示当前生效的提供商、模型和层级；AI_PROVIDERS.md 列出了所有变量和键。

存储无需配置：默认使用每个项目的嵌入式存储，除非 CODEGRAPH_SURREALDB_URL（以及其他 CODEGRAPH_SURREALDB_* 变量）指向某个服务。CODEGRAPH_SCHEMA=v1 会为新存储选择原始的 schema/codegraph.surql。

完整配置选项请参阅 INSTALLATION_GUIDE.md。

实验性图模式（可选）

CodeGraph 可以使用实验性的 SurrealDB graphdb 风格模式（schema/codegraph_graph_experimental.surql）运行，并与现有的 CodeGraph 工具和索引流程互通。

与默认模式（schema/codegraph_v2.surql）相比，实验性模式旨在提升大型代码库上图查询操作（遍历、邻域扩展和工具驱动的图分析）的速度和效率。

若要将其用于嵌入式存储，请在首次创建项目存储之前设置该标志 （或删除 <project>/.codegraph/db 并重新索引）：

CODEGRAPH_USE_GRAPH_SCHEMA=true

若使用 SurrealDB 服务，请将模式加载到专用数据库中一次，然后让 CodeGraph 指向该数据库：

surreal sql --conn ws://localhost:3004 --ns ouroboros --db codegraph_experimental < schema/codegraph_graph_experimental.surql
CODEGRAPH_USE_GRAPH_SCHEMA=true
CODEGRAPH_GRAPH_DB_DATABASE=codegraph_experimental

注意：

• 模式文件为多个嵌入维度（384–4096）定义了 HNSW 索引，因此你可以切换嵌入模型，而无需重新配置数据库。
• 现有存储会保留其创建时使用的模式；切换模式意味着需要新建存储。
• CODEGRAPH_GRAPH_DB_DATABASE 仅适用于服务模式。

---

守护进程模式

自动保持索引最新：

# With MCP server (recommended)
codegraph start stdio --watch

# Standalone daemon
codegraph daemon start /path/to/project --languages rust,typescript

系统会检测更改、进行防抖处理，并在后台重新索引。

对于嵌入式的每项目存储，请使用 --watch：此时监视器会在 MCP 服务进程内运行。独立守护进程是单独的进程，无法与运行中的服务共享项目存储， 因此仅在该项目没有服务运行时，或使用 SurrealDB 服务时才使用它。

---

接下来

• 支持更多语言
• 跨仓库分析
• 自定义图模式
• 自定义分析器插件系统

---

理念

CodeGraph 的存在，是因为我们相信 AI 编码助手应该得到增强，而非被取代。当 AI 深入了解你正在处理的内容时，AI 与人类才能实现最佳协作。

我们无意取代你的 IDE、类型检查器或测试，而是为你的 AI 提供真正发挥帮助所需的上下文。

你的代码库是一张图。让你的 AI 以这种方式观察它。

---

许可证

MIT

---

链接

• 安装指南
• SurrealDB Cloud（免费层级）
• Jina AI（免费 API 令牌）
• Ollama（本地模型）

---