一、OpenSpec 完整详细介绍
1. 基础定义
OpenSpec（官方项目：@fission-ai/openspec）是面向 AI 代码编辑器（Cursor、Claude Code）的轻量规范驱动开发（SDD）开源框架，专门解决 AI 写代码需求跑偏、上下文丢失、无追溯、团队规范不一致的痛点OpenSpec。
- OpenSpec：约束 AI 编码行为、管理业务需求规范的本地开发工具。
核心思想：变更即代码（Change-as-Code）
先写规范，再写代码 把业务需求、页面逻辑、组件约束、接口规则写成项目内持久化的 spec.md，AI 每次编码优先读取本地规范，不会凭空脑补、需求跑偏，所有开发流程可存档、可复盘、团队共享。
2. 核心解决的行业痛点（Cursor 开发 Vue3 最容易遇到）
- 长对话 AI 遗忘需求，写一半偏离页面逻辑；
- 多人协作开发 Vue，组件、接口、Pinia 写法不统一；
- 迭代需求无文档，过段时间不知道页面当初为什么这么写；
- AI 生成代码不符合项目现有技术栈（ref/reactive、Element Plus、路由、axios 封装规范）；
- 新增页面、弹窗、列表时，每次都要重复说明项目目录结构。
3. 目录结构（初始化自动生成）
plaintext
bash
你的Vue3项目根目录/
├── openspec/
│ └── specs/ # 所有功能规范存放目录，一个功能一个文件夹
│ ├── login/
│ │ └── spec.md # 登录页完整规范
│ ├── user-list/
│ │ └── spec.md # 用户列表页面规范
│ └── loan-audit/ # 信贷审核页面（你之前银行渠道业务场景）
│ └── spec.md
├── .cursor/commands/ # 自动注入Cursor专属斜杠指令
│ ├── opsx-proposal
│ ├── opsx-apply
│ └── opsx-archive
├── src/ # 正常Vue3代码
└── package.json4. 标准四步闭环工作流
- Proposal 提案：描述需求，AI 生成结构化 spec.md（包含页面结构、接口、组件、ts 类型、状态管理、校验规则）；
- Review 评审：人工修改规范，确认所有细节无歧义；
- Apply 落地：Cursor 读取 spec，自动生成 / 修改 Vue 页面、composable、api、路由；
- Archive 归档：功能测试完成，归档规范永久存入仓库，后续迭代可直接复用。
5. 三大核心命令（Cursor 内置斜杠指令）
/opsx:proposal 功能名：生成功能规范文档/opsx:apply 功能名：根据规范生成完整 Vue3 代码/opsx:archive 功能名：归档完成的规范，沉淀项目知识库
6. OpenSpec 核心优势
- 轻量化无侵入：不改造 Vue/Vite/Pinia 原有工程，仅新增 openspec 文件夹；
- Cursor 原生适配：官方内置集成，无需额外 MCP 配置即可使用；
- 增量规范：老 Vue 项目不用一次性补全所有文档，新增页面再写 spec；
- 强约束 AI 编码：强制 AI 遵循你项目固定写法（ref/reactive、封装 axios、组件命名）；
- 版本可控：spec.md 随 git 提交，需求变更全程可追溯。
7. spec.md 标准模板（Vue3 页面示例）
markdown
markdown
# user-list 用户列表页面规范
## 1. 项目技术约束
- Vue3 + Vite + TS
- 状态管理：Pinia
- UI组件：Element Plus
- 响应式：统一使用ref，复杂表单使用reactive
- 请求：统一导入@/utils/request axios实例
## 2. 页面需求
1. 分页表格展示用户信息：id、姓名、手机号、授信额度、状态
2. 搜索栏：姓名模糊搜索、状态下拉筛选
3. 操作按钮：查看详情、编辑、删除弹窗
## 3. 接口约定
GET /api/user/list 分页查询
GET /api/user/detail/:id 详情
PUT /api/user/:id 编辑用户
DELETE /api/user/:id 删除用户
## 4. 文件目录要求
- 页面：src/views/user/UserList.vue
- 接口：src/api/user.ts
- 状态：src/stores/user.ts
- 类型：src/types/user.ts
## 5. UI与交互约束
- 表格默认每页10条
- 删除弹出二次确认框
- 表单校验：手机号正则、额度数字限制二、OpenSpec 在 Cursor + Vue3 项目完整使用教程
前置环境
- 已安装 Cursor 编辑器；
- Vue3 + Vite/TS 前端项目；
- Node.js ≥18，npm/pnpm。
步骤 1：全局安装 OpenSpec CLI
bash
运行
perl
# 全局安装官方包
npm install -g @fission-ai/openspec@latest
# 验证安装
openspec -v步骤 2：Vue3 项目初始化（指定 Cursor 工具）
进入你的 Vue 项目根目录执行：
bash
运行
css
openspec init --tools cursor执行后自动完成：
- 创建
openspec/specs规范目录； - 在
.cursor/commands生成三条斜杠指令； - 自动识别 Vue 技术栈，预设前端编码约束模板。
步骤 3：创建 Vue 页面规范（提案流程）
方式 1：终端命令生成提案
bash
运行
openspec proposal loan-audit执行后交互式输入需求：
plaintext
csharp
请描述功能需求：银行贷款资质审核页面，表格展示客户征信、负债、匹配银行产品，弹窗填写客户信息，使用Element Plus，ref管理列表数据，Pinia存储筛选条件工具自动生成：openspec/specs/loan-audit/spec.md 完整规范文档。
方式 2：Cursor 聊天框直接调用（最常用）
打开 Cursor AI 对话窗口，输入：
plaintext
bash
/opsx:proposal loan-audit
需求：Vue3贷款审核页面，包含搜索筛选、客户表格、新增客户弹窗，使用ref做响应式，统一封装axios请求，生成对应api、types、pinia仓库AI 会直接输出完整 spec.md，你可以在对话内修改细节（调整字段、UI、接口），确认无误即保存到项目目录。
步骤 4：根据规范自动生成 Vue3 全套代码（核心）
规范评审完成后，在 Cursor 聊天框执行：
plaintext
bash
/opsx:apply loan-auditAI 自动读取 loan-audit/spec.md，一次性生成整套前端文件，覆盖 Vue3 全套代码：
- 页面文件：
src/views/loan/AuditList.vue（template + script setup，ref/reactive 规范写法） - 接口请求：
src/api/loan.ts（axios 封装、请求 / 响应 TS 类型） - 全局状态：
src/stores/loan.ts（Pinia 组合式写法） - 类型定义：
src/types/loan.ts（Params、Item、Response 完整 TS） - 路由补充：自动提醒补充
src/router/index.ts路由配置
生成代码遵守你 spec 里定义的 Vue3 规范示例
spec 写明「基础变量用 ref，表单对象用 reactive」，AI 生成代码如下：
vue
xml
<script setup lang="ts">
import { ref, reactive } from 'vue'
import { ElMessage } from 'element-plus'
import { getLoanList } from '@/api/loan'
import { useLoanStore } from '@/stores/loan'
// 基础分页数字使用ref
const pageNum = ref(1)
const pageSize = ref(10)
const total = ref(0)
const loading = ref(false)
// 表单对象使用reactive
const searchForm = reactive({
name: '',
creditStatus: ''
})
const loanStore = useLoanStore()
const tableList = ref<LoanItem[]>([])
// 加载列表
const loadData = async () => {
loading.value = true
const res = await getLoanList({ ...searchForm, pageNum: pageNum.value, pageSize: pageSize.value })
tableList.value = res.records
total.value = res.total
loading.value = false
}
</script>步骤 5：迭代修改已有 Vue 页面
如果需要修改现有贷款审核页面，不用重写全部需求：
- 打开
openspec/specs/loan-audit/spec.md，追加需求：新增授信额度筛选框、表格增加产品匹配列； - Cursor 执行：
/opsx:apply loan-audit； - AI 只增量修改对应 Vue 页面、接口、类型，不会覆盖无关代码。
步骤 6：功能完成归档沉淀知识库
页面自测、接口联调无问题后归档，永久存入项目，后续新人 / 迭代可直接复用规范：
bash
运行
bash
# 终端执行
openspec archive loan-audit
# 或Cursor聊天框
/opsx:archive loan-audit步骤 7：团队统一 Vue 编码规范（全局 spec）
在 openspec/specs/global/spec.md 写入全局强制规则，所有页面生成都会遵守：
markdown
markdown
# 全局Vue3编码规范
1. script setup TS 语法，禁止选项式API
2. 数字/布尔/字符串统一ref；表单、复杂对象reactive
3. 组件命名大驼峰，页面目录小驼峰
4. 请求统一引入 @/utils/request，禁止原生fetch
5. 弹窗、表格、表单全部使用Element Plus组件
6. 分页、弹窗抽离成composable复用
7. 禁止直接操作DOM，统一ref绑定元素之后所有 /opsx:apply 生成代码都会严格遵循这套规则。
三、Cursor + OpenSpec 开发 Vue3 高频场景实操
场景 1：新增列表页面（银行信贷客户列表）
/opsx:proposal customer-list输出规范；- 补充字段、接口、分页、弹窗规则；
/opsx:apply customer-list一次性生成页面、api、store、types；- 复制路由配置到 router/index.ts，直接运行。
场景 2：混合开发 uni-app/H5 页面（你之前混合开发需求）
spec 中增加约束：使用uni-app Vue3语法，一套代码兼容H5/App，uni.request封装请求，AI 自动生成 uni 专属页面，不会生成 web 端 Element Plus 代码。
场景 3：复用已有 OpenAPI 接口文档生成 Vue 请求
在 spec.md 嵌入后端 OpenAPI yaml，OpenSpec 会自动解析接口，让 Cursor 生成对应 axios 请求与 TS 类型：
markdown
yaml
## 后端接口OpenAPI定义
```yaml
openapi: 3.0
paths:
/api/customer/list:
get:
summary: 客户列表
parameters:
- name: name
in: query
schema:
type: string执行 /opsx:apply customer-list，自动解析生成完整 api/ts 类型。
四、常见踩坑与优化
- AI 生成代码不使用 ref/reactive 规范解决：在 global 全局 spec 写明响应式强制规则，每次 apply 自动读取；
- 初始化后 Cursor 识别不到斜杠命令 解决：重启 Cursor 编辑器，
Ctrl+Shift+P刷新 AI 指令； - Vue 项目结构特殊，AI 生成文件路径错误解决：在 spec.md 开头写明完整目录结构约束；
- 生成代码覆盖原有页面解决：spec 中写明「增量修改，保留原有逻辑，仅新增字段」；
- 区分 OpenSpec 与 OpenAPIOpenSpec 管前端页面、组件、业务逻辑；OpenAPI 只管后端接口，二者可搭配使用。
五、总结
- OpenSpec 是Cursor 专属 AI 编码规范管理工具，核心价值是约束 AI、沉淀业务文档、统一 Vue3 代码风格；
- 标准流程：proposal 写规范 → apply 生成 Vue 全套代码 → archive 归档；
- Vue3 开发优势：强制统一 ref/reactive、Pinia、axios、组件写法，大幅减少 AI 幻觉、返工；
- 适合 Vue3 项目：大量表格、弹窗、接口页面，批量生成规范代码，前后端对接更高效。