# 读懂 · 索引、@ 引用与非代码资料 · Cursor · 一台元工具 **作者** Aklman · **章节** 05 / 11 · **首发** 2026.07 · **语言** 中文为主, 中英双语 **原文** https://library.aklman.com/books/cursor/05-context **全书 markdown** https://library.aklman.com/books/cursor/llms.md **上一章** https://library.aklman.com/books/cursor/04-terminal/llms.md **下一章** https://library.aklman.com/books/cursor/06-rules/llms.md > 本章来自 Aklman · Library, 完整免费阅读。允许 AI 摘读、引用、问答; 转载请保留作者署名与原文链接 (CC BY-NC-ND 4.0, https://library.aklman.com/license)。 --- > agent 聪明不聪明，一半看模型，一半看它读到了什么。Cursor 把你整个项目切成向量索引，能按意思搜，不只按文件名；@ 让你把某个文件、文件夹、一份文档、甚至一段网页精确喂给它。它读的不必是代码 —— 一个装满笔记的文件夹、一批 CSV、一份手册都行。这一章讲怎么喂得准，以及索引上云那条隐私线。 agent 聪明不聪明，一半看模型，一半看它读到了什么。Cursor 把你整个项目切成向量索引，能按意思搜，不只按文件名；@ 让你把某个文件、文件夹、一份文档、甚至一段网页精确喂给它。 它读的不必是代码 —— 一个装满笔记的文件夹、一批 CSV、一份手册都行。这一章讲两件事：索引怎么让它「读懂」你的项目，以及你怎么用 @ 喂得准、连非代码资料也喂进去。喂对了上下文，前面那台 agent 才真的有的放矢。 ### I · 索引让它按意思找，不按文件名 语义索引是 Cursor 拉开差距的护城河，不是它的 UI。 打开工作区，Cursor 就自动把代码切成块、转成向量嵌入，存进向量库，之后约每 5 分钟增量同步、只处理变过的部分；大仓库要等索引到 ~80% 语义搜索才可用。[^1][^4]好处是它能按意思找：你问「我们在哪儿处理鉴权」，它能定位到相关文件，哪怕那段代码里根本没出现「鉴权」这个词。语义搜索叠加传统的 grep，比单用 grep 答得更准 —— Cursor 自家评测给的数字是准 12.5%。[^4] 这就是为什么同一个模型，在 Cursor 里比在一个干聊天框里更有用 —— 不是模型更强，是它读过你整个项目。底座层的补全谁都有，这层「它认识你的代码库」才是你为它付钱的核心理由之一。 --- ### II · @ 是你精确喂料的手 索引让它能找，@ 让你确保它找对。 与其写一长段背景，不如 @ 准那两样东西。常用的几个：[^2] - **@Files & Folders**: 把指定文件或整个文件夹塞进上下文 —— 最常用，比让它去索引里猜更稳。 - **@Docs**: 搜索已索引的文档，包括你自己加的 —— 能读非代码资料。 - **@Terminals**: 把终端输出当上下文 —— 让它就着报错接着改。 - **@Commit / @Branch**: 把未提交改动或整条分支相对 main 的 diff 给它 —— review、写 commit message 都用得上。 - **@Browser**: 把内置浏览器里的内容附进来 —— 读网页、文档站。 边界：@ 得太多是噪声，张口就 @ 整个代码库更是 —— 那等于让它做一次全库语义搜索，又贵又容易跑偏。先 @ 准那一两个文件，不够再放宽；把最相关的三五样给它，不是把半个项目都贴进去。喂料的本事不是「喂得多」，是「喂得准」。 | 你手里有什么 | 先用 | 不要一上来用 | |---|---|---| | 明确文件 / 组件 / 章节 | @file | @codebase | | 一组同目录资料 | @folder | 整仓检索 | | 外部文档站或团队手册 | @Docs | 复制一大段网页 | | 报错、测试输出、日志 | @Terminals | 口述报错 | | 当前改动需要 review | @Commit / @Branch | 让它猜你改了什么 | | 不确定相关文件 | 先让 Agent search，再要求列来源 | 一次塞半个项目 | --- ### III · 它读的不必是代码 把一个装满资料的文件夹当项目打开，索引和 @ 照样工作 —— 这是它干非编码活的上料口。 指向一个装满笔记的文件夹、一批 CSV、一份手册，@Docs 还能索引外部文档站；agent 就能按意思在你的资料里检索、回答、产出。调研、整理、写作这类活之所以能在 Cursor 里做，正是因为它对待你的资料和对待代码是同一套机制：建索引、按意思找、@ 精确取。 _非代码项目资料结构模板_ ```text ```text project/ AGENTS.md # 口吻、引用、文件命名、禁止事项 docs/ specs/ # 任务说明、产品需求、章节大纲 decisions/ # 已做决策，按日期命名 research/ sources/ # 原始来源摘录，只放可追溯材料 notes/ # agent 生成或你整理的中间笔记 data/ raw/ # 原始数据，只读 working/ # dry-run / 中间产物 output/ # 可交付结果 prompts/ templates.md # 复用 PromptBox / 工作流 ``` ``` **提示词 · Cursor Agent** ```text 先读资料，再行动： - 先阅读 @<资料文件或文件夹> - 输出一份资料地图：关键文件、每个文件讲什么、缺口是什么 - 在我确认前，不要改文件 - 确认后只改 <目标路径> - 每条事实保留来源文件路径。 ``` **示例** ```text 先读资料，再行动： - 先阅读 @research/sources 和 @docs/specs/cursor-outline.md - 输出一份资料地图：关键文件、每个文件讲什么、缺口是什么 - 在我确认前，不要改文件 - 确认后只改 content/books/cursor/chapters/05-context.mdx - 每条事实保留来源文件路径。 ``` 隐私这条线要讲清：官方口径是「Cloud Agents 是唯一需要 Cursor 存储代码的功能」—— 索引流程存的是向量嵌入和加密后的路径，不需要长期存你的源码。[^5][^4]但索引确实上云 —— 真正敏感的仓库或资料，自己掂量，用 .cursorignore 把不想上传的圈掉；它挡索引，也挡 agent 对这些文件的访问，但护栏不是保险箱：真正的密钥别只靠它，放进环境变量或密钥管理。[^3]能被它读懂的资料，才用得上它的脑子；但不是所有资料都该交给它读。 > 想知道它到底读了什么，去 Cursor Settings > Indexing & Docs 看 included files；该排除的（密钥、私有数据、超大产物）写进 .cursorignore。大仓库索引慢，就用它把生成物、依赖、lockfile 排掉 —— 索引小了、答得也准。 - 答案像在猜：先 @ 准文件，不要继续追问同一个模糊问题。 - 找不到新文件：检查索引状态，必要时 Reindex。 - 索引很慢：把生成物、依赖、二进制、大 CSV 写进 .cursorignore。 - 引用来源混乱：要求它列出使用过的文件路径和行号，再继续执行。 - 涉及敏感资料：先决定是否该进 Cursor；不是所有可读材料都该被索引。 拿一份非代码资料试它的上下文： - 把一个非代码文件夹（调研笔记 / 一份手册 / 一批数据）当项目打开，让它建索引。 - 问一个「按意思」的问题，看它能否找到没出现关键词的那段。 - 用 @ 精确指一份文件纠正它一次，对比前后回答。 - 去 Settings 确认索引范围，把不该上传的写进 .cursorignore。 > 模型决定它多聪明， > 上下文决定它多有用 ## 引用与参考 01 · Cursor Docs · Codebase Indexing —— 打开项目即自动扫描建索引，约每 5 分钟周期同步；状态栏看进度，命令面板可 Reindex；大仓库把生成物、依赖写进 .cursorignore 提速。截至 2026-07-10。 (Cursor Docs · Codebase Indexing) 02 · Cursor Docs · @ Symbols —— 用 @ 精确引用上下文：@Files & Folders、@Docs（含自建文档，可读非代码）、@Terminals（终端输出）、@Past Chats、@Commit / @Branch（git diff）、@Browser（内置浏览器内容）。截至 2026-07-10。 (Cursor Docs · @ Symbols) 03 · Cursor Docs · Agent Security —— .cursorignore 用来挡 agent 对指定文件的访问；读文件与搜代码不需审批，会暴露敏感数据的动作需要明确批准。真正的密钥应放环境变量 / 密钥管理，不该只靠 ignore 文件。截至 2026-07-10。 (Cursor Docs · Agent Security) 04 · Cursor Blog · Securely indexing large codebases（2026-01-27）—— 索引把代码切块转成向量嵌入；大仓库要等索引完成至少 80% 语义搜索才可用；用 Merkle 树只同步变过的部分；路径以加密形式存储；Cursor 自家评测称语义搜索叠加 grep 比单用 grep 答代码库问题准 12.5%。 (Cursor Blog · Secure indexing) 05 · Cursor Docs · Privacy & Data Governance —— 官方口径：「Cloud Agents 是唯一需要 Cursor 存储代码的功能」—— 索引流程与 LLM 请求都不需要长期存你的代码；企业档还有 CMEK（用你自己的密钥加密嵌入）。截至 2026-07-10。 (Cursor Docs · Privacy) --- *读懂 · 索引、@ 引用与非代码资料 · Cursor · 一台元工具 · Aklman 著 · CC BY-NC-ND 4.0 · https://library.aklman.com/books/cursor/05-context*