lesson-screen

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Lesson screen

课程屏幕

The lesson screen is a small local web server and one browser tab. The tutor keeps teaching in the terminal. At each step it writes one screen into a folder, and the browser shows the newest screen. The learner can press options and click parts. Those clicks go to an event log that the tutor reads before its next reply.

Use this skill with Claude, Cursor, Codex, OpenClaw, Hermes, or any agent that reads SKILL.md. It needs Node.js 20 or later and a browser on the same machine. It installs no packages.

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

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

When to use

何时使用

A course tutor teaches a lesson, and the learner accepts the screen. The tutors are learn, learn-mcp, learn-agent-skills, learn-reverse-engineering, claude-certification, and mcpa-certification.
The learner asks to see a lesson, a concept, or a system: "show me", "draw it", "in 3D".
A concept has a structure, a flow, or a number that changes. Seeing it helps more than reading it.

课程导师正在讲授课程，且学习者接受使用屏幕页面。可使用的导师包括 learn、learn-mcp、learn-agent-skills、learn-reverse-engineering、claude-certification 和 mcpa-certification。
学习者要求查看课程、概念或系统：“给我看看”“画出来”“用 3D 展示”。
某个概念具有结构、流程或会变化的数字。将其可视化比单纯阅读更有帮助。

When not to use

何时不应使用

The learner declined the screen. Do not offer it again this session.
The learner cannot reach a browser page from the host: a chat app, or a remote machine without port forwarding. Give the lesson page on aiengineeringfromscratch.com.
```
references/hosts.md
```
lists the cases.
The step is words only: a clarifying question, a tradeoff, or a definition. Keep it in the terminal and show the waiting screen.
You need a permanent figure for a lesson file. Use the figure skills directly. This skill makes screens for one learner.

学习者拒绝使用屏幕页面。本会话中不要再次提供。
学习者无法从宿主访问浏览器页面，例如通过聊天应用访问，或使用未配置端口转发的远程机器。此时应提供 aiengineeringfromscratch.com 上的课程页面。
```
references/hosts.md
```
列出了适用情况。
当前步骤只有文字，例如澄清问题、权衡取舍或定义。应在终端中继续，并显示等待页面。
需要为课程文件创建永久图形时，应直接使用 figure skills。本 skill 用于为单个学习者生成屏幕页面。

Paths

路径

SKILL_ROOT

is the folder that holds this SKILL.md. In this file,

CLI

means

node "$SKILL_ROOT/scripts/lesson-screen.mjs"

Run every command from the learner's working folder. Screens go to

.lesson-screen/screens/

, and builds go to

.lesson-screen/builds/

. If the folder is a git repository, ask the learner to add

.lesson-screen/

.gitignore

SKILL_ROOT

是包含此 SKILL.md 的文件夹。在本文件中，

CLI

表示

node "$SKILL_ROOT/scripts/lesson-screen.mjs"

。

所有命令都应在学习者的工作文件夹中运行。屏幕页面写入

.lesson-screen/screens/

，构建产物写入

.lesson-screen/builds/

。如果该文件夹是 Git 仓库，请让学习者将

.lesson-screen/

添加到

.gitignore

。

Start

启动

Run
```
CLI start --open
```
. It prints one JSON line with
```
url
```
,
```
screens
```
,
```
state
```
, and
```
next
```
.
Give the learner the full
```
url
```
with its query string. The key in it protects the page.
Run
```
CLI start
```
again at any time. It reuses a running server and keeps the same port.
If the start fails, say so in one line. Give the lesson page link and keep teaching.

Some hosts end background processes when a command returns. Those hosts need

--foreground

and their own background shell option. See

references/hosts.md

运行
```
CLI start --open
```
。它会输出一行 JSON，其中包含
```
url
```
、
```
screens
```
、
```
state
```
和
```
next
```
。
将带有完整查询字符串的
```
url
```
提供给学习者。URL 中的密钥用于保护页面。
之后可随时再次运行
```
CLI start
```
。它会复用正在运行的服务器，并保持相同端口。
如果启动失败，用一行说明失败原因。提供课程页面链接，并继续授课。

有些宿主会在命令返回时终止后台进程。这些宿主需要使用

--foreground

，并搭配其自带的后台 shell 选项。请参阅

references/hosts.md

。

The teaching loop

教学循环

Before each reply, run
```
CLI events
```
. It prints the clicks since the last call. Treat them as hints.

Write the next screen to

<screens>/<next>-<slug>.html

. Take

