⚡

Cursor文档管理Skill cursor-docs

此技能是一个自动化工具，用于管理Cursor IDE的文档系统。它提供文档爬取、索引管理、搜索和解析功能，确保文档的一致性和可访问性。关键词：文档管理、自动化、搜索、索引、Cursor、开发工具、文档自动化。

其他 0 次安装 0 次浏览 更新于 3/11/2026

name: cursor-docs description: Cursor所有文档的单一真相来源和图书管理员。管理本地文档存储、爬取、发现和解析。在查找、定位、搜索或解析Cursor文档时使用；通过关键词、类别、标签或自然语言查询发现文档；从llms.txt爬取；管理索引元数据（关键词、标签、别名）；或从文件系统重建索引。运行脚本以爬取、查找和解析文档。处理doc_id解析、关键词搜索、自然语言查询、类别/标签过滤、别名解析、llms.txt解析、用于内部使用的markdown子节提取、基于哈希的漂移检测和全面索引维护。 allowed-tools: Read, Glob, Grep, Bash

Cursor文档技能

关键：路径重复预防 - 强制要求

绝对禁止：在从此技能运行脚本时，切勿在PowerShell中使用带&&的cd。

问题： 如果当前工作目录已在技能目录内，使用相对路径会导致PowerShell相对于当前目录而非仓库根目录解析路径，从而导致路径重复。

必需解决方案（选择其一）：

  1. 始终使用绝对路径（推荐）
  2. 使用单独命令（切勿使用带&&的cd）
  3. 从仓库根目录运行并使用相对路径

切勿这样做：

  • 链式使用cd与&&：cd <相对路径> && python <脚本>导致路径重复
  • 假设当前目录
  • 当前目录在技能目录内时使用相对路径

关键：大文件处理 - 强制使用脚本

绝对禁止：切勿使用read_file工具读取index.yaml文件

文件超出上下文限制并会导致问题。必须使用脚本。

必需：始终使用manage_index.py脚本进行任何index.yaml访问：

python scripts/management/manage_index.py count
python scripts/management/manage_index.py list
python scripts/management/manage_index.py get <doc_id>
python scripts/management/manage_index.py verify

所有脚本通过index_manager.py自动处理大文件。

可用斜杠命令

使用统一的docs-ops技能处理常见工作流：

  • /cursor-ecosystem:docs-ops scrape - 从llms.txt源爬取Cursor文档
  • /cursor-ecosystem:docs-ops refresh - 刷新本地索引和元数据而不爬取
  • /cursor-ecosystem:docs-ops validate - 验证索引和引用的一致性
  • /cursor-ecosystem:docs-ops rebuild-index - 强制重建搜索索引
  • /cursor-ecosystem:docs-ops clear-cache - 清除文档搜索缓存

概述

此技能提供Cursor文档管理的自动化工具。它管理：

  • 规范存储（封装在技能中） - 官方文档的单一真相来源
  • 子节提取 - 令牌优化的提取（节省60-90%）
  • 漂移检测 - 基于哈希的验证以对抗上游源
  • 同步工作流 - 维护自动化
  • 文档发现 - 基于关键词的搜索和doc_id解析
  • 索引管理 - 元数据、关键词、标签、别名，用于弹性引用

核心价值： 防止链接失效，实现离线访问，优化令牌成本，自动化维护，并提供基于doc_id的弹性引用。

何时使用此技能

此技能应在以下情况下使用：

  • 爬取文档 - 从Cursor源获取文档
  • 查找文档 - 通过关键词、类别或自然语言搜索文档
  • 解析文档引用 - 将doc_id转换为文件路径
  • 管理索引元数据 - 添加关键词、标签、别名，更新元数据
  • 重建索引 - 从文件系统重新生成索引（处理重命名/移动）

工作流执行模式

关键：此部分定义了如何在此技能中执行操作。

委托策略

默认方法：委托给任务代理

对于所有爬取、验证和索引操作，将执行委托给通用任务代理。

如何调用：

