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 —— 官方並行任務隔離入口。