claude init inited

.claude/skills/claude-init/SKILL.md

@@ -0,0 +1,844 @@
+---
+name: claude-init
+description: Initializes the .claude structure for a new project. Two trigger paths - (1) auto on first session when .claude/.init-done is missing, (2) manual via keywords like "初始化claude", "claude init", "重置 claude", "补 gitignore". Identifies and relocates target project's original rules/skills, cleans template residue (changelog/deferred/pitfalls/profile/distillery/local settings/project-level rules and skills), optionally generates .gitignore, and writes .claude/.init-done sentinel on completion. Already-initialized repos skip auto-trigger unless user invokes keywords.
+---
+
+# Claude Init Skill
+
+把从其它项目复制过来（或通过 git clone 模板仓库获得）的 `.claude/` 目录重置为当前新项目的干净起点。
+
+## 使用场景
+
+### 场景 A：克隆模板仓库后的首次会话
+
+```
+1. 用户把本模板作为 git 仓库发布
+2. 其他人 `git clone <模板仓库>` 得到新项目骨架
+3. 用户打开 Claude Code，在该仓库发出任意第一条消息
+4. `claude-init-recall.md`（alwaysApply）检测 .claude/.init-done 不存在
+   → 引导 Agent 暂停用户原始请求，先执行本 Skill
+5. Agent 按阶段 0 → 7 跑完，写入 .init-done
+6. 后续会话 sentinel 已存在，不再自动触发
+```
+
+### 场景 B：从已有项目直接复制 .claude 目录
+
+```
+1. 用户在 "源项目 A" 中使用本 .claude 模板开发
+2. 用户开 "新项目 B"，把 A 的 .claude/ 整体拷贝到 B
+3. B 原先可能也有自己零散的 rules/SKILL 文件（未必标准）
+4. 用户在 B 中说"初始化claude"（或首次会话被 recall 触发）
+5. 本 Skill 把 B 原有的 rules/skills 按 baserule 归位，清空 A 遗留的项目数据，
+   生成 .gitignore，写入 sentinel
+```
+
+### 场景 C：只补 .gitignore
+
+```
+init 后用户说"补一下 gitignore"或"生成 gitignore" → 只跑阶段 5.5
+```
+
+## 触发条件
+
+本 Skill 由 `claude-init-recall.md` 触发，两类入口：
+
+### A. 全流程（阶段 0 → 7）
+
+- `.claude/.init-done` 不存在 → 会话首次响应前由 recall 规则自动引导
+- 用户关键词：`初始化claude` / `claude init` / `重置 claude` / `reset claude` 等
+- 口头描述"把复制过来的 .claude 清理一下"、"按 baserule 归位一下"
+
+### B. 仅补 .gitignore（只跑阶段 5.5）
+
+- 用户关键词：`补 gitignore` / `生成 gitignore` / `gitignore 模板`
+- 跳过阶段 1-5 和阶段 7 的除"更新 gitignore_generated 字段"外的其他操作
+
+## 执行原则（不可协商）
+
+1. **稳定准确 > token 成本**：每一步可以多读、多确认、让用户点头，不要图快
+2. **破坏性操作必须 dry-run**：删除、重置必须先列清单给用户确认
+3. **不可逆操作前提醒 git**：开始前先提示用户确认工作区已 commit/stash
+4. **模糊就问**：分类不清的文件一律问用户，不要猜
+5. **幂等**：反复运行应当无害（第二次在已干净状态下不会做破坏）
+6. **中断可恢复**：任何阶段异常 abort **不写入** `.init-done`，下次会话仍会被 recall 触发从头继续
+
+## 核心流程
+
+### 阶段 0：前置确认 + 幂等判断
+
+```
+1. 检查当前工作目录下存在 .claude/
+   - 不存在 → 直接结束，提示用户先复制模板
+2. 读取 .claude/.init-done
+   - 不存在 → 继续，按"首次 init"路径执行
+   - 已存在 → 展示其元数据（initialized_at、project_type 等），提示：
+     "检测到本仓库已于 {initialized_at} 完成初始化（project_type: {type}）。
+      继续执行会清空 changelog / deferred / pitfalls / distillery 等数据文件。确认要继续吗？"
+     等用户明确回复"继续"再往下
+3. 运行 `git status`：
+   - 不是 git 仓库 → 警告但不阻塞，建议手动备份
+   - 有未提交改动 → 提醒"建议先 commit 或 stash，便于回滚"，等用户明确回复"继续"
+4. 向用户声明本次操作范围（见"分组规则"），请求口头确认启动
+```
+
+### 阶段 1：递归扫描 `.claude/`
+
+```
+1. 用 shell 列出 .claude 下所有文件（含子目录）
+2. 把每个文件对照"规范清单"和"清理清单"分成三组：
+   - A 组（canonical）：在规范清单中，原样保留
+   - B 组（template-data）：在清理清单中，需要删除或重置
+   - C 组（foreign）：两张清单都没覆盖到的，视作目标项目原有文件或未知项
+3. 把分组结果用表格汇报给用户：
+   | 组 | 路径 | 处理动作 |
+```
+
+### 阶段 2：处理 C 组（目标项目原有文件归位）
+
+对 C 组中的每个文件，按 baserule.md 的归属约定分类，逐条询问用户（可一次性列清单批量确认）：
+
+| 文件特征 | 建议归属 | 目标路径 |
+|----------|----------|----------|
+| `.md`/`.mdc` 且内容是跨项目通用规则 | 通用 Rule | `.claude/rules/common/<name>.md` + CLAUDE.md 追加 @import |
+| `.md`/`.mdc` 且内容是当前新项目专属规则 | 项目 Rule | `.claude/rules/project/<name>.md` + CLAUDE.md 追加 @import |
+| 包含 `SKILL.md` 的目录 | Skill（无论通用/项目专属） | `.claude/skills/<skill-name>/` |
+| 看不出归属 | 询问用户 | — |
+| 明显是临时/垃圾文件（`*.log`、`*.tmp`、缓存等） | 删除（需用户确认） | — |
+
+执行要点：
+
+- **先列清单一次性确认**，然后批量执行移动/删除，避免交互过于频繁
+- **重名冲突**：C 组文件若与 A 组规范文件重名，**保留 A 组版本**，把 C 组备份到 `.claude/_init-backup/` 下让用户自行 diff，不直接覆盖
+- **Skill 归属提示**：通用 Skill 建议用户之后手动同步到 `~/.claude/skills/`（跨项目便利副本，可选）
+- **迁移后核查**：移动完成后重新扫描，确认 C 组已清空
+- **CLAUDE.md 同步**：任何移到 `rules/common/` 或 `rules/project/` 的 rule 文件都必须在 `CLAUDE.md` 对应段追加 `@import` 语句
+
+### 阶段 3：处理 B 组（源项目项目专用数据清理/重置）
+
+按"清理清单"执行：
+
+**A. 直接删除**
+
+- `.claude/rules/project/*.md`（全部）—— 源项目的项目级 rules，新项目不适用。**同时清理 `CLAUDE.md` 中对应的 `@rules/project/...` 引用行**
+- `.claude/skills/<非规范 skill 目录>/` —— 源项目的项目级 Skills（不在白名单的所有 skill 目录）
+- `.claude/plans/` 下所有文件（目录保留，内容清空；若目录不存在则跳过）
+- `.claude/debug-*.log`、`.claude/*.log` —— 调试日志
+- `.claude/settings.local.json` —— 设备绑定，需新设备重新生成
+- `.claude/.pending-init` —— 由 session-init Hook 创建的标记文件（若存在）
+
+**B. 重置为空模板**（保留文件，仅清内容）
+
+| 文件 | 模板（见"模板内容"节） |
+|------|------------------------|
+| `.claude/changelog/changelog-full.md` | L1 模板 |
+| `.claude/changelog/changelog-recent.md` | L2 模板 |
+| `.claude/changelog/changelog-headlines.md` | L3 模板 |
+| `.claude/changelog/.changelog-ack` | 空文件（touch） |
+| `.claude/deferred/registry.md` | deferred 模板 |
+| `.claude/pitfalls/pitfalls.md` | pitfalls 模板 |
+| `.claude/distillery/problems.md` | problems 模板 |
+| `.claude/distillery/insights.md` | insights 模板 |
+| `.claude/distillery/golden-rules.md` | golden-rules 模板 |
+| `.claude/profile/project-profile.md` | project-profile 模板 |
+| `.claude/profile/project-profile-log.md` | project-profile-log 模板 |
+
+执行要点：
+
+- 每个重置前**先 Read 现有内容预览前 10 行**给用户，避免误删有价值数据（特别是 deferred/pitfalls 用户可能想保留）
+- 如用户对某个数据文件明确说"保留"（例如 golden-rules 想带过去），跳过该文件的重置
+
+### 阶段 4：重建 registry
+
+打开 `.claude/skills/epee-orchestrator/registry.md`：
+
+1. 解析现有条目（每条 `### <skill-name>` 块）
+2. 删除所有 `类型: 项目级` 的条目
+3. 遍历 `.claude/skills/` 目录，对照 registry：
+   - registry 有条目但 skill 目录不存在 → 删除条目
+   - skill 目录存在但 registry 无条目 → 读取该 skill 的 SKILL.md frontmatter，新增条目
+4. **确保 `claude-init` 条目本身存在**（类型: 基础设施）
+5. 写回 registry.md
+
+### 阶段 5：同步 `settings.json`（跨平台保守处理）
+
+- 读取 `.claude/settings.json`
+- 若 `hooks` 字段中 `command` 硬编码为 `powershell ...`，且目标新项目声明/探测到的 shell 不是 powershell，**提醒用户**需要按 `hooks/README.md` 手动改为 `bash .claude/hooks/xxx.sh`
+- 本阶段不自动改 settings.json，避免误判
+
+### 阶段 5.5：`.gitignore` 交互式生成
+
+#### 5.5.1 前置检测
+
+```
+检测项目根 .gitignore：
+  不存在        → 进入 5.5.2 问卷
+  已存在且非空  → Read 前 30 行展示给用户，询问：
+                  [覆盖 / 追加到文件末尾 / 跳过本阶段]
+  用户选"跳过"  → 本阶段结束，.init-done 里标记 gitignore_generated: false
+```
+
+#### 5.5.2 问卷（一次性批量 AskUserQuestion 收集）
+
+必问 3 项 + 可选 1 项：
+
+| 编号 | 问题 | 类型 | 选项 |
+|------|------|------|------|
+| Q1 | 项目主要技术栈 | 多选 | Unity / Node.js / Python / Rust / Go / C# 非 Unity / Web 静态站点 / 其他 / **不确定（跳过语言段）** |
+| Q2 | IDE 偏好 | 多选 | Cursor / VSCode / JetBrains 全家桶 / Visual Studio / Vim+Emacs |
+| Q3 | 操作系统 | 多选 | Windows / macOS / Linux（按探测到的当前 OS 预勾） |
+| Q4（可选）| 其他要忽略的路径 | 自由文本 | 用户可跳过 |
+
+#### 5.5.3 片段组装
+
+按问卷选择拼装，片段内容见下方"模板内容 · .gitignore 片段库"。拼装顺序固定：
+
+```
+# === Claude（固定，所有项目都包含） ===
+# === OS ===
+# === IDE ===
+# === Language / Framework ===
+# === Custom ===
+```
+
+若 Q1 选"不确定" → 跳过 Language 段，其他段正常拼装（极简版仍可用）。
+
+#### 5.5.4 预览与确认
+
+1. 把组装结果写到 `.claude/_gitignore-preview`（临时文件）
+2. 给用户完整展示（超过 60 行则折叠中段）
+3. AskUserQuestion：`[写入 .gitignore / 让我调整再确认 / 放弃本阶段]`
+4. "写入"→ move 到项目根 `.gitignore`（已存在时按 5.5.1 的选择做覆盖或追加），删除预览文件
+5. "调整"→ 根据用户描述修改后重复步骤 2-3
+6. "放弃"→ 删除预览文件，`.init-done` 标记 `gitignore_generated: false`
+
+### 阶段 6：验证与报告
+
+```
+1. 重新递归扫描 .claude/，再次分组
+2. 期望状态：
+   - A 组：全部保留，文件内容未被动过
+   - B 组：数据文件仅含模板内容；项目级 rules/skills/日志 已删除
+   - C 组：为空（或仅剩用户明确要求保留的文件）
+   - 项目根 .gitignore：按用户选择存在或被放弃（状态记到报告里）
+   - CLAUDE.md：@import 引用与实际 rules 目录内容一致
+3. 给用户一份结构化报告，至少包含：
+   - 移动的文件（from → to）
+   - 删除的文件
+   - 重置的文件
+   - CLAUDE.md 中新增/删除的 @import 行
+   - .gitignore 的处理结果（新建/追加/覆盖/放弃）
+   - 未处理的文件（如果有，逐条说明原因）
+```
+
+### 阶段 7：写入 `.init-done` sentinel
+
+**仅在阶段 6 验证全部通过后执行**。任何前序阶段异常中断都不写入此文件，确保下次会话 recall 能再次触发。
+
+```
+1. 按"模板内容 · .init-done"格式，填充实际值写入 .claude/.init-done
+2. 删除 .claude/.pending-init（由 session-init Hook 创建，sentinel 存在后不再需要）
+3. 向用户输出收尾提示：
+   > 初始化完成。建议现在执行：
+   >   git add .claude/ .gitignore
+   >   git diff --cached -- .claude/
+   >   git commit -m "chore(claude): initialize .claude from template"
+   >
+   > ⚠️ .claude/.init-done 必须 commit，否则团队其他成员 clone 后会被再次触发 init。
+```
+
+**仅跑阶段 5.5 时**（用户说"补 gitignore"）：
+- 若 `.init-done` 存在 → 更新其中的 `gitignore_generated: true` 字段，保留其他字段
+- 若 `.init-done` 不存在 → 提示用户"仓库尚未完整 init，只补 gitignore 不会写 sentinel。是否改为跑完整 init？"
+
+---
+
+## 规范清单（canonical）
+
+下列文件构成本 `.claude` 模板的"主干"，初始化后必须都在、内容不被删改（数据文件除外）：
+
+### 顶层
+
+- `.claude/CLAUDE.md`
+- `.claude/settings.json`
+- `.claude/settings.local.example.json`
+- `.claude/.init-done` —— **阶段 7 写入**；模板仓库自身不应包含此文件
+
+### Rules（通用）
+
+- `.claude/rules/common/baserule.md`
+- `.claude/rules/common/claude-init-recall.md`
+- `.claude/rules/common/changelog-recall.md`
+- `.claude/rules/common/deferred-recall.md`
+- `.claude/rules/common/distillery-recall.md`
+- `.claude/rules/common/epee-orchestrator.md`
+- `.claude/rules/common/pitfall-recall.md`
+- `.claude/rules/common/profile-recall.md`
+
+### Rules（项目专属目录）
+
+- `.claude/rules/project/`（保留**空目录**；源项目的 `.md` 内容一律删除）
+
+### Skills（规范 Skill 目录白名单）
+
+- `.claude/skills/claude-init/`
+- `.claude/skills/deferred-decisions/`
+- `.claude/skills/dev-changelog/`
+- `.claude/skills/epee-orchestrator/`（含 `registry.md`，见阶段 4）
+- `.claude/skills/pitfall-journal/`
+- `.claude/skills/problem-distillery/`
+- `.claude/skills/profile-memory/`
+
+> **任何不在此白名单中的 skill 目录**，在阶段 3 中一律删除（视为源项目的项目级 Skill）。
+
+### Hooks
+
+- `.claude/hooks/README.md`
+- `.claude/hooks/run-hook.ps1`
+- `.claude/hooks/session-init.ps1`
+- `.claude/hooks/session-init.sh`
+- `.claude/hooks/check-changelog.ps1`
+- `.claude/hooks/check-changelog.sh`
+
+### 数据占位目录（保留目录，文件重置为模板内容）
+
+- `.claude/changelog/{changelog-full.md, changelog-recent.md, changelog-headlines.md, .changelog-ack}`
+- `.claude/deferred/registry.md`
+- `.claude/pitfalls/pitfalls.md`
+- `.claude/distillery/{problems.md, insights.md, golden-rules.md}`
+- `.claude/profile/{project-profile.md, project-profile-log.md}`
+- `.claude/plans/`（空目录）
+
+---
+
+## 清理清单（cleanup list）
+
+### 强制删除
+
+| 路径 | 原因 |
+|------|------|
+| `.claude/rules/project/*.md` | 源项目的项目级 Rules |
+| `.claude/skills/<非白名单>/` | 源项目的项目级 Skills |
+| `.claude/plans/*`（内容） | 源项目规划文档（若目录存在） |
+| `.claude/*.log`、`.claude/debug-*.log` | 调试日志遗留 |
+| `.claude/settings.local.json` | 设备绑定配置，需由新设备重新生成 |
+| `.claude/local-env.json` | 设备绑定配置，需由新设备重新生成 |
+| `.claude/_init-backup/`（如果是上一轮残留） | 仅阶段 2 冲突备份用，运行前应不存在 |
+| `.claude/_gitignore-preview`（如果是上一轮残留） | 阶段 5.5 临时文件 |
+
+### CLAUDE.md 同步清理
+
+阶段 3A 删除 `rules/project/*.md` 后，必须打开项目根 `CLAUDE.md`，移除其中引用的
+`@rules/project/...` 行。保留"项目专属规则"段标题和注释占位，方便用户后续新增。
+
+### 重置为模板
+
+见"模板内容"节。
+
+---
+
+## 模板内容
+
+重置数据文件时使用以下内容。带 `{{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
+
+详细记录每次项目画像更新的完整上下文，按时间正序追加。
+
+## 记录
+```
+
+### .init-done
+
+阶段 7 写入的 sentinel，YAML 格式，字段固定：
+
+```yaml
+# .claude/.init-done — claude-init Skill 写入的初始化标记文件
+# 本文件的存在表示本仓库已完成 .claude 模板初始化
+# 请务必 git commit 此文件，避免团队成员 clone 后被再次触发 init
+initialized_at: {{ISO_DATETIME}}      # 如 2026-04-23T16:30:00+08:00
+initialized_by: claude-init
+skill_version: 2
+project_type: {{PROJECT_TYPE}}        # 阶段 5.5 问卷 Q1 结果；多选逗号分隔；"不确定"写 unknown
+gitignore_generated: {{BOOL}}         # true / false
+```
+
+**写入时机**：
+- 全流程跑完（阶段 6 验证通过）时由阶段 7 写入
+- "补 gitignore" 单独跑阶段 5.5 时，若已存在则只更新 `gitignore_generated` 字段
+
+---
+
+## 模板内容 · .gitignore 片段库
+
+阶段 5.5 按用户问卷选择拼接以下片段。每段前后各空一行，保证可读性。
+
+### 固定段：Claude
+
+```gitignore
+# === Claude ===
+# 设备绑定配置，不同机器需独立生成
+.claude/settings.local.json
+
+# Hook 运行态标记（仅影响本地会话）
+.claude/changelog/.changelog-ack
+
+# claude-init 临时产物
+.claude/_init-backup/
+.claude/_gitignore-preview
+```
+
+### OS 段（按问卷 Q3 多选拼接）
+
+**Windows**
+
+```gitignore
+# === OS: Windows ===
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+Desktop.ini
+$RECYCLE.BIN/
+*.stackdump
+*.lnk
+```
+
+**macOS**
+
+```gitignore
+# === OS: macOS ===
+.DS_Store
+.AppleDouble
+.LSOverride
+Icon
+._*
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+```
+
+**Linux**
+
+```gitignore
+# === OS: Linux ===
+*~
+.fuse_hidden*
+.directory
+.Trash-*
+.nfs*
+```
+
+### IDE 段（按问卷 Q2 多选拼接）
+
+**Cursor**
+
+```gitignore
+# === IDE: Cursor ===
+.cursor/local-env.json
+.cursor/_init-backup/
+.cursor/_gitignore-preview
+```
+
+**VSCode**
+
+```gitignore
+# === IDE: VSCode ===
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+.history/
+*.vsix
+```
+
+**JetBrains**
+
+```gitignore
+# === IDE: JetBrains ===
+.idea/
+*.iml
+*.ipr
+*.iws
+.idea_modules/
+atlassian-ide-plugin.xml
+```
+
+**Visual Studio**
+
+```gitignore
+# === IDE: Visual Studio ===
+.vs/
+*.user
+*.suo
+*.userprefs
+bin/
+obj/
+[Dd]ebug/
+[Rr]elease/
+x64/
+x86/
+```
+
+**Vim/Emacs**
+
+```gitignore
+# === IDE: Vim / Emacs ===
+*.swp
+*.swo
+*.swn
+Session.vim
+.netrwhist
+*~
+\#*\#
+.\#*
+```
+
+### Language / Framework 段（按问卷 Q1 多选拼接）
+
+**Unity**
+
+```gitignore
+# === Language: Unity ===
+[Ll]ibrary/
+[Tt]emp/
+[Oo]bj/
+[Bb]uild/
+[Bb]uilds/
+[Ll]ogs/
+[Uu]ser[Ss]ettings/
+[Mm]emoryCaptures/
+[Rr]ecordings/
+sysinfo.txt
+*.apk
+*.aab
+*.unitypackage
+*.app
+*.csproj
+*.unityproj
+*.sln
+*.suo
+*.tmp
+*.user
+*.userprefs
+*.pidb
+*.booproj
+*.svd
+*.pdb
+*.mdb
+*.opendb
+*.VC.db
+```
+
+**Node.js**
+
+```gitignore
+# === Language: Node.js ===
+node_modules/
+.npm/
+.yarn/
+.pnp.*
+dist/
+build/
+out/
+.next/
+.nuxt/
+.cache/
+.parcel-cache/
+coverage/
+.env
+.env.local
+.env.*.local
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.turbo/
+```
+
+**Python**
+
+```gitignore
+# === Language: Python ===
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+.venv/
+venv/
+env/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+.hypothesis/
+.ipynb_checkpoints/
+```
+
+**Rust**
+
+```gitignore
+# === Language: Rust ===
+target/
+**/*.rs.bk
+*.pdb
+# Cargo.lock：lib crate 建议忽略，bin crate 建议提交，默认不忽略
+# Cargo.lock
+```
+
+**Go**
+
+```gitignore
+# === Language: Go ===
+bin/
+vendor/
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+go.work
+```
+
+**C# 非 Unity**
+
+```gitignore
+# === Language: C# (non-Unity) ===
+bin/
+obj/
+*.user
+*.suo
+*.pdb
+*.cache
+[Dd]ebug/
+[Rr]elease/
+x64/
+x86/
+[Bb]uild/
+*.dll
+*.pdb
+```
+
+**Web 静态站点**
+
+```gitignore
+# === Language: Web Static ===
+node_modules/
+dist/
+build/
+public/build/
+.cache/
+.tmp/
+.sass-cache/
+.parcel-cache/
+```
+
+**其他**：不拼接语言段，用户在 `# === Custom ===` 段自行补充。
+
+### Custom 段（固定尾部）
+
+```gitignore
+# === Custom ===
+# 在此段追加项目专属需要忽略的路径
+```
+
+若用户在问卷 Q4 填了自由文本，按行拆分后追加到 Custom 段下方。
+
+---
+
+## 冲突与边界情况处理
+
+| 场景 | 处理 |
+|------|------|
+| C 组某文件与 A 组重名 | 保留 A 组；C 组移到 `.claude/_init-backup/`，告知用户自行 diff |
+| C 组有 `SKILL.md` 且 skill 名与 A 组白名单同名 | 保留 A 组 skill；C 组整个 skill 目录移到 `_init-backup/` |
+| 数据文件用户明确说"保留" | 跳过该文件重置 |
+| `settings.local.json` 存在且用户说"我就在这台机器上开 B，保留它" | 跳过删除，但执行以下校验：1) 扫描文件中所有绝对路径（如 `D:/GIT_HOME/xxx`、`/home/user/xxx`），与当前工作目录比对；2) 路径不一致的逐条列出并提醒用户修正；3) 提醒该文件已在 `.gitignore` 中 |
+| `.claude/rules/project/` 为空目录 | 保留空目录（便于未来放项目级 rules） |
+| 扫描到 `.claude/_init-backup/`（上轮残留） | 警告用户并询问：删除 / 保留 / 重命名 |
+| `git status` 不能执行（不是 git 仓库） | 警告但不阻塞，改为建议用户手动备份 |
+| `.claude/.init-done` 已存在且用户触发了全流程 | 阶段 0 展示其元数据并要求二次确认 |
+| 阶段 5.5 项目根已有 `.gitignore` 且用户选"追加" | 把拼装结果追加到现有文件末尾（用 `\n\n# --- 以下由 claude-init 追加 ---\n` 分隔） |
+| 阶段 5.5 中途异常或用户放弃 | 不写入 `.gitignore`，`.init-done` 的 `gitignore_generated` 记 false |
+| 阶段 7 写 `.init-done` 前前序阶段已 abort | 不写入 sentinel，下次会话 recall 会重新触发 |
+| 用户说"补 gitignore" 但 `.init-done` 不存在 | 提醒"仓库尚未完整 init"，询问是否改为跑全流程 |
+
+---
+
+## 与其他系统的协作
+
+| 系统 | 关系 | 说明 |
+|------|------|------|
+| `baserule.md` | 分类权威 | 阶段 2 归位目录严格按 baserule 约定 |
+| `claude-init-recall.md` | 触发器 | 负责首次自动触发（alwaysApply + sentinel 检查）和关键词触发 |
+| `CLAUDE.md` | 双向依赖 | 阶段 2/3 要同步更新主文件的 `@import` 引用行 |
+| `epee-orchestrator` Skill | 双向 | 本 Skill 被 Orchestrator 在 registry 里注册；同时本 Skill 负责清理 registry |
+| `dev-changelog` / `pitfall-journal` / `deferred-decisions` / `problem-distillery` / `profile-memory` | 下游数据主人 | 本 Skill 只在阶段 3 重置其数据文件，不改动 SKILL.md |
+| `settings.local.json` | 后继 | 本 Skill 删除此文件，后续由用户参照 example 手工生成 |
+
+---
+
+## 一次运行的最终状态（验收标准）
+
+全流程（阶段 0 → 7）完成后 `.claude/` 应当满足：
+
+1. 规范清单中列出的所有文件/目录都存在
+2. 所有数据文件（changelog/deferred/pitfalls/distillery/profile）仅含模板内容
+3. `.claude/rules/project/` 为空目录
+4. `.claude/skills/` 下仅有白名单中的 skill 目录
+5. `.claude/skills/epee-orchestrator/registry.md` 中只有：基础设施 + 个人级 skill 条目，且包含 `claude-init` 条目
+6. 不存在 `*.log`、`settings.local.json`、`local-env.json`、`_init-backup/`、`_gitignore-preview`
+7. `CLAUDE.md` 中的 `@import` 引用与实际 rules 目录内容一致（不含已删除的 project rules）
+8. `.claude/.init-done` 已写入，字段完整且值有效
+9. 项目根 `.gitignore` 状态明确（存在且有内容 / 被用户显式放弃）
+10. `git status .claude/ .gitignore` 能让用户清楚看到所有改动
+
+仅跑阶段 5.5（"补 gitignore"）完成后：
+
+1. 项目根 `.gitignore` 存在或被显式放弃
+2. 若 `.init-done` 已存在，其 `gitignore_generated` 字段被更新
+3. 其他 `.claude/` 内容**零改动**
+
+---
+
+## 自迭代日志
+
+本节记录使用本 Skill 过程中发现的必要检查项。
+
+### 已知必要检查
+
+1. **阶段 2 的 C 组归位前必须先做 dry-run 展示** —— 批量移动 .md / SKILL 文件是高破坏性操作，只要有一条分类错误就会污染 canonical 结构，必须让用户在列表上逐条过一遍再执行。
+
+2. **重名冲突不许直接覆盖** —— C 组与 A 组重名时，A 组（模板版本）永远是 source of truth，冲突文件只能进 `_init-backup/`，让用户自行决定是否把差异合并回 common rule。
+
+3. **`.init-done` 是完成度契约** —— 只有阶段 6 验证通过后才能写入此文件。中途 abort 必须让 sentinel 缺失，这是保证下次会话能恢复触发的关键设计。
+
+4. **`.gitignore` 用户主导** —— 阶段 5.5 对语言栈/IDE/OS 的判断完全来自用户问卷，不要根据文件探测"智能推断"，因为新项目此时通常还是空白，推断不准反而会填错条目。
+
+5. **`CLAUDE.md` 是 Rule 触发的入口** —— 与 Cursor 不同，Claude Code 的 rules 不会因为 `alwaysApply: true` frontmatter 而自动注入——必须通过 `CLAUDE.md` 的 `@import` 引入。任何对 `rules/common/` 或 `rules/project/` 目录的增删都必须同步更新 `CLAUDE.md`。
+
+6. **保留 `settings.local.json` 时必须校验路径** —— 用户选择保留该文件时，必须扫描其中所有绝对路径（通常出现在 `permissions.allow` 的 Bash 命令中），与当前项目根目录比对。路径不一致的逐条列出提醒用户修正。此检查防止从模板 clone 后路径指向错误项目。