使用Task工具，参数包括：

  • subagent_type: “general-purpose”
  • description: 简短的3-5字描述
  • prompt: 完整任务描述和执行指令

执行模式

脚本默认在前台运行。切勿在后台运行。

当任务代理执行脚本时：

  • 直接运行：python plugins/cursor-ecosystem/skills/cursor-docs/scripts/core/scrape_docs.py
  • 流式日志：脚本通过stdout自然发出进度
  • 等待完成：脚本完成后退出并带有退出代码
  • 切勿使用run_in_background=true：脚本设计为前台执行
  • 切勿轮询输出：流式日志自动出现，无需BashOutput轮询
  • 切勿使用后台作业：无&、无nohup、无后台进程管理

错误和警告报告

关键：报告所有错误、警告和问题 - 切勿抑制或忽略它们。

当通过任务代理执行脚本时：

  • 报告脚本错误：退出代码、异常、错误消息
  • 报告警告：弃用警告、导入问题、配置问题
  • 报告意外输出：404、超时、验证失败
  • 包含上下文：错误发生时正在执行的内容

快速开始

端到端刷新索引（无爬取）

当您希望在不爬取的情况下重建和验证本地索引/元数据时使用：

python plugins/cursor-ecosystem/skills/cursor-docs/scripts/management/refresh_index.py

爬取所有文档

当用户明确希望访问网络并爬取文档时使用：

# 从配置的llms.txt源爬取
python plugins/cursor-ecosystem/skills/cursor-docs/scripts/core/scrape_docs.py

# 爬取后刷新索引
python plugins/cursor-ecosystem/skills/cursor-docs/scripts/management/refresh_index.py

查找文档

# 将doc_id解析为文件路径
python plugins/cursor-ecosystem/skills/cursor-docs/scripts/core/find_docs.py resolve <doc_id>

# 通过关键词搜索（默认：25个结果）
python plugins/cursor-ecosystem/skills/cursor-docs/scripts/core/find_docs.py search agent mcp

# 自然语言搜索
python plugins/cursor-ecosystem/skills/cursor-docs/scripts/core/find_docs.py query "如何配置代理模式"

# 按类别列出
python plugins/cursor-ecosystem/skills/cursor-docs/scripts/core/find_docs.py category core

# 按标签列出
python plugins/cursor-ecosystem/skills/cursor-docs/scripts/core/find_docs.py tag cli

搜索选项：

选项 默认值 描述
--limit N 25 返回的最大结果数
--no-limit - 返回所有匹配结果（无限制）
--min-score N - 仅返回相关度分数 >= N 的结果
--fast - 仅索引搜索（跳过内容grep）
--json - 以JSON格式输出结果
--verbose - 显示相关度分数

配置系统

cursor-docs技能使用统一配置系统。

配置文件：

  • config/defaults.yaml - 包含所有默认值的中央配置文件
  • config/filtering.yaml - 内容过滤规则
  • config/tag_detection.yaml - 标签检测模式

环境变量覆盖：

所有配置值都可以使用环境变量覆盖：CURSOR_DOCS_<SECTION>_<KEY>

依赖项

必需： pyyaml, requests, beautifulsoup4, markdownify, filelock 可选（推荐）： yake（用于关键词提取）

Python版本： 推荐Python 3.11+

核心能力

1. 爬取文档

从配置的源使用llms.txt格式获取文档。

2. 提取子节

提取特定markdown节以进行令牌优化响应。

3. 变更检测

通过404检查和哈希比较检测文档漂移。

4. 查找和解析文档

使用doc_id、关键词或自然语言查询发现和解析文档引用。

5. 索引管理和维护

维护索引元数据、关键词、标签，并从文件系统重建索引。

平台特定要求

Windows用户

必须使用PowerShell（推荐）或在Git Bash命令前加MSYS_NO_PATHCONV=1

Windows上的Git Bash将Unix路径转换为Windows路径，破坏过滤模式。

示例：

MSYS_NO_PATHCONV=1 python scripts/core/scrape_docs.py --filter "/docs/"

故障排除

Unicode编码错误

状态： 已修复 - 脚本自动检测Windows并配置UTF-8编码。

