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

.cursor/skills/cursor-init/SKILL.md

@@ -1,830 +1,199 @@
 ---
 name: cursor-init
 description: >-
-  初始化新项目的 .cursor 结构。两种触发方式：
-  （1）首次自动触发 —— 当 `.cursor/.init-done` sentinel 不存在时，`cursor-init-recall.mdc`
-  会在会话首次响应前引导 Agent 主动执行本 Skill；
-  （2）关键词手动触发 —— "初始化cursor"、"cursor init"、"重置 cursor"、"补 gitignore" 等。
-  流程：识别并迁移目标项目原有的 rules/skills，清理模板残留的项目专用数据
-  （changelog/deferred/pitfalls/profile/distillery/local-env/项目级 rules 与 skills），
-  可选生成 .gitignore 模板，最后写入 `.cursor/.init-done` 标记完成。
-  已 init 仓库不会再自动触发，除非用户主动通过关键词请求。
+  初始化或重置项目的 .cursor 基础设施：保留 canonical Rules、Skills、Hooks 与
+  Godot baseline，清除模板历史数据，采集本机环境，生成 .gitignore，并在验证成功后
+  写入 .init-done。首次缺少 sentinel 时自动使用；也用于“初始化 cursor”、
+  “重置 cursor”、“补 gitignore”等请求。
 ---
 
-# Cursor Init Skill
+# Cursor Init
 
-把从其它项目复制过来（或通过 git clone 模板仓库获得）的 `.cursor/` 目录重置为当前新项目的干净起点。
+把模板仓库或复制来的 `.cursor/` 变成可安全使用、可重复执行的 Godot 项目基线。
 
-## 使用场景
+详细白名单、清理模式、状态模板、sentinel 和 `.gitignore` 片段统一见
+[reference.md](reference.md)。执行全流程或仅补 `.gitignore` 前都必须直接读取该文件，
+不得凭记忆重建清单。
 
-### 场景 A：克隆模板仓库后的首次会话
-
-```
-1. 用户把本模板作为 git 仓库发布
-2. 其他人 `git clone <模板仓库>` 得到新项目骨架
-3. 用户打开 Cursor，在该仓库发出任意第一条消息
-4. `cursor-init-recall.mdc`（alwaysApply）检测 .cursor/.init-done 不存在
-   → 引导 Agent 暂停用户原始请求，先执行本 Skill
-5. Agent 按阶段 0 → 7 跑完，写入 .init-done
-6. 后续会话 sentinel 已存在，不再自动触发
-```
+## 入口
 
-### 场景 B：从已有项目直接复制 .cursor 目录
+### 首次自动初始化
 
-```
-1. 用户在 "源项目 A" 中使用本 .cursor 模板开发
-2. 用户开 "新项目 B"，把 A 的 .cursor/ 整体拷贝到 B
-3. B 原先可能也有自己零散的 rules/SKILL 文件（未必标准）
-4. 用户在 B 中说"初始化cursor"（或首次会话被 recall 触发）
-5. 本 Skill 把 B 原有的 rules/skills 按 baserule 归位，清空 A 遗留的项目数据，
-   重建 registry，生成 .gitignore，写入 sentinel
-```
+每次会话首次响应前由 `.cursor/rules/common/cursor-init-recall.mdc` 检查
+`.cursor/.init-done`。若 sentinel 不存在：
 
-### 场景 C：只补 .gitignore
+1. 暂存用户原请求，说明需要先初始化。
+2. 获得用户同意后执行本 Skill 的阶段 0–7。
+3. 仅在阶段 6 全部通过后写 sentinel。
+4. 初始化成功后继续原请求。
 
-```
-init 后用户说"补一下 gitignore"或"生成 gitignore" → 只跑阶段 5.5
-```
-
-## 触发条件
-
-本 Skill 由 `cursor-init-recall.mdc` 触发，两类入口：
+若用户暂时拒绝，尊重选择；不要写 sentinel，下次会话仍会提醒。
 
-### A. 全流程（阶段 0 → 7）
-
-- `.cursor/.init-done` 不存在 → 会话首次响应前由 recall 规则自动引导
-- 用户关键词：`初始化cursor` / `cursor init` / `重置 cursor` / `reset cursor` 等
-- 口头描述"把复制过来的 .cursor 清理一下"、"按 baserule 归位一下"
+### 手动全流程
 
-### B. 仅补 .gitignore（只跑阶段 5.5）
+触发词包括：`初始化 cursor`、`cursor init`、`重置 cursor`、`reset cursor`、
+“清理复制来的 .cursor”、“按基线归位”。
 
-- 用户关键词：`补 gitignore` / `生成 gitignore` / `gitignore 模板`
-- 跳过阶段 1-5 和阶段 7 的除"更新 gitignore_generated 字段"外的其他操作
+sentinel 已存在时必须先展示其元数据并再次确认；不得把手动触发当作无提示重置。
 
-## 执行原则（不可协商）
-
-1. **稳定准确 > token 成本**：每一步可以多读、多确认、让用户点头，不要图快
-2. **破坏性操作必须 dry-run**：删除、重置必须先列清单给用户确认
-3. **不可逆操作前提醒 git**：开始前先提示用户确认工作区已 commit/stash
-4. **模糊就问**：分类不清的文件一律问用户，不要猜
-5. **幂等**：反复运行应当无害（第二次在已干净状态下不会做破坏）
-6. **中断可恢复**：任何阶段异常 abort **不写入** `.init-done`，下次会话仍会被 recall 触发从头继续
+### 仅补 `.gitignore`
 
