AI Infrastructure · 项目汇报

Code
Graph
Builder

面向 Agent 的代码仓库知识基础设施
让 AI 不再猜测,有据可查

Knowledge Graph AST Parsing Vector Search MCP Protocol
12
支持编程语言
19
MCP 工具接口
4
核心流水线阶段
15K
Python 代码行
Problem

Agent 在大型
代码库中的
三大困境

以上三大困境共同导致一个结果:Agent 大量依赖猜测,产生幻觉——凭空推测不存在的函数、错误的调用路径、或者根本不存在的模块。

01
结构盲区
不知道函数在哪、谁调用谁,只能逐文件盲读,无法建立全局视图
根因 → 缺乏跨文件结构化索引
02
语义缺失
无法理解模块意图和设计边界,只看到代码文本,看不懂"为什么"
根因 → 代码本身不携带语义摘要
03
上下文爆炸
注入大量原始代码导致 context 溢出,越读越乱,关键信息被淹没
根因 → 无信息压缩和精准检索机制
Solution

四步流水线
将代码仓库转化为 Agent 可消费的知识

Step 01
AST 解析
知识图谱构建
Tree-sitter 提取全部符号、调用链、继承关系、模块层级
→ Kuzu 图数据库
Step 02
API 文档
生成
图谱数据转换为三层 Markdown 文档,LLM 补全函数描述
→ L1 / L2 / L3 .md
Step 03
向量嵌入
索引构建
以 L3 函数文档为单位,Qwen3 Embedding 生成语义向量
→ 1536 维向量索引
Step 04
Wiki 生成
语义聚类
语义聚类 + LLM 生成多页 Wiki,覆盖模块概述与使用示例
→ 多页 Markdown Wiki
MCP 标准接口 Claude Code · Cursor · 任意 MCP 客户端
Step 01

知识图谱
构建

基于 Tree-sitter 对所有源文件进行 AST 解析,支持 12 种主流语言,统一提取四类信息并写入 Kuzu 嵌入式图数据库。

C / C++ Python TypeScript Rust Go Java +6 more

中等规模仓库(~3000 个函数)可产生超过 5000 条调用边,覆盖全部跨文件调用关系。

01
定义提取
函数、类、方法、接口、枚举
含签名、可见性、行号
02
调用关系
Trie 树索引跨文件调用解析
foo()project.module.foo
03
导入关系
跨模块依赖链追踪,支持别名、相对导入
04
结构层级
Project → Package → Folder → File → Module 五层体系
Step 02 · 03 · 04

从图谱到 Agent 可读知识

Step 02 · API 文档
三层 Markdown 文档
L1 全项目模块索引
L2 每模块函数列表
L3 每函数完整文档(调用树 + 参数 + 源码),是向量嵌入的基本单元
LLM 补全无注释函数描述(批量 10 条/次)
Step 03 · 向量嵌入
语义检索索引
以 L3 文档为单位,Qwen3 Embedding 生成 1536 维向量。查询端启用任务指令,文档端不加,不对称嵌入弥合自然语言与代码的语义距离
支持自然语言精准检索
Step 04 · Wiki 生成
语义聚类 Wiki
向量相似度聚类 → LLM 为每个功能簇生成一页 Wiki,涵盖模块概述、核心函数、调用关系可视化、使用示例
人类可读 + Agent 可直接引用

每一步都有独立缓存层,支持按需重建,无需重跑全量流程。

Key Innovation

API 文档采用
Markdown
而非 JSON

传统代码分析工具普遍以 JSON 格式输出结构化数据。CGB 选择 Markdown 作为主要知识表示格式,直接影响 Agent 的理解质量。

格式策略
Markdown 知识存储 · Agent 上下文注入
JSON 工具调用 · 程序间通信
JSON — 传统方式
{"name":"authenticate", "params":[{"name":"user","type":"str"}, {"name":"pass","type":"str"}], "return":"Token", "calls":["db.query_user"]}
结构符号消耗大量 token
深层嵌套时 LLM 易混淆层级
长数组中间段内容被跳读
Markdown — CGB 方式
- authenticate(user, pass) → Token - 调用: db.query_user → cache.get_session ## Call Tree authenticate └─ db.query_user
同等信息量,token 密度更高
LLM 母语,标题层级天然分块
生成时几乎不出格式错误
Effect