爬取期间的404错误

状态： 预期 - 一些llms.txt条目可能引用尚不存在的文档。脚本优雅处理并继续。

公共API

cursor-docs技能为外部工具提供干净的公共API：

from cursor_docs_api import (
    find_document,
    resolve_doc_id,
    get_docs_by_tag,
    get_docs_by_category,
    search_by_keywords,
    get_document_section,
    refresh_index
)

# 自然语言搜索
docs = find_document("代理模式配置")

# 将doc_id解析为元数据
doc = resolve_doc_id("cursor-getting-started")

# 按标签获取文档
cli_docs = get_docs_by_tag("cli")

# 提取特定节
section = get_document_section("cursor-overview", "安装")

开发模式

在本地开发此插件时，您可能希望更改转到开发仓库而非安装的插件位置。

启用开发模式

PowerShell：

$env:CURSOR_DOCS_DEV_ROOT = "D:\repos\gh\melodic\claude-code-plugins"

Bash/Zsh：

export CURSOR_DOCS_DEV_ROOT="/path/to/claude-code-plugins"

验证模式

当您运行任何主要脚本（爬取、刷新、重建）时，会显示模式横幅：

开发模式：

[开发模式] 使用本地插件：D:\repos\gh\melodic\claude-code-plugins

生产模式：

[生产模式] 使用安装的技能目录

禁用开发模式

PowerShell：

Remove-Item Env:CURSOR_DOCS_DEV_ROOT

Bash/Zsh：

unset CURSOR_DOCS_DEV_ROOT

目录结构

cursor-docs/
  SKILL.md                    # 此文件（公开）
  cursor_docs_api.py          # 公共API
  canonical/                  # 文档存储（私有）
    index.yaml                # 元数据索引
  scripts/                    # 实现（私有）
    core/                     # 爬取、发现
    management/               # 索引管理
    maintenance/              # 清理、漂移检测
    utils/                    # 共享实用工具
  config/                     # 配置
    defaults.yaml             # 默认设置
    filtering.yaml            # 内容过滤
    tag_detection.yaml        # 标签模式
  references/                 # 技术文档（公开）
    sources.json              # 文档源
  .cache/                     # 缓存存储（倒排索引）
  logs/                       # 日志文件

来源

文档从Cursor llms.txt爬取，地址为https://cursor.com/llms.txt。

文档类别

Cursor文档组织为以下类别：

类别 描述
get-started 入门指南和教程
core 核心功能（Tab、Agent、Inline Edit）
context 上下文管理（代码库索引、MCP、规则）
integrations 外部集成（Slack、Linear、GitHub、GitLab）
configuration 设置和配置
account 账户管理和计费
cookbook 示例和食谱
troubleshooting 问题解决和FAQ

标签

Cursor文档常用标签：

  • cli - Cursor CLI功能
  • ide - Cursor IDE功能
  • agent - 代理模式功能
  • tab - Tab补全功能
  • mcp - 模型上下文协议
  • context - 上下文管理
  • enterprise - 企业功能
  • cloud-agent - 云代理和API
  • inline-edit - 内联编辑功能

测试场景

场景1：关键词搜索

查询： “搜索CLI文档” 预期行为：

  • 技能在关键词"文档"上激活
  • 从索引返回相关文档 成功标准： 用户收到匹配的文档条目

场景2：自然语言查询

查询： “如何配置Cursor代理模式？” 预期行为：

  • 技能在"Cursor"上激活
  • 使用find_docs.py查询命令 成功标准： 返回带有配置步骤的相关文档

场景3：Doc ID解析

查询： “解析cursor-getting-started” 预期行为：

  • 将doc_id解析为文件路径
  • 返回文档元数据 成功标准： 用户收到完整路径和文档内容

版本历史

  • v1.0.0 (2025-12-16): 初始版本 - 从codex-cli-docs适配的完整技能结构

最后更新

日期： 2025-12-16 模型： claude-opus-4-5-20251101

状态： 初始版本 - 准备从https://cursor.com/llms.txt爬取。