.claude/skills/deferred-decisions/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: deferred-decisions
+description: >-
+  Records deferred technical decisions and proactively reminds the user when related tasks arise.
+  Triggers when the conversation contains semantics like "以后再做", "先不做", "defer",
+  "延期方案", "备选方案", "递进方案". Also used for browsing and managing existing deferred items.
+---
+
+# Deferred Decisions Skill
+
+追踪开发中被延期的技术方案，在合适时机主动提醒用户。
+
+## 存储
+
+**数据文件**: `.claude/deferred/registry.md`
+
+该文件是 Agent 的结构化记忆，不是面向人类的文档。每个 deferred item 是一个 H3 级标题块。
+
+## 操作 A：记录延期方案
+
+### 触发识别
+
+当对话中出现以下模式时，Agent 应主动提议记录：
+- 讨论了多种方案，选择了一种，明确说其余"以后再做"
+- 实现了基础版本，提到了可递进升级的高级版本
+- 发现了可以改进的点，但当前优先级不够
+
+### 流程
+
+```
+1. 从对话中提炼：
+   - 选择了什么方案（chosen_alternative）
+   - 延期了什么（标题 + context）
+   - 为什么延期（deferred_reason）
+   - 什么时候可以做（prerequisite）
+   - 涉及哪些领域（tags）和文件（related_files）
+2. 生成 slug 形式的唯一 ID（如 ecosystem-lod-switching）
+3. 读取 .claude/deferred/registry.md（不存在则用模板创建）
+4. 在 "## Active Items" 区域末尾、"---" 分隔线之前追加新条目
+5. 向用户确认已记录，展示条目摘要
+```
+
+### 条目模板
+
+```markdown
+### [item-slug] 简短标题
+- **status**: deferred
+- **tags**: tag1, tag2, tag3
+- **recorded**: YYYY-MM-DD
+- **source_chat**: [简短描述](chat-uuid)
+- **prerequisite**: 实施前提条件（可选，无则写 "无"）
+- **related_files**:
+  - path/to/file1.cs
+  - path/to/file2.cs
+- **context**: |
+    延期方案的具体内容，2-5 行描述。
+    包含方案的要点和实施思路。
+- **chosen_alternative**: 当时选择的方案简述
+- **deferred_reason**: 延期的原因
+```
+
+### 字段说明
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| ID（方括号内） | 是 | slug 形式，全局唯一 |
+| status | 是 | `deferred` / `reminded` / `in_progress` / `done` / `cancelled` |
+| tags | 是 | 逗号分隔的领域标签，用于关联匹配 |
+| recorded | 是 | 记录日期 |
+| source_chat | 否 | 来源对话标识 |
+| prerequisite | 否 | 实施前提条件 |
+| related_files | 否 | 关联代码文件路径 |
+| context | 是 | 延期方案的具体内容 |
+| chosen_alternative | 是 | 当时选择了什么 |
+| deferred_reason | 是 | 延期原因 |
+
+## 操作 B：关联提醒
+
+### 触发条件
+
+由 `.claude/rules/common/deferred-recall.md` 触发，或当用户任务涉及已有 deferred item 的领域时自动触发。
+
+### 流程
+
+```
+1. 读取 .claude/deferred/registry.md
+2. 提取当前任务的关键词和涉及文件
+3. 匹配 status=deferred 的 items：
+   - tags 与当前任务关键词有交集
+   - related_files 与当前任务涉及文件有重叠
+   - prerequisite 描述的条件可能已满足
+4. 如匹配到，在回复开头简要提醒：
+   "提醒：你之前有一个延期方案 [item-title] 与当前任务相关。要一并处理吗？"
+5. 如用户同意，将该 item 的 status 改为 in_progress
+```
+
+### 提醒原则
+
+- 每个 item 在同一会话中最多提醒一次
+- 只提醒 status=deferred 的 items（reminded/in_progress 不重复提醒）
+- 提醒应简洁，不打断用户的主线任务
+
+## 操作 C：状态管理
+
+| 用户动作 | 状态变更 | 额外操作 |
+|---|---|---|
+| "开始做 X" | deferred → in_progress | 无 |
+| "X 完成了" | in_progress → done | 移到 "Completed / Cancelled Items" 区域 |
+| "X 不需要了" | any → cancelled | 移到 "Completed / Cancelled Items" 区域 |
+| Agent 提醒后用户确认 | deferred → in_progress | 无 |
+
+### 移动条目
+
+将条目从 "Active Items" 剪切到 "Completed / Cancelled Items" 区域时，保留完整内容，仅修改 status。
+
+## 操作 D：浏览/回顾
+
+当用户问"有哪些延期方案"、"deferred list"、"待办方案"等时：
+
+```
+1. 读取 registry.md
+2. 列出所有 status=deferred 的 items 摘要表：
+   | ID | 标题 | Tags | 记录日期 | 前提条件 |
+3. 如用户要求按 tag 过滤，只展示匹配项
+```
+
+## Registry 文件模板
+
+当 `.claude/deferred/registry.md` 不存在时，用此模板创建：
+
+```markdown
+# Deferred Decisions Registry
+
+## Active Items
+
+（暂无延期方案）
+
+---
+
+## Completed / Cancelled Items
+
+（暂无已完成或已废弃的方案）
+```
+
+## 自迭代日志
+
+本节记录使用本 Skill 过程中发现的必要检查项。
+
+### 已知必要检查
+
+（暂无）