-## 核心流程
+触发词包括：`补 gitignore`、`生成 .gitignore`、`gitignore 模板`。
+只执行阶段 5；不得改动 `.cursor/` 的其他内容。若 sentinel 存在，只更新
+`gitignore_generated`；若不存在，询问是否改跑完整初始化，不得只为补
+`.gitignore` 创建 sentinel。
 
-### 阶段 0：前置确认 + 幂等判断
+## 不可协商的安全契约
 
-```
-1. 检查当前工作目录下存在 .cursor/
-   - 不存在 → 直接结束，提示用户先复制模板
-2. 读取 .cursor/.init-done
-   - 不存在 → 继续，按"首次 init"路径执行
-   - 已存在 → 展示其元数据（initialized_at、project_type 等），提示：
-     "检测到本仓库已于 {initialized_at} 完成初始化（project_type: {type}）。
-      继续执行会清空 deferred / pitfalls / distillery 等数据文件。确认要继续吗？"
-     等用户明确回复"继续"再往下
-3. 运行 `git status`：
-   - 不是 git 仓库 → 警告但不阻塞，建议手动备份
-   - 有未提交改动 → 提醒"建议先 commit 或 stash，便于回滚"，等用户明确回复"继续"
-4. 向用户声明本次操作范围（见"分组规则"），请求口头确认启动
-```
+1. **先 dry-run，后确认，才写入**：删除、重置、移动、覆盖、追加都进入同一份预览清单。
+2. **canonical 永不删除**：尤其不得清空 `.cursor/rules/project/`；六个 Godot baseline
+   project rules 必须保留。
+3. **精确白名单**：`.cursor/skills/` 最终只能有 reference 中列出的 8 个目录。
+4. **不触碰来源树**：只处理目标项目；不得删除或修改 `source/`。
+5. **幂等**：同一输入重复执行，第二次应只产生空或等价 dry-run。
+6. **失败不写 sentinel**：取消、异常、验证失败或未决冲突都不得创建/更新
+   `.cursor/.init-done`。
+7. **运行态不冒充 canonical**：`.cursor/local-env.json`、`.cursor/changelog/.changelog-ack`
+   与 `.cursor/changelog/.session-start` 都是 gitignored 本机文件，不是 tracked 白名单项。
+8. **文本规范**：新写文本使用 UTF-8 无 BOM、LF。
 
-### 阶段 1：递归扫描 `.cursor/`
+## 阶段 0：前置检查
 
-```
-1. 用 shell 列出 .cursor 下所有文件（含子目录）
-2. 把每个文件对照"规范清单"和"清理清单"分成三组：
-   - A 组（canonical）：在规范清单中，原样保留
-   - B 组（template-data）：在清理清单中，需要删除或重置
-   - C 组（foreign）：两张清单都没覆盖到的，视作目标项目原有文件或未知项
-3. 把分组结果用表格汇报给用户：
-   | 组 | 路径 | 处理动作 |
-```
+1. 确认项目根存在 `.cursor/`；不存在则停止并说明缺失。
+2. 读取 `.cursor/.init-done`：
+   - 不存在：进入首次初始化。
+   - 存在：展示 `initialized_at`、`project_type`、`skill_version`，等待用户明确继续。
+3. 执行 `git status`。有未提交改动时建议先 commit/stash，并等待明确继续；非 Git
+   仓库则建议备份，但可继续。
+4. 读取 [reference.md](reference.md)，声明本轮会保留、删除、重置、生成的范围。
+5. 未获得明确确认前不得进入写入阶段。
 
-### 阶段 2：处理 C 组（目标项目原有文件归位）
+## 阶段 1：一次性采集本机配置
 
-对 C 组中的每个文件，按 baserule.mdc 的归属约定分类，逐条询问用户（可一次性列清单批量确认）：
+在**一轮提问**中采集：
 
-| 文件特征 | 建议归属 | 目标路径 |
-|----------|----------|----------|
-| `.mdc` 且内容是跨项目通用规则 | 通用 Rule | `.cursor/rules/common/<name>.mdc` |
-| `.mdc` 且内容是当前新项目专属规则 | 项目 Rule | `.cursor/rules/project/<name>.mdc` |
-| 包含 `SKILL.md` 的目录 | Skill（无论通用/项目专属） | `.cursor/skills/<skill-name>/` |
-| 看不出归属 | 询问用户 | — |
-| 明显是临时/垃圾文件（`*.log`、`*.tmp`、缓存等） | 删除（需用户确认） | — |
+1. `changelog-author`：稳定、适合文件名的作者 handle。
+2. `shell`：`powershell`、`bash` 或 `zsh`；可把当前探测值作为默认。
+3. `godot4_path`：Godot 4 executable 的绝对路径；允许留空。
 
-执行要点：
+同一轮可附带询问 `.gitignore` 的写入方式（新建 / 追加 / 替换 / 跳过）和自定义忽略项，
+不要把三个环境字段拆成多轮追问。仅收集值，此阶段不写文件。
 
