RepoDoc:用知识图谱重构代码文档生成与增量更新-夜雨聆风

RepoDoc:用知识图谱重构代码文档生成与增量更新

📌 一句话总结：

本文提出 RepoDoc，用 repository knowledge graph 作为代码文档全生命周期语义骨架，在 24 个仓库、8 种语言上实现更高完整性、更低成本和更精准增量更新。

🔍 背景问题：

现有 LLM 代码文档工具仍把代码当作扁平文本或物理文件结构处理：

1️⃣ 文档组织缺少语义模块化，生成结果往往是孤立 API 页面，难以体现跨文件、跨模块依赖；

2️⃣ 大量代码片段被直接塞进 LLM 上下文，导致 token 膨胀、生成缓慢、API 成本高；

3️⃣ 代码变更后缺少语义级影响分析，要么全量重生成，要么只能检测文件级变化，难以维护文档一致性。

💡 方法简介：

RepoDoc 首先构建 RepoKG，将函数、类、接口、模块等抽象为 Code Entity，同时引入 Concept Entity 和 Doc Entity，并建模 calls、imports、contains、implements、semantic-impact、describes 等关系；

随后基于 RepoKG 进行语义模块聚类，不再按文件路径或固定 token 切分，而是根据调用、导入和功能相关性构建层次化模块结构；

文档生成采用 skill-based agent 架构，由 orchestrator 调度 DocWriterSkill、CodeAnalysisSkill 和 GraphStoreSkill，通过图查询精确检索相关代码上下文，生成 README、模块文档、API 文档和 Mermaid 架构图；

面对代码演化，RepoDoc 通过 Semantic Impact Propagation 在 RepoKG 中双向遍历依赖与被依赖组件，并结合拓扑排序，只选择性重生成受影响文档。

📊 实验结果：

在 RepoDocBench 的 24 个真实开源仓库、8 种编程语言上，RepoDoc 平均 API Coverage 达到 53.13%，相比 CodeWiki 的 40.09% 提升 32.5%；

在 Completeness@10 上，RepoDoc 达到 74.12%，高于 CodeWiki 的 67.16%，并在 Python 仓库上以 78.92% 超过 RepoAgent 的 76.53%；

在文档质量 TQS 评估中，RepoDoc 在 Clarity（8.25 vs 7.00）、Conciseness（7.40 vs 6.10）、Structure（8.05 vs 7.20）上全面优于 CodeWiki，说明其语义组织能减少冗余并提升可读性；

在效率上，RepoDoc 平均生成时间为 1,242 秒、消耗 780K tokens，而 CodeWiki 需要 3,673 秒和 5,311K tokens，RepoAgent 更高达 18,629 秒；增量更新阶段，RepoDoc 将更新时间降低 73%、token 使用降低 77%，并取得 97.0% Update Recall。

📂 项目主页：

https://github.com/SYSUSELab/RepoDoc

📄 论文原文：

https://arxiv.org/abs/2604.26523

✨ 一句话点评：

RepoDoc 用”代码图谱—文档维护”的关系揭示了自动文档生成的本质：真正能长期维护大型代码库文档的不是更长上下文，而是可遍历、可更新、可传播的语义结构——这意味着未来软件工程 Agent 应当从”文本拼接式 RAG”走向”知识图谱驱动的生命周期管理”。