三个维度
系统性压缩
幻觉空间

CGB 不是在事后修复幻觉,而是从信息供给端根除幻觉产生的条件。

01
精确定位取代猜测
locate_function / find_api 直接返回确切文件路径和行号,不再需要推测"这个函数应该在哪里"
02
调用图取代推断
Call Tree 与 Called by 将函数上下游关系明确呈现,不需要阅读大量源码来推断调用链
03
语义检索取代全文扫描
向量语义搜索允许 Agent 用自然语言精准找到目标,而非逐文件暴力匹配
Interface

19 个 MCP 工具
覆盖全部场景

通过 MCP(Model Context Protocol)标准协议暴露,任何支持 MCP 的 AI 客户端均可直接接入,无需额外适配。

长时间任务(建图、嵌入)支持实时进度回调,在客户端侧显示进度条。

Claude Code Cursor 任意 MCP 客户端
仓库管理
initialize_repository一键执行完整四步流水线
switch_repository切换已索引仓库
代码搜索
find_api主入口:语义搜索 + API 文档融合
query_code_graph自然语言 → Cypher 图查询
locate_function精确定位函数行号
semantic_search纯向量相似度检索
文档 & Wiki
get_api_doc读取 L3 函数完整文档
get_wiki_page读取指定 Wiki 页面
prepare_guidance依设计文档生成代码建议
01
Technical Deep Dive · 01

多语言 AST 解析
的统一化

语言差异通过配置而非分支处理
每种语言的函数节点类型、调用表达式类型等抽象为 LanguageSpec 配置项。同一套处理管道在所有语言上运行,差异只存在于"查询什么",而非"怎么查询"。新语言接入只需添加配置,无需修改核心逻辑。
完全限定名(FQN)是知识图谱的主键
所有符号被赋予全局唯一 FQN:project.module.Class.method。需处理包文件识别、嵌套类路径追溯、C 头文件跨文件关联等边界情况。
C 语言的特殊挑战:可见性推理
C 没有 public/private,可见性通过三个信号推断:是否带 static、是否在头文件中声明、是否被其他文件导入。头文件必须优先于实现文件处理,这是强制的处理顺序。
双重限制的 AST LRU 缓存
PASS 2(定义提取)后,AST 树缓存供 PASS 3(调用提取)复用。采用条目数 + 内存上限双重约束,防止大型仓库 OOM,同时避免重复解析开销。
02
Technical Deep Dive · 02

函数调用解析
四级消歧策略

源码中 parse_btype(ctx) 需解析为 tinycc.tccgen.parse_btype,才能在图中建立精确的调用边。

核心思想:在保证可靠性的条件下最大化覆盖率。宁可边不建立,也不引入错误的边。注册表采用 Trie 树 + 哈希表双索引,支持 O(1) 精确查找与高效前缀/后缀匹配。

Level 01 · 准确率 ~100%
自调用解析
self.method() / this.method(),直接在当前类上下文查找
Level 02 · 高准确率
限定调用解析
module.func(),查 import 映射表替换首部,验证注册表是否存在
Level 03 · 高准确率
导入表直查
函数名本身在 import 映射中,直接返回全限定名
Level 04 · 最后手段
注册表后缀匹配
全库后缀搜索,唯一匹配时准确,存在同名函数时可能产生歧义
03
Technical Deep Dive · 03

向量检索
不对称嵌入策略

代码检索存在固有的语义不对称:查询是自然语言,文档是代码。直接用同一模型处理两者,效果通常不理想。

Qwen3 Embedding 支持任务特定指令机制:查询端附加"为代码检索任务编码此查询",文档端不加指令。这种不对称嵌入有助于弥合语义距离。

