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

name, description

name	description
cursor-init	初始化或重置项目的 .cursor 基础设施：保留 canonical Rules、Skills、Hooks 与 Godot baseline，清除模板历史数据，采集本机环境，生成 .gitignore，并在验证成功后 写入 .init-done。首次缺少 sentinel 时自动使用；也用于“初始化 cursor”、 “重置 cursor”、“补 gitignore”等请求。

Cursor Init

把模板仓库或复制来的 .cursor/ 变成可安全使用、可重复执行的 Godot 项目基线。

详细白名单、清理模式、状态模板、sentinel 和 .gitignore 片段统一见 reference.md。执行全流程或仅补 .gitignore 前都必须直接读取该文件， 不得凭记忆重建清单。

入口

首次自动初始化

每次会话首次响应前由 .cursor/rules/common/cursor-init-recall.mdc 检查 .cursor/.init-done。若 sentinel 不存在：

1. 暂存用户原请求，说明需要先初始化。
2. 获得用户同意后执行本 Skill 的阶段 0–7。
3. 仅在阶段 6 全部通过后写 sentinel。
4. 初始化成功后继续原请求。

若用户暂时拒绝，尊重选择；不要写 sentinel，下次会话仍会提醒。

手动全流程

触发词包括：初始化 cursor、cursor init、重置 cursor、reset cursor、 “清理复制来的 .cursor”、“按基线归位”。

sentinel 已存在时必须先展示其元数据并再次确认；不得把手动触发当作无提示重置。

仅补 .gitignore

触发词包括：补 gitignore、生成 .gitignore、gitignore 模板。 只执行阶段 5；不得改动 .cursor/ 的其他内容。若 sentinel 存在，只更新 gitignore_generated；若不存在，询问是否改跑完整初始化，不得只为补 .gitignore 创建 sentinel。

不可协商的安全契约

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。

阶段 0：前置检查

1. 确认项目根存在 .cursor/；不存在则停止并说明缺失。
2. 读取 .cursor/.init-done：
   • 不存在：进入首次初始化。
   • 存在：展示 initialized_at、project_type、skill_version，等待用户明确继续。
3. 执行 git status。有未提交改动时建议先 commit/stash，并等待明确继续；非 Git 仓库则建议备份，但可继续。
4. 读取 reference.md，声明本轮会保留、删除、重置、生成的范围。
5. 未获得明确确认前不得进入写入阶段。

阶段 1：一次性采集本机配置

在一轮提问中采集：

1. changelog-author：稳定、适合文件名的作者 handle。
2. shell：powershell、bash 或 zsh；可把当前探测值作为默认。
3. godot4_path：Godot 4 executable 的绝对路径；允许留空。

同一轮可附带询问 .gitignore 的写入方式（新建 / 追加 / 替换 / 跳过）和自定义忽略项， 不要把三个环境字段拆成多轮追问。仅收集值，此阶段不写文件。

阶段 2：扫描、分类与 dry-run

递归扫描 .cursor/，按 reference 分为：

• A / canonical：精确白名单，保留；缺失项记为阻塞错误。
• B / cleanup：历史 fragment、备份、缓存、设备配置、ack、临时文件和状态数据。
• C / foreign：不属于 A/B 的文件。

处理 C 组：

• 非白名单 Skill 必须从 .cursor/skills/ 移除；如用户要保留，先迁出该目录再删原件。
• 非 baseline project rule 视为模板项目遗留；逐项预览，确认后删除或迁出。
• 通用 .mdc 可建议迁到 .cursor/rules/common/，但只有九个 common rule 属于本基线； 最终仍需用户明确决定。
• 重名冲突永远保留 canonical 版本；冲突副本只能在用户确认后临时放入 .cursor/_init-backup/，并须在阶段 6 前移出或删除。

输出一份合并 dry-run，至少列出：

• 保留及缺失的 canonical 项；
• 删除的文件/目录；
• 重置的状态文件；
• C 组迁移/删除动作；
• local-env.json 生成计划；
• registry 重写计划；
• .gitignore 新建/追加/替换计划。

等待用户对整份计划明确确认。分类不清就问，不得猜。

阶段 3：执行 cleanup

严格按已确认 dry-run 和 reference 的 cleanup 表执行：

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 视图。

某一步失败立即停止；不要继续“尽量完成”，也不要写 sentinel。

阶段 4：重建本机配置与 Registry

local-env.json

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 忽略该文件。

不要引用或等待额外的环境检查 Rule；本阶段就是唯一初始化入口。

Skill Registry

将 .cursor/skills/epee-orchestrator/registry.md 校准为磁盘上的 8 个真实 Skill：

cursor-init、deferred-decisions、dev-changelog、epee-orchestrator、 pitfall-journal、problem-distillery、profile-memory、html-doc。

不得保留这 8 项之外的条目或任何磁盘上不存在的 Skill。 每条的路径、类型、能力、触发场景、输出必须与对应 SKILL.md 一致。

阶段 5：生成或补齐 .gitignore

使用 reference.md 的片段，不得临时拼写：

1. 固定加入 Cursor 运行态片段。
2. 固定加入 Godot 片段：忽略 .godot/，但提交 *.uid 和资源 *.import sidecar。
3. 按用户 shell/OS 与自定义项补充其他片段。
4. 已有 .gitignore 时按阶段 1 的新建/追加/替换/跳过选择处理。
5. 写入前展示最终预览；用户调整后重新预览。
6. 清除与 *.uid、*.import 提交要求冲突的旧忽略规则；不要忽略 .cursor/.init-done。

用户跳过时记录 gitignore_generated: false；这不等于流程失败，但报告中必须明确。

阶段 6：验证

逐项验证，任何失败都回到修复或停止状态：

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。

阶段 7：写 sentinel

仅在阶段 6 全部通过后，按 reference 模板写 .cursor/.init-done。写入后再次读取并验证 字段。project_type 固定为 godot，gitignore_generated 反映阶段 5 实际结果。

最后提醒用户检查 git status 和 diff，并提交 .cursor/.init-done；不要代替用户提交。

验收结果

完整初始化后：

• baseline 结构完整，六个 Godot project rules 仍在；
• .cursor/skills/ 只有指定 8 个目录；
• 历史数据、backup、cache、ack 与临时文件已清；
• 状态模板与四视图已重置；
• local-env.json 已由 example 生成且 gitignored；
• .gitignore 正确区分 Godot 缓存和需提交的 sidecar；
• .init-done 只在所有验证通过后存在。