.claude/skills/dev-changelog/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: dev-changelog
+description: >-
+  三层开发进程记录系统。在 Agent 完成代码改动后自动记录，提供从一句话概要到完整日志的
+  多级上下文，帮助 Agent 在跨会话场景下保持对项目开发进展的感知。
+  当用户提到"开发日志"、"changelog"、"最近改了什么"、"回顾改动"等时触发。
+---
+
+# Dev Changelog
+
+三层开发进程记录系统，解决 Agent 跨会话的上下文断裂问题。
+
+## 三层架构
+
+| 层级 | 文件 | 信息密度 | 条目数量 | 注入方式 |
+|------|------|---------|---------|---------|
+| L1 完整版 | `changelog-full.md` | 高（5-15 行/条） | 无上限，只追加 | 用户手动唤醒 |
+| L2 中期版 | `changelog-recent.md` | 中（3-5 行/条） | 滚动窗口 ~20 条 | 检测到关联时自动读取 |
+| L3 概要版 | `changelog-headlines.md` | 低（1 行/条） | 滚动窗口 ~50 条 | 每次会话自动注入 |
+
+所有数据文件存放在 `.claude/changelog/` 目录下。
+
+## 锚点 ID 机制
+
+每条记录在写入时生成一个**锚点 ID**，格式为 `CL-YYYYMMDD-HHMM`（如 `CL-20260424-1430`）。
+同一分钟内有多条时追加字母后缀（`CL-20260424-1430a`、`CL-20260424-1430b`）。
+
+锚点 ID 在三层文件中保持一致，用于跨层精准定位：
+- L3 一句话条目以 `[CL-xxx]` 开头
+- L2 摘要条目的 H3 标题包含 `[CL-xxx]`
+- L1 完整条目的 H3 标题包含 `[CL-xxx]`
+
+这使得从 L3 → L2 → L1 的逐级查找可以通过 Grep 精准定位，无需全文读取。
+
+## 逐级上溯机制
+
+当 Agent 在使用 L3 概要作为上下文时，如果某条记录的一句话描述**语义模糊**
+（如无法判断改动的具体范围、与当前任务的关系不明确），执行以下逐级查找：
+
+```
+1. 从 L3 条目中提取锚点 ID（如 CL-20260424-1430）
+2. 在 changelog-recent.md（L2）中 Grep 该 ID
+   - 找到 → 读取该条目的 3-5 行摘要，通常足以消除歧义
+   - 未找到（已滚出 L2 窗口）→ 进入步骤 3
+3. 在 changelog-full.md（L1）中 Grep 该 ID
+   - 找到 → 用 Read 工具读取该 ID 所在行号 ±20 行范围（精准读取，不读全文）
+   - 未找到 → 放弃上溯，该条目上下文不可用
+```
+
+### 上溯原则
+
+- **按需触发**：只有在 L3 信息不足以支撑当前任务判断时才上溯，不预防性地批量读取
+- **精准读取**：对 L1 的访问必须通过 Grep 定位行号 + Read 局部读取，禁止全文读取
+- **最小化**：一次上溯通常只涉及 1-3 条记录，不批量上溯
+
+## 操作 A：记录写入（核心流程）
+
+### 触发条件
+
+Agent 完成了一个涉及**代码或配置文件实质性改动**的任务后，自动触发。
+
+以下情况**不触发**：
+- 纯对话讨论、方案设计、问题解答（无文件改动）
+- 只读操作（查看文件、搜索代码）
+- 只改动了 `.claude/` 目录下的基础设施文件（如 changelog 自身、hook 脚本等）
+
+### 写入流程
+
+```
+1. 生成锚点 ID：CL-YYYYMMDD-HHMM（检查是否与已有 ID 冲突，冲突则追加字母后缀）
+
+2. 从刚完成的任务中提取以下信息：
+   - 做了什么（what）：一句话概括
+   - 为什么这样做（why）：动机和背景
+   - 改了哪里（where）：受影响的文件/模块列表
+   - 关键决策（decisions）：如果有方案选择，记录选了什么、放弃了什么
+   - 注意事项（notes）：后续可能受影响的地方、已知限制等
+
+3. 生成三层内容（共享同一个锚点 ID）：
+   - L1 完整条目（包含以上全部信息）
+   - L2 摘要条目（what + why + where，3-5 行）
+   - L3 一句话（what，不超过 80 字）
+
+4. 写入三个文件（按以下顺序）：
+   a. 读取 changelog-full.md，在 "## 记录" 下方追加 L1 条目
+   b. 读取 changelog-recent.md，在顶部插入 L2 条目，如超过 20 条则移除最旧的
+   c. 读取 changelog-headlines.md，在顶部插入 L3 条目，如超过 50 条则移除最旧的
+
+5. 在回复末尾附一行提示："[已记录到开发日志]"
+```
+
+### 静默写入原则
+
+- **不需要用户确认**——Agent 自己做的改动，对"做了什么"的认知是一手的
+- 用户如果觉得记录不准确，可通过操作 D 修改或删除
+- 回滚操作也要记录（"回退了 XX 改动"），真实反映开发过程
+
+## 操作 B：L2 自动触发读取
+
+### 触发条件
+
+由 `changelog-recall.md` Rule 调度。当 Agent 开始处理一个新任务时，判断该任务是否
+与近期改动相关。
+
+### 匹配策略（文件 + 标签双匹配）
+
+```
+1. 从当前任务中提取：
+   - 涉及的文件路径
+   - 语义关键词（模块名、功能领域等）
+
+2. 读取 changelog-recent.md，逐条检查：
+   - 硬匹配：当前任务涉及的文件出现在条目的 affected_files 中
+   - 软匹配：当前任务的语义关键词与条目的 tags 有交集
+
+3. 任一匹配命中 → 将匹配到的 L2 条目作为上下文纳入考量
+4. 在回复中自然融入，不显式提及"根据开发日志"
+```
+
+## 操作 C：L1 手动检索
+
+### 触发条件
+
+用户主动要求回顾完整改动记录时触发。典型话语：
+- "回顾一下最近的改动"
+- "XX 模块之前改过什么"
+- "查看开发日志"
+- "changelog"
+
+### 流程
+
+```
+1. 读取 changelog-full.md
+2. 根据用户需求过滤：
+   - 按时间范围
+   - 按模块/文件
+   - 按 tags
+3. 展示匹配的条目摘要表，用户可以进一步查看某条的完整内容
+```
+
+## 操作 D：记录管理
+
+用户可以对已有记录进行管理：
+
+| 操作 | 说明 |
+|------|------|
+| 删除 | 从三层文件中同步移除对应条目 |
+| 修改 | 修改某条记录的描述（三层同步更新） |
+| 清理 | 手动触发 L1 的归档（如按月分文件，暂不实现，作为演进方向） |
+
+## 条目格式
+
+### L1 完整条目
+
+```markdown
+### [CL-20260424-1430] YYYY-MM-DD HH:MM — 一句话标题
+- **tags**: tag1, tag2, tag3
+- **affected_files**:
+  - path/to/file1
+  - path/to/file2
+- **what**: 做了什么的简要描述
+- **why**: 动机和背景
+- **decisions**: 选择了 A 方案（放弃了 B 因为 xxx）
+- **notes**: 后续注意事项
+- **source_chat**: [对话简述](chat-uuid)
+```
+
+### L2 摘要条目
+
+```markdown
+### [CL-20260424-1430] YYYY-MM-DD — 一句话标题
+- **tags**: tag1, tag2, tag3
+- **affected_files**: file1, file2
+- **summary**: 做了什么 + 为什么（3-5 行）
+```
+
+### L3 一句话条目
+
+```markdown
+- [CL-20260424-1430] 一句话描述改动内容（不超过 80 字）
+```
+
+## 滚动窗口维护
+
+### L2 窗口（~20 条）
+
+```
+写入新条目后，检查总条目数：
+- <= 20 条：不做处理
+- > 20 条：移除文件底部（最旧的）条目，直到恰好 20 条
+```
+
+### L3 窗口（~50 条）
+
+```
+写入新条目后，检查总行数（排除文件头部的标题和说明）：
+- <= 50 条：不做处理
+- > 50 条：移除文件底部（最旧的）条目，直到恰好 50 条
+```
+
+被移除的条目不需要额外归档——L1 完整版保留了所有历史。
+
+## 数据文件模板
+
+首次写入时，如对应文件不存在，按以下模板创建。
+
+### 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-recall` Rule | 下游消费者 | 每次会话注入 L3，自动触发 L2 读取，并在 Checklist 中强制调用本 Skill |
+| `check-changelog` Hook | 被动守护 | stop hook 比较源文件 mtime 和 changelog-headlines.md，发现未同步时提醒调用本 Skill |
+| `claude-init` Skill | 重置器 | init 阶段 3 会重置 changelog 三层数据文件 |
+| `epee-orchestrator` Skill | 注册 | 在 registry.md 中注册本 Skill |
+| `pitfall-journal` Skill | 互补 | changelog 记改动事实，pitfall 记经验教训 |
+| `deferred-decisions` Skill | 互补 | deferred 记"没做什么"，changelog 记"做了什么" |
+
+## 自迭代日志
+
+本节记录使用本 Skill 过程中发现的必要检查项。
+
+### 已知必要检查
+
+1. **大任务收尾遗漏风险** — 当单次任务涉及 5+ 个文件改动时，Agent 容易在输出总结回复后遗漏被动写入流程。应在生成最终回复前，先执行 `changelog-recall.md` 中的"任务完成 Checklist"，确认三层日志已写入后再输出回复。绝不能"先回复再补写"。
+
+2. **L3/L2 滚动窗口必须落地** — 操作 A 第 4 步不是「插入即结束」：写入后必须数清条目（L3 为以 `- [` 开头的列表行，L2 为 `### [CL-` 标题行）。L3 超过 50 条、L2 超过 20 条时，必须从**文件底部（最旧）**整段删除条目直至恰好满足上限；禁止长期只追加不修剪。若发现 `changelog-headlines.md` 列表行多于 50，说明上次写入未执行本项，本次补修剪并自检。
+
+3. **顶部插入 Edit 范式（L1/L2）** — L1 和 L2 的每个条目都是多行结构（标题 + 多条 `- **字段**:`）。使用 Edit 工具在顶部插入新条目时，`old_string` 有且仅有两种合法选择：
+   (a) 只包含新条目之前的"稳定前缀"（如 L1 的 `## 记录\n\n` 或 L2 的整段文件头说明），**不触及任何已有条目的任何一行**；`new_string` = 稳定前缀 + 新条目完整内容 + 空行。
+   (b) 把旧首条目的**完整多行内容**（标题行 + 全部字段行）都纳入 `old_string`；`new_string` = 新条目完整内容 + 空行 + 旧首条目完整内容。
+
+   **绝对禁止**：只把旧首条目的标题行（或前 1-2 字段）当 anchor 而不带上剩余字段行——Edit 会吞掉这些 anchor 行但不动剩余字段，造成"旧标题丢失、字段游离"的半损坏状态。
+
+   **写入后自检**：Read 文件头部 30 行，确认看到新条目完整 + 旧首条目标题行仍存在且字段完整跟随。L3 的一行条目不受本条约束（它就是单行，天然无此风险）。

