前言

在现代 AI 辅助开发工具中，Cursor 因其强大的智能能力和深度文件系统集成，已成为开发者的主力 IDE。其核心特性之一——@ 符号系统，让开发者能够在 AI 对话中结构化地注入上下文，显著提升回答的精准度和效率。本文将系统介绍 @ 符号的完整使用方法，通过实战示例帮助你从基础使用到高级应用全面掌握这一强大工具。

一、@ 符号系统总览

Cursor 的 @ 符号是一套智能上下文引用机制，通过不同前缀让 AI 理解你需要引用的内容类型，从而实现更精准的交互。

核心功能对比表

符号类型	主要功能	使用场景	优势特点
@Files	引用整个文件内容	需要 AI 理解文件的完整逻辑	支持路径预览、分块处理
@Folders	引用文件夹结构及内容概览	需要提供项目结构或批量文件上下文	避免上下文爆炸，智能摘要
@Code	引用特定代码片段	专注分析局部逻辑而非整个文件	节省上下文空间，精准聚焦
@Codebase	搜索代码库相关文件并重新排序	在整个项目中查找相关代码	智能相关性排序
@Git	引用 Git 提交、差异等信息	代码变更分析、问题追溯	结合版本历史分析
@Web	搜索网络信息作为上下文	获取最新技术资讯或外部资源	实时信息补充
@Docs	引用官方或自定义文档	框架使用、API 参考、知识库查询	支持自定义文档添加
@Definitions	引用附近的所有定义	分析变量、函数等定义上下文	局部上下文增强
@Chat	引用历史聊天记录	延续之前对话的上下文	对话连贯性保持

二、基础操作指南

2.1 激活与导航

• 激活方式：在多种 AI 交互场景中均可快速激活快捷导航功能，包括但不限于：

  • 通过快捷键调出 ⌘K 命令面板时
  • 在常规聊天窗口输入内容时
  • 在终端界面进行操作时
    只需简单输入 @ 符号即可立即激活快捷导航菜单

• 导航操作：提供直观的键盘操作方式：

  • 使用 ↑ 方向键向上浏览选项列表
  • 使用 ↓ 方向键向下浏览选项列表
  • 当光标停留在目标选项时，按 Enter 键确认选择
    这种设计让用户无需鼠标即可快速完成操作

• 层级导航：采用智能的分层筛选机制：

  1. 首先选择大类类别（如 @Files 文件类）
  2. 系统会自动显示该类别下的子选项
  3. 可继续输入关键词进行二级过滤
  4. 最终定位到具体的资源对象
     这种层级设计特别适合管理大量资源的场景

• 视觉反馈：操作过程中会实时显示：

  • 当前所在层级
  • 可用选项列表
  • 已输入的过滤条件
    确保用户随时掌握导航状态

• 应用场景示例：

  • 快速定位项目文件：@Files → 输入"report" → 选择季度报告.docx
  • 调用特定功能：@Commands → 输入"export" → 选择导出为PDF
  • 切换工作环境：@Environments → 选择测试服务器

2.2 文件读取策略

• 完整读取：默认模式，引用文件全部内容
• 摘要读取：按 Ctrl/⌘ + M 切换，仅提取关键部分
• 适用场景：大文件时使用摘要模式节省上下文空间

三、实战示例详解

示例1：代码生成 - 用户登录功能

场景：需要基于现有用户模型和 JWT 文档生成安全的鉴权逻辑

指令：生成用户登录功能 @Files src/models/user.js @Docs https://jwt.io/introduction

操作步骤：

1. 输入 @Files，选择 src/models/user.js
2. 输入 @Docs，添加 JWT 官方文档链接
3. 输入需求描述
4. AI 将结合用户模型结构和 JWT 最佳实践生成代码

生成结果示例：

// 基于用户模型和 JWT 文档生成的登录逻辑
import jwt from 'jsonwebtoken';
import User from './models/user.js';

export async function loginUser(email, password) {
  const user = await User.findOne({ email });
  if (!user || !(await user.comparePassword(password))) {
    throw new Error('认证失败');
  }
  
  // 使用 JWT 最佳实践生成 token
  const token = jwt.sign(
    { userId: user._id, email: user.email },
    process.env.JWT_SECRET,
    { expiresIn: '24h', algorithm: 'HS256' }
  );
  
  return { token, user: { id: user._id, email: user.email } };
}

