文档协作

如何通过提示、外部资源和内部上下文，在 Cursor 中高效利用文档

为什么文档很重要

文档为模型提供了最新、准确的上下文。如果没有文档，模型只能依赖过时或不完整的训练数据。文档有助于模型理解如下内容：

• 当前的 API 和参数
• 最佳实践
• 组织规范
• 领域术语 以及更多内容. 继续阅读，了解如何在 Cursor 中直接使用文档，无需频繁切换上下文。

模型知识截止点

大型语言模型的训练数据截止到某一时间点，这被称为“知识截止点”。这意味着：

• 最近的库更新可能不会被反映
• 新的框架或工具可能不被模型所知
• 截止日期之后的 API 变更会被遗漏
• 最佳实践可能已经发生变化

例如，如果模型的知识截止点是 2024 年初，即使是流行框架，2024 年底发布的新特性模型也不会了解。

我该用哪个工具？

你可以参考下方决策树选择合适的工具：

思维模型（Mental Model）

公共文档

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

使用 @Docs

@Docs 让 Cursor 连接到流行工具和框架的官方文档。当你需要最新、权威的信息时使用它，例如：

• API 参考：函数签名、参数、返回类型
• 入门指南：安装、配置、基础用法
• 最佳实践：官方推荐的模式
• 框架专属调试：官方故障排查指南

使用 @Web

@Web 会在互联网上实时搜索最新信息、博客和社区讨论。当你需要以下内容时使用：

• 最新教程：社区生成的内容和示例
• 对比分析：不同方法的文章
• 最新动态：非常新的更新或公告
• 多元观点：不同问题的多种解决思路

内部文档

内部文档包含了你所在组织特有的信息，这些内容模型在训练时从未接触过，例如：

• 内部 API：自定义服务和微服务
• 公司标准：编码规范、架构模式
• 专有系统：自定义工具、数据库、工作流
• 领域知识：业务逻辑、合规要求

通过 MCP 访问内部文档

模型上下文协议（MCP）为将你的私有文档和系统引入 Cursor 提供了标准化方式。MCP 充当 Cursor 与内部资源之间的中间层。

为什么 MCP 很重要：

• 模型无法猜测你的内部规范
• 自定义服务的 API 文档并非公开可用
• 业务逻辑和领域知识对每个组织都是独特的

常见的 MCP 集成

自定义解决方案

对于特殊需求，你可以构建自定义 MCP 服务器，实现：

• 抓取内部网站或门户
• 连接专有数据库
• 访问自定义文档系统
• 拉取内部 wiki 或知识库

自定义 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";

// Create an MCP server for scraping internal docs
const server = new McpServer({
  name: "internal-docs",
  version: "1.0.0"
});

const turndownService = new TurndownService();

// Add tool to scrape internal documentation
server.tool("get_doc",
  { url: z.string() },
  async ({ url }) => {
    try {
      const response = await fetch(url);
      const html = await response.text();
      
      // Convert HTML to markdown
      const markdown = turndownService.turndown(html);
      
      return {
        content: [{ type: "text", text: markdown }]
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: `Error scraping ${url}: ${error.message}` }]
      };
    }
  }
);

// Start receiving messages on stdin and sending messages on stdout
const transport = new StdioServerTransport();
await server.connect(transport);

# server.py
import os
import asyncio
from mcp.server.fastmcp import FastMCP
import aiohttp
from markdownify import markdownify as md

# Create an MCP server for scraping internal docs
mcp = FastMCP("internal-docs")

@mcp.tool()
async def get_doc(url: str) -> dict:
    """Scrape internal documentation from a URL"""
    try:
        async with aiohttp.ClientSession() as session:
            async with session.get(url) as response:
                html = await response.text()
        
        # Convert HTML to markdown
        markdown = md(html)
        
        return {
            "content": [{"type": "text", "text": markdown}]
        }
    except Exception as error:
        return {
            "content": [{"type": "text", "text": f"Error scraping {url}: {str(error)}"}]
        }

保持文档最新

文档很容易过时。Cursor 可以根据你的实际代码和开发对话，自动生成和更新文档，帮助你保持文档的时效性和实用性。

从现有代码生成文档

你可以直接用 Cursor 从代码库生成文档：

• API 文档
• JSDoc 注释
• README 创建

为此 Express 路由生成 API 文档，包括所有端点、参数和响应格式

从聊天会话生成文档

你与 Cursor 的对话中包含了有价值的意图，这些内容可以转化为文档：

• 问题解决

请将我们关于设置认证的对话内容，总结成一份团队 Wiki 的分步指南。

• 架构决策 在架构决策之后：

请编写文档，说明我们为何选择了这种数据库设计，并包含我们讨论过的权衡取舍。

• 调试过程 在调试会话后:

请根据我们刚刚修复的这个 bug 编写一份故障排查指南，内容包括症状描述和解决步骤。

要点总结

• 将文档作为上下文能让 Cursor 更加准确和及时
• 官方文档用 @Docs，社区知识用 @Web
• MCP 架起了 Cursor 与内部系统之间的桥梁
• 通过代码和对话生成文档，保持知识的最新
• 结合外部和内部文档来源，实现全面理解