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

name, description

name	description
cursor-init	初始化新项目的 .cursor 结构。当用户把本项目的 .cursor 模板复制到新项目后说 "初始化cursor"、"cursor 初始化"、"重置 cursor"、"cursor init" 时触发。 按 baserule.mdc 约定识别并迁移目标项目原有的 rules/skills，清理模板中残留的 项目专用数据（changelog/deferred/pitfalls/profile/distillery/local-env/ 项目级 rules 与 skills 等），把 .cursor 重置为可以直接投入新项目的干净起点。 该 Skill 通常每个新项目只运行一次，以稳定准确为首要目标。

Cursor Init Skill

把从其它项目复制过来的 .cursor/ 目录重置为当前新项目的干净起点。

使用场景

典型流程：

1. 用户在 "源项目 A" 中使用本 .cursor 模板开发
2. 用户开 "新项目 B"，把 A 的 .cursor/ 整体拷贝到 B 的根目录
3. B 原先可能也有自己零散的 rules/SKILL 文件（路径、命名未必标准）
4. 用户在 B 中说"初始化cursor"
5. 本 Skill 接管：
   - 把 B 原有的 rules/skills 按 baserule.mdc 归位
   - 把 A 遗留的项目专用数据清空或删除
   - 重建干净的 registry，让 B 从第一天起就有规范的 .cursor

触发条件

用户直接表达"初始化 cursor"类意图：

• 初始化cursor / 初始化 cursor / cursor 初始化
• 重置 cursor / reset cursor
• cursor init / init cursor
• 口头描述"把复制过来的 .cursor 清理一下"、"按 baserule 归位一下"

执行原则（不可协商）

1. 稳定准确 > token 成本：每一步可以多读、多确认、让用户点头，不要图快
2. 破坏性操作必须 dry-run：删除、重置必须先列清单给用户确认
3. 不可逆操作前提醒 git：开始前先提示用户确认工作区已 commit/stash，便于回滚
4. 模糊就问：分类不清的文件一律问用户，不要猜
5. 幂等：反复运行应当无害（第二次不会再改已经干净的 .cursor）

核心流程

阶段 0：前置确认

1. 检查当前工作目录下存在 .cursor/
   - 不存在 → 直接结束，提示用户先复制模板
2. 运行 `git status`，若有未提交改动：
   - 提醒用户："建议先 commit 或 stash，便于回滚"
   - 等用户明确回复"继续"再往下
3. 向用户声明本次操作的范围（见"分组规则"），请求用户口头确认启动

阶段 1：递归扫描 .cursor/

1. 用 shell 列出 .cursor 下所有文件（含子目录）
2. 把每个文件对照"规范清单"和"清理清单"分成三组：
   - A 组（canonical）：在规范清单中，原样保留
   - B 组（template-data）：在清理清单中，需要删除或重置
   - C 组（foreign）：两张清单都没覆盖到的，视作目标项目原有文件或未知项
3. 把分组结果用表格汇报给用户：
   | 组 | 路径 | 处理动作 |

阶段 2：处理 C 组（目标项目原有文件归位）

对 C 组中的每个文件，按 baserule.mdc 的归属约定分类，逐条询问用户（可一次性列清单批量确认）：

文件特征	建议归属	目标路径
.mdc 且内容是跨项目通用规则	通用 Rule	.cursor/rules/common/<name>.mdc
.mdc 且内容是当前新项目专属规则	项目 Rule	.cursor/rules/project/<name>.mdc
包含 SKILL.md 的目录	Skill（无论通用/项目专属）	.cursor/skills/<skill-name>/
看不出归属	询问用户	—
明显是临时/垃圾文件（*.log、*.tmp、缓存等）	删除（需用户确认）	—

执行要点：

• 先列清单一次性确认，然后批量执行移动/删除，避免交互过于频繁
• 重名冲突：C 组文件若与 A 组规范文件重名（例如 C 组有 baserule.mdc），保留 A 组版本，把 C 组备份到 .cursor/_init-backup/ 下让用户自行 diff，不直接覆盖
• Skill 归属提示：通用 Skill 建议用户之后手动同步到 ~/.cursor/skills/（跨项目便利副本，可选）
• 迁移后核查：移动完成后重新扫描，确认 C 组已清空

阶段 3：处理 B 组（源项目项目专用数据清理/重置）

按"清理清单"执行：

A. 直接删除

