为什么文档很重要

文档提供了当前准确的上下文信息。没有文档,模型只能使用过时或不完整的训练数据。文档帮助模型理解以下内容:
  • 当前的 API 和参数
  • 最佳实践
  • 组织约定
  • 领域术语
以及更多内容。继续阅读,了解如何在 Cursor 中直接使用文档,而无需切换上下文。

模型知识截止时间

大型语言模型是基于特定时间点之前的数据进行训练的,这个时间点被称为”知识截止时间”。这意味着:
  • 最近的库更新可能不会被反映
  • 新的框架或工具可能是未知的
  • 截止日期之后的 API 变更会被遗漏
  • 最佳实践可能在训练后已经发生了变化
例如,如果一个模型的知识截止时间是 2024 年初,它就不会了解 2024 年末发布的功能,即使是对于流行的框架也是如此。

我应该使用哪个工具?

使用此决策树快速确定满足您文档需求的最佳方法:

心理模型

工具心理模型
@Docs就像浏览和阅读官方文档
@Web就像在互联网上搜索解决方案
MCP就像访问您的内部文档

公共文档

外部文档涵盖了模型可能了解有限或过时的公开可用信息。Cursor 提供了两种主要方式来访问这些信息。

使用 @Docs

@Docs 将 Cursor 连接到流行工具和框架的官方文档。当您需要获取当前权威信息时使用它:
  • API 参考: 函数签名、参数、返回类型
  • 入门指南: 设置、配置、基本用法
  • 最佳实践: 来源推荐的模式
  • 框架特定调试: 官方故障排除指南
@
@Docs Next.js 如何使用捕获所有路由设置动态路由?
Agent⌘I
Auto

使用 @Web

@Web 搜索实时互联网以获取当前信息、博客文章和社区讨论。在以下情况下使用它:
  • 最新教程:社区生成的内容和示例
  • 比较分析:比较不同方法的文章
  • 最新更新:最新的更新或公告
  • 多种观点:解决问题的不同方法
@
@Web latest performance optimizations for React 19
Agent⌘I
Auto

内部文档

内部文档包含特定于您组织的信息,这些信息是AI模型在训练过程中从未遇到过的。这可能包括:
  • 内部API:自定义服务和微服务
  • 公司标准:编码约定、架构模式
  • 专有系统:自定义工具、数据库、工作流程
  • 领域知识:业务逻辑、合规要求

通过 MCP 访问内部文档

Model Context Protocol (MCP) 提供了一种标准化的方式,将您的私有文档和系统引入 Cursor。MCP 在 Cursor 和您的内部资源之间充当一个薄层。 MCP 的重要性:
  • 模型无法猜测您的内部约定
  • 自定义服务的 API 文档不公开可用
  • 业务逻辑和领域知识对您的组织来说是独特的
  • 合规性和安全要求因公司而异

常见的 MCP 集成

集成访问示例
Confluence公司 Confluence 空间架构文档、内部服务的 API 规范、编码标准和指南、流程文档
Google Drive共享文档和文件夹规范文档、会议记录和决策记录、设计文档和需求、团队知识库
Notion工作区数据库和页面项目文档、团队 wiki、知识库、产品需求、技术规范
自定义内部系统和数据库专有 API、遗留文档系统、自定义知识库、专业工具和工作流程

自定义解决方案

对于独特需求,您可以构建自定义 MCP 服务器来:
  • 抓取内部网站或门户
  • 连接到专有数据库
  • 访问自定义文档系统
  • 从内部 wiki 或知识库中提取信息
如果您构建了自定义 MCP 服务器,您还可以公开工具供 Cursor 更新文档
用于抓取内部文档的自定义 MCP 服务器示例:
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import TurndownService from "turndown";

// 创建用于抓取内部文档的 MCP 服务器
const server = new McpServer({
  name: "internal-docs",
  version: "1.0.0"
});

const turndownService = new TurndownService();

// 添加抓取内部文档的工具
server.tool("get_doc",
  { url: z.string() },
  async ({ url }) => {
    try {
      const response = await fetch(url);
      const html = await response.text();
      
      // 将 HTML 转换为 markdown
      const markdown = turndownService.turndown(html);
      
      return {
        content: [{ type: "text", text: markdown }]
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: `抓取 ${url} 时出错:${error.message}` }]
      };
    }
  }
);

// 开始在 stdin 上接收消息并在 stdout 上发送消息
const transport = new StdioServerTransport();
await server.connect(transport);

保持文档更新

文档很容易过时。Cursor 可以帮助您维护最新、有用的文档,通过基于您的实际代码和开发对话来生成和更新文档。

从现有代码生成

使用 Cursor 直接从您的代码库创建文档:
@
为这个 Express 路由器生成 API 文档,包括所有端点、参数和响应格式
Agent⌘I
Auto

从聊天会话中

您与 Cursor 的对话包含有价值的意图,可以转化为文档。
解决复杂问题后:
@
将我们关于设置身份验证的对话总结为团队 wiki 的分步指南
Agent⌘I
Auto

要点总结

  • 将文档作为上下文可以让 Cursor 更加准确和及时
  • 使用 @Docs 获取官方文档,使用 @Web 获取社区知识
  • MCP 在 Cursor 和您的内部系统之间架起桥梁
  • 从代码和对话中生成文档,保持知识的时效性
  • 结合外部和内部文档源,实现全面理解