Twilight/CursorInitGeneral

Template

Fork 0

Files

Nostars Developer 6446261c69 cursor Init 完善多人协同changelog，以及godot相关基础skill和代码规范

2026-07-15 14:38:08 +08:00

12 KiB

Raw Blame History

Cursor Init Reference

本文件是 cursor-init 的精确数据契约。SKILL.md 负责流程，本文件负责 canonical、 cleanup、状态模板、sentinel 与 .gitignore 片段。路径均相对项目根。

1. Canonical 白名单

canonical 是初始化期间必须保留的 tracked 基线。缺失项应报错并从可信模板恢复，不得用空文件伪造。除这里列出的 8 个 Skill 目录外，.cursor/skills/ 不允许有其他一级目录。

1.1 顶层配置与生成标记

.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 个基线项）

.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 必须保留）

.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 个目录）

.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 文件：

.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 全套

.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 全套

.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 占位

.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 状态模板文件

.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，确认后删除：

# 全部历史 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 节模板：

.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`

# Deferred Decisions Registry

## Active Items

（暂无延期方案）

---

## Completed / Cancelled Items

（暂无已完成或已废弃的方案）

3.2 `.cursor/pitfalls/pitfalls.md`

# Pitfall Journal

开发过程中踩过的坑，按时间倒序排列。
Agent 进入 Debug mode 或遇到运行时错误时自动检索匹配。

---

3.3 `.cursor/distillery/problems.md`

# Problem Distillery — Problems

反复出现的顽固问题追踪记录，按时间倒序排列。

<!-- 新条目追加在此行下方 -->

3.4 `.cursor/distillery/insights.md`

# Problem Distillery — Insights

从已解决的顽固问题中蒸馏出的精炼方法论。

<!-- 新条目追加在此行下方 -->

---
last_distill_date: {{DATE}}

3.5 `.cursor/distillery/golden-rules.md`

# Golden Rules

经过实践验证（权重 >= 5）的精炼认知，每次新会话自动注入。

<!-- 当条目达到权重阈值后由 Agent 自动写入 -->

3.6 `.cursor/profile/project-profile.md`

# Project Profile

## 项目定位

## 技术栈与架构

## 设计约定

## 产品方向

3.7 `.cursor/profile/project-profile-log.md`

# Project Profile Log

详细记录每次项目画像更新的完整上下文，按时间正序追加。

## 记录

4. 空 Changelog 四视图

以 .cursor/changelog/tools/changelog_build.py 的输出为准。entries 仅有 .gitkeep 时，生成结果应具备以下固定头部且无条目：

4.1 `changelog-headlines.md`

# Dev Changelog — Headlines

最近 ~50 次改动的一句话概要，按时间倒序排列。每次会话自动注入上下文。
> 本文件由 `tools/changelog_build.py` 从 `entries/` 自动生成，请勿手改。

4.2 `changelog-recent.md`

# Dev Changelog — Recent

最近 ~20 次改动的摘要记录，按时间倒序排列。
当 Agent 检测到当前任务与近期改动相关时自动读取。
> 本文件由 `tools/changelog_build.py` 从 `entries/` 自动生成，请勿手改。

4.3 `changelog-full.md`

# Dev Changelog — Full

完整的开发改动记录，按时间倒序排列。作为主动 RAG 的数据源，用户手动唤醒时读取。
> 本文件由 `tools/changelog_build.py` 从 `entries/` 自动生成，请勿手改；新增/修改请编辑 `entries/<author>/<id>.md` 后重跑生成器。

## 记录

4.4 `changelog-by-author.md`

# Dev Changelog — By Author

按作者聚合的贡献概览，便于多人协作时区分提交来源。
> 本文件由 `tools/changelog_build.py` 自动生成，请勿手改。

生成器统一以单个 LF 结尾，不保留多余空白行；验证应比较生成器实际输出，不自行 trim 后回写。

5. `local-env.json` 生成契约

必须读取 .cursor/local-env.example.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` 模板

仅在全部验证通过后写入：

# .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` 片段

拼装顺序：

Cursor runtime
Godot
OS / IDE / Language（如用户需要）
Custom

追加到已有文件时，用以下分隔：

# --- 以下由 cursor-init 追加 ---

7.1 Cursor runtime（固定）

# === 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（固定）

# === Godot ===
# 编辑器导入缓存可重建，不提交
.godot/

# Godot 4 UID sidecar 与资源导入配置是项目元数据，必须提交
!*.uid
!**/*.uid
!*.import
!**/*.import

写入前检查并移除或修正已有的冲突规则，例如 *.uid、*.import、**/*.uid、 **/*.import。不要把 .godot/ 内的生成缓存误认为资源旁的 *.import sidecar。

7.3 Windows

# === OS: Windows ===
Thumbs.db
Thumbs.db:encryptable
ehthumbs.db
ehthumbs_vista.db
Desktop.ini
$RECYCLE.BIN/
*.stackdump
*.lnk

7.4 macOS

# === OS: macOS ===
.DS_Store
.AppleDouble
.LSOverride
Icon
._*
.DocumentRevisions-V100
.fseventsd
.Spotlight-V100
.TemporaryItems
.Trashes
.VolumeIcon.icns
.com.apple.timemachine.donotpresent

7.5 Linux

# === OS: Linux ===
*~
.fuse_hidden*
.directory
.Trash-*
.nfs*

7.6 VS Code

# === IDE: VS Code ===
.vscode/*
!.vscode/settings.json
!.vscode/tasks.json
!.vscode/launch.json
!.vscode/extensions.json
!.vscode/*.code-snippets
.history/
*.vsix

7.7 JetBrains

# === IDE: JetBrains ===
.idea/
*.iml
*.ipr
*.iws
.idea_modules/

7.8 Visual Studio

# === IDE: Visual Studio ===
.vs/
*.user
*.suo
*.userprefs
bin/
obj/
[Dd]ebug/
[Rr]elease/
x64/
x86/

7.9 Vim / Emacs

# === IDE: Vim / Emacs ===
*.swp
*.swo
*.swn
Session.vim
.netrwhist
*~
\#*\#
.\#*

7.10 Custom

# === Custom ===
# 在此追加项目专属忽略项

8. Dry-run 输出格式

## 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 后扫描结果变化时应重新生成清单并再次确认。

12 KiB Raw Blame History Unescape Escape