企业官网建设流程全解析

1. 从 codegraph 说起：代码图谱到底在解决什么问题

第一次看到 codegraph 这个词，很多人会下意识把它当成又一个"AI 编程工具"的周边插件。但如果你真的在几十万行的老项目里翻过代码，就会明白它想解决的是一个非常具体的痛点：当代码库大到人脑装不下时，怎么让 AI 助手真正"看懂"整个项目，而不是只盯着你打开的那一个文件。

我最早接触这个概念是在用 Claude Code 处理一个遗留系统的时候。那个项目有大概 40 万行代码，分散在十几个模块里，函数调用关系错综复杂。我让 Claude Code 帮我改一个底层的工具函数，它改完之后信誓旦旦说"已经检查了所有调用点"，结果一编译，十几个地方报错——因为它根本没看到那些跨模块的引用。这就是典型的"上下文窗口不够用"问题：AI 再聪明，你喂给它的信息有限，它就只能在有限视野里做判断。

codegraph 的核心思路，就是在 AI 和代码库之间加一层"代码知识图谱"。它把项目里的文件、类、函数、变量、导入导出关系、调用链路全部抽出来，建成一张有向图，然后 AI 需要什么就按图索骥去取，而不是把整个项目硬塞进上下文。这个思路和传统 IDE 的"跳转到定义""查找引用"本质是一回事，区别在于它是给 AI 用的，而且粒度更细、关系更全。

围绕这个核心，热词里出现了一堆相关工具：Claude Code、Codex、Gemini、Cursor。它们各自代表了不同的技术路线——Claude Code 和 Codex 是命令行/终端优先的 agent 型工具，Gemini 走的是云端大模型加代码助手的路子，Cursor 则是把 AI 深度集成进编辑器。codegraph 这类图谱方案，本质上是要给这些工具提供一个"共享的代码理解底座"。

这篇文章适合几类人看：一是正在用 Claude Code、Codex、Cursor 这类工具但觉得"AI 老是改错地方"的开发者；二是团队里负责搭建 AI 辅助开发流程的技术负责人；三是对代码静态分析、知识图谱感兴趣，想自己动手做一个类似工具的人。我会从设计思路、核心实现、实操步骤、踩坑经验四个层面把它讲透，尽量让你看完能自己复现一个最小可用的版本。

2. 整体设计思路：为什么是图谱，而不是向量检索

2.1 向量检索的天花板在哪里

现在大部分 AI 编程助手处理大项目的默认方案是向量检索：把代码切成小块，每块算一个 embedding，存进向量数据库，用户提问时按语义相似度召回最相关的几块喂给模型。这个方案上手快、实现简单，但用在代码上有几个硬伤。

第一个硬伤是代码的语义和自然语言不一样。你搜"用户登录逻辑"，向量检索可能召回一堆注释里带"login"的函数，但真正调用链上的关键函数可能因为命名是authenticate或者verifyCredential而排到后面。代码的相关性更多取决于结构关系（谁调用谁、谁继承谁），而不是文本相似度。

第二个硬伤是切块会切断上下文。一个函数被切成三块，模型看到的是碎片，它不知道这个函数的完整签名、不知道它被谁调用、不知道它依赖哪些全局状态。改出来的代码经常"局部正确、全局崩盘"。

第三个硬伤是无法回答结构性问题。"这个模块的入口在哪""改这个接口会影响哪些下游""有没有循环依赖"——这些问题向量检索基本答不了，因为它没有全局视图。

2.2 图谱方案的核心优势

codegraph 走的是另一条路：先把代码解析成结构化的图，再让 AI 基于图做推理。具体来说，它至少包含三类节点和三类边：

有了这张图，AI 要改一个函数时，可以沿着"调用边"反向找到所有调用者，沿着"导入边"找到所有依赖，沿着"包含边"找到所在文件。这些信息是确定性的、可验证的，不像向量检索那样靠概率猜。

更重要的是，图谱可以增量更新。你改了一个文件，只需要重新解析这个文件及其直接邻居，不用重建整个索引。这对大型项目来说是刚需——全量重建一次可能要几分钟甚至几十分钟，增量更新通常在一秒内完成。

2.3 和 Claude Code、Codex、Cursor 的关系

