1. 项目概述：为什么需要一套现成的 Cursor 配置？

如果你和我一样，是 Cursor 的重度用户，那么你肯定经历过这样的阶段：刚上手时，觉得这个 AI 驱动的 IDE 简直是神器，但随着项目越来越复杂，你开始不满足于它默认的、略显“通用”的智能体（Agent）和技能（Skill）。你希望它能更懂你的代码规范，能自动执行测试驱动开发（TDD）流程，或者能根据你的项目类型（比如前端 React 或后端 Node.js）提供更精准的代码建议。于是，你开始手动创建 .cursor 目录，在里面写各种 .md 文件来定义规则、命令和技能。这个过程很酷，但也相当耗时，而且容易陷入“重复造轮子”的困境。

everything-cursor 这个项目，就是为了解决这个痛点而生的。它不是一个全新的工具，而是一个精心打包的、开箱即用的 Cursor 配置集合。它的核心价值在于，将社区中经过验证的最佳实践——比如清晰的代码结构规则、高效的 TDD 工作流、针对特定框架的智能体配置——打包成一个可以一键安装的包。你不用再从零开始研究 .cursor/agents/planner.md 该怎么写，也不用去琢磨如何定义一个能真正帮你写测试的 tdd-workflow 技能。 everything-cursor 把这些都准备好了，你只需要选择是把它安装到当前项目（ .cursor/ ）还是你的用户目录（ ~/.cursor/ ），然后就可以立刻享受到一套深度定制化的 AI 编程体验。

简单来说，它就像给你的 Cursor 安装了一个“增强模组”，瞬间扩展了其原生能力。更重要的是，它的设计非常巧妙。你可能注意到了，这个项目是基于 everything-claude-code （一个为 Claude Code 编辑器准备的类似项目）构建的。这是因为 Cursor 和 Claude Code 共享了底层的技能存储路径（ ~/.claude/ ）。 everything-cursor 通过一个子模块引用了前者的配置库，并提供了一个跨运行时（Deno/Node.js）的 CLI 工具，将这些配置“搬运”并适配到 Cursor 自己的目录结构中。这意味着你获得的是经过双重验证的、高质量的配置内容。

2. 核心原理与架构设计解析

要真正用好 everything-cursor ，理解它的工作原理和设计思路是关键。这能帮助你在遇到问题时快速排查，也能让你明白如何安全地进行自定义，而不用担心下次更新时自己的心血被覆盖。

2.1 技能共享机制：Cursor 与 Claude Code 的“默契”

项目文档里提到一个非常有趣且重要的点： 为什么基于 Claude Code 的配置可以直接用于 Cursor？ 这背后是 Anthropic（Claude 的创造者）和 Cursor 团队之间一种心照不宣的“兼容性”。

官方上，Cursor 只明确说明从 ~/.claude/skills/ 目录读取技能。但实践中，Cursor 的扫描逻辑更“宽松”，它会递归扫描整个 ~/.claude/ 目录。而 everything-claude-code 这类工具，会将缓存的技能文件存放在 ~/.claude/plugins/cache/ 这样的子目录里。Cursor 在扫描时，会一并发现这些缓存文件，从而加载其中的技能。

everything-cursor 正是利用了这一点。但它没有选择“借用”缓存路径这种取巧但可能不稳定的方式，而是采取了更直接、更可靠的做法： 将 everything-claude-code 仓库中的配置原样复制到 Cursor 官方认可的目录结构（ .cursor/ 或 ~/.cursor/ ）中 。因为两者的配置格式（Markdown 文件描述智能体、技能、命令）本质上是相通的。这使得 everything-claude-code 这个丰富的配置生态，可以几乎无损地迁移到 Cursor 环境。

注意 ：虽然机制上可行，但并非所有 Claude Code 技能都能 100% 在 Cursor 中完美运行，因为两个编辑器的上下文窗口、API 可用性可能存在细微差异。不过， everything-cursor 选取的配置都是经过筛选和测试的通用性较强的部分，兼容性很高。

2.2 项目结构：清晰的责任分离

