Cursor Composer 是面向多文件改动的 Agent 工作台：你用一句话描述目标，它在工作区里找相关文件、给出 diff、再由你决定应用或拒绝。它不是聊天窗口的别名，也不替代 Tab 那种单行补全。第一次用时，把它理解成「带仓库上下文的改码工单」最不容易走偏。
Composer、Chat 和 Tab 各管一层
Tab 处理光标附近的续写，适合改完函数签名后补参数。Chat 适合问「这段为什么报错」或让它解释架构，默认偏对话。Composer 适合跨文件功能：加一个 API、同步 DTO、补测试、改调用方。把架构讨论丢进 Composer 会制造一堆你并不想要的文件；把「加支付回调」只丢给 Chat，你又要自己把补丁搬进仓库。
在界面上，Composer 通常以独立面板出现，能列出将要修改的文件树。你应该习惯先看文件列表，再看具体 hunk。文件列表不对，后面的代码再漂亮也不能点 Apply。
第一次任务建议这样下
- 打开仓库根目录，而不是某个偶然的子文件夹。工作区选错，Composer 会在错误边界里「创造」新项目。
- 用
@Folders或@Files点出模块，再写验收标准：例如「POST /webhooks/stripe 要验签，失败返回 400，并补两个测试」。 - 要求它先列计划再改代码。计划里如果出现你没听说过的目录，立刻纠正，不要等它写完再 Undo。
- 逐文件 Review。先看测试和类型是否一起改了，再看有没有顺手重构你没要求的命名。
- 应用后在终端跑相关测试。Composer 不会替你承担 CI，绿了才算这张工单结束。
它擅长什么，不擅长什么
Composer 擅长在已有约定里做增量：你仓库里已有错误处理、日志和测试框架，它能模仿。它不擅长从零设计复杂领域模型，也不该被用来「顺便升级所有依赖」。上下文窗口再大，也会在巨型 monorepo 里被截断，所以范围越小，成功率越高。
把密钥、生产配置和生成目录用忽略规则挡在外面。Agent 一旦看见 .env，有时会把示例密钥写进文档。这不是功能，是风险。
用一个小功能把流程跑通
第一次不必挑战巨型重构。选一个你熟悉的小接口，例如给已有路由加参数校验和两个失败用例。自己先想清楚文件应该有哪几个，再看 Composer 列的清单是否重合。重合度高，说明引用和描述是对的；它若去改无关的工具函数，立刻停。这个小实验能教会你「清单对了再 Apply」，比直接让它「优化整个项目」更能建立正确手感。跑通后再逐步加大范围。
Composer 对「口头禅式需求」几乎总是表现差。例如只说「优化一下」「按最佳实践改」。它会把范围理解成整个目录的风格统一。把需求改成可验证的句子：输入、输出、失败怎么表现、哪些文件不准动。同一模型下，这句话的质量差异会大于换一个模型。
常见问题
Composer 和 Agent 模式是不是同一个东西？
产品迭代里名称会变，但职责接近：都能读多文件并提交补丁。你要认的是「会不会改仓库」和「要不要你确认」，而不是按钮上的英文单词。
要不要每次都 @ 整个仓库？
不要。整个仓库会冲淡重点，还容易让它改到文档站或基础库。点名两三个目录，效果通常更好。
它可以自动提交 Git 吗？
可以准备提交说明，但提交权应留在你手里。先看 diff 再 git commit，避免把半成品推进共享分支。
