isometric-explainer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Isometric Explainer

等距图解释器

This skill makes a single-page interactive figure. The figure is a solid isometric machine on a bench. Each station of the machine stands for one step of a process. For example, a request card moves on a carriage, a probe drops, and a press stamps the card. A pure state model decides every move, so the picture, the numbers and the words match. The

templates/

folder holds a working starter, and

kit/

holds the geometry library it uses.

该 skill 用于制作单页交互式图示。图示是一台放置在工作台上的实体等距机器。机器的每个工位都代表流程中的一个步骤。例如，请求卡在 carriages 上移动，探针下降，压机在卡片上盖章。纯状态模型决定每一次动作，因此图示、数字和文字始终保持一致。

templates/

文件夹包含一个可运行的 starter，

kit/

文件夹包含所使用的几何库。

When to use

何时使用

The concept is a process with stations, order and failure modes: a loop, a pipeline, a cache, a queue, a retry policy.
The reader can break one part and see what fails.
The figure is the main content of a page.

概念是一个包含工位、顺序和故障模式的过程：循环、流水线、缓存、队列或重试策略。
读者可以破坏某个部件，并观察会发生什么故障。
图示是页面的主要内容。

When not to use

何时不使用

A static diagram explains the idea. Make a flat SVG figure instead.
The concept has no order or state change. Make a static figure instead.
The figure is a small diagram inside a lesson or a README. Use the sibling skill
```
blueprint-figure
```
.
You cannot write a deterministic model of the behavior. Do not animate a guess.
The job needs more than 150 parts and the user has not approved the size.

静态图示足以解释该概念。此时请制作平面 SVG 图。
概念不包含顺序或状态变化。此时请制作静态图示。
图示只是课程或 README 中的小型图表。请使用同级 skill
```
blueprint-figure
```
。
无法为行为编写确定性模型。不要为猜测制作动画。
任务需要超过 150 个部件，且用户尚未批准该规模。

Method

方法

Invent the machine. Write one sentence: "X moves through Y, and that motion means Z." If you cannot write it, pick another machine. See
```
references/concept.md
```
.
Count the parts on paper before you draw, and pick a tier.

Tier Parts Approval
Figure 40 to 80 not needed
Hero 80 to 150 not needed
Larger more than 150 get the user's approval first
Write the state model first. Make
```
model.mjs
```
pure and deterministic, with no DOM and no clock.
```
simulate(config)
```
returns an event list and totals. Test it before any geometry. See
```
references/state-model.md
```
.
Map each concept to a station. Write a table: station, concept word for its nameplate, what it does, what fails without it.
Write the parts list. List each part with its assembly, size in world units, tone and whether it moves. Geometry comes after the list.
Set the camera. Use world units and one isometric camera. Set elevation to 30 degrees. Pick the azimuth so the working faces point at the viewer. Fit the projection over the assembled and the exploded pose.
Build the static geometry once. Each part becomes one SVG group with a depth key. Movers get a
```
data-live
```
hook. See
```
references/geometry.md
```
.
Animate by translation. Move a part by changing its
```
transform
```
only. Rebuild a path only when its shape changes, such as a rod that gets longer.
Paint from back to front. Sort groups by depth key plus the depth of their current offset. Reorder the DOM only when the order changes.
Use one accent colour. Exactly one accent colour marks the active part and its nameplate. Everything else uses four grey shades and four line tones.
Add controls that change the model. Run, step, break, repair, reset and the config switches all act on a real
```
simulate
```
run. Write the config to the URL. See
```
references/live.md
```
.
Verify the page in a headless browser. Take screenshots at desktop and phone width in both themes. Add 4x close-ups, a line-end check, a scenario sweep with zero console errors and a contact sheet. See
```
references/verify.md
```
.

Tier	Parts	Approval
Figure	40 to 80	not needed
Hero	80 to 150	not needed
Larger	more than 150	get the user's approval first

发明这台机器。写一句话：“X 穿过 Y，而这种运动意味着 Z。”如果无法写出这句话，请换一台机器。参见
```
references/concept.md
```
。
绘制前先在纸上统计部件数量，并选择一个层级。