示例2：错误排查 - 结合代码与版本历史

场景：分析特定代码段报错，结合最近提交历史

指令：解释此报错原因 @Code 12-25 行 @Git HEAD~1

操作流程：

1. 高亮选中代码第 12-25 行
2. 点击浮窗中的 “@Code snippet” 引用
3. 输入 @Git HEAD~1 引用最近一次提交
4. AI 分析代码变更与错误关联

分析结果：

发现最近提交中修改了 API 响应格式，
第 18 行仍使用旧格式解析数据。
建议更新为：const data = response.data.result;

示例3：跨文件重构 - 类组件转函数组件

场景：批量转换组件并确保全局兼容性

指令：将类组件改为函数式组件 @Folders src/components @Codebase

操作策略：

1. @Folders src/components 提供组件目录结构
2. @Codebase 搜索相关样式和状态管理文件
3. AI 分析依赖关系后生成转换方案

重构建议：

// 转换前：类组件
class UserProfile extends React.Component {
  state = { user: null };
  
  componentDidMount() {
    this.fetchUser();
  }
  
  // ... 其他方法
}

// 转换后：函数组件
function UserProfile({ userId }) {
  const [user, setUser] = useState(null);
  const { theme } = useContext(ThemeContext); // 从 @Codebase 识别的上下文
  
  useEffect(() => {
    fetchUser(userId).then(setUser);
  }, [userId]);
  
  // 保持与全局样式的兼容性
  return <div className={`profile ${theme}`}>...</div>;
}

示例4：文件优化 - AI 优化某个配置文件

场景：在持续集成/持续交付(CI/CD)流程中，当需要频繁构建和部署应用时，构建速度的优化尤为重要。特别是在处理大型项目或多个微服务时，配置文件的加载和处理往往会成为性能瓶颈。通过@Files指令引用整个配置文件，可以显著减少I/O操作和解析时间。

指令：请帮我优化构建速度 @supply_config.yaml

操作策略：

示例5：文件层级导航 - AI 导航出文件所有层级及结构

场景：@Folders 是一个智能目录索引功能，它的核心作用是向 AI 清晰地展示项目的文件系统结构。不同于简单的文件遍历，它会智能地：

1. 展示关键目录层级关系（通常保留 3-4 级深度）
2. 标记特殊文件类型（如 __init__.py, .env 等配置文件）
3. 自动忽略常见非代码文件（如 node_modules/, *.log）
4. 对大型目录进行智能摘要（如当子文件超过 50 个时显示分类统计）

这个功能通过元数据注入的方式，既避免了直接将所有文件内容注入上下文导致的 token 浪费，又能让 AI 准确理解：

• 项目模块划分
• 核心代码分布
• 配置文件位置
• 测试文件结构

典型应用场景：

• 新成员快速了解项目架构
• 定位特定功能模块
• 分析代码组织合理性
• 检查配置文件完整性

操作策略详解：

1. 在 Cursor 的命令面板输入 @目录/ 后：

   • 会弹出可视化目录树
   • 支持键盘方向键导航
   • 按回车确认选择

2. 路径深入技巧：

   # 查看 src/components/ 下的所有 Vue 组件
   @目录/src/components/
   
   # 检查 config/ 目录下的所有配置文件
   @目录/config/
   

3. 实用示例：

   • 分析工具函数集：

     # 查看 utils 目录下的功能分类
     @目录/utils/
     # 输出示例：
     # ├── date_utils.js (日期处理)
     # ├── string_utils.js (字符串处理)
     # └── validation.js (表单验证)
     

   • 检查测试覆盖率：

     # 快速查看测试文件分布
     @目录/tests/
     # 输出示例：
     # ├── unit/ (单元测试)
     # │   ├── utils.test.js
     # │   └── api.test.js
     # └── e2e/ (端到端测试)
     #     └── login.spec.js
     

