614 lines
30 KiB
Markdown
614 lines
30 KiB
Markdown
# Vibe Cursor Pro
|
||
|
||
**企业级 Cursor Vibe Coding 模板 v4.0**
|
||
|
||
将 Cursor AI 从"代码补全工具"升级为"受约束、可观测、自适应、安全可控"的全栈工程协作者。
|
||
|
||
适用技术栈：Vue 3 + Vite / PHP Hyperf + Swoole / TypeScript (ES2022+)
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [为什么需要这个模板](#为什么需要这个模板)
|
||
- [环境要求](#环境要求)
|
||
- [快速开始](#快速开始)
|
||
- [日常使用指南](#日常使用指南)
|
||
- [Rules 规则系统](#rules-规则系统)
|
||
- [Skills 技能系统](#skills-技能系统)
|
||
- [Subagents 任务委托](#subagents-任务委托)
|
||
- [MCP 服务配置](#mcp-服务配置)
|
||
- [文档知识库](#文档知识库)
|
||
- [自动化脚本](#自动化脚本)
|
||
- [项目结构](#项目结构)
|
||
- [定制化指南](#定制化指南)
|
||
- [常见问题](#常见问题)
|
||
- [版本历史](#版本历史)
|
||
|
||
---
|
||
|
||
## 为什么需要这个模板
|
||
|
||
| 维度 | 传统开发 | Vibe Cursor Pro |
|
||
|------|----------|-----------------|
|
||
| **质量** | 人工 Review | AI Guard 自动质检 + 分层 Rules 约束 |
|
||
| **准确性** | 靠记忆 / Wiki | 智能上下文自动加载 + MCP 实时数据 |
|
||
| **规范性** | 文档驱动 | Rules 自动注入 + Hooks 强制检查 |
|
||
| **安全性** | PR Review | 分级权限 + 敏感操作拦截 + Secret 扫描 |
|
||
| **合规性** | 人工排查 | 许可证白名单/黑名单 + 字体/素材合规检查 |
|
||
| **效率** | 全人工 | PRISM 工作流 + 23 个技能 + 一键脚手架 |
|
||
|
||
**核心设计理念**：
|
||
|
||
- **Intent-First** — 先理解 Why，再执行 What
|
||
- **Slow-to-Fast** — 复杂先规划，简单快速响应
|
||
- **Evidence-Based** — 基于文档和数据决策
|
||
- **Fail-Safe** — 宁可多问，不破坏现有功能
|
||
|
||
---
|
||
|
||
## 环境要求
|
||
|
||
| 工具 | 最低版本 | 用途 |
|
||
|------|---------|------|
|
||
| Cursor IDE | 2.4+ | 原生支持 Skills 和 Subagents |
|
||
| Node.js | 18+ | 前端构建、commitlint |
|
||
| PHP | 8.1+ | 后端运行 |
|
||
| Composer | 2.x | PHP 依赖管理 |
|
||
| Swoole | 5.0+ | 协程引擎 |
|
||
| MySQL | 8.0+ | 数据库 |
|
||
| Redis | 7.x | 缓存和队列 |
|
||
| Git | 2.30+ | 版本控制 |
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 方式一：Workspace 模式（推荐）
|
||
|
||
将 `vibe-cursor-pro` 本身作为 Cursor 工作区根目录，前后端业务项目放置为子目录，各自独立管理 Git。AI 可同时感知规则、技能与前后端业务代码，上下文最完整。
|
||
|
||
**目录结构**
|
||
|
||
```
|
||
vibe-cursor-pro/ <- 用 Cursor 打开这个目录
|
||
├── .cursor/ <- Rules + Skills + MCP（AI 配置）
|
||
├── docs/ <- 项目知识库（填写你的业务文档）
|
||
├── scripts/ <- 自动化工具脚本
|
||
├── Case-Database-Backend/ <- Hyperf 后端（gitignored，独立 git 仓库）
|
||
├── Case-Database-Frontend-user/ <- Vue 3 用户端（gitignored，独立 git 仓库）
|
||
├── Case-Database-Frontend-admin/ <- Vue 3 管理端（gitignored，独立 git 仓库）
|
||
└── Case-Database-Frontend-shared/ <- 共享类型/工具（gitignored，可选独立仓库）
|
||
```
|
||
|
||
> **双前端说明**：`Case-Database-Frontend-user/` 面向终端用户（移动优先），`Case-Database-Frontend-admin/` 面向管理人员（桌面优先，Element Plus）。AI 通过 `011-vue.mdc` 中的双前端上下文规则自动感知目标前端并应用不同设计原则。
|
||
|
||
**初始化步骤**
|
||
|
||
```bash
|
||
# 1. Clone 本模板作为工作区
|
||
git clone https://github.com/your-org/vibe-cursor-pro.git my-workspace
|
||
cd my-workspace
|
||
|
||
# 2. 将已有项目放入对应目录（或初始化新项目）
|
||
git clone <your-backend-repo> Case-Database-Backend
|
||
git clone <your-frontend-user-repo> Case-Database-Frontend-user
|
||
git clone <your-frontend-admin-repo> Case-Database-Frontend-admin
|
||
|
||
# 3. 用 Cursor 打开 my-workspace/，AI 配置自动生效
|
||
```
|
||
|
||
### 方式二：选择性复制
|
||
|
||
```bash
|
||
cp -r vibe-cursor-pro/.cursor your-project/
|
||
cp -r vibe-cursor-pro/docs your-project/
|
||
cp -r vibe-cursor-pro/scripts your-project/
|
||
cp vibe-cursor-pro/.cursorignore your-project/
|
||
```
|
||
|
||
### 初始化后的配置
|
||
|
||
1. **配置 MCP 服务** — 编辑 `.cursor/mcp.json`，填入 Token 和连接信息
|
||
2. **设置信任等级** — 编辑 `002-safety.mdc` 末尾的 `项目状态`（new_project / established / trusted）
|
||
3. **填写项目知识库** — 在 `docs/` 目录下填写你的 PRD、架构、数据模型等文档
|
||
4. **健康检查** — `bash scripts/context-doctor.sh`
|
||
|
||
---
|
||
|
||
## 日常使用指南
|
||
|
||
### 快捷指令
|
||
|
||
| 指令 | 作用 |
|
||
|------|------|
|
||
| `@planning` | 进入规划模式，输出结构化执行计划 |
|
||
| `@review` | 对当前文件做代码审查 |
|
||
| `@debug` | 进入调试模式，系统化排查 |
|
||
| `@refactor` | 重构模式，测试先行、小步安全改善 |
|
||
| `/test` | 为当前代码生成对应测试 |
|
||
| `/doc` | 更新相关文档或生成 ADR |
|
||
| `/skill-name` 或 `@skill-name` | 显式调用指定技能 |
|
||
| `停止` / `STOP` / `ABORT` | 紧急停止当前所有操作 |
|
||
|
||
### 常见场景
|
||
|
||
**端到端开发** — 直接描述需求，AI 自动编排 `full-feature` 技能完成数据库 -> API -> UI 全链路
|
||
|
||
**创建后端模块** — AI 自动加载 `skill-backend-scaffold` 规则，生成 Controller / Service / Repository / FormRequest
|
||
|
||
**创建前端页面/组件** — AI 自动加载 `skill-vue-page` 或 `skill-component-scaffold` 规则
|
||
|
||
**排查 Bug** — AI 自动加载 `skill-debugging` 规则（alwaysApply），按七步法系统排查
|
||
|
||
**代码审查** — `@review` 触发，从安全/正确/可维护/性能/可测试/一致性六维度审查
|
||
|
||
**性能优化** — AI 自动加载 `022-performance` 规则，包含诊断流程和编码规范
|
||
|
||
### PRISM 工作流
|
||
|
||
AI 处理所有任务都遵循 PRISM 流程：
|
||
|
||
```
|
||
Scan -> 理解意图、匹配相关技能
|
||
Plan -> 分析复杂度（L1~L4），制定执行计划
|
||
Retrieve -> 加载文档和 MCP 工具
|
||
Implement -> 逐步执行，每步验证
|
||
Synthesize -> 质量检查、变更摘要、更新文档
|
||
Monitor -> 记录决策、提供后续建议
|
||
```
|
||
|
||
| 复杂度 | 特征 | AI 行为 |
|
||
|--------|------|---------|
|
||
| L1 | 单文件、明确需求 | 直接执行 |
|
||
| L2 | 多文件、需上下文 | 简要规划后执行 |
|
||
| L3 | 架构变更、跨系统 | 输出计划，等确认后执行 |
|
||
| L4 | 生产环境、不可逆 | 强制规划 + 人工审批 |
|
||
|
||
---
|
||
|
||
## Rules 规则系统
|
||
|
||
Rules 是 AI 的"行为手册"，控制 AI **怎么写代码**。共 33 个 `.mdc` 文件，按三种机制自动加载。
|
||
|
||
### 加载机制
|
||
|
||
| 机制 | 说明 | 文件数 |
|
||
|------|------|--------|
|
||
| **alwaysApply** | 每次对话必定注入，构成 AI 的行为底线 | 5 |
|
||
| **globs** | 编辑匹配文件时自动注入（如编辑 `.vue` 文件触发 Vue 规则） | 16 |
|
||
| **SEMANTIC** | Cursor 根据用户意图语义匹配注入（如讨论"性能优化"触发性能规则） | 12 |
|
||
|
||
### 完整规则清单
|
||
|
||
#### alwaysApply — 每次对话自动加载（5 个）
|
||
|
||
| 文件 | 大小 | 作用 |
|
||
|------|------|------|
|
||
| `000-constitution.mdc` | 3.1KB | **AI 宪法**：身份定义（15 年全栈架构师）、核心 Vibe（Intent-First / Slow-to-Fast / Evidence-Based / Fail-Safe）、基本承诺与禁止行为、MCP 自动调用规则、交互语言、紧急停止关键词 |
|
||
| `001-workflow.mdc` | 3.0KB | **PRISM 工作流**：Scan -> Plan -> Retrieve -> Implement -> Synthesize -> Monitor 六步法、复杂度判定（L1~L4）、L2+ 规划输出格式、Synthesize 验证门、完成报告格式、快捷指令表 |
|
||
| `002-safety.mdc` | 2.5KB | **安全权限**：四级操作权限（GREEN/YELLOW/ORANGE/RED）、敏感操作清单（删文件/改配置/装依赖/git push 等）、绝对禁止项、敏感信息自动检测（AWS/GitHub/Stripe 密钥格式）、文件保护清单、信任等级开关 |
|
||
| `003-skills.mdc` | 2.1KB | **Skills 微索引**：两层激活机制说明（自动激活层 skill-*.mdc + 按需加载层 SKILL.md）、技能间依赖关系图、10 个低频技能的兜底路由表、SKILL.md 标准格式、验证门规则 |
|
||
| `skill-debugging.mdc` | 1.9KB | **调试技能（始终可用）**：信号解析（错误消息/复现步骤/影响区域/环境信息）、调试策略路由（PHP/API/DB/Vue/样式各有首选方式）、七步法核心流程（复现->收集->假设->验证->修复->回归）、硬停止条件、验证清单 |
|
||
|
||
#### globs — 按文件类型自动注入（16 个）
|
||
|
||
**编码规范类**（编辑对应类型文件时自动加载）：
|
||
|
||
| 文件 | 匹配 globs | 作用 |
|
||
|------|-----------|------|
|
||
| `010-typescript.mdc` | `*.ts` `*.mjs` `*.vue` | **TypeScript 规范**：ES2022+ 语法、JSDoc 类型注释、命名约定（camelCase 变量/PascalCase 类型/UPPER_CASE 常量）、错误处理模式、import 排序 |
|
||
| `011-vue.mdc` | `*.vue` `*/src/**/*.ts` | **Vue 3 规范 + 双前端上下文**：Composition API / Pinia / Composable 规范、Props 数据流模式（禁止直接修改 prop）、Emits camelCase 命名、单向数据流。内含双前端上下文规则：自动识别用户端（Headless UI + Tailwind，禁止 Element Plus）vs 管理端（Element Plus，权限守卫/二次确认/表单验证/分页），以及共享层约束（纯 TS，无 UI 依赖） |
|
||
| `012-tailwind.mdc` | `*.vue` | **Tailwind CSS 规范**：类名排序、响应式设计、暗色模式、管理端 Element Plus 主题桥接、用户端纯 Tailwind |
|
||
| `013-backend.mdc` | `*.php` | **Hyperf 后端规范**：分层架构（Controller->Service->Repository->Model）、依赖注入、RESTful API、认证授权、Swoole 协程安全 |
|
||
| `014-database.mdc` | 数据库相关文件 | **数据库规范**：Hyperf ORM 使用、Migration 规范、查询优化、索引策略、高并发表设计 |
|
||
| `015-testing.mdc` | `*.test.*` `*.spec.*` `__tests__/**` `phpunit.xml` | **测试规范（后端为主）**：通用测试原则（测行为/单一职责/不为覆盖率写无意义测试）、后端 PHPUnit 金字塔（Unit 60% / Integration 30% / Static 持续）、PHPStan 配置、AAA 模式、覆盖率目标。前端测试的具体工作流由 `skill-vue-testing.mdc` 负责 |
|
||
| `016-swoole.mdc` | `*.php` | **Swoole 规范**：协程安全（禁止全局变量、static 状态）、连接池管理、Channel 通信、defer 用法、内存泄漏防护 |
|
||
| `018-responsive.mdc` | `*.vue` | **响应式设计**：断点体系、移动优先策略、触摸目标尺寸、管理端 Element Plus 适配 |
|
||
| `021-deployment.mdc` | `docker-compose*` `Dockerfile*` `.github/workflows/**` `.env*` | **部署规范**：Docker Compose 配置、CI/CD 流程、环境管理、蓝绿部署、PHP+Vue 双栈构建 |
|
||
| `023-accessibility.mdc` | `*.vue` `*.html` | **无障碍规范**：WCAG AA 标准、语义化 HTML、ARIA 属性、键盘导航、Vue 3 无障碍实践 |
|
||
| `026-secure-coding.mdc` | `*.php` `*.ts` `*.vue` | **安全编码**：SQL 注入防护、XSS 防护、禁用加密算法、IDOR/Mass Assignment 防护、Session 安全、文件上传校验 |
|
||
|
||
**技能规则类**（编辑对应类型文件时自动加载执行摘要）：
|
||
|
||
| 文件 | 匹配 globs | 作用 |
|
||
|------|-----------|------|
|
||
| `skill-backend-scaffold.mdc` | `**/Controller/**/*.php` `**/Service/**/*.php` `**/Repository/**/*.php` | **后端模块脚手架**（合并了原 api-scaffold + hyperf-service）：新建 API 端点或 Service 模块时激活。含完整执行流程（加载规范->确认规格->生成文件->事务/日志/重试）、分层约定、异常体系（Business/Validation/System）、验证清单 |
|
||
| `skill-component-scaffold.mdc` | `**/components/**/*.vue` `**/composables/**/*.ts` | **Vue 组件脚手架**：新建组件或重大组件拆分时激活。含前端识别（管理端 Element Plus / 用户端 Headless UI）、文件结构输出、行数限制（SFC <= 150 行）、设计决策树 |
|
||
| `skill-database-migration.mdc` | `**/migrations/**/*.php` | **数据库迁移**：Schema 变更时激活。安全等级 ORANGE。核心原则（每次变更都是迁移/Schema 与 Data 分离/迁移部署后不可变/新字段 nullable）、执行流程、验证清单 |
|
||
| `skill-vue-page.mdc` | `**/router/**/*.ts` `**/views/**/*.vue` | **Vue 页面脚手架**：新建路由页面时激活。含强制拆分分析（多视图检测/行数预估/重复 UI 检测）、文件结构输出、页面类型（list/detail/form/dashboard/multi-view） |
|
||
| `skill-vue-testing.mdc` | `**/*.test.*` `**/__tests__/**` | **前端测试工作流**：新建或更新测试文件时激活。含测试决策树（纯函数->单元/UI 交互->组件/跨页面->E2E）、核心原则（逻辑提取/穷举排列/AAA/单一行为）、增量式工作流、覆盖率目标 |
|
||
|
||
#### SEMANTIC — 按用户意图语义匹配（12 个）
|
||
|
||
Cursor 根据用户消息的语义自动判断是否注入，无需文件匹配。
|
||
|
||
**编码规范类**：
|
||
|
||
| 文件 | 触发场景 | 作用 |
|
||
|------|---------|------|
|
||
| `017-architecture.mdc` | 讨论水平扩展、限流降级、熔断、高可用架构 | **百万级并发架构**：无状态服务、读写分离、缓存策略、队列削峰、灰度发布 |
|
||
| `019-modular.mdc` | 新建模块、讨论架构设计、模块划分、依赖方向 | **模块化架构**：DDD 边界、依赖方向单向、循环依赖检测、文件拆分阈值 |
|
||
| `020-git.mdc` | 讨论 Git 操作、分支策略、提交规范 | **Git 规范**：分支策略（Git Flow）、Conventional Commits、PR 模板 |
|
||
| `022-performance.mdc` | 报告页面慢、打包体积大、性能优化、Core Web Vitals | **性能规范 + 审计流程**（合并了原 skill-performance-audit）：诊断流程（基线收集->四维度审计->输出建议）+ 编码规范（Vite 构建/Swoole 调优/数据库查询/缓存/Nginx/连接池） |
|
||
| `024-monitoring.mdc` | 讨论日志、监控、告警、Sentry | **日志与监控**：Hyperf Monolog 配置、Vue 3 错误处理、Swoole 监控、告警策略 |
|
||
| `025-licensing.mdc` | 讨论版权、许可证、素材合规 | **版权合规**：许可证白名单/黑名单、字体/图标/图片素材选用规范 |
|
||
|
||
**技能规则类**：
|
||
|
||
| 文件 | 触发场景 | 作用 |
|
||
|------|---------|------|
|
||
| `030-subagents.mdc` | 需要委托子任务给独立 Agent 并行执行 | **Subagent 编排**：调用方式（Read agents/*.md -> Task 工具）、3 个可用 Subagent（repo-scout/test-runner/security-sentinel）、使用模式（清洁上下文/并行/链式/扇出） |
|
||
| `033-refactoring.mdc` | 重构代码、清理技术债、优化代码结构 | **安全重构工作流**（合并了 SKILL.md 内容）：黄金规则（行为不变/小步快跑/测试先行）、坏味道与重构手法对照表（10 种模式）、禁止事项、验证清单 |
|
||
| `skill-code-review.mdc` | 要求 review 代码、检查质量、审查 PR | **六维度代码审查**：安全性->正确性->可维护性->性能->可测试性->一致性，含预提交检查命令和结构化输出格式 |
|
||
| `skill-full-feature.mdc` | 端到端功能开发（数据库到 API 到 UI） | **全链路功能开发**：Phase 1 规划 -> Phase 2 数据层 -> Phase 3 后端 API -> Phase 4 前端 UI -> Phase 5 集成验证 -> Phase 6 收尾。自动编排其他技能协同 |
|
||
| `skill-i18n.mdc` | 添加多语言支持、翻译、vue-i18n | **国际化**：i18n 初始化流程、键命名公式（{feature}.{context}.{action}）、标准命名空间、验证清单 |
|
||
| `skill-security-audit.mdc` | 安全审查、漏洞扫描、OWASP 检查 | **安全审计**：安全等级 RED、依赖扫描、OWASP Top 10 逐项检查、PHP/前端/密钥扫描、中间件链验证、分级输出报告 |
|
||
|
||
### 两层架构说明
|
||
|
||
v4.0 引入两层技能激活机制，解决了技能命中率低的问题：
|
||
|
||
```
|
||
自动激活层（skill-*.mdc）— Cursor 通过 globs/description 自动注入
|
||
↓ 精简执行摘要，Agent 直接遵循
|
||
↓ 需要完整模板时...
|
||
按需加载层（SKILL.md）— Agent 主动 Read 获取完整详情
|
||
```
|
||
|
||
每个 `skill-*.mdc` 顶部都标注了对应 SKILL.md 的路径，Agent 需要深度参考时可自行 Read。
|
||
|
||
---
|
||
|
||
## Skills 技能系统
|
||
|
||
Skills 定义**可复用的任务工作流**，控制 AI **怎么完成任务**。共 23 个技能，位于 `.cursor/skills/`。
|
||
|
||
### 与 Rules 的区别
|
||
|
||
| | Rules (.mdc) | Skills (SKILL.md) |
|
||
|---|---|---|
|
||
| **职责** | 编码规范 + 执行摘要 | 完整任务工作流 + 模板 |
|
||
| **加载** | Cursor 平台自动注入 | Agent 按需 Read |
|
||
| **解决** | "代码怎么写" | "任务怎么完成（完整版）" |
|
||
|
||
### 两层加载
|
||
|
||
```
|
||
Tier 1 — 自动激活: skill-*.mdc 精简摘要，Cursor 自动注入 (~1-2KB/个)
|
||
Tier 2 — 按需深入: SKILL.md 完整流程 + references/ 深度参考 (~2-8KB/个)
|
||
```
|
||
|
||
13 个高频技能有 `.mdc` 自动激活入口（见上方 Rules 清单），其余 10 个低频技能需要 Agent 手动 Read。
|
||
|
||
### 技能清单
|
||
|
||
**已有 .mdc 自动激活入口的技能（13 个）**：
|
||
|
||
| 技能 | 激活方式 | 说明 |
|
||
|------|---------|------|
|
||
| `debugging` | alwaysApply | 七步法系统化调试 |
|
||
| `component-scaffold` | globs | Vue 3 SFC 组件脚手架 |
|
||
| `vue-page` | globs | Vue Router 页面脚手架 |
|
||
| `api-scaffold` | globs（via backend-scaffold） | Hyperf API 端点脚手架 |
|
||
| `hyperf-service` | globs（via backend-scaffold） | Hyperf Service 模块脚手架 |
|
||
| `database-migration` | globs | Hyperf 数据库迁移 |
|
||
| `vue-testing` | globs | Vitest 前端测试工作流 |
|
||
| `code-review` | SEMANTIC | 六维度代码审查 |
|
||
| `full-feature` | SEMANTIC | 端到端功能开发 |
|
||
| `refactoring` | SEMANTIC（via 033-refactoring） | 安全重构工作流 |
|
||
| `security-audit` | SEMANTIC | OWASP 安全审计 |
|
||
| `performance-audit` | SEMANTIC（via 022-performance） | 性能审计流程 |
|
||
| `i18n` | SEMANTIC | 国际化工作流 |
|
||
|
||
> `api-scaffold` 和 `hyperf-service` 合并为 `skill-backend-scaffold.mdc`；`performance-audit` 合并到 `022-performance.mdc`；`refactoring` 合并到 `033-refactoring.mdc`。
|
||
|
||
**仅 SKILL.md 按需加载的技能（10 个）**：
|
||
|
||
| 技能 | 触发场景 | 说明 |
|
||
|------|---------|------|
|
||
| `anti-scraping` | 反爬虫/Bot 防护 | T1~T5 五级反爬虫策略 |
|
||
| `bug-reproduce` | 复现 Bug/回归测试 | 结构化复现框架，不修复 |
|
||
| `documentation` | 写文档/README/ADR | 结构化文档生成 |
|
||
| `env-setup` | 环境配置/项目初始化 | PHP+Node 双栈环境初始化 |
|
||
| `mcp-builder` | 构建 MCP Server | TypeScript MCP SDK 封装 |
|
||
| `message-queue` | 消息队列/异步任务 | Hyperf AsyncQueue + Redis |
|
||
| `nginx-config` | 配置 Nginx/反向代理 | SSL/Gzip/安全头/负载均衡 |
|
||
| `redis-cache` | 添加 Redis 缓存 | Cache-Aside/分布式锁/连接池 |
|
||
| `skill-creator` | 创建新技能 | 生成符合规范的 SKILL.md |
|
||
| `websocket-service` | WebSocket/实时通信 | Swoole WebSocket 服务 |
|
||
|
||
### 使用方式
|
||
|
||
**自然语言触发**（推荐）— 直接描述任务，AI 自动匹配技能
|
||
|
||
**显式调用** — `/skill-name` 或 `@skill-name`
|
||
|
||
**管理脚本**：
|
||
|
||
```bash
|
||
bash scripts/skill-manager.sh list # 列出所有技能
|
||
bash scripts/skill-manager.sh validate # 验证格式合规性
|
||
bash scripts/skill-manager.sh stats # 查看统计信息
|
||
bash scripts/skill-manager.sh create <name> # 创建新技能
|
||
```
|
||
|
||
### 创建自定义技能
|
||
|
||
```
|
||
.cursor/skills/my-skill/
|
||
├── SKILL.md # 必须：主流程 + 验证，含 YAML frontmatter
|
||
├── references/ # 可选：深度内容（模板、示例）
|
||
├── scripts/ # 可选：自动化脚本
|
||
└── assets/ # 可选：模板文件
|
||
```
|
||
|
||
```yaml
|
||
---
|
||
name: my-skill
|
||
description: "做什么 + 什么时候用（< 250 字符）"
|
||
requires: [dep-skill] # 可选：声明依赖
|
||
---
|
||
```
|
||
|
||
---
|
||
|
||
## Subagents 任务委托
|
||
|
||
Subagents 通过 `Task` 工具将子任务委托给独立 Agent 执行，实现上下文隔离和并行处理。
|
||
|
||
### 内置 3 个委托模板
|
||
|
||
位于 `.cursor/agents/`：
|
||
|
||
| Agent | 职责 | 模式 |
|
||
|-------|------|------|
|
||
| `repo-scout` | 代码库探索、文件定位 | 只读 |
|
||
| `test-runner` | 运行测试、分析失败 | 读写（后台） |
|
||
| `security-sentinel` | 安全扫描、密钥泄漏检测 | 只读 |
|
||
|
||
### 编排模式
|
||
|
||
- **链式**：Repo Scout 探索 -> 主 Agent 实现 -> Test Runner 验证
|
||
- **扇出**：同一任务拆分给多个 Agent 并行处理
|
||
|
||
---
|
||
|
||
## MCP 服务配置
|
||
|
||
`.cursor/mcp.json` 配置 AI 可调用的外部工具。
|
||
|
||
### 已启用服务
|
||
|
||
| 服务 | 用途 |
|
||
|------|------|
|
||
| `context7` | 获取最新库/框架文档 |
|
||
| `filesystem` | 文件系统读写 |
|
||
| `git` | Git 仓库操作 |
|
||
| `fetch` | 网络请求 |
|
||
| `memory` | 跨对话知识图谱记忆 |
|
||
| `sequential-thinking` | 复杂问题分步推理 |
|
||
|
||
### 按需启用（需凭证）
|
||
|
||
| 服务 | 用途 | 配置项 |
|
||
|------|------|--------|
|
||
| `github` | PR / Issue 管理 | `GITHUB_TOKEN` |
|
||
| `mysql` | 直接查询数据库 | 连接信息 |
|
||
| `brave-search` | 网页搜索 | `BRAVE_API_KEY` |
|
||
| `playwright` | 浏览器自动化 | 按需 |
|
||
|
||
---
|
||
|
||
## 文档知识库
|
||
|
||
`docs/` 目录是项目的结构化知识库，AI 按需读取以理解业务背景。
|
||
|
||
```
|
||
docs/
|
||
├── vision/
|
||
│ ├── PRD.md # 产品需求
|
||
│ └── roadmap.md # 路线图
|
||
├── architecture/
|
||
│ ├── system-design.md # 系统架构
|
||
│ ├── data-model.md # 数据模型
|
||
│ ├── api-contracts.md # API 契约
|
||
│ ├── frontend-strategy.md # 双前端架构策略
|
||
│ └── decisions/ # ADR 架构决策记录
|
||
├── guides/
|
||
│ ├── style-guide.md # 代码风格
|
||
│ ├── ui-specs-user.md # 用户端 UI 规范
|
||
│ ├── ui-specs-admin.md # 管理端 UI 规范
|
||
│ └── testing-strategy.md # 测试策略
|
||
├── reference/ # 参考文档
|
||
└── runbooks/ # 运维手册
|
||
```
|
||
|
||
---
|
||
|
||
## 自动化脚本
|
||
|
||
所有脚本位于 `scripts/`，纯 Bash 实现。
|
||
|
||
| 脚本 | 用途 |
|
||
|------|------|
|
||
| `setup.sh` | 一键初始化：创建目录结构、配置 Git Hooks |
|
||
| `ai-guard.sh` | 质量门禁：Lint + 类型检查 + 测试 + 安全扫描 |
|
||
| `skill-manager.sh` | Skills 管理：列出/验证/统计/创建 |
|
||
| `pre-commit` | Git pre-commit Hook |
|
||
| `context-doctor.sh` | 健康检查：验证规则/技能/MCP 配置 |
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
vibe-cursor-pro/
|
||
│
|
||
├── .cursor/ # Cursor 配置中心
|
||
│ ├── rules/ # 33 个 .mdc 规则文件
|
||
│ │ ├── 000-constitution.mdc # [alwaysApply] AI 宪法
|
||
│ │ ├── 001-workflow.mdc # [alwaysApply] PRISM 工作流
|
||
│ │ ├── 002-safety.mdc # [alwaysApply] 安全权限
|
||
│ │ ├── 003-skills.mdc # [alwaysApply] Skills 微索引
|
||
│ │ ├── 010-typescript.mdc # [globs] TypeScript 规范
|
||
│ │ ├── 011-vue.mdc # [globs] Vue 3 规范 + 双前端上下文
|
||
│ │ ├── 012-tailwind.mdc # [globs] Tailwind CSS 规范
|
||
│ │ ├── 013-backend.mdc # [globs] Hyperf 后端规范
|
||
│ │ ├── 014-database.mdc # [globs] 数据库规范
|
||
│ │ ├── 015-testing.mdc # [globs] 测试规范（后端为主）
|
||
│ │ ├── 016-swoole.mdc # [globs] Swoole 协程规范
|
||
│ │ ├── 017-architecture.mdc # [SEMANTIC] 并发架构设计
|
||
│ │ ├── 018-responsive.mdc # [globs] 响应式设计
|
||
│ │ ├── 019-modular.mdc # [SEMANTIC] 模块化架构
|
||
│ │ ├── 020-git.mdc # [SEMANTIC] Git 规范
|
||
│ │ ├── 021-deployment.mdc # [globs] 部署规范
|
||
│ │ ├── 022-performance.mdc # [SEMANTIC] 性能规范+审计流程
|
||
│ │ ├── 023-accessibility.mdc # [globs] 无障碍规范
|
||
│ │ ├── 024-monitoring.mdc # [SEMANTIC] 日志与监控
|
||
│ │ ├── 025-licensing.mdc # [SEMANTIC] 版权合规
|
||
│ │ ├── 026-secure-coding.mdc # [globs] 安全编码
|
||
│ │ ├── 030-subagents.mdc # [SEMANTIC] Subagent 编排
|
||
│ │ ├── 033-refactoring.mdc # [SEMANTIC] 安全重构工作流
|
||
│ │ ├── skill-backend-scaffold.mdc # [globs] 后端模块脚手架
|
||
│ │ ├── skill-code-review.mdc # [SEMANTIC] 代码审查
|
||
│ │ ├── skill-component-scaffold.mdc # [globs] Vue 组件脚手架
|
||
│ │ ├── skill-database-migration.mdc # [globs] 数据库迁移
|
||
│ │ ├── skill-debugging.mdc # [alwaysApply] 调试技能
|
||
│ │ ├── skill-full-feature.mdc # [SEMANTIC] 全链路功能开发
|
||
│ │ ├── skill-i18n.mdc # [SEMANTIC] 国际化
|
||
│ │ ├── skill-security-audit.mdc # [SEMANTIC] 安全审计
|
||
│ │ ├── skill-vue-page.mdc # [globs] Vue 页面脚手架
|
||
│ │ ├── skill-vue-testing.mdc # [globs] 前端测试工作流
|
||
│ │ └── references/ # 规则深度内容（Tier 3）
|
||
│ │
|
||
│ ├── skills/ # 23 个技能（SKILL.md + references/）
|
||
│ │ ├── api-scaffold/ # API 端点脚手架
|
||
│ │ ├── anti-scraping/ # 反爬虫防护
|
||
│ │ ├── bug-reproduce/ # Bug 复现框架
|
||
│ │ ├── code-review/ # 代码审查
|
||
│ │ ├── component-scaffold/ # Vue 组件脚手架
|
||
│ │ ├── database-migration/ # 数据库迁移
|
||
│ │ ├── debugging/ # 调试工作流
|
||
│ │ ├── documentation/ # 文档生成
|
||
│ │ ├── env-setup/ # 环境初始化
|
||
│ │ ├── full-feature/ # 全链路功能开发
|
||
│ │ ├── hyperf-service/ # Hyperf Service 模块
|
||
│ │ ├── i18n/ # 国际化
|
||
│ │ ├── mcp-builder/ # MCP Server 构建
|
||
│ │ ├── message-queue/ # 消息队列
|
||
│ │ ├── nginx-config/ # Nginx 配置
|
||
│ │ ├── performance-audit/ # 性能审计
|
||
│ │ ├── redis-cache/ # Redis 缓存
|
||
│ │ ├── refactoring/ # 重构工作流
|
||
│ │ ├── security-audit/ # 安全审计
|
||
│ │ ├── skill-creator/ # 创建新技能
|
||
│ │ ├── vue-page/ # Vue 页面脚手架
|
||
│ │ ├── vue-testing/ # 前端测试
|
||
│ │ └── websocket-service/ # WebSocket 服务
|
||
│ │
|
||
│ ├── agents/ # 3 个 Subagent 模板
|
||
│ │ ├── repo-scout.md # 代码库探索
|
||
│ │ ├── test-runner.md # 测试执行
|
||
│ │ └── security-sentinel.md # 安全扫描
|
||
│ │
|
||
│ └── mcp.json # MCP 服务配置
|
||
│
|
||
├── docs/ # 项目知识库
|
||
├── scripts/ # 自动化脚本
|
||
│
|
||
├── Case-Database-Backend/ # Hyperf 后端（gitignored）
|
||
├── Case-Database-Frontend-user/ # Vue 3 用户端（gitignored）
|
||
├── Case-Database-Frontend-admin/ # Vue 3 管理端（gitignored）
|
||
├── Case-Database-Frontend-shared/ # 共享层（gitignored）
|
||
│
|
||
├── .cursorignore # Cursor 索引排除
|
||
├── .gitignore
|
||
├── .editorconfig
|
||
├── .prettierrc
|
||
├── commitlint.config.ts
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 定制化指南
|
||
|
||
### 适配不同技术栈
|
||
|
||
宪法级规则（000-003）和大部分技能都是技术栈无关的。
|
||
|
||
**需要替换的文件**：
|
||
|
||
| 文件 | 修改内容 |
|
||
|------|---------|
|
||
| `010-typescript.mdc` | 替换为对应语言规范 |
|
||
| `011-vue.mdc` | 替换为 React / Svelte / Angular 规范 |
|
||
| `012-tailwind.mdc` | 替换为你的 CSS 方案 |
|
||
| `013-backend.mdc` | 替换为 Node.js / Go / Java 后端规范 |
|
||
| `014-database.mdc` | 替换为 PostgreSQL / MongoDB 规范 |
|
||
| `016-swoole.mdc` | 不使用 Swoole 可删除 |
|
||
|
||
**不需要修改**：000-003 宪法级、020-git、023-accessibility、debugging/code-review/refactoring 等通用技能。
|
||
|
||
### 添加新规则
|
||
|
||
在 `.cursor/rules/` 下创建 `.mdc` 文件：
|
||
|
||
```yaml
|
||
---
|
||
description: "规则描述（用于 SEMANTIC 匹配）"
|
||
globs: # 可选：文件匹配模式
|
||
- "**/*.vue"
|
||
alwaysApply: false # 可选：是否始终加载
|
||
---
|
||
|
||
# 规则内容（Markdown）
|
||
```
|
||
|
||
### 添加新技能
|
||
|
||
```bash
|
||
bash scripts/skill-manager.sh create my-new-skill
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Rules 没有生效？
|
||
|
||
1. 确认扩展名为 `.mdc`
|
||
2. 确认 YAML frontmatter 格式正确
|
||
3. 运行 `bash scripts/context-doctor.sh`
|
||
4. 重启 Cursor
|
||
|
||
### Skills 没有自动触发？
|
||
|
||
v4.0 引入了两层激活机制，13 个高频技能已有 `.mdc` 自动入口，应能自动触发。如仍未触发：
|
||
|
||
1. 尝试显式调用：`/skill-name` 或 `@skill-name`
|
||
2. 检查对应 `skill-*.mdc` 的 `description` 是否覆盖了你的使用场景
|
||
3. 检查 SKILL.md 的 `description` 字段
|
||
|
||
### Token 消耗太高？
|
||
|
||
1. 检查 `alwaysApply: true` 的规则数量 — 仅保留 5 个（000/001/002/003/debugging）
|
||
2. 当前 alwaysApply 总量约 12.6KB（~3,600 tokens），在合理范围内
|
||
3. globs 触发的规则仅在编辑匹配文件时注入
|
||
4. SEMANTIC 规则仅在用户意图匹配时注入
|
||
|
||
---
|
||
|
||
## 版本历史
|
||
|
||
| 版本 | 日期 | 变更 |
|
||
|------|------|------|
|
||
| v4.0 | 2026-03-01 | **Skill 命中率优化三轮迭代**：引入两层激活机制（skill-*.mdc 自动注入 + SKILL.md 按需加载）；alwaysApply 从 32KB 降至 12.6KB（-60%）；消除 available_skills 幻觉概念；合并冗余规则（api-scaffold + hyperf-service -> backend-scaffold / 022-performance 吸收 audit / 011-vue 吸收 context / 015-testing 去重前端）；019-modular 和 017-architecture 从 globs 改 SEMANTIC 降低注入量；13 个技能有 .mdc 自动入口，10 个低频技能按需 Read；策略 B 双向标注（.mdc 指向 SKILL.md，SKILL.md 标注 .mdc）|
|
||
| v3.7 | 2026-02-26 | 双前端架构适配：新增用户端/管理端/共享层目录和规则 |
|
||
| v3.6 | 2026-02-26 | Workspace 模式（推荐）：vibe-cursor-pro 作为主工作区 |
|
||
| v3.5 | 2026-02-24 | 全栈防爬（T1~T5）；新增 018/019/025 规则；版权合规 |
|
||
| v3.4 | 2026-02-24 | 深度对齐旧项目分析报告 |
|
||
| v3.3 | 2026-02-24 | PHPbase：迁移至 Vue 3 + PHP Hyperf + Swoole |
|
||
| v3.0 | 2026-02-12 | Cursor 专属重构 |
|