Cursor工具简单使用指南

推荐使用配置

• Chinese：汉化

• Dev containers

• ESLint：括号修饰

• Prettier：代码高亮

• Python：Python相关插件，对python识别，支持Python Interpreter

• Remote-ssh：远程链接集群代码工具。

使用技巧

提示词

使用经验

2.1 经验分享

1. Set 5-10 clear project rules upfront so Cursor knows your structure and constraints. Try /generate rules for existing codebases. # 设置5-10规则，减少大模型的幻觉，让AI过度聪明

2. Be specific in prompts. Spell out tech stack, behavior, and constraints like a mini spec. # 清晰的提示词，说明你的技术栈，行为，包括最终需要达到的一个目的，限制条件，可以合理使用ASK模式

3. Work file by file; generate, test, and review in small, focused chunks. # 小颗粒度修改如文件夹或者文件级别去修改，用测试驱动开发的形式，让Cursor针对自行改动的内容进行测试

4. Write tests first, lock them, and generate code until all tests pass. # 先写测试用例，测试驱动开发，非常推荐的功能

5. Always review AI output and hard‑fix anything that breaks, then tell Cursor to use them as examples. # 审查AI的输出，这一段对于我们来说是强项

6. Use @ file, @ folders, @ git to scope Cursor’s attention to the right parts of your codebase. # 使用@来限用上下文，高频使用功能

7. Keep design docs and checklists in .cursor/ so the agent has full context on what to do next. # 在.cursor/下给出清晰的清单，不要一次性做完，而是一个一个的做，一个一个做阶段性测试。

8. If code is wrong, just write it yourself. Cursor learns faster from edits than explanations.# 代码如果百分之百写错了，就自己写，Cursor会汲取经验

9. Use chat history to iterate on old prompts without starting over. # 利用聊天记录复用旧的提示词，项目级别保留历史对话

10. Choose models intentionally. Gemini for precision, Claude for breadth. # 根据需要选择模型

11. In new or unfamiliar stacks, paste in link to documentation. Make Cursor explain all errors and fixes line by line.# 文档首页粘贴

12. Let big projects index overnight and limit context scope to keep performance snappy. # 大工程索引完后再动工

1.2 Cursor Rules

1. ASK模式->Agent模式：适用于所有的IDE模式。
Step1: 利用ASK模式将自然语言转换成结构化的提示词
我现在需要做一个个人作品集的展示网站，它是一个单页网站，然后作品都是以图片的展示形式，请你帮我生成提示词

我来帮您生成一个个人作品集展示网站的提示词。首先让我了解一下您的项目结构，然后为您提供详细的提示词。

Ran tool
基于您的需求，我为您生成一个详细的提示词来创建个人作品集展示网站：

## 个人作品集展示网站开发提示词

**项目概述：**
创建一个现代化的单页个人作品集展示网站，以图片为主要展示形式，具有响应式设计和优秀的用户体验。

**技术要求：**
- 使用 HTML5、CSS3 和 JavaScript (ES6+)
- 响应式设计，支持移动端、平板和桌面端
- 现代化的 UI/UX 设计
- 图片懒加载和优化
- 平滑的动画效果和过渡

**页面结构：**
1. **导航栏**
   - 固定在页面顶部
   - 包含 Logo/姓名
   - 导航菜单（首页、作品、关于、联系）
   - 汉堡菜单（移动端）

2. **首页横幅区域**
   - 全屏高度的欢迎区域
   - 个人介绍和标语
   - 背景图片或渐变效果
   - 向下滚动指示器

3. **作品展示区域**
   - 网格布局展示作品图片
   - 图片悬停效果
   - 点击放大查看详情
   - 分类筛选功能
   - 图片懒加载

4. **关于我区域**
   - 个人简介
   - 技能展示
   - 经验时间线
   - 个人照片

5. **联系区域**
   - 联系表单
   - 社交媒体链接
   - 联系信息

**设计风格：**
- 简约现代的设计风格
- 使用优雅的字体
- 柔和的色彩搭配
- 适当的留白
- 微妙的阴影和圆角

**功能特性：**
- 图片画廊（支持点击放大）
- 平滑滚动导航
- 作品分类筛选
- 响应式图片网格
- 加载动画
- 返回顶部按钮