.claude/skills/epee-orchestrator/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: epee-orchestrator
+description: >-
+  EPEE Skill Orchestrator: meta-level dispatch system. Detects whether a task can be handled
+  by an existing Skill and routes accordingly, or discovers Skill gaps and guides the creation
+  of new Skills. Triggers when the Agent encounters tasks with dense manual configuration,
+  clear repetition patterns, or overly long manual instructions. Also used for Skill Registry
+  maintenance and synchronization.
+---
+
+# EPEE Skill Orchestrator
+
+元层调度系统，负责 Skill 分流、缺口发现和 Registry 维护。
+
+## 操作 A：Skill 分流（匹配已有 Skill）
+
+### 流程
+
+```
+1. 读取 registry.md 获取所有已注册 Skill 的摘要
+2. 将当前任务特征与每个 Skill 的"触发场景"关键词匹配
+3. 如果匹配到：
+   a. 告知用户"此任务可以通过 [Skill名] 高效完成"
+   b. 简述该 Skill 的能力及与当前任务的契合点
+   c. 用户确认后，读取并激活对应 Skill 的 SKILL.md
+```
+
+### 匹配规则
+
+- 优先匹配触发场景关键词与当前任务描述的交集
+- 如有多个 Skill 匹配，按相关度排序推荐，由用户选择
+- `deferred-decisions` 等标记为"基础设施"类型的 Skill 不参与任务分流匹配，
+  仅作为 Orchestrator 的下游工具使用
+
+## 操作 B：Skill 缺口发现 + 创建引导
+
+### 触发条件
+
+操作 A 未找到匹配的 Skill，且当前任务满足"Skill 创建价值判断标准"中至少 2 条。
+
+### 流程
+
+```
+1. 向用户提出建议：
+   "这类任务可以通过创建一个 [建议 Skill 名] 来自动化"
+2. 给出 1-3 句方案概要：
+   - 这个 Skill 会做什么
+   - 核心工作机制（如 DSL 生成、YAML 直写、MCP 调用等）
+   - 预估能节省的重复劳动
+3. 询问用户选择：
+   a) "继续讨论并创建" → 进入创建流程
+   b) "以后再说" → 进入延期记录流程
+   c) "不需要" → 结束，正常执行当前任务
+```
+
+### a) 创建流程
+
+```
+1. 使用 Claude Code 内置的 Skill Creator（通过 /skill 命令或 Skill 工具）创建新 Skill
+2. 将以下上下文传递给 Skill Creator 流程：
+   - 触发创建的原始任务描述
+   - Orchestrator 的方案概要
+   - 建议的 Skill 名称
+3. 按 Skill Creator 的标准流程完成 Discovery → Design → Implementation → Verification
+4. 创建完成后，要求用户对新 Skill 进行实际测试
+5. 测试通过后，执行操作 C 同步 Registry
+```
+
+### b) 延期记录流程
+
+```
+1. 读取 deferred-decisions Skill（路径: .claude/skills/deferred-decisions/SKILL.md）
+2. 按其"操作 A：记录延期方案"流程，将 Skill 创建建议记录为 deferred item
+3. tags 中包含 "skill-creation" 和相关领域标签
+4. context 中记录方案概要，便于未来回忆
+```
+
+## 操作 C：Registry 同步
+
+### 触发条件
+
+- 新 Skill 被创建后
+- 已有 Skill 的 SKILL.md 被实质性修改后（如能力范围变化、触发场景变化）
+
+### 流程
+
+```
+1. 读取目标 Skill 的 SKILL.md
+2. 从 frontmatter 提取 name 和 description
+3. 从正文提取核心能力和触发场景关键词
+4. 读取 registry.md
+5. 新增或更新对应条目，遵循 registry.md 中定义的条目格式
+6. 写回 registry.md
+```
+
+### 条目格式
+
+参见 [registry.md](registry.md) 中的条目结构。
+
+## Skill 创建价值判断标准
+
+当操作 A 无匹配时，Agent 使用以下标准评估是否建议创建新 Skill。
+满足 **2 条及以上** 即认为值得建议：
+
+1. **频次**：该类任务预计会出现 3 次以上
+2. **模式明确**：任务有明确的输入/输出模式（输入 X → 产出 Y）
+3. **步骤繁多**：手动操作步骤 >= 5 步，或涉及 >= 3 个文件的协调修改
+4. **易错**：存在容易出错的重复性操作（如 GUID 填写、格式对齐等）
+5. **可自动化**：可以通过生成 DSL / YAML / 配置文件 / MCP 调用来替代手动操作
+
+不满足标准时，Agent 正常执行任务，不提出创建建议。
+
+## 与其他系统的协作
+
+| 系统 | 关系 | 说明 |
+|------|------|------|
+| Claude Code 内置 Skill Creator | 下游委托 | 操作 B 创建流程的执行者 |
+| `deferred-decisions` Skill | 下游工具 | 操作 B 延期记录的执行者 |
+| `skill-self-iteration` Rule | 并行 | 它负责单个 Skill 的经验积累，Orchestrator 负责 Skill 间的调度 |
+| `deferred-recall` Rule | 协同 | Orchestrator 延期的建议通过 deferred-recall 在未来自动提醒 |
+| `forskill-convention` Rule | 兼容 | 新 Skill 如需 Editor 脚本，仍遵循 ForSkill 约定 |
+
+## 自迭代日志
+
+本节记录使用本 Skill 过程中发现的必要检查项。
+
+### 已知必要检查
+
+1. **收尾动作级联遗漏** — 当 Agent 遗漏了一个收尾动作（如 changelog 写入）后，后续的收尾动作（自迭代、Registry 同步）也会被一并遗漏，因为它们都在同一个"收尾阶段"。`changelog-recall.md` 中的 Checklist 化设计可以打断这种级联——每项独立检查，不依赖前一项的执行记忆。

