Windsurf AI 编辑器完全指南：从安装到企业级工作流配置

# 方法一：Homebrew 安装（推荐）
brew install --cask windsurf

# 方法二：DMG 下载安装
# 访问 https://codeium.com/windsurf/download
# 下载 Windsurf_latest_x64.dmg 后双击拖入 Application

# 安装完成后，命令行验证
open -a Windsurf
# 首次启动会弹出登录窗口，用 Google/GitHub 账号免费登录

# 下载 AppImage
wget https://codeium.com/windsurf/download/linux -O windsarf.AppImage
chmod +x windsurf.AppImage

# 首次运行需要赋予执行权限
./windsurf.AppImage

# 如遇缺失依赖（Ubuntu 18.04），先安装：
sudo apt update && sudo apt install -y libgtk-3-0 libnss3 libxss1 libasound2

# 创建桌面快捷方式（可选）
cat > ~/.local/share/applications/windsurf.desktop << 'EOF'
[Desktop Entry]
Name=Windsurf
Exec=/path/to/windsurf.AppImage
Type=Application
Icon=windsurf
EOF

# 方法一：Scoop 包管理器（推荐）
scoop bucket add extras
scoop install windsurf

# 方法二：winget
winget install Codeium.Windsurf

# 方法三：手动安装
# 下载 Windsurf_latest_x64.exe 安装包，双击运行安装向导
# 默认安装路径：C:\Users\<用户名>\AppData\Local\Programs\Windsurf

# 步骤1：打开设置 Cmd/Ctrl + ,
# 步骤2：在左侧找到 "Model Menu" 或直接搜索 "model"

# 步骤3：在 "Custom Providers" 中添加：
{
  "provider": "openai",
  "name": "My-GPT-4",
  "api_key": "sk-xxxxxxxxxxxxxxxx",
  "base_url": "https://api.openai.com/v1",
  "model": "gpt-4-turbo"
}

# 或者配置 Claude（Anthropic）：
{
  "provider": "anthropic",
  "name": "My-Claude",
  "api_key": "sk-ant-xxxxxxxxxxxxxxxx",
  "model": "claude-3-5-sonnet-20240620"
}

# 配置本地 Ollama：
{
  "provider": "ollama",
  "name": "Local-Llama3",
  "base_url": "http://localhost:11434",
  "model": "llama3:70b"
}

# 在文件中选中需要 AI 处理的区域
# 按 Cmd/Ctrl + L 打开 Write 模式并生成代码

# 示例：选中以下注释描述，生成实际代码
# /* 生成一个支持并发控制的 Python 任务调度器，包含：
#    - 最大并发数限制（max_workers）
#    - 任务优先级队列
#    - 失败重试机制（最多3次）
#    - 任务完成回调
# */

import asyncio
from typing import Callable, Optional, List
from dataclasses import dataclass, field
from enum import IntEnum
import heapq

class TaskPriority(IntEnum):
    """任务优先级枚举，数字越小优先级越高"""
    CRITICAL = 0   # 关键任务（如支付、认证）
    HIGH = 1       # 高优先级（数据同步、实时计算）
    NORMAL = 2     # 普通任务（批量处理）
    LOW = 3        # 低优先级（报表生成）

@dataclass(order=True)
class Task:
    """
    任务数据结构，按优先级排序的堆元素
    priority: 优先级（用于堆排序，0最高）
    task_id: 唯一标识符
    callback: 任务执行函数
    max_retries: 最大重试次数
    current_retries: 当前已重试次数
    """
    priority: int
    task_id: str = field(compare=False)
    callback: Callable = field(compare=False, repr=False)
    max_retries: int = field(default=3, compare=False)
    current_retries: int = field(default=0, compare=False)

