windsurf的配置和项目规则、工作流、agent技巧使用

Windsurf 在前端开发中的落地实践：以 Vue3 + TypeScript 后台项目为例

导读

这篇文章不是泛泛而谈的"工具介绍"，而是基于我当前真实前端项目整理出来的一套可落地实践。

如果你正准备在 Vue 3 + TypeScript + Vite 项目里把 Windsurf 用起来，建议重点看下面这几个部分：

MCP 应该怎么配
Workflow 为什么是工程提效核心
项目规则和全局规则怎么分层
Memory 应该记什么，不该记什么
Skill 和 Agent 在前端场景里怎么落地
如何基于当前项目做一套自己的 AI 工程协作方案

一、windsurf常用的配置介绍

如果你是前端开发工程师，尤其是负责中后台项目、管理后台、业务配置平台这类复杂工程，那么 Windsurf 不只是一个"会补代码"的 AI 工具，它更适合作为一个真正参与工程协作的智能开发助手。

这篇文章我结合自己当前项目的实际配置，系统介绍前端工程里如何使用 Windsurf，包括：

MCP 如何配置与使用
Workflow 工作流怎么设计
项目规则与全局规则如何约束 AI 输出
Memory 记忆机制怎么服务持续开发
Skill、Agent 应该如何理解和规范使用
在真实 Vue 3 + TS + Vite 项目中的推荐实践

本文内容基于我当前正在使用的前端项目整理，项目技术栈如下：

text 复制代码

Vue 3 + TypeScript + Vite + Element Plus + Tailwind CSS + Vue Router + Pinia + vue-request + Playwright + Vitest

项目名称：uni-platform-admin

从工程角度看，这是一个典型的前端后台管理系统项目，因此非常适合用来说明 Windsurf 在真实业务开发中的价值。

二、我当前项目里的 Windsurf 配置结构

我当前项目里和 Windsurf 相关的目录主要有这些：

text 复制代码

.windsurf/
├── doc/
├── rules/
│   └── projectrules.md
└── workflows/
    ├── 1-实施修复须遵守SOP.md
    ├── 2-根因分析与建议SOP.md
    ├── 3-开发文档撰写SOP.md
    ├── 4-可行性分析SOP.md
    ├── 5-开发文档实施SOP.md
    ├── 6-自动化测试SOP.md
    ├── 7-代码规范.md
    └── 8-后台管理开发SOP.md

这套结构非常适合前端项目长期使用：

rules 负责约束 AI 输出风格和工程边界
workflows 负责把复杂任务变成标准 SOP
doc 负责沉淀过程文档、方案文档、文章草稿、交付说明

如果你是团队开发，我建议把这三类内容都放进仓库统一维护，这样 AI 输出会稳定很多。

三、为什么前端工程师要认真配置 Windsurf

很多人第一次接触 AI 编码工具，只是把它当成代码补全工具。但在真实前端项目里，真正耗时的不是"写一行代码"，而是下面这些事情：

理解现有工程结构
找到正确修改点
遵守团队规范
保持类型安全
不破坏路由、权限、状态、接口链路
编写测试与文档
避免 AI 胡乱生成不存在的实现

所以，前端工程里使用 Windsurf，核心思路不是"让 AI 更自由"，而是：

让 AI 在清晰的规则、流程和上下文下稳定工作。

这也是为什么我会重点配置：

MCP
工作流
项目规则
全局规则
记忆
Agent / Skill 使用规范

四、当前项目的前端工程背景

为了让文章更贴近实际，先看一下当前项目本身：

1. 项目技术栈

根据 package.json，当前项目核心依赖如下：

vue@3.5.26
typescript@~5.9.3
vite@^7.3.0
element-plus@^2.13.6
vue-router@^4.6.4
pinia@^3.0.4
vue-request@^2.0.4
axios@^1.13.2
@playwright/test@^1.57.0
vitest@^4.0.16
tailwindcss@^4.1.18

2. 项目脚本

项目里已经具备标准化脚本：

bash 复制代码

pnpm run dev
pnpm run build
pnpm run preview
pnpm run type-check
pnpm run lint
pnpm run lint:oxlint
pnpm run lint:eslint
pnpm run format
pnpm run test:unit
pnpm run test:e2e

这意味着 Windsurf 在这个项目中，不仅可以辅助写代码，还可以围绕以下环节工作：

开发
构建
规范检查
类型检查
单测
E2E 自动化测试
文档编写

五、MCP 是什么，前端工程为什么一定要配

1. MCP 的作用

MCP 可以理解为 Windsurf 的"外接能力接口"。

有了 MCP，AI 不再只能依赖模型记忆，而是可以真正调用外部能力，例如：

查官方文档
操作浏览器
跑自动化测试
获取上下文资源

对于前端工程师来说，MCP 的价值非常明显，因为前端开发高度依赖：

官方 API 文档
浏览器交互调试
页面自动化验证
与现有工程结构的联动

2. 我当前使用场景里的重点 MCP

从当前使用习惯来看，前端项目最值得配置的是两个方向：

`Context7`

适合查最佳实践和最新官方文档，例如：

Vue 3 组合式 API
Vite 配置
Element Plus 组件用法
Playwright 测试 API
Tailwind 写法
Pinia 状态管理
vue-request 的使用规范

在复杂项目中，AI 如果不查文档，极容易输出"似是而非"的代码。尤其是版本变化快的前端生态，这一点非常关键。

`Playwright MCP`

这个能力对前端工程师尤其有价值，因为它可以直接做：

页面点击
表单输入
读取控制台
查看网络请求
获取页面快照
辅助排查前端交互问题

对于后台项目来说，很多 bug 不只是代码层问题，而是交互链路问题 。这个时候浏览器级的 MCP 能大幅提升排查效率。

如果需要还可以把figma【是进行原型图 的开发给产品经理使用的】也配置进去；下面是MCP配置代码：

复制代码

{
  "mcpServers": {
    "context7": {
        "command": "npx",
        "args": [
            "-y",
            "@upstash/context7-mcp@latest"
        ]
    },
    "io.windsurf/figma-remote-mcp-server": {
      "registry": "io.windsurf/figma-remote-mcp-server",
      "url": "https://mcp.figma.com/mcp"
    },
    "io.windsurf/mcp-playwright": {
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ],
      "command": "npx",
      "disabled": false,
      "registry": "io.windsurf/mcp-playwright"
    }
  }
}

3. 前端工程师如何配置 MCP

不同版本的 Windsurf 配置界面可能有差异，但配置原则基本一致：

接入官方或可用的 MCP Server
优先接入文档查询类 MCP
前端项目优先接入 Playwright 相关 MCP
对需要联网、执行外部操作的能力进行明确授权控制
明确哪些 MCP 是"查资料"，哪些 MCP 是"执行动作"

4. 前端项目推荐的 MCP 使用策略

我建议按下面这套优先级来配置：

第一优先级：文档类 MCP
第二优先级：浏览器自动化类 MCP
第三优先级：资源检索类 MCP
第四优先级：外部系统集成类 MCP

如果你是做 Vue 管理后台，这套优先级足够覆盖 80% 以上场景。

5. MCP 在当前项目里的典型用法

结合我当前项目，AI 适合这样使用 MCP：

