大改版,可以针对不同项目引擎进行初始化
This commit is contained in:
@@ -21,7 +21,6 @@ alwaysApply: true
|
||||
|
||||
创建环境、安装依赖、启动项目或运行测试前,先确认项目声明的运行时版本;禁止直接采用系统默认版本,也不得擅自升级到最新或预发布版本。
|
||||
|
||||
- Godot:检查 `project.godot` 的兼容声明、项目 README 的版本要求,以及 `.cursor/local-env.json` 记录的本机可执行文件与版本;本机配置只用于选择运行时,不能覆盖项目要求。
|
||||
- Python:检查 `pyproject.toml`、`.python-version` 和 README。
|
||||
- Node.js:检查 `package.json` 的 `engines`、`.nvmrc`、`.node-version` 和 README。
|
||||
- 声明互相冲突时指出冲突;版本仍不明确时,先向用户确认再安装或执行。
|
||||
|
||||
@@ -33,6 +33,6 @@ alwaysApply: true
|
||||
|
||||
## Skill 一致性
|
||||
|
||||
- 创建、删除、重命名或修改任何 Skill 后,同步 `.cursor/skills/epee-orchestrator/registry.md`,确保名称、入口、能力描述与触发条件一致。
|
||||
- 创建、删除、重命名或修改任何 Skill 后,同步 `.cursor/bootstrap/skills.json` 与所属 manifest,再运行初始化脚本生成 Registry,确保名称、入口、能力描述与触发条件一致。
|
||||
- Skill 使用出现遗漏、误触或系统性偏差时,按 `epee-orchestrator` Skill 的自迭代流程处理。
|
||||
- 用户明确限制可修改路径时,以该限制为准:报告未能执行的日志或 registry 写入,不越权修改。
|
||||
|
||||
@@ -7,7 +7,12 @@ alwaysApply: true
|
||||
|
||||
## 首次会话自检
|
||||
|
||||
处理每次会话的第一个用户任务前,检查 `.cursor/.init-done`:
|
||||
处理每次会话的第一个用户任务前,先检查项目根 `.cursor-init-source`:
|
||||
|
||||
- 存在:当前仓库用于开发初始化框架,不自动运行 cursor-init;用户讨论或修改初始化流程也不视为手动初始化。
|
||||
- 不存在:再检查 `.cursor/.init-done`。
|
||||
|
||||
目标项目中的 sentinel 规则:
|
||||
|
||||
- 文件存在:正常处理任务;没有显式触发词时不重复提醒。
|
||||
- 文件不存在:说明仓库尚未完成 Cursor 初始化,概述原任务,并在执行清理、移动、覆盖等操作前取得用户确认。
|
||||
@@ -15,6 +20,14 @@ alwaysApply: true
|
||||
|
||||
用户确认后读取 `.cursor/skills/cursor-init/SKILL.md`,严格按其当前阶段执行。Skill 不存在时停止初始化并报告缺失,不自行实施破坏性替代流程。
|
||||
|
||||
项目类型选项必须来自:
|
||||
|
||||
```bash
|
||||
python .cursor/bootstrap/tools/cursor_init.py --list-types --json
|
||||
```
|
||||
|
||||
只展示脚本返回的 ready 类型,不把文档中的示例、draft bundle 或 MCP 工具当作支持类型。
|
||||
|
||||
## 手动触发
|
||||
|
||||
以下意图触发完整初始化或重置:`初始化 cursor`、`cursor init`、`重置 cursor`、`reset cursor`、清理复制来的 `.cursor`。
|
||||
@@ -24,6 +37,6 @@ alwaysApply: true
|
||||
## 执行约束
|
||||
|
||||
- 开始前检查工作区状态,提醒用户处理未提交改动。
|
||||
- 删除、重置、覆盖和批量移动前提供 dry-run 清单并取得确认。
|
||||
- 删除、重置、覆盖和批量移动前提供脚本生成的完整 dry-run 与 `PLAN_DIGEST` 并取得确认。
|
||||
- 分类不清的文件逐项询问,不猜测归属。
|
||||
- 流程保持幂等;重复执行不应破坏已经正确的状态。
|
||||
|
||||
@@ -9,7 +9,7 @@ alwaysApply: true
|
||||
|
||||
- 引擎插件、addon、扩展和原生库;
|
||||
- npm、pip 等包管理依赖及锁文件变更;
|
||||
- Asset Library 或网络来源的素材、字体、音频、模型和模板;
|
||||
- 引擎/平台资源库或网络来源的素材、字体、音频、模型和模板;
|
||||
- 会改变构建、导出或运行环境的工具链组件。
|
||||
|
||||
确认前说明:名称、用途、目标版本、来源、许可、维护状态、影响范围,以及工程内是否已有替代方案。
|
||||
|
||||
@@ -16,9 +16,10 @@ alwaysApply: true
|
||||
|
||||
创建、删除、重命名或修改任何 Skill 后:
|
||||
|
||||
1. 更新 `.cursor/skills/epee-orchestrator/registry.md` 中的对应条目。
|
||||
2. 使名称、能力说明、适用场景和入口路径与实际内容一致。
|
||||
3. 不保留指向已删除 Skill 的条目。
|
||||
1. 更新 `.cursor/bootstrap/skills.json` 与所属 common/type manifest。
|
||||
2. 使名称、作用域、能力说明、适用场景和入口路径与实际内容一致。
|
||||
3. 运行 `python .cursor/bootstrap/tools/cursor_init.py --sync-registry` 生成 Registry。
|
||||
4. 不保留指向已删除 Skill 的机读条目或 manifest 引用。
|
||||
|
||||
## 自迭代
|
||||
|
||||
|
||||
1
.cursor/rules/project/.gitkeep
Normal file
1
.cursor/rules/project/.gitkeep
Normal file
@@ -0,0 +1 @@
|
||||
|
||||
@@ -1,41 +0,0 @@
|
||||
---
|
||||
description: Godot 项目的分层、依赖方向、信号解耦与工程完整性约定
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Godot 分层架构
|
||||
|
||||
先识别项目已有目录、autoload 和通信方式,再沿用其边界;不要仅为套用规则而创建新框架。
|
||||
|
||||
## 依赖方向
|
||||
|
||||
- 领域逻辑负责规则、状态与数据,尽量保持可在 headless 环境运行。
|
||||
- 表现层负责场景、UI、输入、动画、音频和特效,不在回调中复制领域规则。
|
||||
- 逻辑层不得加载 UI 场景、抓取表现节点或等待表现动画完成。
|
||||
- UI 将用户意图转为逻辑层公开命令;状态变化通过返回值、可观察状态或信号反馈。
|
||||
- 跨系统优先用明确接口或信号解耦。若项目已有事件总线,复用其契约;没有时不要强制新建全局总线。
|
||||
|
||||
```gdscript
|
||||
# 表现层只转发意图
|
||||
func _on_confirm_pressed() -> void:
|
||||
entity_service.confirm(entity_id)
|
||||
|
||||
# 逻辑层发布状态变化,不直接操作 UI
|
||||
func confirm(id: StringName) -> void:
|
||||
# 更新领域状态
|
||||
entity_confirmed.emit(id)
|
||||
```
|
||||
|
||||
## 边界约束
|
||||
|
||||
- 信号参数和公开方法是跨层契约;修改时同步调用方、测试与相关文档。
|
||||
- 避免双向依赖和跨层节点路径。依赖应显式注入或通过稳定接口获取。
|
||||
- autoload 只承载确需全局生命周期的服务或状态,不把普通功能默认做成单例。
|
||||
- 新系统先明确所有权、生命周期、可测试边界和失败处理,再决定放置位置。
|
||||
|
||||
## 工程完整性
|
||||
|
||||
- Godot 版本遵循项目声明;升级引擎或兼容特征前必须说明影响并取得确认。
|
||||
- 修改 `project.godot`、导出预设、autoload 或输入映射前,先说明运行与构建影响。
|
||||
- Godot 生成的 UID 与对应资源保持一致,不手工伪造;移动或删除资源时检查引用。
|
||||
- 外部插件和第三方资源遵守 `dependency-governance`。
|
||||
@@ -1,26 +0,0 @@
|
||||
---
|
||||
description: Godot 素材引用、导入一致性与可替换占位规范
|
||||
globs: "**/*.{gd,tscn,tres,res}"
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Godot 素材与占位
|
||||
|
||||
## 正式素材
|
||||
|
||||
- 面向用户的成品视觉应使用项目批准的正式素材;程序绘制只用于确属程序化的视觉、调试或明确的临时占位。
|
||||
- 沿用项目现有素材目录、命名、尺寸基准和导入预设,不假设固定路径或分辨率。
|
||||
- 文件命名保持稳定、可搜索;移动或重命名后检查场景、资源和脚本引用。
|
||||
- 纹理过滤、mipmap、压缩、循环和采样等导入设置按素材用途确定,同类素材保持一致。
|
||||
- 逻辑层只引用稳定的资源标识或数据,不直接依赖表现素材。
|
||||
|
||||
## 缺失素材占位
|
||||
|
||||
正式素材缺失时可以占位,但必须满足:
|
||||
|
||||
- 视觉上明显区别于成品,并显示或记录可搜索的 asset key;
|
||||
- 在代码或清单中标注 `PLACEHOLDER`,注明期望用途和替换条件;
|
||||
- 占位节点尺寸、锚点和接口与目标素材兼容,替换时不要求改业务逻辑;
|
||||
- 项目已有统一占位生成器或缺失素材清单时必须复用;没有时采用最小可删除实现,不额外建立复杂系统。
|
||||
|
||||
提交或交付前搜索未解决的 `PLACEHOLDER`,明确哪些仍被允许保留。
|
||||
@@ -1,28 +0,0 @@
|
||||
---
|
||||
description: Godot 数据驱动内容、数据访问、校验与存档兼容约定
|
||||
globs: "**/*.{gd,tres,res,csv,json}"
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Godot 数据系统
|
||||
|
||||
## 数据驱动边界
|
||||
|
||||
- 需要由策划或内容人员独立调整的参数、实体定义和效果配置,应放入项目采用的数据源,不散落为脚本字面量。
|
||||
- 先复用项目已有的 `Resource`、CSV、JSON 或其他数据管线;项目尚未采用数据驱动时,根据实际复用需求选择最小方案,不强制新增格式或仓库层。
|
||||
- 技术常量、枚举、协议版本和与内容无关的安全默认值可以留在代码中,并用名称或注释说明用途。
|
||||
- 不明确某个数值属于内容还是技术约束时,先查现有数据定义和调用方。
|
||||
|
||||
## 加载与访问
|
||||
|
||||
- 为数据定义稳定 ID、字段类型、必填项和默认值;加载边界统一做格式与引用校验。
|
||||
- 解析失败应包含数据源、记录 ID 和字段名;可恢复问题使用安全默认值并报告,不可恢复问题尽早失败。
|
||||
- 若项目已有 Store、Repository 或缓存层,公开查询入口统一经过该层,并提供测试可用的清理或重载能力。
|
||||
- 调用方不应重复解析同一数据源,也不应依赖数据文件中的偶然顺序。
|
||||
- 新增可配置行为时优先扩展既有注册或组合机制,避免在多个调用点堆叠同类条件分支。
|
||||
|
||||
## 存档与兼容
|
||||
|
||||
- 持久化数据携带明确版本;读取时对缺失字段提供默认值,并为不兼容结构提供显式转换。
|
||||
- 只保存恢复状态所需的数据,不序列化场景节点引用或临时缓存。
|
||||
- 数据结构变化时同时更新加载、保存、校验和回归测试。
|
||||
@@ -1,35 +0,0 @@
|
||||
---
|
||||
description: 通用 GDScript 文件结构、命名、类型、注释与错误处理规范
|
||||
globs: "**/*.gd"
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# GDScript 风格
|
||||
|
||||
## 文件结构
|
||||
|
||||
按 Godot 风格保持稳定顺序:`@tool`(如需)→ `class_name`(如需)→ `extends` → 文档注释 → signals → enums → constants → exports → public members → private members → lifecycle → public methods → private methods。
|
||||
|
||||
- 可复用类型使用 `class_name`;仅由 autoload 注册的脚本避免重复声明同名全局类。
|
||||
- 缩进使用 Tab,单个文件内不得混用 Tab 与空格。
|
||||
- 一个脚本聚焦一个主要职责;脚本持续膨胀时按状态、数据访问或表现职责拆分。
|
||||
|
||||
## 命名
|
||||
|
||||
- 文件、变量、函数、参数和信号使用 `snake_case`。
|
||||
- 类名使用 `PascalCase`,常量使用 `UPPER_SNAKE_CASE`。
|
||||
- 私有成员和私有方法使用 `_` 前缀;参数与成员冲突时使用 `p_` 前缀。
|
||||
- 信号名称表达已经发生的事件,如 `entity_selected`,避免含糊的 `changed`。
|
||||
|
||||
## 类型与接口
|
||||
|
||||
- 函数参数和返回值显式标注类型;局部变量优先 `:=` 推断,容器尽量声明元素类型。
|
||||
- 跨系统边界避免无结构的 `Dictionary`;可复用数据优先使用具名类型、Resource 或明确 schema。
|
||||
- 可空值、失败返回和副作用必须从签名、名称或文档中可见。
|
||||
- 只对已理解且范围最小的问题使用 `@warning_ignore`,不全局压制告警。
|
||||
|
||||
## 注释与诊断
|
||||
|
||||
- `##` 用于公开类型、属性和方法的文档;普通注释解释原因与约束,不复述代码。
|
||||
- 日志和警告包含稳定的模块或类标签以及关键上下文。
|
||||
- 可恢复的外部数据问题用明确错误信息处理;真正的内部不变量可用 `assert`,不要用断言处理正常用户输入。
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
description: Godot 场景节点组织、依赖、生命周期与用户文本约定
|
||||
globs: "**/*.tscn"
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Godot 场景与节点
|
||||
|
||||
## 场景组织
|
||||
|
||||
- 场景保持单一职责;可复用子结构拆成独立场景,并尽量能单独实例化验证。
|
||||
- 场景拥有专用脚本时采用可对应的命名,例如 `entity_view.tscn` 与 `entity_view.gd`;不要求无脚本场景创建空脚本。
|
||||
- 节点名称表达角色而非临时布局位置;不要依赖自动生成或易变化的名称作为跨场景契约。
|
||||
- 重复子场景使用稳定的 `PackedScene` 引用;避免在运行热点反复同步加载资源。
|
||||
|
||||
## 节点依赖
|
||||
|
||||
- 场景内部的稳定子节点可用唯一节点名或局部路径引用。
|
||||
- 外部依赖通过 `@export`、初始化方法或父级组装显式注入。
|
||||
- 禁止硬编码场景树根路径或多级上溯路径来获取其他系统节点。
|
||||
- 子节点向上报告事件使用信号;父节点向下调用明确方法。若项目已有总线,只用于真正跨系统的事件。
|
||||
|
||||
## 生命周期
|
||||
|
||||
- Node 释放使用 `queue_free()`;访问可能已释放的对象前检查有效性。
|
||||
- 连接到长生命周期发射者的回调应在退出树时断开,或使用可随接收者失效的安全连接方式。
|
||||
- `_process` 与 `_physics_process` 只做每帧必需工作;可事件驱动的更新不要轮询。
|
||||
- 高频实例化是否使用对象池由性能测量决定,不预先为普通节点增加池化复杂度。
|
||||
|
||||
## 用户文本
|
||||
|
||||
用户可见文本集中在表现层,并接入项目已有本地化方案;不要在深层逻辑中硬编码最终文案。
|
||||
@@ -1,29 +0,0 @@
|
||||
---
|
||||
description: Godot 测试脚本的 headless、隔离、确定性与退出码规范
|
||||
globs: "**/*test*.gd"
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Godot 测试
|
||||
|
||||
## 运行原则
|
||||
|
||||
- 领域逻辑应能在无窗口、无 UI 和无渲染依赖的环境中验证。
|
||||
- 运行前按项目声明确定 Godot 版本、可执行文件和测试入口;不假设固定目录、场景名或脚本命名。
|
||||
- 项目已有测试框架或统一入口时必须复用。没有时采用最小可执行入口;引入第三方框架前遵守依赖确认规则。
|
||||
- 自动化测试成功返回退出码 0,失败返回非零;不得仅依赖日志文本判断结果。
|
||||
- 性能与超时断言应测量被测逻辑本身,避免输出管道、编辑器启动和资源导入污染计时。
|
||||
|
||||
## 用例约束
|
||||
|
||||
- 每个用例独立设置并清理状态,不依赖执行顺序或前一个用例留下的 autoload、缓存、随机种子和文件。
|
||||
- 随机、时间和异步流程使用可控种子、可注入时钟或明确超时,避免无限等待。
|
||||
- 优先断言公开行为、信号参数和持久化结果,不绑定私有实现细节。
|
||||
- 纯逻辑用例不实例化 UI、3D 或特效场景;只有验证集成边界时才加载必要场景。
|
||||
- 失败信息包含期望值、实际值和关键实体标识,便于在 headless 日志中定位。
|
||||
|
||||
## 变更要求
|
||||
|
||||
- 修复缺陷时先补可复现用例,或说明为何无法自动化。
|
||||
- 新增逻辑系统时覆盖正常路径、边界输入、失败路径和状态重置。
|
||||
- 数据 schema、存档版本、信号契约或项目配置变化时同步更新相关回归测试。
|
||||
Reference in New Issue
Block a user