cursor需启用全项目索引、配置.cursorignore、使用@codebase前缀、绑定文件选区及启用代码图谱视图，才能准确理解大型项目结构与依赖关系。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您打开一个大型代码库，但Cursor未能准确理解项目结构、函数调用链或模块依赖关系，则很可能是代码库索引未正确启用或配置不当。以下是让Cursor真正读懂大型项目的具体操作路径：
一、启用并验证全项目索引状态
代码库索引是Cursor理解项目全局上下文的基础机制，它通过静态分析构建符号表、文件依赖图与跨文件引用关系。只有索引完成且状态为“Ready”，AI才具备跨文件生成、语义搜索与依赖追溯能力。
1、打开Cursor，确保已加载目标项目的根目录（状态栏应显示项目路径）。
2、进入设置界面：按下 Ctrl+,（Windows/Linux）或 Cmd+,（Mac），导航至「Features」→「Codebase Indexing」。
3、确认「启用代码库索引」开关已开启；若为灰色不可点，检查项目是否为合法工作区（含package.json、pyproject.toml等标识文件）。
4、观察右下角状态栏：出现“Indexing…”表示正在构建索引；待其变为“Ready”后，方可执行后续深度操作。
二、配置.cursorignore精准排除干扰路径
无效文件的索引会拖慢处理速度、污染语义上下文，并可能导致AI误用构建产物或敏感配置。通过.cursorignore可强制限定索引范围，提升准确性与响应效率。
1、在项目根目录新建纯文本文件，命名为 .cursorignore（注意开头的英文句点）。
2、向该文件中逐行写入需忽略的路径模式，语法与.gitignore完全一致。
3、必须包含以下典型条目：node_modules/、dist/、build/、*.log、.env*、__pycache__/、.DS_Store。
4、保存后，Cursor将自动触发增量索引更新；如未生效，可手动点击设置页中的「刷新索引」按钮。
三、使用@codebase前缀触发项目级语义查询
普通自然语言提问默认基于当前文件上下文，而添加@codebase指令可显式激活全索引层检索，使AI能访问函数定义位置、全部调用点、模块导入关系等全局信息。
1、在AI聊天框中输入问题前，务必以 @codebase 开头，例如：“@codebase 项目中哪些地方调用了handlePaymentError函数？”
Agents 正在你的整个代码库中处理越来越复杂、运行时间更长的任务。本次版本引入了新的 agent 框架改进，以实现更好的上下文管理，并在编辑器和 CLI 中带来了许多提升使用体验的修复。
2、避免模糊表述，优先使用项目内真实函数名、类名、API路径或业务术语（如“订单超时取消逻辑”“用户权限校验入口”）。
3、对返回结果中的每个匹配项，点击右侧跳转图标，可直接定位至源码行并展开上下文。
4、若结果为空，检查该符号是否被.cursorignore排除，或确认其是否存在于已索引文件中（如仅存在于未提交的临时文件里）。
四、绑定文件或选区发起局部深度对话
针对关键模块，将AI对话范围收缩至单个文件或代码块，可规避全局噪声，获得更聚焦的技术解析，尤其适用于阅读高耦合或缺乏注释的遗留逻辑。
1、在编辑器中打开目标文件（如 src/core/auth/TokenManager.ts）。
2、用鼠标拖选需理解的完整类定义或函数体（建议包含import语句与相邻辅助函数）。
3、右键选区，选择「Ask Cursor about selection」；或使用快捷键 Ctrl+L（Windows/Linux）/ Cmd+L（Mac）。
4、在弹出对话框中提出具体问题，例如：“这个refreshToken方法如何保证线程安全？是否可能触发重复刷新？”
五、启用代码图谱视图可视化依赖拓扑
代码图谱将抽象的调用关系转化为可交互节点图，直观呈现函数间控制流与数据流走向，帮助识别核心服务边界、识别孤立模块及发现隐式耦合。
1、在任意函数名或类名上右键，选择「Show Code Graph」。
2、图谱默认以该节点为中心展开三层关联；悬停任一节点可查看其签名、所在文件路径及简要说明。
3、按住空格键拖动画布，滚轮缩放，双击节点跳转至其定义处。
4、点击图谱左上角「Filter by file type」，勾选 .ts、.js、.py 等主代码类型，关闭测试、配置、模板类文件显示。
