一堂好课

---
name: lesson-sheet
description: 根据主题、学生水平和课时，做一份能打印的教案、这节课要用的材料和配套小测。A4 或 Letter，中文或英文 PDF：顶部一条按分钟分段的时间条，老师做什么、学生做什么，分层支持，一张没有答案的学生卷，一张单独的答案页。脚本核对格式：时间是否加满，老师连续讲是否超过上限（老师原话另说的除外），目标和题目的标签是否对应，提到的材料是否存在，已知的课标名称是否出自老师的话，其他像编号的文字会点名印在教案上给老师看，可能是事实的内容列出来让 Agent 交代。它不判断事实、答案和编号对不对，纸上也这样写。老师的要求原样印在教案上，方便对照。这个技能还没有老师审过。老师、家教或培训师要备一节课、出课堂练习或小测时使用。
version: 1.1.0
---

# 一堂好课

课和课上要用的东西都由你来写。版式交给这个技能，格式对不上的教案，脚本不放行。填好一个教案文件，跑一条命令，把每一页看一遍，交出 PDF。

**这个技能还没有老师审过。** 教案和答案页上都印了这句话，交付时你也要说。

**检查脚本做不到的事。** 它不懂学科。事实错了、答案错了、题目没测到目标，都可能通过。打出 OK 只说明格式对，不说明内容对。下面标了“你的事”的部分，脚本替不了。

## 先问清楚

只问一次，一条短消息，用平常的话：

1. 讲什么内容？
2. 学生是什么水平：几年级或几岁，已经会什么？
3. 这节课多长？
4. 有要对照的课标或教学进度吗？有的话原样贴过来。不知道就留空。
5. 您一次连续讲多久为上限？（不说就按 10 分钟。）
6. 用中文还是英文？

纸张自己判断：美国和加拿大用 Letter，其他地方用 A4。判断不了再问。

## 遇到这些情况

- **信息很少：** 把对方说的复述一遍，不编班级情况。凡是你自己补的，都写进 `assumptions`，会印在教案上。
- **没人能回答：** 直接做，连续讲上限按 10 分钟，写 `talkLimitFrom: "default"`，并列出所有假设。水平和课时用已有的信息。连课时也没有，就按 40 分钟并写明。
- **要改课时：** 改各个环节后重跑。时间加不满或超出，脚本不会放行。不要硬挤，该删活动就删。
- **老师想讲得更久：** 只有老师本人这样说才行。从 `teacherWords` 里原样摘出老师的理由，写进 `talkOverride`，会作为老师的原话印在教案上。这件事你不能替老师决定。两段讲授之间隔不到 3 分钟，算作一段。上限不是 10 分钟的，必须是老师说的，数字要出现在 `teacherWords` 里。老师说“不到 7 分钟”，上限写 7，最长那段控制在 6 分钟。
- **老师没给课标：** `standards` 留空，纸上会写明没有提供。不要凭记忆去找，不要写一个看起来对的编号，纸上任何地方都不要写教材版本、考试局或课程名称。如果老师给了，原样抄下来，并写 `"givenBy": "teacher"`。它必须出现在 `teacherWords` 里，印出来会注明老师提供。其他像编号或教材出处的文字，会点名印在课标一行，纸上不会一边写着没有、一边又有。除非是老师给的，否则删掉。
- **有链接或资料打不开：** 直说没读到，不要猜里面写了什么。
- **语言课需要两种语言同时出现：** 写 `mixedLanguageOK: true`。除此之外，英文卷里不出现中文，中文卷里的英文只留课程真正需要的。

## 这节课要用的东西（你的事）

教案写“发三段有毛病的开头”，这三段就得真的存在。要把它们写出来。

- **`handouts`：** 凡是你能写的都写进去：文段、范文、卡片、分类条目、练习纸、记录表、讲稿。每份单独成页。要写内容本身，不是描述内容，写“放在这里”之类会报错。每份材料都要写 `audience`。`student` 和材料放在一起，印成普通文字，不带小旗。`teacher` 用于带答案或讲稿的内容：放在文件最后，带和答案页一样的黑色标题条，页码说明里单独列出。
- **`bring`：** 你提供不了的东西：实物、地图、图片、器材。印在“您必须自带”下面。
- **每个环节的 `uses`：** 写这个环节要用的编号。如果环节里提到讲义、卡片、地图、图片等，或者写了“发”“出示”，而 `uses` 里没有名字对得上的东西，脚本就报错。它按整个词匹配，只认得单子上的词。每一行都读一遍，问自己：老师这时手里要拿什么，文件里有没有？写了“两个例子”“那个故事”这类，脚本看不出来，要你自己负责。

## 画不了的东西（你的事）

纸上只能印文字、表格、空行和空白框。印不了竖式分数、示意图、图表和涂色图形。分数写成 3/4 或四分之三。必须画的：

