---
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="/docs/windsurf/understanding/01-what-is-windsurf" />
  <Card title="第一次项目闭环" description="从只读理解、单文件修改、验证回滚开始，建立安全上手节奏。" href="/docs/windsurf/understanding/02-first-project-loop" />
  <Card title="Cascade 心智模型" description="理解 Cascade 如何拿上下文、计划任务、调用工具和管理 checkpoint。" href="/docs/windsurf/understanding/03-cascade-mental-model" />
  <Card title="上下文与规则" description="把 Fast Context、Rules、AGENTS.md、Memories 和 .codeiumignore 放到正确位置。" href="/docs/windsurf/understanding/04-context-rules-agents-md" />
  <Card title="MCP、Skills、Workflows" description="拆清外部工具、复杂能力包、手动流程和 Hooks 的边界。" href="/docs/windsurf/understanding/05-mcp-skills-workflows" />
  <Card title="命令安全" description="用 allow/deny list、人工确认和团队 command control 管住终端风险。" href="/docs/windsurf/understanding/06-terminal-command-safety" />
  <Card title="模型与用量策略" description="用任务风险、Adaptive 路由、quota 和团队治理决定模型策略。" href="/docs/windsurf/understanding/07-model-usage-strategy" />
  <Card title="工具对比" description="判断 Windsurf、Cursor、Claude Code、Codex 分别应该放在哪一层。" href="/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 是什么](/docs/windsurf/understanding/01-what-is-windsurf)。
2. 按 [第一次项目闭环](/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) —— 官方文档全量索引。
