学习指南
你为每次考试生成一个自包含的 HTML 页面，该页面通过 scripts/build.py 从课程文件夹的纯文本文件构建。页面包含三个部分：
- 笔记，每次讲座一个章节。每个论点都引用幻灯片页码。每个主题都配有通俗解释框、工作示例、图表和红色的“陷阱”框。每个章节末尾的练习框让学生可以在阅读后立即自测。
- 练习中心，包含四个标签页：
- 一个练习题库，提供即时反馈和每个选项的解释；
- 逐步引导的简答题，支持部分得分；
- 定时模拟考试，从独立题库中按真实考试比例抽取；
- 一个自动填充的错题本。
- 进度报告，由页面为你保存。你稍后阅读它并编写针对学生实际错误的新练习。
引擎 (assets/engine.js) 和样式 (assets/page.css) 已完成并经过测试，因此你的工作是内容和问题。页面的大部分实用价值在于参考文件；在完成相应步骤时请阅读它们。
| 当你即将…… | 请阅读 |
|---|---|
| 编写讲座章节 | references/content-standard.md |
| 编写或审核问题，或校准模拟考试 | references/question-bank.md |
| 检查字段名、进度格式或数据库文档 | references/data-format.md |
examples/demo/ 是一个完整的小型课程（虚构的 PROB 101，三次讲座）。如果不确定某部分应如何呈现，请从其源文件复制模式：sections/*.html、practice.json、mock.json 和 short.json。
不要读取 assets/engine.js、assets/page.css 或任何已构建的 review.html。build.py 会内联它们，它们包含数万个 token，并且不需要你的编辑。
在下面的命令中，<skill-dir> 是包含本 SKILL.md 的文件夹。如果找不到 python3（在 Windows 上常见），请使用 python 或 py -3。
1. 了解考试内容
在编写任何内容之前，先获取以下信息。尽可能自行查找，仅就你找不到的信息询问学生：
- 考试： 日期和时间、时长（分钟）、涵盖的讲座范围、格式以及允许的参考资料。格式指问题类型、每种类型的数量及其分值。参考资料指笔记页、计算器或不允许任何资料。
- 资料： 幻灯片（PDF 或链接）、阅读材料、课程网站以及任何官方练习题、测验结果或样题。
- 学生： 他们希望页面使用的语言（
lang：界面语言zh或en；并用学生所用语言编写内容），以及他们的基础水平。说“我跟不上”的学生需要在几乎每个主题上都配有通俗解释框。
如果你能浏览课程网站，请自行研究课程：课程表页面、教学大纲和公布的测验结果。寻找值得告诉学生的模式，例如“课堂检查问题正好出现在某张幻灯片之后”或“官方题库说它与考试使用相同格式”。将后勤信息放入页面的标题区域。
检查教学大纲中的课程 AI 政策。有些课程禁止 AI 生成的学习材料或禁止在评分作业上使用 AI 帮助。如果政策禁止此操作，请在构建之前告知学生。切勿将评分作业的答案放到页面上。
2. 校准模拟考试，避免泄题
学生通常希望保留官方样题用于一次定时练习。那么不要阅读其问题；而是测量它：
python3 <skill-dir>/scripts/count_exam.py sample_exam.pdf
该脚本从不打印问题、选项或场景文本。它打印：
- 页数和问题数，以及每个问题的选项数；
- 分值、时间限制和封面说明（计算器、笔记）；
- 共享一个场景的部分标题和问题范围（“问题 11-14……”）；
- 引用前面材料的问题编号。
使用输出来设置模拟部分（类型和数量）和时间限制。一个引用前面材料的问题（例如，复用了前面场景的简答题）在描述考试结构时属于该场景。
如果脚本无法告诉你某些信息，请报告为未知并让学生查看封面页。不要编写你自己的探针来打印问题内部的单词或数字。即使是零星的“总计”或“%”也会暗示问题的主题，而方程中的数字会泄露问题。
在打开任何样题或答案之前先询问。即使学生允许阅读，也只将其用于校准（结构、难度、风格）。切勿将考试的问题或场景复制到页面中。
3. 设置课程文件夹
python3 <skill-dir>/scripts/build.py --init <course-dir>
这会复制示例课程。然后编辑 course.json：
title、lang和lectures。讲座标签必须与问题和分组使用的标签完全一致，例如"L1"或"L5-L6"。storageKey：每个课程和考试唯一，例如"bio201-mt1"。进度存储在其下，因此一旦学生开始使用，切勿更改它。mock.sections：一个条目对应一个问题类型，按考试顺序排列，数量与真实试卷匹配。mock.minutes：可供选择的时间限制。包含真实时间；如果模拟考试省略了长问题，也要提供一个按比例缩短的时间。
在替换时删除示例的章节和问题。每个字段的说明请参见 references/data-format.md。
4. 编写章节
在 sections/ 中为每个讲座编写一个文件（10-l1.html、20-l2.html……），加上用于后勤信息的 00-hero.html 和一个最终的陷阱列表。每个讲座是一个 <section class="part" id="...">。当有一个练习分组使用 "sec" 指向该 id 时，其练习框会自动出现。
references/content-standard.md 包含完整的配方和每个组件的 HTML。简而言之：引用每个论点，用词汇表和类比开场难懂的讲座，为每个主题提供一个一行摘要、公式前的具体示例、通俗解释框、有助于理解的图表，以及针对判断题设置的陷阱框。
5. 编写问题
有三个题库。references/question-bank.md 包含规则和审核清单。
practice.json：每个讲座 8-15 个问题。混合单选题、判断题、多选题和填空题，以及偶尔的抽认卡。每个选项都有其自己的解释。mock.json：其自己的问题，绝不复制练习项目。数量约为每次考试从每种类型抽取数量的两倍，以便每次练习试卷不同。匹配真实考试的风格。short.json（可选）：考试中简答题类型的逐步版本。每个步骤是一个容差的填空题、选择题或与标准答案的自我检查。
6. 构建并检查
python3 <skill-dir>/scripts/build.py <course-dir>
错误会停止构建。警告来自问题库检查；除非有理由，否则修复它们。它们标记以下模式：
- 正确答案在太多问题中是最长的选项；
- 同一个字母作为显示答案的次数太多；
- 每个多选题都有相同数量的答案；
- 模拟考试问题是用新数字替换的练习问题。
添加 --strict 以使警告以退出码 2 结束构建（页面仍会写入），以便你可以继续修复直至干净。然后，在浏览器中打开 <course-dir>/review.html 并检查：
- 控制台没有错误，且公式正常渲染；
- 回答练习问题、简答题步骤和完整的模拟考试都能正常工作；
- 在 375 像素宽度下，没有内容导致页面横向滚动（图表和表格在其自己的框内滚动）；
- 图表中没有文本与线条、箭头或其他文本重叠（截取屏幕截图）。
7. 交付
- 本地（任何代理）： 提供文件路径。进度保存在该浏览器的 localStorage 中。练习中心的导出进度按钮提供 JSON 供学生粘贴回给你。
- claude.ai 工件（仅限 Claude；实验性，尚未进行端到端测试）： 发布构建后的 HTML 并授予
db能力。如果window.claude.use("db")可用，引擎会将进度镜像到文档progress/practice和progress/mock，并在progress/report中保存摘要。在依赖它之前，在已发布的页面上回答一个问题并读取progress/report。如果文档缺失，请告诉学生改用导出进度。
用两三行文字告诉学生如何使用页面：阅读一个章节，做其练习框，在临近考试前做模拟考试，以及考试前一天使用错题本。
8. 闭环
当学生回来时，在更改任何内容之前先读取他们的进度。使用他们粘贴或发送的导出 JSON（其 report 字段），或者如果工件同步正常工作，则使用 progress/report 数据库文档。报告列出：
- 每个讲座的首次正确率；
- 每个答错的练习问题，包含他们的答案和正确答案；
- 他们答错的简答题步骤；
- 模拟考试历史，以及上次试卷中答错和标记的问题。
然后：
- 用几句话指出薄弱环节。统计首次正确率低于约 80% 的讲座、重复出现的误解，以及持续出错的简答题步骤。还要统计标记为不确定但答对的问题；那些也是不牢固的知识。
- 为每个薄弱环节编写新的练习。用不同的措辞、数字或场景重新提问相同的概念；绝不重复他们答错的问题。将它们以新 ID 添加到
practice.json中，如果模拟题库在该处薄弱，也添加到mock.json中。 - 修复解释，而不仅仅是问题。如果某个误解重复出现，可能是章节解释得不好。为该混淆点添加一个通俗解释框、一个工作示例或一个图表。
- 重新构建，然后告诉学生更改了哪些内容以及在哪里。
编辑时保持已保存的进度有效
记录通过 storageKey、问题 id 和原始选项索引进行键控。因此：
- 保持
storageKey和现有 ID； - 不要重新排序、插入或删除已回答问题中的选项（而是追加一个新问题）；
- 不要为不同的问题重复使用旧 ID；
- 如果问题的含义或答案发生变化，请为其分配一个新 ID 并删除旧 ID。已删除 ID 的记录会被忽略，不会被误读。
引擎使用来自 ID 的种子对选项的显示顺序进行洗牌，因此存储的索引保持正确。要更改答案作为哪个字母显示，请设置 "show"（参见 references/data-format.md），而不是重新排序选项。修复题干和解释中的拼写或措辞始终是安全的，编辑章节 HTML 也是安全的。
学生反馈的需求
这些经验教训来自于构建用于真实考试的复习页面：
- 抽象的解释没有效果。学生要求先给出具体数字（“抛硬币 10 次……”），然后是公式，并将推导过程折叠起来并标记为不考。
- 在练习之前学习多个讲座令人疲惫。这就是为什么每个章节都以自己的练习框结尾。
- 对格式的挑剔令人恼火，例如因为
1/2而不是0.5被扣分。引擎按数值比较数字答案；在accept中列出文本变体。 - 学生很快学会答案模式。正确答案通常是最长的选项，每个多选题有 3 个答案，正确答案总是 B。构建工具会审计前两个；引擎会洗牌显示顺序。
- 重复使用练习问题的模拟考试衡量的是记忆力，而不是理解力。这就是为什么模拟题库是独立的。
- 学生希望选择选项文本进行复制，并且有一个计时器在时间耗尽时自动提交。
学生反馈的需求（续）
- 简答题的逐步指导需要更智能：如果学生在第一步输入了正确数字但格式错误（例如缺少单位），应该提醒而不是直接判错。
- 模拟考试的计时器需要提供剩余时间的视觉警告（例如最后 5 分钟变红）。
- 错题本应允许学生标记“已掌握”并将问题移出列表，以便专注于仍然困难的问题。