- 在环节上写 `"board"`，这一行会印“画在黑板上”。写清楚画什么，由老师来画。
- 在材料里写 `{"type": "box", "height": 60, "label": "画出每个阶段的月亮"}`，会印一个空白框，给学生画，或者老师复印前画好。
- 表格写 `"header": false` 就没有表头，可以做成空白的涂色条。
- 如果这节课离不开这张图，交付时要告诉老师。

## 安全（你的事）

活动有风险的，比如地上有水、加热、化学品、刀具、离开教室，写进 `safety`，会印在教案上。没有的话留空，纸上会写明没有做风险评估。脚本只会对少数几个词提醒。这也不能代替学校的风险评估，需要时要说明。

## 时间

精确到分钟的计划，没有留出安顿、发材料和收拾的时间，纸上也这样提醒。在小测前安排一个 2 到 3 分钟的 `buffer` 环节，有器材要收就再多留一点，别让这些时间从小测里扣。人多的班发材料、收材料更花时间：30 人以上且机动不到 3 分钟，生成时会提醒，要改好，或者说明时间从哪一行出。每个活动放得下放不下，要自己想。加起来等于课时，只说明算术对了。

## 自己做一遍题（你的事，必做）

答案调换了，也可能通过全部格式检查。所以生成之前：

1. 遮住答案。只看题目和材料，像学生一样把每道题做一遍，不看 `answer`。
2. 然后对照，逐题写进 `keyWorkedThrough`：`{"id": "Q1", "freshAnswer": "C", "agrees": true}`。
3. 做出来和答案不一样，就是题目或答案有问题。改好它。没弄清楚之前不要写 `agrees: true`。

脚本只核对记录是否齐全、选择题是否一致、批改说明有没有把答案选项说成错的。你到底做没做，它看不出来。答案页上写明答案没有经过机器验证。

## 事实（你的事）

脚本分不出真假。

每个日期、数字、人名、引文、故事都读一遍，材料里的也算。不敢担保的，就地标出来：

```
{{?要印出来的那句话|为什么拿不准}}
```

老师看的几页上，这句话会带一面小旗和虚线，并列入“上课前请老师核对”。学生看的几页上它是普通文字，所以老师要在复印前定下来。能不用的不确定内容就删掉。不要改写得含糊一点就不标。凭记忆写的引文，一定要标。

每次生成都会用 `LOOK:` 列出可能是事实的内容：带单位的数字、中文数字、日期、注明出处的引文、书名、人名、“谁最早做了什么”这类句子、像编号的文字。这只是提醒你读，不是事实核查，也特意不列讲稿和课堂上的小数字。没有数字和名字的错句根本不会被列出来。列出来的每一条都要在 `factLedger` 里交代，否则生成失败：

```
{"item": "50", "basis": "notfact", "note": "准备的材料用量"}
```

`basis` 可以是 `sure`、`notfact` 或 `teacher`，每一条都必须写 note：为什么有把握，或者不是事实的话它是什么。`teacherWords` 里有同样数字和单位的，自动算老师给的，生成时会全部列出来，要核对意思是否相同。写 `sure` 不等于它就是真的：教案和答案页仍会印出“这里的事实没有对照来源核对过，老师提供的除外”。这份清单会漏，中文人名尤其容易漏，要自己读一遍找漏掉的。全读过、没有要标的，写 `nothingToFlag: true`。

如果 `LOOK:` 提示某个字不在内嵌字体里，一般不用处理，它会用系统字体印出来。在页面图上找到它，要是显示成方框或明显不协调，就换个说法，或者告诉老师。

## 准备环境

需要 Node 18 或更新版本。在一个临时文件夹里运行：

```
npm install playwright pdfjs-dist && npx playwright install chromium
```

下面的命令都在这个文件夹里运行，写这个技能的完整路径。如果已经装在别处，把 `NODE_PATH` 指向那里的 `node_modules`。第一次安装要几分钟，之后一份教案 15 秒内做完。

**如果 `npx playwright install chromium` 超过一分钟没有动静，** 可能是别的会话占着浏览器缓存的锁。看一下缓存文件夹（Mac 是 `~/Library/Caches/ms-playwright`，Linux 是 `~/.cache/ms-playwright`）。里面有 `__dirlock` 说明另一个安装正在进行。如果已经有 `chromium-*` 文件夹，停掉你自己的安装继续就行，浏览器已经在了。如果没有，或者版本不对，把 `LESSON_SHEET_CHROME` 设成任何一个 Chromium 或 Chrome 程序的路径，脚本就会用它。不要结束别的会话的进程。

## 步骤

