8.0 KiB
Cursor Init Reference
本文件说明多类型初始化的数据契约和验收规则。机器真相源是 .cursor/bootstrap/*.json；
流程入口是 SKILL.md。不得在本文件重新维护固定 Rule/Skill 数量。
1. 目录边界
.cursor/
├─ bootstrap/ # tracked、惰性、自包含可信源
│ ├─ catalog.json # 支持类型与状态
│ ├─ common.manifest.json # common canonical、重置与公共策略
│ ├─ skills.json # 全部 Skill 与 Registry 元数据
│ ├─ fragments/ # common Git managed block 片段
│ ├─ templates/ # 状态与空 changelog 模板
│ ├─ tools/cursor_init.py # dry-run/apply/check 引擎
│ ├─ tests/test_cursor_init.py
│ └─ types/<type>/
│ ├─ manifest.json
│ ├─ fragments/
│ └─ payload/ # 未选时不会进入 Cursor 活动目录
├─ rules/common/ # 始终活动
├─ rules/project/ # 只含所选类型；general 时仅 .gitkeep
├─ skills/ # common + 所选类型 Skill
├─ hooks/changelog-scan.json # 按类型生成的活动扫描策略
├─ .init-state.json # managed payload 文件 hash
└─ .init-done # 全部验证通过后的提交标记
保护边界
.cursor/bootstrap/**永不被 cleanup、类型切换或 reset 修改。- common 只在活动层保存一份；缺失时阻塞，不从不明来源生成空文件。
- payload 中的
.mdc/SKILL.md不位于 Cursor 活动路径，未选类型不得物化。 source/和业务目录不属于初始化管理范围。
2. Catalog
.cursor/bootstrap/catalog.json 字段：
schema_version：当前为1；skill_version：sentinel 使用的初始化契约版本；common_manifest、skills_catalog：相对 bootstrap 的安全路径；types[]：id、用户标签label、status与 manifest 路径。
合法状态只有：
ready：payload 和片段完整且可通过校验；会出现在--list-types；draft：允许保留设计占位，但不会暴露给用户，也不能 dry-run/apply。
Agent 只能展示脚本返回的 ready 类型，不从文档、MCP 或目录名猜测支持范围。
3. Common Manifest
.cursor/bootstrap/common.manifest.json 是跨类型契约：
canonical_files：必须存在的活动 common 文件；skills：始终活动的 Skill ID；local_env_fields：所有类型都声明的本机字段；是否由初始化采集由字段元数据决定；scan：Hook 公共扫描策略；gitignore_fragments/gitattributes_fragments：公共 Git 片段；reset_files：初始化时恢复为空模板的状态文件；cleanup_globs：确认后删除的历史 fragment、缓存、备份和运行标记。
所有路径必须是项目根或 manifest 根内的相对路径；.. 与绝对路径非法。
4. Type Manifest
每个 .cursor/bootstrap/types/<type>/manifest.json 声明：
id、version；readiness：是否允许空 payload，以及 ready 时是否强制要求 scan / gitignore；files[]：单文件 source → 活动 target；trees[]：完整目录 source → 活动 target，适合项目专属 Skill；skills[]：该类型激活的 Skill ID；local_env_fields：仅选择该类型时生成；是否由初始化采集由字段元数据决定；scan：与 common 合并的 Hook 文件名、扩展名和排除目录；- Git managed block 片段。
general 表示 common-only，不物化 project Rule/Skill。类型切换时，只删除已知 managed
且 hash 未被用户修改的旧 bundle 文件；用户改动过的文件必须成为阻塞项。
5. Skill Registry
.cursor/bootstrap/skills.json 保存每个 Skill 的：
id、scope、活动target；- Registry 的类型、能力、触发场景和输出。
common manifest 和 type manifest 只引用 Skill ID。初始化脚本按活动 ID 生成
.cursor/skills/epee-orchestrator/registry.md，并验证对应目录存在 SKILL.md。
创建、删除、重命名或实质修改 Skill 时，先更新 skills.json 与所属 manifest，再重新生成 Registry。
6. Dry-run 与所有权
dry-run 至少包含：
创建 / 更新 / 删除
Foreign
阻塞
PLAN_DIGEST
阻塞条件包括：
- common canonical、ready payload 或片段缺失；
- 活动目录存在 manifest 未登记的 Rule/Skill；
- managed 文件内容既不等于 payload，也不等于
.init-state.json记录的安装 hash； - 本机必填字段缺失；
- Git managed block 标记缺失一端、重复或损坏；
- 路径越界或 schema 无效。
Apply 必须重算同一份计划并比对 digest。只有无阻塞计划才可执行。
7. 生成文件
local-env.example.json / local-env.json
common 与所选类型的 local_env_fields 按顺序合并。每个字段可使用：
required：初始化完成前是否必须提供；sensitive：值是否属于密钥等敏感信息；collect_at_init：初始化问卷和--set是否允许采集。
example 可提交且只能包含占位值；local-env 保留未知键和已有用户值，并由 .gitignore
忽略。只有非 sensitive 且 collect_at_init 未设为 false 的字段才允许通过
--set KEY=VALUE 提供。敏感字段不阻塞初始化，也不参与状态漂移，真实值必须由用户
手工写入 .cursor/local-env.json；不得保存密码、Cookie 或会话令牌。
changelog-scan.json
common + type 的 included_names、included_extensions、excluded_directories 去重合并。
PowerShell/Bash Hook 只读取此文件；会话标记、Git 内容状态与 mtime 的守卫逻辑留在脚本中。
Git managed blocks
脚本只维护以下标记之间的内容：
# >>> cursor-init managed >>>
...
# <<< cursor-init managed <<<
标记外用户内容不得覆盖。选择 --skip-git-files 时不改 .gitignore / .gitattributes，
sentinel 写 gitignore_generated: false。
.init-state.json
记录当前项目类型、bundle 版本、manifest digest 与已物化 payload 文件 hash，用于区分 bundle 升级和用户修改。它需要提交，不能包含本机绝对路径或秘密。
8. Sentinel
.cursor/.init-done 仅在 apply 后活动闭包再次验证通过时写入：
initialized_by: cursor-init
initialized_at: <ISO_DATETIME>
schema_version: 1
skill_version: <catalog.skill_version>
project_type: <single-ready-type>
bundle_version: <type-manifest.version>
manifest_digest: <sha256>
gitignore_generated: true|false
sentinel 和 .init-state.json 字段必须与当前 manifest 一致。取消、摘要变化、部分写入或验证失败
都不得创建/更新 sentinel。
9. Hook 契约
check-changelog.ps1 与 .sh 必须保持相同行为：
- 非 Agent mode、缺 changelog、缺 scan config、缺
.session-start时返回{}； - Git 不可用、状态失败或工作区无内容差异时返回
{}； - 只扫描活动配置命中的文件，并要求 mtime 晚于 session/changelog；
- 候选路径还必须被
git status --porcelain判定为未提交改动； - 任意解析或运行错误 fail-open，不阻断用户。
回归测试入口：
python .cursor/hooks/tests/test_check_changelog.py
10. 验收
初始化或重置完成后：
python .cursor/bootstrap/tools/cursor_init.py --check通过；- 活动 project Rules/Skills 与单选类型闭包完全一致，未选 payload 仍惰性保留；
- Registry、scan config、local-env example、Git managed blocks 与 manifest 一致；
- cleanup 后 changelog entries 仅有
.gitkeep，状态文件等于模板； python .cursor/changelog/tools/changelog_build.py --check通过；- Hook 双实现测试、初始化引擎测试、
git diff --check通过； - 本轮写入文本为 UTF-8 无 BOM、LF。