多文件编辑与 Composer

Composer 是什么

Composer 是 Cursor 中专门用于多文件同时编辑的 AI 功能，快捷键 Cmd+I（Mac）/ Ctrl+I（Windows）。 与 Chat 的核心区别在于：Chat 以"对话"为中心，Composer 以"任务"为中心——你描述一个需要修改多个文件的任务， Composer 在一个统一视图中展示所有文件的 diff，你可以一次性审查和接受全部改动。

Normal 模式 vs Agent 模式

Composer 有两种工作模式，选择合适的模式很重要：

• Normal 模式（普通模式） AI 根据你的描述，直接提出所有需要修改的文件和内容。改动一次性展示，适合你已经明确知道要修改哪些文件的场景。生成速度快，不会自主执行命令。
• Agent 模式（代理模式） AI 以 Agent 方式自主探索代码库，可以运行命令、搜索文件、迭代修改。适合复杂任务，AI 需要先"理解"再"动手"。Token 消耗更多，但结果质量更高。

Composer 工作流实战

典型场景：为 Express 项目添加用户认证模块

// 打开 Composer（Cmd+I），输入任务描述：
"""
为这个 Express + TypeScript 项目添加完整的 JWT 认证系统：
1. 创建 src/auth/authController.ts（注册、登录接口）
2. 创建 src/auth/authMiddleware.ts（JWT 验证中间件）
3. 创建 src/auth/authService.ts（业务逻辑）
4. 修改 src/models/User.ts（添加 password 字段和 hashPassword 方法）
5. 修改 src/app.ts（注册认证路由）
6. 创建 src/auth/auth.test.ts（完整单元测试）

使用 bcrypt 加密密码，jsonwebtoken 签发 Token，
Token 有效期 7 天，遵循项目现有的代码风格。
"""

// Composer 会：
// 1. 扫描现有代码理解项目结构
// 2. 生成6个文件的内容（创建或修改）
// 3. 在左侧文件树中高亮所有受影响的文件
// 4. 每个文件都有 diff 视图，绿色=新增，红色=删除

审查与接受改动

Composer 展示所有文件改动后，你有以下操作选项：

Checkpoint 版本快照

每次 Composer 执行前，Cursor 自动创建一个 Checkpoint（检查点），保存所有相关文件的当前状态。 这相当于一个临时的 Git 快照，让你可以随时回滚到 Composer 执行前的状态，而不影响你的 Git 历史。

# Checkpoint 与 Git 的协作方式（推荐流程）：

# 1. 确保在干净的 Git 状态下启动 Composer
git status  # 确认没有未提交的修改
git commit -m "feat: before auth module"

# 2. 让 Composer 执行任务

# 3. 审查 Composer 的改动
#    - 如果满意：Accept All，然后 git commit
#    - 如果不满意：Reject All 或用 Checkpoint 回滚
#    - 如果部分满意：选择性 Accept，手动修改不满意的部分，再 git commit

# 4. 提交最终结果
git add .
git commit -m "feat: add JWT authentication module"

高效使用技巧

技巧 1：用 @符号指定相关文件

// 在 Composer 描述中用 @引用相关文件，帮助 AI 理解上下文：
"参考 @src/models/User.ts 的写法，为 Product 模型
添加 Elasticsearch 搜索功能，修改 @src/models/Product.ts
和 @src/services/productService.ts"

技巧 2：分步执行大型重构

// ❌ 一次性重构整个后端（太大，质量差）
"将整个项目从 JavaScript 迁移到 TypeScript"

// ✅ 分模块逐步迁移（可控，可审查）
// 第1次 Composer：
"将 src/models/ 目录中的所有 .js 文件迁移到 TypeScript，
添加完整类型注解，保持功能不变"
// 审查验证后，再做下一模块

技巧 3：描述中包含技术约束

// 好的 Composer 需求描述应包含：
"
添加图片上传功能，约束：
- 使用 multer 中间件（项目已安装）
- 图片存储到 AWS S3（使用现有 @src/config/aws.ts 配置）
- 图片格式限制：JPEG/PNG/WebP，最大 10MB
- 自动生成缩略图（300x300）
- 上传记录写入 uploads 表（参考 @src/models/Upload.ts 结构）
- 遵循项目中 @src/middleware/auth.ts 的鉴权方式
"