这里要澄清一个容易混淆的点：codegraph 不是要替代这些工具，而是给它们提供更好的上下文。

Claude Code 和 Codex 这类 agent 工具，本身有文件读写、命令执行的能力，但它们"看代码"的方式比较原始——要么你手动指定文件，要么它自己用 grep 去搜。有了 codegraph，agent 可以先查图，精确定位到相关文件和相关符号，再决定读哪些、改哪些。这能显著减少"读了一堆无关文件浪费 token"和"漏掉关键调用点改出 bug"两种情况。

Cursor 这类编辑器集成的工具，本身有 LSP（语言服务器协议）提供的跳转和引用能力，但 LSP 是给人用的、按需触发的，AI 用起来不够顺手。codegraph 相当于把 LSP 的能力批量化、图结构化，让 AI 可以一次性拿到某个符号的完整关系网。

Gemini 的代码助手走的是云端路线，它对本地代码库的访问受限，图谱方案对它来说更多是"上传一份结构摘要"的思路——把图序列化成紧凑的文本，让云端模型也能理解项目结构。

2.4 方案选型的关键取舍

自己动手做 codegraph，有几个关键决策点，我按重要性排一下：

第一，解析器选型。你可以用现成的语言服务器（比如 TypeScript 的 tsserver、Python 的 jedi），也可以用 tree-sitter 这类通用解析器，还可以直接上各语言官方的 AST 库。我的建议是：优先用 tree-sitter。它支持几十种语言、解析速度快、API 统一，虽然拿到的 AST 比语言服务器粗一些，但对建图来说够用了。语言服务器的优势是类型信息全，但启动慢、内存占用高，不适合做批量索引。

第二，图的存储。小项目（几万行以内）直接用内存里的字典加列表就行，简单直接。中等项目（几十万行）建议上 SQLite，用表存节点和边，查询用 SQL，稳定可靠。大项目（百万行以上）才需要考虑 Neo4j 这类图数据库，但说实话，大部分团队用不到这个量级，SQLite 加好索引完全够。

第三，更新策略。全量重建简单但慢，增量更新快但实现复杂。我的经验是先做全量，再做增量。全量版本能跑通、能验证正确性之后，再加文件监听做增量。别一上来就追求增量，容易在缓存一致性上翻车。

第四，和 AI 工具的对接方式。最通用的是提供一个 CLI，输入符号名输出关系网，让 agent 通过命令行调用。也可以做成 MCP（模型上下文协议）服务器，这样 Claude Code、Cursor 这些支持 MCP 的工具能直接调用。MCP 方式更优雅，但需要工具本身支持，CLI 方式兼容性最好。

3. 核心细节解析：从源码到图谱的完整链路

3.1 解析阶段：怎么把代码变成 AST

解析是整个流程的地基，地基不稳后面全白搭。以 tree-sitter 为例，基本流程是这样的：

import tree_sitter from tree_sitter import Language, Parser # 加载语言（以 Python 为例） PY_LANGUAGE = Language('build/my-languages.so', 'python') parser = Parser() parser.set_language(PY_LANGUAGE) # 读取源码并解析 with open('example.py', 'rb') as f: source = f.read() tree = parser.parse(source) root = tree.root_node

拿到 AST 之后，你需要遍历树，提取出你关心的节点。对建图来说，至少要提取这几类：

• 函数定义：function_definition、method_definition
• 类定义：class_definition
• 调用表达式：call_expression
• 导入语句：import_statement、import_from_statement
• 变量赋值：assignment（可选，看你要不要追踪数据流）

遍历的时候要注意一个坑：tree-sitter 的节点类型名是语言相关的。Python 里叫function_definition，JavaScript 里可能叫function_declaration，Go 里又是另一套。所以你的提取逻辑要么按语言分别写，要么抽象出一层映射表。我建议后者，维护起来清晰。

NODE_TYPE_MAP = { 'python': { 'function': ['function_definition'], 'class': ['class_definition'], 'call': ['call_expression'], 'import': ['import_statement', 'import_from_statement'], }, 'javascript': { 'function': ['function_declaration', 'arrow_function', 'method_definition'], 'class': ['class_declaration'], 'call': ['call_expression'], 'import': ['import_statement'], }, }

