---
title: "Windsurf 從原理到實戰"
description: "用 8 篇中文教程講清 Windsurf 的定位、Cascade 工作模型、上下文治理、MCP/Skills/Workflows/Hooks、安全邊界、模型用量和工具對比。"
verifiedAt: "2026-05-09"
---

這一組文章解決“會開啟 Windsurf 之後，怎麼真的用好”的問題。官方文件負責告訴你功能在哪裡；這裡負責告訴你真實專案裡應該先做什麼、少做什麼、哪些能力值得沉澱成團隊流程。

> [!NOTE]
> **先給結論**：Windsurf 的核心價值不是補全，而是把 IDE、程式碼上下文、Cascade、終端、規則、Hooks 和外部工具放進同一條開發軌道。用得好，它是編輯器內的專案協作者；用得差，它只是另一個會亂改檔案的聊天框。

## 官方能力地圖

Windsurf 官方 Getting Started 把它稱為 next-generation AI IDE，歡迎頁第一屏就把 Cascade、Usage、Terminal、MCP、Memories、Context Awareness、Advanced、Workflows、App Deploys 放在同一組入口裡。這說明 Windsurf 不是“補全外掛 + 聊天面板”，而是圍繞 IDE 現場組織的一套 agentic workflow。

官方 Cascade 頁面進一步說明了核心能力：Code / Chat 兩種模式、模型選擇、計劃和 Todo、queued messages、tool calling、voice input、named checkpoints 和 reverts、real-time awareness、Problems panel、Explain and Fix、`.codeiumignore`、linter integration、conversation sharing、previous conversation mention、simultaneous Cascades。

理解篇就按這個事實拆成四層：

| 層 | 官方能力 | 本系列學習重點 |
| --- | --- | --- |
| IDE 入口 | 安裝、onboarding、VS Code/Cursor 匯入、PATH、遠端開發 | 先讓編輯器、專案目錄、認證和只讀驗證穩定 |
| Cascade 執行 | Code/Chat、plans、tool calls、checkpoints、linter、Problems panel | 把任務拆成可回復的小閉環 |
| 上下文治理 | Fast Context、Memories、Rules、AGENTS.md、`.codeiumignore` | 哪些上下文自動進來，哪些必須排除或顯式規則化 |
| 擴充套件與治理 | MCP、Skills、Workflows、Hooks、Terminal、models、quota、Admin | 只在規則和命令邊界清楚後再擴充套件 |

這也是為什麼本系列從“第一次專案閉環”開始，而不是從 MCP、Skills 或團隊後臺開始。

## 8 篇閱讀路徑

<Cards>
  <Card title="Windsurf 是什麼" description="先確定它在 AI 程式設計工具堆疊裡的位置，不把它誤當成 Cursor 皮膚。" href="/zh-Hant/docs/windsurf/understanding/01-what-is-windsurf" />
  <Card title="第一次專案閉環" description="從只讀理解、單檔案修改、驗證回復開始，建立安全上手節奏。" href="/zh-Hant/docs/windsurf/understanding/02-first-project-loop" />
  <Card title="Cascade 心智模型" description="理解 Cascade 如何拿上下文、計劃任務、呼叫工具和管理 checkpoint。" href="/zh-Hant/docs/windsurf/understanding/03-cascade-mental-model" />
  <Card title="上下文與規則" description="把 Fast Context、Rules、AGENTS.md、Memories 和 .codeiumignore 放到正確位置。" href="/zh-Hant/docs/windsurf/understanding/04-context-rules-agents-md" />
  <Card title="MCP、Skills、Workflows" description="拆清外部工具、複雜能力包、手動流程和 Hooks 的邊界。" href="/zh-Hant/docs/windsurf/understanding/05-mcp-skills-workflows" />
  <Card title="命令安全" description="用 allow/deny list、人工確認和團隊 command control 管住終端風險。" href="/zh-Hant/docs/windsurf/understanding/06-terminal-command-safety" />
  <Card title="模型與用量策略" description="用任務風險、Adaptive 路由、quota 和團隊治理決定模型策略。" href="/zh-Hant/docs/windsurf/understanding/07-model-usage-strategy" />
  <Card title="工具對比" description="判斷 Windsurf、Cursor、Claude Code、Codex 分別應該放在哪一層。" href="/zh-Hant/docs/windsurf/understanding/08-windsurf-vs-cursor-claude-code-codex" />
</Cards>

## 適合誰讀

這組教程適合三類人：

- 已經在 VS Code / Cursor 寫程式碼，想試 Windsurf，但不想重新摸索一套 IDE。
- 已經會用 Claude Code / Codex，希望補一個編輯器內 agentic workflow。
- 團隊準備引入 AI coding 工具，需要先設規則、許可權、命令、MCP 和用量邊界。

