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