AI编程：如何提供库文档

如果你正在使用AI编码助手或代理，它们的有用程度将取决于它们对您使用的库的了解程度。大型语言模型（LLMs）从训练集中了解很多关于世界的信息，但这可能并不包括某个库的文档，或者只包括较旧的版本。代理可以浏览互联网寻找更近期的信息，但这可能不够精确。例如，网络上可能充斥着过时的示例，而最新的信息可能仅在官方文档中提供。

因此，如果你是库的作者，你如何为编码代理准备文档？如果你是库的用户，你如何提取你最喜欢的库的文档，以便它们能高效地作为你提示的一部分？

我在 X、BlueSky 和 LinkedIn 上提出了这个问题，并得到了一致的结果；以下是总结。这是一个不断发展的领域，目前还没有单一的答案或标准，但有一些选项可供探索。

1、尝试一下

作为一名库的作者，我当然尝试了上述的方法。到目前为止，我的尝试局限于 Ox 这个 Scala 并发和弹性库，但如果它证明是有用的，我会将相同的设置扩展到我们维护的其他库（包括 Jox、Tapir 和 sttp-client）。

我将专注于在使用 Cursor IDE 时可用的功能。其他编辑器可能有类似的功能。

2、Cursor 文档索引

如果你使用的是 Cursor，最快且最直接的选项可能是尝试内置的文档索引功能。在编辑器中选择 @Docs -> Add New Doc，或者进入 Cursor -> Settings -> Cursor Settings -> Indexing & Docs -> Add docs。在地址栏中输入库的文档地址，后面加上 /，例如 https://ox.softwaremill.com/latest/。过一段时间后，文档应该会被索引，在我们的案例中，使用的是 Ox 名称。

关于其工作原理的信息很少，但根据代码索引的类比，这似乎是在 Cursor 的服务器上存储文档页面的嵌入表示，然后用于相关的用户查询。或者，使用 AI 术语，这是一种 RAG（检索增强生成）系统。

你可以使用 @Docs Ox 来提示 Cursor 使用 Ox 的文档：

3、Cursor 规则

规则指导 LLMs，通过将规则内容作为每个请求的上下文（“Auto Attached”）、让模型请求规则内容（“Agent Requested”），或在提示中显式提及（“Manual”）来实现。

规则可能是项目范围的，也可以与用户相关联。项目规则存储在 .cursor/rules 目录中。

在 Ox 的情况下，我使用了一个 LLM 来生成规则，因为所有信息应该已经在项目的文档中。我们只需要一个不同的文本投影，适合 AI 编码代理并遵循规则格式。

生成本身是一个两步过程。我使用了 Claude-4-sonnet 模型，首先用一个提示生成规则列表。我要求结果写入文件：按主题分组的规则名称和描述列表。这个列表非常好，但需要一些修改，这相对容易，因为这只是编辑一个文本文件。

第二步是使用另一个提示生成规则本身。再次，LLM 大部分都正确。在某些地方，一些 API 被错误地生成了，所以你仍然需要阅读其中的所有内容。这是结果：

1---  
2description:   
3globs:   
4alwaysApply: true  
5---  
6# Ox 库概述  
7  
8Ox 是一个 Scala 3 库，用于 **JVM 上的安全直接风格流、并发和弹性**。需要 JDK 21+ 和 Scala 3。  
9  
10## 关键概念  
11  
12**直接风格编程**：使用虚拟线程而不是 async/await 或反应流编写阻塞风格的代码。这提供了可读、可调试的代码，没有回调地狱。  
13  
14**双重错误处理**：   
15- 对于错误和意外情况使用 **异常**  
16- 对于应用程序逻辑错误使用 **Either 值**，通过 `.ok()` 解包  
17  
18**结构化并发**：所有并发操作都在高级操作或低级作用域内发生，确保适当的清理和资源管理。  
19  
20**使用 Flows 进行流处理**：使用 `Flow[T]` 进行懒惰、可组合、兼容反应流的数据转换管道，内置并发控制。  
21  
22(...)

