render-api/.cursorrules at master · feng3d-labs/render-api · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
# Cursor 项目规则

## Git 提交信息规范

当生成 Git 提交信息时：

1. **语言**：始终使用简体中文

2. **格式**：遵循约定式提交（Conventional Commits）格式
   ```
   <类型>(<范围>): <简短描述>

   [可选的详细说明]

   [可选的脚注]
   ```

3. **提交类型**（中文描述）：
   - `feat`: 新增功能
   - `fix`: 修复问题
   - `refactor`: 代码重构（不改变功能）
   - `perf`: 性能优化（图形渲染项目重点关注）
   - `style`: 代码格式调整（不影响代码含义）
   - `docs`: 文档更新
   - `test`: 测试相关
   - `chore`: 构建过程或辅助工具的变动
   - `build`: 构建系统或外部依赖项的更改
   - `ci`: CI 配置文件和脚本的更改

4. **范围**（可选）：可以是模块、组件或功能区域，如 `webgl`、`webgpu`、`test` 等

5. **提交信息要求**：
   - 第一行简短描述，不超过 50 个字符
   - 使用祈使句，如"添加"、"修复"、"优化"
   - 描述要清晰、具体、有意义
   - 如有必要，添加详细说明，解释"为什么"而不是"是什么"
   - 性能优化提交应说明优化点和预期效果

6. **示例**：
   ```
   feat(webgl): 添加深度测试功能

   - 实现深度缓冲区管理
   - 添加深度测试配置选项
   - 更新相关文档
   ```

   ```
   perf(webgpu): 优化纹理上传性能

   - 使用批量上传减少 GPU 调用次数
   - 预期性能提升 30%
   ```

## 代码风格

- 优先使用 TypeScript
- 遵循现有代码的命名约定和格式
- 添加必要的中文注释以提高代码可读性
- 使用 ESLint 和 Prettier 保持代码格式一致
- 提交前必须通过 lint 检查
- 避免使用 `any` 类型，优先使用明确的类型定义

## 命名规范

- **变量和函数**：使用驼峰命名（camelCase）
- **类和接口**：使用帕斯卡命名（PascalCase）
- **常量**：使用全大写下划线分隔（UPPER_SNAKE_CASE）
- **文件名**：使用小写字母和连字符（kebab-case）或与导出的主要类/函数同名，优先使用函数名

## 注释规范

- 公共 API 必须添加 JSDoc 注释
- 复杂逻辑必须添加中文注释说明
- 临时解决方案或待优化代码必须添加 TODO 注释
- 注释应该解释"为什么"而不是"是什么"

## 代码组织结构

- **配置文件结构**：在配置文件中（如 `vite.config.js`、`test_vite.config.js` 等），应按照以下顺序组织代码：
  - **文件头部**：导入语句、配置变量（可更改的设置）、主要执行逻辑（如 `export default defineConfig()`）
  - 其次是导出函数以及类应该放在文件前面
  - 再其次是私有函数和类应该放在文件后面
  - **文件尾部**：函数定义（所有辅助函数和工具函数）

  这样可以让配置文件的主要配置和执行逻辑一目了然，而将实现细节放在后面。

- **模块结构**：
  - 避免使用默认导出，优先使用命名导出
  - 避免不必要的导出
  - 每个文件应该有一个明确的职责
  - 每个文件应该不超过 300 行代码
  - 相关功能应该组织在同一个目录下
  - 使用清晰的目录结构（如 `src/utils/`、`src/types/` 等）
  - 每个模块应该有清晰的职责边界
  - 模块间依赖应该明确且最小化
  - 公共 API 应该稳定，变更需要充分讨论

- **渲染相关代码**：
  - Shader 代码应单独文件管理
  - 渲染管线相关代码应组织在专门的目录
  - 资源管理代码应与渲染逻辑分离

## 性能优化规范

- **内存管理**：
  - 及时释放 GPU 资源（纹理、缓冲区等）
  - 避免内存泄漏，特别是在渲染循环中
  - 使用对象池复用频繁创建的对象

- **渲染优化**：
  - 减少 draw call 数量
  - 合理使用批处理（batching）
  - 避免在渲染循环中进行不必要的计算
  - 使用缓存避免重复计算

- **类型安全**：
  - 避免使用 `any` 类型
  - 为 GPU 资源提供明确的类型定义
  - 使用类型守卫确保运行时类型安全

## 错误处理

- 优先使用明确的错误类型
- 提供有意义的错误消息
- 避免静默失败，除非有明确的业务需求

## 代码审查规范

- 所有代码变更必须经过代码审查
- 审查重点：
  - 代码逻辑正确性
  - 性能影响
  - 类型安全
  - 测试覆盖
  - 文档完整性

## 文档规范

- 公共 API 必须包含完整的 JSDoc 注释
- 复杂算法或业务逻辑必须添加说明文档
- README 文件应该保持更新
- 重大变更应该更新 CHANGELOG

## 测试规范

- 新功能必须包含相应的测试
- 修复 bug 时必须添加回归测试
- 关键渲染功能必须包含测试
- 性能关键路径应包含性能测试
- 使用 WebGL/WebGPU 测试框架进行渲染测试
- 测试覆盖率应该保持在合理水平（建议 > 80%）
- 测试应该清晰、独立、可重复

## agent 规则

- 没有正确修复问题时重新让修复时，尽量还原上次修改的内容后再进行修复
- 每次完成代码修改后，必须检查并处理编译错误（使用 ReadLints 工具或运行测试）
- 确保所有测试通过后再告知用户任务完成