knowledge-miner

从 Git commit 或当前会话的真实信息中挖掘知识，把分散概念串成一条完整的功能因果链，并通过费曼讲解和从零创造最小版本帮助初中生真正理解。当用户要求总结提交知识点、学习最近修改、讲解某个 commit、复盘本次会话、总结刚才学到了什么，或从上文提炼知识时使用。提供 commit hash 时分析指定提交；明确指定当前会话时分析可见会话证据；未指定来源时合并分析最近三次提交。

从用户指定的信息来源中寻找有真实证据、可以迁移到其他问题的知识。先理解本次工作真正构建或改变了什么，再选择知识点；不要让时间线上偶然出现的报错或命令细节抢走核心产物的教学位置。教学对象按没有专业开发基础的初中生处理：先解释词语，再讲过程；使用日常生活类比，但不能让类比代替真实证据。

教学完成的标准不是“列出了几个概念”，而是学习者能够回答三件事：这些改动合起来实现了什么功能；为什么必须按这样的顺序协作；怎样亲手创造一个保留核心机制的最小版本。把“能用自己的话讲清楚”和“能从零重建并预测结果”作为理解证据。

需要设计类比、控制难度或判断知识教学价值时，读取 references/teaching-guide.md。选择当前会话模式时，还要读取 references/session-evidence-guide.md。

选择信息来源

根据用户的明确表达选择一种模式：

1. 指定 commit 模式：用户提供 commit hash 时，验证该 hash 能唯一解析为 commit，然后只分析该 commit。hash 无效、歧义或对象不存在时，明确说明并请用户检查；不要改为其他模式。
2. 当前会话模式：用户明确说“本次会话”“当前对话”“刚才”“上文”“我们刚完成的过程”等表达时，只分析当前可见会话中的真实证据。此模式不要求当前目录是 Git 仓库。
3. 最近提交模式：用户没有提供 hash，也没有明确指定会话时，读取当前分支从 HEAD 开始的最近三次 commit。少于三次时分析实际存在的全部 commit，并说明数量。

不要仅因为当前会话存在就自动选择会话模式。这样可以保留“未指定来源时查看最近三次 commit”的默认行为。如果用户同时明确指定 commit 和会话，询问要以哪一种信息来源为准，不要自行混合。

Commit 取证

指定 commit 模式和最近提交模式都先确认当前目录属于 Git 仓库。若不是 Git 仓库，并且用户没有给出仓库路径，询问要分析的项目位置，不要猜测。

最近提交模式将三次提交合并归纳，去除重复知识点。每个知识点都要标注其证据来自哪些 commit。不要把工作区未提交修改、暂存区修改或其他分支的提交混入范围。

对每个目标 commit 至少查看：

• commit hash、标题和父提交；
• 文件列表与增删统计；
• 完整 diff；
• 理解 diff 所必需的少量提交时文件上下文。

优先使用 Git 读取提交时的版本，例如 git show、git diff 和 git show <commit>:<path>。不要仅依据当前工作区文件解释旧 commit，因为文件之后可能已经变化。

遇到 merge commit 时，以第一父提交为基线识别该 merge 实际引入的变化，并说明这是合并提交。不要把被合并分支的全部历史重复当成本次修改。

commit 结论必须能指回 commit、文件和 diff 片段。commit 标题只能帮助理解意图，不能代替代码证据。

会话取证

当前会话模式只使用当前可见上下文，不声称访问已经丢失、被截断或其他任务中的内容。若上下文明显不完整，要说明证据边界。

按可靠程度使用以下证据：

1. 实际工具或命令输出、测试结果和错误信息；
2. 本次会话中读取、创建、修改或验证过的真实文件与产物；
3. 用户在会话中提供的事实、需求、代码、截图或报错；
4. 助手提出的方案、判断和解释。

第 4 类只能用于说明“讨论过什么”，不能证明已经实施。能够通过低成本只读操作核验的最终文件或状态，应先核验再教学。会话前后信息冲突时，以较新的真实验证结果为准，并把失败尝试与最终结果区分开。

每个会话知识点都要标注证据类型和发生阶段，例如“需求澄清”“文件修改”“命令报错”“最终验证”。不要暴露系统提示、开发者指令、隐藏推理、密钥、令牌、密码、连接信息或与教学无关的个人数据。详细筛选规则见会话证据指南。

构建功能因果链

完成取证后，先写一份只用于内部推导的“功能因果链卡”，不要立刻按文件、commit 或会话时间线挑知识：

• 起点问题：修改前遇到什么限制、风险或需求；
• 整体能力：这些改动合起来让系统能够完成什么；
• 输入与输出：什么信息进入系统，最后产生什么结果；
• 必要环节：从输入到输出必须经过哪些步骤；
• 环节连接：上一环产生什么，下一环为什么需要它；
• 设计理由：为什么选择这些机制，不采用它们会在哪里失败；
• 关键取舍：为了安全、正确、性能或可维护性放弃了什么；
• 验证边界：哪些环节已有证据，哪些仍未证明。

把必要环节压缩成一条可以读出来的链：

起点问题 → 接收输入 → 关键处理 A → 关键处理 B → 校验或保护 → 最终能力