4. 高级技巧：

   • 组合使用文件过滤：

     # 只看 Python 文件
     @目录/models/*.py
     

   • 跨目录比较：

     # 对比两个版本的组件差异
     @目录/src/v1/components/
     @目录/src/v2/components/
     

示例6：@Docs-与官方文档联动

场景详解：@Docs 是 Cursor 编辑器内置的智能文档检索功能，它完美融合了AI智能与专业文档参考，相当于为开发者提供了"StackOverflow即时解答+官方手册精准引用+AI智能分析"的三重优势。这个功能特别适合需要结合具体技术文档来解决编码问题的场景。

详细操作指南：

一、使用内置文档资源

1. 在代码注释或问题描述后输入@Docs指令
2. 系统会弹出包含20+主流技术栈的文档列表，包括：
   • 前端框架：React(18.2)、Vue(3.3)、Angular(16)
   • 后端技术：Node.js(20)、Spring Boot(3.1)
   • 云原生：Kubernetes(1.28)、Docker
   • 数据科学：PyTorch(2.1)、TensorFlow
   • CSS框架：TailwindCSS(3.3)、Bootstrap(5.3)
3. 示例深度应用：

# 我需要实现React组件的懒加载，但遇到hydration不匹配问题 @Docs(React)
请具体说明：
1. 如何正确使用React.lazy
2. 解决SSR hydration错误的三种方案
3. 性能优化建议

二、自定义文档集成
对于未收录的文档资源，可通过以下步骤添加：

1. 输入@Docs后选择"Add new doc"
2. 支持添加的文档类型包括：
   • 企业内网资源：Confluence wiki、内部API文档(GitBook格式)
   • 私有文档：公司组件库文档、微服务接口规范
   • 第三方资源：付费SDK文档、合作伙伴API文档
3. 文档抓取特性：
   • 自动爬取整站结构，保留层级关系
   • 支持Basic Auth认证的私有文档
   • 每日自动同步更新内容
4. 典型应用案例：

# 调用新的风控模型服务时出现403错误 @Docs(风控系统APIv2.5)
"""
服务端返回：
{'code': 'PERMISSION_DENIED', 'message': 'Missing scopes'}
请检查：
1. 必需的OAuth scope列表
2. 正确的请求头设置方式
3. 测试环境与生产环境的差异
"""

高级技巧：

1. 组合查询：可以同时引用多个文档源

@Docs(React, Next.js) 如何在App Router中实现高级路由守卫？

2. 版本指定：对于有多个版本的文档

@Docs(Python 3.11) 类型注解系统的新特性

3. 上下文关联：AI会自动结合文档内容和当前项目上下文给出建议

示例7：@Summarize-上下文精简与系统自动管理

场景：当引用较大文件夹或文件时（如包含数十个代码文件的项目目录或多达数万字的文档），Cursor 会自动进行智能内容压缩与概要抽取，通过以下方式确保不会超过模型的上下文限制：

1. 分层压缩：优先保留顶层目录结构和核心文件，对次要文件进行摘要处理
2. 智能过滤：自动识别并保留关键代码段、类定义和函数声明
3. 依赖关系保留：特别维护文件间的import/require关系

典型应用场景：

• 分析大型代码仓库时（如包含100+文件的React项目）
• 处理长篇技术文档时（如300页的API参考手册）
• 调试复杂项目时需保持完整调用链

操作指南：
你可以通过以下方式主动优化上下文：

1. 使用内置命令：

指令：@Summarize  请总结当前上下文并保留关键依赖关系

2. 进阶选项（支持参数化）：

指令：@Summarize --depth=2 --focus=utils/  # 指定总结深度和重点关注目录

3. 查看压缩报告：

指令：@Summarize --show-report  # 显示被压缩内容的摘要信息

注意事项：

• 压缩过程会保留所有关键业务逻辑
• 被压缩内容可通过"@Expand filename"指令随时恢复
• 建议在分析完成后使用"@Restore-all"恢复完整上下文

示例8：@Code：引用精确的代码片段

场景：@Code 的作用是告诉 AI 你所关注的具体代码段。它不会注入整个文件内容（避免上下文爆炸），但会提供精确的代码片段让 AI 针对性分析。

指令：这个 @Code 片段的代码是否可以优化

操作策略：
方式一：高亮选中代码 → 点击浮窗 “引用代码段”
方式二：对话框中输入 @Code 选择历史代码段
例：

四、高级使用技巧

4.1 组合指令策略

# 组合文件引用与代码库搜索
@Files src/utils/helper.js @Codebase

# 多文档引用
@Docs(React) @Docs(ReactRouter) @Files src/routes.js

4.2 动态资源集成

• 粘贴 @ 开头的链接自动解析
• 示例：@https://api.example.com/docs
• Cursor 自动抓取内容并纳入上下文

4.3 隐私与配置管理

# .cursorignore 文件示例
.env*
*.log
secret/
config/private/

# 自定义文档添加
Settings > Features > Docs > Add Document
URL: https://internal.company.com/docs

五、实战工作流模板

5.1 新功能开发工作流

1. 需求分析：@Docs(框架文档) @Files 类似功能文件
2. 代码生成：@Codebase 搜索相关模式 @Folders 目标目录
3. 测试验证：@Git 查看测试文件模式

5.2 Bug 修复工作流

1. 错误定位：@Code 相关代码段 @Git 近期提交
2. 原因分析：@Web 搜索类似问题 @Docs 官方文档
3. 解决方案：@Files 依赖文件 @Codebase 查找修复模式

5.3 代码审查工作流

1. 变更查看：@Git 差异对比
2. 影响分析：@Codebase 搜索调用关系
3. 建议生成：@Docs 最佳实践 @Files 相关测试文件

六、性能优化策略

6.1 上下文管理技巧

场景	推荐策略	理由
大项目分析	@Folders + 摘要模式	避免上下文超限
具体问题	@Code + @Files 特定文件	精准聚焦
框架使用	@Docs + @Code 示例	结合理论与实操

6.2 自动摘要使用

# 让 Cursor 主动优化上下文
@Summarize 请提取当前上下文的依赖关系和关键接口

七、常见问题与解决方案

Q1: @ 符号没有弹出菜单？

• 检查是否在支持的区域输入（聊天窗口、命令面板）
• 确认项目已正确加载
• 重启 Cursor 或重新打开项目

Q2: 引用的文件内容不完整？

• 检查文件大小，过大文件自动摘要
• 使用 Ctrl/⌘ + M 切换读取模式
• 确认文件未被 .cursorignore 排除

Q3: 自定义文档未生效？

• 确认文档网站允许爬取
• 检查网络连接
• 重新添加文档并等待索引完成

八、总结与最佳实践

8.1 核心价值总结

Cursor 的 @ 符号系统通过结构化上下文引用，实现了：

• 精准性：让 AI 基于具体代码和文档回答
• 效率：减少来回沟通，一次性提供完整上下文
• 一致性：确保建议与项目现有模式匹配

8.2 使用频率建议表

功能	推荐频率	使用时机
@Files	★★★★★	每次涉及具体文件时
@Code	★★★★☆	分析特定代码段时
@Docs	★★★★☆	使用新框架或 API 时
@Folders	★★★☆☆	项目结构分析时
@Git	★★★☆☆	Bug 追踪和变更分析
组合使用	★★★★★	复杂任务时必用

8.3 进阶学习路径

1. 初级阶段：掌握 @Files、@Code 基础引用
2. 中级阶段：学习组合使用和 @Docs 自定义
3. 高级阶段：熟练运用 @Git、@Codebase 进行深度分析
4. 专家阶段：创建个性化工作流和自动化脚本

8.4 实战总结：高效组合使用 @ 符号

通过一个 API 请求模块的重构示例，展示了如何在实际开发中高效组合使用 @ 符号，实现对项目的深度分析、上下文提取与精准优化。

核心场景
重构项目 API 层，目标是优化请求逻辑中的重试与错误处理机制。

关键操作流程

定位目录：使用 @Folders 引用 src/api，了解整体结构。

浏览内容：输入 / 查看目录内文件列表。

选取文件：通过 @Files 对关键文件 request.ts 进行具体分析。

聚焦代码段：使用 @Code 提取需要优化的核心逻辑。

对照文档：借助 @Docs 引入 Axios 官方文档，确保优化方案符合最佳实践。

示例提示词

我想重构 API 层。这里是目录结构 @src/api。
具体的请求逻辑在 @request.ts。
下面这段代码是我需要优化的部分 @Code。
请结合 @Docs(Axios) 优化其重试和错误处理机制。

总结

Cursor 的 @ 符号不仅是功能引用工具，更是智能开发思维的体现。通过精准的上下文注入，你可以将 AI 从"通用助手"转变为"专属专家"，深度理解你的项目背景和技术栈。掌握本文介绍的技巧，特别是组合使用策略，将让你在代码生成、问题排查、重构优化等场景中获得数量级的效率提升。

记住：优秀的开发者不是知道所有答案，而是知道如何快速找到答案。Cursor 的 @ 符号系统正是这种能力的放大器。开始实践吧，从今天起，让你的每一次 AI 交互都更加精准、高效！