-- **先列清单一次性确认**，然后批量执行移动/删除，避免交互过于频繁
-- **重名冲突**：C 组文件若与 A 组规范文件重名，**保留 A 组版本**，把 C 组备份到 `.cursor/_init-backup/` 下让用户自行 diff，不直接覆盖
-- **Skill 归属提示**：通用 Skill 建议用户之后手动同步到 `~/.cursor/skills/`（跨项目便利副本，可选）
-- **迁移后核查**：移动完成后重新扫描，确认 C 组已清空
-
-### 阶段 3：处理 B 组（源项目项目专用数据清理/重置）
-
-按"清理清单"执行：
-
-**A. 直接删除**
-
-- `.cursor/rules/project/*.mdc`（全部）—— 源项目的项目级 rules，新项目不适用
-- `.cursor/skills/<非规范 skill 目录>/` —— 源项目的项目级 Skills（不在白名单的所有 skill 目录）
-- `.cursor/plans/` 下所有文件（目录保留，内容清空）
-- `.cursor/debug-*.log`、`.cursor/*.log` —— 调试日志
-- `.cursor/local-env.json` —— 设备绑定，需新设备重新生成（`local-env-check.mdc` 自动探测）
-
-**B. 重置为空模板**（保留文件，仅清内容）
-
-| 文件 | 模板（见"模板内容"节） |
-|------|------------------------|
-| `.cursor/changelog/changelog-full.md` | L1 模板 |
-| `.cursor/changelog/changelog-recent.md` | L2 模板 |
-| `.cursor/changelog/changelog-headlines.md` | L3 模板 |
-| `.cursor/changelog/.changelog-ack` | 空文件（touch） |
-| `.cursor/deferred/registry.md` | deferred 模板 |
-| `.cursor/pitfalls/pitfalls.md` | pitfalls 模板 |
-| `.cursor/distillery/problems.md` | problems 模板 |
-| `.cursor/distillery/insights.md` | insights 模板 |
-| `.cursor/distillery/golden-rules.md` | golden-rules 模板 |
-| `.cursor/profile/project-profile.md` | project-profile 模板 |
-| `.cursor/profile/project-profile-log.md` | project-profile-log 模板 |
-
-执行要点：
-
-- 每个重置前**先 Read 现有内容预览前 10 行**给用户，避免误删有价值数据（特别是 deferred/pitfalls 用户可能想保留）
-- 如用户对某个数据文件明确说"保留"（例如 golden-rules 想带过去），跳过该文件的重置
-
-### 阶段 4：重建 registry
-
-打开 `.cursor/skills/epee-orchestrator/registry.md`：
-
-1. 解析现有条目（每条 `### <skill-name>` 块）
-2. 删除所有 `类型: 项目级` 的条目
-3. 遍历 `.cursor/skills/` 目录，对照 registry：
-   - registry 有条目但 skill 目录不存在 → 删除条目
-   - skill 目录存在但 registry 无条目 → 读取该 skill 的 SKILL.md frontmatter，新增条目
-4. **确保 `cursor-init` 条目本身存在**（类型: 基础设施）
-5. 写回 registry.md
-
-### 阶段 5：同步 `hooks.json`（跨平台保守处理）
-
-- 读取 `.cursor/hooks.json`
-- 若 `command` 字段硬编码为 `powershell ...`，且目标新项目声明/探测到的 shell 不是 powershell（参考 `local-env-check.mdc`），**提醒用户**需要按 `hooks/README.md` 手动改为 `bash .cursor/hooks/xxx.sh`
-- 本阶段不自动改 hooks.json，避免误判
-
-### 阶段 5.5：`.gitignore` 交互式生成
-
-#### 5.5.1 前置检测
-
-```
-检测项目根 .gitignore：
-  不存在        → 进入 5.5.2 问卷
-  已存在且非空  → Read 前 30 行展示给用户，询问：
-                  [覆盖 / 追加到文件末尾 / 跳过本阶段]
-  用户选"跳过"  → 本阶段结束，.init-done 里标记 gitignore_generated: false
-```
-
-#### 5.5.2 问卷（一次性批量 AskQuestion 收集）
-
-必问 3 项 + 可选 1 项：
-
-| 编号 | 问题 | 类型 | 选项 |
-|------|------|------|------|
-| Q1 | 项目主要技术栈 | 多选 | Unity / Node.js / Python / Rust / Go / C# 非 Unity / Web 静态站点 / 其他 / **不确定（跳过语言段）** |
-| Q2 | IDE 偏好 | 多选 | Cursor（预勾）/ VSCode / JetBrains 全家桶 / Visual Studio / Vim+Emacs |
-| Q3 | 操作系统 | 多选 | Windows / macOS / Linux（按探测到的当前 OS 预勾） |
-| Q4（可选）| 其他要忽略的路径 | 自由文本 | 用户可跳过 |
-
-#### 5.5.3 片段组装
+## 阶段 2：扫描、分类与 dry-run
 
-按问卷选择拼装，片段内容见下方"模板内容 · .gitignore 片段库"。拼装顺序固定：
+递归扫描 `.cursor/`，按 reference 分为：
 