3.2 符号解析：怎么确定"这个调用指向哪个函数"

这是整个流程里最容易出错、也最考验功力的一步。你在代码里看到foo()，怎么知道它调用的是哪个foo？可能有同名的局部函数、导入的函数、类的方法、全局函数。

我的做法是分层解析，从近到远：

1. 先查当前作用域：当前函数内定义的局部函数、当前类的方法。
2. 再查当前文件：文件顶层定义的函数、导入的符号。
3. 最后查全局：如果前两层都没找到，标记为"未解析"，不要瞎猜。

对于导入的符号，要顺着导入语句找到源文件，再在源文件里查。这一步需要维护一个模块路径到文件路径的映射，不同语言的规则不一样：

• Python：from a.b import c→ 找a/b.py或a/b/__init__.py里的c
• JavaScript：import { c } from './a/b'→ 找./a/b.js或./a/b/index.js里的c
• Go：import "a/b"→ 找a/b包里的导出符号

这里有个实用技巧：先做一遍全量符号表，再做调用解析。也就是说，第一遍遍历所有文件，把每个文件里定义了哪些符号、导入了哪些符号记下来；第二遍再解析调用关系，这时候查符号表就是 O(1) 的字典查找，比每次重新遍历 AST 快得多。

3.3 建图阶段：节点和边怎么组织

符号解析完之后，建图就是水到渠成的事。我用的数据结构是这样的：

class CodeGraph: def __init__(self): self.nodes = {} # id -> node_info self.edges = {} # (from_id, to_id, edge_type) -> edge_info self.symbol_index = {} # (file_path, symbol_name) -> node_id def add_node(self, node_id, node_type, name, file_path, line): self.nodes[node_id] = { 'type': node_type, 'name': name, 'file': file_path, 'line': line, } def add_edge(self, from_id, to_id, edge_type): key = (from_id, to_id, edge_type) self.edges[key] = {'type': edge_type}

节点 ID 的生成规则很重要，要稳定且唯一。我一般用文件路径:符号名:行号的格式，这样同一个符号在多次解析之间 ID 不变，方便做增量更新和缓存。

边的类型我建议至少保留这几种：

• contains：文件包含符号
• calls：函数调用函数
• imports：文件导入文件
• inherits：类继承类
• implements：类实现接口

有了这些边，你就能回答很多有价值的问题。比如"改这个函数会影响谁"，就是沿着calls边反向遍历；"这个文件的依赖树"，就是沿着imports边正向遍历。

3.4 查询接口：让 AI 能方便地取用

图建好了，怎么让 AI 用起来？我设计了几个核心查询接口：

def get_callers(self, symbol_id, depth=1): """获取调用某符号的所有符号，支持多级""" result = [] current = [symbol_id] for _ in range(depth): next_level = [] for sid in current: for (f, t, etype) in self.edges: if t == sid and etype == 'calls': result.append(f) next_level.append(f) current = next_level return result def get_callees(self, symbol_id, depth=1): """获取某符号调用的所有符号""" # 类似实现，方向相反 pass def get_file_symbols(self, file_path): """获取某文件定义的所有符号""" return [nid for nid, info in self.nodes.items() if info['file'] == file_path and info['type'] != 'file'] def find_symbol(self, name, file_path=None): """按名字查找符号，可限定文件""" if file_path: return self.symbol_index.get((file_path, name)) # 全局查找，可能返回多个 return [nid for nid, info in self.nodes.items() if info['name'] == name]

这些接口输出的是结构化的 JSON，可以直接喂给 AI。比如 AI 要改UserService.login，你先调get_callers拿到所有调用点，再调get_callees拿到它依赖的东西，把这些信息一起塞进 prompt，AI 的判断准确率会高很多。

提示：查询接口的输出要控制体积。一个热门函数可能有几百个调用者，全塞进去会撑爆上下文。我的做法是默认只返回一级关系，超过 20 个结果就截断并提示"还有 N 个调用者未显示"，让 AI 决定要不要深入。

4. 实操过程：从零搭一个最小可用的 codegraph

4.1 环境准备与依赖安装

我以 Python 项目为例，走一遍完整流程。你需要准备：

• Python 3.10 以上（3.11 更好，性能有提升）
• tree-sitter 及其 Python 绑定
• 一个代码编辑器（VS Code 就行）