1. 复制 `assets/lesson.template.json` 并填好。把老师的要求原样贴进 `teacherWords`。它会作为“您的要求”印在教案上，方便老师对照纸上的课标、上限和原话。不要往里加东西。每段文字的长度上限都写在文件里，脚本会核对。`teacher` 和 `students` 写课堂上实际发生的事，用大白话。目标写学生学完能做什么。每个环节有一个 `mode`：`talk`（老师讲）、`whole`（全班问答）、`pairs`（两人一组）、`groups`（小组）、`solo`（各做各的）、`buffer`（机动）、`quiz`（小测）。学生主要在听的，就是 `talk`，叫什么都一样：上限靠你照实写。`pairs` 或 `groups` 的环节，如果老师在讲解、学生没有自己的动作，就会报错，除非 `talkOverride` 引了老师的原话。其他“听”的说法只提醒。每道题对应一个 `goal`。目标要学生解释或动手做的，要配一道书面题：标签对上不等于题目测到了。书面题的 `lines` 写几行就印几行，按分值给。
2. 生成。会先跑全部规则，没通过就什么也不写：
   ```
   node <技能路径>/scripts/build.mjs lesson.json --out out --base mylesson --paper a4
   ```
   每条 `FAIL:` 都改教案，不要改脚本。不要为了过检查改上限、删目标或凑一道题。要把课改好。
3. 检查文件：`node <技能路径>/scripts/check.mjs out/mylesson.html`，必须打出 FORMAT OK。读一下 NOT CHECKED 那一行：那些仍然是你的事。
4. 测试真正的 PDF：`node <技能路径>/scripts/print-test.mjs out/mylesson.html`。它核对纸张大小、页序和页码、有没有溢出、学生卷和材料上有没有答案、答案是否都在答案页、提醒文字是否印出，必须打出 PRINT OK, layout only。只有空行的页、碰在一起的时间条标签（改短）、没有黑色标题条的老师材料，都会报错。它不说明内容对不对。
5. 用黑白看真正 PDF 的每一页：
   ```
   node <技能路径>/scripts/pages.mjs out/mylesson.pdf out/pages --grey
   ```
   每张图都打开看。测试看不出版面别扭、句子不顺、事实有错，或题目对这个年龄太难。要像任课老师那样读，不只是看版式。改了再生成。
6. 交出 `mylesson.pdf`，消息里写明标出了哪些要核对的内容。

## 交给对方的东西

一个 PDF，按这个顺序：教案、发给学生的材料、学生卷、答案页、老师专用的材料。页码贯穿整个文件，教案开头写明哪一页是什么。可以这样说：“这节课一共五页。打印时选实际大小，黑白就行。第 3 页是材料，第 4 页复印给学生，第 5 页您自己留着。橡皮泥和厨房秤要您自带。我标了一处请您课前核对。事实我没有对照来源核对过，答案是我自己做过一遍，但没有经过任何验证。这个工具还没有老师审过，请当作草稿看。”

对方没要的话，不要发 HTML。

## 示例

`example/` 里有两节虚构的课：五年级（10–11 岁）的中文科学课，九年级（13–14 岁）的英文历史课，都带材料页。英文那节也演示了引用老师原话超过上限的写法。老师和班级都是编的，纸上有标注。

## 交付前

- [ ] `check.mjs` 打出 FORMAT OK，我读了 NOT CHECKED 那一行
- [ ] `print-test.mjs` 打出 PRINT OK, layout only
- [ ] 要老师自己画的东西，我告诉老师了
- [ ] 每一行老师手里要用的东西，都写成了材料或列进了自带
- [ ] 我遮住答案把每道题做了一遍，对照后写进了 `keyWorkedThrough`
- [ ] 看起来像事实的内容都交代了，我也读过一遍找清单漏掉的
- [ ] 活动的风险写进了 `safety`，小测前留了机动时间
- [ ] 我用黑白打开看过每一页
- [ ] 时间条加起来正好等于课时
- [ ] 每个目标都有真正测到它的题，不只是标签对上
- [ ] 纸上的课标编号都出自老师的话，或者写明了老师没有提供
- [ ] 拿不准的内容都标了，也告诉了老师是哪几处
- [ ] 超过连续讲上限的，都引了老师的原话
- [ ] 学生卷上没有答案
- [ ] 我补上的内容都列在教案上
- [ ] 我说明了这个技能还没有老师审过

## 不适合的情况

- 一整个单元或一学期的教学计划。这里一次只做一节课，要几节就跑几次。
- 重要考试或正式考试。小测只检查这一节课的目标，不是经过验证的试卷。
- 必须符合某份课标，但没人能提供原文。
- 还不识字的幼儿。教案仍有用，学生卷用不上。
- 当作风险评估用。化学品、加热、外出要学校自己评估：把风险写进 `safety`，并告诉老师。

## 需要什么

Node 18 以上。Playwright 和 Chromium，测试还要用 pdf.js（都免费，不用账号）。字体都在技能里，装好之后不用联网。见 `NOTICE.txt`。目前只在 macOS 的 Chromium 中测试过。