用 Tree-sitter 构建 AI 文档引擎

文档是每位开发者最不喜欢的任务。

我们都同意它很重要。我们都打算保持更新。然而……它通常是第一个落后的。

在我见证了每个团队都出现这种情况后，我构建了 AutomaDocs —— 一个 AI 驱动的文档引擎，可以连接到你的 GitHub 仓库并自动保持文档同步。

以下是系统的工作原理以及我在构建过程中学到的东西。

1、真正的问题

每个工程团队都经历过这样的对话：

• PM：“文档更新了吗？”
• Dev：“呃……差不多吧。”
• PM：“上周 API 端点变了。”
• Dev：“……我明天更新。”

问题不在于懒惰。而在于架构。

我们将文档视为与代码分离的产物 —— 但代码在不断变化。手动保持两个并行系统同步是不可扩展的。

所以我问：

如果文档根本不需要手动编写会怎样？

如果它直接从结构化的代码理解中生成呢？

这就是 AutomaDocs 的由来。

2、架构

AutomaDocs 有三个核心层：

1. 结构化代码分析
2. LLM 驱动的文档生成
3. 持续同步 + 检索 (RAG)

让我们来分析一下。

2.1 使用 Tree-sitter 进行代码分析

大多数 AI 文档工具只是将原始源代码输入到 LLM 中。

这种方法可以……但它很嘈杂且不可靠。

相反，我使用 Tree-sitter 将代码库解析为抽象语法树 (AST)。这提供了结构化的、语言感知的代码库理解：

• 带有参数和返回类型的函数签名
• 类层次结构
• 导入/导出示意图
• 文档字符串提取
• 类型信息

AI 看到的不再是"文本"，而是结构化的架构。

示例输出：

{
  type: "function_declaration",
  name: "createUser",
  parameters: [
    { name: "email", type: "string" },
    { name: "role", type: "UserRole" }
  ],
  returnType: "Promise<User>",
  docstring: "创建新用户账户"
}

与原始代码提示相比，这种结构显著提高了文档质量。

关键洞察：

当你在提示前减少歧义时，LLM 的表现会显著提升。

2.2 使用 Claude 进行 AI 生成

一旦我们有了结构化的 AST 数据，我们就将其输入到 Claude 中，并配合精心设计的提示。

系统生成：

• API 端点文档
• 方法/函数描述
• 带类型的参数分解
• 使用示例
• 高层架构摘要

因为输入是结构化的，输出也更加：

• 更一致
• 更少幻觉
• 更容易确定性地重新生成

这种分离 —— 解析器用于理解，LLM 用于解释 —— 保持了职责的清晰。

2.3 使用 Webhooks + RAG 进行自动同步

文档永远不应该过时。

当你推送代码时会发生什么：

1. GitHub webhook 触发
2. 我们检测到变更的文件
3. Tree-sitter 仅重新解析受影响的节点
4. Claude 重新生成相关文档
5. 在 Pinecone 中更新嵌入

你的文档永远不会比代码落后一次推送。

无需手动更新。

3、RAG 聊天系统

我们还构建了一个基于文档的 AI 聊天界面。

我们没有使用基本的向量搜索，而是实现了混合检索：

• BM25 → 精确关键词匹配（函数名、错误码）
• Pinecone → 语义搜索（概念性问题）
• 倒数排名融合 (RRF) → 结合两种排名系统

这意味着用户可以问：

“认证是如何工作的？”

即使单词认证没有直接出现在代码中，系统仍然能找到相关的逻辑、中间件或配置。

混合搜索显著提高了回答质量。

4、技术栈

最大的架构决策是分离：

• 解析层
• 生成层
• 检索层

保持这些解耦使迭代速度大大加快。

5、我会怎样做的

5.1 从更少的语言开始

从第一天起就支持 15+ 种语言过于雄心勃勃。

如果我今天重新构建，我会专注于：

• JavaScript / TypeScript
• Python

先把这两个做好。以后再扩展。

5.2 更早地构建"文档健康评分"

我们后来添加了文档健康评分系统 —— 令人惊讶的是，它成为了最受欢迎的功能之一。

游戏化是有效的。

当团队能看到以下内容时，他们更有可能维护文档：

• 覆盖率 %
• 过时的端点
• 缺失的描述

如果我重新开始，这将是 v1 版本的一部分。

5.3 使用 WebSocket 而不是轮询

我们目前通过轮询来获取生成状态更新。

WebSocket 会使系统更干净、更实时。

经典的 v1 权衡：先上线，以后再优化。

6、构建 AI 开发工具的经验教训

一些高层次的收获：

• 结构化输入 > 巧妙的提示
• 检索质量比模型大小更重要
• 开发工具成功是因为它们减少了摩擦，而不是增加了 AI 新奇性
• 自动化只有在不可见的情况下才能发挥作用

AI 很强大 —— 但只有在良好的架构包裹下才能发挥作用。

原文链接: How I Built an AI Documentation Engine with Tree-sitter, Claude AI, and RAG

汇智网翻译整理，转载请标明出处