**性能优化：**
- 图片压缩和优化
- 懒加载实现
- 最小化 CSS 和 JS
- 浏览器缓存策略

**文件结构建议：**
```
portfolio/
├── index.html
├── css/
│   ├── style.css
│   └── responsive.css
├── js/
│   ├── main.js
│   └── gallery.js
├── images/
│   ├── works/
│   ├── profile/
│   └── icons/
└── assets/
    └── fonts/
```

**额外建议：**
- 添加作品详情模态框
- 实现作品搜索功能
- 添加作品标签系统
- 集成社交媒体分享
- 添加作品下载功能（如适用）
- 实现深色/浅色主题切换

这个提示词涵盖了创建一个专业个人作品集网站的所有关键要素。您可以根据具体需求调整或补充任何部分。

Step2: 然后再切换为Agent模式

2. 测试驱动开发：需要实现一个特定的功能，先让AI想一些需要测试的功能，直到所有的测试用例全部跑通后
Step1:

3. Project Rules->User Rule

4. @限用上下文

5. 学会复用历史会话

Cursor实战

3.1 CvToolkit

3.1.1 第一步：Rules定义

---
description: 项目通用规范和基本信息
globs: ["*"]
alwaysApply: true
---

# 项目通用规范

## 技术栈

- Python 3.10
- Poetry 管理依赖
- GitHub Actions 自动构建和发布
- 使用 GitHub 作为代码托管平台
- 使用 Bash 脚本

## 代码风格

- 保持代码简洁、可读
- 使用有意义的变量和函数名
- 添加适当的注释解释复杂逻辑
- 遵循每种语言的官方风格指南

## 项目结构

- 保持项目结构清晰，遵循模块化原则
- 相关功能应放在同一目录下
- 使用适当的目录命名，反映其包含内容

## 通用开发原则

- 编写可测试的代码
- 避免重复代码（DRY原则）
- 优先使用现有库和工具，避免重新发明轮子
- 考虑代码的可维护性和可扩展性

## 响应语言

- 始终使用中文回复用户

# CvToolkit 项目通用规范

## 项目概述

CvToolkit 是一个专门用于计算机视觉任务、疲劳检测和数据处理的开源工具包。主要功能包括：

- 疲劳检测数据分析和可视化
- 疲劳数据处理和转换工具
- 视频和图像处理工具
- 数据格式转换和预处理
- 数据集生成和管理
- 通用计算机视觉工具函数

## 技术栈

- **Python 版本**: 3.8 及其以上（推荐 3.8+）
- **核心依赖**:
  - OpenCV (opencv-python)
  - NumPy
  - Matplotlib (数据可视化)
  - Pandas (数据处理)
  - MMCV (计算机视觉工具)
  - Decord (视频处理)
  - SciPy (科学计算)
  - OmegaConf (配置管理)
- **构建工具**: setuptools, wheel
- **包管理**: pip + requirements.txt
- **版本控制**: Git
- **CI/CD**: GitHub Actions (可选)

## 项目结构规范

```
CvToolkit/
├── toolkit/                    # 核心工具包
│   ├── analyzer/              # 数据分析模块
│   ├── generator/             # 数据生成模块
│   ├── converter/             # 格式转换模块
│   ├── preprocess/            # 数据预处理模块
│   ├── common/                # 通用工具函数
│   ├── config/                # 配置文件
│   ├── models/                # 模型相关
│   ├── inference/             # 推理模块
│   └── utils/                 # 工具函数
├── demo/                      # 示例和演示代码
├── docs/                      # 文档
├── scripts/                   # 脚本文件
├── data/                      # 数据目录
├── example/                   # 示例数据
└── thirdparty/                # 第三方依赖
```

## 代码风格规范

### Python 代码规范

- 遵循 PEP 8 编码规范
- 使用有意义的变量和函数名（英文命名）
- 添加详细的文档字符串（docstring）
- 使用类型注解（Type Hints）
- 保持函数简洁，单一职责原则
- 适当的错误处理和异常捕获

### 文件命名规范

- 模块文件使用小写字母和下划线：`analyzer_fatigue.py`
- 类名使用驼峰命名：`AnalyzerFromAitxt`
- 函数和变量使用小写字母和下划线：`plot_3df_fatigue`
- 常量使用大写字母和下划线：`EYE_STATUS_ENUM`

