这篇讲什么
从”刚下完 Windsurf”到”Cascade 跑出一个我敢提的多文件小 diff”，30 分钟线性路径。Windsurf 是 Codeium 的 AI 优先 IDE——壳跟 VS Code 一样，但 Cascade agent 是主角，不是附加件。新人最容易犯的错是当它是”换皮 Cursor”，开口就让它”整理整个仓库”，diff 一炸就放弃。这篇逼你慢下来：装、登录、钉几个文件、跑一个具名小任务、收一个小 diff。
核心概念：
- Cascade：agent 模式——多步、多文件，授权时还能跑 shell 和测试。
- Write / Chat / Cascade 三角：三种交互模式；Write 是行内补全，Chat 是对话，Cascade 才是 agent。
- Rules：钉住的项目上下文文件，Windsurf 当 system prompt 用。
这篇适合谁看
已经用过一个 AI 编程工具（Copilot、Cursor、Claude Code）、想要第二个对照——或者觉得 Cursor Composer 在计划上不够果断、想试更紧的 agent 循环。会用 VS Code 快捷键。完全没用过 AI IDE 的，先走Cursor 新手 30 分钟跑通完整工作流，知道”agent diff”长啥样再来评估 Windsurf。
什么时候适合用
Cursor agent 在”该不该动手”上犹豫的时候，或者你想换个新工具 A/B 一下当前流程的时候。Windsurf 在范围明确的多文件改动上特别合身——把一个模式套到 5 个文件、加一个端点带测试、机械式迁移。和 Cursor 比社区小、和 Claude Code 比长时间 shell 会话弱。
开始前准备
- 本地切一份真项目——别用
hello-world。agent 的价值只在真上下文里看得出来。 main的测试和 lint 都过。Cascade 会放大仓库当前状态，包括烂的。- 一个 Codeium 账号（免费档够第一次跑；付费档解锁更多 Cascade 调用）。
- 提前选好一个小目标：在 3 个文件里改一个函数名、给一个模块加测试、把一个组件迁到新模式。别选”现代化整个仓库”。
具体步骤
- 官网下 Windsurf 装上启动。第一次启动会问要不要导入 VS Code 设置和扩展——接受，省 20 分钟。
- 用 Codeium 登录。命令面板（
Cmd/Ctrl+Shift+P）搜”Windsurf: Sign In”，如果面板没弹出来。状态栏看到账号就行。 - 打开项目文件夹。等索引跑完——状态栏看进度。索引没完不要开 Cascade，会引一堆不存在的文件路径。
- 钉一份 rules 文件。仓库根建
.windsurfrules：
# Cascade 项目规则
- 语言：TypeScript，strict 模式开。
- 测试命令：`pnpm test`。改完必须跑。
- Lint 命令：`pnpm lint`。lint 错没修不算完。
- 不要碰 `src/generated/`——是代码生成的。
- 优先 named export。新文件不要 default export。
- React 组件，测试同目录命名 `Component.test.tsx`。- 打开 Cascade（右侧面板或
Cmd/Ctrl+L）。选模型——Claude Sonnet 4.6 是安全默认；要多推理用 GPT-5，要速度用 GPT-5.4。打一段紧的 prompt：计划把 src/ 里的 getUser 改名为 fetchUserProfile。列出要动的文件和要改的测试。先别动代码。 - 看计划。错的地方推回去：超范围的文件、漏改的测试。然后说
按计划执行，一次一个文件，每个文件后跑测试。 - 看着 diff 跟着改。按文件 accept 或 reject。测试都过、diff 跟计划对得上，就 commit。
一段”逼它说实话”的 prompt
存成 Cascade 的复用片段，第一次会话开头用：
你在这个仓库里干活。动手前：
1. 读 `.windsurfrules`，列出和本任务相关的规则。
2. 列出要改的文件，每个一句话讲为什么。
3. 列出不会动的文件，并说为什么。
4. 说你要跑哪个测试命令、什么时候跑。
然后等我说"开始"。我没说之前不要写代码。
不要碰 src/generated/ 和 vendor/。
任何一步连失败两次，停下来问——不要循环。这段 prompt 能把”第一次会话后悔率”砍掉一半左右——Windsurf 大部分失败都是 agent 跳过了计划那一拍。
完成后检查
- diff 和你批准的计划一致。超出的就是范围漂移——拒掉重提。
- 每个文件后测试都过，不是攒到最后才跑。Cascade 一次性批量改、最后才挂的话没法二分定位。
.windsurfrules已经 commit，队友能继承约束。- Cascade 对话里引的是真的 symbol 和文件。引到幻觉就是索引没跑完——重 index 再来。
- 模型和任务匹配：通用代码 Sonnet 4.6、架构推理 GPT-5、模板活 GPT-5.4。
怎么复用这套流程
- 上面那段计划 prompt 存成 Cascade snippet。所有非琐碎会话第一句就贴。
- 把
.windsurfrules当活的记忆。Cascade 同一种错犯两次，就加一条禁止规则。 - 列一份”必须钉住”的文件清单——核心类型、主配置、测试启动文件。可能动到它们的 prompt 开头就提到。
- 一次会话成功了，把它最后的总结复制进 PR 描述。Cascade 写的总结当 PR 模板基本能用。
建议的操作流程
装 → 登录 → 等索引 → 写 .windsurfrules → 计划 prompt → 看计划 → 按文件执行 → 每个文件后测 → commit。
容易踩的坑
- 索引没完就开 Cascade。引一堆假路径，第一天就丢信心。
- 觉得”项目简单”就跳过
.windsurfrules。哪怕 10 行也能拉高产出。 - “把这个模块现代化一下”——你会拿到 40 文件 diff、没法看。给它一个具名小步。
- 把 Cascade 当 Cursor Composer 用。形似但 Windsurf 对计划提交得更狠——你的 prompt 范围要更紧。
- 每个任务都用 GPT-5。模板活上是浪费（也慢）——换 GPT-5.4 或 Sonnet 4.6。
- diff 不看就全收。再好的 agent 也会顺手改一个你不想动的文件。
FAQ
- Windsurf 比 Cursor 好吗？: 权衡不同。机械式多文件 Windsurf agent 循环更紧；社区、扩展、rules 生态 Cursor 赢。试一周再决定。
- 能离线用吗？: 不能——agent 走远端模型。行内补全有一点本地启发，Cascade 必须联网。
- 能用自己的 API key 吗？: 可以，BYO-key 设置；绕过 Codeium 配额但要自付模型钱。
- 改着改着上一轮编辑被回滚？: Cascade 偶尔会重读文件、覆盖未保存内容。继续对话前先 save，或者用按文件 accept 的流程。