IShenH 复盘存档（My Reflection）
这个 skill 做什么
一个入口，三种重量（速记 / 完整 / 深度）、两类产物。先分轻重，再判断走哪条路，最后读对应的参考文件——不要凭记忆直接套结构。
两条路的判据看意图和触发词——最常见的两个词族是：说『归档 / 项目』（让我做了很多事之后，记录发生了什么）→ B；说『学习笔记』（之前就某个问题、技术或概念讨论提问过）→ A。主题是不是技术、有没有代码都不决定归属：两者记录的东西不同，混用结构会两边都不合格：
| 路径 A：学习心得记录 | 路径 B：项目档案 | |
|---|---|---|
| 判据 | 重点是学习、理解、反思 | 重点是把一个项目本身讲清楚 |
| 对象 | 一个问题、一个概念、一段经历、一篇文章/一本书 | 一个项目整体（整个作品） |
| 回答 | 为什么是这样、我搞明白了什么 | 这个项目是什么、做成了什么 |
| 跨度 | 一次学习/调试/探索的经过 | 项目全生命周期，含版本演进 |
| 重心 | 深度：一个点挖到机制层 | 广度：概览、功能、成果、边界、叙事 |
| 读者 | 用户自己日后复习 | 他人（面试官、读者）+ 项目留档 |
第一步：先分轻重
轻量提法（『快速复盘』『简单说说』『简要记录』『记录一下』『先记个大概』『不用太详细』）→ 直接出速记，不要先纠结 A 还是 B，也不要读参考文件。只有需要完整文档时才往下走。
速记的样子（一张骨架，不分路径）
速记不做 A/B 区分，只用一张骨架，把两类对象该有的信息都收进来——对象是一个问题还是一个项目，都用它：
---
date: YYYY-MM-DD
type: 速记
tags: [reflection/quick-note, 关键词]
---
# 速记：{主题}
- **是什么**：一句话说清这次记的对象（一个问题 / 一个项目 / 一件事）
- **经过**：2–3 句，按事情本身的顺序讲清发生了什么
- **根因 / 关键**：为什么会这样，一句话说透
- **怎么解决的 / 怎么做的**：关键改动或做法，一行
- **原理**：一句话给最核心的机制，不展开
- **下次注意 / 局限**：一行——下次怎么判断，或现在还差什么、没验证什么
写法上：
- 写成一段连贯的短讲解，不要对着标签硬填——上面几行是『该讲到的信息』，不是必须出现的小标题；信息少时可以合并成两三句话。总长 20 行以内，一屏看完。
- 两类信息都兼有：问题类重点在『根因 / 原理』，项目类重点在『做了什么 / 局限』，但都不要缺另一侧——项目速记也给一句原理（为什么这样做），问题速记也交代结果和边界。
- 口吻：默认用户的视角（『遇到了……原以为……后来发现……』），主语『我』能省则省；但不必强求第一人称——事情的主角是 AI 或工具时，直接用中性的第三方叙述更准确（『排查时发现……』『让 AI 改了配置后……』）。详见
references/learning-reflection.md的口吻一节。
速记的规则：
- 速记是索引，不是教材：不贴长代码、不写七节结构、不做方案对比、不追求『不重走探索也能懂』（那是完整文档的标准）。
- 说了『快速讲讲』就不要输出完整文档；说了『讲透』『整理成完整笔记』也不要停在速记。
- 可升级：用户随后说『展开第 N 点』『讲透原理』，就在这份速记的骨架上扩成完整文档（文件按保存去向归位），不要重头另起，也不要重新问一遍分类。
- 速记本身不做 A/B 区分——分类留到需要升级成完整文档时再判。轻量记录大多就是边界地带，不必在记录的时候把类别定死。
第二步：判断条件
（不走速记时）按顺序判断，命中即停：
- 用户说『归档』『项目』（『归档一下』『整理项目』『写项目文档』『梳理这个项目』）→ 路径 B（项目档案）。典型场景：让我做了一件事（写了个工具、搭了个功能、改了一堆东西），做完之后要把发生了什么、做了什么记录下来——对象是这件事/这个作品本身。
- 用户说『学习笔记』『学习心得』（『整理成学习笔记』『记一下心得』）→ 路径 A（学习心得）。典型场景：之前就某个问题、技术或概念跟 AI 讨论和提问过，要把搞懂了什么、为什么是这样记录下来——对象是理解和认知。
- 其他说法时看内容：这次重点是学习、理解、反思（搞懂一个报错/概念/技术点，读完一本书/一篇论文/一篇文章后的思考整理，把零散理解理顺）→ 路径 A，与主题是不是技术无关；重点是把一个项目本身讲清楚（这个作品是什么、由什么组成、做出了什么，给别人看或留档）→ 路径 B。
- 用户在谈方案取舍（两者唯一的实质重叠处）：
- 问『为什么这样设计、trade-off 是什么、怎么在项目叙事里说』→ 路径 B。
- 问『这个方案为什么技术上行得通、切断了哪条因果链』→ 路径 A。
- 『复盘』二字本身不决定归属，看宾语：『复盘这个项目』通常指 B；指项目里某个具体问题则 A。
- 分不清时，只问一句：「这次想留下的是学习/反思的心得，还是这个项目的档案？」不要一次抛多个问题。
- 两条都要（项目收尾时常见：项目档案 + 若干关键技术点心得）→ 先 B 后 A，各自独立成文，不要混在一份文档里。
第三步：读对应的参考文件
- 路径 A → 读
references/learning-reflection.md - 路径 B → 读
references/project-documentation.md
读完再动笔。这两个文件各自带着完整的结构、质量标准与模板，是实际产出的依据。
两条路都适用的原则
- 不编造：材料里没有的细节不补。推断要标注『推断 / 待验证』；项目效果没有数据就写『当前没有量化指标』，宁可留白也不要编数字。
- 区分信息状态：事实（可验证的）／判断（对原因、动机、价值的解释）／待确认（材料不足的）——项目档案里尤其要随手标注。
- 为复习而写：不出现『刚才』『上面那段代码』这类依赖会话现场的指代，涉及的东西直接用名字说清；开头交代背景（日期、项目、技术栈/环境）。
- 触发后直接产出，不要反问『你想复盘什么』。信息不足时只针对缺失环节提问（优先问：当时的确切现象/报错是什么、已经做过哪些尝试）。
如果用户是要回看，不是要记录
用户想看的不是新的记录，而是旧的（『回顾一下我这段时间的速记』『把关于 Vite 的记录汇总一下』『我上次那个问题是怎么解决的』）时：去笔记根（见『保存与命名』）按关键词找相关文件读，然后串成一份回顾——按主题或时间线组织，指出反复出现的问题、哪些已经解决，不要凭空另写一份新记录。只有用户说要留档时才落盘。
保存与命名
产出都是 Markdown 文档，落盘后都要给出可点击的路径。
- 速记（轻量档）默认落盘——用户要的就是『快速复盘或者记录』，所以直接存进笔记根，并告诉用户存到了哪；只有用户明确说『只是讲讲』『不用存』时才只在对话里给。
- 完整档（A / B）：用户意图是留存（『把这次的收获记下来』『整理成笔记』『存档』）时落盘；用户只是在追问、没说要记（『这到底怎么回事』『为什么会这样』）时，先在对话里给文档，并提示可以存下来。
保存位置：先看 references/paths.md 是否存在（本地私有配置，不随仓库分发）——存在就完全按它执行；不存在则用下面的默认规则。
<笔记根>/
├── YYYY-MM-DD-主题.md ← 速记（轻量）：直接放这一层
├── learning-notes\ ← 学习心得（A，完整 / 深度）
└── project-archives\ ← 项目档案（B）
- 笔记根默认是当前工作区的
notes/，没有就新建；用户指定过位置就用用户的。 - 想固定长期使用的位置（换机器、换工具都不用改正文），复制
references/paths.md.example为references/paths.md填上即可。
| 产出 | 文件名 | 位置 |
|---|---|---|
| 速记（轻量） | YYYY-MM-DD-主题.md |
笔记根 |
| 学习心得（A） | 同名，# 速记： 改成 # 学习心得： |
笔记根\learning-notes\ |
| 项目档案（B） | <项目名>.md（如 mcp-agent-project.md），不带日期 |
笔记根\project-archives\ |
- 速记升级成学习心得时，把文件移到
learning-notes\并就地扩写，不要在两处各留一份。 - 项目档案不带日期：它要长期反复更新，已有档案就在其上更新，不从零重写。
- 同一件事第二次记录（同一个问题又犯了、接着上次继续）→ 先按主题关键词找已有文件名（
ls *关键词*.md，根层和两个子文件夹都看），找到就扩写，不要新建日期文件。同一件事只有一个文件。 - 路径可能含空格或中文，按原样写入（shell 里整个路径要加引号），不要截断、转义或改写。
- 文件名里的主题：空格换成短横线，去掉
\ / : * ? " < > |这些平台非法字符，控制在 40 字以内。 - 目录不存在就创建；若笔记根所在位置不可用（换了机器、盘符不存在），先问用户一句，不要静默改存到别处。用户当场指定了别的位置时，从其指定。
- 目录里已有索引文件时才顺手补一条；没有就不必为单次产出新建索引。
笔记头部（frontmatter）
每份笔记的第一行就是 frontmatter，三行，不要省——笔记工具（Obsidian、Logseq）靠它按日期、类型、标签把笔记捞出来，纯文本检索也一样受益：
---
date: 2026-09-16
type: 速记 | 学习心得 | 项目档案
tags: [reflection/quick-note, 关键词]
---
type与实际产出一致：速记 / 学习心得 / 项目档案。- 标签用层级标签，固定第一个：速记
reflection/quick-note、学习心得reflection/learning、项目档案reflection/project；再补一到三个主题关键词（如vite、proxy）。前缀要换别的，在references/paths.md里改。 - 日期只写在这里，H1 里不再重复（文件名已带日期）。
- 相关笔记互相链接：同一主题已有别的笔记时，在正文末尾加一行——按
references/paths.md里配的链接写法写（例如[[笔记名]]这种可点击的库内双链，或中性的相关笔记：笔记名），没配就写相关笔记：笔记名。升级是移动文件，所以不要让它链回自己。
交付前自检
- 完整档：至少有一处写到机制层（哪个函数、哪个配置项、哪条调用链）、至少一条可迁移经验、没有编造材料里不存在的东西。
- 速记：20 行以内；问题类不缺结果与边界，项目类不缺一句原理。
- 落盘：路径、文件名、H1 三者与『保存与命名』一致；速记升级时是移动文件，不是复制。
- 头部：frontmatter 三行（date / type / tags）齐全，
type与实际产出一致，tags里带主题关键词。