92 lines
3.1 KiB
Markdown
92 lines
3.1 KiB
Markdown
# `.cursor` 协作指南
|
||
|
||
本目录提供项目级的 Agent 记忆、计划和开发日志基础设施。所有内容均以 `.cursor/` 为根路径；初始化后的空模板不包含任何项目历史。
|
||
|
||
## 目录
|
||
|
||
- `.cursor/bootstrap/`：多项目类型初始化的 catalog、manifests、惰性 payload、模板与标准库脚本。
|
||
- `.cursor/rules/common/`：所有项目始终启用的 Rules。
|
||
- `.cursor/rules/project/`：只包含初始化时所选项目类型的活动 Rules。
|
||
- `.cursor/skills/`：common 与所选项目类型的活动 Skills。
|
||
- `.cursor/hooks/changelog-scan.json`：由初始化脚本按项目类型生成的 Hook 扫描策略。
|
||
- `.cursor/changelog/entries/`：开发日志 fragment 的唯一数据源。
|
||
- `.cursor/changelog/changelog-*.md`：由生成器确定性生成的只读视图。
|
||
- `.cursor/changelog/tools/`：生成、迁移、合并导入和 Git hooks 安装工具。
|
||
- `.cursor/deferred/registry.md`：延期决策登记。
|
||
- `.cursor/pitfalls/pitfalls.md`：踩坑记录。
|
||
- `.cursor/distillery/`：问题、洞察和黄金规则。
|
||
- `.cursor/profile/`：项目画像及其变更日志。
|
||
- `.cursor/plans/`：实施计划。
|
||
|
||
## 多类型初始化
|
||
|
||
支持类型不能从文档猜测，必须由 catalog 动态返回：
|
||
|
||
```bash
|
||
python .cursor/bootstrap/tools/cursor_init.py --list-types
|
||
```
|
||
|
||
初始化或重置使用 dry-run digest 保护：
|
||
|
||
```bash
|
||
python .cursor/bootstrap/tools/cursor_init.py --dry-run --project-type general \
|
||
--set shell=powershell --set changelog-author=<handle>
|
||
```
|
||
|
||
完整流程、安全边界和类型就绪门槛见 `.cursor/skills/cursor-init/`。未选类型只保存在
|
||
`.cursor/bootstrap/types/`，不会进入 Cursor 活动 Rule/Skill 路径。
|
||
|
||
## 开发日志
|
||
|
||
每条日志保存为 `.cursor/changelog/entries/<author>/<id>.md`。不要手改四个生成视图：
|
||
|
||
- `.cursor/changelog/changelog-full.md`
|
||
- `.cursor/changelog/changelog-recent.md`
|
||
- `.cursor/changelog/changelog-headlines.md`
|
||
- `.cursor/changelog/changelog-by-author.md`
|
||
|
||
创建或修改 fragment 后运行：
|
||
|
||
```bash
|
||
python .cursor/changelog/tools/changelog_build.py
|
||
python .cursor/changelog/tools/changelog_build.py --check
|
||
```
|
||
|
||
生成器要求 Python 3.10 或更高版本。
|
||
|
||
### 安装 Git hooks
|
||
|
||
Windows：
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File .cursor/changelog/tools/install-git-hooks.ps1
|
||
```
|
||
|
||
Linux / macOS：
|
||
|
||
```bash
|
||
sh .cursor/changelog/tools/install-git-hooks.sh
|
||
```
|
||
|
||
`pre-commit` 会重建并暂存四个视图；`post-merge` 会在合并后重新生成视图。每个克隆只需安装一次。
|
||
|
||
### 导入旧格式日志
|
||
|
||
仅在需要把旧的聚合日志转换为 fragment 时使用：
|
||
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File .cursor/changelog/tools/merge-import.ps1
|
||
```
|
||
|
||
```bash
|
||
sh .cursor/changelog/tools/merge-import.sh
|
||
```
|
||
|
||
也可将分支或 ref 作为参数传入。导入工具只添加尚不存在的 ID，随后重建并校验视图。
|
||
|
||
## 维护约定
|
||
|
||
- 生成视图只由 `.cursor/changelog/tools/changelog_build.py` 维护。
|
||
- 新记录写入对应模板文件，不在模板中保留其他项目的数据。
|
||
- 所有文本文件使用 UTF-8（无 BOM）和 LF 换行。
|