class TaskScheduler:
    """
    并发控制任务调度器
    
    使用 asyncio 优先级堆实现任务调度，
    支持最大并发数限制、失败重试、任务完成回调。
    
    使用示例：
        scheduler = TaskScheduler(max_workers=5)
        await scheduler.start()
        await scheduler.add_task(critical_func, priority=TaskPriority.CRITICAL)
        await scheduler.stop()
    """
    
    def __init__(self, max_workers: int = 5):
        """
        初始化调度器
        
        Args:
            max_workers: 最大并发执行的任务数
        """
        self.max_workers = max_workers
        self._active_tasks: int = 0  # 当前活跃任务计数
        self._task_heap: List[Task] = []  # 优先级堆
        self._running = False
        self._lock = asyncio.Lock()
        self._condition = asyncio.Condition(self._lock)
        self._results = {}  # task_id -> result
        self._callbacks: List[Callable] = []  # 完成回调列表
    
    async def start(self):
        """启动调度器（后台运行）"""
        self._running = True
        asyncio.create_task(self._worker_loop())
    
    async def stop(self):
        """停止调度器，等待所有任务完成"""
        self._running = False
        async with self._lock:
            pass  # 唤醒 worker
        # 等待活跃任务完成
        while self._active_tasks > 0:
            await asyncio.sleep(0.1)
    
    async def add_task(
        self,
        callback: Callable,
        priority: int = TaskPriority.NORMAL,
        task_id: Optional[str] = None,
        max_retries: int = 3
    ) -> str:
        """
        添加一个新任务到调度器
        
        Args:
            callback: 任务执行函数（可以是 async 或 sync 函数）
            priority: 优先级（默认 NORMAL）
            task_id: 任务ID（自动生成如果为 None）
            max_retries: 最大重试次数
        
        Returns:
            任务ID
        """
        if task_id is None:
            task_id = f"task_{id(callback)}_{asyncio.get_event_loop().time()}"
        
        task = Task(
            priority=priority,
            task_id=task_id,
            callback=callback,
            max_retries=max_retries
        )
        
        async with self._lock:
            heapq.heappush(self._task_heap, task)
            self._condition.notify()  # 唤醒一个等待中的 worker
        
        return task_id
    
    async def _worker_loop(self):
        """工作线程主循环，从堆中取出任务并执行"""
        while self._running:
            task = None
            
            async with self._lock:
                # 等待直到有任务或达到最大并发数
                while (self._active_tasks >= self.max_workers 
                       or not self._task_heap) and self._running:
                    await self._condition.wait()
                
                if self._task_heap and self._active_tasks < self.max_workers:
                    task = heapq.heappop(self._task_heap)
                    self._active_tasks += 1
            
            if task:
                asyncio.create_task(self._execute_task(task))
    
    async def _execute_task(self, task: Task):
        """执行单个任务，包含重试逻辑"""
        try:
            # 根据函数类型选择执行方式
            if asyncio.iscoroutinefunction(task.callback):
                result = await task.callback()
            else:
                result = task.callback()
            
            # 存储结果
            self._results[task.task_id] = {"status": "success", "result": result}
            
            # 触发完成回调
            for cb in self._callbacks:
                if asyncio.iscoroutinefunction(cb):
                    asyncio.create_task(cb(task.task_id, result))
                else:
                    cb(task.task_id, result)
                    
        except Exception as e:
            # 失败重试逻辑
            task.current_retries += 1
            if task.current_retries < task.max_retries:
                # 重新入堆，优先级略微降低（增加 priority 数值）
                async with self._lock:
                    retry_task = Task(
                        priority=task.priority + (task.current_retries * 10),
                        task_id=task.task_id,
                        callback=task.callback,
                        max_retries=task.max_retries,
                        current_retries=task.current_retries
                    )
                    heapq.heappush(self._task_heap, retry_task)
                    self._condition.notify()
                self._results[task.task_id] = {"status": "retry_scheduled", "retries": task.current_retries}
            else:
                # 超过最大重试次数，标记为失败
                self._results[task.task_id] = {"status": "failed", "error": str(e)}
        finally:
            async with self._lock:
                self._active_tasks -= 1
                self._condition.notify()  # 唤醒新的 worker
    
    def register_callback(self, callback: Callable):
        """注册任务完成回调函数"""
        self._callbacks.append(callback)
    
    def get_result(self, task_id: str) -> Optional[dict]:
        """获取任务执行结果"""
        return self._results.get(task_id)