我们来看看 everything-cursor 项目本身的结构，这能让你明白它是如何工作的：

everything-cursor/
├── everything-claude-code/    # 子模块，核心配置来源
├── cli.ts                     # Deno CLI 主入口
├—— scripts/
│   └── generate-file-list.mjs # 构建脚本，生成文件清单
├── file-list.json             # 由脚本生成，记录所有要分发的 .md 文件
├── jsr.json                   # Deno JSR 包配置
└── package.json               # npm 包配置

它的核心是一个 “搬运工” 架构：

1. 配置源 ： everything-claude-code 子模块，这是一个独立的、维护者可能不同的仓库，专门存放各种 AI 编程配置。
2. 分发逻辑 ： cli.ts 和相关的 Node.js 封装，负责读取子模块中的文件，并根据用户选择（本地或全局）复制到正确的 Cursor 目录。
3. 清单管理 ： file-list.json 是关键。它是在构建时（ npm run build 或发布前）由脚本自动生成的，列出了子模块中所有需要被复制的 .md 文件路径。这样做的好处是：
   • 精确控制 ：只复制需要的文件（ agents/ , skills/ , commands/ , rules/ 下的 .md 文件），忽略测试文件、脚本等。
   • 安全 ：防止意外复制或执行任何非 Markdown 文件。
   • 高效更新 ：更新子模块后，重新生成清单即可知道哪些文件变了。

2.3 安装策略：本地与全局的权衡

安装时让你选择的 “local” 和 “home” ，是两种不同的使用策略，对应不同的场景：

• 本地安装（ ./.cursor/ ） ：

  • 场景 ：适用于公司项目、特定技术栈项目（如一个 React 项目组）。
  • 优点 ：配置与项目绑定。提交到 Git 后，所有克隆该项目的团队成员都会获得完全一致的 Cursor 配置，保证团队编码规范和工作流的统一。
  • 缺点 ：每个项目都需要安装一次（虽然可以自动化）。

• 全局安装（ ~/.cursor/ ） ：

  • 场景 ：适用于个人开发者，或者你有一套自己偏好的、适用于所有个人项目的通用配置。
  • 优点 ：一次安装，所有项目受益。非常方便，无需为每个新项目重复设置。
  • 缺点 ：无法针对不同项目做精细化配置。如果项目间技术栈差异巨大（比如一个是 Go 微服务，一个是前端 Vue），全局配置可能不够贴切。

实操心得 ：我个人通常采用混合策略。在 ~/.cursor/ 安装一套我的个人通用基础配置（如代码风格、安全规则）。然后，对于重要的团队项目，再在项目根目录运行一次 everything-cursor install 选择 local ，覆盖或补充团队特定的规则和命令。Cursor 会智能地合并这些配置，本地目录的配置通常优先级更高。

3. 完整安装与配置实战指南

了解了原理，我们来一步步完成安装和初步探索。这里我会以最推荐的 Deno 方式为例，因为它是一键执行，无需永久安装，最干净。同时也会说明其他包管理器的细节。

3.1 环境准备与安装执行

首先，确保你系统上安装了 Cursor 编辑器。然后打开终端。

使用 Deno（推荐，无残留） ：

# 这是一条命令，直接下载并执行最新版本的安装脚本
deno run -A jsr:@yoshixmk/everything-cursor/cli install

运行后，你会立刻看到交互提示：

📍 Select installation location:
  1) local  - Project local (.cursor/)
  2) home   - Home directory (~/.cursor/)
  3) cancel - Cancel installation

Enter your choice (1-3):

输入 1 或 2 并回车。脚本就会开始工作，将文件复制到目标位置。你会看到类似以下的输出：

📦 Installing everything-cursor...
🔍 Scanning for Markdown files...
📄 Copying agents/planner.md...
📄 Copying skills/tdd-workflow/README.md...
...
✅ Installation complete!
  Location: ~/.cursor/
  Files installed: 47

使用 npm/pnpm（适合 Node.js 生态用户） ：

# npm 一次性执行
npx everything-cursor install

