From 12be225242fb4c7a660dfa214a96d04c0dd71ebc Mon Sep 17 00:00:00 2001
From: "Shin@HOME" <shin.epee@live.com>
Date: Tue, 21 Apr 2026 11:13:57 +0800
Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9Ecursor=E5=88=9D=E5=A7=8B?=
 =?UTF-8?q?=E5=8C=96skill?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .cursor/rules/common/cursor-init-recall.mdc  |  31 ++
 .cursor/skills/cursor-init/SKILL.md          | 412 +++++++++++++++++++
 .cursor/skills/epee-orchestrator/registry.md |   8 +
 3 files changed, 451 insertions(+)
 create mode 100644 .cursor/rules/common/cursor-init-recall.mdc
 create mode 100644 .cursor/skills/cursor-init/SKILL.md

diff --git a/.cursor/rules/common/cursor-init-recall.mdc b/.cursor/rules/common/cursor-init-recall.mdc
new file mode 100644
index 0000000..d268128
--- /dev/null
+++ b/.cursor/rules/common/cursor-init-recall.mdc
@@ -0,0 +1,31 @@
+---
+description: 当用户要求初始化/重置 .cursor 目录（新项目首次落地模板）时，引导 Agent 读取 cursor-init Skill 并按其流程执行
+globs:
+alwaysApply: false
+---
+
+## .cursor 初始化触发
+
+当用户表达以下意图之一时，读取并执行 `cursor-init` Skill：
+
+**触发关键词**（匹配任意一条即可）：
+
+- "初始化cursor" / "初始化 cursor" / "cursor 初始化"
+- "重置 cursor" / "reset cursor"
+- "cursor init" / "init cursor"
+- "把复制过来的 .cursor 清理一下" / "按 baserule 归位一下"
+
+**执行方式**：
+
+1. 读取 `.cursor/skills/cursor-init/SKILL.md`
+2. 严格按 Skill 中的 0 → 6 阶段流程执行
+3. **稳定准确优先于 token 成本**：
+   - 破坏性操作（删除、重置、移动）前必须给用户 dry-run 清单
+   - 分类不清的文件必须逐条询问用户，不要猜
+   - 开始前先执行 `git status` 并提醒用户 commit/stash
+4. 本 Skill 预期在新项目生命周期中只运行一次，但设计为幂等——重复运行在已干净状态下不应造成破坏
+
+**不触发本 Skill 的情况**：
+
+- 用户只是问"cursor 有什么 skill"——这是浏览需求，走 `epee-orchestrator` 的操作 A
+- 用户只是想初始化某个具体数据文件（比如"初始化画像"）——这是对应 Skill 自己的流程（如 `profile-memory`），不涉及全局结构重置
diff --git a/.cursor/skills/cursor-init/SKILL.md b/.cursor/skills/cursor-init/SKILL.md
new file mode 100644
index 0000000..ed3b277
--- /dev/null
+++ b/.cursor/skills/cursor-init/SKILL.md
@@ -0,0 +1,412 @@
+---
+name: cursor-init
+description: >-
+  初始化新项目的 .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
+
+```markdown
+# Dev Changelog — Full
+
+完整的开发改动记录，按时间倒序排列。作为主动 RAG 的数据源，用户手动唤醒时读取。
+
+## 记录
+```
+
+### changelog-recent.md
+
+```markdown
+# Dev Changelog — Recent
+
+最近 ~10 次改动的摘要记录，按时间倒序排列。
+当 Agent 检测到当前任务与近期改动相关时自动读取。
+```
+
+### changelog-headlines.md
+
+```markdown
+# Dev Changelog — Headlines
+
+最近 ~50 次改动的一句话概要，按时间倒序排列。每次会话自动注入上下文。
+```
+
+### .changelog-ack
+
+空文件（0 字节），只用于更新 mtime 阻止 hook 重复提醒。
+
+### deferred/registry.md
+
+```markdown
+# Deferred Decisions Registry
+
+## Active Items
+
+（暂无延期方案）
+
+---
+
+## Completed / Cancelled Items
+
+（暂无已完成或已废弃的方案）
+```
+
+### pitfalls/pitfalls.md
+
+```markdown
+# Pitfall Journal
+
+开发过程中踩过的坑，按时间倒序排列。
+Agent 进入 Debug mode 或遇到运行时错误时自动检索匹配。
+
+---
+```
+
+### distillery/problems.md
+
+```markdown
+# Problem Distillery — Problems
+
+反复出现的顽固问题追踪记录，按时间倒序排列。
+
+<!-- 新条目追加在此行下方 -->
+```
+
+### distillery/insights.md
+
+```markdown
+# Problem Distillery — Insights
+
+从已解决的顽固问题中蒸馏出的精炼方法论。
+
+<!-- 新条目追加在此行下方 -->
+
+---
+last_distill_date: {{DATE}}
+```
+
+### distillery/golden-rules.md
+
+```markdown
+# Golden Rules
+
+经过实践验证（权重 >= 5）的精炼认知，每次新会话自动注入。
+
+<!-- 当条目达到权重阈值后由 Agent 自动写入 -->
+```
+
+### profile/project-profile.md
+
+```markdown
+# Project Profile
+
+## 项目定位
+
+## 技术栈与架构
+
+## 设计约定
+
+## 产品方向
+```
+
+### profile/project-profile-log.md
+
+```markdown
+# 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 条目。
diff --git a/.cursor/skills/epee-orchestrator/registry.md b/.cursor/skills/epee-orchestrator/registry.md
index 0597a97..14e9a02 100644
--- a/.cursor/skills/epee-orchestrator/registry.md
+++ b/.cursor/skills/epee-orchestrator/registry.md
@@ -17,6 +17,14 @@
 
 ## 已注册 Skill
 
+### cursor-init
+- **类型**: 基础设施
+- **能力**: 把从其它项目复制过来的 .cursor/ 重置为新项目的干净起点——按 baserule 归位目标项目原有的 rules/skills，清理源项目的项目专用数据，重建干净的 registry
+- **触发场景**: "初始化cursor"、"cursor 初始化"、"重置 cursor"、"cursor init"、"init cursor"、"reset cursor"、"按 baserule 归位"、新项目首次落地 .cursor 模板
+- **输出**: 重置/清理后的 `.cursor/` 结构（规范清单完整、项目级内容已清、数据文件为模板、registry 仅含通用条目）
+- **路径**: .cursor/skills/cursor-init/SKILL.md
+- **备注**: 每个新项目一次性运行，破坏性操作必须 dry-run；由 `cursor-init-recall.mdc` 触发；设计为幂等，重复运行无害
+
 ### deferred-decisions
 - **类型**: 基础设施
 - **能力**: 记录和追踪延期的技术方案/决策，在关联任务出现时主动提醒