# 使用示例
async def main():
    scheduler = TaskScheduler(max_workers=3)
    await scheduler.start()
    
    # 注册回调
    def on_complete(task_id, result):
        print(f"Task {task_id} completed: {result}")
    scheduler.register_callback(on_complete)
    
    # 添加不同优先级的任务
    await scheduler.add_task(
        lambda: print("执行关键任务"),
        priority=TaskPriority.CRITICAL
    )
    await scheduler.add_task(
        lambda: 1/0,  # 测试重试
        priority=TaskPriority.HIGH,
        max_retries=3
    )
    
    await asyncio.sleep(5)
    await scheduler.stop()
    print("调度器已停止")

if __name__ == "__main__":
    asyncio.run(main())

# 在 Chat 输入框中输入以下内容
@config.py
@utils/helpers.py
请解释这两个文件的依赖关系，以及为什么 config.py 会在 utils 之前加载？

# Windsurf 会自动解析这两个文件的AST依赖图，在回答时展示：
# 1. config.py 导入了哪些模块
# 2. utils/helpers.py 的导出内容
# 3. 二者之间的调用链

# 方法一：快捷键
Cmd/Ctrl + Shift + P 打开命令面板
输入 "Windsurf: Start Flow" 并回车

# 方法二：直接在 Cascade 面板输入任务描述，以 "/" 开头
# 示例：
/ 实现一个用户认证中间件，需要支持 JWT 和 OAuth2

# 方法三：选中代码后右键选择 "Ask Windsurf to..."
# Windsurf 会自动分析选中代码并生成改进建议

┌─────────────────────────────────────────────┐
│  🌊 Flow: 实现用户认证中间件                  │
├─────────────────────────────────────────────┤
│                                             │
│   INIT → PLAN → EXEC(1/4) → EXEC(2/4) → ... │
│                                             │
│   当前状态: EXEC(2/4)                        │
│   子任务列表:                                │
│   [✓] 1. 创建 auth/middleware.py 基础结构   │
│   [→] 2. 实现 JWT 验证逻辑                   │
│   [ ] 3. 实现 OAuth2 回调处理                │
│   [ ] 4. 编写单元测试                        │
│                                             │
│   最近修改:                                  │
│   修改了: auth/jwt_handler.py (行 23-67)    │
│   修改了: config/auth.yaml                  │
│                                             │
└─────────────────────────────────────────────┘

# 打断 Flow：按 Cmd/Ctrl + C 或点击 "Stop Flow" 按钮
# 继续 Flow：点击 "Resume Flow" 按钮
# 查看完整日志：点击 "View Detailed Log" 查看每个状态的输入输出

# 项目根目录结构
# .
# ├── .windsurf/
# │   ├── rules.md          # 全局规则
# │   ├── frontend.md       # 前端特定规则
# │   ├── backend.md        # 后端特定规则
# ├── src/
# ├── tests/
# └── package.json

# .windsurf/rules.md 示例（全局规则）
# 这个文件会被自动应用到整个项目

# === 代码风格 ===
- 使用 4 空格缩进（不是 Tab）
- 每行最大长度 120 字符
- 禁止使用 var，优先使用 const
- 函数命名使用 camelCase，类名使用 PascalCase

# === 提交规范 ===
- 所有 commit message 使用 Conventional Commits 格式
- feat: 新功能
- fix: 修复 bug
- docs: 文档更新
- style: 代码格式（不影响功能）
- refactor: 重构
- perf: 性能优化
- test: 测试
- chore: 构建/工具

# === 安全要求 ===
- 禁止在代码中硬编码密钥，必须使用环境变量
- 所有用户输入必须经过 sanitize
- API 路由必须有权限检查装饰器

# === 测试要求 ===
- 公共函数必须有对应单元测试
- 测试覆盖率不低于 80%
- 使用 mock 隔离外部依赖

# .windsurf/backend.md 示例（后端特定规则）