# 或 pnpm 一次性执行
pnpm dlx everything-cursor install

# 如果你想全局安装命令（之后直接输入 everything-cursor 即可）
npm install -g everything-cursor
# 或
pnpm add -g everything-cursor
# 然后运行
everything-cursor install

流程和 Deno 版本完全一致。

3.2 安装后的目录结构解析

安装完成后，去你选择的目录下看看。以全局安装（ ~/.cursor/ ）为例，结构如下：

~/.cursor/
├── agents/
│   ├── planner.md          # 项目规划智能体，擅长拆解复杂任务
│   ├── reviewer.md         # 代码审查智能体，专注于发现代码问题
│   └── ...                 # 其他智能体
├── skills/
│   ├── tdd-workflow/
│   │   ├── README.md       # TDD 技能描述
│   │   └── skill.md        # 技能实现细节
│   ├── react-specialist/
│   └── ...                 # 其他技能
├── commands/
│   ├── tdd.md             # 触发 TDD 工作流的快捷命令
│   ├── refactor.md
│   └── ...                # 其他自定义命令
└── rules/
    ├── security.md        # 安全编码规则
    ├── clean-code.md      # 整洁代码规则
    └── ...                # 其他规则

每个目录的作用：

• agents/ ：这里定义了不同的“AI 角色”。每个 .md 文件描述了一个智能体的系统提示词（System Prompt）、能力和边界。例如， planner.md 里的智能体会更倾向于先写设计文档，再写代码。
• skills/ ：这是更细粒度的能力单元。一个技能通常对应一个具体的工作流，比如 tdd-workflow 会指导 AI 先写测试用例，再实现功能，最后运行测试。技能可以被不同的智能体调用。
• commands/ ：自定义命令。在 Cursor 中按 Cmd/Ctrl + K 输入命令时，这里定义的命令会出现。例如，输入 tdd 可能会触发一个交互，让你选择要测试的文件，然后自动启动 TDD 技能。
• rules/ ：项目级的约束和规范。这些文件中的内容会作为背景知识（Context）提供给 AI，确保它生成的代码符合你的要求，比如“禁止使用 var ”、“SQL 查询必须参数化”等。

3.3 在 Cursor 中验证与使用

安装完成后， 你需要完全关闭 Cursor 并重新启动 。这是为了确保 Cursor 能重新扫描并加载新的配置文件。

重启后，打开任何一个项目（如果是全局安装）或对应的项目（如果是本地安装），尝试以下操作来验证是否生效：

1. 检查智能体 ：在 Cursor 的聊天界面，你应该能看到可选的智能体（Agent）列表增加了，比如除了默认的“Cursor”，可能还有“Planner”、“Reviewer”等。
2. 使用自定义命令 ：在编辑器内按 Cmd/Ctrl + K ，然后输入 tdd 或 refactor 等，看看是否有对应的自定义命令提示。
3. 观察代码建议 ：尝试让 AI 生成一些代码。如果你安装了 rules/clean-code.md ，你可能会发现 AI 生成的代码会更倾向于使用 const 和 let ，函数命名也更规范。

4. 高级用法：自定义、更新与问题排查

安装只是第一步，让它真正为你所用，还需要一些定制和维护。

4.1 安全地添加自定义配置

这是 everything-cursor 设计得非常人性化的一点： 它永远不会删除你自己创建的文件 。你可以放心地在 .cursor/ 目录的任何子文件夹中添加你自己的 .md 文件。

例如，我想为我的团队增加一条特殊的 React Hooks 规则：

# 如果安装在项目本地
echo -e '# React Hooks Rules\n- Always use exhaustive-deps rule for useEffect/useMemo/useCallback.\n- Prefer custom hooks over repeated logic in components.' > .cursor/rules/react-hooks.md

# 如果安装在全局
echo -e '# React Hooks Rules\n- Always use exhaustive-deps rule for useEffect/useMemo/useCallback.\n- Prefer custom hooks over repeated logic in components.' > ~/.cursor/rules/react-hooks.md

