Cursor 怎么安全删除项目文件？查引用、审查命令并验证构建

删除项目文件的难点不是执行删除，而是证明它确实不再被使用，并且出错后能恢复。文件没有直接 import 不代表无用，它还可能被路由表、构建脚本、反射、配置、部署清单或代码生成器按路径读取。下面这套流程适合受 Git 管理的代码仓库，目标是把“想删掉”变成一组可以复核的证据。

开始前建立恢复点

先提交或暂存当前工作，确认目标文件可从 Git 恢复，并说明为什么要删除以及替代路径。建议先运行 git status --short；如果已有与本次无关的改动，先提交、暂存或移到单独分支。Cursor 官方的 Agent Security 文档说明，Agent 对工作区文件的修改会立即写入磁盘，并建议使用版本控制以便恢复，因此不能把聊天记录当备份。

给 Agent 的任务应先限制为只读分析，例如：

先不要修改或删除文件。我要评估删除 src/legacy/report.ts：
1. 全仓搜索文件路径、文件名、导出符号和字符串引用；
2. 检查路由、构建配置、测试、脚本和文档；
3. 说明它是源文件、生成物还是迁移记录；
4. 列出每处证据和建议替代路径。

按顺序检查引用

1. 搜索路径和文件名。让 Agent 全仓库搜索文件名、导出符号、路由、配置和生成脚本引用，只读输出证据。人工也可用 git grep -n "legacy/report\|report.ts" 复核；动态拼接路径时还要搜索目录名和文件基名。
2. 搜索公开符号。查函数、类、命令名、配置键和测试夹具。仅删除文件而不更新入口文件，常会在构建或运行阶段才暴露。
3. 判断文件身份。源文件应追到调用者；生成物应找到生成命令和生成源；数据库迁移、锁文件、部署配置等有顺序或审计意义，不能按“当前没有 import”处理。
4. 阅读删除计划。要求 Agent 列出将删除和将修改的准确路径。拒绝目录不明、仓库外路径、未展开变量和范围过大的递归通配符。

Cursor 的 Terminal 文档说明，命令是否需要批准及是否进入沙箱由当前 Run Mode 决定。即使界面要求确认，也应逐字阅读命令；确认按钮不能替代路径检查。

执行一个最小删除

确认引用已处理后，只删除明确路径。受 Git 管理的文件可用 git rm -- src/legacy/report.ts，其中 -- 用来结束选项解析。不要把未经检查的变量拼进 rm -rf。如果还要改入口文件，应让一次提交只完成一个清晰目的，便于审查和回退。

删除后立即查看：

git status --short
git diff --stat
git diff -- src/index.ts
git grep -n "legacy/report\|report.ts" -- .

预期结果是状态中只出现计划内的删除和引用修正；最后一次搜索不应再出现运行时引用。文档中的历史说明可以保留，但要确认不会被构建系统读取。

构建、测试与启动验证

先运行最接近被删模块的测试，再运行项目规定的构建。例如 JavaScript 项目可能是 npm test -- report 和 npm run build，Python 项目可能是 pytest tests/test_report.py。命令必须以仓库 README、持续集成配置或现有脚本为准，不能照抄示例后声称通过。

验收必须包含 Git 中明确的删除列表、全仓引用结果、构建与测试通过，以及可用的恢复方法。若服务可启动，再访问受影响入口，检查启动日志、404、资源加载和配置解析。构建成功只证明静态阶段没有发现问题，不能覆盖懒加载、计划任务或部署脚本中的运行时引用。

失败时怎样处理

• 构建报“module not found”时，先从首个报错定位仍存在的入口引用，不要批量创建空文件掩盖问题。
• 测试发现快照或夹具依赖时，判断业务是否仍需要该行为；不能为了通过而直接删除断言。
• 文件删除后又被生成，说明应修改生成源或生成配置，并重新执行生成命令核对差异。
• 发现误删时，用 git restore --source=HEAD -- path/to/file 恢复尚未提交的版本；若已提交，则按团队的回退流程处理。

适用边界

数据库迁移、生产配置、用户数据和密钥目录不适用普通清理流程，需要专门审批与备份。未纳入 Git 的二进制资产、本地数据库和上传目录也必须先确认备份；分布式系统还要检查其他仓库和部署环境，单仓搜索不能证明全局无引用。

相关问答

Checkpoint 能代替 Git 吗？

不能完全代替。关键删除应有 Git 提交或可靠备份，并用状态和差异证明恢复点存在。

删除生成文件安全吗？

先确认它能由固定命令重新生成，修改真正的生成源，再验证新生成结果与仓库策略一致。

资料与适用范围

本文根据 2026 年 10 月 1 日核验的 Cursor Agent Security 官方文档、Cursor Terminal 官方文档整理。示例流程未在你的设备、账号或仓库中实测，界面、方案、权限和项目命令应以当前环境为准。