# === Python 后端规范 ===
- 使用 type hints 标注所有函数参数和返回值
- 异步函数用 async/await，禁止使用 threading
- 异常必须捕获并记录到 logger
- 配置文件使用 pydantic 的 BaseModel 验证

# === FastAPI 路由规范 ===
```python
# 正确示例
@router.post("/items/{item_id}", response_model=ItemResponse)
async def update_item(
    item_id: int,
    body: ItemUpdate,
    current_user: User = Depends(get_current_user)  # 必须有认证
) -> ItemResponse:
    """
    更新指定 ID 的物品
    
    Args:
        item_id: 物品唯一标识符
        body: 更新内容（pydantic 模型验证）
        current_user: 当前登录用户（自动从 JWT 提取）
    
    Returns:
        更新后的物品对象
    
    Raises:
        401: 未认证
        403: 无权限
        404: 物品不存在
    """
    # ... 实现逻辑
    pass

# 错误示例（ Windsurf 会自动标记并拒绝生成）
@router.post("/items/{item_id}")  # 缺少 response_model
async def update_item(item_id, body):  # 缺少类型标注
    pass
```

# === 数据库操作 ===
- 使用 SQLAlchemy 2.0 语法
- 所有查询使用 async session
- 禁止直接拼接 SQL 字符串
- 使用 Alembic 进行数据库迁移

# 在 Windsurf 中，每个项目就是一个 Workspace
# Workspace 配置存储在 .windsurf/workspace.json

# 示例：workspace.json
{
  "workspace_id": "my-project-prod",
  "project_path": "/Users/xiao/Dev/my-project",
  "model_config": {
    "default_model": "cascade-plus",
    "code_generation": "cascade-pro",
    "chat": "claude-3-5-sonnet"
  },
  "context_config": {
    "index_patterns": [
      "**/*.py",
      "**/*.js",
      "**/*.ts",
      "!**/node_modules/**",
      "!**/__pycache__/**",
      "!**/.venv/**"
    ],
    "max_files_in_context": 50,
    "include_test_files": true
  },
  "flow_config": {
    "auto_stop_on_error": true,
    "max_parallel_tasks": 3,
    "checkpoint_interval": 30
  }
}

# 设置工作区（命令行）
cd /path/to/your/project
windsurf workspace init

# 列出所有工作区
windsurf workspace list

# 切换工作区
windsurf workspace switch my-project-dev

# 切换工作区（GUI 操作）
# 1. 按 Cmd/Ctrl + P 打开命令面板
# 2. 输入 "Workspace: Switch"
# 3. 选择目标工作区

# 同步工作区配置到团队成员
# 在团队共享的代码库中，将 .windsurf 目录提交到 Git
# 新成员 clone 后，Windsurf 自动读取并应用规则

# macOS 清理 Keychain 并重试
# 1. 打开 "钥匙串访问" 应用
# 2. 搜索 "codeium" 并删除所有条目
# 3. 重启 Windsurf 并重新登录

# Linux 清理配置
rm -rf ~/.config/Windsurf/
rm -rf ~/.cache/windsurf/
open -a Windsurf  # 重启后重新登录

# 查看 Flow 详细日志
# 1. 在 Cascade 面板点击 "View Detailed Log"
# 2. 复制日志内容到本地分析

# 查看 Windsurf 进程日志（macOS）
cat ~/Library/Logs/Windsurf/windsurf.log

# 查看 Windsurf 进程日志（Linux）
cat ~/.config/Windsurf/logs/windsurf.log

# 解决方案：
# 1. 切换到更快的模型（Cascade Basic）
# 2. 减少上下文文件数量（降低 max_files_in_context）
# 3. 断开慢速网络，使用本地模型

# 配置本地 Ollama 加速（推荐）
# 安装 Ollama：
curl -fsSL https://ollama.com/install.sh | sh

# 下载模型：
ollama pull llama3:8b

# 在 Windsurf Model Menu 中添加 Ollama provider
# base_url: http://localhost:11434
# model: llama3:8b

# 测试延迟：
curl http://localhost:11434/api/generate -d '{"model":"llama3:8b","prompt":"hi","stream":false}'