next

from

start

CLI status

Never reuse a file name. The browser shows the newest file.
Tell the learner in one line what the screen shows. Ask for the answer in the terminal.
When the next step is words only, write a waiting screen.

Write screens with your file tool. Do not print them to the terminal with

cat

or a heredoc.

每次回复前，运行
```
CLI events
```
。它会输出自上次调用以来的点击事件。将这些事件视为提示。
将下一个屏幕页面写入
```
<screens>/<next>-<slug>.html
```
。从
```
start
```
或
```
CLI status
```
获取
```
next
```
。
绝不要重复使用文件名。浏览器会显示最新文件。
用一行说明屏幕页面展示的内容，并请学习者在终端中作答。
如果下一步只有文字，请编写一个等待页面。

使用文件工具编写屏幕页面。不要通过

cat

或 heredoc 将其打印到终端。

What to show at each step

每个步骤应展示的内容

Tutor step	Screen	Source of truth
Frame the problem	a step rail and a card with the lesson question	`docs/en.md`
Core concept	the lesson's registered figure, set to the example you discuss	the `figure` fences in `docs/en.md`
Build it	a code trace: the chunk, the active line, the variables	a real run of the lesson code
Use it	the library call beside the scratch call, with the same output	the lesson code and its output
See it	the figure that you built for this lesson	the figure skills, the lesson text, and the real run
Prediction or quiz	the question and its options as buttons	`quiz.json` , without the answer

references/screens.md

lists every class, with a full example of each screen.

导师步骤	屏幕页面	事实依据
明确问题	步骤导航栏和一张包含课程问题的卡片	`docs/en.md`
核心概念	课程已注册的图形，并设置为当前讨论的示例	`docs/en.md` 中的 `figure` 围栏块
构建它	代码跟踪：代码块、活动行和变量	课程代码的实际运行结果
使用它	将库调用与临时调用并排展示，并显示相同输出	课程代码及其输出
直观呈现	为本课程构建的图形	figure skills、课程文本和实际运行结果
预测或测验	问题及以按钮呈现的选项	`quiz.json` ，不包含答案

references/screens.md

列出了所有屏幕类，并提供每种屏幕页面的完整示例。

Registered figures first

优先使用已注册图形

Most lessons already have interactive figures. Look for them before you build anything new.

Search the lesson's
```
docs/en.md
```
for fenced blocks with the language
```
figure
```
.

Put the first line of the fence in a host element:

<div class="lesson-figure" data-figure="kv-cache-sizer"></div>

Keep the JSON config of the fence if it has one, as in
```
data-figure='iso-machine {"machine":"kv-cache"}'
```
.
Change a config value only with a key that the fence already uses.

The screen loads the course figure runtime and mounts the figure. The figure looks and works as it does on the lesson page.

大多数课程已经包含交互式图形。在构建任何新图形之前，先查找这些图形。

在课程的
```
docs/en.md
```
中搜索语言为
```
figure
```
的围栏块。

在宿主元素中放置围栏块的第一行：

<div class="lesson-figure" data-figure="kv-cache-sizer"></div>

。

如果围栏块包含 JSON 配置，请保留该配置，例如
```
data-figure='iso-machine {"machine":"kv-cache"}'
```
。
只能使用围栏块中已经存在的键修改配置值。

屏幕页面会加载课程图形运行时并挂载图形。其外观和功能与课程页面上的图形一致。

Build a figure on the fly

实时构建图形

The best figure for a lesson is one made for that lesson. Build it while you teach, so that it is ready at the See it step.

When the lesson starts, read
```
docs/en.md
```
and run the lesson code.
Name the lesson's system in one sentence: "X moves through Y, and that motion means Z."
Pick one form from the table below. Offer it with its time, and build only after the learner accepts.
Write a building screen and keep its stage list current.
Give the build to a second agent when the host can run one. Keep teaching in the terminal.
Without a second agent, build during the lab or the quiz, or offer the figure for the end of the session.
Check the build with
```
CLI shot
```
. Look at every image and fix what looks wrong.
Run
```
CLI publish <page.html>
```
. The page becomes the next screen.

Form	Build it with	Time	Pick it when
Blueprint	the blueprint-figure skill	5 to 10 minutes	the idea is a structure with named parts
Mechanism	tier 2 of the motion-figure skill	15 to 25 minutes	one control changes a computed result
Isometric machine	the isometric-explainer skill	40 to 90 minutes	the idea is a process with stations, order, and failures
3D model	an installed figure skill with a 3D mode, or three.js	60 to 120 minutes	depth or rotation is the idea, or the learner asks for 3D

