isometric-explainer

等距解释图

这项技能可以制作单页交互式图示。图示展示一台放在工作台上的实体等距机器。机器的每个工位代表一个流程步骤。例如，一张请求卡在滑架上移动，探针落下，压机则在卡片上盖印。每个动作都由纯状态模型决定，因此图像、数字和文字彼此一致。templates/ 文件夹中有一个可用的起始模板，kit/ 文件夹中则有它使用的几何库。

适用场景

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

不适用场景

• 静态图表就能解释这个概念。请改用扁平 SVG 图示。
• 这个概念没有顺序或状态变化。请改用静态图示。
• 图示只是课程或 README 中的一张小图。请使用同级技能 blueprint-figure。
• 你无法为这种行为编写确定性模型。不要对猜测进行动画处理。
• 任务需要超过 150 个部件，且用户尚未批准这个规模。

方法

1. 设计机器。用一句话写出：“X 经过 Y 移动，这种移动代表 Z。”如果写不出来，就换一种机器。请参阅 references/concept.md。

2. 绘制前先在纸上清点部件，并选择一个层级。

   层级	部件数	是否需要批准
   图示	40 到 80	不需要
   主视觉图	80 到 150	不需要
   更大型	超过 150	先征得用户批准

3. 先编写状态模型。让 model.mjs 保持纯粹且确定，不使用 DOM 和时钟。simulate(config) 返回事件列表和总数。在制作任何几何图形之前先测试它。请参阅 references/state-model.md。

4. 将每个概念映射到一个工位。编写一张表，列出工位、用作标签的概念词、工位的作用，以及缺少它会导致什么故障。

5. 编写部件清单。逐一列出每个部件的组件、世界单位尺寸、色调以及是否会移动。完成清单后再制作几何图形。

6. 设置相机。使用世界单位和单个等距相机。将仰角设为 30 度。选择方位角，让工作面朝向观看者。确保投影范围能容纳组装态和爆炸态。

7. 只构建一次静态几何图形。每个部件都变为一个带有深度键的 SVG 组。移动部件需要 data-live 挂钩。请参阅 references/geometry.md。

8. 通过平移实现动画。只通过修改 transform 来移动部件。仅当形状发生变化时才重建路径，例如杆件变长时。

9. 从后向前绘制。根据深度键加上当前偏移的深度对各组排序。仅在顺序发生变化时才重新排列 DOM。

10. 使用颜色和墨线进行绘制。每种材质使用三种纯色色调，主要实体使用粗重的墨线轮廓，并在每个实体于工作台上投下的短而平的暖灰色阴影。只有一种强调色，用于标记活动部件及其胶囊标签。请参阅 references/colour-and-ink.md。

11. 添加会改变模型的控件。运行、步进、破坏、修复、重置以及配置开关都应作用于真实的 simulate 运行。将配置写入 URL。请参阅 references/live.md。

12. 在无头浏览器中验证页面。在桌面和手机宽度下，分别为两种主题截图。添加 4x 特写、线段端点检查、无控制台错误的场景扫描，以及联系表。请参阅 references/verify.md。

规则

真实性：

• 状态模型是唯一可信来源。运动、读数、轨迹线和结果文本都来自它的事件。
• 使用相同配置调用 simulate 会返回相同事件。测试会证明这一点适用于所有配置组合。
• 绝不伪装真实模型、真实服务或真实指标。脚本化部分的页面文案必须注明“固定脚本”。
• 所有展示模拟时间的页面都必须包含一个以“This is a simulation.”开头的句子，并说明这些时间是固定耗时，而非测量结果。
• 在模型中使用真实算术。测试会断言页面打印的确切数值。

几何：

• 所有坐标都以世界单位表示。像素只出现在投影中。
• 仰角为 30 度。整个页面使用一个固定的方位角。参考页面使用 60 度。
• 实体使用 kit/ink.mjs 中的 inkSolid：每种材质使用三种平涂色调、墨线轮廓，以及围绕每个主体的较粗剪影线。
• 每条线的末端都落在实体或另一条线上。带有刻意悬空端点的线要标记 data-free="start"、"end" 或 ""。
• 每个工位都带有一个胶囊标签，并通过引线连接到其工作部件；标签使用大写概念词，例如 CACHE 或 VERIFIER。页面提供“Labels”切换开关，并识别 ?labels=0。
• 状态灯显示模型提供的各工位状态：完成时为绿色，失败或留下缺口时为红色。
• 玻璃罩要显示工位内部情况：使用浅色调和一两道条纹。
• 放置在其他部件上的部件要设置深度偏移，以便在支撑部件之后绘制。

运动：

• 移动部件只改变 transform。对于形状会改变的路径，尽可能使用缓存结果重新构建。
• 每个节拍持续 0.1 到 1.3 秒。移动时间随距离增加。
• 爆炸视图使用弹簧参数：刚度为 64、阻尼为 14.2，每个组件间隔 0.04 秒。
• 将帧间隔限制为 1/20 秒，避免慢帧跳过节拍。
• 开启减少动态效果时，运行速度加快 40 倍，爆炸视图会直接跳至结束姿态。
• 舞台离开屏幕或没有部件移动时，动画循环会停止。

页面：

• 桌面宽度下，工作台应能在一个屏幕内容纳工具栏、舞台和读数，总高度为 100svh。
• 手机宽度下，页面采用纵向堆叠，绝不出现横向滚动。
• 按钮高度至少为 44 px。舞台可获取焦点，并支持通过键盘按键运行、单步执行、展开、故障和修复。
• SVG 必须具有 role="img"，并使用 aria-label 列出每个工位的名称。
• 运行结束时，aria-live="polite" 区域会播报结果。

完成前检查

• 页面文案或构建说明中写有一句话的机器说明。
• 部件数量符合已批准的等级。
• 模型测试通过，包括对所有配置组合进行遍历测试。
• 页面是构建脚本的输出。重新构建不会产生差异。
• 每个配置控件都会调用 simulate 并更新 URL。
• 使用 ? 参数打开 URL 时，会恢复相同配置。
• 任意时刻恰好显示一种强调色，并且该颜色跟随活动部件。
• 所有工位在两种主题和手机宽度下都显示清晰易读的胶囊标签，且没有标签遮挡移动部件或其他标签。
• 摆动滑块、颜色样本和“Labels”切换开关都能正常工作；使用 ?labels=0 打开页面时，标签处于关闭状态。
• 图示下方的“The big idea”一行用通俗语言说明核心要点。
• 线端检查报告没有悬空端点。
• 场景遍历会运行每种配置直至结束，且控制台错误数为零。
• 桌面和手机在浅色与深色主题下的截图均无裁切，也无横向滚动。
• 展开姿态始终位于舞台范围内。
• 页面上有模拟说明句。

文件

• references/concept.md：构思机器、单句测试、概念映射和尺寸。
• references/state-model.md：模型契约、事件形状、测试和 URL 状态。
• references/geometry.md：单位、摄像机、零件清单、套件函数、着色、深度键和标签。
• references/colour-and-ink.md：材质、色调、墨线粗细、投影、玻璃、状态灯、药丸标签、抖动和深色主题。
• 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/LICENSE。
• kit/ink.mjs：颜色和墨线层：inkSolid、silhouetteSvg、castShadowSvg、glassSvg、pillSvg、wobbleFilter、PALETTES 和 INK_CSS。

在 AI Engineering from Scratch 仓库中，还可以查看 scripts/decompiler-machine/ 和 site/test_decompiler_machine.js，了解采用颜色和墨线风格构建的完整主视觉；以及 scripts/agent-machine/，了解旧版灰色风格。