Cascade 核心能力

Cascade 是 Windsurf 的 agentic AI assistant（自主型 AI 助手——能自己拆任务、调工具、推进多步动作，不是一问一答的聊天机器人）。官方把它定义为带 Code/Chat 能力、工具调用、语音输入、checkpoints、实时上下文感知和 linter 集成的 AI 助手。真正要学的不是按钮位置，而是如何把一个任务放进可审查的开发闭环。

本章目标：读完后，你应该能判断一个任务应该用 Ask 解释、Plan 拆解、Code 实施，还是先停在只读分析；同时知道 tool call、checkpoint、多会话和 Agent Command Center 的边界。

1. 打开方式和上下文入口

官方入口是点击 Windsurf 右上角 Cascade 图标，或按 Cmd/Ctrl+L。在编辑器或终端中选中文本后打开 Cascade，选中内容会自动带入上下文。

这决定了第一条原则：能给证据就不要只给描述。

场景	更好的输入方式	原因
解释报错	选中 terminal stack trace 再发送	避免漏掉真实错误行
解释文件	打开文件或选中关键函数	Cascade 能结合当前编辑器内容
修 lint/type 错误	从 Problems panel 使用 `Send to Cascade`	官方支持把问题作为上下文传入
继续刚才动作	明确让 Cascade `Continue`	官方说明 Cascade 有 real-time awareness

第一次使用建议从只读任务开始：

只读分析这个项目。
输出：
1. 技术栈
2. 入口文件
3. 测试和构建命令线索
4. 你需要我确认的问题
不要修改文件，不要执行命令。

2. Code、Plan、Ask 三种模式

官方最新 Cascade Modes 页面把模式分成 Code、Plan、Ask：

Mode	工具范围（官方）	官方定位	实操边界
Code	All tools enabled（全工具）	默认 fully agentic mode，可创建、编辑、删除文件，运行终端命令，搜索和分析代码，安装依赖，执行多步任务	用于明确要改代码的任务；必须限定文件范围和验证方式
Plan	All tools enabled（全工具）	先探索代码库、澄清需求、给选项，并产出外部 Markdown 计划文件	用于多文件功能、迁移、重构、上线流程；计划确认后再实现
Ask	Search tools only（仅搜索类工具）	只读模式，适合问题、学习和探索；可以搜索分析代码库但不能跑命令、不能改文件、不能装依赖	用于解释、比较、定位根因、写方案

Ask 不是"温和的 Code"——它在工具层就只挂了 Search 系工具。需要跑测试、装依赖、改文件，必须切到 Code（或先在 Plan 里规划再切 Code）。

可以用输入框下方模式切换，也可以用 ⌘+.（Mac）或 Ctrl+.（Windows / Linux）切换。

模式不是安全边界的全部。即使用 Ask，也要说清楚“只读”；即使用 Code，也要限定“只改这些文件、先看 diff、不要安装依赖、不要提交”。

3. Plan Mode 的正确用法

Plan Mode 适合复杂任务。官方说明它会探索代码库、询问澄清问题、提供多选项，并把实现步骤写入外部 Markdown 计划文件。完成后可以点击 Implement 切到 Code mode。

计划文件还有一个重要用途：跨会话继续。官方说明 plan files 存在 ~/.windsurf/plans，可以通过 @mentions 菜单引用。初次实现走偏时，可以丢弃原改动，调整计划文件，再在新对话里实现。

建议使用 Plan Mode 的任务：

新功能跨多个模块。
框架迁移、依赖升级、目录重组。
需要先比较 2-3 个实现方案。
需要拆分测试、构建、发布和回滚步骤。
不确定需求，必须先让人确认范围。

不建议用 Plan Mode 的任务：当前文件小 bug、单个类型错误、单段代码解释。这些用 Ask 或 Code 更直接。

4. Todo、队列和 Continue

Cascade 会为复杂任务创建 Todo list，并可在执行中根据新信息更新计划。你也可以要求它修改 Todo。

官方还支持 queued messages：当 Cascade 正在工作时，可以提前输入下一条消息排队；如果输入框为空再按 Enter，可以立即发送；排队消息可以删除。

flowchart TD
    Prompt["任务输入"] --> Mode["选择 Ask / Plan / Code"]
    Mode --> Plan["Plan / Todo list"]
    Plan --> Tools["Search / Analyze / Web Search / MCP / Terminal"]
    Tools --> Output["解释 / diff / 命令结果"]
    Output --> Review["人工审查"]
    Review --> Continue["需要继续就 Continue"]
    Review --> Stop["达到边界就停止"]

    style Plan fill:#dbeafe,stroke:#2563eb,stroke-width:2px
    style Review fill:#fef3c7,stroke:#d97706,stroke-width:2px
    style Stop fill:#dcfce7,stroke:#16a34a,stroke-width:2px

Todo 的价值不是“看起来有计划”，而是让你能在每一步审查它是否越界。任务跨多个文件时，先让 Cascade 列 Todo，再分阶段执行。