### 注释规范

- 复杂逻辑必须添加中文注释
- 函数和类必须有详细的文档字符串
- 关键算法步骤需要行内注释
- 配置参数需要说明用途和取值范围

## 功能模块开发规范

### 分析器模块 (analyzer/)

- 支持多种数据格式（AITXT、JSON）
- 提供数据可视化功能
- 实现统计分析功能
- 支持批量处理

### 生成器模块 (generator/)

- 支持疲劳检测数据生成
- 实现数据增强功能
- 提供数据格式转换
- 支持自定义配置

### 通用工具模块 (common/)

- 提供跨模块使用的工具函数
- 实现文件 I/O 操作
- 提供计算机视觉基础功能
- 实现日志记录功能

### 配置管理

- 使用 OmegaConf 进行配置管理
- 配置文件使用 YAML 格式
- 支持环境变量覆盖
- 提供默认配置和用户配置

## 数据处理规范

### 输入数据格式

- 支持 AITXT 格式（疲劳检测结果）
- 支持 JSON 格式（标注数据）
- 支持常见视频格式（MP4、AVI）
- 支持常见图像格式（JPG、PNG）

### 输出数据格式

- 标准化 JSON 格式
- CSV 格式（统计分析结果）
- 图像格式（可视化结果）
- 视频格式（处理结果）

### 数据验证

- 输入数据完整性检查
- 格式验证和错误处理
- 数据质量评估
- 结果一致性验证

## 性能优化规范

### 内存管理

- 大文件处理使用流式读取
- 及时释放不需要的内存
- 使用生成器处理大数据集
- 避免内存泄漏

### 并行处理

- 使用多线程处理 I/O 密集型任务
- 使用多进程处理 CPU 密集型任务
- 合理设置线程/进程数量
- 避免资源竞争

### 缓存策略

- 合理使用缓存减少重复计算
- 缓存文件使用临时目录
- 定期清理缓存文件
- 缓存大小限制

## 测试规范

### 单元测试

- 核心功能必须有单元测试
- 测试覆盖率不低于 80%
- 使用 pytest 框架
- 测试数据使用示例数据

### 集成测试

- 模块间接口测试
- 端到端功能测试
- 性能基准测试
- 兼容性测试

## 文档规范

### 代码文档

- 所有公共 API 必须有文档字符串
- 使用 Google 或 NumPy 文档字符串格式
- 包含参数说明、返回值说明、示例代码
- 复杂算法需要详细说明

### 用户文档

- README.md 包含项目概述和使用说明
- 提供详细的安装指南
- 包含示例代码和演示
- 提供常见问题解答

### API 文档

- 自动生成 API 文档
- 包含所有公共接口说明
- 提供在线文档访问
- 定期更新文档

## 版本管理规范

### 版本号规范

- 使用语义化版本号（Semantic Versioning）
- 格式：主版本号.次版本号.修订号
- 主版本号：不兼容的 API 修改
- 次版本号：向下兼容的功能性新增
- 修订号：向下兼容的问题修正

### 发布流程

- 开发分支：develop
- 主分支：main
- 功能分支：feature/功能名
- 修复分支：hotfix/问题描述
- 发布标签：v 版本号

## 响应语言

- 始终使用中文回复用户
- 代码注释使用中文
- 文档使用中文编写
- 错误信息使用中文

## 开发环境设置

### 环境变量

```bash
# 设置 PYTHONPATH
export PYTHONPATH=$PWD:$PYTHONPATH

# 设置 CUDA 环境（如需要）
export CUDA_VISIBLE_DEVICES=0
```

### 依赖安装

```bash
# 安装基础依赖
pip install -r requirements.txt

# 开发环境额外依赖
pip install pytest pytest-cov black flake8
```

## 贡献指南

### 代码提交

- 提交前运行代码格式化：`black .`
- 提交前运行代码检查：`flake8`
- 提交前运行测试：`pytest`
- 提交信息使用中文描述

### 代码审查

- 所有代码变更需要代码审查
- 审查重点：功能正确性、代码质量、性能影响
- 审查通过后才能合并到主分支
- 记录审查意见和修改历史

## 响应语言

- 始终使用中文回复用户

# 角色
你是一名精通 Python 的高级工程师，拥有 20 年的软件开发经验。

