读懂 · 索引、@ 引用与非代码资料Read It All · Indexing, @-Mentions, and Non-Code Material.
agent 聪明不聪明，一半看模型，一半看它读到了什么。Cursor 把你整个项目切成向量索引，能按意思搜，不只按文件名；@ 让你把某个文件、文件夹、一份文档、甚至一段网页精确喂给它。它读的不必是代码 —— 一个装满笔记的文件夹、一批 CSV、一份手册都行。这一章讲怎么喂得准，以及索引上云那条隐私线。How smart the agent is depends half on the model and half on what it actually read. Cursor slices your whole project into a vector index you can search by meaning, not just by filename; @ lets you feed it a specific file, folder, doc, or even a web page. What it reads need not be code — a folder of notes, a batch of CSVs, a manual all work. How to feed it precisely, and the privacy line where the index goes to the cloud.
agent 聪明不聪明，一半看模型，一半看它读到了什么。Cursor 把你整个项目切成向量索引，能按意思搜，不只按文件名；@ 让你把某个文件、文件夹、一份文档、甚至一段网页精确喂给它。How smart the agent is depends half on the model and half on what it actually read. Cursor slices your whole project into a vector index you can search by meaning, not just by filename; @ lets you feed it a specific file, folder, doc, or even a web page.它读的不必是代码 —— 一个装满笔记的文件夹、一批 CSV、一份手册都行。这一章讲两件事：索引怎么让它「读懂」你的项目，以及你怎么用 @ 喂得准、连非代码资料也喂进去。喂对了上下文，前面那台 agent 才真的有的放矢。What it reads need not be code — a folder of notes, a batch of CSVs, a manual all work. This chapter covers two things: how the index lets it 'understand' your project, and how you use @ to feed it precisely, non-code material included. Feed the right context and the agent from earlier finally has something to aim at.
— I
索引让它按意思找，不按文件名The Index Lets It Search by Meaning.
语义索引是 Cursor 拉开差距的护城河，不是它的 UI。The semantic index is Cursor's moat, not its UI.打开工作区，Cursor 就自动把代码切成块、转成向量嵌入，存进向量库，之后约每 5 分钟增量同步、只处理变过的部分；大仓库要等索引到 ~80% 语义搜索才可用。1注 1Note 1Cursor Docs · Codebase Indexing —— 打开项目即自动扫描建索引，约每 5 分钟周期同步；状态栏看进度，命令面板可 Reindex；大仓库把生成物、依赖写进 .cursorignore 提速。截至 2026-07-10。Cursor Docs · Codebase Indexing — opening a project scans and indexes automatically, syncing roughly every five minutes; the status bar shows progress, and the command palette can Reindex; on large repos, speed it up by adding generated files and dependencies to .cursorignore. As of 2026-07-10.4注 4Note 4Cursor Blog · Securely indexing large codebases（2026-01-27）—— 索引把代码切块转成向量嵌入；大仓库要等索引完成至少 80% 语义搜索才可用；用 Merkle 树只同步变过的部分；路径以加密形式存储；Cursor 自家评测称语义搜索叠加 grep 比单用 grep 答代码库问题准 12.5%。Cursor Blog · Securely indexing large codebases (2026-01-27) — indexing chunks code into vector embeddings; on large repos semantic search isn't available until at least 80% of indexing is done; a Merkle tree syncs only what changed; paths are stored encrypted; Cursor's own evaluation says semantic search layered on grep answers codebase questions 12.5% more accurately than grep alone.好处是它能按意思找：你问「我们在哪儿处理鉴权」，它能定位到相关文件，哪怕那段代码里根本没出现「鉴权」这个词。语义搜索叠加传统的 grep，比单用 grep 答得更准 —— Cursor 自家评测给的数字是准 12.5%。4注 4Note 4Cursor Blog · Securely indexing large codebases（2026-01-27）—— 索引把代码切块转成向量嵌入；大仓库要等索引完成至少 80% 语义搜索才可用；用 Merkle 树只同步变过的部分；路径以加密形式存储；Cursor 自家评测称语义搜索叠加 grep 比单用 grep 答代码库问题准 12.5%。Cursor Blog · Securely indexing large codebases (2026-01-27) — indexing chunks code into vector embeddings; on large repos semantic search isn't available until at least 80% of indexing is done; a Merkle tree syncs only what changed; paths are stored encrypted; Cursor's own evaluation says semantic search layered on grep answers codebase questions 12.5% more accurately than grep alone.Open a workspace and Cursor auto-chunks the code into vector embeddings stored in a vector database, then syncs incrementally about every 5 minutes, processing only what changed; on a large repo, semantic search isn't available until indexing reaches ~80%.1注 1Note 1Cursor Docs · Codebase Indexing —— 打开项目即自动扫描建索引，约每 5 分钟周期同步；状态栏看进度，命令面板可 Reindex；大仓库把生成物、依赖写进 .cursorignore 提速。截至 2026-07-10。Cursor Docs · Codebase Indexing — opening a project scans and indexes automatically, syncing roughly every five minutes; the status bar shows progress, and the command palette can Reindex; on large repos, speed it up by adding generated files and dependencies to .cursorignore. As of 2026-07-10.4注 4Note 4Cursor Blog · Securely indexing large codebases（2026-01-27）—— 索引把代码切块转成向量嵌入；大仓库要等索引完成至少 80% 语义搜索才可用；用 Merkle 树只同步变过的部分；路径以加密形式存储；Cursor 自家评测称语义搜索叠加 grep 比单用 grep 答代码库问题准 12.5%。Cursor Blog · Securely indexing large codebases (2026-01-27) — indexing chunks code into vector embeddings; on large repos semantic search isn't available until at least 80% of indexing is done; a Merkle tree syncs only what changed; paths are stored encrypted; Cursor's own evaluation says semantic search layered on grep answers codebase questions 12.5% more accurately than grep alone. The payoff is search by meaning: ask 'where do we handle auth' and it locates the relevant files even when that word never appears in the code. Semantic search layered on traditional grep answers more accurately than grep alone — Cursor's own evaluation puts it at 12.5% more accurate.4注 4Note 4Cursor Blog · Securely indexing large codebases（2026-01-27）—— 索引把代码切块转成向量嵌入；大仓库要等索引完成至少 80% 语义搜索才可用；用 Merkle 树只同步变过的部分；路径以加密形式存储；Cursor 自家评测称语义搜索叠加 grep 比单用 grep 答代码库问题准 12.5%。Cursor Blog · Securely indexing large codebases (2026-01-27) — indexing chunks code into vector embeddings; on large repos semantic search isn't available until at least 80% of indexing is done; a Merkle tree syncs only what changed; paths are stored encrypted; Cursor's own evaluation says semantic search layered on grep answers codebase questions 12.5% more accurately than grep alone.这就是为什么同一个模型，在 Cursor 里比在一个干聊天框里更有用 —— 不是模型更强，是它读过你整个项目。底座层的补全谁都有，这层「它认识你的代码库」才是你为它付钱的核心理由之一。This is why the same model is more useful inside Cursor than in a bare chat box — not a stronger model, but one that has read your whole project. Autocomplete on the base layer is everywhere; this layer — 'it knows your codebase' — is one of the core reasons you pay for it.
— II
@ 是你精确喂料的手@ Is How You Feed It Precisely.
索引让它能找，@ 让你确保它找对。The index lets it find; @ lets you make sure it finds the right thing.与其写一长段背景，不如 @ 准那两样东西。常用的几个：2注 2Note 2Cursor Docs · @ Symbols —— 用 @ 精确引用上下文：@Files & Folders、@Docs（含自建文档，可读非代码）、@Terminals（终端输出）、@Past Chats、@Commit / @Branch（git diff）、@Browser（内置浏览器内容）。截至 2026-07-10。Cursor Docs · @ Symbols — pull in precise context with @: @Files & Folders, @Docs (including your own, reads non-code), @Terminals (terminal output), @Past Chats, @Commit / @Branch (git diffs), @Browser (built-in browser content). As of 2026-07-10.Rather than write a paragraph of background, @ the two things that matter. The ones you'll use most:2注 2Note 2Cursor Docs · @ Symbols —— 用 @ 精确引用上下文：@Files & Folders、@Docs（含自建文档，可读非代码）、@Terminals（终端输出）、@Past Chats、@Commit / @Branch（git diff）、@Browser（内置浏览器内容）。截至 2026-07-10。Cursor Docs · @ Symbols — pull in precise context with @: @Files & Folders, @Docs (including your own, reads non-code), @Terminals (terminal output), @Past Chats, @Commit / @Branch (git diffs), @Browser (built-in browser content). As of 2026-07-10.
@Files & Folders@Files & Folders
把指定文件或整个文件夹塞进上下文 —— 最常用，比让它去索引里猜更稳。Drop a specific file or whole folder into context — the most-used, steadier than making it guess from the index.
@Docs@Docs
搜索已索引的文档，包括你自己加的 —— 能读非代码资料。Search indexed documentation, including your own — reads non-code material.
@Terminals@Terminals
把终端输出当上下文 —— 让它就着报错接着改。Bring terminal output in as context — let it continue from the error.
@Commit / @Branch@Commit / @Branch
把未提交改动或整条分支相对 main 的 diff 给它 —— review、写 commit message 都用得上。Hand it your uncommitted changes or a branch's full diff against main — useful for review and commit messages.
@Browser@Browser
把内置浏览器里的内容附进来 —— 读网页、文档站。Attach content from the built-in browser — read a web page or docs site.
边界：@ 得太多是噪声，张口就 @ 整个代码库更是 —— 那等于让它做一次全库语义搜索，又贵又容易跑偏。先 @ 准那一两个文件，不够再放宽；把最相关的三五样给它，不是把半个项目都贴进去。喂料的本事不是「喂得多」，是「喂得准」。The boundary: too many @s are noise, and reaching for @ the whole codebase is worse — that's a project-wide semantic search, costly and easy to send off track. Start by @-ing the one or two files that matter and widen only if needed; give it the three-to-five most relevant things, not half the project. The skill isn't feeding more; it's feeding precisely.
你手里有什么What you have
先用Use first
不要一上来用Do not start with
明确文件 / 组件 / 章节A known file / component / chapter
@file
@codebase
一组同目录资料A folder of related material
@folder
整仓检索whole-repo search
外部文档站或团队手册External docs or team manual
@Docs
复制一大段网页pasting a huge web page
报错、测试输出、日志Error, test output, logs
@Terminals
口述报错describing the error from memory
当前改动需要 reviewCurrent changes need review
@Commit / @Branch
让它猜你改了什么letting it guess what changed
不确定相关文件Unknown relevant files
先让 Agent search，再要求列来源Let Agent search first, then list sources
一次塞半个项目attaching half the project
— III
它读的不必是代码What It Reads Needn't Be Code.
把一个装满资料的文件夹当项目打开，索引和 @ 照样工作 —— 这是它干非编码活的上料口。Open a folder full of material as a project and the index and @ work just the same — this is the intake for its non-code work.指向一个装满笔记的文件夹、一批 CSV、一份手册，@Docs 还能索引外部文档站；agent 就能按意思在你的资料里检索、回答、产出。调研、整理、写作这类活之所以能在 Cursor 里做，正是因为它对待你的资料和对待代码是同一套机制：建索引、按意思找、@ 精确取。Point it at a folder of notes, a batch of CSVs, a manual, and @Docs can even index an external docs site; the agent then searches your material by meaning, answers, and produces. Research, organizing, and writing can happen in Cursor precisely because it treats your material the same way it treats code: index it, search by meaning, @ it precisely.
先读资料，再行动：
- 先阅读 @<资料文件或文件夹>
- 输出一份资料地图：关键文件、每个文件讲什么、缺口是什么
- 在我确认前，不要改文件
- 确认后只改 <目标路径>
- 每条事实保留来源文件路径。Read material before acting:
- First read @<material file or folder>
- Output a material map: key files, what each says, and gaps
- Do not modify files before I confirm
- After confirmation, modify only <target path>
- Keep source file paths for every factual claim.
先读资料，再行动：
- 先阅读 @research/sources 和 @docs/specs/cursor-outline.md
- 输出一份资料地图：关键文件、每个文件讲什么、缺口是什么
- 在我确认前，不要改文件
- 确认后只改 content/books/cursor/chapters/05-context.mdx
- 每条事实保留来源文件路径。Read material before acting:
- First read @research/sources and @docs/specs/cursor-outline.md
- Output a material map: key files, what each says, and gaps
- Do not modify files before I confirm
- After confirmation, modify only content/books/cursor/chapters/05-context.mdx
- Keep source file paths for every factual claim.
隐私这条线要讲清：官方口径是「Cloud Agents 是唯一需要 Cursor 存储代码的功能」—— 索引流程存的是向量嵌入和加密后的路径，不需要长期存你的源码。5注 5Note 5Cursor Docs · Privacy & Data Governance —— 官方口径：「Cloud Agents 是唯一需要 Cursor 存储代码的功能」—— 索引流程与 LLM 请求都不需要长期存你的代码；企业档还有 CMEK（用你自己的密钥加密嵌入）。截至 2026-07-10。Cursor Docs · Privacy & Data Governance — the official line: 'Cloud Agents are the only feature that requires Cursor to store code' — neither indexing nor LLM requests need your code stored; Enterprise adds CMEK (embeddings encrypted with your own keys). As of 2026-07-10.4注 4Note 4Cursor Blog · Securely indexing large codebases（2026-01-27）—— 索引把代码切块转成向量嵌入；大仓库要等索引完成至少 80% 语义搜索才可用；用 Merkle 树只同步变过的部分；路径以加密形式存储；Cursor 自家评测称语义搜索叠加 grep 比单用 grep 答代码库问题准 12.5%。Cursor Blog · Securely indexing large codebases (2026-01-27) — indexing chunks code into vector embeddings; on large repos semantic search isn't available until at least 80% of indexing is done; a Merkle tree syncs only what changed; paths are stored encrypted; Cursor's own evaluation says semantic search layered on grep answers codebase questions 12.5% more accurately than grep alone.但索引确实上云 —— 真正敏感的仓库或资料，自己掂量，用 .cursorignore 把不想上传的圈掉；它挡索引，也挡 agent 对这些文件的访问，但护栏不是保险箱：真正的密钥别只靠它，放进环境变量或密钥管理。3注 3Note 3Cursor Docs · Agent Security —— .cursorignore 用来挡 agent 对指定文件的访问；读文件与搜代码不需审批，会暴露敏感数据的动作需要明确批准。真正的密钥应放环境变量 / 密钥管理，不该只靠 ignore 文件。截至 2026-07-10。Cursor Docs · Agent Security — use .cursorignore to block agent access to specific files; reading files and searching code need no approval, while actions that could expose sensitive data require explicit approval. Real secrets belong in environment variables / a secret manager, not behind an ignore file alone. As of 2026-07-10.能被它读懂的资料，才用得上它的脑子；但不是所有资料都该交给它读。The privacy line, stated plainly: the official position is that 'Cloud Agents are the only feature that requires Cursor to store code' — the indexing pipeline keeps vector embeddings and encrypted paths, not a long-term copy of your source.5注 5Note 5Cursor Docs · Privacy & Data Governance —— 官方口径：「Cloud Agents 是唯一需要 Cursor 存储代码的功能」—— 索引流程与 LLM 请求都不需要长期存你的代码；企业档还有 CMEK（用你自己的密钥加密嵌入）。截至 2026-07-10。Cursor Docs · Privacy & Data Governance — the official line: 'Cloud Agents are the only feature that requires Cursor to store code' — neither indexing nor LLM requests need your code stored; Enterprise adds CMEK (embeddings encrypted with your own keys). As of 2026-07-10.4注 4Note 4Cursor Blog · Securely indexing large codebases（2026-01-27）—— 索引把代码切块转成向量嵌入；大仓库要等索引完成至少 80% 语义搜索才可用；用 Merkle 树只同步变过的部分；路径以加密形式存储；Cursor 自家评测称语义搜索叠加 grep 比单用 grep 答代码库问题准 12.5%。Cursor Blog · Securely indexing large codebases (2026-01-27) — indexing chunks code into vector embeddings; on large repos semantic search isn't available until at least 80% of indexing is done; a Merkle tree syncs only what changed; paths are stored encrypted; Cursor's own evaluation says semantic search layered on grep answers codebase questions 12.5% more accurately than grep alone. But the index does go to the cloud — for a genuinely sensitive repo or dataset, weigh it, and fence off what you don't want uploaded with .cursorignore; it blocks indexing and the agent's access to those files, but a guardrail isn't a vault: real secrets don't belong behind it alone — keep them in environment variables or a secret manager.3注 3Note 3Cursor Docs · Agent Security —— .cursorignore 用来挡 agent 对指定文件的访问；读文件与搜代码不需审批，会暴露敏感数据的动作需要明确批准。真正的密钥应放环境变量 / 密钥管理，不该只靠 ignore 文件。截至 2026-07-10。Cursor Docs · Agent Security — use .cursorignore to block agent access to specific files; reading files and searching code need no approval, while actions that could expose sensitive data require explicit approval. Real secrets belong in environment variables / a secret manager, not behind an ignore file alone. As of 2026-07-10. Only material it can read is material its brain can use; but not all material should be handed to it to read.
答案像在猜：先 @ 准文件，不要继续追问同一个模糊问题。Answer feels guessed: @ the exact file first; do not keep asking the same vague question.
找不到新文件：检查索引状态，必要时 Reindex。Cannot find new files: check indexing status and reindex if needed.
索引很慢：把生成物、依赖、二进制、大 CSV 写进 .cursorignore。Indexing is slow: exclude generated output, dependencies, binaries, and huge CSVs in .cursorignore.
引用来源混乱：要求它列出使用过的文件路径和行号，再继续执行。Sources are muddled: require file paths and line references before continuing.
涉及敏感资料：先决定是否该进 Cursor；不是所有可读材料都该被索引。Sensitive material: decide whether it belongs in Cursor first; not all readable material should be indexed.
拿一份非代码资料试它的上下文：Test its context on a folder of non-code material:
把一个非代码文件夹（调研笔记 / 一份手册 / 一批数据）当项目打开，让它建索引。Open a non-code folder (research notes / a manual / a batch of data) as a project and let it index.
问一个「按意思」的问题，看它能否找到没出现关键词的那段。Ask a 'by meaning' question and see if it finds the passage where the keyword never appears.
用 @ 精确指一份文件纠正它一次，对比前后回答。Use @ to point at one file and correct it once; compare the answers before and after.
去 Settings 确认索引范围，把不该上传的写进 .cursorignore。Confirm the index scope in Settings, and add anything that shouldn't be uploaded to .cursorignore.
模型决定它多聪明，
上下文决定它多有用.
The model sets how smart it is,
context sets how useful.
Aklman Library
— 讨论Discussion
讨论Discussion.
评论区初始化中…Initializing comments…
01 / 01
没有匹配结果No matches.
换个关键词，或按 Esc 回到页面Try another keyword, or press Esc to return