现在，当你在这个项目（或所有项目）中使用 Cursor 时，AI 在编写 React 组件时会自动参考这条新规则。

文件管理规则总结：

文件类型	是否被 everything-cursor 管理	说明
来自子模块的 .md 文件	✅ 是	安装、更新、卸载时会同步。
用户自创的 .md 文件	❌ 否	绝对安全 ，脚本会忽略它们。
任何非 .md 文件	❌ 否	完全忽略。

4.2 更新到最新版本

当 everything-claude-code 子模块增加了新的技能或修复了现有配置时，你可以更新 everything-cursor 来获取这些改进。

更新操作非常简单，就是重新安装：

# Deno
deno run -A jsr:@yoshixmk/everything-cursor/cli install

# npm (npx)
npx everything-cursor install

# 如果全局安装了 CLI
everything-cursor install

脚本内置了 智能更新检测 。它会检查当前安装的版本号。如果你运行的版本和已安装的版本一致，它会直接提示“Already up to date”并跳过，避免不必要的文件操作。只有当检测到新版本时，才会执行复制更新。

4.3 卸载与清理

如果你不再需要这套配置，或者想换用其他配置，卸载同样简单：

# Deno
deno run -A jsr:@yoshixmk/everything-cursor/cli uninstall

# npm (npx)
npx everything-cursor uninstall

# 全局 CLI
everything-cursor uninstall

重要提示 ：卸载操作 只会删除当初由 everything-cursor 安装的那些文件 （即 file-list.json 中记录的文件）。你在期间自己创建的所有自定义 .md 文件都会被完整保留，完全无需担心数据丢失。

4.4 常见问题与排查技巧

在实际使用中，你可能会遇到一些小问题。这里记录一些我踩过的坑和解决方法：

问题1：安装后，Cursor 里看不到新的智能体或命令。

• 排查步骤 ：
  1. 重启 Cursor ：这是最关键的一步，Cursor 只在启动时加载配置。
  2. 检查安装路径 ：确认你安装到了正确的目录。如果你为项目 A 安装了本地配置，但在项目 B 中打开，自然是看不到的。
  3. 检查目录权限 ：确保 Cursor 有权限读取 ~/.cursor/ 或 ./.cursor/ 目录。
  4. 查看 Cursor 日志 ：在 Cursor 中，通过 Help -> Toggle Developer Tools 打开开发者工具，查看 Console 选项卡是否有加载配置时的错误信息。

问题2：自定义命令（如 tdd ）执行没反应或报错。

• 可能原因 ：命令文件（ .md ）的格式不符合 Cursor 的解析要求。
• 排查步骤 ：
  1. 打开对应的命令文件，例如 ~/.cursor/commands/tdd.md 。
  2. 检查其内容结构。一个典型的 Cursor 命令文件通常以特定的元数据开头，例如：

     ---
     name: tdd
     description: Start a Test-Driven Development workflow
     ---
     # 这里是命令的具体提示词和步骤...
     

  3. 确保没有语法错误，并且描述清晰。你可以参考其他能正常工作的命令文件格式。

问题3：我想修改某个默认的技能（比如 skills/tdd-workflow/skill.md ），但又怕下次更新被覆盖。

• 最佳实践 ：不要直接修改 everything-cursor 安装的文件。相反，采用“覆盖”或“扩展”的方式。
  • 方法A（覆盖） ：在相同的相对路径下创建你自己的文件。例如，在 ~/.cursor/skills/tdd-workflow/skill.md 的同级目录，Cursor 可能会优先加载用户目录下的文件（取决于加载顺序）。但这种方式不够优雅。
  • 方法B（扩展-推荐） ：创建你自己的技能或规则文件，在其中引用或继承默认行为，并添加你的定制逻辑。例如，创建一个 ~/.cursor/rules/my-tdd-enhancements.md ，在里面详细说明你团队特定的测试规范。这样，默认技能和你的定制规则会共同作用于 AI。

问题4：安装脚本执行失败，提示权限错误（Permission Denied）。