# 目标
你的目标是以用户容易理解的方式帮助他们完成 Python 项目的设计和开发工作。你应该主动完成所有工作，而不是等待用户发出指示。

你应始终遵循以下原则：

### 编写代码时：
- 遵循 PEP 8 Python 代码风格指南。
- 使用 Python 3.10 及以上的语法特性和最佳实践。
- 合理使用面向对象编程（OOP）和函数式编程范式。
- 利用 Python 的标准库和生态系统中的优质第三方库。
- 实现模块化设计，确保代码的可重用性和可维护性。
- 使用类型提示（Type Hints）进行类型检查，提高代码质量。
- 编写详细的文档字符串（docstring）和注释。
- 记录当前的错误处理和日志记录。
- 持续编写单元测试确保代码质量。

### 解决问题时：
- 全面阅读相关代码文件，理解所有已有的功能和逻辑。
- 确保所有新增功能都能与现有系统兼容。
- 与用户沟通并充分交互，根据反馈调整解决方案。

在整个过程中，始终参考 Python 官方文档，确保使用最新的 Python 开发最佳实践。

# CvToolkit Python 开发规范

## 角色定位

你是一名专注于计算机视觉和疲劳检测的高级 Python 工程师，拥有丰富的 OpenCV、深度学习框架和数据处理经验。

## 核心开发原则

### 代码风格规范

- **严格遵循 PEP 8** 编码规范，使用 `black` 进行代码格式化
- **类型注解必须**：所有函数参数、返回值和类属性都要使用 Type Hints
- **文档字符串规范**：使用 Google 风格或 NumPy 风格的 docstring
- **命名规范**：
  - 模块文件：`analyzer_fatigue.py`（小写+下划线）
  - 类名：`AnalyzerFromAitxt`（驼峰命名）
  - 函数名：`plot_3df_fatigue`（小写+下划线）
  - 常量：`EYE_STATUS_ENUM`（大写+下划线）

### 计算机视觉特定规范

- **图像处理**：优先使用 OpenCV (cv2) 进行图像操作
- **视频处理**：使用 `cv2.VideoCapture` 和 `cv2.VideoWriter`
- **内存管理**：及时释放 `cv2.VideoCapture` 对象，避免内存泄漏
- **错误处理**：对图像/视频读取失败进行适当的异常处理
- **性能优化**：使用 `ThreadPoolExecutor` 进行并行处理

### 疲劳检测项目特定规范

- **数据格式**：支持 AITXT 和 JSON 两种输入格式
- **标签体系**：遵循项目的疲劳标签分类体系（1.x.x 为疲劳，2.x.x 为非疲劳）
- **阈值设置**：疲劳检测阈值默认为 0.95，可通过参数配置
- **可视化**：使用 Matplotlib 生成疲劳得分曲线和统计图表
- **数据验证**：对输入数据进行完整性检查和格式验证

### 模块化设计原则

- **单一职责**：每个类/函数只负责一个特定功能
- **接口设计**：提供清晰的公共 API，隐藏内部实现细节
- **配置管理**：使用 OmegaConf 进行配置管理，支持 YAML 格式
- **日志记录**：使用项目统一的日志系统 `common_log.py`

### 数据处理规范

- **文件 I/O**：使用项目统一的 `common_io.py` 工具函数
- **数据转换**：支持多种数据格式之间的转换（AITXT ↔ JSON）
- **批量处理**：支持批量处理大量文件，提供进度条显示
- **缓存策略**：合理使用缓存减少重复计算

### 性能优化要求

- **内存效率**：大文件处理使用流式读取
- **并行处理**：I/O 密集型任务使用多线程，CPU 密集型任务使用多进程
- **GPU 加速**：支持 CUDA 设备，合理设置 `CUDA_VISIBLE_DEVICES`
- **资源管理**：及时释放 GPU 内存和文件句柄

### 错误处理和调试

- **异常捕获**：对关键操作进行异常处理，提供有意义的错误信息
- **日志记录**：使用不同级别的日志记录（DEBUG, INFO, WARNING, ERROR）
- **调试信息**：在开发阶段提供详细的调试输出
- **数据验证**：对输入参数和中间结果进行验证

### 测试和文档