安装依赖：

pip install tree-sitter tree-sitter-languages

tree-sitter-languages这个包把常见语言的语法都打包好了，省得你自己编译。如果你要支持的语言它没有，就得自己用tree-sitter build编译.so文件。

验证安装：

from tree_sitter_languages import get_parser parser = get_parser('python') tree = parser.parse(b'def foo(): pass') print(tree.root_node.type) # 应该输出 module

能打印出module就说明环境没问题。

4.2 第一步：遍历项目，收集所有源文件

先写一个文件遍历器，把项目里所有源文件找出来。要注意排除掉不该解析的目录：

import os EXCLUDE_DIRS = {'.git', 'node_modules', '__pycache__', 'venv', '.venv', 'dist', 'build', '.idea', '.vscode'} SOURCE_EXTS = {'.py', '.js', '.ts', '.go', '.java'} def walk_source_files(root_dir): for dirpath, dirnames, filenames in os.walk(root_dir): # 原地修改 dirnames 实现剪枝 dirnames[:] = [d for d in dirnames if d not in EXCLUDE_DIRS] for fname in filenames: ext = os.path.splitext(fname)[1] if ext in SOURCE_EXTS: yield os.path.join(dirpath, fname)

这里有个细节：用dirnames[:] = [...]而不是dirnames = [...]。前者是原地修改，os.walk 会尊重这个修改；后者只是重新绑定局部变量，os.walk 看不到，剪枝就失效了。这个坑我踩过，当时纳闷为什么 node_modules 还是被遍历了。

4.3 第二步：解析单个文件，提取符号和调用

这是核心逻辑，我把它拆成两个函数：一个提取定义，一个提取调用。

from tree_sitter_languages import get_parser def extract_definitions(tree, source_bytes, file_path): """提取文件里定义的所有符号""" definitions = [] parser = get_parser('python') def visit(node, parent_symbol=None): if node.type == 'function_definition': name_node = node.child_by_field_name('name') if name_node: definitions.append({ 'type': 'function', 'name': source_bytes[name_node.start_byte:name_node.end_byte].decode(), 'line': node.start_point[0] + 1, 'parent': parent_symbol, }) elif node.type == 'class_definition': name_node = node.child_by_field_name('name') if name_node: class_name = source_bytes[name_node.start_byte:name_node.end_byte].decode() definitions.append({ 'type': 'class', 'name': class_name, 'line': node.start_point[0] + 1, 'parent': parent_symbol, }) # 递归处理类体，parent 设为类名 for child in node.children: visit(child, class_name) return for child in node.children: visit(child, parent_symbol) visit(tree.root_node) return definitions

提取调用稍微复杂一点，因为要处理foo()、obj.method()、module.func()这几种形式：

def extract_calls(tree, source_bytes): """提取文件里所有的函数调用""" calls = [] def visit(node): if node.type == 'call_expression': func_node = node.child_by_field_name('function') if func_node: call_text = source_bytes[func_node.start_byte:func_node.end_byte].decode() calls.append({ 'text': call_text, 'line': node.start_point[0] + 1, }) for child in node.children: visit(child) visit(tree.root_node) return calls

call_text可能是foo、self.foo、module.foo、a.b.c各种形式。解析的时候要按.拆分，取最后一段作为符号名，前面的部分作为限定符。限定符用来消歧——self.foo里的self说明是当前类的方法，module.foo说明是导入模块的函数。

4.4 第三步：构建符号表，解析调用目标

这一步把前面收集的信息整合起来，建立"符号名 → 符号 ID"的映射，然后解析每个调用指向哪个符号。

