大改版，可以针对不同项目引擎进行初始化
This commit is contained in:
Nostars Developer
@@ -1,199 +1,132 @@
|
||||
---
|
||||
name: cursor-init
|
||||
description: >-
|
||||
初始化或重置项目的 .cursor 基础设施：保留 canonical Rules、Skills、Hooks 与
|
||||
Godot baseline，清除模板历史数据，采集本机环境，生成 .gitignore，并在验证成功后
|
||||
写入 .init-done。首次缺少 sentinel 时自动使用；也用于“初始化 cursor”、
|
||||
“重置 cursor”、“补 gitignore”等请求。
|
||||
按项目内 catalog 与 manifest 初始化或重置 Cursor 基础设施。首次缺少 sentinel，
|
||||
或用户要求初始化、重置、补齐 Git 忽略配置时使用；只展示当前 ready 的项目类型，
|
||||
经 dry-run 确认后物化对应 Rules、Skills、Hooks 与本机配置。
|
||||
---
|
||||
|
||||
# Cursor Init
|
||||
|
||||
把模板仓库或复制来的 `.cursor/` 变成可安全使用、可重复执行的 Godot 项目基线。
|
||||
|
||||
详细白名单、清理模式、状态模板、sentinel 和 `.gitignore` 片段统一见
|
||||
[reference.md](reference.md)。执行全流程或仅补 `.gitignore` 前都必须直接读取该文件，
|
||||
不得凭记忆重建清单。
|
||||
把复制到目标仓库的 common Cursor 基线与惰性项目 bundle，转换为只激活一个
|
||||
`project_type` 的可重复状态。流程与安全契约见 [reference.md](reference.md)，机器真相源位于
|
||||
`.cursor/bootstrap/`。
|
||||
|
||||
## 入口
|
||||
|
||||
### 首次自动初始化
|
||||
- 首次会话：`.cursor/.init-done` 不存在，且用户同意初始化。
|
||||
- 手动全流程：`初始化 cursor`、`cursor init`、`重置 cursor`、`reset cursor`。
|
||||
- 只补 Git 配置：`补 gitignore`、`生成 .gitignore`、`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。
|
||||
用户明确要求跳过时不得执行；本初始化框架源码仓也不得因缺少 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。
|
||||
1. 先检查 Git 状态，再列出支持类型；未确认完整 dry-run 前不写文件。
|
||||
2. 类型选项只能来自脚本 `--list-types` 输出，不在对话中硬编码或展示 `draft` bundle。
|
||||
3. `.cursor/bootstrap/**` 是自包含可信源，初始化、重置和 cleanup 永不删除或覆盖。
|
||||
4. common canonical 缺失、foreign Rule/Skill、用户修改过的 managed 文件或摘要变化都是阻塞项。
|
||||
5. Apply 必须携带用户确认的 `PLAN_DIGEST`；扫描变化后重新 dry-run。
|
||||
6. 失败、取消或验证未通过时不得写 `.cursor/.init-done`。
|
||||
7. 新写文本使用 UTF-8 无 BOM、LF；不得安装第三方依赖。
|
||||
8. 不运行本 Skill 自行初始化当前 CursorInitGeneral 源码仓。
|
||||
|
||||
## 阶段 0：前置检查
|
||||
## 标准流程
|
||||
|
||||
1. 确认项目根存在 `.cursor/`；不存在则停止并说明缺失。
|
||||
2. 读取 `.cursor/.init-done`：
|
||||
- 不存在：进入首次初始化。
|
||||
- 存在：展示 `initialized_at`、`project_type`、`skill_version`，等待用户明确继续。
|
||||
3. 执行 `git status`。有未提交改动时建议先 commit/stash，并等待明确继续；非 Git
|
||||
仓库则建议备份，但可继续。
|
||||
4. 读取 [reference.md](reference.md)，声明本轮会保留、删除、重置、生成的范围。
|
||||
5. 未获得明确确认前不得进入写入阶段。
|
||||
### 阶段 0：前置检查
|
||||
|
||||
## 阶段 1：一次性采集本机配置
|
||||
1. 检查项目根、`.cursor/bootstrap/catalog.json` 与脚本是否存在。
|
||||
2. 读取现有 `.cursor/.init-done`；存在时展示 `project_type`、`skill_version` 与
|
||||
`manifest_digest`，重置或换类型前再次确认。
|
||||
3. 执行 `git status`；有未提交改动时提醒用户先处理，用户明确继续后才进入问卷。
|
||||
4. 确认项目声明 Python 3.10+，再运行脚本；版本不满足时停止，不修改业务文件迁就环境。
|
||||
|
||||
在**一轮提问**中采集：
|
||||
### 阶段 1：动态问卷
|
||||
|
||||
1. `changelog-author`：稳定、适合文件名的作者 handle。
|
||||
2. `shell`：`powershell`、`bash` 或 `zsh`；可把当前探测值作为默认。
|
||||
3. `godot4_path`：Godot 4 executable 的绝对路径；允许留空。
|
||||
先运行：
|
||||
|
||||
同一轮可附带询问 `.gitignore` 的写入方式（新建 / 追加 / 替换 / 跳过）和自定义忽略项，
|
||||
不要把三个环境字段拆成多轮追问。仅收集值，此阶段不写文件。
|
||||
```bash
|
||||
python .cursor/bootstrap/tools/cursor_init.py --list-types --json
|
||||
```
|
||||
|
||||
## 阶段 2：扫描、分类与 dry-run
|
||||
仅把输出中的类型作为单选项。用户选择后运行：
|
||||
|
||||
递归扫描 `.cursor/`，按 reference 分为：
|
||||
```bash
|
||||
python .cursor/bootstrap/tools/cursor_init.py --describe-type --project-type <type> --json
|
||||
```
|
||||
|
||||
- **A / canonical**：精确白名单，保留；缺失项记为阻塞错误。
|
||||
- **B / cleanup**：历史 fragment、备份、缓存、设备配置、ack、临时文件和状态数据。
|
||||
- **C / foreign**：不属于 A/B 的文件。
|
||||
在一轮提问中只采集 `collect_at_init` 未设为 `false` 且非 `sensitive` 的
|
||||
`local_env_fields`，并询问是否跳过 `.gitignore` / `.gitattributes` managed block。
|
||||
敏感字段只展示键名和说明，要求用户稍后手工填写 `.cursor/local-env.json`，不得在聊天、
|
||||
命令行或 `--set` 中索取。`general` 表示 common-only；common 不作为额外选项。
|
||||
|
||||
处理 C 组：
|
||||
### 阶段 2：dry-run
|
||||
|
||||
- 非白名单 Skill 必须从 `.cursor/skills/` 移除；如用户要保留，先迁出该目录再删原件。
|
||||
- 非 baseline project rule 视为模板项目遗留；逐项预览，确认后删除或迁出。
|
||||
- 通用 `.mdc` 可建议迁到 `.cursor/rules/common/`，但只有九个 common rule 属于本基线；
|
||||
最终仍需用户明确决定。
|
||||
- 重名冲突永远保留 canonical 版本；冲突副本只能在用户确认后临时放入
|
||||
`.cursor/_init-backup/`，并须在阶段 6 前移出或删除。
|
||||
把允许初始化采集的用户输入作为重复的 `--set KEY=VALUE` 传入；值含空格时按当前
|
||||
shell 正确引用。不得用 `--set` 传入 sensitive 或 `collect_at_init: false` 字段：
|
||||
|
||||
输出一份合并 dry-run，至少列出：
|
||||
```bash
|
||||
python .cursor/bootstrap/tools/cursor_init.py \
|
||||
--dry-run \
|
||||
--project-type <type> \
|
||||
--set shell=<shell> \
|
||||
--set changelog-author=<handle>
|
||||
```
|
||||
|
||||
- 保留及缺失的 canonical 项；
|
||||
- 删除的文件/目录；
|
||||
- 重置的状态文件；
|
||||
- C 组迁移/删除动作；
|
||||
- `local-env.json` 生成计划；
|
||||
- registry 重写计划；
|
||||
- `.gitignore` 新建/追加/替换计划。
|
||||
用户选择跳过 Git 文件时附加 `--skip-git-files`。dry-run 必须完整展示：
|
||||
|
||||
等待用户对整份计划明确确认。分类不清就问，不得猜。
|
||||
- 创建、更新、删除的 managed 文件；
|
||||
- 状态模板和 changelog 历史 cleanup；
|
||||
- foreign、冲突、缺失 common canonical 与必填输入；
|
||||
- `PLAN_DIGEST`。
|
||||
|
||||
## 阶段 3：执行 cleanup
|
||||
任何阻塞项都先处理并重新 dry-run。让用户确认整份清单与 digest，不拆成多次隐式确认。
|
||||
|
||||
严格按已确认 dry-run 和 reference 的 cleanup 表执行：
|
||||
### 阶段 3：Apply 与验证
|
||||
|
||||
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 视图。
|
||||
使用与 dry-run 完全相同的类型、`--set` 和 skip 参数，并附确认摘要：
|
||||
|
||||
某一步失败立即停止；不要继续“尽量完成”，也不要写 sentinel。
|
||||
```bash
|
||||
python .cursor/bootstrap/tools/cursor_init.py \
|
||||
--apply \
|
||||
--project-type <type> \
|
||||
--plan-digest <PLAN_DIGEST> \
|
||||
--set shell=<shell> \
|
||||
--set changelog-author=<handle>
|
||||
```
|
||||
|
||||
## 阶段 4：重建本机配置与 Registry
|
||||
脚本会：
|
||||
|
||||
### `local-env.json`
|
||||
1. 重算摘要并拒绝时序变化；
|
||||
2. 重置模板状态、清理历史运行数据；
|
||||
3. 只物化所选类型的 Rules/Skills，移除未选 bundle 的未修改 managed 文件；
|
||||
4. 生成 `local-env.example.json`、`local-env.json`、EPEE Registry 与 Hook scan profile；
|
||||
5. 更新 Git managed blocks（未跳过时）；
|
||||
6. 验证活动闭包，最后写 `.cursor/.init-state.json` 与 `.cursor/.init-done`。
|
||||
|
||||
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；本阶段就是唯一初始化入口。
|
||||
```bash
|
||||
python .cursor/bootstrap/tools/cursor_init.py --check
|
||||
python .cursor/changelog/tools/changelog_build.py --check
|
||||
```
|
||||
|
||||
### Skill Registry
|
||||
任一失败都报告具体漂移，不手工伪造 sentinel。
|
||||
|
||||
将 `.cursor/skills/epee-orchestrator/registry.md` 校准为磁盘上的 8 个真实 Skill：
|
||||
## 只补 Git 配置
|
||||
|
||||
`cursor-init`、`deferred-decisions`、`dev-changelog`、`epee-orchestrator`、
|
||||
`pitfall-journal`、`problem-distillery`、`profile-memory`、`html-doc`。
|
||||
仍先动态列出并选择项目类型，再采集允许初始化采集的本机字段；敏感字段继续由用户
|
||||
手工维护。使用正常 dry-run/apply，但在确认清单中只允许 Git managed blocks 与必要生成文件
|
||||
发生预期变化；若出现 cleanup、类型切换或活动文件变化，询问用户是否改跑完整初始化，
|
||||
不得把它伪装成“只补 gitignore”。
|
||||
|
||||
不得保留这 8 项之外的条目或任何磁盘上不存在的 Skill。
|
||||
每条的路径、类型、能力、触发场景、输出必须与对应 `SKILL.md` 一致。
|
||||
## Bundle 就绪门槛
|
||||
|
||||
## 阶段 5：生成或补齐 `.gitignore`
|
||||
类型只有同时满足以下条件才能在 catalog 标记为 `ready`：
|
||||
|
||||
使用 [reference.md](reference.md) 的片段，不得临时拼写：
|
||||
- manifest、payload、Git 片段与 Hook scan 策略完整；
|
||||
- manifest 引用的 Skill 在 `skills.json` 中登记且 payload 含完整 `SKILL.md` 目录；
|
||||
- 初始化引擎与 Hook 双平台测试通过；
|
||||
- `--check` 能验证该类型的活动闭包。
|
||||
|
||||
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` 只在所有验证通过后存在。
|
||||
只有计划或空目录的类型必须保持 `draft`；Roblox 在完成上述门槛前不得出现在用户问卷中。
|
||||
|
||||
Reference in New Issue
Block a user