SuperAPI AI 工具集

windsurf-sdk-patterns

编程与开发

查看项目

更新于 10-16 10:10

技能介绍

用途

本技能用于在 Windsurf IDE 中建立生产可用的配置体系,让 Cascade(Windsurf 的 AI 编程助手)遵循项目既定的技术栈、架构约定与安全要求。适用于希望把团队编码规范、目录分层、测试标准固定到 AI 上下文的开发者。

主要能力

1. 根级 .windsurfrules(持久上下文)

.windsurfrules 是影响 Cascade 输出质量最高的单个配置文件,为每次会话提供持久上下文。资料给出的示例以 payments-api 项目为例,声明了:

  • 技术栈:Node.js 20 LTS、TypeScript 5.x(strict、noUncheckedIndexedAccess)、Fastify v4、Drizzle(PostgreSQL)、zod、Vitest、Biome
  • 架构规则:路由处理放在 src/routes/(不含业务逻辑);业务逻辑放在 src/services/(不抛异常,使用 Result<T,E>);数据库查询放在 src/repositories/(仅用 Drizzle);共享类型放在 src/types/(均带 JSDoc 导出)
  • 禁止事项:不使用 any 类型、不使用默认导出、不使用基于 class 的模式(用函数 + 闭包)、未经明确要求不修改 migrations/ 中的文件、不使用已废弃 API(my_old_helper、legacyAuth)
  • 测试要求:每个 service 方法有单元测试、每个路由处理器有集成测试、集成测试不 mock 仓储、使用 tests/fixtures/ 中的夹具

限制:每个规则文件 6,000 字符;全局与工作区合计 12,000 字符。

2. 带触发模式的工作区规则

在 .windsurf/rules/ 目录中通过 YAML frontmatter 创建细粒度规则,支持三种触发模式:

  • glob:按文件路径匹配,例如测试文件规则(/*.test.ts、/.spec.ts)要求使用 describe/it 块而非 test()、用 msw mock 外部 API、断言成功与错误路径、UI 组件至少一个快照测试;API 路由规则(src/routes/**/.ts)要求先用 zod schema 校验输入、返回统一错误格式 { error, code, statusCode }、日志带请求 ID、不直接访问数据库
  • model_decision:由模型语义判断触发,例如涉及认证、授权或密钥的代码适用安全规则(不记录密钥/令牌/PII、使用参数化查询、用 jose 校验 JWT、公开端点限流、CORS 显式白名单)
  • manual:手动激活,例如通过 @migrations 触发的数据库迁移规则(可逆迁移、生产环境先弃用再删列、为外键列建索引、先在数据副本上测试)

3. MCP 服务器配置

通过 Model Context Protocol 把外部工具接入 Cascade,配置文件位于 ~/.codeium/windsurf/mcp_config.json,示例接入 github、postgres、memory 三个服务器,使用 npx 启动并通过环境变量传入令牌与数据库连接。需在 Windsurf Settings > Cascade > Model Context Protocol (MCP) 中启用。

工具限制:Cascade 所有 MCP 服务器合计最多支持 100 个工具,可在各 MCP 设置页禁用未使用的工具。

4. Cascade 提示词模式

资料给出高效提示词的对比:

  • 好的提示(具体、有范围):如“在 src/services/payment.ts 中添加 refundPayment 方法,调用 Stripe 退款 API,处理部分退款,返回 Result<Refund, PaymentError>”,或用 @src/routes/users.ts 指定文件并要求用 UserCreateSchema 校验、返回带字段级错误的 400
  • 差的提示(模糊、无范围):“给 API 加校验”“重构代码库”“让它更好”

使用方式

  1. 在项目根目录创建 .windsurfrules,写入技术栈、架构规则、禁止事项和测试要求
  2. 在 .windsurf/rules/ 下按主题创建规则文件,用 YAML frontmatter 指定 trigger(glob / model_decision / manual)
  3. 在 ~/.codeium/windsurf/mcp_config.json 中配置 MCP 服务器并在设置中启用
  4. 编写具体的、有文件范围限定的 Cascade 提示词

资料提供了一个项目健康检查命令:

ls -la .windsurfrules .codeiumignore .windsurf/rules/ 2>/dev/null

错误处理

  • 规则被 Cascade 忽略:文件超过 6,000 字符——精简并拆分到工作区规则
  • 工作区规则未加载:目录错误——必须是 .windsurf/rules/,而非 .windsurfrules/
  • MCP 服务器无法连接:命令找不到——确保 npx 能解析该包
  • MCP 工具过多:超出 100 工具上限——按服务器禁用未使用工具
  • glob 触发不生效:模式语法错误——使用 gitignore 风格 glob,如 **/*.test.ts

适用场景与限制

适用于已在 Windsurf 中认证并运行、理解 Cascade Write 与 Chat 模式区别、项目已有既定编码约定的团队。前置条件包括 Windsurf 认证可用。全局规则示例(~/.windsurf/global_rules.md,6,000 字符上限)包括:代码注释与提交信息一律用英文、优先函数式编程、写自解释代码、解释终端命令用途、不建议安装全局 npm 包。

资料未提供收费、价格、平台支持范围、性能数据或效果保证等信息。