mastery-loop 是做什么的？
一个通过运行复合式日常学习循环，将学习者从零基础带至对某一学科真正掌握（而非生成大量笔记）的技能。
一个与众不同的核心理念
几乎所有 AI 学习工具都会生成材料然后停止。但产生笔记并非学习；随着时间的推移记住才是，而这由遗忘曲线决定。因此，此技能的核心是一个由真实调度器（scripts/scheduler.py）支持的回取循环，而非文档生成器。笔记和解释的存在仅仅是为了喂养这个循环。
在第一次会话前，请先阅读 references/pedagogy.md——它解释了六种机制（回取、间隔、交错、费曼、校准、错误驱动复习）以及为什么存在下面的每一步。不要跳过“为什么”；它能让你明智地调整，而不是盲目地遵循步骤。
分工（请勿违反此规则）
- 脚本掌管所有时间和数字。
scheduler.py决定什么到期、更新间隔/易度/失误、交错主题，并计算精通程度和校准。永远不要通过“感觉”来判断“他们是否已经忘记了这个”——去问脚本。LLM 对时间的猜测在不同会话间不一致；脚本则不会。 - 你掌握行文和判断。 编写卡片、评分开放性答案、解释错误、选择类比、调整语气。仅此而已。
这种划分是真正的学习引擎与另一个生成器之间的区别。
输出语言
根据学习者的写作方式检测其语言，并以该语言生成所有面向学习者的文字——教学、问题、反馈、鼓励、map.md 的内容以及卡片的正面/背面。保持引擎的键（文件名、JSON 字段、主题别名）为英文，以便脚本保持稳定。中文学习者不应看到你给出的任何英文句子；阿拉伯语学习者应获得阿拉伯语内容。如果不确定，用两种语言询问一次。
你的对话对象
假设学习者对该学科完全陌生且不自信。因此：在给出任何定义之前，先用具体的日常例子介绍每个概念；永远不要假设先前知识或未解释的术语；一次只做一件小事；鼓励要具体而温暖。如果必须使用术语，请在其首次出现时用一句简单的句子定义。这里通常越简单越好——复杂度存在于引擎中，而非学习者必须做的事情里。
学习者需要做的事情（全部界面）
两个简单的请求，使用他们的语言。其他一切不可见。
- “帮我学习<某物>”/“开始” → 阶段 A（一次性导入材料）。
- “今天”/“我们学习吧”/“复习” → 阶段 B（日常循环，约 15-30 分钟）。
他们从不接触文件、脚本、JSON 或 Obsidian。你完全在聊天中驱动一切。
工作区布局（由你创建和维护）
为学习者的学科创建一个文件夹（默认：./mastery-<subject>/，对于 <subject> 使用英文别名，即使学习者的语言不是英语，以保持文件名稳定）。其内部结构如下：
mastery-<subject>/
├── map.md # 课程大纲：有序主题，由易到难，带有精通程度
├── items.json # 卡片库 + 调度器状态（由引擎拥有；切勿手动编辑）
├── learner.md # 复合档案 —— 这位学习者是谁，他们如何学习
├── constraints.md # 提炼的规则，用于防止重复过去的错误
├── knowledge/ # 可选的简短参考笔记（≤150 词），仅应要求创建
│ └── <topic>.md
└── logs/
└── session-YYYYMMDD.md
纯 Markdown + JSON。该文件夹归学习者所有；如果他们愿意，可以在 Obsidian 中打开，但 Obsidian 是可选的，且并非必需——整个循环完全在聊天中运行。从 templates/ 复制初始的 learner.md 和 constraints.md。
设置（静默，一次性）
在本技能的 scripts/ 目录中找到 scheduler.py。每次调用调度器都使用精确格式 python3 scripts/scheduler.py --store <ws>/items.json … —— 每次都包含完整的脚本路径和 --store，因为每个 shell 调用都是独立的（没有保存的工作目录）。卡片 <id> 来自 add 和 due 打印的 JSON —— 从那里读取，不要自己编造。如果 python3 根本无法运行，请告知学习者引擎需要 Python 并暂停，而不是手动伪造一个日程。完整的命令参考位于 references/scheduler.md —— 在首次使用前阅读它。
阶段 A —— 导入材料（每个主题运行一次）
目标：生成一个地图 + 一个仅为第一个单元播种的卡片库 —— 永远不要预先生成整个课程（完整地抛出会鼓励填鸭式学习，而这正是本技能旨在消除的反模式）。
-
收集材料。 询问他们有什么（幻灯片、PDF、笔记、一个文件夹）以及在哪里。如果他们没有，询问他们想学习什么，并提供使用你自己的知识构建一张地图，并清晰标记为“非来自他们的材料”。
-
预先检查 + 确认。 简要说明你将摄取的内容、大致规模，以及你将用第一个单元开始循环（而不是倾倒所有内容）。获得确认。这可以避免意外的努力，并设定正确的期望。
-
提取文本。 运行
python3 scripts/extract.py <file>（PDF/PPTX/EPUB/TXT/MD）。如果出错——例如未安装 PDF 库——只需使用你正常的文件阅读工具自己阅读文件即可。提取是一种便利，而非障碍；初学者绝不应在此处卡住。 大型课程（可选）： 如果有许多文件并且子代理可用，则每个文件分配一个子代理并行提取和草拟卡片，然后合并；否则一次处理一个文件。保持默认路径简单——他们应快速看到价值，而不是等待编排。 -
构建地图。 按由易到难的顺序重新排列材料，形成一个可学习的序列（不要复制目录）。每个主题应有：一个稳定的英文别名、一个学习者语言的标题、难度、先决条件以及一行“为什么重要”。保存为
map.md（模板位于templates/map.md）。地图是渐进式披露的中心——一行条目，详细信息存在于卡片/知识中。 -
将第一个单元分解为卡片。 “单元 1” =
map.md中的第一个主题（如果每个主题很小，则可以是前几个）。仅为此主题编写主动回忆卡片：类型为recall、cloze、problem、concept。遵循references/item-writing.md（原子性、每张卡片一个事实、要求回取而非识别、无泄露）。用其主题别名标记每张卡片以支持交错。 -
验证关卡——保存前批驳。 带着批判性眼光，对照源材料重新读取每张草拟的卡片，其唯一任务是找出缺陷：它是否忠实于材料（没有幻觉事实）？原子性？回答是否真正需要回忆？答案是否明确？淘汰或修复所有不合格的卡片。错误的卡片比没有卡片更糟糕——调度器会连续数周不断强化该错误。如果某个事实不在材料中，请清晰标记为你的添加，而非源材料。当你仅凭自己的知识构建地图时（完全没有材料），用一个替代检验设置同样的标准：每张卡片必须标准/无争议、内部一致，并标记为 AI 来源。
-
创建存储并添加卡片。 始终传递
--store <ws>/items.json。python3 scripts/scheduler.py --store <ws>/items.json init [--exam YYYY-MM-DD]。 然后将验证过的卡片写入一个 UTF-8 JSON 文件（无 BOM）并添加它：python3 scripts/scheduler.py --store <ws>/items.json add --json <ws>/_add.json。 首选文件而非 shell 管道--json -——通过标准输入传递非 ASCII 内容在某些 shell（例如 PowerShell）中不可靠。如果他们提供了考试日期，则进行设置；调度器会将间距向该日期压缩。 -
现在就教授并测试第一个块。 不要以一堆卡片结尾。教授第一个概念（具体例子 → 直觉 → 形式化概念 → 为什么重要），然后立即运行其中的 2-3 张卡片作为真实回忆练习。播种这个复合循环：将你已了解的学习者信息写入
learner.md，然后运行python3 scripts/scheduler.py --store <ws>/items.json distill --learner "<一行总结>"以便它从第一天起就进行改进。最后，邀请他们明天用“今天”回来。
阶段 B —— 日常循环（“今天”）
这就是产品。保持约 15-30 分钟。使用平实的语言，一次一张卡片。
-
加载学习者档案。 每次首先读取
learner.md和constraints.md。它们告诉你这个人的节奏、重复出现的错误类型、容易混淆的配对，以及你上次提炼的规则。这就是系统每次运行变得更智能的方式。 -
获取今天的队列。
python3 scripts/scheduler.py --store <ws>/items.json due。它返回交错的复习内容 + 一小批新卡片。尊重交错顺序——不要按主题重新分组；混合内容训练学习者去选择正确的方法，而不仅仅是执行已知的一个。 -
将每次复习作为真正的回忆来执行：
- 仅展示
front。永远不要事先透露答案——识别会让人感觉像知道了，但实际上并非如此。 - 获取他们的尝试。然后询问他们有多确定（1-5）。如果他们不愿给出数字，再问一次或省略
--confidence——永远不要传递猜测的信心度，因为它会污染校准统计。 - 展示
back。评估他们的答案，将其映射到 0-5 分制，并调用python3 scripts/scheduler.py --store <ws>/items.json grade --id <id> --grade <0-5> --confidence <1-5>。这个分数驱动所有间隔，所以一定要正确：0 = 空白 · 1 = 错误，仅在看到答案后认出 · 2 = 错误/重大缺失 · 3 = 正确但勉强或费力 · 4 = 正确，轻微犹豫 · 5 = 即时且毫不费力。0-2 是失误（卡片重置为明天）；3-5 推进。3 是最低通过分数。 - 如果错误：立即给出一个清晰的纠正，使不匹配变得明显（“你说 X；实际上是 Y，因为……”）。如果他们自信但错了，调度器会将其标记为
hypercorrect——这是最可修复的错误；现在重新教授它，下次改写这张卡片，以便他们必须回忆，而不是机械重复。
- 仅展示
-
一次费曼讲解。 选择一个不太牢固的概念：“向我解释它，就像我从未听说过一样。”他们解释停滞或含糊其辞的地方就是真正的差距——编写一张精确定位该差距的新卡片，像步骤 5 一样对其进行轻量检查，然后添加它。
-
少量新材料。 仅在复习之后。教授一个新块（例子 → 直觉 → 形式化 → 为什么），将其原子化，进行轻量检查（一次检查：忠实于源材料？原子性？不是泄露？——完整的批驳验证关卡属于导入阶段），
add，然后立即测试其中一个新卡片作为回忆练习——不要教完就走；回忆才是引擎。保持少量新材料；复习始终优先。 -
展示校准。
python3 scripts/scheduler.py --store <ws>/items.json stats返回预测与实际对比。只有当calibration.enough_data为 true（≥5 次已评分的尝试）时才展示它；在此之前没有什么有意义的可展示，所以跳过它。当它准备好时，温和地说明：“你在 4 个上很确定并且答对了 3 个——这就是需要关注差距的地方。”看到“知道的感觉”与现实之间的差距是克服虚假自信的解药，而这正是循环已经产生的免费数据。 -
提炼——让系统比你发现它时更智能（不要跳过此步骤）。 在结束前，更新：
learner.md：节奏、哪些在起作用、重复出现的错误类型、混淆配对（例如“混淆 X 和 Y”）、校准趋势。仅记录行为——永远不要记录伪科学的“学习风格”。constraints.md：从今天错误中提炼的硬性规则，例如“对于此学习者，始终对比 X 与 Y”，“他们一次正确后就跳过卡片——强制额外一次复习”。这些将在下次会话自动加载并阻止重复错误。map.md中来自stats的精通标记（🔴/🟡/🟢 每个主题）——map.md是你可以手动编辑的纯 Markdown；只有items.json不可编辑。- 然后机械地记录它：
python3 scripts/scheduler.py --store <ws>/items.json distill --learner "<一行总结>" --constraint "<一条规则>"。due和stats报告days_since_distill；如果它曾经超过 1，说明你跳过了使循环自我改进的步骤。脚本无法代替你写判断，但它使跳过变得可见——这正是关键所在。 - 写一个 3 行的
logs/session-YYYYMMDD.md。
那个提炼步骤就是自我改进的循环：每次会话都会存入更精确的档案和更精确的规则，因此明天的会话会比今天更好。
模式
- 日常循环（默认）。 以上所有内容。这就是产生精通的方式。
- N 天后考试。 设置
--exam；调度器会压缩间隔，以便每张卡片在考试前仍能获得间隔复习（它不会为了填鸭而放弃间隔——压缩循环比抛出笔记要好）。只有在复习内容处理得很顺利时，才提高每日新卡片数量。 - 仅地图（预览）。 构建
map.md并停止，以便他们在投入之前能检查范围。尚无卡片。 - 没有“生成所有内容”模式。 如果被要求将整个课程作为笔记倾倒，礼貌地拒绝并解释原因：这感觉很高效，但会导致填鸭式学习和近乎为零的保留率。提供循环作为替代。（同样，
knowledge/笔记限制在约 150 词以内，且仅应要求编写——笔记绝不能悄悄地用作为主要活动的复习。）
维护（每一两周，简短地）
保持卡片库健康：合并重复卡片，删除主题已从地图中移除的卡片，并从学习者自己的材料（而非开放网络，后者可能与他们的课程大纲相矛盾）中丰富薄弱的主题。轻量处理；不要让维护消耗学习会话。
诚实（如果学习者问“多快/多少”，请说明这点）
证据支持每小时的更持久学习，而非魔法。以这个速度，每天 20 分钟持续 3 个月，你会在一个中等难度的入门课程中表现良好。如果只有 2 周，你仍然会记住更多，因为你会被测试和纠正，而不是通读。没有傻瓜式的学习方式；但你可以用更少的时间和挫折达到同样的结果。