lesson-screen

课程屏幕

课程屏幕由一个小型本地 Web 服务和一个浏览器标签页组成。导师继续在终端中授课。每个步骤都会将一个屏幕写入文件夹，浏览器则显示最新的屏幕。学习者可以选择选项并点击各个部分。这些点击会记入事件日志，导师会在下一次回复前读取日志。

将此技能与 Claude、Cursor、Codex、OpenClaw、Hermes，或任何会读取 SKILL.md 的 Agent 配合使用。需要 Node.js 20 或更高版本，以及同一台机器上的浏览器。不会安装任何软件包。

适用场景

• 课程导师授课，学习者接受屏幕。相关导师包括 learn、learn-mcp、learn-agent-skills、learn-reverse-engineering、claude-certification 和 mcpa-certification。
• 学习者要求查看课程、概念或系统：“给我看看”“画出来”“用 3D 展示”。
• 某个概念具有结构、流程或会变化的数值。直观展示比阅读更有帮助。

不适用场景

• 学习者拒绝了屏幕。本次会话中不要再次提供。
• 学习者无法从主机访问浏览器页面：例如使用聊天应用，或在没有端口转发的远程机器上。提供 aiengineeringfromscratch.com 上的课程页面。references/hosts.md 列出了相关情况。
• 当前步骤只有文字：澄清问题、权衡取舍或定义。继续在终端中进行，并显示等待屏幕。
• 你需要为课程文件制作永久图示。请直接使用图示技能。此技能生成的是供单个学习者使用的屏幕。

路径

SKILL_ROOT 是存放此 SKILL.md 的文件夹。在此文件中，CLI 指 node "$SKILL_ROOT/scripts/lesson-screen.mjs"。

从学习者的工作文件夹运行所有命令。屏幕存放在 .lesson-screen/screens/，构建产物存放在 .lesson-screen/builds/。如果该文件夹是 git 仓库，请让学习者将 .lesson-screen/ 添加到 .gitignore。

启动

1. 运行 CLI start --open。它会输出一行包含 url、screens、state 和 next 的 JSON。
2. 将完整的 url（包括查询字符串）发给学习者。其中的密钥用于保护页面。
3. 随时再次运行 CLI start。它会复用正在运行的服务，并保持端口不变。
4. 如果启动失败，用一行话说明。提供课程页面链接并继续授课。

某些主机会在命令返回后结束后台进程。这些主机需要使用 --foreground 和自己的后台 shell 选项。请参阅 references/hosts.md。

教学循环

1. 每次回复前，运行 CLI events。它会输出自上次调用以来的点击记录。将它们作为提示。
2. 将下一个屏幕写入 <screens>/<next>-<slug>.html。从 start 或 CLI status 获取 next。
3. 不要重复使用文件名。浏览器会显示最新的文件。
4. 用一行话告诉学习者屏幕展示了什么，并在终端中让学习者作答。
5. 如果下一步只有文字，就写一个等待屏幕。

使用文件工具编写屏幕。不要用 cat 或 heredoc 将屏幕内容打印到终端。

每个步骤要展示的内容

导师步骤	屏幕	信息来源
梳理问题	步骤导航条和一张包含课程问题的卡片	docs/en.md
核心概念	课程已注册的图示，并设置为你正在讲解的示例	docs/en.md 中的 figure 代码围栏
构建过程	代码跟踪：代码块、当前行、变量	实际运行课程代码的结果
使用方法	并排展示库调用和临时代码调用，并保持输出相同	课程代码及其输出
查看成果	为本课程构建的图示	图示技能、课程文本和实际运行结果
预测或测验	将问题和选项作为按钮展示	quiz.json，不包含答案

references/screens.md 列出了每个类，并提供了每种屏幕的完整示例。

优先使用已注册的图示

大多数课程已经有交互式图示。构建新图示之前，先查找现有图示。

1. 搜索课程的 docs/en.md，查找语言标记为 figure 的围栏代码块。
2. 将围栏代码块的第一行放入宿主元素：<div class="lesson-figure" data-figure="kv-cache-sizer"></div>。
3. 如果围栏代码块中有 JSON 配置，就保留它，例如 data-figure='iso-machine {"machine":"kv-cache"}'。
4. 只有围栏代码块中已有的键才能用于更改配置值。

屏幕会加载课程图示运行时并挂载图示。图示的外观和工作方式与课程页面中的一致。

即时构建图示

最适合某节课的图示，是专为该课制作的图示。在教学过程中构建图示，让它在“看看效果”环节就绪。

1. 课程开始时，阅读 docs/en.md 并运行课程代码。
2. 用一句话描述课程中的系统：“X 经过 Y 移动，而这种运动意味着 Z。”
3. 从下表中选择一种形式。说明所需时间，并在学习者同意后再构建。
4. 编写构建界面，并及时更新其阶段列表。
5. 如果宿主环境能够运行第二个 Agent，就把构建任务交给它。继续在终端中教学。
6. 如果没有第二个 Agent，就在实验或测验期间构建，或者提出在课程结束时提供图示。
7. 使用 CLI shot 检查构建结果。查看每张图片，并修复所有看起来不对的地方。
8. 运行 CLI publish <page.html>。该页面会成为下一个屏幕。