不適合只想看功能截圖的人。這裡預設你關心的是長期工程效率、可控修改和團隊協作。

## 最小可執行路線

1. 先讀 [Windsurf 是什麼](/zh-Hant/docs/windsurf/understanding/01-what-is-windsurf)。
2. 按 [第一次專案閉環](/zh-Hant/docs/windsurf/understanding/02-first-project-loop) 在一個非生產分支跑一次。
3. 把專案規則寫入 `AGENTS.md`，排除敏感檔案。
4. 設定終端命令 allow/deny list。
5. 再接 MCP、Skills、Workflows 和 Hooks。
6. 最後再調整模型、quota 和團隊策略。

順序不要反。沒做好規則和命令邊界，就接 MCP 和自動化，只會把風險放大。

## 規則、Memory、Workflow、Skill 怎麼分

官方 Memories & Rules 頁面給了一個重要建議：需要 Cascade 穩定複用的知識，優先寫成 Rule 或儲存庫裡的 `AGENTS.md`，不要只依賴自動生成的 Memories。原因很實際：Rules 可版本控制、可共享、可指定觸發方式；Memories 是 Cascade 在對話中自動生成和本機儲存的上下文，更適合一次性事實或個人工作區事實。

| 機制 | 官方含義 | 實操判斷 |
| --- | --- | --- |
| Memories | Cascade 自動生成，本機 workspace 相關，存於 `~/.codeium/windsurf/memories/` | 只放短期或個人化上下文 |
| Rules | global、workspace、system 級人工規則 | 團隊規範和專案約定優先放這裡 |
| AGENTS.md | 目錄作用域規則，root 常駐，子目錄自動按路徑應用 | 已有 agent 規則體系時優先複用 |
| Workflows | 手動 slash command，重複多步驟任務 | 釋出、PR review、測試清單等人工觸發流程 |
| Skills | 帶 supporting files 的複雜任務能力包 | 需要指令碼、模板、參考檔案時再做 |
| Hooks | Cascade 行為前後自動執行 shell command | 審計、阻斷、格式化、校驗和企業治理 |

這張表是 Windsurf 團隊化落地的關鍵。把所有東西都寫進 always-on rule，會汙染每次對話；把團隊長期規則只留在 Memories，又不可控、不可審查。

## 透過標準

讀完這組理解篇，你應該能獨立完成一次安全匯入：

1. 在非生產分支開啟專案，並讓 Cascade 只讀解釋目錄結構。
2. 用 Chat mode 做理解，用 Code mode 做小範圍修改。
3. 修改前要求 Cascade 給出 plan、觸碰檔案和驗證命令。
4. 修改後檢查 diff、checkpoint、revert 路徑和 linter 輸出。
5. 用 `.codeiumignore` 排除金鑰、日誌、客戶資料和構建產物。
6. 用 `AGENTS.md` 或 `.windsurf/rules/` 寫專案規則。
7. 只允許 lint、test、build 這類低風險命令自動執行。
8. MCP、Skills、Workflows、Hooks 上線前能說明許可權和失敗處理。
9. 模型和 quota 有團隊策略，不讓每個人憑感覺選擇。

如果這些做不到，Windsurf 會變成“能力很多但不可控”的工具。做到這些，它才更像一個可治理的編輯器內協作者。

## 本組自檢

讀完整組後，用這 4 個問題檢查：

1. 你能不能用一句話解釋為什麼 Windsurf 不是聊天框、不是補全工具、也不是終端 agent？
2. 你能不能區分 Memories、Rules、AGENTS.md、Workflows、Skills、Hooks 的邊界？
3. 你能不能給真實儲存庫設定終端 allow/deny list 和 `.codeiumignore`？
4. 你能不能為團佇列出模型、命令、MCP、共享、SSO/SCIM 和排障的上線清單？

透過標準：你能在編輯器內把 Cascade 當成可治理的專案協作者使用，而不是又裝一個會亂改檔案的 agent 入口。

## 官方來源

- [Welcome to Windsurf](https://docs.windsurf.com/windsurf/getting-started) —— 官方安裝、onboarding、PATH 和首次嘗試入口。
- [Cascade Overview](https://docs.windsurf.com/windsurf/cascade/cascade) —— 官方 Cascade 全部能力總覽。
- [Memories & Rules](https://docs.windsurf.com/windsurf/cascade/memories) —— 官方 Rules、AGENTS.md、Workflows、Skills、Memories 對比表。
- [Windsurf llms.txt](https://docs.windsurf.com/llms.txt) —— 官方文件全量索引。