层级部件数量审批
Figure 40 到 80 无需审批
Hero 80 到 150 无需审批
Larger 超过 150 必须先获得用户批准
首先编写状态模型。让
```
model.mjs
```
保持纯粹且确定性，不依赖 DOM 和时钟。
```
simulate(config)
```
返回事件列表和汇总数据。在编写任何几何内容之前先进行测试。参见
```
references/state-model.md
```
。
将每个概念映射到一个工位。编写一张表：工位、铭牌使用的概念词、它执行的操作，以及缺少它时会出现什么故障。
编写部件列表。列出每个部件的装配结构、以世界单位表示的尺寸、色调以及是否会移动。几何内容应在列表之后编写。
设置相机。使用世界单位和一个等距相机。将仰角设为 30 度。选择方位角，使工作面朝向观察者。调整投影，使其同时适配装配态和爆炸态。
只构建一次静态几何。每个部件对应一个带 depth key 的 SVG group。运动部件设置
```
data-live
```
hook。参见
```
references/geometry.md
```
。
通过平移进行动画。移动部件时只更改其
```
transform
```
。仅在形状发生变化时重新构建路径，例如杆件变长的情况。
从后向前绘制。按照 depth key 与当前偏移深度对 group 排序。仅在顺序发生变化时重新排列 DOM。
使用一种强调色。任意时刻恰好只有一种强调色，用于标记当前活动部件及其铭牌。其他所有内容使用四种灰阶和四种线条色调。
添加会改变模型状态的控件。run、step、break、repair、reset 以及所有配置开关都必须作用于真实的
```
simulate
```
运行。将配置写入 URL。参见
```
references/live.md
```
。
在无头浏览器中验证页面。分别以桌面和手机宽度、明暗两种主题截取屏幕截图。添加 4 倍特写、线端检查、零控制台错误的场景扫描以及一张接触印相表。参见
```
references/verify.md
```
。

层级	部件数量	审批
Figure	40 到 80	无需审批
Hero	80 到 150	无需审批
Larger	超过 150	必须先获得用户批准

Rules

规则

Truth:

The state model is the single source of truth. Motion, readouts, trace lines and outcome text all come from its events.
```
simulate
```
with the same config returns the same events. A test proves this for every config combination.
Never fake a real model, a real service or real metrics. A scripted part says "fixed script" in the page copy.
Every page with simulated timing shows a sentence that starts "This is a simulation." and says that times are fixed costs, not measurements.
Use real arithmetic in the model. Tests assert the exact numbers that the page prints.

Geometry:

All coordinates are world units. Pixels appear only in the projection.
Elevation is 30 degrees. The azimuth is one fixed value for the whole page. The reference page uses 60.
Solids use four shade bands and an outline. Lines use the tones
```
hi
```
,
```
mid
```
,
```
lo
```
and
```
faint
```
.
Every line ends on a solid or on another line. A line with a deliberate loose end carries
```
data-free="start"
```
,
```
"end"
```
or
```
""
```
.
Each station carries an engraved nameplate with its concept word in capitals, such as
```
CACHE
```
or
```
VERIFIER
```
.
A part that rests on another part gets a depth bias so it paints after its support.

Motion:

Movers change
```
transform
```
only. A path that changes shape is rebuilt from cached results where it can be.
One beat lasts 0.1 to 1.3 seconds. Travel time grows with distance.
Explode uses a spring with stiffness 64, damping 14.2 and a 0.04 s stagger per assembly.
Clamp the frame step to 1/20 s so a slow frame never skips a beat.
With reduced motion, runs advance 40 times faster and explode snaps to its end pose.
The animation loop stops when the stage is off screen and when nothing moves.

Page:

The workbench fits one screen at desktop width: toolbar, stage and readouts in
```
100svh
```
.
At phone width the page stacks and never scrolls sideways.
Buttons are at least 44 px tall. The stage takes focus and has keyboard keys for run, step, explode, break and repair.
The SVG has
```
role="img"
```
and an
```
aria-label
```
that names every station.
An
```
aria-live="polite"
```
region announces the outcome when a run ends.

真实性：

状态模型是唯一的事实来源。运动、读数、轨迹线和结果文本都来自其事件。
使用相同配置调用
```
simulate
```
会返回相同事件。测试需证明每一种配置组合都满足这一规则。
绝不能伪造真实模型、真实服务或真实指标。脚本化部件必须在页面文案中标明“fixed script”。
每个包含模拟计时的页面都必须显示一句以
```
This is a simulation.
```
开头的说明，并指出其中的时间表示固定成本，而不是测量值。
模型中使用真实的算术运算。测试必须断言页面所显示数字的精确值。

几何：

所有坐标均使用世界单位。像素仅用于投影。
仰角为 30 度。整页使用一个固定方位角。参考页面使用 60 度。
实体使用四级明暗色带和轮廓线。线条使用
```
hi
```
、
```
mid
```
、
```
lo
```
和
```
faint
```
色调。
每条线都终止于实体或另一条线上。有意保留的悬空线端必须带有
```
data-free="start"
```
、
```
"end"
```
或
```
""
```
。
每个工位都有一块刻有概念词的铭牌，概念词使用大写字母，例如
```
CACHE
```
或
```
VERIFIER
```
。
放置在其他部件上的部件需要设置 depth bias，以便在其支撑部件之后绘制。

运动：