做 Element Plus 表单时，先查官方 API
修改 vue-request 请求逻辑时，先查文档最佳实践
写 Playwright E2E 测试时，通过浏览器能力复现流程
调试后台页面时，检查请求链路和页面行为是否一致

一句话总结：

MCP 不是可选项，而是让 Windsurf 从"聊天工具"升级为"工程助手"的关键能力。

6. 一套适合前端工程的 MCP 配置思路

如果你是第一次配 MCP，我建议按"先够用，再完善"的思路来做，不要一上来就接太多能力。

第一步：先接文档类 MCP

先把和前端日常开发最相关的官方文档能力接进来，优先覆盖：

Vue
TypeScript
Vite
Element Plus
Tailwind CSS
Pinia
Playwright
vue-request

这样做的核心价值是：当 AI 遇到 API 细节、版本差异、配置写法时，可以优先查官方资料，而不是凭经验猜。

第二步：再接浏览器自动化类 MCP

前端项目和普通后端项目最大的不同在于，你经常需要验证：

页面是否真的能点
表单是否真的能提
路由跳转是否正确
接口请求是否按预期发出
控制台是否有报错

所以浏览器类 MCP 对前端工程不是锦上添花，而是非常实用的验证能力。

第三步：给 MCP 设定使用边界

MCP 越强，越需要边界。前端项目里我建议至少明确这几条：

文档类 MCP 优先用于"查最佳实践"
浏览器类 MCP 优先用于"验证页面行为"
涉及联网、执行动作、读取外部信息时要明确授权
不要让 AI 跳过项目规则直接按照 MCP 查询结果胡乱重构

六、工作流 Workflow 怎么配，为什么这是团队提效核心

如果说规则是边界，那么 Workflow 就是执行路径。

我当前项目已经定义了多套工作流：

1-实施修复须遵守SOP
2-根因分析与建议SOP
3-开发文档撰写SOP
4-可行性分析SOP
5-开发文档实施SOP
6-自动化测试SOP
7-代码规范SOP
8-后台管理开发SOP

这类配置对于前端工程非常有用，因为前端任务经常不是单一步骤，而是一个完整闭环：

text 复制代码

需求理解 -> 分析现有代码 -> 制定方案 -> 修改页面 -> 联调接口 -> 检查规范 -> 编写测试 -> 输出文档

1. 我当前工作流设计的特点

从现有文件内容来看，这些 workflow 有几个非常明显的特征：

面向实际开发场景，而不是空泛描述
明确要求最小改动方案
明确要求查官方文档
明确禁止硬编码和降级方案
明确要求通过 lint、type-check、测试
明确要求围绕当前工程结构实施

这说明工作流不是"给 AI 看看"，而是把团队真实开发 SOP 固化给 AI。

2. 举几个工作流的实际价值

`1-实施修复须遵守SOP`

这个工作流强调：

先定位问题
查官方文档
明确根因与影响面
输出最小改动方案
不改无关逻辑
最终通过 ESLint 检查

这对前端排错非常重要，因为前端问题往往会牵涉：

组件 Props / Emits
路由跳转
Pinia 状态
权限逻辑
接口调用链
样式冲突

`6-自动化测试SOP`

这个工作流直接规定了测试体系：

单元/组件测试：Vitest + Vue Test Utils
E2E 测试：Playwright
关键业务流要有覆盖
测试目录和脚本都要规范

对于后台管理系统，这能保证 AI 不是"只会改页面"，而是知道怎么验证。

`8-后台管理开发SOP`

这个工作流特别适合管理后台项目，覆盖了：

权限
表格
表单
导入导出
路由守卫
Pinia 状态
性能与可用性
风险与回滚

这类 SOP 非常适合中大型前端项目，因为 AI 会天然倾向于只改界面，但真正业务开发远不止 UI。

3. Workflow 推荐写法

一个高质量工作流，建议至少包含这些部分：

适用场景
技术栈约束
实施步骤
风险提示
验证方式
项目脚本引用
最终检查清单

4. 前端项目推荐工作流分类

如果你想从 0 到 1 搭建自己的工作流体系，我建议至少准备这几类：

缺陷修复类：排查、修复、回归验证
功能开发类：页面、表单、表格、弹窗、权限
文档输出类：需求方案、技术设计、交付说明
测试类：单测、E2E、性能验证
代码规范类：命名、目录、请求、样式、组件拆分

七、项目规则 Project Rules 怎么写，为什么它决定 AI 输出质量

我当前项目里的项目规则文件是：

text 复制代码

.windsurf/rules/projectrules.md

它本质上是一份针对当前前端项目的工程规范说明书。

1. 我当前规则里已经覆盖的重点

从文件内容看，已经覆盖了这些关键领域：

代码风格规范
TypeScript 规范
Vue 组件规范
页面请求规范
CSS 样式规范
项目架构规范
Git 规范
代码质量检查

这套规则对前端工程非常完整，尤其适合 Vue 后台项目。

2. 当前规则中最值得保留的约束

结合当前 projectrules.md，我认为最有价值的点有这些：

代码风格统一

2 空格缩进
单引号
不使用分号
单行长度限制

这可以显著减少 AI 输出与项目风格不一致的问题。

TypeScript 严格类型

禁止滥用 any
优先使用 interface
联合类型和交叉类型用 type
可选属性使用 ?

这对于前端工程尤其重要，因为 AI 很喜欢在不确定时使用 any 糊弄过去。

Vue SFC 结构顺序

规则已经明确了组件内部推荐顺序：

类型定义
Props
Emits
响应式数据
计算属性
方法

这能有效提高多人协作和 AI 输出一致性。

请求统一使用 `vue-request`

这一条非常关键。

因为在真实项目中，如果 AI 一会儿用 fetch，一会儿直接 axios，一会儿又绕开现有请求封装，最终项目会很乱。

而当前规则明确要求：

统一使用 useRequest
显式处理 loading
参数和返回值要类型安全
支持节流和防抖场景

这就是典型的"工程规则优先于模型自由发挥"。

样式优先 Tailwind

规则里也明确了：

优先用 Tailwind
尽量少写 <style>
避免任意值泛滥
保持设计风格统一

这对前端 AI 输出很有帮助，因为 AI 很容易在样式层面过度自由发挥。

3. 项目规则的本质

项目规则不是为了写给人看，而是为了让 AI 明确知道：

这个项目允许怎么写
这个项目禁止怎么写
这个项目已有的架构原则是什么
这个项目验收标准是什么

4. 前端项目规则推荐内容

我建议前端工程的项目规则至少包含：

技术栈版本约束
目录结构约束
组件规范
请求规范
状态管理规范
路由规范
UI 与样式规范
测试规范
提交规范
脚本与质量门禁

如果这些没有写清楚，AI 很容易写出"能跑但不适合当前项目"的代码。

八、全局规则 Global Rules 怎么理解，应该放什么

项目规则解决的是"这个仓库怎么干活"，而全局规则解决的是"你希望 AI 一直以什么方式和你协作"。

对于前端工程师来说，全局规则非常重要，因为很多习惯是跨项目的。

1. 全局规则适合放什么

我建议全局规则优先放下面这些内容：

回复语言
沟通风格
是否优先直接改代码
复杂任务是否必须先给计划
是否优先用官方文档
调试时的基本原则
测试工具优先级
对硬编码、降级方案的态度
对代码规范、可维护性的要求

