Cursor @ 引用怎么用：一句话结论
在 Cursor 里知道哪些文件相关就用 @ 精确指定上下文，不确定就干脆不用——Agent 会自己搜索找到相关文件。@ 引用是「精确注入」，不是「越多越好」，滥用反而稀释关键信息。
@ 引用能挂哪些上下文
根据 Cursor 官方文档，聊天输入框里输入 @ 会弹出匹配建议，可引用的对象包括：
- 文件和文件夹：
@auth.ts添加单个文件，@src/components/添加整个文件夹，选中文件夹后继续输入/可逐层深入浏览。 - 终端：
@Terminals把终端输出直接喂给智能体，报错场景下比复制粘贴更快。 - 历史会话：
@Chats引用之前对话的上下文，跨会话延续任务。 - Git diff：
@Commit附加未提交更改的 diff，@Branch附加整个分支与主分支的差异，代码审查场景的利器。 - 浏览器：
@Browser附加内置浏览器的页面上下文，调 UI 时直接给视觉证据。
可以连续输入 @ 附加多个条目，每个条目都会注入对话。
什么时候该用，什么时候别用
官方给了一条很实用的判断标准：当你知道哪些文件与任务相关时用 @；不确定哪些文件重要就跳过。这条标准背后是上下文管理的取舍：
- 明确知道要改某个组件和它的测试？@ 这两个文件，智能体不用再花轮次去搜。
- 需求模糊、只描述了现象？别乱 @ 一堆可能相关的文件，让 Agent 通过搜索自己定位，避免无关代码挤占注意力。
- 已读过 AI 编程上下文窗口管理的话会更好理解：@ 引用本质上是手动做上下文裁剪，和 /clear 、/compact 是同一层工具箱。
五步上手实操
按下面的流程跑一遍，基本就形成肌肉记忆了：
- 在聊天输入框输入 @，弹出候选列表。
- 继续输入文件名过滤，选中目标文件或文件夹；文件夹可输入 / 继续下钻。
- 需要终端报错就加 @Terminals，需要看改动就加 @Commit 或 @Branch 。
- 一次消息可叠加多个 @ 条目，按任务最小相关原则取舍。
- 发送后观察 Agent 是否围绕你指定的文件工作；若它频繁偏离，说明该补 @ 或该精简。
进阶：@Docs 与自定义模式
除了项目内的文件，@ 还能引用第三方文档：@Docs 可以选择 Cursor 预置索引的文档库，也可以粘贴 URL 添加自定义文档（爬取并定期重新索引），让模型基于官方文档回答框架 API 问题，减少幻觉。配合具体查询效果更好，例如 @Docs React hooks 最佳实践。
另一个值得知道的机制是自定义模式（Custom Modes）：输入 / 调用技能并按 Alt+Enter 回车，技能会在每一轮持续保持在上下文中，适合把团队手册、代码评审清单这类「工作方式」长期挂载，而不是只对一条消息生效。这与把团队约定写进规则文件的思路一致，细节可参考 Cursor Rules 配置实战。
常见误区
- 把整个 src 目录 @ 进来：文件夹引用会注入大量文件，噪声多于信号，尽量下钻到具体文件。
- 用 @ 代替描述：@ 只是挂上下文，任务目标仍要说清楚，「@auth.ts 修一下」远不如「@auth.ts 里 token 过期后没有刷新重试，加上重试逻辑」。
- 截图手动转文字：UI 和报错直接粘贴图片或用 @Browser/@Terminals，比手写描述更保真。
常见问题
@ 引用和自动代码库索引是什么关系？
一次消息最多能 @ 多少个文件？
@ 引用的文件后来被改了怎么办？
小结
@ 引用的定位是「你知道答案在哪时帮 Agent 省掉搜索成本」。把它当成精确制导，而不是火力覆盖，配合规则文件和索引搜索，上下文控制才完整。
评论 (0)