Autodoc

⚡ 使用大语言模型自动生成代码库文档的工具包 ⚡

这是什么？ • 开始使用 • 社区 • 贡献

这是什么？

Autodoc 是一个实验性工具包，用于利用大型语言模型（如 GPT-4 或 Alpaca）为 Git 仓库自动生成代码库文档。你可以在大约 5 分钟内将 Autodoc 安装 到你的仓库中。它会通过深度优先遍历整个仓库内容来索引你的代码库，并调用 LLM 为每个文件和文件夹生成文档。这些文档可以组合起来描述你系统的各个组件及其协作方式。

生成的文档会保留在你的代码库中，并随着代码一起传播。下载你代码的开发者可以使用 doc 命令来询问关于代码库的问题，并获得带有代码文件引用链接的高度精确答案。

在不久的将来，文档将会作为 CI 流水线的一部分被重新索引，从而始终保持最新状态。如果你有兴趣参与这项工作，请参阅 此议题。

状态

Autodoc 目前仍处于开发的早期阶段。虽然功能可用，但尚未准备好投入生产环境使用。可能会出现各种问题或不符合预期的情况。如果你有兴趣参与核心 Autodoc 框架的开发，请参阅 贡献指南。我们非常欢迎你的帮助！

常见问题解答

问： 我得到的回答质量不高，该如何提高回答质量？

答： Autodoc 目前仍处于开发的早期阶段。因此，回答质量会因你正在索引的项目类型以及问题的表述方式而有很大差异。以下是一些编写优质查询的建议：

1. 提问时要具体明确。例如，不要只问“解释一下认证”，而是问“这个系统中有哪些不同的认证组件？”这样可以帮助 Autodoc 选择合适的上下文，从而给出最佳答案。
2. 使用 GPT-4。相比 GPT-3.5，GPT-4 在理解代码方面有显著优势，这种能力同样体现在生成高质量文档上。如果你没有访问权限，可以在这里注册申请。

示例

以下是 Autodoc 的一些使用示例。

1. Autodoc - 该仓库包含由 Autodoc 自动生成的自身文档，存放在 .autodoc 文件夹中。请按照此处的说明学习如何查询该文档。
2. TolyGPT.com - TolyGPT 是一个基于 Solana 验证器 代码库训练的 Autodoc 聊天机器人，已部署到网页上以便于访问。在不久的将来，除了现有的命令行工具外，Autodoc 还将支持网页版。

开始使用

要求

Autodoc 需要 Node.js v18.0.0 或更高版本，推荐使用 v19.0.0 或更高版本。请确保运行的是正确版本：

$ node -v

示例输出：

v19.8.1

将 Autodoc 命令行工具以全局 NPM 模块的形式安装：

$ npm install -g @context-labs/autodoc

此命令会安装 Autodoc 命令行工具，使你可以创建和查询 Autodoc 索引。

运行 doc 查看可用命令。

查询

你可以通过命令行查询已安装 Autodoc 的仓库。我们将以 Autodoc 仓库本身为例，演示 Autodoc 的查询方式，但这也可以是你自己的包含索引的仓库。

克隆 Autodoc 并切换目录以开始：

$ git clone https://github.com/context-labs/autodoc.git
$ cd autodoc

目前，Autodoc 仅支持 OpenAI。请确保已在当前会话中导出你的 OpenAI API 密钥：

$ export OPENAI_API_KEY=<YOUR_KEY_HERE>

要启动 Autodoc 查询命令行界面，请运行：

$ doc q

如果你是第一次运行 doc q，屏幕上会出现提示，让你选择可访问的 GPT 模型。根据你的访问权限选择相应的选项。如果不确定，可以选择第一个选项：

现在你已经可以查询 Autodoc 仓库的文档了：

这是核心的查询体验，目前还非常基础，有很大的改进空间。如果你想改善 Autodoc 命令行查询体验，请查看 此议题。

索引

请按照以下步骤，使用 Autodoc 为您的仓库生成文档。

切换到项目的根目录：

cd $PROJECT_ROOT

确保当前会话中已设置 OpenAI API 密钥：

$ export OPENAI_API_KEY=<YOUR_KEY_HERE>

运行 init 命令：

doc init