class SymbolTable: def __init__(self): self.by_file = {} # file_path -> {symbol_name: symbol_id} self.by_name = {} # symbol_name -> [symbol_id, ...] self.imports = {} # file_path -> {alias: target_file} def add_symbol(self, file_path, name, symbol_id): self.by_file.setdefault(file_path, {})[name] = symbol_id self.by_name.setdefault(name, []).append(symbol_id) def resolve_call(self, file_path, call_text, current_class=None): """解析一个调用指向哪个符号""" parts = call_text.split('.') name = parts[-1] qualifier = parts[-2] if len(parts) >= 2 else None # 1. 如果是 self.xxx，查当前类的方法 if qualifier == 'self' and current_class: class_symbols = self.by_file.get(file_path, {}) # 这里简化处理，实际要按类名限定 if name in class_symbols: return class_symbols[name] # 2. 查当前文件 if name in self.by_file.get(file_path, {}): return self.by_file[file_path][name] # 3. 查导入 if file_path in self.imports and qualifier in self.imports[file_path]: target_file = self.imports[file_path][qualifier] if name in self.by_file.get(target_file, {}): return self.by_file[target_file][name] # 4. 全局查找（可能多个，返回第一个或标记歧义） if name in self.by_name: return self.by_name[name][0] return None # 未解析

这个解析器是启发式的，不可能 100% 准确。Python 的动态特性（比如getattr、猴子补丁）会让静态解析失效。但对建图来说，80% 的准确率已经能带来巨大价值，剩下 20% 标记为"未解析"就行，不要强行猜。

4.5 第四步：持久化到 SQLite

图建好之后要存起来，不然每次重启都重新解析太慢。SQLite 是最省事的选择：

import sqlite3 def init_db(db_path): conn = sqlite3.connect(db_path) conn.executescript(''' CREATE TABLE IF NOT EXISTS nodes ( id TEXT PRIMARY KEY, type TEXT NOT NULL, name TEXT NOT NULL, file TEXT NOT NULL, line INTEGER, parent TEXT ); CREATE TABLE IF NOT EXISTS edges ( from_id TEXT NOT NULL, to_id TEXT NOT NULL, edge_type TEXT NOT NULL, PRIMARY KEY (from_id, to_id, edge_type) ); CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name); CREATE INDEX IF NOT EXISTS idx_nodes_file ON nodes(file); CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(from_id); CREATE INDEX IF NOT EXISTS idx_edges_to ON edges(to_id); ''') return conn

索引很关键。idx_nodes_name让按名字查符号变快，idx_edges_from和idx_edges_to让正向和反向遍历都高效。没有索引的话，几十万条边查一次要好几秒。

写入的时候用批量插入加事务，比逐条插入快几十倍：

def save_graph(conn, nodes, edges): with conn: conn.executemany( 'INSERT OR REPLACE INTO nodes VALUES (?, ?, ?, ?, ?, ?)', [(n['id'], n['type'], n['name'], n['file'], n['line'], n.get('parent')) for n in nodes] ) conn.executemany( 'INSERT OR REPLACE INTO edges VALUES (?, ?, ?)', [(e['from'], e['to'], e['type']) for e in edges] )

4.6 第五步：提供 CLI 查询接口

最后包一层命令行，让 AI 工具能调用：

import argparse import json def main(): parser = argparse.ArgumentParser() parser.add_argument('command', choices=['callers', 'callees', 'symbols', 'find']) parser.add_argument('target') parser.add_argument('--depth', type=int, default=1) parser.add_argument('--db', default='codegraph.db') args = parser.parse_args() conn = sqlite3.connect(args.db) if args.command == 'callers': result = query_callers(conn, args.target, args.depth) elif args.command == 'callees': result = query_callees(conn, args.target, args.depth) elif args.command == 'symbols': result = query_file_symbols(conn, args.target) elif args.command == 'find': result = query_find_symbol(conn, args.target) print(json.dumps(result, ensure_ascii=False, indent=2))

用起来就是：

python codegraph.py callers UserService.login --depth 2

输出一段 JSON，列出所有调用UserService.login的符号，以及它们的调用者。AI agent 拿到这段 JSON，就知道改这个方法要检查哪些地方。

注意：CLI 的输出格式要稳定。字段名、嵌套结构一旦定下来就别随便改，因为 AI 的 prompt 里可能硬编码了这些字段。要改就加版本号，比如--format v2。

5. 常见问题与排查技巧实录

5.1 解析报错：tree-sitter 找不到语言

最常见的报错是LanguageNotFoundError或者OSError: cannot open shared object file。原因通常是tree-sitter-languages没装好，或者你手动编译的.so路径不对。

排查步骤：

1. 先确认包装上了：pip show tree-sitter-languages
2. 确认能加载：from tree_sitter_languages import get_parser; get_parser('python')
3. 如果报错，试试重装：pip install --force-reinstall tree-sitter-languages

