> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# 用 Tree-sitter 构建 AI 文档引擎
- URL: https://www.hubwiz.com/blog/build-an-ai-document-engine-with-tree-sitter/
- Published: 2026-07-21T14:50:46.000Z
- Updated: 2026-10-13T15:09:57.000Z
- Description: 在我见证了每个团队都出现这种情况后，我构建了 AutomaDocs —— 一个 AI 驱动的文档引擎，可以连接到你的 GitHub 仓库并自动保持文档同步。
- Author: admin
- Tags: LIBRARY, TREE-SITTER, #Import 2026-10-14 14:41

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

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

在我见证了每个团队都出现这种情况后，我构建了 **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 看到的不再是"文本"，而是结构化的架构。

示例输出：

```json
{
  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、技术栈

| 组件    | 技术                      |
| ----- | ----------------------- |
| 前端    | Next.js 16 (App Router) |
| 后端    | Express (ES Modules)    |
| 数据库   | PostgreSQL              |
| 向量数据库 | Pinecone                |
| AI    | Claude (Anthropic)      |
| 解析器   | Tree-sitter             |
| 队列    | BullMQ + Redis          |
| 托管    | Vercel + Railway        |

最大的架构决策是分离：

- **解析层**
- **生成层**
- **检索层**

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

## 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](https://dev.to/liztacular/how-i-built-an-ai-documentation-engine-with-tree-sitter-claude-ai-and-rag-4jgk?ref=hubwiz.com)

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

> **这是「RAG / 数据 / 文档智能」专题的一部分。**完整地图见：[RAG / 数据 / 文档智能完全指南](https://www.hubwiz.com/blog/rag-data-stack/)