133 lines
5.4 KiB
Markdown
133 lines
5.4 KiB
Markdown
---
|
||
name: cursor-init
|
||
description: >-
|
||
按项目内 catalog 与 manifest 初始化或重置 Cursor 基础设施。首次缺少 sentinel，
|
||
或用户要求初始化、重置、补齐 Git 忽略配置时使用；只展示当前 ready 的项目类型，
|
||
经 dry-run 确认后物化对应 Rules、Skills、Hooks 与本机配置。
|
||
---
|
||
|
||
# Cursor Init
|
||
|
||
把复制到目标仓库的 common Cursor 基线与惰性项目 bundle，转换为只激活一个
|
||
`project_type` 的可重复状态。流程与安全契约见 [reference.md](reference.md)，机器真相源位于
|
||
`.cursor/bootstrap/`。
|
||
|
||
## 入口
|
||
|
||
- 首次会话：`.cursor/.init-done` 不存在，且用户同意初始化。
|
||
- 手动全流程：`初始化 cursor`、`cursor init`、`重置 cursor`、`reset cursor`。
|
||
- 只补 Git 配置：`补 gitignore`、`生成 .gitignore`、`gitignore 模板`。
|
||
|
||
用户明确要求跳过时不得执行；本初始化框架源码仓也不得因缺少 sentinel 被自动初始化。
|
||
|
||
## 不可协商的安全契约
|
||
|
||
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/bootstrap/catalog.json` 与脚本是否存在。
|
||
2. 读取现有 `.cursor/.init-done`；存在时展示 `project_type`、`skill_version` 与
|
||
`manifest_digest`，重置或换类型前再次确认。
|
||
3. 执行 `git status`；有未提交改动时提醒用户先处理，用户明确继续后才进入问卷。
|
||
4. 确认项目声明 Python 3.10+，再运行脚本；版本不满足时停止，不修改业务文件迁就环境。
|
||
|
||
### 阶段 1：动态问卷
|
||
|
||
先运行：
|
||
|
||
```bash
|
||
python .cursor/bootstrap/tools/cursor_init.py --list-types --json
|
||
```
|
||
|
||
仅把输出中的类型作为单选项。用户选择后运行：
|
||
|
||
```bash
|
||
python .cursor/bootstrap/tools/cursor_init.py --describe-type --project-type <type> --json
|
||
```
|
||
|
||
在一轮提问中只采集 `collect_at_init` 未设为 `false` 且非 `sensitive` 的
|
||
`local_env_fields`，并询问是否跳过 `.gitignore` / `.gitattributes` managed block。
|
||
敏感字段只展示键名和说明，要求用户稍后手工填写 `.cursor/local-env.json`，不得在聊天、
|
||
命令行或 `--set` 中索取。`general` 表示 common-only；common 不作为额外选项。
|
||
|
||
### 阶段 2：dry-run
|
||
|
||
把允许初始化采集的用户输入作为重复的 `--set KEY=VALUE` 传入；值含空格时按当前
|
||
shell 正确引用。不得用 `--set` 传入 sensitive 或 `collect_at_init: false` 字段：
|
||
|
||
```bash
|
||
python .cursor/bootstrap/tools/cursor_init.py \
|
||
--dry-run \
|
||
--project-type <type> \
|
||
--set shell=<shell> \
|
||
--set changelog-author=<handle>
|
||
```
|
||
|
||
用户选择跳过 Git 文件时附加 `--skip-git-files`。dry-run 必须完整展示：
|
||
|
||
- 创建、更新、删除的 managed 文件；
|
||
- 状态模板和 changelog 历史 cleanup；
|
||
- foreign、冲突、缺失 common canonical 与必填输入；
|
||
- `PLAN_DIGEST`。
|
||
|
||
任何阻塞项都先处理并重新 dry-run。让用户确认整份清单与 digest，不拆成多次隐式确认。
|
||
|
||
### 阶段 3：Apply 与验证
|
||
|
||
使用与 dry-run 完全相同的类型、`--set` 和 skip 参数，并附确认摘要：
|
||
|
||
```bash
|
||
python .cursor/bootstrap/tools/cursor_init.py \
|
||
--apply \
|
||
--project-type <type> \
|
||
--plan-digest <PLAN_DIGEST> \
|
||
--set shell=<shell> \
|
||
--set changelog-author=<handle>
|
||
```
|
||
|
||
脚本会：
|
||
|
||
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`。
|
||
|
||
完成后运行：
|
||
|
||
```bash
|
||
python .cursor/bootstrap/tools/cursor_init.py --check
|
||
python .cursor/changelog/tools/changelog_build.py --check
|
||
```
|
||
|
||
任一失败都报告具体漂移，不手工伪造 sentinel。
|
||
|
||
## 只补 Git 配置
|
||
|
||
仍先动态列出并选择项目类型，再采集允许初始化采集的本机字段；敏感字段继续由用户
|
||
手工维护。使用正常 dry-run/apply，但在确认清单中只允许 Git managed blocks 与必要生成文件
|
||
发生预期变化；若出现 cleanup、类型切换或活动文件变化，询问用户是否改跑完整初始化，
|
||
不得把它伪装成“只补 gitignore”。
|
||
|
||
## Bundle 就绪门槛
|
||
|
||
类型只有同时满足以下条件才能在 catalog 标记为 `ready`：
|
||
|
||
- manifest、payload、Git 片段与 Hook scan 策略完整；
|
||
- manifest 引用的 Skill 在 `skills.json` 中登记且 payload 含完整 `SKILL.md` 目录；
|
||
- 初始化引擎与 Hook 双平台测试通过；
|
||
- `--check` 能验证该类型的活动闭包。
|
||
|
||
只有计划或空目录的类型必须保持 `draft`；Roblox 在完成上述门槛前不得出现在用户问卷中。
|