Offer the smallest form that shows the idea. Offer a larger form when the learner has time and asks for more.

references/build.md

holds the build stages, the page contract, the craft rules, and the 3D rules. Read it before every build.

最适合课程的图形，是专门为该课程制作的图形。在授课过程中构建它，以便在“直观呈现”步骤准备好。

课程开始时，读取
```
docs/en.md
```
并运行课程代码。
用一句话概括课程中的系统：“X 在 Y 中移动，而这种运动意味着 Z。”
从下表中选择一种形式。向学习者提供该形式并告知耗时，只有在学习者接受后才开始构建。
编写构建屏幕页面，并持续更新其阶段列表。
如果宿主可以运行第二个 Agent，则将构建任务交给它，同时继续在终端中授课。
如果没有第二个 Agent，则在实验或测验期间构建，或提议在本次课程结束时提供图形。
使用
```
CLI shot
```
检查构建结果。查看每张图片，并修正看起来有误的部分。
运行
```
CLI publish <page.html>
```
。该页面将成为下一个屏幕页面。

形式	构建工具	耗时	选择条件
蓝图	blueprint-figure skill	5 至 10 分钟	概念是由命名部件组成的结构
机构	motion-figure skill 的第 2 层	15 至 25 分钟	一个控制项会改变计算结果
等距机器	isometric-explainer skill	40 至 90 分钟	概念是由工位、顺序和故障构成的过程
3D 模型	带有 3D 模式的已安装 figure skill，或 three.js	60 至 120 分钟	重点在于深度或旋转，或者学习者要求使用 3D

应提供能够展示概念的最简形式。当学习者有时间并要求更多内容时，可以提供更复杂的形式。

references/build.md

包含构建阶段、页面契约、制作规范和 3D 规则。每次构建前都要阅读它。

Figure skills

The course figure skills are blueprint-figure, motion-figure, isometric-explainer, and course-style. If one is not installed, read its files from

https://raw.githubusercontent.com/rohitg00/ai-engineering-from-scratch/main/skills/<name>/

The host can have more figure skills installed, such as an isometric illustration skill with a 3D mode or WebGL effects. Check the host's skill list before you pick a form. Use such a skill when it fits the form, and keep the truth rules and the page contract of this skill.

课程 figure skills 包括 blueprint-figure、motion-figure、isometric-explainer 和 course-style。如果其中某个 skill 尚未安装，请从

https://raw.githubusercontent.com/rohitg00/ai-engineering-from-scratch/main/skills/<name>/

读取其文件。

宿主还可以安装更多 figure skills，例如带 3D 模式或 WebGL 效果的等距插图 skill。选择形式前应检查宿主的 skill 列表。当这些 skill 与所需形式匹配时应使用它们，同时继续遵循本 skill 的真实性规则和页面契约。

Practice after the lesson

课程后的练习

CLI practice <lesson-path>

writes a practice page for one lesson as the next screen. It has four parts:

Brief: the hook, the learning objectives, and a card for each key term that shows its meaning on a press.
Drill: the questions from
```
quiz.json
```
, with keys 1 to 4, Enter for the next question, and an optional timer.
Review: missed questions return after 1, 3, 7, and 16 days.
Go deeper: the lesson page, the lesson folder, the command that runs its code, one exercise, and further reading.

Follow these rules:

Offer practice only after the tutor's own quiz for the lesson is complete. The page holds the answer key.
The page grades itself and keeps its progress in the browser. Record nothing from it. It never changes a score, a review queue, or any evidence.
It reads the lesson from the clone, or from GitHub when there is no clone.
A lesson without
```
quiz.json
```
gets questions made from its Key Terms table.

CLI practice <lesson-path>

会为一节课程生成练习页面，并将其作为下一个屏幕页面。页面包含四个部分：

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

遵循以下规则：

只有在导师自带的课程测验完成后，才能提供练习。页面中包含答案键。
页面会自行评分，并在浏览器中保存进度。不从中记录任何内容。它绝不改变分数、复习队列或任何学习证据。
它从 clone 中读取课程；如果没有 clone，则从 GitHub 读取。
没有
```
quiz.json
```
的课程，会根据其 Key Terms 表生成问题。

Truth rules

真实性规则