如果用的是自己编译的.so，注意路径要用绝对路径，相对路径在不同工作目录下会失效。

5.2 调用解析大量失败

如果你发现解析出来的调用有一大半是"未解析"，通常是这几个原因：

我的经验是：不要追求 100% 解析率。一个真实项目里，能有 70%-85% 的调用被正确解析，就已经能大幅提升 AI 的准确率了。剩下的标记为"未解析"，让 AI 知道这里存在不确定性，反而比瞎猜一个错误目标要好。

5.3 增量更新后图不一致

做增量更新时最容易出的问题是：改了一个文件，重新解析后新节点加进去了，但旧节点没删，导致图里同时存在新旧两套符号。

解决办法是按文件粒度做替换：

def update_file(conn, file_path, new_nodes, new_edges): with conn: # 先删掉这个文件相关的所有节点和边 conn.execute('DELETE FROM nodes WHERE file = ?', (file_path,)) conn.execute('''DELETE FROM edges WHERE from_id IN (SELECT id FROM nodes WHERE file = ?)''', (file_path,)) # 再插入新的 conn.executemany('INSERT INTO nodes VALUES (?, ?, ?, ?, ?, ?)', new_nodes) conn.executemany('INSERT INTO edges VALUES (?, ?, ?)', new_edges)

注意删除边的时候要同时删掉"以这个文件的符号为起点"和"以它为终点"的边。只删起点会留下悬空的入边，查询时会报错。

5.4 查询太慢

如果callers查询要好几秒，八成是索引没建好，或者查询写法有问题。检查两点：

1. edges表的to_id上有没有索引？反向查询（找调用者）靠的就是这个索引。
2. 查询有没有用LIKE或者函数包裹列？比如WHERE name LIKE '%foo%'用不上索引，WHERE name = 'foo'才能用。

如果数据量真的很大（百万级边），可以考虑把图加载到内存里做查询。启动时一次性读进字典，之后查询都是内存操作，速度提升几十倍。代价是启动慢一点、内存占用高一点，但对交互式查询来说完全值得。

5.5 和 AI 工具对接时的坑

把 codegraph 接到 Claude Code 或 Cursor 上时，我遇到过几个问题：

第一个是输出太长。AI 工具调用 CLI 拿到一大段 JSON，直接塞进上下文，token 瞬间爆掉。解决办法是在 CLI 层面做截断和摘要，默认只返回前 N 条，并附带总数。

第二个是路径问题。AI 工具的工作目录可能和你的项目根目录不一致，导致相对路径解析错误。统一用绝对路径，或者在 CLI 里加一个--root参数显式指定项目根。

第三个是并发调用。有些 agent 会并行发起多个查询，如果都用同一个 SQLite 连接会冲突。要么每个查询开独立连接，要么加锁串行化。SQLite 的读操作本身支持并发，但写操作要串行，所以查询场景下开多个只读连接是安全的。

5.6 一个实用的调试技巧

建图过程中如果结果不对，最有效的调试方法是把图可视化出来。不用搞复杂的图形界面，直接输出 DOT 格式，用 Graphviz 渲染：

def to_dot(conn, output_path, max_nodes=100): nodes = conn.execute('SELECT id, name, type FROM nodes LIMIT ?', (max_nodes,)).fetchall() edges = conn.execute('SELECT from_id, to_id, edge_type FROM edges').fetchall() with open(output_path, 'w') as f: f.write('digraph codegraph {\n') for nid, name, ntype in nodes: f.write(f' "{nid}" [label="{name}\\n({ntype})"];\n') for f, t, etype in edges: f.write(f' "{f}" -> "{t}" [label="{etype}"];\n') f.write('}\n')

然后dot -Tpng codegraph.dot -o codegraph.png，打开图片一看，哪里连错了、哪里断了，一目了然。这个技巧帮我定位过好几次解析 bug，比盯着日志强多了。

6. 几个值得深挖的扩展方向

6.1 加上类型信息，提升解析准确率

纯 AST 解析拿不到类型信息，所以obj.method()里的obj到底是什么类型，解析器不知道。如果你能接入语言服务器（比如 Python 的 pyright、TypeScript 的 tsserver），就能拿到类型推断结果，把方法调用的解析准确率从 70% 提到 90% 以上。