系统会提示您输入项目名称、GitHub 仓库地址，并选择您有权使用的 GPT 模型。如果您不确定自己可以使用哪些模型，请选择第一个选项。您还可以指定自定义的 GPT 文件或目录提示，这些提示将用于总结和分析代码仓库。该命令会在项目的根目录下生成一个 autodoc.config.json 文件来存储这些值。请务必将此文件提交到 Git 仓库中。

注意： 请勿跳过输入这些值，否则索引可能无法正常工作。

提示配置： 提示的相关说明位于 prompts.ts 文件中，部分片段可以在 autodoc.config.json 中进行自定义。当前的提示主要面向开发者，并假设您的仓库以代码为主。未来我们将提供更多参考模板。

运行 index 命令：

doc index

您应该会看到如下界面：

此界面会估算索引您仓库的成本。您也可以通过 doc estimate 命令访问该界面。如果您已经进行过一次索引，那么第二次运行 doc index 时，只会重新索引那些发生更改的文件。

对于项目中的每个文件，Autodoc 都会根据文件内容计算其 token 数量。代码行数越多，token 数量越大。基于这一数量，Autodoc 会为每个文件选择合适的模型，始终选择上下文长度能够支持该文件 token 数量且价格最低的模型。如果您有兴趣帮助实现 Autodoc 中模型选择的可配置化，请查看 此议题。

注意： 这种简单的模型选择策略意味着，token 数量少于约 4000 的文件将使用 GPT-3.5 进行文档化，这会导致文档的准确性较低。我们建议至少使用 GPT-4 8K。 使用 GPT-4 进行索引可以获得显著更好的输出。您可以通过 此处 申请访问权限。

对于大型项目，成本可能会高达数百美元。OpenAI 的定价信息请参见 此处。

在不久的将来，我们将支持自托管模型，例如 Llama 和 Alpaca。如果您有兴趣参与相关开发，请阅读 此议题。

当您的仓库完成索引后，您应该会看到如下界面：

现在您可以按照 查询 中的步骤来查询您的应用了。

社区

目前有一小群人正全职致力于 Autodoc 的开发。欢迎加入我们的 Discord，或关注我们的 Twitter 获取最新动态。我们会定期发布更新，并持续改进 Autodoc 应用程序。想参与贡献吗？请继续阅读。

贡献

作为一项处于快速发展的领域的开源项目，我们非常欢迎各种形式的贡献，无论是新功能、基础设施优化，还是文档改进。

有关如何贡献的详细信息，请参阅 .github/CONTRIBUTING.md。

Autodoc 快速上手指南

Autodoc 是一个利用大语言模型（如 GPT-4）自动为 Git 代码库生成文档的实验性工具包。它能索引你的代码库，为每个文件和文件夹生成文档，并允许开发者通过命令行查询代码细节。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• Node.js: 版本需为 v18.0.0 或更高（推荐 v19.0.0 及以上）。
  • 验证命令：node -v
• OpenAI API Key: 目前 Autodoc 仅支持 OpenAI 模型。你需要拥有有效的 API Key，并建议在会话中导出该变量。
  • 注意：为了获得高质量的文档，强烈建议使用 GPT-4 (8K context) 模型。GPT-3.5 生成的文档准确性较低。

安装步骤

通过 npm 全局安装 Autodoc CLI 工具：

npm install -g @context-labs/autodoc

安装完成后，运行以下命令查看可用指令：

doc

基本使用

1. 初始化项目 (Indexing)

进入你的项目根目录，运行初始化命令以配置项目信息：

cd $PROJECT_ROOT
export OPENAI_API_KEY=<YOUR_KEY_HERE>
doc init

执行 doc init 后，按提示输入：

• 项目名称
• GitHub 仓库 URL
• 可用的 GPT 模型选项（若不确定，选择第一个选项）

该命令会在项目根目录生成 autodoc.config.json 配置文件，请将此文件提交到 Git 仓库。

接着，运行索引命令开始生成文档：

doc index

系统会先估算索引成本。确认后，Autodoc 将遍历代码库，根据文件大小自动选择模型（推荐使用 GPT-4）并生成文档。

• 提示：大型项目的索引成本可能较高，具体取决于代码量和所选模型。

2. 查询文档 (Querying)

索引完成后，你可以随时查询代码库文档。

在项目目录下运行：

doc q

如果是首次运行，系统会提示你选择已拥有的 GPT 模型。选择后即可进入交互模式，输入关于代码库的具体问题（例如：“这个系统中的授权组件有哪些？”），Autodoc 将结合生成的文档提供带有代码引用链接的详细回答。