-```
-# === Cursor（固定，所有项目都包含） ===
-# === OS ===
-# === IDE ===
-# === Language / Framework ===
-# === Custom ===
-```
-
-若 Q1 选"不确定" → 跳过 Language 段，其他段正常拼装（极简版仍可用）。
-
-#### 5.5.4 预览与确认
-
-1. 把组装结果写到 `.cursor/_gitignore-preview`（临时文件）
-2. 给用户完整展示（超过 60 行则折叠中段）
-3. AskQuestion：`[写入 .gitignore / 让我调整再确认 / 放弃本阶段]`
-4. "写入"→ move 到项目根 `.gitignore`（已存在时按 5.5.1 的选择做覆盖或追加），删除预览文件
-5. "调整"→ 根据用户描述修改后重复步骤 2-3
-6. "放弃"→ 删除预览文件，`.init-done` 标记 `gitignore_generated: false`
+- **A / canonical**：精确白名单，保留；缺失项记为阻塞错误。
+- **B / cleanup**：历史 fragment、备份、缓存、设备配置、ack、临时文件和状态数据。
+- **C / foreign**：不属于 A/B 的文件。
 
-### 阶段 6：验证与报告
+处理 C 组：
 
-```
-1. 重新递归扫描 .cursor/，再次分组
-2. 期望状态：
-   - A 组：全部保留，文件内容未被动过
-   - B 组：数据文件仅含模板内容；项目级 rules/skills/日志 已删除
-   - C 组：为空（或仅剩用户明确要求保留的文件）
-   - 项目根 .gitignore：按用户选择存在或被放弃（状态记到报告里）
-3. 给用户一份结构化报告，至少包含：
-   - 移动的文件（from → to）
-   - 删除的文件
-   - 重置的文件
-   - 新注册/移除的 registry 条目
-   - .gitignore 的处理结果（新建/追加/覆盖/放弃）
-   - 未处理的文件（如果有，逐条说明原因）
-```
+- 非白名单 Skill 必须从 `.cursor/skills/` 移除；如用户要保留，先迁出该目录再删原件。
+- 非 baseline project rule 视为模板项目遗留；逐项预览，确认后删除或迁出。
+- 通用 `.mdc` 可建议迁到 `.cursor/rules/common/`，但只有九个 common rule 属于本基线；
+  最终仍需用户明确决定。
+- 重名冲突永远保留 canonical 版本；冲突副本只能在用户确认后临时放入
+  `.cursor/_init-backup/`，并须在阶段 6 前移出或删除。
 
-### 阶段 7：写入 `.init-done` sentinel
+输出一份合并 dry-run，至少列出：
 
-**仅在阶段 6 验证全部通过后执行**。任何前序阶段异常中断都不写入此文件，确保下次会话 recall 能再次触发。
+- 保留及缺失的 canonical 项；
+- 删除的文件/目录；
+- 重置的状态文件；
+- C 组迁移/删除动作；
+- `local-env.json` 生成计划；
+- registry 重写计划；
+- `.gitignore` 新建/追加/替换计划。
 
-```
-1. 按"模板内容 · .init-done"格式，填充实际值写入 .cursor/.init-done
-2. 向用户输出收尾提示：
-   > 初始化完成。建议现在执行：
-   >   git add .cursor/ .gitignore
-   >   git diff --cached -- .cursor/
-   >   git commit -m "chore(cursor): initialize .cursor from template"
-   >
-   > ⚠️ .cursor/.init-done 必须 commit，否则团队其他成员 clone 后会被再次触发 init。
-```
+等待用户对整份计划明确确认。分类不清就问，不得猜。
 
-**仅跑阶段 5.5 时**（用户说"补 gitignore"）：
-- 若 `.init-done` 存在 → 更新其中的 `gitignore_generated: true` 字段，保留其他字段
-- 若 `.init-done` 不存在 → 提示用户"仓库尚未完整 init，只补 gitignore 不会写 sentinel。是否改为跑完整 init？"
+## 阶段 3：执行 cleanup
 
----
+严格按已确认 dry-run 和 reference 的 cleanup 表执行：
 
-## 规范清单（canonical）
+1. 删除全部历史 changelog fragments，只保留 `entries/.gitkeep`。
+2. 删除全部 backup、cache、编译缓存、ack、session marker、日志和 init 临时文件。
+3. 删除旧 `.cursor/local-env.json`；后续从 example 重新生成。
+4. 删除非白名单 Skill；最终目录名必须恰好为 8 个。
+5. 保留六个 Godot baseline project rules，绝不执行“清空 rules/project”。
+6. 重置 deferred、pitfalls、distillery、profile 状态文件。
+7. 在 entries 为空后运行 `changelog_build.py`，确定性重建四个 changelog 视图。
 
-下列文件构成本 `.cursor` 模板的"主干"，初始化后必须都在、内容不被删改（数据文件除外）：
+某一步失败立即停止；不要继续“尽量完成”，也不要写 sentinel。
 
-### 顶层
+## 阶段 4：重建本机配置与 Registry
 
-- `.cursor/hooks.json`
-- `.cursor/local-env.example.json`
-- `.cursor/.init-done` —— **阶段 7 写入**；模板仓库自身不应包含此文件
+### `local-env.json`
 