代价是语言服务器启动慢、内存占用高。我的建议是做成可选增强：默认用纯 AST 快速建图，需要高精度时再启动语言服务器做二次解析。

6.2 追踪数据流，而不只是调用流

现在的图只追踪"谁调用谁"，但很多 bug 出在数据流上——一个变量在哪里被赋值、在哪里被读取、在哪里被修改。加上数据流边之后，AI 就能回答"改这个字段会影响哪些计算"这类问题。

数据流分析比调用分析复杂得多，需要做到达定值分析或者SSA 转换。如果只是想要个粗略版本，可以追踪"变量赋值 → 变量读取"的边，不做精确的路径分析，准确率低一些但实现简单。

6.3 把图序列化成 AI 友好的格式

直接给 AI 喂 JSON 其实不是最优的，因为 JSON 的括号和引号很占 token。可以设计一种更紧凑的文本格式：

[fn] UserService.login @ src/auth/user.ts:42 <- calls: AuthController.handleLogin @ src/controller/auth.ts:15 <- calls: UserServiceTest.testLogin @ test/user.test.ts:88 -> calls: UserRepository.findByEmail @ src/repo/user.ts:23 -> calls: hashPassword @ src/util/crypto.ts:10

这种格式一眼就能看懂关系，token 消耗也比 JSON 少一半左右。AI 读起来也更顺，因为它更接近自然语言的描述方式。

6.4 多语言项目的统一图谱

真实项目经常是多种语言混用——前端 TypeScript、后端 Go、脚本 Python。如果每种语言建一张独立的图，跨语言的调用（比如前端调后端 API）就追踪不到。

一个可行的方案是在 API 边界上建桥：识别出后端的路由定义（比如@app.route('/api/user')）和前端的请求调用（比如fetch('/api/user')），在两者之间加一条api_call边。这样从后端改一个接口，能顺着边找到所有调用它的前端代码。

这个桥接需要针对具体框架写适配器，工作量不小，但对全栈项目来说价值很大。

6.5 把图谱作为团队共享资产

单个开发者建图，收益有限。如果整个团队共享一张图，收益会放大——新人入职可以快速理解项目结构，代码评审时能自动检查影响范围，重构时能评估风险。

实现上，可以把图存到共享的数据库，或者定期导出成文件放进版本控制。每次 CI 跑的时候更新图，保证它和代码同步。这样图就成了和代码一样的一等公民，而不是某个开发者本地的临时工具。

提示：共享图谱要注意权限和隐私。如果项目里有敏感代码，图谱里可能泄露函数名、文件路径等信息。导出前要做脱敏，或者只在内网共享。

7. 我在实际使用中的几点体会

搭完这套东西并用了几个月之后，有几个感受比较深。

第一，图谱的价值不在"全"，而在"准"。一开始我追求把所有关系都建进去，结果图又大又乱，查询慢、噪音多。后来砍掉了很多边类型，只保留calls、imports、contains三种，反而更好用。AI 需要的是关键路径上的准确信息，不是全量信息。

第二，和 AI 工具的配合需要调优。同样的图谱，prompt 写得好不好，效果差很多。我的经验是：先让 AI 查图，再让它读代码，最后才让它改代码。顺序反了，AI 容易先入为主，改出问题。

第三，增量更新比想象中难做对。我一开始觉得"删了重加"很简单，实际做的时候在缓存一致性上翻了好几次车。后来加了一个版本号机制：每次全量重建递增版本号，增量更新时检查版本号，不一致就触发全量重建。虽然粗暴，但稳定。

第四，别指望它解决所有问题。动态语言、反射、元编程这些场景，静态图谱天生无能为力。遇到这类代码，老老实实让 AI 读源码，别硬套图谱。工具是辅助，不是万能药。

最后分享一个小技巧：如果你只是想快速体验一下 codegraph 的效果，不用从零写。可以先用现成的工具（比如ctags生成符号索引，grep加脚本做简单的关系提取），跑通流程、验证价值之后，再决定要不要投入精力做完整版本。很多时候，一个粗糙但能用的原型，比一个完美但没上线的系统更有价值。