本文介绍了一款专为解决大模型在处理大型代码仓库时面临的上下文理解难题而设计的工具 Codeindex。针对代码量大、分支多及依赖关系复杂等痛点，Codeindex 提供了代码语义化索引、检索以及函数依赖图生成能力。其核心技术亮点包括：利用增量索引与摘要生成技术提升大模型对代码意图的理解，采用分层架构与图数据库（KuzuDB/Postgres）精准构建函数上下游依赖关系。该工具通过 OpenAPI 和 SDK 两种形式，支持 CodeWiz 代码检索、AICR 智能代码审查及 CodeWiki 自动生成文档等应用场景，旨在帮助开发者更高效地构建基于代码的 AI 应用。
前⾔
在⽇常 开 发⼯作 中 你 有 没 有 这 样 的 想 法：
想⾃⼰实 现⼀个 Agent 助⼿来 回 答 关 于 代 码 的⼀些 问 题，但 是 代 码 仓 库 过⼤，都 塞 给⼤模 型 也 不 太 现 实…
想 对 仓 库 代 码 做 分 析，但 还 要 考 虑 不 同 仓 库 不 同 分⽀的⽂件 变 化…
想识别函数的 上下 游 依 赖，使⼤模型更 准确 地 理解代码，还 要单独实现函数依 赖 的 上下 游 能⼒…
现 在，你 可 以 使⽤Codeindex 来 帮 助 你 解 决 这 些 问 题：
增 量 语 义 化 索 引&检 索 你 的 代 码 仓 库，召 回 相 关 的 代 码⽚段
增 量⽣成 代 码⽚段&⽂件 级 别 的 代 码 摘 要
根 据 函 数 声 明&调⽤⽣成 函 数 依 赖 关 系 图，可 获 取 函 数 依 赖 的 上 下 游 函 数
下⾯就 来 介 绍 下 Codeindex⽀持 的 能⼒以 及 可 以 实 现 的 场 景。
介绍
Codeindex 是⼀个 代码语义化 索引、检索 和函数依 赖图⽣成⼯具，并⽀持增 量 索引。借助 codeindex，你可以对你的⼤型 代码仓 库进⾏索引，通过 语义化描 述检索 代码仓 库 中的相关代码⽚段，此 外你 还 可以 获 取 这段 代码或 者 其对 应⽂件的语义化摘要，从⽽帮 助⼤模型更 好 地 理解代码意 图。
整体架构
Codeindex 提 供 SDK 与 OpenAPI 两 种 服 务，OpenAPI 依 赖 Node.js SDK 实 现，⼆者 均 提 供 如 下 能⼒：
建⽴索引：根 据仓 库 及分⽀对代码 建⽴语义化 索引，并 存储⽂件哈 希值 信 息，⼆次索引 可 复⽤，实现增 量 索引。
查 询 索 引 进 度：因 索 引 过 程 中 涉 及⽂本 模 型 及 向 量 模 型 的 调⽤，⼤型 项⽬的 索 引 时 间 较⻓，可 通 过 该 能⼒实 时 查 询 索 引 进 度。
语义化 检索：索引 完成之后可 通过⼀段 语义化描 述检索 代码仓 库 中相关的代码⽚段 及其语 义化摘要。
查 询⽂件 摘 要：可 查 询 单 个⽂件 的 语 义 化 摘 要，可⽤于 Codewiki 等 应⽤。
查 询 函 数 声 明：可 查 询⽂件 中 声 明 的 函 数⽚段。
查 询 函 数 Deps：查 询 某 个 函 数 的 上 下 游 函 数 依 赖，可⽤于 AI CR 等 场 景，辅 助⼤模 型 判 断 代 码 变 更 是 否 合 理。
部分细节解析
▐语 义 化 摘 要 语 义 化 摘 要 依 赖 代 码 Chunk 拆 分 的 结 果，在 分 块 过 程 中 会 使⽤如 下 策 略：
codeChunker：codeChunker 利⽤Tree-sitter 解 析 器⽣成 AST，并 基 于 语 法 结 构 进⾏分块：
若 Class 内 代 码 超 出 chunk token 上 限，会 对 内 部 的 函 数 体 省 略，保 持 Class 的 整 体 代 码 结 构 完 整
对 Class 内部的函 数 成 员⼆次 处 理，单 独 进⾏Chunk 拆 分。
basicChunker：basicChunker 是⼀个 简 单 的 基 于⾏的 分 块 器，适⽤于 纯⽂本和 Markdown⽂件，会 按 照 Chunk token 上 限 进⾏拆 分。Chunk 拆 分 完 成 之 后 会⽣成 语 义 化 代 码 摘 要，代 码⽚段 会 按 照 如 下 结 构 发 送 给⼤模 型，最 外 层 为 docum ent 标 签，表 示 单 个⽂件，path 属 性 为⽂件 路 径；内 部 的 code 标 签 为 当 前⽂件内 拆 分 的 代 码⽚段，startline 与 endline 分 别 表 示 代 码⽚段 的 开 始⾏号 和 结 束⾏号。<document path="lib/utils.js"> <code startline="0" endline="2"> function formatDate(date) { return date.toISOString().split('T')[0]; } </code> <code startline="3" endline="5"> function validateEmail(email) { return /^[^s@]+@[^s@]+.[^s@]+$/.test(email); } </code></document>我 们 会 将 上 述 信 息 发 送 给⼤模 型 让 其 做 摘 要，返 回 结 果 为 如 下 结 构 的 JSON 对 象[ { "summary": "文件维度的代码摘要", "path": "文件路径", "chunks": [ { "startline": "开始行号", "endline": "结束行号", "summary": "代码片段级别的代码摘要" } ] }]
▐函 数 依 赖 图 代 码 依 赖 图 可 以⽤在 AI CR 等 场 景 中，它 可 以 查 询 函 数 依 赖 的 上 下 游，从⽽为⼤模 型 提 供 更 完 备 的 上 下⽂信 息。由 于 涉 及 到 多 种 编 程 语⾔以 及 数 据 库 语 法 差 异，函 数 依 赖 图 部 分 整 体 采⽤分 层 架 构 设 计：
Parser 适 配 层，所 有 语⾔的 依 赖 图 解 析 均 通 过 拓 展 该 层 的⽅式 实 现，对 外 暴 露 API⼀致，内 部 采⽤tree-sitter 对 代 码 进⾏解 析，分 析 其 内 部 的 函 数 依 赖。
GraphDB 适 配 层，由 于 涉 及 到 SDK 与 openapi，故 需 要 考 虑 本 地 与 线 上 两 种 存 储 介 质，所 以 对 KuzuDB 与 Postgres 数 据 库 对 外 暴 露 接⼝标 准 化，⽆缝 切 换 存 储 介 质。
函 数 依 赖 图⽣成 时 序 图
总结一下上面的时序图，SDK 内部会查询文件内部声明了哪些函数、函数内部有没有嵌套声明函数、函数内部调用了哪些函数、被调用的函数是来自内部声明还是外部引用。获取到这些信息之后可以合并为图数据结构存储在图数据库中。
图 数 据 存 储⽅⾯，嵌⼊式 图 数 据 库 采⽤KuzuDB，线 上 使⽤Postgres Age 插 件，⼆者 均 设计 了 如 下 表 结 构⽤于 存 储 图 数 据 结 构：
Files:节 点 表，存 储 代 码 库 中 每 个⽂件 的 基 本 信 息。
Functions:节 点 表，存 储 代 码 中 定 义 的 函 数 信 息。
Contains:关 系 表，表 示⽂件 与 函 数 之 间 的 包 含 关 系(Files->Functions)。
FunctionCalls:关 系 表，记 录 函 数 之 间 的 调⽤关 系(Functions->Functions)。
FileCalls:关 系 表，记 录⽂件 直 接 调⽤函 数 的 关 系(Files->Functions)。
Imports:关 系 表，表 示⽂件 之 间 的 导⼊/导 出 关 系(Files -> Files)。
Exports:关 系 表，表 示⽂件 导 出 函 数 的 关 系(Files->Functions)。
FunctionContains:关 系 表，表 示 函 数 内 部 定 义 了 其 他 函 数 的 关 系（嵌 套 函 数），(Functions -> Functions)。
借 助 上 述 的 图 数 据 表 可 以 查 询 函 数 的 多 级 依 赖。可 以⽣成 类 似 下⾯的 关 系 图
应⽤
CodeWiz 集 成 CodeWiz 基 于 codeindex 的 索 引/检 索 能⼒实 现 了 代 码 库 索 引 功 能，并 为⼤模 型 提 供 检 索⼯具，可 在 Chat 过 程 中 获 取 上 下⽂，从⽽更 好 地 为⽤户 解 决 问 题。AI CR Agent AI CR 是 聚 焦 中 后 台 场 景、具 有 智 能 上 下⽂分 析 能⼒的 Agent 应⽤，其 内 部 依 赖 了 Codeindex 来 获 取 函 数 依 赖 的 上 下 游 信 息，以 帮 助⼤模 型 更 好 地 判 断 当 前 变 更 是 否 对 已 有 功 能 产⽣影 响。CodeWiki CodeWiki 可 根 据 仓 库 中 的 代 码 基 于 Qwen⼤模 型⽣成 wiki⽂档。Codeindex 索 引 过 程 中 会⽣成 代 码⽚段 以 及 全⽂语 义 化 摘 要，将⽂件 路 径 及 其 摘 要 发 送 给⼤模 型 可 以 帮 助⼤模 型 更 准 确 地 输 出 Wiki 结 构，Codewiki 前 置 会 先⽣成 对 应 仓 库 的 Codeindex 索 引，后 续 会 基 于 其 拆 分 的 代 码⽚段 以 及 语 义 化 摘 要⽣成⽂档。
总结
总 结⼀下，Codeindex 是⼀个 代 码 语 义 化 索 引&检 索⼯具，并 且 可 以⽣成 代 码⽚段/⽂件 级 别 的 语 义 化 摘 要 和 函 数 依 赖 图，你 可 以 使⽤这 些 能⼒来 构 建 你 的 AI 应⽤。⽬前 Codeindex 同 时 提 供 了 OpenAPI 和 SDK 两 种⽅式，OpenAPI 中 已 经 配 置 好 了 SDK，只 需 要 传⼊你 的 仓 库 信 息 就 可 以 为 你 的 仓 库⽣成 索 引。
