> ## 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.

# AI编程：如何提供库文档
- URL: https://www.hubwiz.com/blog/ai-coding-how-to-provide-library-documents/
- Published: 2025-11-18T10:22:54.000Z
- Updated: 2025-11-18T10:22:54.000Z
- Description: 如果你正在使用AI编码助手或代理，它们的有用程度将取决于它们对您使用的库的了解程度。
- Author: admin
- Tags: APPLICATION, CONTEXT ENGINEERING, #Import 2026-10-14 14:41

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

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

我在 [X](https://x.com/adamwarski/status/1937444507890372937?ref=hubwiz.com)、[BlueSky](https://bsky.app/profile/warski.org/post/3lsdsc6skxk2x?ref=hubwiz.com) 和 [LinkedIn](https://www.linkedin.com/posts/adamwarski%5Fis-there-some-standard-adopted-as-in-activity-7343210707116613632-XWim?ref=hubwiz.com) 上提出了这个问题，并得到了一致的结果；以下是总结。这是一个不断发展的领域，目前还没有单一的答案或标准，但有一些选项可供探索。

## 1、尝试一下

作为一名库的作者，我当然尝试了上述的方法。到目前为止，我的尝试局限于 [Ox](https://github.com/softwaremill/ox?ref=hubwiz.com) 这个 Scala 并发和弹性库，但如果它证明是有用的，我会将相同的设置扩展到我们维护的其他库（包括 [Jox](https://github.com/softwaremill/jox?ref=hubwiz.com)、[Tapir](https://github.com/softwaremill/tapir?ref=hubwiz.com) 和 [sttp-client](https://github.com/softwaremill/sttp?ref=hubwiz.com)）。

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

## 2、Cursor 文档索引

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

![](https://www.hubwiz.com/blog/content/images/2025/11/image-94.png)

关于其工作原理的信息很少，但根据代码索引的类比，这似乎是在 Cursor 的服务器上存储文档页面的嵌入表示，然后用于相关的用户查询。或者，使用 AI 术语，这是一种 [RAG（检索增强生成）](https://cloud.google.com/use-cases/retrieval-augmented-generation?hl=en&ref=hubwiz.com) 系统。

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

![](https://www.hubwiz.com/blog/content/images/2025/11/image-95.png)

## 3、Cursor 规则

[规则](https://docs.cursor.com/context/rules?ref=hubwiz.com) 指导 LLMs，通过将规则内容作为每个请求的上下文（“Auto Attached”）、让模型请求规则内容（“Agent Requested”），或在提示中显式提及（“Manual”）来实现。

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

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

生成本身是一个两步过程。我使用了 `Claude-4-sonnet` 模型，首先用一个 [提示生成规则列表](https://github.com/softwaremill/ox/blob/master/cursor-rules/generation/prompt1-rule-list.md?ref=hubwiz.com)。我要求结果写入文件：按主题分组的规则名称和描述列表。这个列表非常好，但需要一些修改，这相对容易，因为这只是编辑一个 [文本文件](https://github.com/softwaremill/ox/blob/master/cursor-rules/generation/rules-list.md?ref=hubwiz.com)。

第二步是使用 [另一个提示](https://github.com/softwaremill/ox/blob/master/cursor-rules/generation/prompt2-rule-gen.md?ref=hubwiz.com) 生成规则本身。再次，LLM 大部分都正确。在某些地方，一些 API 被错误地生成了，所以你仍然需要阅读其中的所有内容。这是 [结果](https://github.com/softwaremill/ox/tree/master/cursor-rules?ref=hubwiz.com)：

```
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 认为某条规则在基于描述的情况下有帮助，它可以随后获取更详细的信息：

![](https://www.hubwiz.com/blog/content/images/2025/11/image-96.png)

## 4、Context7

[Context7](https://github.com/upstash/context7?ref=hubwiz.com) 是一个开源 MCP ([Model Context Protocol](https://virtuslab.com/blog/ai/virtuslab-guide-agentic-programming-jvm-part-one/?ref=hubwiz.com)) 服务器，旨在为 AI 编码助手提供最新的文档。你可以使用托管的全局 MCP 服务器或运行自己的服务器。

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

再次，对于 Ox，我使用 LLM 生成了它，然后做了一些调整。结果 [context7.json](https://github.com/softwaremill/ox/blob/master/context7.json?ref=hubwiz.com) 文件如下所示：

```
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 的情况下，它的文档已 [在全局服务器上索引](https://context7.com/add-library?ref=hubwiz.com)。要在提示中引用它，请确保添加 `use context7`（提示的上下文不会自动丰富）：

![](https://www.hubwiz.com/blog/content/images/2025/11/image-97.png)

## 5、llms.txt

另一个旨在标准化 LLM 可访问文档的举措是 `llms.txt` 文件，它应该位于文档网页的根目录下。它在 [llms.txt](https://llmstxt.org/?ref=hubwiz.com) 网站上有更详细的描述。

然而，尚不清楚是否有任何工具（尤其是 [IDE](https://virtuslab.com/blog/backend/best-ide-in-2024/?ref=hubwiz.com)）实际使用它。因此，目前 Ox 不支持这种格式，特别是因为 [Sphinx](https://github.com/sphinx-doc/sphinx/issues/13268?ref=hubwiz.com) 不支持它，因此需要自定义生成器。然而，如果 `llms.txt` 格式的支持变得更加普遍，我们也会在 Ox 的文档中包含它。

## 6、结束语

哪种方法效果最好？

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

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

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

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

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

请记住，对于某些语言，结合上述方法和 MCP 服务器可能会获得更好的结果，这使得你可以探索项目中的可用 API 并运行编译和测试。在 Scala 的情况下，这样的 [MCP 服务器是可用的](https://softwaremill.com/a-beginners-guide-to-using-scala-metals-with-its-model-context-protocol-server/?ref=hubwiz.com)。

---

原文链接：[Providing library documentation to AI coding assistants](https://virtuslab.com/blog/ai/providing-library-documentation/?ref=hubwiz.com)

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