.claude/skills/epee-orchestrator/registry.md

@@ -0,0 +1,70 @@
+# EPEE Skill Registry
+
+> 本文件由 EPEE Skill Orchestrator 维护，记录所有已实现 Skill 的摘要信息。
+> 每次创建/修改 Skill 后必须同步更新（参见 `epee-orchestrator` Rule）。
+
+## 条目格式说明
+
+每个条目包含以下字段：
+- **类型**：项目级 / 个人级 / 基础设施
+- **能力**：1 句话核心能力描述
+- **触发场景**：逗号分隔的关键词/短语，用于与任务特征匹配
+- **输出**：该 Skill 的产出物
+- **路径**：SKILL.md 的相对路径
+- **备注**（可选）：特殊说明
+
+---
+
+## 已注册 Skill
+
+### claude-init
+- **类型**: 基础设施
+- **能力**: 把从模板 clone 或复制过来的 .claude/ 重置为新项目的干净起点——按 baserule 归位原有 rules/skills，清理源项目的项目专用数据，重建 registry，交互式生成 .gitignore，最后写入 `.claude/.init-done` sentinel
+- **触发场景**: 首次会话自动触发（.claude/.init-done 缺失时由 claude-init-recall 规则引导）；关键词："初始化claude"、"claude init"、"重置 claude"、"reset claude"、"按 baserule 归位"、"补 gitignore"、"生成 gitignore"、"gitignore 模板"
+- **输出**: 清理后的 `.claude/` 结构（规范清单完整、项目级内容已清、数据文件为模板、registry 仅含通用条目）、项目根 `.gitignore`（可选）、`.claude/.init-done` sentinel
+- **路径**: .claude/skills/claude-init/SKILL.md
+- **备注**: 首次通过 sentinel 自动触发一次，之后仅关键词手动触发；破坏性操作必须 dry-run；设计为幂等，重复运行无害；阶段 7 失败时不写 sentinel 保证可恢复
+
+### deferred-decisions
+- **类型**: 基础设施
+- **能力**: 记录和追踪延期的技术方案/决策，在关联任务出现时主动提醒
+- **触发场景**: "以后再做"、"先不做"、"defer"、延期方案管理、延期回顾
+- **输出**: .claude/deferred/registry.md 条目
+- **路径**: .claude/skills/deferred-decisions/SKILL.md
+- **备注**: 不参与任务分流匹配，仅作为 Orchestrator 的下游工具
+
+### dev-changelog
+- **类型**: 基础设施
+- **能力**: 三层开发进程记录系统，Agent 完成代码改动后自动记录，提供一句话概要到完整日志的多级上下文
+- **触发场景**: "开发日志"、"changelog"、"最近改了什么"、"回顾改动"、"查看开发记录"、代码改动后自动写入
+- **输出**: .claude/changelog/ 下的 changelog-full.md、changelog-recent.md、changelog-headlines.md
+- **路径**: .claude/skills/dev-changelog/SKILL.md
+
+### pitfall-journal
+- **类型**: 基础设施
+- **能力**: 记录开发中踩过的坑（非显而易见的问题），在遇到同类问题时自动检索匹配已有经验
+- **触发场景**: debug 完成后、"踩坑"、"之前遇到过"、"坑"、进入 Debug mode、同类错误反复出现
+- **输出**: .claude/pitfalls/pitfalls.md 条目
+- **路径**: .claude/skills/pitfall-journal/SKILL.md
+
+### problem-distillery
+- **类型**: 基础设施
+- **能力**: 追踪反复出现的顽固问题，记录解决过程和弯路，定期蒸馏精炼方法论，经实践验证后自动升级为新会话常规注入
+- **触发场景**: "还有问题"、"没解决"、"还是一样"、"又出现了"、"试了好多次"、"反复出现"、Agent 意识到同一问题尝试 2 次以上未解决、"蒸馏"、"总结经验"
+- **输出**: .claude/distillery/ 下的 problems.md、insights.md、golden-rules.md
+- **路径**: .claude/skills/problem-distillery/SKILL.md
+
+### profile-memory
+- **类型**: 个人级
+- **能力**: 在对话中被动检测用户个人特质和项目信息，经确认后持久化为精简画像和详细日志
+- **触发场景**: "画像"、"profile"、"我的偏好"、"查看画像"、"项目信息"、"查看项目画像"、用户主动管理画像
+- **输出**: ~/.claude/profile/user-profile.md、.claude/profile/project-profile.md 及对应 log 文件
+- **路径**: .claude/skills/profile-memory/SKILL.md
+
+### epee-orchestrator
+- **类型**: 基础设施
+- **能力**: 元层调度系统，检测任务是否可由已有 Skill 处理并分流，或发现 Skill 缺口并引导创建新 Skill；同时负责 Skill Registry 维护
+- **触发场景**: 手动配置密集、重复模式明确、手工指引过长的任务、Skill 缺口发现、Registry 同步维护
+- **输出**: 分流决策（调用已有 Skill / 创建新 Skill）、.claude/skills/epee-orchestrator/registry.md 维护
+- **路径**: .claude/skills/epee-orchestrator/SKILL.md
+- **备注**: 元层 Skill，自身注册以便其他 Agent 了解调度能力的可用性