-### Rules（通用）
+1. 读取 `.cursor/local-env.example.json`。
+2. 深拷贝其 JSON 结构到 `.cursor/local-env.json`，保留 example 中不认识的键。
+3. 用阶段 1 的值设置 `changelog-author`、`shell`、`godot4_path`。
+4. `godot4_path` 留空时写空字符串，不伪造路径。
+5. 验证 JSON 可解析，且 `.gitignore` 忽略该文件。
 
-- `.cursor/rules/common/baserule.mdc`
-- `.cursor/rules/common/changelog-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/cursor-init-recall.mdc`
+不要引用或等待额外的环境检查 Rule；本阶段就是唯一初始化入口。
 
-### Rules（项目专属目录）
+### Skill Registry
 
-- `.cursor/rules/project/`（保留**空目录**；源项目的 `.mdc` 内容一律删除）
+将 `.cursor/skills/epee-orchestrator/registry.md` 校准为磁盘上的 8 个真实 Skill：
 
-### Skills（规范 Skill 目录白名单）
+`cursor-init`、`deferred-decisions`、`dev-changelog`、`epee-orchestrator`、
+`pitfall-journal`、`problem-distillery`、`profile-memory`、`html-doc`。
 
-- `.cursor/skills/cursor-init/`
-- `.cursor/skills/deferred-decisions/`
-- `.cursor/skills/dev-changelog/`
-- `.cursor/skills/epee-orchestrator/`（含 `registry.md`，见阶段 4）
-- `.cursor/skills/pitfall-journal/`
-- `.cursor/skills/problem-distillery/`
-- `.cursor/skills/profile-memory/`
+不得保留这 8 项之外的条目或任何磁盘上不存在的 Skill。
+每条的路径、类型、能力、触发场景、输出必须与对应 `SKILL.md` 一致。
 
-> **任何不在此白名单中的 skill 目录**，在阶段 3 中一律删除（视为源项目的项目级 Skill）。
+## 阶段 5：生成或补齐 `.gitignore`
 
-### Hooks
+使用 [reference.md](reference.md) 的片段，不得临时拼写：
 