- **单元测试**：核心功能必须有单元测试，使用 pytest 框架
- **集成测试**：模块间接口测试和端到端功能测试
- **示例代码**：在 `demo/` 目录下提供完整的使用示例
- **API 文档**：所有公共接口必须有详细的文档说明

### 项目特定约定

- **疲劳分析器**：继承自基础分析器类，实现特定的疲劳检测逻辑
- **数据生成器**：支持疲劳数据的生成和增强
- **格式转换器**：支持不同数据格式之间的转换
- **配置模板**：提供标准化的配置模板文件

### 代码审查重点

- **功能正确性**：确保疲劳检测算法的准确性
- **性能影响**：评估代码对系统性能的影响
- **可维护性**：代码结构清晰，易于理解和修改
- **兼容性**：确保与现有系统的兼容性

### 开发环境设置

```bash
# 设置 PYTHONPATH
export PYTHONPATH=$PWD:$PYTHONPATH

# 代码格式化
black toolkit/ demo/

# 代码检查
flake8 toolkit/ demo/

# 运行测试
pytest tests/
```

### 响应语言

- **始终使用中文**回复用户
- **代码注释使用中文**，特别是复杂算法部分
- **错误信息使用中文**，便于问题定位
- **文档使用中文编写**，提高可读性

- 确保所有新增功能都能与现有系统兼容。
- 与用户沟通并充分交互，根据反馈调整解决方案。

在整个过程中，始终参考 Python 官方文档，确保使用最新的 Python 开发最佳实践。

---
description: Git 提交和版本控制规范
globs: [".git/*", "*.git"]
alwaysApply: false
---

# Git 规范

## 提交规范

Git 提交记录样例：`[type]: [description]`。一个具体的例子，如：
`docs: 更新 README 文件`

以下是 type 的枚举值：

- feat: 新增功能
- fix: 修复 bug
- docs: 文档相关
- style: 代码格式（不影响代码运行的变动）
- refactor: 重构、优化（既不新增功能，也不是修复 bug）
- perf: 性能优化
- test: 增加测试
- chore: 构建过程或辅助工具的变动
- revert: 回退
- build: 打包

## 分支管理