.claude/skills/pitfall-journal/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: pitfall-journal
+description: >-
+  Pitfall experience recording system. Records root causes and solutions after debugging
+  or discovering non-obvious pitfalls, and automatically retrieves matching entries when
+  similar issues arise. Triggers when debug completes, issues recur, or the user mentions
+  "踩坑", "之前遇到过", "坑", or when entering Debug mode.
+---
+
+# Pitfall Journal
+
+记录开发过程中遇到的"坑"——那些不看代码逻辑觉得应该没问题、但实际运行时才暴露的问题。
+与 dev-changelog 互补：changelog 记"做了什么"，pitfall-journal 记"踩了什么坑、怎么爬出来的"。
+
+## 数据文件
+
+所有记录存放在 `.claude/pitfalls/pitfalls.md`。
+
+## 条目格式
+
+```markdown
+### [PF-YYYYMMDD-HHMM] 一句话标题
+- **症状**: 用户/系统看到的错误表现
+- **根因**: 技术层面的真正原因
+- **解法**: 具体怎么修的
+- **防御**: 以后如何避免（可选，如果有通用性的话）
+- **关联**: 相关文件、模块、技术栈标签
+```
+
+## 操作 A：写入记录
+
+### 触发条件
+
+以下任一场景触发：
+
+1. **调试完成后** — 经历了 debug 过程并找到了非显而易见的根因
+2. **用户主动提及** — "记录一下这个坑"、"以后别再犯"
+3. **Agent 识别到经验价值** — 问题涉及框架/库的隐式行为、配置陷阱、环境差异等
+
+以下情况**不触发**：
+- 纯拼写错误、简单语法错误
+- 问题原因一目了然（如变量名打错）
+- 纯业务逻辑调整（不涉及"坑"的语义）
+
+### 流程
+
+```
+1. 生成条目 ID：PF-YYYYMMDD-HHMM
+2. 从调试过程中提取：症状、根因、解法
+3. 归纳防御措施（如果有通用性）
+4. 读取 pitfalls.md，在顶部追加新条目
+5. 在回复末尾附：[已记录到踩坑日志]
+```
+
+### 静默写入原则
+
+与 dev-changelog 一致——Agent 自己调试出来的问题，不需要用户确认就可以记录。
+
+## 操作 B：自动匹配检索
+
+### 触发条件
+
+当 Agent 在当前任务中遇到以下情况时，应主动检索 pitfalls.md：
+
+1. **进入 Debug mode** — 读取 pitfalls.md，扫描是否有与当前错误症状匹配的记录
+2. **同类错误再现** — 错误信息关键词与已有条目的"症状"匹配
+3. **涉及已知高危区域** — 当前操作涉及的模块/技术栈在已有条目的"关联"中出现
+
+### 匹配策略
+
+```
+1. 提取当前问题的关键信号：
+   - 错误信息关键词
+   - 涉及的文件/模块
+   - 涉及的技术栈/框架
+
+2. 在 pitfalls.md 中匹配：
+   - 硬匹配：错误信息关键词出现在条目的"症状"中
+   - 软匹配：涉及的模块/技术栈出现在条目的"关联"中
+
+3. 命中时，在分析中优先考虑已有经验：
+   > 注意：之前遇到过类似问题 [PF-xxx]：[一句话描述]。
+   > 上次的根因是 [xxx]，先排查这个方向。
+```
+
+## 操作 C：手动检索
+
+### 触发条件
+
+用户主动要求回顾踩坑记录。典型话语：
+- "之前那个坑是什么来着"
+- "看看踩坑日志"
+- "有遇到过类似的问题吗"
+
+### 流程
+
+```
+1. 读取 pitfalls.md
+2. 根据用户描述匹配相关条目
+3. 展示匹配结果
+```
+
+## 与其他系统的协作
+
+| 系统 | 关系 | 说明 |
+|------|------|------|
+| `dev-changelog` | 互补 | changelog 记改动事实，pitfall 记经验教训 |
+| `pitfall-recall` Rule | 下游消费者 | 进入 Debug mode 或遇到错误时自动触发检索 |
+| `epee-orchestrator` | 注册 | 在 registry.md 中注册本 Skill |
+
+## 自迭代日志
+
+本节记录使用本 Skill 过程中发现的必要检查项。
+
+### 已知必要检查
+
+1. **顶部插入必须保持旧首条目完整性** — 使用 Edit 在文件顶部插入新条目时（操作 A 第 4 步），anchor（`old_string`）有且仅有两种合法选择：
+   (a) 只包含新条目之前的"稳定前缀"（如 `---\n\n` 或整个文件头部说明段），**不触及任何已有条目的任何一行**；然后 `new_string` = 稳定前缀 + 新条目完整内容 + 空行。
+   (b) 把旧首条目的**完整多行内容**（标题行 + 全部字段行）都纳入 `old_string`；然后 `new_string` = 新条目完整内容 + 空行 + 旧首条目完整内容。
+
+   **绝对禁止**：把旧首条目的"标题行"单独当 anchor 而不带上它紧跟的字段行——Edit 是精确替换，这样做会删掉标题、让字段"无主"残留在新条目之后，造成半损坏状态（2026-04-20 实际踩过此坑）。
+
+   **写入后自检**：Read 文件头 25 行，确认看到 `### [PF-新ID]` 后紧跟其 5 字段，再往下能看到 `### [PF-旧首条目ID]` 标题行且字段完整跟随。

