Chapter 02

Cascade——AI Agent 深度使用

Cascade 是 Windsurf 最核心的功能——一个能自主读写文件、运行命令、跨文件完成复杂任务的 AI Agent。掌握它，才能真正发挥 Windsurf 的价值。

Cascade 的两种模式

Cascade 面板顶部有 Write / Chat 两个模式切换按钮，理解它们的区别是高效使用的基础：

Write Mode（写入模式）
Cascade 会直接读取和修改你的文件，还可以运行终端命令。每次修改以高亮 diff 形式展示，你可以逐个接受或拒绝。Write Mode 消耗的 AI 额度更多（因为涉及工具调用），但这是完成实际编程任务的正确模式。适合：实现新功能、重构、调试修复、添加测试。
Chat Mode（对话模式）
纯对话，不修改文件，不运行命令。AI 只会阅读你指定的上下文并给出文字回答。消耗额度少，响应更快。适合：解释代码逻辑、技术方案讨论、学习新 API、在修改前先"谋而后动"。建议在执行 Write Mode 任务前，先用 Chat Mode 讨论方案。
最佳实践：先 Chat，再 Write 对于复杂任务，先用 Chat Mode 问 "如果我要实现 X，你会如何设计？"，确认方案后再切换到 Write Mode 执行。这样可以避免 AI 朝错误方向生成大量代码，节省时间和额度。

代码库理解：Windsurf 如何索引你的项目

Windsurf 的代码库理解能力是其核心竞争力，底层依赖三种技术的结合：

代码库索引架构（Windsurf Codebase Indexing） ┌─────────────────────────────────────────────────────┐ │ 你的项目文件树 │ └──────────────────┬──────────────────────────────────┘ │ ┌──────────┼──────────┐ ▼ ▼ ▼ ┌────────────┐ ┌──────────┐ ┌─────────────────┐ │ AST 解析 │ │ 向量嵌入 │ │ LSP 集成 │ │（语法结构） │ │（语义相似） │ │（类型/引用关系） │ └────────────┘ └──────────┘ └─────────────────┘ │ │ │ └──────────┼──────────┘ ▼ ┌─────────────────┐ │ 统一索引数据库 │ │（本地 + 云端） │ └────────┬────────┘ │ ▼ Cascade 检索时按需查询 （相关性排序，只取最有用的上下文）

这意味着：当你问 Cascade "用户登录逻辑在哪里"，它不是做文本搜索，而是理解"用户认证"的语义，找到 auth.ts、middleware/jwt.ts、routes/login.ts 等多个相关文件并自动关联。

@上下文引用语法

在 Cascade 输入框中，使用 @ 前缀可以精确指定给 AI 的上下文，避免 AI 猜测：

// @文件 — 引用特定文件
请优化 @src/api/users.ts 中的数据库查询性能

// @符号 — 引用特定函数/类/变量
解释 @UserService.createUser 函数的参数校验逻辑

// @Codebase — 让 Cascade 搜索整个代码库
@Codebase 找出所有直接操作数据库的函数，列出文件路径

// @Web — 搜索最新文档（需要联网权限）
@Web React 19 的 Server Components 最新使用规范

// 组合使用
参考 @Web 上的 Prisma 最新文档，
帮我把 @src/db/queries.ts 中的原始 SQL 改为 Prisma ORM 风格

工具调用：Cascade 能做什么

Cascade 在 Write Mode 下可以调用多种工具，这是它"自主完成任务"的能力来源：

read_file / write_file
读取和写入任意文件。Cascade 会自动决定需要读取哪些文件，不需要你逐一指定。写入前会展示 diff，你可以查看修改内容再决定是否接受。支持批量操作——一次任务可修改几十个文件。
run_terminal（终端命令）
在集成终端中运行命令并读取输出。常见用途：运行测试（npm test）、类型检查（tsc --noEmit）、Lint（eslint .）、安装包（npm install）。Cascade 会分析命令输出，如果有错误会自动继续修复——形成"修改→测试→再修复"的闭环。
search_codebase（代码库搜索）
语义搜索代码库，找到与当前任务相关的文件和代码片段。这是 Cascade 能"理解整个项目"的核心工具，让它不用你告诉每一个相关文件在哪里。
web_search（网络搜索）
搜索最新文档、Stack Overflow 等网络资源。当 Cascade 遇到它知识截止日期之后的新 API，会主动搜索最新用法。需要在 Settings 中启用联网权限。