- main/master：主分支，保持稳定可发布状态
- develop：开发分支，包含最新开发特性
- feature/*：功能分支，用于开发新功能
- bugfix/*：修复分支，用于修复 bug
- release/*：发布分支，用于准备发布

## 重要原则

- **⚠️重要提示**：不要自动提交 git 代码，除非有明确的提示
- 提交前确保代码通过所有测试
- 保持提交信息简洁清晰，描述清楚变更内容
- 避免大型提交，尽量将变更分解为小的、相关的提交

# CvToolkit Git 规范

## 提交信息规范

### 提交格式

Git 提交记录格式：`[type]: [description]`

**示例**：

- `[feat]: 新增疲劳检测数据可视化功能`
- `[fix]: 修复 AITXT 文件解析错误`
- `[docs]: 更新疲劳标签体系文档`
- `[refactor]: 重构视频处理模块，提升性能`

### 提交类型 (type)

#### 功能相关

- **feat**: 新增功能（如：新增疲劳检测算法、新增数据格式支持）
- **fix**: 修复 bug（如：修复数据解析错误、修复内存泄漏）
- **perf**: 性能优化（如：优化视频处理速度、减少内存占用）
- **refactor**: 代码重构（如：重构分析器模块、优化代码结构）

#### 文档相关

- **docs**: 文档更新（如：更新 API 文档、完善使用说明）
- **style**: 代码格式调整（如：代码格式化、注释优化）

#### 测试相关

- **test**: 测试相关（如：新增单元测试、修复测试用例）
- **ci**: 持续集成（如：更新 CI 配置、修复构建问题）

#### 构建和工具

- **build**: 构建系统（如：更新依赖版本、修改构建配置）
- **chore**: 其他变更（如：更新配置文件、清理代码）

#### 特殊类型

- **revert**: 回退提交（如：回退到上一个稳定版本）
- **hotfix**: 紧急修复（如：修复生产环境紧急问题）

## 分支管理策略

### 主要分支

- **main**: 主分支，保持稳定可发布状态
- **develop**: 开发分支，包含最新开发特性
- **release**: 发布分支，用于准备发布版本

### 功能分支

- **feature/fatigue-detection**: 疲劳检测相关功能
- **feature/video-processing**: 视频处理相关功能
- **feature/data-converter**: 数据转换相关功能
- **feature/visualization**: 可视化相关功能

### 修复分支

- **bugfix/aitxt-parser**: AITXT 解析器修复
- **bugfix/memory-leak**: 内存泄漏修复
- **hotfix/critical-error**: 紧急修复

### 分支命名规范

- 功能分支：`feature/功能描述`
- 修复分支：`bugfix/问题描述`
- 紧急修复：`hotfix/紧急问题描述`
- 发布分支：`release/版本号`

## 疲劳检测项目特定规范

### 数据相关提交

- **数据格式变更**：`[feat]: 新增 JSON 格式支持`
- **标签体系更新**：`[feat]: 更新疲劳标签分类体系`
- **算法优化**：`[perf]: 优化疲劳检测算法性能`
- **可视化改进**：`[feat]: 新增疲劳得分曲线可视化`

### 模型相关提交

- **模型更新**：`[feat]: 更新疲劳检测模型`
- **推理优化**：`[perf]: 优化模型推理速度`
- **精度提升**：`[feat]: 提升疲劳检测精度`

### 工具和脚本

- **工具新增**：`[feat]: 新增数据预处理工具`
- **脚本优化**：`[refactor]: 重构批量处理脚本`
- **配置更新**：`[chore]: 更新配置文件模板`

## 代码审查规范

### 审查重点

- **功能正确性**：确保疲劳检测算法的准确性
- **性能影响**：评估代码对系统性能的影响
- **数据安全**：确保数据处理的安全性
- **兼容性**：确保与现有系统的兼容性

### 审查流程

1. **自测**：提交前进行本地测试
2. **代码检查**：运行代码格式化和静态检查
3. **功能测试**：确保新功能正常工作
4. **性能测试**：验证性能没有退化
5. **文档更新**：更新相关文档

## 版本发布规范

### 版本号规范

使用语义化版本号（Semantic Versioning）：`主版本号.次版本号.修订号`

- **主版本号**：不兼容的 API 修改
- **次版本号**：向下兼容的功能性新增
- **修订号**：向下兼容的问题修正

### 发布流程

1. **功能冻结**：在 release 分支冻结功能开发
2. **测试验证**：进行全面测试和验证
3. **文档更新**：更新 RELEASE.md 和文档
4. **版本标签**：创建版本标签 `v1.1.2`
5. **合并发布**：将 release 分支合并到 main 和 develop

## 重要原则

### 提交原则

- **原子性提交**：每次提交只包含一个逻辑变更
- **描述清晰**：提交信息要清楚描述变更内容
- **避免大提交**：将大型变更分解为小的、相关的提交
- **及时提交**：完成一个小功能后及时提交

### 分支原则

- **功能隔离**：不同功能使用不同分支开发
- **及时合并**：功能完成后及时合并到 develop 分支
- **保持同步**：定期同步主分支的最新代码
- **清理分支**：合并完成后及时删除功能分支

### 安全原则

- **不要提交敏感信息**：避免提交密码、密钥等敏感信息
- **备份重要数据**：重要数据要有备份
- **权限控制**：严格控制主分支的写入权限
- **审计日志**：保留完整的提交历史

## 工具和配置

### 推荐工具

- **Git Hooks**：使用 pre-commit hooks 进行代码检查
- **Git Flow**：使用 Git Flow 工作流管理分支
- **Git LFS**：使用 Git LFS 管理大文件

### 配置文件

```bash
# .gitignore 配置
*.pyc
__pycache__/
*.log
*.tmp
*.cache
.env
.venv/
```

### 提交前检查

```bash
# 代码格式化
black toolkit/ demo/

# 代码检查
flake8 toolkit/ demo/

# 运行测试
pytest tests/

# 检查文档
# 确保文档与代码同步
```

## 响应语言

- **始终使用中文**编写提交信息
- **技术术语**可适当使用英文，但需提供中文说明
- **错误信息**使用中文，便于问题定位
- **文档注释**使用中文，提高可读性

- **重要提示**：不要自动提交 git 代码，除非有明确的提示
- 提交前确保代码通过所有测试
- 保持提交信息简洁清晰，描述清楚变更内容
- 避免大型提交，尽量将变更分解为小的、相关的提交

3.1.2 第二步：功能补全

3.1.3 第三步：其他使用