Composer 与多文件编辑

Composer 与多文件编辑

本节摘要:真实项目中的功能开发很少只改一个文件——加一个 API 接口,可能要同时改 model、service、controller、router、test 五六个文件。Composer(Cursor)和 Cascade(Windsurf)就是为这种场景设计的:你描述一个完整意图,AI 同时修改多个关联文件,生成统一的 diff 供你审查。本节拆解多文件编辑的底层工作流程,讲清如何控制编辑范围、审查 diff、以及在 AI「改飞了」时如何回滚。

一、多文件编辑的工作流程

不管你用 Cursor Composer 还是 Windsurf Cascade,多文件编辑的底层逻辑是一样的:

关键步骤解析:

1. 上下文收集:AI 根据意图自动搜索相关文件(或你手动 @file 指定)
2. 规划方案:AI 决定需要改哪些文件、每个文件改什么
3. 生成 diff:所有修改以 diff 形式呈现(绿色新增/红色删除)
4. 用户审查:你逐个文件查看,决定接受或拒绝
5. 应用变更:确认后,所有修改一次性写入文件

关键概念:多文件编辑的核心价值不是「AI 能改多个文件」,而是「AI 能保持多个文件之间的一致性」。比如你改了一个接口签名,AI 会同步修改所有调用方——这是手动 Inline Edit 做不到的。

二、Cursor Composer 实操

打开方式

• 快捷键:Cmd+I(macOS)/ Ctrl+I(Windows)
• 或从 Chat 面板切换到「Composer」标签

基本用法

在 Composer 输入框中描述你的意图:

给用户模块添加「修改密码」功能:
- 在 src/api/user.ts 中添加 PUT /user/password 接口
- 在 src/services/userService.ts 中添加 updatePassword 方法
- 需要验证旧密码正确后才能修改
- 用项目现有的 hashPassword 和 comparePassword 工具函数
​

Composer 会:

1. 搜索相关文件(你 @ 的 + 它自己找的)
2. 在面板中列出所有要修改的文件
3. 每个文件显示 diff
4. 你可以:
   • Accept All(Cmd+Enter):全部接受
   • 逐文件审查:点开每个文件看 diff,单独接受/拒绝
   • Reject All(Esc):全部放弃

Agent 模式下的 Composer

切换到 Agent 模式后,Composer 不仅能改文件,还能:

• 执行终端命令(如运行测试验证修改)
• 根据命令输出自动修复问题
• 创建新文件、安装依赖

💡 技巧:对于「加一个完整功能」这种任务,直接用 Agent 模式。对于「我知道要改哪些文件,只需要 AI 帮我写代码」的任务,用普通 Composer(更快、更可控)。

三、Windsurf Cascade 的差异

Cascade 的多文件编辑与 Composer 逻辑类似,但体验上有几个不同:

• 更自动:Cascade 默认自己搜索上下文,不需要你手动 @file
• 流式展示:修改是一个文件一个文件「流出来」的,你能实时看到 AI 的思考过程
• 自动验证:Cascade 更倾向于「改完就跑一下看看对不对」

适用差异:

• 如果你对要改的文件很明确 → Cursor Composer(手动指定,更精准)
• 如果你不确定涉及哪些文件 → Windsurf Cascade(让它自己找,更省心)

四、审查 diff 的技巧

多文件编辑最大的风险是「AI 改多了」或「AI 改错了」。审查 diff 是保护自己的最后一道防线。

快速审查清单

1. 文件列表对不对:AI 要改的文件是否都是你预期的?有没有不该动的文件?
2. import 变化:新增的 import 是否合理?有没有引入不存在的模块?
3. 接口签名:函数参数、返回值是否跟调用方一致?
4. 删除内容:红色删除的部分是否真的不需要了?
5. 副作用:有没有「顺手」修改了不相关的逻辑?

回滚策略

如果接受后发现有问题:

• Git 回滚:git diff 查看变更,git checkout -- . 全部回滚
• Ctrl+Z:刚接受还没做其他操作时,可以撤销
• 部分回滚:只回滚某个文件 git checkout -- src/api/user.ts

⚠️ 注意:养成习惯——在让 AI 做大规模多文件修改之前,先 git add -A && git commit -m "before AI edit"。这样不管 AI 改成什么样,你都能一键回到修改前。

五、控制编辑范围

AI 有时候会「热心过度」——你让它加一个函数,它顺手重构了整个文件。控制范围的方法:

方法 1:在 Prompt 中明确约束

只修改 src/api/user.ts 和 src/services/userService.ts。
不要修改其他文件。不要重构现有代码。
​

方法 2:手动指定文件列表

@file:src/api/user.ts
@file:src/services/userService.ts
基于这两个文件,添加修改密码功能。
​

方法 3:分步执行
先让 AI 只改 service 层 → 确认 → 再让它改 API 层 → 确认。每步范围小,出错容易定位。

本节要点回顾

1. 核心价值:多文件编辑保持文件间一致性——改接口签名时同步改调用方
2. 工作流:意图 → 上下文收集 → 规划 → 多文件 diff → 审查 → 应用
3. Composer vs Cascade:Composer 更精准(手动指定),Cascade 更自动(自己搜索)
4. 审查重点:文件列表、import 变化、接口签名、删除内容、副作用
5. 回滚保障:大修改前先 git commit;出问题用 git checkout 回滚
6. 范围控制:Prompt 约束 + 手动指定文件 + 分步执行

多文件编辑是 AI 编程的「重武器」。但再好的武器也需要精准的「瞄准」——下一节我们讲一套可复用的需求描述模板,让你的每一次 Prompt 都精准命中目标。