不知为何，我无法让 LLM 生成正确的 .mdc 文件元数据头。我怀疑 Cursor 应用程序以某种方式搞砸了这一点，因为这种格式有一个特殊的编辑器视图。因此，作为后期处理步骤，我不得不更新每个规则的元数据，将其设置为“auto attached”或“agent request”，并附带描述。

为了利用这些规则，用户必须从库的 GitHub 获取规则目录，并将所有文件放入其项目的 .cursor/rules 目录中。

大多数规则都是 Agent-Requested，因为这将规则列表及其描述暴露给模型，而无需始终包含每条规则的文本。如果 LLM 认为某条规则在基于描述的情况下有帮助，它可以随后获取更详细的信息：

4、Context7

Context7 是一个开源 MCP (Model Context Protocol) 服务器，旨在为 AI 编码助手提供最新的文档。你可以使用托管的全局 MCP 服务器或运行自己的服务器。

由于这是一个 MCP 服务器，它独立于任何特定的 IDE。它应该与 Cursor、VS Code 等一起正常工作。你可以依赖 Cursor7 的爬虫，或者提供有关要包含和排除哪些目录的指导。此外，你可以提供一组规则，指导模型在使用该库生成代码时的行为。

再次，对于 Ox，我使用 LLM 生成了它，然后做了一些调整。结果 context7.json 文件如下所示：

1{  
2    "$schema": "https://context7.com/schema/context7.json",  
3    "projectTitle": "Ox",  
4    "description": "适用于 JVM 上 Scala 的安全直接风格并发和弹性",  
5    "folders": [  
6        "generated-doc"  
7    ],  
8    "rules": [  
9        "尽可能使用高阶并发操作如 par(), race(), 和 timeout()",  
10        "对于手动并发，始终使用带有监督作用域的结构化并发，以确保线程和资源的适当清理",  
11        "使并发作用域尽可能小，为单个请求或任务创建短生命周期的作用域",  
12        "使用 useCloseableInScope() 实现自动资源管理，确保作用域退出时进行清理",  
13        "通过异常（用于错误和意外情况）或使用 Either 的应用错误值来处理错误",  
14        “(...”)  
15    ]  
16}

在 Ox 的情况下，它的文档已在全局服务器上索引。要在提示中引用它，请确保添加 use context7（提示的上下文不会自动丰富）：

5、llms.txt

另一个旨在标准化 LLM 可访问文档的举措是 llms.txt 文件，它应该位于文档网页的根目录下。它在 llms.txt 网站上有更详细的描述。

然而，尚不清楚是否有任何工具（尤其是 IDE）实际使用它。因此，目前 Ox 不支持这种格式，特别是因为 Sphinx 不支持它，因此需要自定义生成器。然而，如果 llms.txt 格式的支持变得更加普遍，我们也会在 Ox 的文档中包含它。

6、结束语

哪种方法效果最好？

简而言之，这还需要在更大的项目中确定。欢迎反馈 :)

作为基准，当使用 Cursor 和 Claude 4 生成一个简单的演示应用程序而没有额外的上下文时，结果基于 LLM 训练集中的内容。最终，代理会进行网络搜索，结果是正确的，但获取它们需要更长时间。

在 Cursor 中索引文档有所帮助，但 LLM 最初得到的是一个“天真”的较长解决方案。与“基础方法”相比，没有明显的区别。

使用 Cursor 规则和 Context7 获得了最佳效果。使用 Context7 时，你甚至不需要添加 use context7 提示；LLM 会尝试自己获取文档。Context7 的工作方式是提供从整个文档中派生的片段，因此你总是能得到全部内容。对于测试提示，这样生成的解决方案是最全面的，但也是最复杂的（你可能会说，过于复杂）。

当依赖规则时，Cursor 快速收敛到一个正确的结果。有一些多余的构造，表明自动生成的规则需要进行调整。这里的好处是只有相关的规则被代理请求。此外，可以协作和共享规则集（例如，这里是一套 Java 开发的规则）。这也是一个缺点：编写和维护规则需要一些手动劳动。

请记住，对于某些语言，结合上述方法和 MCP 服务器可能会获得更好的结果，这使得你可以探索项目中的可用 API 并运行编译和测试。在 Scala 的情况下，这样的 MCP 服务器是可用的。

原文链接：Providing library documentation to AI coding assistants

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