引用文档 ¶
Cursor 是一款功能强大的代码编辑工具，集成了文档管理功能，帮助开发者和团队在编写代码时快速访问和引用相关文档。本指南将详细介绍如何在 Cursor 中引用文档，包括不同工具的使用场景、设置步骤以及最佳实践。
1. 为什么要在 Cursor 中引用文档 ¶
根据官方文档，文档为 Cursor 提供了当前且准确的上下文信息。大型语言模型（LLM）的知识库有截止日期（knowledge cutoff），这意味着：
- 模型可能不了解最新的库更新、新框架或工具。
- API 变更或最佳实践的演进可能未被模型知晓。
通过引用文档，Cursor 可以帮助您获取最新的 API 参考、框架指南、组织内部标准等信息，从而提高代码开发的准确性和效率。文档引用主要解决以下问题：
- 当前 API 和参数：了解最新的函数签名和用法。
- 最佳实践：获取官方推荐的模式和方法。
- 组织规范：遵循公司内部的编码标准或架构模式。
- 领域术语：理解特定业务逻辑或合规要求。
2. 在 Cursor 中引用文档的工具选择 ¶
Cursor 提供了多种工具来引用文档，根据您的需求选择合适的工具非常重要。官方文档中提供了一个决策树和心智模型（Mental Model）来帮助用户选择：
| 工具 | 心智模型 | 适用场景 |
|---|---|---|
@Docs |
像浏览和阅读官方文档一样 | 需要官方 API 参考、入门指南、调试指南等权威信息 |
@Web |
像在互联网上搜索解决方案一样 | 需要最新的教程、比较文章、社区讨论或多种视角 |
| MCP | 像访问内部文档一样 | 需要公司内部 API、标准、专有系统信息等 |
2.1 使用 @Docs 引用官方文档 ¶
@Docs 连接到流行工具和框架的官方文档，适用于获取当前、权威的信息。您可以在 Cursor 的聊天或代码编辑界面中输入 @Docs，然后搜索相关文档内容，例如：
- API 参考：函数签名、参数、返回类型。
- 入门指南：设置、配置、基本用法。
- 最佳实践：官方推荐的模式。
- 框架特定调试：官方故障排查指南。
使用步骤：
- 在 Cursor 聊天窗口或代码注释中输入
@Docs。 - 输入您要查询的框架或工具名称（如 "React" 或 "Python requests"）。
- 选择相关文档内容，Cursor 将插入引用或显示详细信息。
2.2 使用 @Web 获取互联网信息 ¶
当您需要最新的社区内容或多种视角时，可以使用 @Web 工具搜索互联网上的信息，适用于：
- 近期教程：社区生成的例子。
- 对比文章：不同方法的比较。
- 最新更新：近期公告或更新。
- 多种视角：解决问题的不同方法。
使用步骤：
- 在聊天窗口输入
@Web。 - 输入搜索关键词（如 "latest React hooks tutorial"）。
- Cursor 将显示搜索结果，您可以直接引用或浏览相关内容。
2.3 使用 MCP 访问内部文档 ¶
对于组织特定的内部文档，Cursor 提供了模型上下文协议（Model Context Protocol, MCP），这是一个连接 Cursor 和您内部资源的桥梁。MCP 适用于：
- 内部 API：自定义服务或微服务。
- 公司标准：编码规范、架构模式。
- 专有系统：自定义工具、数据库、工作流程。
- 领域知识：业务逻辑或合规要求。
常见 MCP 集成：
- Confluence：访问公司架构文档、内部 API 规范。
- Google Drive：查看共享的规格文档、设计要求。
- Notion：连接项目文档、团队知识库。
- 自定义解决方案：通过 MCP 服务器连接内部网站、专有数据库或 wiki。
使用步骤：
- 确保您的组织已配置 MCP（可能需要 IT 团队支持）。
- 在 Cursor 中选择 MCP 集成，访问内部资源。
- 在对话或代码中直接引用内部文档内容。
3. 设置文档引用环境 ¶
要开始在 Cursor 中引用文档，您需要确保环境已正确配置：
- 登录 Cursor 账户：确保可以访问云端功能和集成工具。
- 启用 MCP 集成：如果需要访问内部文档，联系管理员确认 MCP 已设置。
- 熟悉界面：了解聊天窗口和代码编辑器中
@Docs和@Web的快捷输入方式。
4. 在代码中引用文档 ¶
Cursor 支持在代码注释或聊天中直接引用文档内容，以便快速访问相关信息。
4.1 通过 @Docs 或 @Web 引用 ¶
在代码注释中输入 @Docs 或 @Web，Cursor 会弹出搜索框供您查找文档或互联网内容。
示例：
# Reference: @Docs Python Requests Library for API calls
def make_api_request(url):
pass
点击 @Docs Python Requests Library，Cursor 将显示官方文档的相关内容。
4.2 引用内部文档 ¶
如果使用 MCP，可以在代码中引用内部资源：
// See internal API spec via MCP: Authentication Service
function authUser() {
// Implementation here
}
5. 保持文档最新 ¶
文档很容易过时，Cursor 提供了生成和更新文档的功能：
- 从现有代码生成文档：Cursor 可以根据代码库自动生成文档注释或说明文件。
- 从聊天记录生成文档：在解决复杂问题后，将对话内容转为文档保存。
示例：在聊天中解决了一个问题后，点击“保存为文档”按钮，将解决方案存储为团队知识库的一部分。
6. 最佳实践 ¶
为确保文档引用的有效性，建议遵循以下最佳实践：
- 结合外部和内部文档：综合使用
@Docs、@Web和 MCP，获取全面信息。 - 定期更新文档：使用 Cursor 的生成工具保持文档内容最新。
- 描述性引用：在代码中引用时，添加简短说明，如“See API Authentication for token usage”。
- 选择合适的工具：根据需求选择
@Docs（官方信息）、@Web（社区内容）或 MCP（内部文档）。 - 维护文档结构：无论是内部还是外部文档，确保目录清晰，便于快速查找。
7. 解决常见问题 ¶
- 文档内容过时：如果引用的文档不准确，使用
@Web获取最新信息，或通过 MCP 更新内部文档。 - 找不到相关文档：尝试不同的关键词，或切换工具（例如从
@Docs到@Web）。 - MCP 集成问题：如果无法访问内部文档，联系 IT 团队确认配置是否正确。
结论 ¶
在 Cursor 中引用文档是提升开发效率和代码质量的重要手段。通过 @Docs 获取官方权威信息、通过 @Web 搜索最新社区内容、以及通过 MCP 访问内部资源，您可以确保始终使用准确且相关的上下文信息。遵循本指南的步骤和最佳实践，您将能够充分利用 Cursor 的文档引用功能，优化工作流程。