.claude/skills/problem-distillery/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: problem-distillery
+description: >-
+  Progressive knowledge distillation system for stubborn problems. Tracks recurring unresolved
+  issues, records solution processes and dead ends, periodically distills refined insights,
+  and auto-promotes validated insights to routine injection. Triggers when the user expresses
+  "还有问题", "没解决", "还是一样", "又出现了", or when the Agent realizes the same
+  problem has been attempted 2+ times without resolution.
+---
+
+# Problem Distillery
+
+从反复出现的顽固问题中，经过"追踪 → 解决 → 蒸馏 → 验证 → 注入"的完整生命周期，
+蒸馏出经过实践验证的精炼认知和方法论。
+
+与其他系统的区别：
+- **pitfall-journal**：互补。pitfall 是事后快照（debug 完记一笔），distillery 是过程追踪 + 知识提炼
+- **dev-changelog**：不重叠。changelog 记事实改动，distillery 记问题解决过程和认知沉淀
+
+## 数据文件
+
+```
+.claude/distillery/
+  problems.md        -- 问题记录（open + resolved），操作 A/B 写入
+  insights.md        -- 蒸馏后的精炼方法论，操作 C 写入
+  golden-rules.md    -- 权重达标后升级的条目，操作 D 管理，新会话自动注入
+```
+
+## 条目格式
+
+### problems.md 条目
+
+```markdown
+### [PD-YYYYMMDD-HHMM] 一句话标题
+- **status**: open | resolved
+- **fingerprint**: 关键特征词列表（用于匹配同一问题）
+- **category**: tech | workflow | decision | other
+- **first_seen**: YYYY-MM-DD HH:MM
+- **attempts**:
+  1. [YYYY-MM-DD HH:MM] 尝试了什么 → 结果如何
+  2. [YYYY-MM-DD HH:MM] 又尝试了什么 → 结果如何
+- **resolution**: （解决后填写）最终解决方案
+- **dead_ends**: （解决后填写）走过的弯路及其失败原因
+- **spark**: （解决后填写）一句话启发——这个问题教会了什么
+- **distilled**: （蒸馏后填写）IN-xxx
+```
+
+### insights.md 条目
+
+```markdown
+### [IN-YYYYMMDD-NN] 一句话方法论
+- **source_problems**: [PD-xxx, PD-yyy]
+- **weight**: 0
+- **promoted**: false | true | demoted
+- **content**: 2-3 句精炼认知
+```
+
+文件尾部保留元数据：
+
+```markdown
+---
+last_distill_date: YYYY-MM-DD
+```
+
+### golden-rules.md
+
+```markdown
+# Golden Rules
+
+经过实践验证（权重 >= 5）的精炼认知，每次新会话自动注入。
+
+1. [GR-001] 一句话认知（来源: IN-xxx, 累计验证 N 次）
+2. [GR-002] ...
+```
+
+硬上限 15 条。超出时按权重排序保留 top-15，被淘汰的条目降回 insights.md（promoted 改为 demoted）。
+
+## 操作 A：追踪记录（问题进行中）
+
+### 触发条件
+
+以下**任一**场景触发：
+
+1. **用户明确表达**问题未解决：
+   - "还有问题"、"问题没有解决"、"还是一样"、"又出现了"
+   - "试了好多次了"、"这个问题反复出现"、"不行"、"没用"
+   - 以及其他表达"问题反复发生、Agent 没有完全解决"的语义
+2. **Agent 自身意识到**同一问题已经尝试了 2 次以上仍未解决
+
+### 适用范围
+
+不限于技术问题——工作流设计、产品决策等各类反复纠结的问题均适用。
+
+### 流程
+
+```
+1. 提取当前问题的指纹：
+   - 技术问题：错误信息关键词、涉及文件/模块、症状描述
+   - 非技术问题：核心矛盾点、涉及领域、反复出现的决策困境
+
+2. 读取 problems.md，用指纹匹配 status=open 的条目
+
+3. 匹配到已有条目 → 在 attempts 中追加本次尝试记录
+
+4. 无匹配 → 创建新条目：
+   - 生成 ID：PD-YYYYMMDD-HHMM
+   - status: open
+   - 记录首次尝试
+
+5. 告知用户："已开始追踪这个问题 [PD-xxx]"（首次）
+   或 "已更新追踪记录 [PD-xxx]，这是第 N 次尝试"（后续）
+```
+
+### 与 pitfall-journal 的衔接
+
+当 pitfall-journal 中某个条目的同一问题反复出现（用户再次报告相同症状），
+Agent 应意识到这已超出 pitfall 的"一次性记录"范畴，主动触发操作 A 建立追踪。
+
+## 操作 B：解决记录
+
+### 触发条件
+
+存在 status=open 的追踪条目，且满足以下**任一**：
+- 用户确认问题已解决："好了"、"解决了"、"终于可以了"
+- Agent 判断问题已解决（测试通过、错误消失等）
+
+### 流程
+
+```
+1. 填写 resolution：最终的解决方案
+2. 填写 dead_ends：走过的弯路及其失败原因（从 attempts 中归纳）
+3. 填写 spark：一句话启发——这个问题教会了什么
+4. status 改为 resolved
+5. 回复末尾附 [顽固问题已解决并记录]
+```
+
+### 注意
+
+- 如果问题在当前会话中从发现到解决只花了 1-2 次尝试，不需要走 distillery 流程
+  （那是 pitfall-journal 的范畴）
+- 只有经历了"反复尝试"的问题才值得 distillery 追踪
+
+## 操作 C：定期蒸馏
+
+### 触发条件
+
+由 `distillery-recall` Rule 在每次会话开头检查：
+- 读取 insights.md 尾部的 `last_distill_date`
+- 如果距今超过 7 天，且 problems.md 中有未标记 `distilled` 的 resolved 条目
+- 则提醒用户："你有 N 个已解决的顽固问题尚未总结，要花几分钟蒸馏一下吗？"
+- 每次会话最多提醒一次
+
+### 流程（用户同意后）
+
+```
+1. 读取所有 status=resolved 且无 distilled 标记的条目
+2. Agent 分析这些问题的共性，提出归纳建议：
+   - 哪些问题有共同的根因模式？
+   - 能提炼出什么通用的认知或方法论？
+   - 建议的表述（2-3 句精炼认知）
+3. 用户确认/修改后：
+   - 写入 insights.md（ID 格式：IN-YYYYMMDD-NN，NN 为当日序号）
+   - weight 初始为 0
+   - promoted: false
+4. 更新 insights.md 尾部的 last_distill_date
+5. 在对应 problems.md 条目上标记 distilled: IN-xxx
+```
+
+## 操作 D：验证与升级
+
+### 被动验证
+
+当操作 A 触发时（遇到新的或再次出现的顽固问题），额外执行：
+
+```
+1. 读取 insights.md，对当前问题做语义匹配
+2. 如有相关条目，向用户展示：
+   "之前总结过一条相关经验 [IN-xxx]: [内容摘要]，可能对当前问题有帮助。"
+3. 在问题解决流程中，跟踪该经验是否发挥了作用：
+   - 用户确认"这个提示有用"
+   - 或 Agent 判断解决方案与该 insight 的方向一致
+4. 确认有用 → weight += 1，在 insights.md 中更新
+5. 确认无用 → 不扣分（weight 只增不减，避免偶然失误惩罚好经验）
+```
+
+### 升级为 Golden Rule
+
+```
+1. 当某条 insight 的 weight >= 5：
+   a. 检查 golden-rules.md 当前条目数
+   b. 如 < 15 → 直接升级：
+      - 在 golden-rules.md 中追加条目（ID: GR-NNN，NNN 为递增序号）
+      - insights.md 中 promoted 改为 true
+   c. 如 = 15 → 比较权重：
+      - 新条目权重 > golden-rules.md 中最低权重条目 → 替换
+      - 被替换的条目降回 insights.md（promoted 改为 demoted）
+      - 否则不升级
+2. 升级后告知用户：
+   "经验 [IN-xxx] 已累计验证 N 次，升级为 Golden Rule [GR-NNN]，后续新会话将自动注入。"
+```
+
+### 新会话注入
+
+由 `distillery-recall` Rule 负责：
+- 每次会话开头读取 `golden-rules.md`
+- 如果非空，将全部条目作为背景知识注入上下文
+- 注入方式与 `changelog-headlines` 同级别——轻量、不显式提及来源
+
+## 容量与性能控制
+
+| 文件 | 策略 | 阈值 |
+|------|------|------|
+| problems.md | resolved 且已 distilled 的条目超过 50 条时，归档到 problems-archive.md | 50 条 |
+| insights.md | 无上限（条目本身是精炼的，每条 3-5 行） | — |
+| golden-rules.md | 硬上限，按权重淘汰 | 15 条 |
+| 新会话注入成本 | 只读 golden-rules.md（预期 < 30 行） | 极轻量 |
+
+## 与其他系统的协作
+
+| 系统 | 关系 | 说明 |
+|------|------|------|
+| `pitfall-journal` | 上游来源 | pitfall 条目反复出现时，升级为 distillery 追踪 |
+| `dev-changelog` | 不重叠 | changelog 记事实改动，distillery 记过程和认知 |
+| `distillery-recall` Rule | 下游消费者 | 负责 golden-rules 注入和蒸馏提醒 |
+| `epee-orchestrator` | 注册 | 在 registry.md 中注册本 Skill |
+
+## 自迭代日志
+
+本节记录使用本 Skill 过程中发现的必要检查项。
+
+### 已知必要检查
+
+（暂无）