2. 结合我当前使用习惯，前端工程常见全局规则示例

下面这些规则就很适合作为全局规则：

始终使用中文回复
回答要简洁明了
复杂任务优先给计划
优先查官方文档最佳实践
前端测试优先使用 Playwright
保证代码通过 ESLint，不引入新的规范问题
注重边界处理、健壮性和可维护性
禁止用硬编码或降级方案掩盖真实问题
单文件不要过大，要按功能拆分
命名要见名知意

3. 为什么全局规则不能写得太散

如果全局规则写太多、太碎、太口语化，会有两个问题：

AI 抓不到重点
不同规则之间容易冲突

我建议全局规则聚焦在"长期稳定有效"的共性习惯上，而不是写太多项目细节。

项目细节放 projectrules.md，全局偏好放 Global Rules，这样层次最清晰。

4. 一份适合前端工程师的全局规则模板

如果你想给自己准备一份更实用的全局规则，我建议写成"短规则 + 强约束"的形式，避免长篇空话。

下面这份模板就比较适合前端工程场景：

text 复制代码

1. 始终使用中文回复，保持结论清晰。
2. 复杂任务先给计划，再实施。
3. 优先依据官方文档和当前仓库真实代码，不猜测不存在的 API。
4. 前端项目优先遵守 Vue 3 + TypeScript + Vite 最佳实践。
5. 页面请求优先复用现有请求封装，不绕开项目约定。
6. 样式优先复用现有 UI 体系和 Tailwind 约束，不随意新增大量 scoped 样式。
7. 禁止用硬编码、降级方案或假数据掩盖真实问题。
8. 改动前先分析影响面，避免修改无关逻辑。
9. 输出代码必须可维护、可读，并尽量通过 lint / type-check。
10. 前端测试优先使用 Playwright，必要时补充 Vitest。

下面是我具体代码全局规则配置可以参考：
全局规则global_rules.md

复制代码

基本对话规则
1. 总是用中文回复我
2. 保持对话的连贯性和逻辑性
3. 如果我问的问题很简短，你可以适当的扩展问题，给出更详细的回答
4. 回答要简洁明了，不要啰嗦

基本开发准则
1. 保证代码规范eslint里面不报红报错，保持代码的可读性和可维护性
2. 注重代码的健壮性，处理各种边界情况
3. 代码要注释清晰，方便他人理解和维护
4. 代码要模块化，方便复用和维护
5. 代码要简洁，避免过度设计
6. 重启动文件必须在根目录
7. 时间使用北京时间
8. 代码要遵循单一职责原则
9. 查json数据的时候，用jq工具，查询svg或xml数据是用xmlstarlet工具
10. 备份文件放在backups文件夹中
11. 禁止使用硬编码或降级方案来掩盖真实的问题
12. 单个文件不要过大，要按功能模块分块
13. 数据表，字段，备注，方法，参数等要规范命名，见名知意，不能涉及具体的服务提供商名称；
14. 按照开发文档实施复杂任务的时候，需要遵守每个步骤任务的要求，不要偏离范围或遗漏

最佳实践查询规则
1. 优先使用MCP Context7 查找官方文档最佳实践
2. 查询最佳实践时，要结合上下文和具体场景，给出最合适的建议
3. 不要重复询问用户已经回答过的问题
4. 询问用户的时候，要简洁明了，不要啰嗦
5. 询问用户的时候，要给出选项，不要让用户自己输入

前端测试规则
1. 前端测试优先使用MCP Playwright

项目规则配置projectrules.md

复制代码

# Vue + TypeScript 项目开发规范

## 概述

本文档为 Vue 3 + TypeScript + Element Plus + Axios + vue-request 项目提供完整的开发规范，旨在确保代码一致性、可维护性和高质量。

## 目录