L3 文档结构顺序的设计意图
描述行(意图摘要)位于最前,是向量化时权重最高的部分。调用树、参数表、源码依次排列,为相似度计算提供上下文,也为 Agent 重读时提供完整细节。
两种向量存储模式
Memory 纯 Python cosine 相似度,适合中小型仓库,无外部依赖,启动即用
Qdrant 专业向量数据库,支持持久化和大规模检索,适合超大型仓库
NL → Cypher 图查询
将完整图 Schema 编码进系统提示,LLM 以温度 0 生成 Cypher,强制 LIMIT 50 防止全图扫描。
04
Technical Deep Dive · 04

为何选择
Kuzu 图数据库

  • 嵌入式:直接以库的形式嵌入 Python 进程,无需 Docker,类似 SQLite 的定位
  • Cypher 兼容:标准 Cypher 查询语言,与 Neo4j 生态兼容,不锁定用户
  • 批量写入优化:高效批量节点/关系插入,适合一次性建图场景
关系多态性:运行时动态建表
Kuzu 的 REL TABLE 要求明确指定源/目标节点类型,无法直接表达"任意→任意"。系统的处理方式是首次遇到新 label 对(如 Method→Function)时自动创建对应关系表,并在覆盖映射中记录,查询时自动扩展到所有相关物理表。
Cypher 值的安全序列化
Python 值到 Cypher 字面量的映射层防止 Cypher 注入(类似 SQL 注入),处理 None → NULL、bool 大小写、字符串转义、列表递归序列化等差异。
分层缓存的重建代价
图数据库重建
5–15 分钟
向量索引重建
1–5 分钟
API 文档重建
~10 秒
Wiki 重建
~30 秒
Design Philosophy

贯穿始终的
四大设计原则

优雅降级,而非崩溃
文件解析失败、LLM 调用失败、调用无法解析——系统都选择记录日志并继续。一个有少量缺失边的图谱,远比一个因单个文件失败而无法构建的系统更有价值。
实用主义的精度权衡
类型推理不追求完整静态分析,内存估算不追求精确计量。在每个维度,系统选择"覆盖 80% 的常见情况",而非"完美处理 100% 的情况"。
参数化多样性,而非条件分支
多语言通过 LanguageSpec 参数化,多向量存储通过接口抽象。扩展新语言、新存储后端的成本极低,不需要修改核心逻辑。
分层缓存保护昂贵操作
四步流水线的每一步都有独立缓存层。AST 解析、LLM 调用、向量化 API 只在必要时执行,开发迭代和增量更新场景下响应速度合理。
Use Cases

适用场景

嵌入式 / 系统编程
大型 C/C++ 嵌入式系统
无成熟 LSP 支持,代码关系复杂,调用图和精确定位受益最大。CGB 是这类项目中 AI 辅助开发的稀缺基础设施。
多语言 / 跨仓库
多语言混合仓库
统一知识图谱屏蔽语言差异,Agent 跨 Python + TypeScript + Go 等混合代码库理解无障碍。
团队效能
新人 Onboarding 加速
Wiki 和语义搜索提供快速代码导航,新成员理解陌生大型仓库的时间从数周缩短至数天。
AI 辅助开发
AI 辅助代码重构
完整调用图让 Agent 评估改动影响范围时不再依赖人工提示,大幅提升重构任务的可靠性。
Project Status

项目现状

12
支持编程语言
C/C++ · Python · TS · Rust · Go…
19
MCP 工具接口
覆盖搜索 · 文档 · Wiki · 管理
15K
Python 代码行
含 15+ 测试模块
4
流水线阶段
全自动 · 分层缓存
图数据库
Kuzu(嵌入式,无需 Docker)
向量模型
Qwen3 Embedding · 1536 维
协议标准
MCP(Model Context Protocol)
AST 引擎
Tree-sitter · 统一多语言解析
Summary
CGB 不是一个"让 Agent 读更多代码"的工具,
而是一套让 Agent 不再需要猜测的基础设施。

通过将代码仓库的全部显性结构与隐性语义预先提取、索引,并以 LLM 最友好的 Markdown 格式呈现,从根源上系统性地压缩 Agent 的幻觉风险。

Knowledge Graph Markdown First MCP Protocol Anti-Hallucination
Code Graph Builder · 2026