• 原因 ：脚本需要向 ~/.cursor/ 或 ./.cursor/ 目录写入文件。
• 解决 ：
  • 如果是全局安装，确保你对 ~/.cursor/ 目录有写权限。
  • 如果是本地安装，确保你在项目根目录有写权限。
  • 在极少数情况下，可能是包管理器的问题。尝试使用 sudo （不推荐，可能引发其他权限问题）或换用 Deno 的一次性执行命令。

5. 开发者视角：参与贡献与构建自己的配置集

如果你不满足于使用，还想贡献或者基于此模式构建自己的配置分发包，那么了解其开发流程就很有必要。

5.1 从源码运行与测试

首先，你需要克隆仓库并初始化子模块：

git clone --recursive https://github.com/yoshixmk/everything-cursor.git
cd everything-cursor
# 如果已经克隆但未拉取子模块
git submodule update --init

然后安装依赖（这是一个 Node.js 项目，虽然 CLI 用 Deno 写，但构建脚本用 Node）：

npm install
# 或 pnpm install

项目提供了便捷的开发和测试脚本，定义在 package.json 的 scripts 里：

• npm run dev:install ：使用本地源码进行安装（通常链接到 ./.cursor 用于测试）。
• npm run dev:uninstall ：卸载本地测试安装。
• npm run build ：执行构建流程，核心是运行 scripts/generate-file-list.mjs 来生成 file-list.json 。

关键构建脚本解析 ： scripts/generate-file-list.mjs 这个文件是枢纽。它遍历 everything-claude-code 子模块目录，筛选出 agents/ , skills/ , commands/ , rules/ 这四个目录下的所有 .md 文件，将它们的相对路径记录到 file-list.json 。这个 JSON 文件随后会被 cli.ts 读取，作为“需要安装的文件清单”。任何对子模块内容的更新，都必须重新运行此脚本以更新清单。

5.2 发布新版本流程（维护者）

如果你是项目的维护者，或者 fork 后想发布自己的版本，流程如下：

1. 更新子模块 ：进入 everything-claude-code 目录，拉取上游最新更改，或提交你自己的更改后，在主项目根目录执行 git submodule update --remote 。
2. 更新版本号 ：手动修改 jsr.json 、 package.json 和 mod.ts 中的版本号字段（如从 "0.0.8" 改为 "0.0.9" ）。
3. 重新生成文件清单 ：运行 npm run build 或直接 node scripts/generate-file-list.mjs ，确保 file-list.json 反映最新的文件结构。
4. 提交更改 ：将版本号文件和更新后的 file-list.json 以及子模块指针一起提交。

   git add jsr.json package.json mod.ts file-list.json everything-claude-code
   git commit -m “Bump version to 0.0.9”
   

5. 发布到 JSR (Deno Registry) ：运行 npx jsr publish 。这会根据 jsr.json 的配置，将包发布到 JSR，供用户通过 deno run jsr:@your-scope/your-package 使用。
6. 发布到 npm ：运行 npm publish 。这将发布到 npm 仓库，供 Node.js 用户通过 npx 或 npm install 使用。

整个流程确保了 Deno 和 Node.js 用户都能获取到一致的内容。

5.3 设计自己的“Everything-*”工具

everything-cursor 的模式可以被复制。假设你为另一个支持类似配置的 AI 工具（比如 Windsurf 或 Zed with AI）创建配置集，你可以遵循同样的架构：

1. 一个核心配置仓库（作为子模块）。
2. 一个包装仓库，包含：
   • 一个 CLI 工具，用于复制文件。
   • 一个构建脚本，生成文件清单。
   • 多运行时支持（JSR + npm）。
   • 安全的安装/卸载逻辑，保护用户文件。 这种模式清晰、可维护，并且对用户友好。

回过头看， everything-cursor 的成功在于它精准地捕捉到了一个需求： 为强大的 AI 编程工具提供高质量、可共享的“预设” 。它降低了高级功能的使用门槛，促进了最佳实践的传播。通过理解其原理并掌握自定义方法，你不仅能成为一个高效的使用者，还能将它融入团队流程，甚至创造出适合自己的配置生态。