Windsurf 安装指南
安装 Windsurf，熟悉 Cascade Agent，并用 Rules / MCP 支撑日常 AI 辅助开发。
概述
Windsurf（Codeium）是面向 AI 编程的 IDE，核心体验是 Cascade Agent：连贯地读代码、改多文件并调用工具。本篇覆盖安装、Cascade 入门与项目级开发实践。
前置条件
- 支持的桌面系统（Windows / macOS / Linux）
- Codeium / Windsurf 账号
- 建议准备一个 Git 项目作为练习仓库
安装与获取
- 访问 codeium.com/windsurf（或官方下载页）获取安装包
- 安装并启动 Windsurf
- 登录账户，完成首次引导
首次配置
- 打开 Cascade 面板，熟悉对话与 Flow / Agent 模式
- 导入或对齐常用编辑器快捷键（若从 VS Code 迁移）
- 在项目中按需创建
.windsurfrules（或官方当前推荐的项目规则位置），写清技术栈与验证命令 - 需要外部工具时，在 Settings → Tools / Cascade 中配置 MCP（见官方 Cascade MCP）
MCP 配置文件常见路径：~/.codeium/windsurf/mcp_config.json（Windows 为 %USERPROFILE%\.codeium\windsurf\mcp_config.json）。改完后在 Cascade 的 MCP 工具栏点刷新。
核心用法
- 提问：让 Cascade 解释模块职责、定位 bug
- 实现：描述可验收需求，允许其跨文件编辑
- 工具：通过 MCP 连接 GitHub、文档、数据库等（只开需要的服务器）
- 审阅：接受改动前检查 diff，再跑本地测试
示例提示：
在用户设置页增加深色模式开关，状态持久化；只改设置相关文件，改完说明如何手动验证。
开发实践
- 用 Git 管理项目，Agent 改动后小步提交
- 规则文件只保留「跨任务都成立」的约定；任务型长流程不要塞进全局规则
- 大功能先让 Cascade 出步骤，再分批执行
- MCP 令牌用最小权限；不要把 PAT 提交进仓库
- 与团队共享规则文件，个人偏好放本机设置
常见问题
- Cascade 无响应：检查登录状态、网络与模型额度
- MCP 不生效：确认 JSON 合法、Docker（若本地服务器需要）在跑，并点击 Refresh
- 改动范围过大：提示里限定目录与文件类型