[Cursor-Guide]文档协作指南

原始链接: 原始链接

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

文档的重要性

文档提供最新、准确的上下文。缺乏文档时，模型会使用过时或不完整的训练数据。文档帮助模型理解以下内容：

• 当前API及参数
• 最佳实践
• 组织规范
• 领域术语

等等。继续阅读了解如何在Cursor中直接使用文档而无需切换上下文。

模型知识截止

大语言模型的训练数据截止于特定时间点，称为"知识截止"。这意味着：

• 可能未反映最近的库更新
• 可能不了解新框架或工具
• 会遗漏截止日期后的API变更
• 训练后的最佳实践可能已演进

例如，若模型的知识截止为2024年初，它将不知道2024年末发布的功能，即使对于流行框架也是如此。

工具选择指南

使用此决策树帮助选择合适工具

心智模型

公共文档

外部文档涵盖模型可能只有有限或过时知识的公开信息。Cursor提供两种主要访问方式。

使用@Docs

@Docs连接Cursor与流行工具的官方文档。当需要以下最新权威信息时使用：

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

使用@Web

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

• 最新教程：社区生成的内容和示例
• 对比分析：不同方法的比较文章
• 近期更新：最新发布或公告
• 多元视角：问题的不同解决思路

内部文档

内部文档包含模型训练中从未接触的组织特定信息，可能包括：

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

通过MCP访问内部文档

模型上下文协议(MCP)提供了将私有文档和系统接入Cursor的标准化方式。MCP作为Cursor与内部资源间的薄层。

MCP的重要性：

• 模型无法猜测内部规范
• 定制服务的API文档不公开
• 业务逻辑和领域知识具有独特性
• 合规安全要求因公司而异

常见MCP集成

定制解决方案

针对特殊需求，可构建定制MCP服务器实现：

• 抓取内部网站或门户
• 连接专有数据库
• 访问定制文档系统
• 从内部维基或知识库拉取

构建定制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";

// 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);

保持文档更新

文档容易过时。Cursor可根据实际代码和开发对话生成更新文档，帮助维护最新有效的文档。

基于现有代码

使用Cursor直接从代码库生成文档：

• API文档

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

• JSDoc注释

为此类添加全面的JSDoc注释，记录所有方法及其参数

• README创建

为此项目创建README，包含安装说明、使用示例和API概览

• 架构设计

编写文档说明我们选择该数据库设计的原因，包括我们讨论过的权衡取舍

• 调试排错

根据我们刚修复的这个bug编写故障排除指南，需包含症状表现和解决步骤

核心要点

• 将文档作为上下文可使Cursor的响应更准确且与时俱进
• 使用@Docs引用官方文档，@Web引用社区知识
• MCP（Metadata Context Provider）弥合了Cursor与内部系统间的鸿沟
• 通过代码和对话生成文档以保持知识更新
• 结合外部与内部文档来源以获得全面理解

系列文章索引

• [Cursor-Guide]上下文应用指南
• [Cursor-Guide]模型选择指南
• [Cursor-Guide]Web开发指南
• [Cursor-Guide]架构图
• [Cursor-Guide]大型代码库管理
• [Cursor-Guide]文档协作指南