- [代码风格规范](#代码风格规范)
- [TypeScript 规范](#typescript-规范)
- [Vue 组件规范](#vue-组件规范)
- [页面请求规范](#页面请求规范)
- [CSS 样式规范](#css-样式规范)
- [项目架构规范](#项目架构规范)
- [Git 规范](#git-规范)
- [代码质量检查](#代码质量检查)

---

## 代码风格规范

### 基本规则

1. **缩进**：使用 2 个空格进行缩进
2. **换行**：使用 LF (Unix 风格) 换行符
3. **行宽**：每行最大 100 字符
4. **分号**：不使用分号（项目已配置 Prettier）
5. **引号**：使用单引号（项目已配置 Prettier）
6. **对象括号**：不使用空格（项目已配置 Prettier）

### 命名规范

#### 文件和目录命名

- **组件文件**：使用 PascalCase（首字母大写），如 `HelloWorld.vue`
- **其他文件**：使用 kebab-case（短横线连接），如 `date-helper.ts`
- **目录**：使用 kebab-case（短横线连接），如 `components/icons/`

#### 变量和函数命名

- **变量**：使用 camelCase（小驼峰），如 `userData`
- **常量**：使用 UPPER_SNAKE_CASE（大写蛇形），如 `MAX_ITEMS`
- **函数**：使用 camelCase（小驼峰），如 `getUserData()`
- **类型/接口**：使用 PascalCase（首字母大写），如 `UserProfile`
- **枚举**：使用 PascalCase（首字母大写），成员使用 UPPER_SNAKE_CASE
- **私有属性**：使用 `_` 前缀，如 `_privateMethod()`

```typescript
// 好的命名
const MAX_ITEMS = 10
const userData = {
  firstName: 'John',
  lastName: 'Doe',
}

interface UserProfile {
  id: number
  email: string
}

function getUserData(): UserProfile {
  // ...
}
```

---

## TypeScript 规范

### 类型声明

#### 严格类型检查

项目已启用严格类型检查，禁止使用 `any` 类型：

```typescript
// 禁止
function processData(data: any) {
  // ...
}

// 推荐
interface DataStructure {
  id: number
  name: string
}

function processData(data: DataStructure) {
  // ...
}
```

#### 接口与类型别名

- 优先使用 `interface` 定义数据结构
- 使用 `type` 定义类型别名、联合类型和交叉类型

```typescript
// 接口（推荐用于对象类型）
interface Product {
  id: number
  name: string
  price: number
}

// 类型别名（推荐用于联合类型、交叉类型）
type Status = 'active' | 'inactive' | 'pending'
type ProductWithStatus = Product & {status: Status}
```

#### 可选属性

使用 `?` 标记可选属性，避免使用 `undefined` 类型联合：

```typescript
// 好的做法
interface User {
  id: number
  name: string
  email?: string // 可选属性
}
```

---

## Vue 组件规范

### 组件结构

#### SFC 基本结构

使用 `<script setup lang="ts">` 语法，按以下顺序组织代码：

```vue
<script setup lang="ts">
import {ref, computed} from 'vue'

// 1. 类型定义
interface Props {
  title: string
  subtitle?: string
}

// 2. Props 定义
const props = withDefaults(defineProps<Props>(), {
  subtitle: '默认副标题',
})

// 3. Emits 定义
const emit = defineEmits<{
  'update:model-value': [value: string]
  'item-click': [item: any, index: number]
}>()

// 4. 响应式数据
const count = ref(0)

// 5. 计算属性
const doubleCount = computed(() => count.value * 2)

// 6. 方法
const increment = () => {
  count.value++
  emit('update:model-value', String(count.value))
}
</script>

<template>
  <div class="component-name">
    <h1>{{ props.title }}</h1>
    <p>{{ props.subtitle }}</p>
    <el-button @click="increment">Count: {{ count }}</el-button>
  </div>
</template>

<style scoped>
.component-name {
  padding: 20px;
}
</style>
```

### Props 规范

- 使用 TypeScript 接口定义 Props 类型
- 使用 `withDefaults` 提供默认值
- Props 名称使用 camelCase
- 避免使用 `v-bind` 绑定简单类型

```typescript
// 推荐
interface Props {
  userId: number
  userName?: string
}

const props = withDefaults(defineProps<Props>(), {
  userName: 'Guest',
})
```

### Emit 规范

- 使用类型声明定义 Emit 事件
- 事件名称使用 kebab-case
- 事件处理函数使用 camelCase
- 使用 `defineEmits` 类型参数语法

```typescript
const emit = defineEmits<{
  'update:model-value': [value: string]
  'item-click': [item: Item, index: number]
}>()

// 调用
emit('item-click', item, index)
```

### 响应式数据

- 使用 `ref()` 定义基本类型响应式数据
- 使用 `reactive()` 定义对象类型响应式数据
- 避免过度使用 `ref()` 包装对象
- 大型数据使用 `shallowRef` 或 `shallowReactive` 优化性能

```typescript
// 基本类型
const count = ref(0)

// 对象类型（推荐使用 reactive）
const user = reactive<{name: string; age: number}>({
  name: 'John',
  age: 30,
})

// 大型数据（推荐使用 shallowRef）
const largeData = shallowRef({
  /* 大量数据 */
})
```

---

## 页面请求规范

### 基本规则

1. **统一使用 vue-request**：项目中所有页面请求必须使用 `vue-request` 库进行管理
2. **导入规范**：在组件中导入 `useRequest` 函数
3. **类型安全**：确保请求参数和返回值都有正确的 TypeScript 类型定义

### 核心功能使用

#### Loading 状态管理

- 使用 `useRequest` 返回的 `loading` 状态来控制 UI 加载状态
- 在表单提交、数据获取等操作中，使用 `:loading` 属性绑定到按钮或其他 UI 元素

```vue
<template>
  <el-button :loading="loading" @click="handleLogin">登录</el-button>
</template>

<script setup lang="ts">
import {useRequest} from 'vue-request'
import {iamAuth} from '@/service/api/iamAuth'

const {runAsync, loading} = useRequest(iamAuth.iamAuthLogin)

const handleLogin = async () => {
  await runAsync({
    /* 登录参数 */
  })
}
</script>
```

#### 节流和防抖

- **节流 (throttle)**：适用于频繁触发的操作，如获取验证码、搜索输入等
- **防抖 (debounce)**：适用于需要等待用户输入完成后再执行的操作

```typescript
// 节流示例 - 验证码获取
const reqImgCode = useRequest(iamAuth.iamAuthGetImgCode, {
  throttleInterval: 500, // 500ms 内最多执行一次
})

// 防抖示例 - 搜索
const reqSearch = useRequest(searchApi, {
  debounceInterval: 300, // 300ms 内无操作才执行
})
```

---

## CSS 样式规范

优先使用 Tailwind 写 CSS，而不是写在 <style></style> 中

### 使用原则

- **优先使用内置类**：尽量使用 Tailwind 提供的内置类，避免使用自定义值
- **避免过度定制**：如果已有合适的内置类（如 `px-3`），避免使用任意值（如 `px-[12px]`）
- **语义化命名**：使用语义化的类名，避免使用难以理解的简写
- **统一风格**：项目内保持一致的设计风格，使用相同的间距、颜色和字体

### 类名使用规范

#### 优先使用内置类

```vue
<!-- 推荐 -->
<div class="px-3 py-2">
  内容
</div>

<!-- 尽量避免 - 使用任意值替代内置类 -->
<div class="px-[12px] py-[8px]">
  内容
</div>
```

#### 避免过度使用任意值

```vue
<!-- 推荐 -->
<div class="bg-blue-500 text-white rounded-lg shadow-md">
  按钮
</div>

<!-- 禁止 - 过度使用任意值 -->
<div class="bg-[#2563eb] text-[#ffffff] rounded-[0.5rem] shadow-[0_4px_6px_rgba(0,0,0,0.1)]">
  按钮
</div>
```

### 自定义配置

- 仅在必要时扩展 Tailwind 配置
- 在 `tailwind.config.js` 中统一管理自定义配置
- 避免在组件中硬编码样式

```javascript
// tailwind.config.js
/** @type {import('tailwindcss').Config} */
export default {
  content: ['./index.html', './src/**/*.{vue,js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#eff6ff',
          500: '#3b82f6',
          600: '#2563eb',
        },
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
      },
    },
  },
  plugins: [],
}
```

### 性能优化

- 避免过度使用类名组合
- 合理使用 `@layer` 指令组织自定义样式
- 避免在模板中使用复杂的计算属性生成类名

```vue
<!-- 推荐 -->
<div class="flex items-center justify-between p-4 bg-white rounded-lg">
  <h1 class="text-lg font-semibold">标题</h1>
  <button class="px-3 py-1 text-sm bg-blue-500 text-white rounded">
    按钮
  </button>
</div>

<!-- 禁止 - 过度复杂的类名组合 -->
<div
  class="flex items-center justify-between p-4 bg-white rounded-lg hover:bg-gray-50 transition-colors duration-200"
>
  <h1 class="text-lg font-semibold text-gray-900">标题</h1>
  <button class="px-3 py-1 text-sm bg-blue-500 text-white rounded hover:bg-blue-600 transition-colors duration-200">
    按钮
  </button>
</div>
```

---

## 项目架构规范

### 目录结构

```
src/
├── assets/           # 静态资源
│   ├── base.css      # 基础样式
│   ├── logo.svg      # 项目 Logo
│   └── main.css      # 主样式
├── common/           # 通用配置
├── components/       # 通用组件
│   └── icons/        # 图标组件
├── router/           # 路由配置
├── stores/           # Pinia 状态管理
├── views/            # 页面组件
├── App.vue           # 根组件
└── main.ts           # 入口文件
```

### 导入规范

- 使用路径别名 `@/` 代替相对路径
- 导入顺序：Vue 核心 API → 第三方库 → 项目组件 → 样式

```typescript
// 禁止 - 相对路径
import {formatDate} from '../../utils/date-helper'

// 推荐 - 使用路径别名
import {formatDate} from '@/utils/date-helper'

// 推荐的导入顺序
import {ref, computed} from 'vue'
import {useRoute} from 'vue-router'
import HelloWorld from '@/components/HelloWorld.vue'
import '@/assets/main.css'
```

---

## Git 规范

### 分支命名

```
<type>/<description>
```

**类型说明：**

- `feature/` - 新功能开发
- `fix/` - 错误修复
- `refactor/` - 代码重构

**示例：**

```
feature/xx新功能开发
fix/修复xx错误
refactor/xx代码重构
```

### Commit 规范

使用 Conventional Commits 规范：

```
<type>(<scope>): <subject>

<body>

<footer>
```

**类型说明：**

- `feat` - 新功能
- `fix` - 错误修复
- `docs` - 文档更新

**示例：**

```
feat: 添加用户管理页面 (#123)

- 新增用户列表组件
- 实现用户搜索功能
- 添加用户详情页面

BREAKING CHANGE: 移除了旧的用户API
```

### 代码提交检查

项目配置了以下提交前检查：

- TypeScript 类型检查
- ESLint 代码规范检查
- Oxlint 快速代码检查
- Prettier 格式化检查

---

## 代码质量检查

### 运行检查命令

```bash
# 启动开发服务器
pnpm run dev

# 构建项目（包括类型检查）
pnpm run build

# 预览构建结果
pnpm run preview

# TypeScript 类型检查
pnpm run type-check

# 代码规范检查和修复（oxlint + eslint）
pnpm run lint

# 仅运行 oxlint 检查
pnpm run lint:oxlint

# 仅运行 eslint 检查
pnpm run lint:eslint

# 格式化代码
pnpm run format
```

### 常见问题修复

1. **类型错误**

   ```bash
   pnpm run type-check
   # 查看并修复类型错误
   ```

2. **代码规范问题**

   ```bash
   pnpm run lint
   # 自动修复大部分规范问题
   ```

3. **格式化问题**
   ```bash
   pnpm run format
   # 自动格式化代码
   ```

---

## 最佳实践

### 性能优化

1. **避免过度渲染**
   - 使用 `v-memo` 优化列表渲染
   - 合理使用 `v-show`（频繁切换）和 `v-if`（条件渲染）
   - 避免在模板中使用复杂计算

2. **代码分割**
   - 使用动态导入优化首屏加载
   - 懒加载组件
   - 按需加载第三方库

3. **响应式优化**
   - 使用 `shallowRef` 和 `shallowReactive` 优化大型数据
   - 避免在计算属性中使用副作用
   - 使用 `toRefs` 解构响应式对象

### 组件设计

1. **单一职责原则**
   - 每个组件只负责一个功能

2. **可复用性**
   - 抽取通用逻辑到组合式函数
   - 设计可配置的组件接口

3. **可测试性**
   - 组件逻辑与 UI 分离
   - 使用组合式函数提高可测试性

### 安全建议

1. **XSS 防护**
   - 避免使用 `v-html`
   - 对用户输入进行适当转义

2. **API 安全**
   - 使用 HTTPS
   - 验证和消毒输入数据
   - 实现适当的权限控制

---

## 工具和插件

### 推荐的 VS Code 插件

- Vue Language Features (Volar)
- TypeScript Vue Plugin
- ESLint
- Prettier - Code formatter
- Oxlint
- Vite

### 配置文件

| 配置文件             | 用途                    |
| -------------------- | ----------------------- |
| `tsconfig.json`      | TypeScript 根配置       |
| `tsconfig.app.json`  | 应用 TypeScript 配置    |
| `tsconfig.node.json` | Node.js TypeScript 配置 |
| `vite.config.ts`     | Vite 构建配置           |
| `eslint.config.ts`   | ESLint 代码规范配置     |
| `.oxlintrc.json`     | Oxlint 代码检查配置     |
| `.prettierrc.json`   | Prettier 格式化配置     |
| `.editorconfig`      | 编辑器通用配置          |

---

## 总结

遵循这些规范可以帮助我们：

- 提高代码质量和一致性
- 减少错误和维护成本
- 提高团队协作效率
- 优化项目性能和用户体验

请务必遵守这些规范，并在代码审查过程中严格执行。

配置位置：

这类全局规则的目标不是"越多越好"，而是让 AI 在任何项目里都先遵守你的协作原则。

九、Memory 记忆机制怎么用，为什么它对长期项目特别重要

Memory 是 Windsurf 在长期协作中的核心能力之一。

如果没有记忆，AI 每次都像第一次进项目；如果记忆用得好，AI 就会越来越像熟悉你团队工程习惯的同事。

1. 什么信息适合写入记忆

前端工程里最适合沉淀为记忆的内容包括：

用户固定偏好
团队代码风格
项目技术栈
常用目录结构
请求封装约定
测试策略
文档输出习惯
常见业务模块命名
长期有效的架构原则

2. 对当前项目来说，哪些内容最值得记忆

结合当前项目，我认为这些信息非常值得沉淀：

这是一个 Vue 3 + TS + Vite 的后台项目
UI 使用 Element Plus
样式优先 Tailwind
请求统一使用 vue-request
测试优先 Playwright
项目有完整的 rules/workflows/doc 结构
质量门禁依赖 type-check + lint + build + test

3. 记忆的正确使用姿势

我建议记忆遵循以下原则：

只记长期有效信息
不记临时需求
不记容易过期的上下文
优先记协作偏好和架构共识

4. 记忆不是替代文档

这点非常重要。

Memory 适合记"长期稳定偏好"
Rules 适合记"可执行规范"
Workflow 适合记"任务执行 SOP"
Doc 适合记"面向人阅读的方案与沉淀"

这四者是互补关系，不要混用。

5. 一份适合前端项目的记忆清单

如果你不知道应该给 Windsurf 记什么，我建议前端项目优先沉淀下面这些：

当前主要技术栈
常用 UI 库
请求层统一方案
测试工具优先级
文档输出风格
常用工作流名称和用途
你的协作语言与沟通风格
团队明确禁止的做法

例如，结合我当前项目，比较适合长期记住的信息就是：

text 复制代码

这是一个 Vue 3 + TypeScript + Vite 的后台项目。
UI 使用 Element Plus，样式优先 Tailwind。
接口请求统一使用 vue-request。
前端测试优先 Playwright。
复杂任务优先按 workflow 执行。
禁止硬编码和降级方案掩盖真实问题。

如果你把这些长期稳定信息记住，后续很多对话都不需要重复解释。

十、Skill 怎么理解，前端工程师应该怎么用

很多人会把 Skill 理解成"额外插件"，其实更适合理解为：

让 AI 在某类任务上表现更稳定的一套能力模板或专业技能域。

在前端工程中，Skill 更适合从任务类型来划分。

1. 前端常见 Skill 分类建议

我建议你按下面几类理解和设计：

页面开发 Skill：列表页、详情页、弹窗、抽屉、表单
组件开发 Skill：可复用组件、插槽、Props/Emits、类型约束
请求与数据流 Skill：接口封装、useRequest、错误处理、节流防抖
状态管理 Skill：Pinia、持久化、跨页面状态重置
路由与权限 Skill：路由守卫、meta、按钮权限、RBAC
测试 Skill：Vitest、Playwright、Mock、断言设计
文档 Skill：方案文档、实施文档、博客文章、交付说明

2. 当前项目里最适合重点强化的 Skill

因为这是后台管理项目，所以我认为以下 Skill 最值得重点建设：

后台列表/表单页开发
权限链路处理
useRequest 请求模式
Element Plus 表单与表格
Playwright 前端回归测试
文档沉淀与 SOP 输出

3. Skill 和 Workflow 的区别

这个很容易混淆。

Skill 更像能力方向
Workflow 更像执行流程

比如：

"后台管理页面开发"更像一种 Skill
"从需求分析到验收测试的 SOP"更像 Workflow

所以我的建议是：

用 Skill 解决"会不会做"
用 Workflow 解决"按什么步骤做"

4. 前端工程推荐的 Skill 清单模板

如果你准备自己整理一套 Skill 体系，可以先从下面这些开始：

Skill 名称	适用场景	核心要求
页面开发 Skill	列表页、详情页、配置页	组件拆分、请求接入、状态管理、表单校验
组件封装 Skill	弹窗、抽屉、选择器、上传组件	Props/Emits 类型完备、可复用、低耦合
数据流 Skill	useRequest、接口联调、错误处理	loading/error/cancel 完整处理
权限 Skill	菜单权限、按钮权限、数据权限	RBAC、路由 meta、兜底逻辑
测试 Skill	Vitest、Playwright	关键链路可验证，断言明确
文档 Skill	实施文档、方案文档、博客文章	结构完整、可复用、可交付

这样整理后，你会发现 Skill 更像"能力目录"，非常适合做长期沉淀。

十一、Agent 怎么理解，前端工程中如何设计 Agent 协作方式

如果把 Windsurf 用深一点，你会发现 Agent 的价值在于：

让 AI 不只是回答问题，而是按角色承担任务。

1. 前端工程常见 Agent 角色划分

我建议前端开发至少可以按下面这些角色来理解 Agent：

前端开发 Agent：负责页面实现、组件拆分、状态管理、接口联调
测试 Agent：负责单测、E2E、测试场景设计
文档 Agent：负责需求文档、技术方案、发布说明、博客沉淀
架构/规范 Agent：负责检查是否符合项目规则、目录规范、最佳实践
排障 Agent：负责根因分析、影响面评估、修复建议

2. 当前项目最适合的 Agent 模式

结合现有配置，我认为最适合的就是下面这套：

开发型 Agent ：配合 8-后台管理开发SOP
修复型 Agent ：配合 1-实施修复须遵守SOP
分析型 Agent ：配合 2-根因分析与建议SOP
文档型 Agent ：配合 3-开发文档撰写SOP
测试型 Agent ：配合 6-自动化测试SOP

这套组合方式的好处是，Agent 的角色职责和 Workflow 的执行流程是能对应起来的。

3. Agent 设计原则

前端项目里设计 Agent，建议遵守这几个原则：

一个 Agent 只承担一类主要职责
Agent 不要越权改无关模块
Agent 输出必须服从项目规则
Agent 在不确定时优先查文档
Agent 在复杂任务中先给计划再实施

4. 一套适合前端团队的 Agent 协作模板

如果你希望文章更有"实操感"，建议加上一套 Agent 分工示例。下面这套就很适合中后台项目：

Agent 角色	主要职责	对应工作流
开发 Agent	页面开发、组件拆分、接口接入、状态联动	`8-后台管理开发SOP`
修复 Agent	bug 定位、根因分析、最小修复方案	`1-实施修复须遵守SOP`
分析 Agent	可行性分析、风险评估、影响面梳理	`2-根因分析与建议SOP`、`4-可行性分析SOP`
测试 Agent	单测、E2E、回归验证、测试建议	`6-自动化测试SOP`
文档 Agent	开发文档、交付说明、博客沉淀	`3-开发文档撰写SOP`、`5-开发文档实施SOP`

这种写法很适合给读者建立一个认知：Agent 不是玄学，而是"带角色边界的 AI 协作方式"。

十二、结合当前项目，给出一套可落地的 Windsurf 使用教程

下面我给出一套更偏实战的使用教程，适合直接写进文章正文。

第一步：先整理项目级规则

先在项目里准备好这三类目录：

text 复制代码

.windsurf/rules
.windsurf/workflows
.windsurf/doc

然后至少补齐：

一个项目规则文件
多个高频工作流文件
一个文档沉淀目录

第二步：把项目规范写成 AI 可执行规则

以我当前项目为例，项目规则里重点要写清楚：

技术栈和版本
组件写法
请求写法
样式写法
目录结构
测试方式
质量门禁

比如当前项目就已经明确：

组件使用 <script setup lang="ts">
请求统一使用 vue-request
样式优先 Tailwind
代码通过 ESLint + Oxlint + Prettier
测试使用 Vitest + Playwright

第三步：把高频任务固化成工作流

前端项目最常见的高频任务有：

修 bug
开新页面
写测试
写文档
做可行性分析

这些都不应该每次靠口头描述，而应该沉淀为 workflow。

我的建议是：

Bug 修复做一个 SOP
页面开发做一个 SOP
测试做一个 SOP
文档编写做一个 SOP
代码规范做一个 SOP

第四步：配置 MCP，解决"资料"和"验证"问题

前端工程最常见的两个问题就是：

API 写法不确定
页面行为需要验证

所以 MCP 至少要覆盖：

官方文档查询
浏览器交互验证

你可以这样理解：

Context7 解决"怎么写才对"
Playwright MCP 解决"现在到底跑得对不对"

第五步：补充全局规则，固定协作风格

全局规则建议重点写：

回复语言
输出简洁度
是否先计划后实施
是否优先查官方文档
是否优先自动化测试
是否允许硬编码

如果这些没有约束，AI 很容易在不同项目里输出风格飘忽不定。

第六步：利用记忆做长期协作

只要是长期项目，我都建议把这些记成稳定偏好：

你的技术栈
你的测试偏好
你的代码规范重点
你的文档输出风格
你的协作语言

这样 AI 在后续对话里会越来越稳定。

第七步：用 Agent 思维来分配任务

同样是 Windsurf，为什么有的人越用越顺，有的人越用越乱？

关键就是有没有角色意识。

比如你可以这样提需求：

让它以"修复 Agent"方式排查 bug
让它以"前端开发 Agent"方式实现页面
让它以"测试 Agent"方式补 Playwright 用例
让它以"文档 Agent"方式输出交付文档

这样它会更容易进入正确的任务模式。

第八步：把结果纳入工程验收闭环

这一点特别重要。很多人用了 AI 之后，只看"它有没有写出来"，却忽略了"它有没有符合当前工程标准"。

在当前项目里，我建议把验收闭环固定成下面这套顺序：

text 复制代码

读规则 -> 读 workflow -> 分析影响面 -> 实施改动 -> 自查代码 -> type-check -> lint -> 测试 -> 文档沉淀

如果是前端后台项目，这套闭环比"写完就合并"稳定得多。

第九步：沉淀可复用模板

当你完成几次高质量协作后，建议把下面这些逐步沉淀下来：

常用提问模板
常用工作流模板
页面开发模板
文档模板
测试模板

这样 Windsurf 就不再只是临时助手，而会逐步变成你团队的工程加速器。

十三、如果你要从 0 到 1 实施，我建议直接按这个顺序落地

如果你是第一次在团队里正式引入 Windsurf，我建议不要一口气配得太复杂，直接按下面的顺序实施。

第 1 周：先完成最小可用配置

准备 .windsurf/rules
准备 .windsurf/workflows
准备 .windsurf/doc
写一份项目规则
写 2 到 3 个高频 workflow
接入文档类 MCP

这一阶段的目标不是面面俱到，而是让 AI 开始"按项目约束工作"。

第 2 周：补全验证链路

接入浏览器类 MCP
梳理测试 SOP
明确项目脚本和验收命令
固定复杂任务先计划后实施

这一阶段的目标，是让 AI 输出从"会写"升级到"会验证"。

第 3 周：补全长期协作能力

固化全局规则
明确记忆策略
归纳高频 Agent 角色
沉淀 Skill 清单
整理文档模板

这一阶段的目标，是让 Windsurf 从单次提效变成长期提效。

第 4 周：开始做团队化沉淀

把规则纳入仓库维护
把 workflow 当作 SOP 维护
把文档沉淀纳入交付流程
用真实页面和 bug 修复持续迭代规则

做到这一步后，你的 AI 协作体系就基本成型了。

十四、结合当前项目，我最推荐的实际使用方式

如果你是和我类似的前端后台项目，我最推荐的 Windsurf 使用方式是下面这套组合拳。

1. 开发前

先让 AI：

阅读项目规则
阅读对应 workflow
梳理目标模块的目录结构
先给出最小改动方案

2. 开发中

要求 AI：

按项目规则改代码
不要修改无关逻辑
遇到组件 API 不确定先查文档
接口请求统一走 useRequest
样式优先用 Tailwind
保持类型安全

3. 开发后

要求 AI：

检查是否符合 lint / type-check 规则
补必要测试
输出变更说明
如果是复杂需求，再输出实施文档或博客沉淀

4. 适合当前项目的典型提问方式

你可以这样给 Windsurf 下指令：

text 复制代码

按照 8-后台管理开发SOP，在当前 Vue3 + TS + Element Plus 项目中实现一个数据字典管理页面，要求接口统一用 vue-request，样式优先 Tailwind，并补充必要测试。

或者：

text 复制代码

按照 1-实施修复须遵守SOP，排查当前页面的树形构建逻辑问题，先分析根因和影响面，再给出最小修复方案。

这种提问方式，比单纯说一句"帮我改一下这个页面"质量要高很多。

十五、真实案例增强版：用数据字典页面说明 Windsurf 如何落地

为了让这篇文章更接近真实项目，我这里直接用当前项目中的"数据字典页面"作为案例来说明。

这个案例不是虚构示例，而是当前项目里已经存在的真实页面：

text 复制代码

路由文件：src/router/modules/property.ts
页面文件：src/views/property/settings/data-dictionary/index.vue
路由地址：/property/settings/data-dictionary
页面名称：数据字典管理

1. 这个案例为什么适合写进文章

因为这个页面很典型，几乎涵盖了前端后台开发里的几个核心要素：

左侧树形分类
右侧数据表格
关键字搜索
弹窗批量新增
删除确认
接口联动
页面初始化默认选中

对于讲解 Windsurf 在前端工程中的用法来说，这类页面比单纯的静态展示页更有代表性。

2. 当前项目中的页面挂载方式

这个页面是通过路由模块挂载到"物业 -> 系统 -> 数据字典管理"下面的。

可直接引用的真实代码位置：

text 复制代码

src/router/modules/property.ts

对应配置逻辑可以概括为：

一级菜单：/property
二级分组：settings
页面路由：data-dictionary
页面组件：@/views/property/settings/data-dictionary/index.vue

这部分很适合在文章里说明：Windsurf 不是只看单个页面文件，而是应该先理解页面在整个路由体系中的位置。

3. 页面实现结构拆解

从当前 index.vue 的实现来看，这个页面结构非常清晰，可以拆成下面几个部分：

左侧：字典分类树

使用 el-tree
通过 filterText 做过滤
使用 buildTree 将后端分类数据转换成树结构
默认展开并高亮当前节点

右侧：字典值表格

使用 el-table
根据当前选中的分类加载数据
支持关键字搜索
展示名称、code、备注
支持删除操作

弹窗：批量新增字典值

使用 el-dialog
动态维护 addForm.items
支持增加/删除输入行
提交前做基础校验
提交成功后刷新列表

4. 这个页面里最有代表性的几个前端工程点

这个页面虽然代码量不大，但非常适合用来讲解 Windsurf 的工程化使用方式，因为它有几个很典型的实现点。

工程点一：树形结构转换

页面里有一个非常关键的方法：buildTree。

它负责把接口返回的分类分组数据，整理成 el-tree 需要的结构：

groupName -> label
groupId -> value
categoryVOList -> children
dataCount -> 节点数量标签

这类逻辑就是典型的"AI 很容易写错，但又非常适合让 AI 辅助分析"的点。

如果你让 Windsurf 直接介入这类问题，一个高质量提问方式可以写成：

text 复制代码

请基于当前 index.vue 中的 buildTree 实现，分析数据字典树形结构的构建逻辑，检查是否存在默认选中异常、空 children 节点处理不完整或类型不一致的问题，并给出最小修复方案。

工程点二：页面初始化逻辑

当前页面在 onMounted 时会调用 fetchCategories()，而 fetchCategories() 里又会：

请求分类数据
构造树结构
如果当前没有选中项，则自动选中第一项
如果已经有有效分类，则继续加载右侧表格

这就是很典型的后台页面初始化链路。

对于 Windsurf 来说，这类链路如果没有规则约束，很容易被改乱；但如果先读规则、再读页面、再分析状态流，AI 就能协助得很好。

工程点三：列表和表单共存的页面状态管理

这个页面同时维护了几组状态：

树过滤：filterText
表格搜索：searchKeyword
当前类别：activeCategory
表格数据：tableData
弹窗状态：addDialogVisible
新增表单：addForm.items
提交状态：submitting

这很适合在文章里说明：

前端工程里使用 Windsurf，不是只让它写一个按钮点击事件，而是要让它理解整页状态之间的关系。

工程点四：Element Plus 组件协作

这个页面同时使用了多种 Element Plus 组件：

el-card
el-row / el-col
el-input
el-tree
el-tag
el-table
el-dialog
el-button
ElMessage
ElMessageBox

这也正好适合说明为什么前端项目里要配文档类 MCP：

不确定组件 API 时，先查官方文档
不确定交互边界时，先看当前工程已有用法
不确定事件或属性时，再由 AI 结合项目规则给实现建议

5. 当前页面的接口联动方式

从真实代码看，这个页面主要依赖了几个接口：

pmsPmsDicCategoryList
pmsPmsDicDataList
pmsPmsDicDataBatchInsert
pmsPmsDicDataDelete

对应的业务动作也很清晰：

查询分类
查询字典值
批量新增字典值
删除单个字典值

这类页面很适合用来说明一个工程原则：

AI 写页面时，不能只盯着模板层，要同时理解接口动作、状态流和用户操作链路。

6. 如果我用 Windsurf 来开发或优化这个页面，我会怎么提需求

下面这几类提问方式，你可以直接放进文章里，作为读者可复用的"实战模板"。

场景一：新建页面

text 复制代码

按照 8-后台管理开发SOP，在当前 Vue3 + TypeScript + Element Plus 项目中实现一个数据字典管理页面。页面左侧是分类树，右侧是字典值表格，支持关键字搜索、弹窗批量新增和删除操作。要求遵守项目规则，接口风格与现有 service/api 保持一致，样式优先复用当前 UI 风格。

场景二：排查树形结构问题

text 复制代码

按照 1-实施修复须遵守SOP，排查数据字典页面 buildTree 和默认选中逻辑，分析为什么某些分类节点点击后没有正确加载右侧表格，并给出最小修复方案。

场景三：补测试

text 复制代码

按照 6-自动化测试SOP，为数据字典页面补充核心测试，覆盖分类切换、搜索、弹窗新增和删除确认的关键交互链路。

场景四：输出开发文档

text 复制代码

按照 3-开发文档撰写SOP，基于当前数据字典页面的真实实现，输出一份包含页面结构、接口联动、状态流和测试建议的开发说明文档。

7. 这个案例最能体现 Windsurf 的价值在哪里

如果让我用一句话总结这个案例的价值，我会这样写：

数据字典页面不是一个"难页面"，但它足够完整，能够很好地体现 Windsurf 在前端工程里如何结合规则、工作流、文档和真实代码上下文来工作。

它能很好地说明几个事实：

AI 不应该脱离真实项目结构单独写页面
AI 应该先理解路由、状态、接口、组件协作关系
AI 的高质量输出依赖规则、workflow 和文档约束
真实项目案例比空泛概念更能说服前端开发者

如果你把这节案例放进文章里，整篇内容的可信度和收藏价值都会明显提升。

十六、前端工程里使用 Windsurf 的几个常见误区

误区一：没有规则，直接让 AI 写

这样最容易出现：

风格不一致
技术栈乱用
绕开现有封装
写出不符合项目结构的代码

误区二：只有规则，没有工作流

只有规则，AI 只知道"什么不能做"，但不知道"应该按什么顺序做"。

尤其是复杂任务，没有 Workflow，AI 很容易跳步骤。

误区三：把记忆当文档仓库

记忆应该存长期有效的偏好和共识，不应该把每次任务细节都塞进去。

误区四：不接 MCP 只靠模型猜

前端生态更新很快，如果不查官方文档，很多输出会看起来像对的，实际却不严谨。

误区五：AI 输出后不做验收

AI 可以提升效率，但不能跳过工程验收。

在当前项目里，至少应该关注：

pnpm run type-check
pnpm run lint
pnpm run build
pnpm run test:unit
pnpm run test:e2e

十七、我对前端团队落地 Windsurf 的建议

如果是个人开发者，我建议先做最小配置：

一份项目规则
两到三个核心 workflow
MCP 文档能力
MCP 浏览器能力

如果是团队开发，我建议一步到位：

项目规则仓库化
Workflow 标准化
文档模板沉淀
测试 SOP 固化
记忆策略明确
Agent 角色边界清晰

对于前端团队来说，Windsurf 真正的价值不是"省几行代码"，而是：

把团队经验、工程规范、测试标准、文档习惯都沉淀进 AI 协作链路里。

十八、可直接用于文章结尾的总结

总的来说，前端工程师想把 Windsurf 用好，关键不是多会"prompt"，而是要把工程上下文建设好。

在我当前这个 Vue 3 + TypeScript + Vite 后台项目里，真正发挥作用的是下面这套组合：

用 MCP 解决文档查询和页面验证
用 Workflow 固化任务 SOP
用 Project Rules 约束项目内实现方式
用 Global Rules 固定长期协作习惯
用 Memory 记住稳定偏好和架构共识
用 Skill / Agent 强化任务角色与执行质量

当这些都配置好之后，Windsurf 就不只是一个"聊天式 AI"，而会变成一个真正能参与前端工程交付的智能搭档。

如果你也是做 Vue 后台、管理平台、企业中后台系统，我非常建议你把规则、工作流、测试和文档一起建设起来。这样你会发现，AI 的产出质量和稳定性会有非常明显的提升。

windsurf的配置和项目规则、工作流、agent技巧使用

Windsurf 在前端开发中的落地实践：以 Vue3 + TypeScript 后台项目为例

导读

一、windsurf常用的配置介绍

二、我当前项目里的 Windsurf 配置结构

三、为什么前端工程师要认真配置 Windsurf

四、当前项目的前端工程背景

1. 项目技术栈

2. 项目脚本

五、MCP 是什么，前端工程为什么一定要配

1. MCP 的作用

2. 我当前使用场景里的重点 MCP

Context7

Playwright MCP

3. 前端工程师如何配置 MCP

4. 前端项目推荐的 MCP 使用策略

5. MCP 在当前项目里的典型用法

6. 一套适合前端工程的 MCP 配置思路

第一步：先接文档类 MCP

第二步：再接浏览器自动化类 MCP

第三步：给 MCP 设定使用边界

推荐的 MCP 使用口令模板

六、工作流 Workflow 怎么配，为什么这是团队提效核心

1. 我当前工作流设计的特点

2. 举几个工作流的实际价值

1-实施修复须遵守SOP

6-自动化测试SOP

8-后台管理开发SOP

3. Workflow 推荐写法

4. 前端项目推荐工作流分类

七、项目规则 Project Rules 怎么写，为什么它决定 AI 输出质量

1. 我当前规则里已经覆盖的重点

2. 当前规则中最值得保留的约束

代码风格统一

TypeScript 严格类型

Vue SFC 结构顺序

请求统一使用 vue-request

样式优先 Tailwind

3. 项目规则的本质

4. 前端项目规则推荐内容

八、全局规则 Global Rules 怎么理解，应该放什么

1. 全局规则适合放什么

2. 结合我当前使用习惯，前端工程常见全局规则示例

3. 为什么全局规则不能写得太散

4. 一份适合前端工程师的全局规则模板

九、Memory 记忆机制怎么用，为什么它对长期项目特别重要

1. 什么信息适合写入记忆

2. 对当前项目来说，哪些内容最值得记忆

3. 记忆的正确使用姿势

4. 记忆不是替代文档

5. 一份适合前端项目的记忆清单

十、Skill 怎么理解，前端工程师应该怎么用

1. 前端常见 Skill 分类建议

2. 当前项目里最适合重点强化的 Skill

3. Skill 和 Workflow 的区别

4. 前端工程推荐的 Skill 清单模板

十一、Agent 怎么理解，前端工程中如何设计 Agent 协作方式

1. 前端工程常见 Agent 角色划分

2. 当前项目最适合的 Agent 模式

3. Agent 设计原则

4. 一套适合前端团队的 Agent 协作模板

十二、结合当前项目，给出一套可落地的 Windsurf 使用教程

第一步：先整理项目级规则

第二步：把项目规范写成 AI 可执行规则

第三步：把高频任务固化成工作流

第四步：配置 MCP，解决"资料"和"验证"问题

第五步：补充全局规则，固定协作风格

第六步：利用记忆做长期协作

第七步：用 Agent 思维来分配任务

第八步：把结果纳入工程验收闭环

第九步：沉淀可复用模板

十三、如果你要从 0 到 1 实施，我建议直接按这个顺序落地

第 1 周：先完成最小可用配置

第 2 周：补全验证链路

第 3 周：补全长期协作能力

第 4 周：开始做团队化沉淀

十四、结合当前项目，我最推荐的实际使用方式

1. 开发前

2. 开发中

3. 开发后

`Context7`

`Playwright MCP`

`1-实施修复须遵守SOP`

`6-自动化测试SOP`

`8-后台管理开发SOP`

请求统一使用 `vue-request`