形式	使用什么来构建	时间	适用情况
蓝图	blueprint-figure skill	5 到 10 分钟	概念是由命名部件组成的结构
机制图	motion-figure skill 的第 2 级	15 到 25 分钟	一个控件会改变计算结果
等距机器图	isometric-explainer skill	40 到 90 分钟	概念是一个包含站点、顺序和故障的流程
3D 模型	已安装且支持 3D 模式的图示 skill，或 three.js	60 到 120 分钟	概念的关键在于深度或旋转，或者学习者要求使用 3D

优先提供能展示概念的最简形式。当学习者有时间且想要更多内容时，再提供更复杂的形式。

references/build.md 包含构建阶段、页面约定、制作规则和 3D 规则。每次构建前都要阅读。

图示 skills

课程图示 skills 包括 blueprint-figure、motion-figure、isometric-explainer 和 course-style。如果未安装其中某个 skill，请从 https://raw.githubusercontent.com/rohitg00/ai-engineering-from-scratch/main/skills/<name>/ 读取其文件。

宿主环境可能安装了更多图示 skills，例如带有 3D 模式或 WebGL 效果的等距插画 skill。选择形式前，先检查宿主环境的 skill 列表。适合所选形式时，可使用这些 skill，但必须遵守本 skill 的真实性规则和页面约定。

课程后的练习

CLI practice <lesson-path> 会为一节课生成练习页面，作为下一个屏幕。页面包含四个部分：

• 简介：引入内容、学习目标，以及一张包含关键术语的卡片；按下卡片时会显示术语含义。
• 练习：来自 quiz.json 的问题，使用 1 到 4 键作答，按 Enter 进入下一题，并可选择启用计时器。
• 复习：答错的问题会在 1、3、7 和 16 天后再次出现。
• 深入学习：课程页面、课程文件夹、运行课程代码的命令、一道练习题和延伸阅读。

请遵守以下规则：

• 只有在导师完成该课程自己的测验后，才提供练习页面。答案会保存在页面中。
• 页面会自行评分，并在浏览器中保存进度。不要从页面记录任何信息。页面不会更改分数、复习队列或任何证据。
• 页面从克隆仓库读取课程；没有克隆仓库时则从 GitHub 读取。
• 没有 quiz.json 的课程，会根据其“关键术语”表生成问题。

真实性规则

• 绝不编造数字。读数、标签和步骤文本必须来自课程文本或真实运行结果。
• 带有动态效果的构建图示使用经过测试的小型状态模型。该模型会移动各个部件并写入读数。
• 在学习者作答前，绝不在屏幕上显示正确答案、答案序号或解释。学习者可以查看页面源代码。练习页面是唯一例外，且只会在导师测验后显示。
• 点击只是提示，绝不算作测验答案、检查点证据或实验结果。
• 进度、分数和证据由导师自身的规则决定。
• 每个构建图示都显示一行文字，说明该图示由你的导师为本课程构建，课程作者未对其进行审核。
• 每个模拟值或缩放值都必须在页面上注明。

事件

CLI events 会打印 {"type":"events","events":[...]}。每个事件都包含 type、screen 和 at，以及以下字段。

type	Fields	Meaning
choice	question、choice、text	学习者按下了某个选项
part	part、label	学习者询问构建图示中的某个部件
step	step、label	学习者切换到构建图示的某个步骤
note	text	来自自定义屏幕的自由备注

CLI events --all 会打印所有事件，并保留读取位置。

停止并保留

• 课程结束时运行 CLI stop，除非下一节课程现在就要开始。
• 服务空闲两小时后会自动停止。
• 构建的页面从磁盘打开。只有通过服务才能向导师提问。
• 将学习者想要保留的构建内容及其源文件复制到 learning-artifacts/<phase>-<lesson>/。

命令

Command	Does
start [--open] [--foreground] [--port N] [--host H] [--url-host H] [--assets live|local] [--repo PATH] [--idle-minutes N]	启动服务，或复用正在运行的服务
status	打印 running、url、screens、latest、next 和未读事件数
events [--all]	打印新事件
publish FILE [--name SLUG]	将构建的页面复制到 screens 文件夹，作为下一屏幕
practice LESSON [--repo PATH] [--name SLUG]	为课程路径生成练习页面，作为下一屏幕
shot TARGET [--width N] [--height N] [--theme light|dark] [--wait MS] [--out FILE] [--chrome PATH]	使用本地 Chrome、Chromium 或 Edge 截取屏幕名称或页面文件的图像
stop	停止服务

每条命令都可使用 --dir PATH 指定其他会话文件夹。每条命令都会打印一行 JSON。错误以 JSON 形式输出到 stderr，退出代码为 1。

默认情况下，屏幕会从 aiengineeringfromscratch.com 加载图示运行时。--assets local 会从克隆仓库的 site/ 文件夹加载。请先在该克隆仓库中运行 node site/build.js。

完成前检查

• 学习者已获得包含密钥的完整 URL，或课程页面链接。
• 每次回复前都已读取事件。
• 每个屏幕都与终端中讲解的步骤一致。
• 没有屏幕在学习者作答前显示答案。
• 构建图示中的每个数字都来自课程内容或真实运行结果。
• 发布前已查看每个构建内容在两种主题下的 CLI shot 图像。
• 已停止服务，或已告知学习者服务会继续运行。