553 lines
12 KiB
Markdown
553 lines
12 KiB
Markdown
# Cursor Init Reference
|
||
|
||
本文件是 `cursor-init` 的精确数据契约。`SKILL.md` 负责流程，本文件负责 canonical、
|
||
cleanup、状态模板、sentinel 与 `.gitignore` 片段。路径均相对项目根。
|
||
|
||
## 1. Canonical 白名单
|
||
|
||
canonical 是初始化期间必须保留的 tracked 基线。缺失项应报错并从可信模板恢复，
|
||
不得用空文件伪造。除这里列出的 8 个 Skill 目录外，`.cursor/skills/` 不允许有其他
|
||
一级目录。
|
||
|
||
### 1.1 顶层配置与生成标记
|
||
|
||
```text
|
||
.cursor/hooks.json
|
||
.cursor/local-env.example.json
|
||
.cursor/.init-done
|
||
```
|
||
|
||
说明：
|
||
|
||
- `.cursor/.init-done` 是阶段 7 生成后需要提交的文件；模板源在首次 init 前可以没有。
|
||
- `.cursor/local-env.json` 是由 example 生成的 gitignored 运行态，不是 canonical。
|
||
- `.cursor/changelog/.changelog-ack` 是 gitignored hook 运行态，不是 canonical。
|
||
- `.cursor/changelog/.session-start` 是 sessionStart hook 刷新的 gitignored 运行态，不是 canonical。
|
||
|
||
### 1.2 Common Rules（恰好 9 个基线项）
|
||
|
||
```text
|
||
.cursor/rules/common/baserule.mdc
|
||
.cursor/rules/common/changelog-recall.mdc
|
||
.cursor/rules/common/cursor-init-recall.mdc
|
||
.cursor/rules/common/deferred-recall.mdc
|
||
.cursor/rules/common/distillery-recall.mdc
|
||
.cursor/rules/common/epee-orchestrator.mdc
|
||
.cursor/rules/common/pitfall-recall.mdc
|
||
.cursor/rules/common/profile-recall.mdc
|
||
.cursor/rules/common/dependency-governance.mdc
|
||
```
|
||
|
||
### 1.3 Godot baseline Project Rules（首次 init 必须保留）
|
||
|
||
```text
|
||
.cursor/rules/project/godot-architecture.mdc
|
||
.cursor/rules/project/godot-assets.mdc
|
||
.cursor/rules/project/godot-data-systems.mdc
|
||
.cursor/rules/project/godot-gdscript-style.mdc
|
||
.cursor/rules/project/godot-scene-conventions.mdc
|
||
.cursor/rules/project/godot-testing.mdc
|
||
```
|
||
|
||
禁止用 `.cursor/rules/project/*.mdc` 之类的通配删除覆盖这些文件。
|
||
|
||
### 1.4 Skills（最终恰好 8 个目录）
|
||
|
||
```text
|
||
.cursor/skills/cursor-init/
|
||
.cursor/skills/deferred-decisions/
|
||
.cursor/skills/dev-changelog/
|
||
.cursor/skills/epee-orchestrator/
|
||
.cursor/skills/pitfall-journal/
|
||
.cursor/skills/problem-distillery/
|
||
.cursor/skills/profile-memory/
|
||
.cursor/skills/html-doc/
|
||
```
|
||
|
||
目录内 canonical 文件：
|
||
|
||
```text
|
||
.cursor/skills/cursor-init/SKILL.md
|
||
.cursor/skills/cursor-init/reference.md
|
||
.cursor/skills/deferred-decisions/SKILL.md
|
||
.cursor/skills/dev-changelog/SKILL.md
|
||
.cursor/skills/epee-orchestrator/SKILL.md
|
||
.cursor/skills/epee-orchestrator/registry.md
|
||
.cursor/skills/pitfall-journal/SKILL.md
|
||
.cursor/skills/problem-distillery/SKILL.md
|
||
.cursor/skills/profile-memory/SKILL.md
|
||
.cursor/skills/html-doc/SKILL.md
|
||
.cursor/skills/html-doc/assets/theme.css
|
||
.cursor/skills/html-doc/assets/annotate.js
|
||
.cursor/skills/html-doc/templates/skeleton.html
|
||
```
|
||
|
||
### 1.5 Hooks 全套
|
||
|
||
```text
|
||
.cursor/hooks.json
|
||
.cursor/hooks/README.md
|
||
.cursor/hooks/run-hook.ps1
|
||
.cursor/hooks/session-init.ps1
|
||
.cursor/hooks/session-init.sh
|
||
.cursor/hooks/check-changelog.ps1
|
||
.cursor/hooks/check-changelog.sh
|
||
```
|
||
|
||
### 1.6 Changelog tools 全套
|
||
|
||
```text
|
||
.cursor/changelog/tools/changelog_build.py
|
||
.cursor/changelog/tools/migrate_changelog.py
|
||
.cursor/changelog/tools/install-git-hooks.ps1
|
||
.cursor/changelog/tools/install-git-hooks.sh
|
||
.cursor/changelog/tools/merge-import.ps1
|
||
.cursor/changelog/tools/merge-import.sh
|
||
.cursor/changelog/tools/git-hooks/pre-commit
|
||
.cursor/changelog/tools/git-hooks/post-merge
|
||
```
|
||
|
||
`tools/__pycache__/` 和 `*.pyc` 永远不是 canonical。
|
||
|
||
### 1.7 Changelog 四视图与 entries 占位
|
||
|
||
```text
|
||
.cursor/changelog/changelog-full.md
|
||
.cursor/changelog/changelog-recent.md
|
||
.cursor/changelog/changelog-headlines.md
|
||
.cursor/changelog/changelog-by-author.md
|
||
.cursor/changelog/entries/.gitkeep
|
||
```
|
||
|
||
四视图由 `changelog_build.py` 生成，不手改。初始化时先清空 entries（保留
|
||
`.gitkeep`），再运行生成器得到空视图。
|
||
|
||
### 1.8 状态模板文件
|
||
|
||
```text
|
||
.cursor/deferred/registry.md
|
||
.cursor/pitfalls/pitfalls.md
|
||
.cursor/distillery/problems.md
|
||
.cursor/distillery/insights.md
|
||
.cursor/distillery/golden-rules.md
|
||
.cursor/profile/project-profile.md
|
||
.cursor/profile/project-profile-log.md
|
||
```
|
||
|
||
## 2. Cleanup 清单
|
||
|
||
### 2.1 强制删除
|
||
|
||
下面内容必须进入 dry-run，确认后删除：
|
||
|
||
```text
|
||
# 全部历史 changelog fragment；唯一例外是 entries/.gitkeep
|
||
.cursor/changelog/entries/**
|
||
!.cursor/changelog/entries/.gitkeep
|
||
|
||
# 历史备份
|
||
.cursor/changelog/_backup/**
|
||
.cursor/_init-backup/**
|
||
.cursor/**/_backup/**
|
||
.cursor/**/*.bak
|
||
.cursor/**/*.backup
|
||
|
||
# 缓存和编译产物
|
||
.cursor/**/__pycache__/**
|
||
.cursor/**/*.pyc
|
||
.cursor/**/*.pyo
|
||
.cursor/**/*.cache
|
||
.cursor/**/.cache/**
|
||
|
||
# 设备绑定与 hook 运行态
|
||
.cursor/local-env.json
|
||
.cursor/changelog/.changelog-ack
|
||
.cursor/changelog/.session-start
|
||
|
||
# init / 调试临时产物
|
||
.cursor/_gitignore-preview
|
||
.cursor/**/*.tmp
|
||
.cursor/**/*.temp
|
||
.cursor/**/*.log
|
||
.cursor/debug-*.log
|
||
```
|
||
|
||
模式中的 `!` 只是“例外”说明，不表示可把这段直接交给任意删除命令。实现时必须先枚举
|
||
实际文件并逐项比对白名单，防止通配误删。
|
||
|
||
此外：
|
||
|
||
- 删除 `.cursor/skills/` 下所有非 8 项白名单目录。
|
||
- 删除或迁出非 baseline project rules，但必须逐项确认；六个 baseline 永不删除。
|
||
- 删除任何非 8 项白名单 Skill。
|
||
- 不删除 `source/`，不修改项目根 Git 文件（`.gitignore` 仅在用户明确选择时例外）。
|
||
|
||
### 2.2 重置而非删除
|
||
|
||
以下文件保留路径并重置为第 3 节模板：
|
||
|
||
```text
|
||
.cursor/deferred/registry.md
|
||
.cursor/pitfalls/pitfalls.md
|
||
.cursor/distillery/problems.md
|
||
.cursor/distillery/insights.md
|
||
.cursor/distillery/golden-rules.md
|
||
.cursor/profile/project-profile.md
|
||
.cursor/profile/project-profile-log.md
|
||
```
|
||
|
||
四个 changelog 视图不使用手写模板覆盖：删除 fragments 后运行生成器重建。
|
||
|
||
### 2.3 环境配置入口
|
||
|
||
本机环境只由 `cursor-init` 阶段 1 和阶段 4 一次性采集、生成，不依赖额外环境检查 Rule。
|
||
|
||
## 3. 状态模板
|
||
|
||
写入时替换 `{{DATE}}` 为本地日期 `YYYY-MM-DD`。
|
||
|
||
### 3.1 `.cursor/deferred/registry.md`
|
||
|
||
```markdown
|
||
# Deferred Decisions Registry
|
||
|
||
## Active Items
|
||
|
||
（暂无延期方案）
|
||
|
||
---
|
||
|
||
## Completed / Cancelled Items
|
||
|
||
（暂无已完成或已废弃的方案）
|
||
```
|
||
|
||
### 3.2 `.cursor/pitfalls/pitfalls.md`
|
||
|
||
```markdown
|
||
# Pitfall Journal
|
||
|
||
开发过程中踩过的坑，按时间倒序排列。
|
||
Agent 进入 Debug mode 或遇到运行时错误时自动检索匹配。
|
||
|
||
---
|
||
```
|
||
|
||
### 3.3 `.cursor/distillery/problems.md`
|
||
|
||
```markdown
|
||
# Problem Distillery — Problems
|
||
|
||
反复出现的顽固问题追踪记录，按时间倒序排列。
|
||
|
||
<!-- 新条目追加在此行下方 -->
|
||
```
|
||
|
||
### 3.4 `.cursor/distillery/insights.md`
|
||
|
||
```markdown
|
||
# Problem Distillery — Insights
|
||
|
||
从已解决的顽固问题中蒸馏出的精炼方法论。
|
||
|
||
<!-- 新条目追加在此行下方 -->
|
||
|
||
---
|
||
last_distill_date: {{DATE}}
|
||
```
|
||
|
||
### 3.5 `.cursor/distillery/golden-rules.md`
|
||
|
||
```markdown
|
||
# Golden Rules
|
||
|
||
经过实践验证（权重 >= 5）的精炼认知，每次新会话自动注入。
|
||
|
||
<!-- 当条目达到权重阈值后由 Agent 自动写入 -->
|
||
```
|
||
|
||
### 3.6 `.cursor/profile/project-profile.md`
|
||
|
||
```markdown
|
||
# Project Profile
|
||
|
||
## 项目定位
|
||
|
||
## 技术栈与架构
|
||
|
||
## 设计约定
|
||
|
||
## 产品方向
|
||
```
|
||
|
||
### 3.7 `.cursor/profile/project-profile-log.md`
|
||
|
||
```markdown
|
||
# Project Profile Log
|
||
|
||
详细记录每次项目画像更新的完整上下文，按时间正序追加。
|
||
|
||
## 记录
|
||
```
|
||
|
||
## 4. 空 Changelog 四视图
|
||
|
||
以 `.cursor/changelog/tools/changelog_build.py` 的输出为准。entries 仅有 `.gitkeep` 时，
|
||
生成结果应具备以下固定头部且无条目：
|
||
|
||
### 4.1 `changelog-headlines.md`
|
||
|
||
```markdown
|
||
# Dev Changelog — Headlines
|
||
|
||
最近 ~50 次改动的一句话概要，按时间倒序排列。每次会话自动注入上下文。
|
||
> 本文件由 `tools/changelog_build.py` 从 `entries/` 自动生成，请勿手改。
|
||
```
|
||
|
||
### 4.2 `changelog-recent.md`
|
||
|
||
```markdown
|
||
# Dev Changelog — Recent
|
||
|
||
最近 ~20 次改动的摘要记录，按时间倒序排列。
|
||
当 Agent 检测到当前任务与近期改动相关时自动读取。
|
||
> 本文件由 `tools/changelog_build.py` 从 `entries/` 自动生成，请勿手改。
|
||
```
|
||
|
||
### 4.3 `changelog-full.md`
|
||
|
||
```markdown
|
||
# Dev Changelog — Full
|
||
|
||
完整的开发改动记录，按时间倒序排列。作为主动 RAG 的数据源，用户手动唤醒时读取。
|
||
> 本文件由 `tools/changelog_build.py` 从 `entries/` 自动生成，请勿手改；新增/修改请编辑 `entries/<author>/<id>.md` 后重跑生成器。
|
||
|
||
## 记录
|
||
```
|
||
|
||
### 4.4 `changelog-by-author.md`
|
||
|
||
```markdown
|
||
# Dev Changelog — By Author
|
||
|
||
按作者聚合的贡献概览，便于多人协作时区分提交来源。
|
||
> 本文件由 `tools/changelog_build.py` 自动生成，请勿手改。
|
||
```
|
||
|
||
生成器统一以单个 LF 结尾，不保留多余空白行；验证应比较生成器实际输出，不自行 trim 后回写。
|
||
|
||
## 5. `local-env.json` 生成契约
|
||
|
||
必须读取 `.cursor/local-env.example.json`，复制完整 JSON 结构，再覆盖三个键：
|
||
|
||
```json
|
||
{
|
||
"shell": "{{SHELL}}",
|
||
"changelog-author": "{{CHANGELOG_AUTHOR}}",
|
||
"godot4_path": "{{GODOT4_EXECUTABLE_OR_EMPTY}}"
|
||
}
|
||
```
|
||
|
||
规则：
|
||
|
||
- example 中其他键原样保留，不以这段最小示例覆盖整个文件。
|
||
- `godot4_path` 可为空字符串。
|
||
- 不写用户未确认的自动猜测值。
|
||
- 文件必须能被 JSON parser 读取，并由 `.gitignore` 忽略。
|
||
- 不提交 `local-env.json`。
|
||
|
||
## 6. `.init-done` 模板
|
||
|
||
仅在全部验证通过后写入：
|
||
|
||
```yaml
|
||
# .cursor/.init-done — cursor-init 写入的初始化标记
|
||
# 必须提交此文件，避免 clone 后重复触发初始化
|
||
initialized_at: {{ISO_DATETIME}}
|
||
initialized_by: cursor-init
|
||
skill_version: 3
|
||
project_type: godot
|
||
gitignore_generated: {{BOOL}}
|
||
```
|
||
|
||
`{{BOOL}}` 只能是 `true` 或 `false`。流程失败、取消或存在未解决项时不得写入。
|
||
|
||
## 7. `.gitignore` 片段
|
||
|
||
拼装顺序：
|
||
|
||
1. Cursor runtime
|
||
2. Godot
|
||
3. OS / IDE / Language（如用户需要）
|
||
4. Custom
|
||
|
||
追加到已有文件时，用以下分隔：
|
||
|
||
```gitignore
|
||
# --- 以下由 cursor-init 追加 ---
|
||
```
|
||
|
||
### 7.1 Cursor runtime（固定）
|
||
|
||
```gitignore
|
||
# === Cursor runtime ===
|
||
.cursor/local-env.json
|
||
.cursor/changelog/.changelog-ack
|
||
.cursor/changelog/.session-start
|
||
.cursor/_init-backup/
|
||
.cursor/_gitignore-preview
|
||
|
||
# .cursor/.init-done 是需提交的完成标记，不得忽略
|
||
```
|
||
|
||
### 7.2 Godot（固定）
|
||
|
||
```gitignore
|
||
# === Godot ===
|
||
# 编辑器导入缓存可重建，不提交
|
||
.godot/
|
||
|
||
# Godot 4 UID sidecar 与资源导入配置是项目元数据，必须提交
|
||
!*.uid
|
||
!**/*.uid
|
||
!*.import
|
||
!**/*.import
|
||
```
|
||
|
||
写入前检查并移除或修正已有的冲突规则，例如 `*.uid`、`*.import`、`**/*.uid`、
|
||
`**/*.import`。不要把 `.godot/` 内的生成缓存误认为资源旁的 `*.import` sidecar。
|
||
|
||
### 7.3 Windows
|
||
|
||
```gitignore
|
||
# === OS: Windows ===
|
||
Thumbs.db
|
||
Thumbs.db:encryptable
|
||
ehthumbs.db
|
||
ehthumbs_vista.db
|
||
Desktop.ini
|
||
$RECYCLE.BIN/
|
||
*.stackdump
|
||
*.lnk
|
||
```
|
||
|
||
### 7.4 macOS
|
||
|
||
```gitignore
|
||
# === OS: macOS ===
|
||
.DS_Store
|
||
.AppleDouble
|
||
.LSOverride
|
||
Icon
|
||
._*
|
||
.DocumentRevisions-V100
|
||
.fseventsd
|
||
.Spotlight-V100
|
||
.TemporaryItems
|
||
.Trashes
|
||
.VolumeIcon.icns
|
||
.com.apple.timemachine.donotpresent
|
||
```
|
||
|
||
### 7.5 Linux
|
||
|
||
```gitignore
|
||
# === OS: Linux ===
|
||
*~
|
||
.fuse_hidden*
|
||
.directory
|
||
.Trash-*
|
||
.nfs*
|
||
```
|
||
|
||
### 7.6 VS Code
|
||
|
||
```gitignore
|
||
# === IDE: VS Code ===
|
||
.vscode/*
|
||
!.vscode/settings.json
|
||
!.vscode/tasks.json
|
||
!.vscode/launch.json
|
||
!.vscode/extensions.json
|
||
!.vscode/*.code-snippets
|
||
.history/
|
||
*.vsix
|
||
```
|
||
|
||
### 7.7 JetBrains
|
||
|
||
```gitignore
|
||
# === IDE: JetBrains ===
|
||
.idea/
|
||
*.iml
|
||
*.ipr
|
||
*.iws
|
||
.idea_modules/
|
||
```
|
||
|
||
### 7.8 Visual Studio
|
||
|
||
```gitignore
|
||
# === IDE: Visual Studio ===
|
||
.vs/
|
||
*.user
|
||
*.suo
|
||
*.userprefs
|
||
bin/
|
||
obj/
|
||
[Dd]ebug/
|
||
[Rr]elease/
|
||
x64/
|
||
x86/
|
||
```
|
||
|
||
### 7.9 Vim / Emacs
|
||
|
||
```gitignore
|
||
# === IDE: Vim / Emacs ===
|
||
*.swp
|
||
*.swo
|
||
*.swn
|
||
Session.vim
|
||
.netrwhist
|
||
*~
|
||
\#*\#
|
||
.\#*
|
||
```
|
||
|
||
### 7.10 Custom
|
||
|
||
```gitignore
|
||
# === Custom ===
|
||
# 在此追加项目专属忽略项
|
||
```
|
||
|
||
## 8. Dry-run 输出格式
|
||
|
||
```markdown
|
||
## cursor-init dry-run
|
||
|
||
### 保留
|
||
- path — canonical
|
||
|
||
### 缺失（阻塞）
|
||
- path — 需要从可信模板恢复
|
||
|
||
### 删除
|
||
- path — cleanup 原因
|
||
|
||
### 重置
|
||
- path — 使用的模板
|
||
|
||
### 迁移 / 冲突
|
||
- from → to — 原因与是否需要用户选择
|
||
|
||
### 生成
|
||
- .cursor/local-env.json — 输入字段摘要（不要泄露不必要的本机信息）
|
||
- .cursor/skills/epee-orchestrator/registry.md — 8 项
|
||
- .gitignore — 新建 / 追加 / 替换 / 跳过
|
||
- .cursor/.init-done — 仅验证成功后
|
||
```
|
||
|
||
确认必须覆盖整份 dry-run。dry-run 后扫描结果变化时应重新生成清单并再次确认。
|