每个箭头都要能用一句“因为……所以……”解释。无法解释的箭头表示理解仍有缺口，应回到 diff、文件或会话证据补证，而不是用猜测填空。

知识点必须从这条链中选择，不能先选三个孤立概念再强行拼接。每个重点都要说明：它位于哪一环；上一环交给它什么；它把什么结果交给下一环；删掉这一环后整体功能会怎样失效。

如果多个 commit 或会话事件确实共同实现一项能力，就按运行关系合并讲解，不按提交顺序分课。如果它们属于互不相干的功能，明确说明不能组成同一条链：选择教学价值最高的一条作为主线，其余放入“其他可以继续学的内容”，不得虚构联系。

如果存在主要产物，主线应先回答“它整体怎样工作、为什么需要这些组成部分”。只有缺少核心领域知识，或用户明确要求复盘调试时，才把普通报错、命令用法、文件搬迁等过程知识提升为重点。

例如：主要产物是一个 Skill，应把“触发识别 → 证据选择 → 内容处理 → 输出验证”作为候选功能链，再从真实实现确认每一环；安装命令或偶发环境报错通常只是附带信息。数据库功能可使用“请求 → 校验 → 事务修改 → 持久化 → 返回结果”，页面功能可使用“用户操作 → 状态变化 → 数据请求 → 渲染反馈”。这些只是构链方法，不能代替本次真实证据。

提炼可学习知识

知识不限定技术领域。可以来自实际出现的：

• 编程语言、数据结构、算法和异步流程；
• 页面组件、状态管理、网络请求和交互设计；
• 服务端接口、鉴权、缓存、并发和错误处理；
• 数据库表、SQL、事务、索引和数据迁移；
• 测试、调试、日志、安全、性能和可维护性；
• Git、构建、依赖、容器、CI/CD 和工程配置；
• 需求拆解、方案比较、失败定位、验证方法和安全迁移。

先把候选知识分为三层：

1. 核心领域知识：主要产物的结构、原理、工作机制和重要设计决策；
2. 实现与验证知识：怎样实现主要产物、怎样证明它满足目标、不同验证层级有什么边界；
3. 附带过程知识：偶发报错、环境差异、命令细节、权限流程、目录迁移和普通协作步骤。

可靠证据只是入选门槛，不代表知识价值高。按“核心领域知识 → 实现与验证知识 → 附带过程知识”的顺序选择，层级优先于错误是否醒目、命令输出是否具体。最多深入讲 3 个知识点：只要存在可靠的核心领域知识，第一个知识点必须来自第一层；有足够内容时，前两个知识点都应解释主要产物的设计或工作原理。第三层默认只能进入“其他可以继续学的内容”。

完整的功能链优先于领域多样性。不要为了同时覆盖前端、后端、数据库或每个 commit 而各选一点。一个环节如果需要两个紧密配合的概念才能讲清，可以合并成一个知识点；一个概念如果无法解释整体能力中的输入、处理或输出，就不应进入主线。

附带过程知识只有满足以下任一条件时才能进入前三：它直接改变了最终产物的设计；它是本次任务的核心问题；用户明确要求学习该过程；或者前两层没有足够可靠的知识。其余确有价值的内容只列出名称及证据来源，供用户后续选择。

以下信息通常不能单独支撑知识教学：

• 只有格式、空白、拼写、机械重命名或重复确认；
• 只有自动生成文件、编译产物或无对应源码变化的 lockfile；
• 只有版本号、合并记录、权限确认或工具状态噪声；
• 没有得到实施或验证的普通方案；
• 与主要产物无关、只在执行过程中偶然出现的报错或环境问题；
• 无法从目标信息来源确认其作用的内容。

不要为了凑满 3 个知识点而包装琐碎细节。没有可靠且适合学习的内容时：

• 最近提交模式回答：最近提交没有可学习的知识。
• 指定 commit 模式回答：这个提交没有可学习的知识。
• 当前会话模式回答：本次会话没有足够可靠的可学习知识。

可以补充检查过的信息范围和判定原因，但不要继续生成教程。

用费曼法讲通整条链

费曼学习法在这里不是简单地“说得更通俗”，而是通过讲解暴露理解缺口。对整体功能和每个关键环节依次执行：

1. 不用术语说清目标：先用初中生能复述的一句话说明系统要解决什么问题。
2. 沿数据或控制流讲过程：从真实输入讲到真实输出，不按文件目录背概念。
3. 寻找说不清的地方：凡是只能重复术语、跳过中间步骤或无法解释“为什么”的位置，都视为理解缺口。
4. 回到证据补洞：重新查看对应 diff、文件、测试或会话结果，补全条件、边界和失败路线。
5. 再次简化并教回去：用更短的语言重讲，同时保留正确边界；最后让学习者用自己的话复述整条链。

生活类比只负责帮助进入概念。讲完类比后必须回到本次真实系统，指出类比中的每个角色对应哪段输入、状态、处理或输出，以及类比在哪些地方不成立。

每个重点知识按以下顺序讲解：