多步骤任务实战：添加 React 认证功能

下面是一个实际的 Cascade Write Mode 任务演示——在现有 React 项目中添加完整的用户认证功能。注意 Prompt 的写法：

// 这是一个好的多步骤 Prompt 示例
我有一个 React + TypeScript + React Router v6 项目。
需要添加完整的用户认证功能，要求：

技术栈：
- 使用 Zustand 管理认证状态
- JWT 存储在 httpOnly Cookie（不要用 localStorage，有 XSS 风险）
- API 调用使用现有的 @src/lib/api.ts 中的 axios 实例

功能要求：
1. LoginPage 组件（/login 路由）
2. 受保护路由 ProtectedRoute 组件
3. AuthStore（Zustand）含 user、token、login()、logout() 方法
4. API 请求自动附带认证 header（axios interceptor）
5. Token 过期后自动跳转登录页

请先分析现有路由结构，再给出修改方案，确认后执行。

Cascade 收到这个 Prompt 后，会执行大致如下的自主步骤：

Cascade 自主执行流程（示意）： Step 1: search_codebase("路由配置, React Router") → 找到 src/App.tsx，分析现有路由结构 Step 2: read_file("src/lib/api.ts") → 了解 axios 实例的配置方式 Step 3: read_file("src/main.tsx") → 了解应用入口和 Provider 结构 Step 4: 生成方案并在 Cascade 面板显示（等待用户确认） Step 5（用户确认后）: write_file("src/store/authStore.ts") — 创建 Zustand store write_file("src/components/ProtectedRoute.tsx") write_file("src/pages/LoginPage.tsx") write_file("src/lib/api.ts") — 修改，添加 interceptor write_file("src/App.tsx") — 修改，添加路由保护 Step 6: run_terminal("npx tsc --noEmit") → 检查 TypeScript 类型错误 Step 7（如有错误）: 自动修复并再次验证

最佳 Prompt 写法指南

Cascade 的输出质量很大程度取决于 Prompt 的质量。以下是经过实践验证的写法规则：

好的 Prompt 要素

  • 明确说明使用的技术栈版本
  • 引用具体文件路径（用 @）
  • 说明"为什么"，不只是"做什么"
  • 列出约束条件（禁止用某 API 等）
  • 分点列出多个子要求
  • 要求先分析再执行
  • 指定输出格式（如"只修改必要的行"）

常见 Prompt 错误

  • "帮我优化这个"（太模糊）
  • 不提技术栈（AI 可能用错版本）
  • 一个 Prompt 要求太多功能
  • 不说约束导致 AI 随意选库
  • 不要求先确认方案直接执行
  • 忽略现有代码风格
  • 测试和业务代码混在一起要求
// 差的 Prompt（模糊，缺少上下文）
帮我加个登录功能

// 好的 Prompt（具体，有约束，有上下文）
在 @src/App.tsx 中，使用 React Router v6 的 loader/action 模式
添加 /login 路由，要求：
- 表单包含 email（必填，email 格式验证）和 password（必填，至少8位）字段
- 错误提示使用 zod + react-hook-form
- 成功登录后重定向到 /dashboard
- 不要引入新的 UI 库（使用项目现有的 Tailwind CSS 类名风格）
- 遵循 @src/components/Button.tsx 中已有的按钮组件风格

上下文窗口管理

Cascade 的上下文窗口有限，长任务执行过程中需要注意上下文消耗：

新建 Cascade 会话
当一个任务完成后，点击 Cascade 面板顶部的"+"新建会话，清空上下文。不要在一个超长的对话中持续追加新任务——随着上下文增长，AI 对早期信息的"注意力"会下降，错误率上升。
任务分解
大型功能（如"重构整个认证系统"）应拆分为多个独立的 Cascade 任务，每个任务专注一个模块。不要试图在一个 Prompt 中完成整个系统的重写——这会消耗大量上下文并增加出错概率。
进度状态栏
Cascade 面板底部的状态栏会显示当前会话消耗的上下文量（如"23% of context used"）。当超过 60% 时，建议开始一个新会话继续未完成的任务。
本章小结 Cascade 的核心是 Write Mode 下的自主 Agent 能力：它能读文件、写代码、运行命令、形成修复闭环。关键技巧：用 @语法精确提供上下文、先 Chat 确认方案再 Write 执行、复杂任务分解为多个独立 Cascade 会话。好的 Prompt 是具体、有约束、包含技术栈版本的。