初始化

README.md

@@ -0,0 +1,613 @@
+# 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 专属重构 |