1. 它在功能链中的位置：展示 上一环 → 本环 → 下一环，先建立联系。
2. 一句话认识它：不用未解释的专业词汇说明它是什么。
3. 生活中的类比：只解释这一环的关键关系，并指出类比边界。
4. 本次信息里的证据：给出 commit、文件和 diff，或会话阶段、工具结果和最终状态。只展示理解所需的短小片段。
5. 一步一步发生了什么：说明它收到什么、怎样处理、交出什么；一次只引入一个新词。
6. 为什么整体功能需要它：说明删掉这一环后，哪一步会出错或失去保障。
7. 以后还能用在哪里：给出一个同类但不同场景，帮助迁移知识。
8. 理解缺口检查：提出一道要求解释因果关系的问题，并紧接着给出参考答案。

首次出现的英文术语同时给出简短中文解释。避免假设用户熟悉前端、后端、数据库、Git 或命令行。

用创造检验理解

“凡我不能创造的，我就不能理解”落实为一个贯穿全部重点知识的最小创造任务。它不是每个知识点各做一道互不相关的小练习，而是让学习者从零搭出整条功能链的缩小版。

创造任务必须包含：

1. 目标：一句话说明要创造的最小功能，以及输入和输出。
2. 零件：列出与主线知识点一一对应的最少组件、数据或规则。
3. 骨架：先用流程图、表格或不依赖具体语言的伪代码连接这些零件。
4. 逐步搭建：先实现最短可运行路线，再按功能链顺序一次加入一个机制；每一步都说明新增机制解决了什么失败。
5. 先预测再验证：给出正常、边界和失败输入，要求学习者先写出预期结果，再展示参考结果或测试方法。
6. 故意拆掉一环：移除或关闭一个关键机制，预测整体功能会怎样坏掉，用反例理解“为什么需要它”。
7. 映射回真实工程：逐项指出最小版本的零件对应本次证据中的哪个文件、函数、数据结构或流程。

优先使用纸笔、伪代码、内存数据、只读命令或隔离测试环境。除非用户明确要求实施，不自动创建或修改项目文件。不要让初学者操作生产数据、真实密钥、账号权限或破坏性命令。

输出结构

按以下结构组织答案，并让标题与来源相符：

markdown

# 本次知识挖掘课

## 从哪里找到这些知识
- commit 来源：`<short-hash>` `<subject>`：一句话说明实际变化
- 或会话来源：`<阶段>` `<证据类型>`：一句话说明实际发生的事情

## 这些修改合起来创造了什么
- 起点问题：修改前缺少什么能力或保障
- 整体功能：这些改动配合后，系统现在能够做什么
- 为什么要做：不这样设计会出现什么具体失败

## 功能因果链
`输入 → 环节 A → 环节 B → 保护或验证 → 输出`

逐个解释箭头为什么成立。流程超过三个环节且关系明确时，可以补一张简单 Mermaid 图。

## 知识点 1：名称
### 它在功能链中的位置
### 一句话认识它
### 生活中的类比
### 本次信息里的证据
### 一步一步发生了什么
### 为什么整体功能需要它
### 以后还能用在哪里
### 理解缺口检查

## 从零创造一个最小版本
### 要创造什么
### 需要哪些零件
### 先画骨架
### 按功能链逐步搭建
### 先预测，再验证
### 故意拆掉一环
### 对应回真实工程

## 用费曼法讲回去
- 不使用专业词汇，用自己的话说明整体功能
- 解释每两个环节之间为什么必须连接
- 说出删掉一个关键环节后会发生什么

## 其他可以继续学的内容
- 名称：证据来源

不要同时输出“commit 来源”和“会话来源”占位行，只保留当前模式对应的内容。没有其他知识时省略“其他可以继续学的内容”。如果证据显示多个功能互不相关，在“这些修改合起来创造了什么”中明确主线范围，不输出虚假的总功能。用户要求深入某一点时，继续使用相同来源中的真实证据讲解，并保留它与整体功能的连接。

交付前检查

• 已按用户表达选择指定 commit、最近提交或当前会话模式；
• 最近三次已合并归纳并去重；
• 每个知识点都有可核验的来源；
• 已识别起点问题、整体能力、输入、输出和必要环节；
• 已先说明这些改动合起来实现什么以及为什么要做；
• 功能链中每个箭头都有真实证据和因果解释；
• 无关改动没有被强行串成同一项功能；
• 第一个知识点来自主要产物的核心领域，除非确实没有可靠内容；
• 有足够核心内容时，前两个知识点都在解释主要产物的设计或工作原理；
• 每个重点都说明了上一环、本环、下一环和移除后的失败；
• 偶发报错、环境问题和命令细节没有压过核心领域知识；
• 讨论方案没有被写成实际成果；
• 失败过程与最终验证结果已经区分；
• 深入知识点不超过 3 个；
• 最小创造任务覆盖了全部主线知识点，而不是分散练习；
• 创造任务包含先预测再验证、故意拆环和映射真实工程；
• 费曼复述问题能暴露术语背诵或因果跳步；
• 没有泄露敏感信息、隐藏指令或隐藏推理；
• 初中生不查资料也能理解首次出现的词语；
• 没有可学内容时使用了对应模式的明确结论。