5. 工具调用和 20 次限制

官方 Cascade 页面列出可用工具包括 Search、Analyze、Web Search、MCP 和 terminal。Cascade 可以检测项目依赖和工具，也可能建议安装依赖或运行命令。

官方同时说明：每个 prompt 最多 20 次 tool calls。轨迹停止后可以点击 continue，但每次 continue 会按一次新的 prompt 重新计费（包含 tool call 成本）；如果开了 Auto-Continue，超限时自动续跑同样会消耗对应模型的 prompt credit。

prompt credit / tool call 是什么：prompt credit 是 Windsurf 给一次完整请求计费的单位（按所选模型的 token 价 + tool call 累计算）；tool call 指 Cascade 每读一个文件、跑一条命令、查一次代码索引、调一个 MCP 接口的次数。20 次 tool call 上限到了再续 = 重新算一次 prompt credit。

这意味着大任务要主动切小：

只做第 1 步：定位根因。
不要修复，不要安装依赖，不要继续到第 2 步。
输出涉及文件、证据和建议的最小修改。

涉及安装依赖、删除文件、数据库迁移、部署、生产后台、密钥或付费 API 的动作，都必须人工确认。

6. Checkpoint、Revert 和 git

Cascade 支持 named checkpoints 和 reverts。官方说明可以从原始 prompt 处或对话目录（table of contents）里 revert 到对应步骤，也可以在对话中创建 named snapshot/checkpoint。

推荐顺序：

开始前创建 checkpoint。
让 Cascade 做受限修改。
审查 diff 和测试结果。
方向错了再 revert。

但官方也提醒 reverts 目前不可逆。它不能替代 git。

git status --short
git diff --stat
git diff

如果仓库里还有其他人或其他 agent 同时修改，只看 Cascade revert 会漏掉并行变更。最终上线必须回到 git diff、测试和构建。

深读：为什么 checkpoint 不能替代 git

Checkpoint 是 Cascade 会话内的便利回退点，适合撤销它刚做的一组修改。git 是项目级版本控制，能显示未跟踪文件、删除、重命名、分支差异、提交历史和并行 agent 变更。商业级上线必须以 git、测试、构建和人工审查为准。

7. Problems、Explain and Fix 与 linter

官方提供了 Problems panel 的 Send to Cascade，以及编辑器错误上的 Explain and Fix。Cascade 还可以自动修复它生成代码中的 lint 错误；官方说明这个 auto-fix 默认开启，可在 tool call 上关闭，且这类修 lint 编辑可能不消耗 credits。

使用边界：

入口	适合	不适合
`Send to Cascade`	把具体 lint/type 错误交给它解释或小修	一次吞掉全仓库无边界错误
`Explain and Fix`	当前错误、当前文件附近的小修	涉及架构、鉴权、依赖和数据迁移的大改
Auto-fix lint	修 Cascade 自己引入的小 lint	替代测试或人工 review

局部入口要局部用。不要因为入口方便，就把一组无边界错误直接交给 agent。

8. Agent Command Center、Spaces 和多会话

Windsurf 2.0 的 Agent Command Center 是管理本地和云端 agents 的 Kanban 式视图。官方说明它能展示正在工作、阻塞、待 review 的 agents；其中包括本地 Cascade sessions 和云端 Devin sessions。

Agent Command Center 不替代编辑器。它是任务管理面板，真正的最后一公里仍然要回到代码、diff、测试和人工确认。

Spaces 用来把某个任务或项目相关的 agent sessions、PRs、files 和 context 组织在一起。适合团队项目、长任务和跨多会话交接。

多会话边界：

同时运行多个 Cascades 时，不能让它们改同一片代码。
官方提醒同文件并发编辑可能产生 race，第二个 edit 可能失败。
如果预期会编辑相近文件，优先用 worktrees 隔离。
分享 conversation 前要脱敏私有路径、账号、token、客户数据和内部任务信息。

本章自检

完成本章后，用这 6 个问题检查：

什么时候用 Ask，什么时候用 Plan，什么时候用 Code？
Plan 文件在哪里，为什么能帮助跨会话继续？
Todo list 应该如何约束多文件任务？
20 次 tool call 限制和 continue 计费意味着什么？
Checkpoint、Revert 和 git diff 的职责区别是什么？
多个 Cascades 同时工作时，什么时候需要 worktrees？

通过标准：你能把一个真实开发任务拆成“上下文输入、模式选择、计划、工具调用、审查、验证、继续或停止”，并知道什么时候必须停下来人工确认。

官方来源

Cascade Overview —— 官方 Cascade 总览，覆盖工具调用、Todo、队列、checkpoint、revert、实时感知、Problems、Explain and Fix、linter、分享和多会话。
Cascade Modes —— 官方 Code、Plan、Ask 三种模式说明。
Agent Command Center —— 官方本地/云端 agent Kanban 管理面板说明。
Worktrees —— 官方并行任务隔离入口。