Never invent a number. Readouts, labels, and step text come from the lesson text or a real run.
A built figure with motion uses a small tested state model. The model moves the parts and writes the readouts.
Never put a correct answer, an answer index, or an explanation on a screen before the learner answers. The learner can read the page source. The practice page is the one exception, and it appears only after the tutor's quiz.
A click is a hint. It never counts as a quiz answer, checkpoint evidence, or a lab result.
The tutor's own rules decide progress, scores, and evidence.
Every built figure shows a line that says your tutor built it for this lesson and the course authors did not review it.
Every simulated or scaled value says so on the page.

绝不编造数字。读数、标签和步骤文案必须来自课程文本或实际运行结果。
带有运动效果的构建图形使用小型且经过测试的状态模型。模型负责移动部件并生成读数。
在学习者作答前，绝不在屏幕上放置正确答案、答案索引或解释，因为学习者可以查看页面源代码。练习页面是唯一的例外，并且只会在导师的测验完成后出现。
点击只是一种提示，绝不计入测验答案、检查点证据或实验结果。
进度、分数和证据均由导师自身的规则决定。
每个构建的图形都必须显示一行说明：“你的导师为本课程构建了此图形，课程作者未对其进行审阅。”
每个模拟值或缩放值都必须在页面上明确注明。

Events

事件

CLI events

prints

{"type":"events","events":[...]}

. Each event has

type

screen

, and

at

, plus the fields below.

type	Fields	Meaning
`choice`	`question` , `choice` , `text`	The learner pressed an option
`part`	`part` , `label`	The learner asked about a part of a built figure
`step`	`step` , `label`	The learner moved to a step of a built figure
`note`	`text`	A free note from a custom screen

CLI events --all

prints every event and keeps the read position.

CLI events

会打印

{"type":"events","events":[...]}

。每个事件都包含

type

、

screen

和

at

，以及下表中的字段。

type	字段	含义
`choice`	`question` 、 `choice` 、 `text`	学习者按下了某个选项
`part`	`part` 、 `label`	学习者询问了构建图形中的某个部件
`step`	`step` 、 `label`	学习者切换到了构建图形中的某个步骤
`note`	`text`	学习者通过自定义屏幕页面留下了自由备注

CLI events --all

会打印所有事件，并保持当前读取位置不变。

Stop and keep

停止与保留

Run
```
CLI stop
```
when the lesson ends, unless the next lesson starts now.
The server stops by itself after two idle hours.
Built pages open from disk. Questions to the tutor work only through the server.
Copy the builds that the learner wants to keep to
```
learning-artifacts/<phase>-<lesson>/
```
, with their source.

课程结束时运行
```
CLI stop
```
，除非下一节课会立即开始。
服务器会在闲置两小时后自动停止。
构建后的页面从磁盘打开。只有通过服务器才能向导师发送问题。
将学习者希望保留的构建产物连同源文件复制到
```
learning-artifacts/<phase>-<lesson>/
```
。

Commands

命令

Command	Does
`start [--open] [--foreground] [--port N] [--host H] [--url-host H] [--assets live\|local] [--repo PATH] [--idle-minutes N]`	Starts the server, or reuses a running one
`status`	Prints `running` , `url` , `screens` , `latest` , `next` , and the unread event count
`events [--all]`	Prints new events
`publish FILE [--name SLUG]`	Copies a built page into the screens folder as the next screen
`practice LESSON [--repo PATH] [--name SLUG]`	Writes a practice page for a lesson path as the next screen
`shot TARGET [--width N] [--height N] [--theme light\|dark] [--wait MS] [--out FILE] [--chrome PATH]`	Takes a screenshot of a screen name or a page file with a local Chrome, Chromium, or Edge
`stop`	Stops the server

Every command takes

--dir PATH

for another session folder. Every command prints one JSON line. Errors go to stderr as JSON, with exit code 1.

By default the screen loads the figure runtime from aiengineeringfromscratch.com.

--assets local

loads it from the

site/

folder of a clone. Run

node site/build.js

in that clone first.

命令	作用
`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]`	将构建好的页面复制到屏幕文件夹，作为下一个屏幕页面
`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

时，会从 clone 的

site/

文件夹加载它。首先在该 clone 中运行

node site/build.js

。

Check before you finish

完成前检查

The learner got the full URL with its key, or the lesson page link.
You read events before each reply.
Each screen matches the step that you teach in the terminal.
No screen holds an answer before the learner answers.
Every number on a built figure comes from the lesson or a real run.
You looked at
```
CLI shot
```
images of each build in both themes before you published it.
You stopped the server, or told the learner that it stays up.

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