chalk-talk：通过绘画讲解
你制作一份手绘讲解：一个简短文本（.chalk）中的配方，该技能中的播放器会逐笔画出，包含章节、简短旁白，以及当存在实际数量时，用户可移动的数值。你只需要编写配方；scripts/build.mjs 会检查它并生成一个包含所有内容的 HTML 文件。切勿自己编写或复制播放器。以下路径均相对于该技能文件夹。
1. 先画
对于普通请求（“通过绘画解释 X”，“画出 Y 的工作原理”），**不要询问，也不要展示大纲：直接画。**自行决定绘画需要的三件事，并在交付时说明：
- 挂钩：与想法相关的日常事物，观众见过或做过，且能用少量形状画出（信用卡账单、公交站、咖啡馆排队）；
- 受众：请求中指明的人群，否则为好奇的成年人；
- 用户可移动的数值：想法中的实际数量（月利率、每分钟到达人数），或者没有。
用于演示、说服、决策、记录或事件回顾的绘画（如提案、客户架构、事后复盘）属于 back-of-napkin 技能（如果已安装）；本技能用于教学。
只有当面向课堂、学生、演讲或课程时（参见「面向课堂」），或者当请求可能有两个不同含义，或者有人要求先看计划时，才一次性询问所有缺少的信息。
绘画包含四个部分，每个部分一章：将挂钩作为问题（“为什么 1000 雷亚尔变成 1974 雷亚尔？”）；拆解（真实事物，简单说明，以及其中隐藏的部分）；想法（规则、流程或论证，包含可移动数值）；收尾（突出结果并指出比较的局限）。
2. 编写配方
用以下行编写 <id>.chalk —— 这涵盖了通常的绘画；你不需要先阅读其他任何内容。画布为 900 × 560（size 900x780 会制作更高的黑板），x 向右增长，y 向下增长，道具的 at 表示其站立位置（底部中心）；保持离边缘 30 像素。# Title 开启一个章节，> sentence 是旁白：两者都进入下一步。点用 x,y 表示，不带空格；表达式放在引号中，可以使用参数和变量。
**它是一块黑板：章节永远不清除画布。**所有绘制的内容都会保留，就像黑板上的粉笔字，所以要在编写前规划整块黑板，为每个部分分配各自的位置——标题一次性放在顶部，挂钩和真实事物放在上半部分，想法放在其下方或旁边，收尾放在剩余位置。切勿在两个相同位置绘制不同内容；12 到 25 步通常就足够了。
开头：
title 复利 ↔ 信用卡账单
locale zh-CN
size 900x560
param taxa "月利率 (%)" 1..15 step=1 = 8
switch atraso "逾期付款" off
var f = "1 + taxa/100"
learning goal "逐月观察利滚利的增长。"
编写所有四个 learning 行 —— goal（目标）、question（一个思考题）、answer（有根据的答案）和 caveat（简化了什么）—— 并将 locale 设置为用户的语言，所有文本都使用该语言。
人物和物体是道具：person、person-sitting、person-pointing、house、car、bus、coin、phone、document、server、bank、cloud、queue、desk、computer、clock、lock、money-arrow、tree、school、hospital、factory、truck、cart、safe、bulb、gear、database、robot、ship、container、warehouse、box、pallet、shop、shelf、field、cup、function、api-gateway、cache、cluster、board、book、pencil。人物可以具有 mood=：happy、sad、surprised、worried 或 idea。
person ana at 150,330 "Ana" mood=worried
text "1000 雷亚尔变成多少？" at 40,64 size=36
text "只还最低额度" right-of ana gap 16 align=start
ana thinks "如果我逾期了呢？" side=above width=200
ana -> banco "付款" -> loja "转交"
arrow 60,350 -> 840,350 color=#2E8F62 stroke=3
highlight 90,500 -> 810,500 thickness=24
无需计算坐标即可放置——当元素并排或依次排列时优先使用这些方法。chain 是指传递某物的链条：分布在画布上，每个元素与下一个相连，如果需要，还有长箭头：
chain at 40,190 forward="咖啡下降" back="订单上升"
field fazenda "农场"
truck caminhao "运输"
cup cafe "咖啡馆"
person voce "你"
row at 470,150 gap 14
repeat 3: coin size 44
repeat 3: coin at "100 + i*60",400 size 40
从该步骤开始持续在原地移动的内容 —— spin、drive、steam（上方蒸汽）、talk、pulse 或 float，以及 stop。仅在移动有含义时使用（卡车离开、杯子上方蒸汽），每个绘画最多一两个：
animate caminhao drive
预制动画表情 —— 仅当有人要求时才使用，且每节课最多一个（它是精致的，不是粉笔风格）：celebrate、think、surprised、ok、idea 或 time，居中于 at；或 ./file.json，一个由用户提供的 Lottie 文件，与配方同级。构建会将其放入文件中，并附带其版权信息——文件大小会从约 340 KB 增加到约 610 KB（播放器和动画）：
lottie celebrate at 720,180 size=120
跟随数值的数字：
counter at 470,270 "1000*f^6" "R$ {v:0} 六个月后" size=34
bars box 90,320,440,180 values 1000,"1000*f^3","1000*f^6" labels 今天,"3 个月后","6 个月后" format="R$ {v:0}"
plot "1000*(1+taxa/100)^x" domain 0..12 range 0..4000 box 480,120,360,240
when atraso:
text "逾期罚款 2%" at 600,100 color=#C8442C
没有现成道具的物品：在 0–100 网格上制作（整数，y 向下；它位于 50,100），然后使用其名称：
define xicara
polygon 24,48 76,48 70,90 30,90 fill=#FFFFFF
curve 74,56 90,62 72,80
xicara minha at 450,300 "我的杯子"
等待用户操作，以及测验（两者均用于课堂）：
pause ask "六个月后账单会变成多少？"
quiz "如果利率翻倍，六个月后的账单……"
* 利息增长超过翻倍 —— 这是利滚利
- 只会翻倍 —— 那只是单利
保持：一块黑板 8 到 40 步；仅在想法改变时有简短旁白；标题 36 到 44，标签 24 到 34，任何内容不小于 22；颜色石墨色（默认）、#2F5BEA、#C8442C、#2E8F62、#8C8578、标记色 #FFE45C，最多三种强调色；事实和数字必须正确——切勿虚构引文或数字。其他步骤（circle、curve、card、table、axis、timeline、brace、note、move……）在 references/text.md 中；每个步骤绘制的内容在 references/recipe.md 中。仅当需要上述未提及的步骤或构建信息无法解决错误时才打开它们。
如果用户提供了 Mermaid 图，则保持原样，添加 %% title …、%% # chapter 和 %% > narration 行，并将其保存为 <id>.mmd（references/text.md 显示如何操作）。将配方保存在用户操作的文件夹中，或者当存在用于用户下载文件的输出文件夹时（在 claude.ai 上为 /mnt/user-data/outputs），保存在那里。
3. 构建和检查
node scripts/build.mjs <id>.chalk
它会在配方旁边写入 <id>.html 并打印：
✗ text: line N …或✗ contract: …（退出码 1，未写入任何内容）：根据消息指示修复该行，如下面的示例所示。! review …（退出码 3）：已绘制，但某些内容超出画布、文本重叠或线条穿过文本。修复它并使用--snapshots再次构建：它还会写入<id>.snapshots/<id>.contact-sheet.png—— 每个章节在每种数值设置下的快照。打开该图片，修复 review 中命中的问题以及任何看起来不对的内容（不明显的人物、拥挤的角落、过小的文本）。✓ review或• review … the page checks itself when opened（此处无浏览器）：完成。• figures … defined：配方使用了define制作图形，且 review 仅会测量它——打开联系表一次，检查图形是否如预期那样可辨认。✗ review not checked: …：完成，但告知用户绘画未被检查。
最多进行两轮修复；然后交付，并用简单的语言说明遗留问题（“在 15% 时，标签会碰到标题”）。
多节课（一门课程）：每节课一个配方，一起构建——node scripts/build.mjs one.chalk two.chalk --out course.html --title "课程名称"。对于 README（或仅需要图片的地方），当被要求时：node scripts/build.mjs <id>.chalk --svg 会写入 <id>.svg，一张自绘图片；课程仍然以 .html 形式存在。
4. 交付
给出 .html 的路径（或用户下载文件时的文件本身），并用一句话说明你的选择以及提供更改的选项：“我把它和信用卡账单联系起来，面向从未学习过利息的人，附带可调节的月利率——想要换个挂钩、换个受众或者做任何改动吗？”然后说一句关于看什么的话（“按“下一步”；在第 3 章，调整利率”）。该文件离线可用，包含章节、画布旁的数值，以及 PNG、SVG、GIF 和 WebM 下载——可以通过电子邮件发送或在投影仪上使用。
用于演示（演讲、投影仪上的课堂）：使用 --present 构建——页面每次只显示一章，全屏，第一页带有演讲者备注；翻页器的 PageDown 键可前进。用于 PowerPoint，当被要求时：使用 --pptx（每章一页；steps 使绘图逐点击增长，video 嵌入每章的自绘动画），旁白作为演讲者备注。
面向课堂
当绘画面向课堂、学生、演讲或课程时，一次询问，仅一条消息：最多三个挂钩，最佳优先，每个附带一句为什么适合该受众的理由（references/hooks.md），明确受众是谁，以及学生可以调节哪个数值。不要询问已经说过的话。然后以几行展示四部分大纲，等待对方同意（“可以”，“go”）。配方添加 theme chalkboard、回答该暂停问题的 pause ask，以及结尾的 quiz。
无代码执行（改用工件）
在无法运行代码但可以显示 HTML 工件的地方，将配方放在这个小型页面中——仅此而已——并显示它。播放器从 CDN 加载并自行检查配方：
<!doctype html>
<meta charset="utf-8">
<title>课程标题</title>
<script type="text/chalk-talk" id="chalk-recipe">
配方文本
</script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/player.js"></script>
如果页面显示配方无法打开，请修复它命名的行。
后续更改
“把箭头改成蓝色”、“再加一个人”、“改用 5%”：只更改被要求的部分，保留其余部分，再次构建并说明更改了什么。不同的挂钩或受众则需重新绘制。
绝对不要
- 绝不要编辑
assets/或scripts/contract.mjs：它们是自动生成的。 - 绝不要在配方中放入 HTML、链接、脚本或图片：文本是纯文本，颜色是十六进制或名称。
- 绝不要编写脚本来生成配方：自己编写（表达式和
repeat处理算术）。 - 没有代码执行时，绝不要手写播放器、SVG 或绘画图片：使用上面的小型页面。如果既不能运行代码也不能显示工件，请说明情况并提供配方。