• .cursor/rules/project/*.mdc（全部）—— 源项目的项目级 rules，新项目不适用
• .cursor/skills/<非规范 skill 目录>/—— 源项目的项目级 Skills（不在规范 Skill 列表中的所有 Skill 目录）
• .cursor/plans/ 下所有文件（目录保留，内容清空）
• .cursor/debug-*.log、.cursor/*.log —— 调试日志
• .cursor/local-env.json —— 设备绑定，需要新设备重新生成（local-env-check.mdc 会自动探测）

B. 重置为空模板（保留文件，仅清内容）

文件	模板（见"模板内容"节）
.cursor/changelog/changelog-full.md	L1 模板
.cursor/changelog/changelog-recent.md	L2 模板
.cursor/changelog/changelog-headlines.md	L3 模板
.cursor/changelog/.changelog-ack	空文件（touch）
.cursor/deferred/registry.md	deferred 模板
.cursor/pitfalls/pitfalls.md	pitfalls 模板
.cursor/distillery/problems.md	problems 模板
.cursor/distillery/insights.md	insights 模板
.cursor/distillery/golden-rules.md	golden-rules 模板
.cursor/profile/project-profile.md	project-profile 模板
.cursor/profile/project-profile-log.md	project-profile-log 模板

执行要点：

• 每个重置动作前先 Read 现有内容预览前 10 行给用户，避免误删有价值的数据（特别是 deferred/pitfalls 用户可能想保留）
• 如用户对某个数据文件明确说"保留"（例如 golden-rules 想带过去），跳过该文件的重置

阶段 4：重建 registry

打开 .cursor/skills/epee-orchestrator/registry.md：

1. 解析现有条目（每条 ### <skill-name> 块）
2. 删除所有 类型: 项目级 的条目
3. 遍历 .cursor/skills/ 目录，对照 registry：
   • registry 有条目但 skill 目录不存在 → 删除条目（说明是被第 3 阶段清理掉的项目级 skill）
   • skill 目录存在但 registry 无条目 → 读取该 skill 的 SKILL.md frontmatter，新增条目
4. 确保 cursor-init 条目本身存在（类型: 基础设施）
5. 写回 registry.md

阶段 5：同步 hooks.json（跨平台保守处理）

• 读取 .cursor/hooks.json
• 若 command 字段硬编码为 powershell ...，且目标新项目声明/探测到的 shell 不是 powershell（参考 local-env-check.mdc），提醒用户需要按 hooks/README.md 的说明手动改成 bash .cursor/hooks/xxx.sh
• 本阶段不自动改 hooks.json，避免误判

阶段 6：验证与报告

1. 重新递归扫描 .cursor/，再次分组
2. 期望状态：
   - A 组：全部保留，文件内容未被动过
   - B 组：数据文件仅含模板内容；项目级 rules/skills/日志 已删除
   - C 组：为空（或仅剩用户明确要求保留的文件）
3. 给用户一份结构化报告，至少包含：
   - 移动的文件（from → to）
   - 删除的文件
   - 重置的文件
   - 新注册/移除的 registry 条目
   - 未处理的文件（如果有，逐条说明原因）
4. 收尾提示：
   > 初始化完成。建议现在执行：
   >   git add .cursor/
   >   git diff --cached -- .cursor/
   >   git commit -m "chore(cursor): initialize .cursor from template"

---

规范清单（canonical）

下列文件构成本 .cursor 模板的"主干"，初始化后必须都在、内容不被删改（数据文件除外，见"清理清单"）：

顶层

• .cursor/hooks.json
• .cursor/local-env.example.json

Rules（通用）

• .cursor/rules/common/baserule.mdc
• .cursor/rules/common/changelog-recall.mdc
• .cursor/rules/common/deferred-recall.mdc
• .cursor/rules/common/distillery-recall.mdc
• .cursor/rules/common/epee-orchestrator.mdc
• .cursor/rules/common/pitfall-recall.mdc
• .cursor/rules/common/profile-recall.mdc
• .cursor/rules/common/cursor-init-recall.mdc

Rules（项目专属目录）

• .cursor/rules/project/（保留空目录；源项目的 .mdc 内容一律删除）

Skills（规范 Skill 目录白名单）

• .cursor/skills/cursor-init/
• .cursor/skills/deferred-decisions/
• .cursor/skills/dev-changelog/
• .cursor/skills/epee-orchestrator/（含 registry.md，见阶段 4）
• .cursor/skills/pitfall-journal/
• .cursor/skills/problem-distillery/
• .cursor/skills/profile-memory/

任何不在此白名单中的 skill 目录，在阶段 3 中一律删除（视为源项目的项目级 Skill）。

Hooks

• .cursor/hooks/README.md
• .cursor/hooks/run-hook.ps1
• .cursor/hooks/session-init.ps1
• .cursor/hooks/session-init.sh
• .cursor/hooks/check-changelog.ps1
• .cursor/hooks/check-changelog.sh

数据占位目录（保留目录，文件重置为模板内容）

• .cursor/changelog/{changelog-full.md, changelog-recent.md, changelog-headlines.md, .changelog-ack}
• .cursor/deferred/registry.md
• .cursor/pitfalls/pitfalls.md
• .cursor/distillery/{problems.md, insights.md, golden-rules.md}
• .cursor/profile/{project-profile.md, project-profile-log.md}
• .cursor/plans/（空目录）

---

清理清单（cleanup list）

强制删除

路径	原因
.cursor/rules/project/*.mdc	源项目的项目级 Rules
.cursor/skills/<非白名单>/	源项目的项目级 Skills
.cursor/plans/*（内容）	源项目规划文档
.cursor/*.log、.cursor/debug-*.log	调试日志遗留
.cursor/local-env.json	设备绑定配置，需由新设备重新生成
.cursor/_init-backup/（如果是上一轮残留）	仅阶段 2 冲突备份用，运行前应不存在

重置为模板

见"模板内容"节。

---

模板内容

重置数据文件时使用以下内容。带 {{DATE}} 的占位符替换为当天日期（YYYY-MM-DD）。

changelog-full.md

# Dev Changelog — Full

完整的开发改动记录，按时间倒序排列。作为主动 RAG 的数据源，用户手动唤醒时读取。

## 记录

changelog-recent.md

# Dev Changelog — Recent

最近 ~10 次改动的摘要记录，按时间倒序排列。
当 Agent 检测到当前任务与近期改动相关时自动读取。

changelog-headlines.md

# Dev Changelog — Headlines

最近 ~50 次改动的一句话概要，按时间倒序排列。每次会话自动注入上下文。

.changelog-ack

空文件（0 字节），只用于更新 mtime 阻止 hook 重复提醒。

deferred/registry.md

# Deferred Decisions Registry

## Active Items

（暂无延期方案）

---

## Completed / Cancelled Items

（暂无已完成或已废弃的方案）

pitfalls/pitfalls.md

# Pitfall Journal

开发过程中踩过的坑，按时间倒序排列。
Agent 进入 Debug mode 或遇到运行时错误时自动检索匹配。

---

distillery/problems.md

# Problem Distillery — Problems

反复出现的顽固问题追踪记录，按时间倒序排列。

<!-- 新条目追加在此行下方 -->

distillery/insights.md

# Problem Distillery — Insights

从已解决的顽固问题中蒸馏出的精炼方法论。

<!-- 新条目追加在此行下方 -->

---
last_distill_date: {{DATE}}

distillery/golden-rules.md

# Golden Rules

经过实践验证（权重 >= 5）的精炼认知，每次新会话自动注入。

<!-- 当条目达到权重阈值后由 Agent 自动写入 -->

profile/project-profile.md

# Project Profile

## 项目定位

## 技术栈与架构

## 设计约定

## 产品方向

profile/project-profile-log.md

# Project Profile Log

详细记录每次项目画像更新的完整上下文，按时间正序追加。

## 记录

---

冲突与边界情况处理

场景	处理
C 组某文件与 A 组重名	保留 A 组；C 组移到 .cursor/_init-backup/，告知用户自行 diff
C 组有 SKILL.md 且 skill 名与 A 组白名单同名	保留 A 组 skill；C 组整个 skill 目录移到 _init-backup/
数据文件（如 pitfalls.md）用户明确说"保留"	跳过该文件重置
local-env.json 存在且用户说"我就在这台机器上开 B，保留它"	跳过删除，但提醒用户其已在 .gitignore
.cursor/rules/project/ 为空目录	保留空目录（便于未来放项目级 rules）
扫描到 .cursor/_init-backup/（上轮残留）	警告用户并询问：删除 / 保留 / 重命名
git status 不能执行（不是 git 仓库）	警告但不阻塞，改为建议用户手动备份

---

与其他系统的协作

系统	关系	说明
baserule.mdc	分类权威	阶段 2 归位目录严格按 baserule 约定
epee-orchestrator Skill	双向	本 Skill 被 Orchestrator 在 registry 里注册；同时本 Skill 负责清理 registry
dev-changelog / pitfall-journal / deferred-decisions / problem-distillery / profile-memory	下游数据主人	本 Skill 只在阶段 3 重置其数据文件，不改动 SKILL.md
local-env-check.mdc	后继	本 Skill 删除 local-env.json，后续新会话由 local-env-check 自动重新探测并生成
cursor-init-recall.mdc	触发器	负责匹配"初始化cursor"等关键词，引导 Agent 读取本 SKILL.md

---

一次运行的最终状态（验收标准）

运行结束后 .cursor/ 应当满足：

1. 规范清单中列出的所有文件/目录都存在
2. 所有数据文件（changelog/deferred/pitfalls/distillery/profile）仅含模板内容
3. .cursor/rules/project/ 为空目录
4. .cursor/skills/ 下仅有白名单中的 skill 目录
5. .cursor/skills/epee-orchestrator/registry.md 中只有：基础设施 + 个人级 skill 条目，且包含 cursor-init 条目
6. 不存在 *.log、local-env.json、_init-backup/（或 backup 已被用户确认保留/清理）
7. git status .cursor/ 能让用户清楚看到所有改动

---

自迭代日志

本节记录使用本 Skill 过程中发现的必要检查项。

已知必要检查

1. 阶段 2 的 C 组归位前必须先做 dry-run 展示 —— 批量移动 .mdc / SKILL 文件是高破坏性操作，只要有一条分类错误就会污染 canonical 结构，必须让用户在列表上逐条过一遍再执行。

2. 重名冲突不许直接覆盖 —— C 组与 A 组重名时，A 组（模板版本）永远是 source of truth，冲突文件只能进 _init-backup/，让用户自行决定是否把差异合并回 common rule。

3. registry 重建时先读后写 —— 阶段 4 不要直接用硬编码模板覆盖 registry.md，必须先解析现有条目，只移除项目级条目、补齐缺失条目，避免丢失用户自己添加的个人级 Skill 条目。