在维护期项目或接手陌生代码库时，人工逐行审查容易遗漏，而传统 Linter 只能捕获语法和格式问题。Cursor 的 @Codebase 结合 Agent 模式，可以基于项目全局上下文做语义级风险排查，一次性列出跨文件的潜在缺陷。
1. 触发方式
在侧边栏 AI 对话面板输入框中，先输入 @Codebase（或点击输入框下方的 " codebase " 按钮）绑定全项目上下文，随后用自然语言描述排查目标。例如：
"检查整个项目中所有异步函数，找出缺少 try-catch 或错误处理的地方，按文件路径列出具体问题行。"
若项目规模较大，建议先切换到 Agent 模式（在对话面板顶部模型选择旁切换），让 Cursor 自动读取多个文件、执行搜索命令并汇总结果，减少手动跳转。
2. 典型排查场景
以下指令模板可直接复用或微调：
- 逻辑缺陷："找出所有可能返回 null 但未做空值判断的函数调用，重点关注 API 返回和数据库查询后的使用位置。"
- 资源泄漏："检查项目中打开文件、数据库连接或网络请求后，未正确关闭或释放资源的代码。"
- 硬编码与敏感信息："扫描代码库里是否存在硬编码的密钥、密码、Token 或内网 IP，并列出所在文件。"
- 重复实现："查找功能相似或逻辑重复的函数/组件，建议抽象成公共方法的地方。"
- 类型与接口不一致："对比前后端共享的 DTO/接口定义，找出字段名或类型不匹配的位置。"
3. 操作步骤与技巧
- 先缩小范围，再逐步扩大：首次排查不要直接抛"检查所有 Bug"这类宽泛问题。建议限定目录（如
@文件夹名）或文件类型（如"只检查.ts文件"），结果会更精准。 - 结合现有报错：如果你已有编译错误、测试失败日志或运行时堆栈，先把错误信息粘贴给 AI，再附加
@Codebase让它定位根因："根据以下报错，在全库找出导致该错误的源头。" - 分批次确认：AI 给出的问题清单往往包含误报（例如把故意抛出的异常当成未处理）。建议要求它以表格形式输出：文件路径 | 行号 | 问题描述 | 风险等级。你可以先修复高风险的，低风险的稍后处理。
- 批量修复与回滚：在 Agent 模式下，你可以直接要求"对以上问题自动创建修复分支并逐条修改"，Cursor 会跨文件应用变更。执行前确保项目已纳入 Git 管理，方便一次性 diff 审查和回滚。
4. 现实边界
- 假阳性不可避免：AI 对业务上下文理解有限，可能把正常的设计模式误判为缺陷，务必逐条人工确认。
- 大项目需耐心等待：代码库超过十万行时，上下文索引和检索可能耗时数十秒，建议避开业务高峰期操作。
- 安全红线：涉及支付、权限、加密等核心模块的问题，即使 AI 给出修复方案，也必须由资深开发审核后再合入，不要直接一键应用。
通过这种方式，你可以在几分钟内完成过去需要数小时人工 Code Review 的初筛工作，把精力集中在真正的风险点上。