.claude/skills/profile-memory/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: profile-memory
+description: >-
+  Progressive user/project profiling system. Two trigger paths:
+  (1) Passive detection (primary) — triggered by `changelog-recall` checklist item A for short-circuit
+  scanning; executes Operation A (summarize + user confirm + write) when preference/project-decision
+  keywords are hit.
+  (2) Explicit management — executes Operation B (browse, modify, delete existing entries) when the user
+  mentions "画像", "profile", "查看画像", "我的偏好", "项目信息".
+---
+
+# Profile Memory
+
+渐进式画像系统，被动收集并持久化用户个人特质与项目信息。
+
+## 存储结构
+
+| 文件 | 位置 | 用途 | 注入上下文 |
+|------|------|------|-----------|
+| user-profile.md | `~/.claude/profile/` | 个人画像精简版 | 是（每次会话） |
+| user-profile-log.md | `~/.claude/profile/` | 个人画像详细日志 | 否 |
+| project-profile.md | `.claude/profile/` | 项目画像精简版 | 是（每次会话） |
+| project-profile-log.md | `.claude/profile/` | 项目画像详细日志 | 否 |
+
+精简版 Profile 是 Agent 每次会话的上下文输入，必须极度精简。
+详细 Log 保留完整上下文，供用户主动查阅和溯源。
+
+## 锚点 ID 机制
+
+每条画像记录在写入时生成一个**锚点 ID**，格式为 `PF-YYYYMMDD-NN`（如 `PF-20260412-01`），
+其中 NN 为当天的序号。
+
+锚点 ID 在精简版和 Log 中保持一致：
+- 精简版条目格式：`- 条目内容 <!-- PF-20260412-01 -->`（HTML 注释，不影响可读性）
+- Log 条目的 H3 标题：`### [PF-20260412-01] YYYY-MM-DD — 简短标题`
+
+这使得从精简版到 Log 的查找可以通过 Grep 精准定位，无需全文读取 Log。
+
+## 逐级上溯机制
+
+当 Agent 在使用精简版 Profile 作为上下文时，如果某条记录**语义模糊**
+（如无法判断偏好的具体适用场景、与当前任务的关系不明确），执行以下查找：
+
+```
+1. 从精简版条目中提取锚点 ID（HTML 注释中的 PF-xxx）
+2. 在对应的 Log 文件中 Grep 该 ID
+   - 找到 → 用 Read 工具读取该 ID 所在行号 ±15 行范围（精准读取，不读全文）
+   - Log 中包含原始上下文、来源对话等完整信息，通常足以消除歧义
+```
+
+### 上溯原则
+
+- **按需触发**：只有在精简版信息不足以支撑当前判断时才上溯
+- **精准读取**：通过 Grep 定位行号 + Read 局部读取，禁止全文读取 Log
+- **最小化**：一次上溯通常只涉及 1-2 条记录
+
+## 硬上限
+
+- user-profile.md：不超过 **50 行**
+- project-profile.md：不超过 **30 行**
+- 每条信息一行，`- ` 开头，措辞客观中立
+
+## 操作 A：被动检测 + 对话结束前确认
+
+### 检测范围
+
+在正常对话中被动检测以下信号（**不主动询问**）：
+
+**个人特质**：
+- 审美/设计偏好（"太花哨了"、"我喜欢 minimal"）
+- 技术偏好（"以后都用 X"、"我不喜欢 class 写法"）
+- 做事风格（"先讨论再动手"、"不要自作主张"）
+- 沟通偏好（"给我简短的回答"、"多解释一下原理"）
+- 产品理解/思维方式
+
+**项目信息**：
+- 项目定位和目标（"这个项目是做 X 的"）
+- 技术栈与架构决策
+- 设计约定和规范
+- 产品方向和目标用户
+
+### 检测原则
+
+- **保守而非激进**：宁可漏记也不误记
+- 只记录**持久性**的偏好/特质，忽略一次性的临时需求
+- 区分"个人"和"项目"两个维度
+
+### 变更分类
+
+检测到的新信息与已有条目的关系分为三类，处理方式不同：
+
+| 类型 | 定义 | 示例 | 提示强度 |
+|------|------|------|---------|
+| **新增** | 全新维度，无已有条目 | 首次提到审美偏好 | 常规 |
+| **演进** | 已有条目的深化、细化或自然发展 | "偏好 React" → "偏好 React + Next.js 全栈" | 常规，展示前后对比 |
+| **转向** | 与已有条目方向性矛盾或根本性变化 | "偏好 React" → "想转 Vue"；项目方向从 B2C 转 B2B | **加强提醒**，展示前后对比 |
+
+### 确认流程
+
+```
+1. 在对话过程中将检测到的信息在内部缓存，分类为"个人"或"项目"
+2. 对每条缓存信息，与已有 Profile 比对，标记变更类型（新增/演进/转向）
+3. 当用户的主线任务完成后，统一提出，格式如下：
+
+   "本次对话中我注意到以下可记录的画像信息："
+
+   **个人画像：**
+   - [新增][分类] 条目内容
+   - [演进][分类] 旧：xxx → 新：yyy
+   - [转向][分类] 旧：xxx → 新：yyy ⚠️
+
+   **项目画像：**
+   - （同上格式）
+
+   转向类条目额外标注 ⚠️ 并附一句说明：
+   "⚠️ 以下条目与已有记录存在方向性变化，请特别关注："
+
+   "是否记录？你可以全部确认、逐条修改或跳过。"
+
+4. 用户确认后执行写入流程
+5. 如本次对话未检测到任何画像信息，则不触发此流程
+```
+
+### 写入流程
+
+```
+1. 读取对应的精简 Profile 和详细 Log（不存在则用模板创建）
+2. 为每条新记录生成锚点 ID：PF-YYYYMMDD-NN（检查 Log 中已有 ID 避免冲突）
+3. 按变更类型执行：
+   - 新增：在对应分类下追加条目，带锚点 ID 注释
+   - 演进：替换对应旧条目为新措辞，沿用旧条目的锚点 ID（或生成新 ID，视变化程度而定）
+   - 转向：替换对应旧条目为新措辞，生成新锚点 ID（用户已在确认流程中审核）
+4. 写入精简 Profile（条目格式：`- 内容 <!-- PF-xxx -->`）
+5. 追加详细 Log（标题格式：`### [PF-xxx] YYYY-MM-DD — 简短标题`），其中：
+   - 新增条目：操作记为"新增"
+   - 演进条目：操作记为"更新（旧值 → 新值）"
+   - 转向条目：操作记为"转向（旧值 → 新值）"，便于溯源重大变化
+6. 检查精简 Profile 是否超过硬上限，超过则提醒用户精简
+```
+
+## 操作 B：用户主动管理
+
+当用户说"查看我的画像"、"profile"、"查看项目画像"、"我的偏好"等：
+
+```
+1. 读取对应的精简 Profile，展示给用户
+2. 如用户要看详细版或溯源，读取对应 Log 展示
+3. 用户可要求：
+   - 删除某条记录（同步删除精简版条目，Log 中标记为已删除）
+   - 修改某条记录的措辞
+   - 合并/重组分类
+   - 新增分类
+```
+
+## 操作 C：变更比对与冲突处理
+
+### 比对逻辑
+
+```
+对每条新检测到的信息，在同分类下的已有条目中查找语义相近项：
+1. 无相近条目 → 标记为"新增"
+2. 有相近条目且方向一致（深化/细化/补充） → 标记为"演进"
+3. 有相近条目且方向矛盾（替代/转向/否定） → 标记为"转向"
+```
+
+### 前后对比格式
+
+演进和转向类条目在确认流程中必须展示前后对比：
+
+```
+- [演进][技术偏好] 旧：偏好 React → 新：偏好 React + Next.js 全栈开发
+- [转向][产品方向] 旧：面向 C 端个人用户 → 新：转向 B 端企业客户 ⚠️
+```
+
+### 用户选择
+
+对每条演进/转向条目，用户可以：
+- **确认更新**：用新条目替换旧条目
+- **保留两者**：旧条目不动，新条目作为补充追加（适用于不同细分维度）
+- **放弃**：不记录本条
+
+## 数据文件模板
+
+首次使用时，如对应文件不存在，按以下模板创建。
+
+### user-profile.md
+
+```markdown
+# User Profile
+
+## 审美与设计
+
+## 技术偏好
+
+## 做事风格
+
+## 沟通偏好
+
+## 产品理解
+```
+
+### user-profile-log.md
+
+```markdown
+# User Profile Log
+
+详细记录每次画像更新的完整上下文，按时间正序追加。
+
+## 记录
+```
+
+### project-profile.md
+
+```markdown
+# Project Profile
+
+## 项目定位
+
+## 技术栈与架构
+
+## 设计约定
+
+## 产品方向
+```
+
+### project-profile-log.md
+
+```markdown
+# Project Profile Log
+
+详细记录每次项目画像更新的完整上下文，按时间正序追加。
+
+## 记录
+```
+
+### Log 条目格式
+
+每次写入 Log 时，追加以下格式的条目：
+
+```markdown
+### [PF-20260412-01] YYYY-MM-DD — 简短标题
+- **分类**: 对应的精简 Profile 分类名
+- **精简版**: 写入精简 Profile 的那一行内容
+- **原始上下文**: 用户原话或对话中的关键语句
+- **来源对话**: [对话简述](chat-uuid)
+- **操作**: 新增 / 演进（旧值 → 新值）/ 转向（旧值 → 新值）/ 删除
+```
+
+## 分类扩展
+
+预设的分类列表可以扩展。当检测到的信息不属于任何现有分类时：
+
+```
+1. 在确认流程中标注"建议新增分类: [分类名]"
+2. 用户确认后在精简 Profile 中新增该分类的 H2 标题
+3. 注意硬上限，新增分类会占用行数
+```
+
+## 与其他系统的协作
+
+| 系统 | 关系 | 说明 |
+|------|------|------|
+| `profile-recall` Rule | 下游消费者 | 每次会话读取精简 Profile 并注入上下文 |
+| `epee-orchestrator` | 注册 | 在 registry.md 中注册本 Skill |
+
+## 自迭代日志
+
+本节记录使用本 Skill 过程中发现的必要检查项。
+
+### 已知必要检查
+
+（暂无）