深度解析 TeamAI graph-boost 重排序：代码图谱如何增强知识召回结果

深度解析 TeamAI graph-boost 重排序：代码图谱如何增强知识召回结果

【免费下载链接】teamai-cliMake Every Team AI Native项目地址: https://gitcode.com/GitHub_Trending/te/teamai-cli

TeamAI 是一个让团队 AI 原生的命令行工具，它的核心能力之一是用BM25 关键词检索 + graph-boost 图谱重排序的混合策略搜索团队知识库。本文将带你搞懂 graph-boost 是如何利用代码图谱，把"结构上相关"的文档顶到召回结果前列的。

为什么光靠关键词搜索不够？

传统的文本检索（比如 BM25）只关心"词是否出现"：查询词在某个文档里出现越多、越稀有，分数就越高。但在真实的代码知识库里，这有个明显短板：

• 一篇真正相关的模块文档，正文里可能压根没提你的查询词，只通过依赖关系和你相关；
• 一篇标题命中的文档，可能只是恰好撞词，与你的任务没有结构上的联系。

TeamAI 的解法是：在 BM25 分数之上，叠加一层由代码图谱（graph）计算的加分项，也就是 graph-boost。核心实现位于 src/code-knowledge-recall.ts，文件开头的注释直接点明了算法设计：

Graph-aware codebase knowledge recall (BM25 + graph-boost)

graph-boost 的三层加分机制

整个重排序逻辑集中在computeGraphBoost函数中（src/code-knowledge-recall.ts），它按"离入口节点越近、加分越大"的原则分三档：

1. 入口节点：直接命中，加 8 分

先用查询词去匹配图谱中的节点（slug + title），命中的节点称为入口节点。如果某个 wiki 页面本身就对应一个入口节点，直接获得ENTRY_NODE_BOOST = 8的固定加分——这是全算法中最高的单项加分。

2. 一跳邻居：按关系类型加权

如果页面没直接命中，就检查它是否是入口节点的直接邻居（1-hop）。邻居加分不是固定值，而是按边的关系类型加权：

也就是说，"你的入口依赖的模块"比"仅被提及的模块"排名更靠前——这符合工程直觉：改 A 之前，A 依赖的 B 比 A 的邻居 C 更值得关注。

3. 二跳邻居：权重减半再衰减

对 1-hop 的邻居再向外扩一层（2-hop），加分公式为权重 × 0.4，恰好是一跳的一半。既保留了"外围弱相关"页面的曝光机会，又避免远距离的噪声页面抢占前排。

入口节点命中 +8.0 └─ 1-hop 邻居 +权重×0.8 （DEPENDS_ON 最高 2.4） └─ 2-hop 邻居 +权重×0.4 （再减半）

图谱数据从哪里来？

graph-boost 的"原料"是位于teamwiki/.indices/graph-index.json的图谱索引，其结构由 src/wiki-engine/core/graph-index.schema.ts 定义（schema 版本team-wiki.graph-index.v1）。

• 节点（nodes）：模块、组件、接口、文档页，带有类型和置信度（EXTRACTED / INFERRED 等）；
• 边（edges）：from → to + relation，支持DEPENDS_ON、REFERENCES、IMPLEMENTS、MAPS_TO等关系类型。

这份图谱由teamai codebase --extract从源码仓库提取生成，边来自双轨流水线：AST 解析（TS/JS/Python/Go，基于 tree-sitter）产出高精度边，正则启发式兜底覆盖其他语言（详见 README.md 的 Codebase Knowledge Graph 章节）。

一个细节：图谱加载失败时（比如本地还没跑过 extract），算法优雅降级为纯 BM25 排序，不会报错——重排序是增强项，不是前置依赖。

召回深度：graph-boost 在不同模式下如何工作

teamai recall支持三种深度（实现在 src/code-knowledge-recall.ts 的queryCodeKnowledge中）：

• route：只返回路由表，用于发现项目，不参与图谱排序；
• context（默认）：搜索 overview / modules / docs，graph-boost 全程生效；
• lookup：全量搜索，额外利用图谱的前向依赖边，为每条结果附加relatedFiles（最多 15 个直接依赖文件），方便 AI Agent 直接定位"改这里还该看哪些文件"。

最终得分就是BM25 分数 + graph-boost 加分，排序后按 token 预算（context 5000、lookup 20000）截断输出。配套的行为测试在 src/__tests__/recall-progressive.test.ts 中，其中"graph-boost 在 context 模式生效"这一用例专门构造了含recall → src-module边的最小图谱来验证加分逻辑。

实际用起来是什么体验？

对普通用户来说，graph-boost 是零配置的：只要跑过teamai import或teamai codebase --extract生成了图谱，之后的每次检索都会自动受益。

# 本地仓库提取知识图谱（生成 teamwiki/ 下的 graph-index.json） teamai codebase --extract /path/to/repo # 检索时自动启用 BM25 + graph-boost teamai recall "重试 超时 配置"

在 Agent 工作流中，召回结果的Sources:行会列出相关源文件路径——这背后正是图谱的 source 锚点 + 前向依赖扩展在起作用，让 AI 拿到结果后能直接开始改代码，而不是重新翻仓库。完整的 Agent 侧召回流程见 agents/teamai-recall.md。

关键文件速查

小结

graph-boost 的精髓可以用一句话概括：用"结构距离"弥补"词面距离"的盲区。入口节点 +8 分、一跳按关系类型加权、二跳权重减半——这套简单而克制的衰减设计，让teamai recall不再只是"搜得到关键词"，而是"搜得到相关的模块和文件"。想本地体验完整流程，可以克隆仓库后按 README.md 快速开始：

git clone https://gitcode.com/GitHub_Trending/te/teamai-cli

【免费下载链接】teamai-cliMake Every Team AI Native项目地址: https://gitcode.com/GitHub_Trending/te/teamai-cli