运动部件只更改
```
transform
```
。形状发生变化的路径在可行情况下通过缓存结果重新构建。
一个节拍持续 0.1 到 1.3 秒。移动时间随距离增加。
explode 使用弹簧动画，刚度为 64、阻尼为 14.2，每个装配体的启动间隔为 0.04 s。
将帧步长限制为 1/20 s，避免较慢的帧跳过节拍。
启用减少动态效果时，运行推进速度提高 40 倍，explode 直接切换到最终姿态。
当舞台不在视口内或没有任何对象移动时，动画循环停止。

页面：

在桌面宽度下，工作台内容适配一屏：toolbar、stage 和读数区域共同使用
```
100svh
```
。
在手机宽度下，页面纵向堆叠，且绝不出现横向滚动。
按钮高度至少为 44 px。stage 可获得焦点，并提供用于 run、step、explode、break 和 repair 的键盘按键。
SVG 使用
```
role="img"
```
，其
```
aria-label
```
会列出每个工位的名称。
```
aria-live="polite"
```
区域会在一次运行结束时播报结果。

Check before you finish

完成前检查

The one-sentence machine statement is written in the page copy or the build notes.
The part count matches the approved tier.
Model tests pass, including a sweep over every config combination.
The page is the output of the build script. Rebuilding produces no diff.
Every config control calls
```
simulate
```
and updates the URL.
Opening the URL with
```
?
```
parameters restores the same config.
Exactly one accent colour shows at any moment, and it follows the active part.
Every station shows a readable nameplate in both themes and at phone width.
The line-end check reports zero loose ends.
The scenario sweep runs every config to the end with zero console errors.
Desktop and phone screenshots in light and dark show no clipping and no horizontal scroll.
The exploded pose stays inside the stage.
The simulation sentence is on the page.

一句话的机器说明已写入页面文案或构建备注。
部件数量与获批的层级一致。
模型测试通过，包括对每一种配置组合的扫描。
页面是构建脚本的输出。重新构建不会产生差异。
每个配置控件都会调用
```
simulate
```
并更新 URL。
使用
```
?
```
参数打开 URL 时会恢复相同配置。
任意时刻恰好显示一种强调色，并始终跟随当前活动部件。
在两种主题和手机宽度下，每个工位都显示清晰可读的铭牌。
线端检查报告零个悬空线端。
场景扫描会将每种配置运行至结束，且控制台零错误。
明亮和暗色主题下的桌面与手机截图均无裁切，也无横向滚动。
爆炸态始终位于舞台范围内。
页面中包含模拟说明句。

Files

文件

```
references/concept.md
```
: invent the machine, the one-sentence test, concept mapping, sizing.
```
references/state-model.md
```
: the model contract, event shape, tests, URL state.
```
references/geometry.md
```
: units, camera, parts list, kit functions, shading, depth keys, nameplates.
```
references/live.md
```
: the beat timeline, the draw loop, sorting, accent, controls, accessibility, layout.
```
references/verify.md
```
: the headless verification loop with a script.

templates/model.mjs

templates/model.test.mjs

templates/build.mjs

templates/live.js

: a working cache machine. Run

node templates/build.mjs

to write

templates/out.html

. Run

node --test templates/model.test.mjs

for the model tests.

```
kit/iso-kit.mjs
```
,
```
kit/lathe.mjs
```
,
```
kit/tube.mjs
```
: projection, solids, lathe bodies, tubes and the base CSS. Keep
```
kit/LICENSE
```
with the kit.

Inside the AI Engineering from Scratch repo, also see

scripts/agent-machine/

and

site/test_agent_machine.js

for a full hero build with 57 depth-sorted items.

```
references/concept.md
```
：发明机器、一句话检验方法、概念映射和尺寸规划。
```
references/state-model.md
```
：模型契约、事件结构、测试和 URL 状态。
```
references/geometry.md
```
：单位、相机、部件列表、kit 函数、明暗处理、depth key 和铭牌。
```
references/live.md
```
：节拍时间线、绘制循环、排序、强调色、控件、无障碍和布局。
```
references/verify.md
```
：包含脚本的无头验证循环。

templates/model.mjs

、

templates/model.test.mjs

、

templates/build.mjs

、

templates/live.js

：一个可运行的缓存机器示例。运行

node templates/build.mjs

可写出

templates/out.html

。运行

node --test templates/model.test.mjs

可执行模型测试。

```
kit/iso-kit.mjs
```
、
```
kit/lathe.mjs
```
、
```
kit/tube.mjs
```
：投影、实体几何、车削体、管件和基础 CSS。使用 kit 时请保留
```
kit/LICENSE
```
。

在 AI Engineering from Scratch 仓库中，还可查看

scripts/agent-machine/

和

site/test_agent_machine.js

，了解包含 57 个深度排序项的完整 hero 构建。