-- `.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. 固定加入 Cursor 运行态片段。
+2. 固定加入 Godot 片段：忽略 `.godot/`，但提交 `*.uid` 和资源 `*.import` sidecar。
+3. 按用户 shell/OS 与自定义项补充其他片段。
+4. 已有 `.gitignore` 时按阶段 1 的新建/追加/替换/跳过选择处理。
+5. 写入前展示最终预览；用户调整后重新预览。
+6. 清除与 `*.uid`、`*.import` 提交要求冲突的旧忽略规则；不要忽略
+   `.cursor/.init-done`。
 
-### 数据占位目录（保留目录，文件重置为模板内容）
+用户跳过时记录 `gitignore_generated: false`；这不等于流程失败，但报告中必须明确。
 
-- `.cursor/changelog/{changelog-full.md, changelog-recent.md, changelog-headlines.md, .changelog-ack}`
-- `.cursor/deferred/registry.md`
-- `.cursor/pitfalls/pitfalls.md`
-- `.cursor/distillery/{problems.md, insights.md, golden-rules.md}`
-- `.cursor/profile/{project-profile.md, project-profile-log.md}`
-- `.cursor/plans/`（空目录）
+## 阶段 6：验证
 
----
+逐项验证，任何失败都回到修复或停止状态：
 
-## 清理清单（cleanup list）
+1. reference 中全部 canonical 文件存在。
+2. 九个 common rules 和六个 Godot baseline project rules 全部存在。
+3. `.cursor/skills/` 的一级目录集合与 8 项白名单**完全相等**。
+4. 所有历史 fragments、backup、cache、旧 ack、session marker 和临时文件均不存在。
+5. `entries/.gitkeep` 存在，entries 下无其他文件。
+6. 四个 changelog 视图与空 entries 经生成器重建的结果一致。
+7. 状态文件等于 reference 模板。
+8. `local-env.json` 可解析、字段与用户输入一致且被 Git 忽略。
+9. registry 恰有 8 项，路径均存在，无三个排除项或旧项目名。
+10. 所有 Skill frontmatter `name` 与目录一致，description 同时说明 what + when。
+11. Skill 内相对引用均存在；不存在环境检查 Rule 的悬空引用。
+12. `.gitignore` 忽略 `.godot/`、`local-env.json`、ack、session marker，同时不忽略 `*.uid` 和
+    资源 `*.import`。
+13. 本次写入的文本为 UTF-8 无 BOM、LF。
 
-### 强制删除
+报告移动、删除、重置、生成、跳过和未解决项。未解决项不为空时不得进入阶段 7。
 
-| 路径 | 原因 |
-|------|------|
-| `.cursor/rules/project/*.mdc` | 源项目的项目级 Rules |
-| `.cursor/skills/<非白名单>/` | 源项目的项目级 Skills |
-| `.cursor/plans/*`（内容） | 源项目规划文档 |
-| `.cursor/*.log`、`.cursor/debug-*.log` | 调试日志遗留 |
-| `.cursor/local-env.json` | 设备绑定配置，需由新设备重新生成 |
-| `.cursor/_init-backup/`（如果是上一轮残留） | 仅阶段 2 冲突备份用，运行前应不存在 |
-| `.cursor/_gitignore-preview`（如果是上一轮残留） | 阶段 5.5 临时文件 |
+## 阶段 7：写 sentinel
 
-### 重置为模板
+仅在阶段 6 全部通过后，按 reference 模板写 `.cursor/.init-done`。写入后再次读取并验证
+字段。`project_type` 固定为 `godot`，`gitignore_generated` 反映阶段 5 实际结果。
 
-见"模板内容"节。
+最后提醒用户检查 `git status` 和 diff，并提交 `.cursor/.init-done`；不要代替用户提交。
 
----
+## 验收结果
 
-## 模板内容
+完整初始化后：
 
-重置数据文件时使用以下内容。带 `{{DATE}}` 的占位符替换为当天日期（`YYYY-MM-DD`）。
-
-### changelog-full.md
-
-```markdown
-# Dev Changelog — Full
-
-完整的开发改动记录，按时间倒序排列。作为主动 RAG 的数据源，用户手动唤醒时读取。
-
-## 记录
-```
-
-### changelog-recent.md
-
-```markdown
-# Dev Changelog — Recent
-
-最近 ~10 次改动的摘要记录，按时间倒序排列。
-当 Agent 检测到当前任务与近期改动相关时自动读取。
-```
-
-### changelog-headlines.md
-
-```markdown
-# Dev Changelog — Headlines
-
-最近 ~50 次改动的一句话概要，按时间倒序排列。每次会话自动注入上下文。
-```
-
-### .changelog-ack
-
-空文件（0 字节），只用于更新 mtime 阻止 hook 重复提醒。
-
-### deferred/registry.md
-
-```markdown
-# Deferred Decisions Registry
-
-## Active Items
-
-（暂无延期方案）
-
----
-
-## Completed / Cancelled Items
-
-（暂无已完成或已废弃的方案）
-```
-
-### pitfalls/pitfalls.md
-
-```markdown
-# Pitfall Journal
-
-开发过程中踩过的坑，按时间倒序排列。
-Agent 进入 Debug mode 或遇到运行时错误时自动检索匹配。
-
----
-```
-
-### distillery/problems.md
-
-```markdown
-# Problem Distillery — Problems
-
-反复出现的顽固问题追踪记录，按时间倒序排列。
-
-<!-- 新条目追加在此行下方 -->
-```
-
-### distillery/insights.md
-
-```markdown
-# Problem Distillery — Insights
-
-从已解决的顽固问题中蒸馏出的精炼方法论。
-
-<!-- 新条目追加在此行下方 -->
-
----
-last_distill_date: {{DATE}}
-```
-
-### distillery/golden-rules.md
-
-```markdown
-# Golden Rules
-
-经过实践验证（权重 >= 5）的精炼认知，每次新会话自动注入。
-
-<!-- 当条目达到权重阈值后由 Agent 自动写入 -->
-```
-
-### profile/project-profile.md
-
-```markdown
-# Project Profile
-
-## 项目定位
-
-## 技术栈与架构
-
-## 设计约定
-
-## 产品方向
-```
-
-### profile/project-profile-log.md
-
-```markdown
-# Project Profile Log
-
-详细记录每次项目画像更新的完整上下文，按时间正序追加。
-
-## 记录
-```
-
-### .init-done
-
-阶段 7 写入的 sentinel，YAML 格式，字段固定：
-
-```yaml
-# .cursor/.init-done — cursor-init Skill 写入的初始化标记文件
-# 本文件的存在表示本仓库已完成 .cursor 模板初始化
-# 请务必 git commit 此文件，避免团队成员 clone 后被再次触发 init
-initialized_at: {{ISO_DATETIME}}      # 如 2026-04-21T16:30:00+08:00
-initialized_by: cursor-init
-skill_version: 2
-project_type: {{PROJECT_TYPE}}        # 阶段 5.5 问卷 Q1 结果；多选逗号分隔；"不确定"写 unknown
-gitignore_generated: {{BOOL}}         # true / false
-```
-
-**写入时机**：
-- 全流程跑完（阶段 6 验证通过）时由阶段 7 写入
-- "补 gitignore" 单独跑阶段 5.5 时，若已存在则只更新 `gitignore_generated` 字段
-
----
-
-## 模板内容 · .gitignore 片段库
-
-阶段 5.5 按用户问卷选择拼接以下片段。每段前后各空一行，保证可读性。
-
-### 固定段：Cursor
-
-```gitignore
-# === Cursor ===
-# 设备绑定配置，不同机器需独立生成
-.cursor/local-env.json
-
-# Hook 运行态标记（仅影响本地会话）
-.cursor/changelog/.changelog-ack
-
-# cursor-init 临时产物
-.cursor/_init-backup/
-.cursor/_gitignore-preview
-```
-
-### OS 段（按问卷 Q3 多选拼接）
-
-**Windows**
-
-```gitignore
-# === OS: Windows ===
-Thumbs.db
-Thumbs.db:encryptable
-ehthumbs.db
-ehthumbs_vista.db
-Desktop.ini
-$RECYCLE.BIN/
-*.stackdump
-*.lnk
-```
-
-**macOS**
-
-```gitignore
-# === OS: macOS ===
-.DS_Store
-.AppleDouble
-.LSOverride
-Icon
-._*
-.DocumentRevisions-V100
-.fseventsd
-.Spotlight-V100
-.TemporaryItems
-.Trashes
-.VolumeIcon.icns
-.com.apple.timemachine.donotpresent
-```
-
-**Linux**
-
-```gitignore
-# === OS: Linux ===
-*~
-.fuse_hidden*
-.directory
-.Trash-*
-.nfs*
-```
-
-### IDE 段（按问卷 Q2 多选拼接）
-
-**VSCode**
-
-```gitignore
-# === IDE: VSCode ===
-.vscode/*
-!.vscode/settings.json
-!.vscode/tasks.json
-!.vscode/launch.json
-!.vscode/extensions.json
-!.vscode/*.code-snippets
-.history/
-*.vsix
-```
-
-**JetBrains**
-
-```gitignore
-# === IDE: JetBrains ===
-.idea/
-*.iml
-*.ipr
-*.iws
-.idea_modules/
-atlassian-ide-plugin.xml
-```
-
-**Visual Studio**
-
-```gitignore
-# === IDE: Visual Studio ===
-.vs/
-*.user
-*.suo
-*.userprefs
-bin/
-obj/
-[Dd]ebug/
-[Rr]elease/
-x64/
-x86/
-```
-
-**Vim/Emacs**
-
-```gitignore
-# === IDE: Vim / Emacs ===
-*.swp
-*.swo
-*.swn
-Session.vim
-.netrwhist
-*~
-\#*\#
-.\#*
-```
-
-**Cursor**：固定段已覆盖，无需额外片段。
-
-### Language / Framework 段（按问卷 Q1 多选拼接）
-
-**Unity**
-
-```gitignore
-# === Language: Unity ===
-[Ll]ibrary/
-[Tt]emp/
-[Oo]bj/
-[Bb]uild/
-[Bb]uilds/
-[Ll]ogs/
-[Uu]ser[Ss]ettings/
-[Mm]emoryCaptures/
-[Rr]ecordings/
-sysinfo.txt
-*.apk
-*.aab
-*.unitypackage
-*.app
-*.csproj
-*.unityproj
-*.sln
-*.suo
-*.tmp
-*.user
-*.userprefs
-*.pidb
-*.booproj
-*.svd
-*.pdb
-*.mdb
-*.opendb
-*.VC.db
-```
-
-**Node.js**
-
-```gitignore
-# === Language: Node.js ===
-node_modules/
-.npm/
-.yarn/
-.pnp.*
-dist/
-build/
-out/
-.next/
-.nuxt/
-.cache/
-.parcel-cache/
-coverage/
-.env
-.env.local
-.env.*.local
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-pnpm-debug.log*
-.turbo/
-```
-
-**Python**
-
-```gitignore
-# === Language: Python ===
-__pycache__/
-*.py[cod]
-*$py.class
-*.so
-.Python
-build/
-dist/
-*.egg-info/
-*.egg
-.venv/
-venv/
-env/
-.pytest_cache/
-.mypy_cache/
-.ruff_cache/
-.coverage
-.coverage.*
-htmlcov/
-.tox/
-.nox/
-.hypothesis/
-.ipynb_checkpoints/
-```
-
-**Rust**
-
-```gitignore
-# === Language: Rust ===
-target/
-**/*.rs.bk
-*.pdb
-# Cargo.lock：lib crate 建议忽略，bin crate 建议提交，默认不忽略
-# Cargo.lock
-```
-
-**Go**
-
-```gitignore
-# === Language: Go ===
-bin/
-vendor/
-*.exe
-*.exe~
-*.dll
-*.so
-*.dylib
-*.test
-*.out
-go.work
-```
-
-**C# 非 Unity**
-
-```gitignore
-# === Language: C# (non-Unity) ===
-bin/
-obj/
-*.user
-*.suo
-*.pdb
-*.cache
-[Dd]ebug/
-[Rr]elease/
-x64/
-x86/
-[Bb]uild/
-*.dll
-*.pdb
-```
-
-**Web 静态站点**
-
-```gitignore
-# === Language: Web Static ===
-node_modules/
-dist/
-build/
-public/build/
-.cache/
-.tmp/
-.sass-cache/
-.parcel-cache/
-```
-
-**其他**：不拼接语言段，用户在 `# === Custom ===` 段自行补充。
-
-### Custom 段（固定尾部）
-
-```gitignore
-# === Custom ===
-# 在此段追加项目专属需要忽略的路径
-```
-
-若用户在问卷 Q4 填了自由文本，按行拆分后追加到 Custom 段下方。
-
----
-
-## 冲突与边界情况处理
-
-| 场景 | 处理 |
-|------|------|
-| C 组某文件与 A 组重名 | 保留 A 组；C 组移到 `.cursor/_init-backup/`，告知用户自行 diff |
-| C 组有 `SKILL.md` 且 skill 名与 A 组白名单同名 | 保留 A 组 skill；C 组整个 skill 目录移到 `_init-backup/` |
-| 数据文件（如 `pitfalls.md`）用户明确说"保留" | 跳过该文件重置 |
-| `local-env.json` 存在且用户说"我就在这台机器上开 B，保留它" | 跳过删除，但提醒其已在 `.gitignore` |
-| `.cursor/rules/project/` 为空目录 | 保留空目录（便于未来放项目级 rules） |
-| 扫描到 `.cursor/_init-backup/`（上轮残留） | 警告用户并询问：删除 / 保留 / 重命名 |
-| `git status` 不能执行（不是 git 仓库） | 警告但不阻塞，改为建议用户手动备份 |
-| `.cursor/.init-done` 已存在且用户触发了全流程 | 阶段 0 展示其元数据并要求二次确认 |
-| 阶段 5.5 项目根已有 `.gitignore` 且用户选"追加" | 把拼装结果追加到现有文件末尾（用 `\n\n# --- 以下由 cursor-init 追加 ---\n` 分隔） |
-| 阶段 5.5 中途异常或用户放弃 | 不写入 `.gitignore`，`.init-done` 的 `gitignore_generated` 记 false |
-| 阶段 7 写 `.init-done` 前前序阶段已 abort | 不写入 sentinel，下次会话 recall 会重新触发 |
-| 用户说"补 gitignore" 但 `.init-done` 不存在 | 提醒"仓库尚未完整 init"，询问是否改为跑全流程 |
-
----
-
-## 与其他系统的协作
-
-| 系统 | 关系 | 说明 |
-|------|------|------|
-| `baserule.mdc` | 分类权威 | 阶段 2 归位目录严格按 baserule 约定 |
-| `cursor-init-recall.mdc` | 触发器 | 负责首次自动触发（alwaysApply + sentinel 检查）和关键词触发 |
-| `epee-orchestrator` Skill | 双向 | 本 Skill 被 Orchestrator 在 registry 里注册；同时本 Skill 负责清理 registry |
-| `dev-changelog` / `pitfall-journal` / `deferred-decisions` / `problem-distillery` / `profile-memory` | 下游数据主人 | 本 Skill 只在阶段 3 重置其数据文件，不改动 SKILL.md |
-| `local-env-check.mdc` | 后继 | 本 Skill 删除 `local-env.json`，后续新会话由 `local-env-check` 自动重新探测并生成 |
-
----
-
-## 一次运行的最终状态（验收标准）
-
-全流程（阶段 0 → 7）完成后 `.cursor/` 应当满足：
-
-1. 规范清单中列出的所有文件/目录都存在
-2. 所有数据文件（changelog/deferred/pitfalls/distillery/profile）仅含模板内容
-3. `.cursor/rules/project/` 为空目录
-4. `.cursor/skills/` 下仅有白名单中的 skill 目录
-5. `.cursor/skills/epee-orchestrator/registry.md` 中只有：基础设施 + 个人级 skill 条目，且包含 `cursor-init` 条目
-6. 不存在 `*.log`、`local-env.json`、`_init-backup/`、`_gitignore-preview`
-7. `.cursor/.init-done` 已写入，字段完整且值有效
-8. 项目根 `.gitignore` 状态明确（存在且有内容 / 被用户显式放弃）
-9. `git status .cursor/ .gitignore` 能让用户清楚看到所有改动
-
-仅跑阶段 5.5（"补 gitignore"）完成后：
-
-1. 项目根 `.gitignore` 存在或被显式放弃
-2. 若 `.init-done` 已存在，其 `gitignore_generated` 字段被更新
-3. 其他 `.cursor/` 内容**零改动**
-
----
-
-## 自迭代日志
-
-本节记录使用本 Skill 过程中发现的必要检查项。
-
-### 已知必要检查
-
-1. **阶段 2 的 C 组归位前必须先做 dry-run 展示** —— 批量移动 .mdc / SKILL 文件是高破坏性操作，只要有一条分类错误就会污染 canonical 结构，必须让用户在列表上逐条过一遍再执行。
-
-2. **重名冲突不许直接覆盖** —— C 组与 A 组重名时，A 组（模板版本）永远是 source of truth，冲突文件只能进 `_init-backup/`，让用户自行决定是否把差异合并回 common rule。
-
-3. **registry 重建时先读后写** —— 阶段 4 不要直接用硬编码模板覆盖 registry.md，必须先解析现有条目，只移除项目级条目、补齐缺失条目，避免丢失用户自己添加的个人级 Skill 条目。
-
-4. **`.init-done` 是完成度契约** —— 只有阶段 6 验证通过后才能写入此文件。中途 abort 必须让 sentinel 缺失，这是保证下次会话能恢复触发的关键设计。
-
-5. **`.gitignore` 用户主导** —— 阶段 5.5 对语言栈/IDE/OS 的判断完全来自用户问卷，不要根据文件探测"智能推断"，因为新项目此时通常还是空白，推断不准反而会填错条目。
+- baseline 结构完整，六个 Godot project rules 仍在；
+- `.cursor/skills/` 只有指定 8 个目录；
+- 历史数据、backup、cache、ack 与临时文件已清；
+- 状态模板与四视图已重置；
+- `local-env.json` 已由 example 生成且 gitignored；
+- `.gitignore` 正确区分 Godot 缓存和需提交的 sidecar；
+- `.init-done` 只在所有验证通过后存在。

.cursor/skills/cursor-init/reference.md

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