Anatomy:让 Coding Agent 用交互式装置解释技术原理
AI 参与说明(Agent:Codex):本文根据作者网站、Anatomy 与 anatomy-figures 公开源码协助调研、整理和校验,资料核验于 2026-10-13;中文正文使用 humanizer-zh 编辑。Anatomy 源码锁定为提交
454a0ef。运行记录:模型gpt-6.1-sol,reasoning effortultra,执行入口 Codex Desktop,提供方openai;CLI 版本0.162.0-alpha.17.2(不代表桌面 App 版本)。
修订说明
深入修订(2026-10-20,Agent:Codex):重新核对 Collection、early examples、已安装 Skill 与上游差异,补充可操作的作品对照、技术选型、机制设计方法及既有博客实验的选型参照。本文区分上游规则、源码事实与本站实践建议;中文使用 humanizer-zh 编辑。执行入口 Codex Desktop;本轮模型完整标识与 reasoning effort 未取得任务级运行记录。
标签整理(2026-10-16,Agent:Codex):本次仅补齐分类标签并核对元数据,未改写或重新校验原文技术结论。运行记录:模型
gpt-6.1-sol,reasoning effortultra,执行入口 Codex Desktop,提供方openai;CLI 版本0.162.0-alpha.17.2(不代表桌面 App 版本)。
实践补充(2026-10-13,Agent:Codex):补充项目核心机制讲解的适用要求与 OpenFilm 实例,中文使用项目
humanizer-zh编辑。运行记录:模型gpt-6.1-sol,reasoning effortultra,执行入口 Codex Desktop,提供方openai;CLI 版本0.162.0-alpha.17.2(不代表桌面 App 版本)。
后续实践补充(2026-10-13,Agent:Codex):补充 Cindy 与 ClawHub 核心机制 Figure 的阅读入口,中文使用项目
humanizer-zh编辑。运行记录:模型gpt-6.1-sol,reasoning effortultra,执行入口 Codex Desktop,提供方openai;CLI 版本0.162.0-alpha.17.2(不代表桌面 App 版本)。
展示修订(2026-10-13,Agent:Codex):撤下 Cindy 与 ClawHub 的装置实践入口,保留能直接观察输入、各层转换与输出关系的 OpenFilm 示例,补充装置讲解的适用性判断;中文使用 humanizer-zh 编辑。运行记录:模型
gpt-6.1-sol,reasoning effortultra,执行入口 Codex Desktop。
Anatomy 是一套让 Coding Agent 把技术机制做成可操作装置的 Skill。它最值得学习的是怎样选择表现形式:缓存顺序可以变成书架上的取放,二维卷积可以变成针床与两把梳子的对照,波动则需要连续的水面。装置怎样工作,就应当说明规则怎样工作。
只把一张状态表放进等距机器、让指示灯随结果变化,通常还没有解释计算过程。一个更有效的检查是:读者改变输入后,能否从画面看出变化发生在哪里,并预测下一次输入的结果?SVG、WebGL、3D 都服务于这个问题。
应用方法修订(2026-10-21,Agent:Codex):将 Anatomy 明确为按题材选择的可选工具,撤下不适合的博客装置案例,保留有直接解释作用的实践。连续动作与中间帧检查用于核验已经选定的插图,不能替代对题材是否合适的判断。沿用下文固定资料版本,中文按 humanizer-zh 编辑。执行入口 Codex Desktop;本轮模型完整标识与 reasoning effort 未取得任务级运行记录。
阅读前先看这几个词
| 英文术语 | 中文名称 | 简要解释 |
|---|---|---|
| Anatomy | 保留原名(项目名称) | 生成技术插图的 Skill 及其配套绘图工具 |
| Agent Skill | 智能体技能 | Agent 按任务读取的说明、代码和参考资源 |
| isometric illustration | 等距插图 | 用平行投影表现物体体积的插图风格 |
| SVG | 可缩放矢量图形 | 用路径和形状描述图形,适合精细线条与结构 |
| WebGL | 保留原名(浏览器图形 API) | 在浏览器中利用 GPU 绘制火焰、光等效果 |
| shader | 着色器 | 在 GPU 上计算像素颜色,可表现水面、光照等连续变化 |
| 3D | 三维 | 部件在空间中转动或弯曲,改变表面朝向与遮挡 |
| separable blur | 可分离模糊 | 把满足分离条件的二维卷积拆成横向与纵向两次一维卷积 |
| geometry audit | 几何检查 | 检查已记录零件的穿透、连接和遮挡关系 |
| Custom Elements | 自定义元素 | 可通过自定义 HTML 标签使用的网页组件 |
| LRU cache | 最近最少使用缓存 | 容量不足时淘汰最久没有被访问的条目 |
它提供了什么
Anatomy combines agent instructions, a drawing kit, reference examples, and verification scripts. 它把制作过程交给 Coding Agent:理解题材、选择装置、编写模型、搭建几何、实现交互,再检查结果。生成物是项目中的 SVG、HTML、TypeScript 或 React 组件代码。SKILL.md
SKILL.md 是入口,详细参考材料按制作步骤需要读取,绘图 kit 则提供实际运行的代码。这种组织方式把写作与设计要求交给 Agent,将投影、几何和检查交给可重复执行的程序;它的能力来自这几部分配合。参考材料入口
需要区分两个仓库:
| 入口 | 用途 | 什么时候选它 |
|---|---|---|
| anatomy | Skill、绘图 kit、参考材料、检查脚本与源代码示例 | 希望 Agent 为自己的主题制作新插图 |
| anatomy-figures | 作者已制作的交互插图组件库 | 已有插图恰好能解释所需主题,希望直接嵌入 |
作者主要用 Claude Code 制作展示作品,当前 Skill README 也给出 Codex 安装与调用方式。作品成形之后由浏览器运行本地的模型和绘图代码;从已检查的组件源码看,运行交互无需再调用远端 AI。Agent 的模型服务与计费属于制作阶段的条件,不能由此推断制作免费。Skill README、组件库
2026-10-20 核对时,Collection 列出 52 项:22 项 SVG、10 项 WebGL、1 项 3D,以及 19 项 early examples。主页的 33 项对应前三组。分类描述的是作品主要使用的能力:WebGL 作品仍有 SVG 结构,3D 作品也可能有 shader,不是三套互斥的渲染框架。Collection
本站已安装的 454a0ef 快照已经包含八个完整 examples、WebGL 与 3D 工具。2026-10-20 核对的上游 1482e846 又加入打印相关能力等改动;下文固定版本的 kit 分析仍以已安装快照为准。是否做出合适的图,不能只看有没有安装最新版,还要看制作时是否读过最接近的 example、是否建立了真实模型。
四个可以直接操作的对照
Anatomy · 官方作品对照
同一种讲解方法,四种具体做法
书的位置就是缓存的访问顺序
操作:点击书,或聚焦图形后按 A–J。依次访问 A、B、C、D,再访问 B、E;每次等书归位后继续。
观察:刚访问的书移到上层左端;加入 E 时,最久没被访问的 A 回到下层。
正在加载 SVG · LRU。启用 JavaScript 后可在此操作,也可打开官方作品。
对应的规则:上层四个书位表示容量,左右次序表示最近访问顺序,取回与送回分别表示加载和淘汰。SVG 的移动已经足够解释这条规则。
原作 Ryan · anatomy-figures 0.1.0 · MIT 许可。此处保留原作英文读数,中文提示用于对照阅读。
这里复用作者的 anatomy-figures@0.1.0,用于研究表达方式;作品不是本站重新创作的装置。一次只加载所选作品。正文中的解释独立于组件,关闭 JavaScript 后仍可阅读。
比较时先带着一个问题操作:LRU 中再次访问已有书,位置为什么改变?Turbofan 的推力增加时,哪些流动随之变化?Seasons 中季节变化为什么伴随不同的受光姿态?Separable blur 的第一次处理后,图像在哪个方向已经模糊、哪个方向还保留细节?这些问题分别检验顺序、连续场、空间关系和中间计算结果。
原理一:让装置的动作对应概念的规则
它的设计规则可以概括为:先写清“什么在动,这个动作意味着什么”,再开始画。对于真实机器,表现的是机器自身的结构;对于算法和系统概念,需要设计一个行为对应的类比装置。Craft 规则
| 概念 | 作者选择的装置 | 读者观察什么 |
|---|---|---|
| LRU cache | 有上下两层的书架 | 命中后调整顺序,未命中时取书,容量不足时淘汰 |
| Message queue | 弹珠轨道 | 任务排队,按顺序经过控制机构 |
| Mutex | 两台泵、水箱和钥匙 | 只有持有钥匙的一方可以进入临界区 |
| Bloom filter | 三个转轮和一排标志位 | 多个 hash 对应的标志位共同决定查询结果 |
类比是否有用,取决于装置的行为能否对应概念的规则。以 LRU cache 为例,“书架有四个位置”只是容量说明;命中后把书移到左端、满额时从右端淘汰,才表现了 LRU 的规则。类比没有覆盖的行为仍需正文补充,不能让画面暗示系统还具备未建模的能力。
从一个正常结果走到边界条件
最有用的作品会把“不一样的结果为什么发生”也做进动作。阅读 Bloom filter 时,重点是同一组 bit 可以被不同词共同置位:查询时三个标志都已升起,装置可以给出“可能存在”,但这不能证明这个词真的插入过。只画三个转轮,再点亮一个绿色结果,不足以解释 false positive。
发布版模型默认加入 cherry、plum、peach。orange 对应的位置是 11、0、5,三个位置都已置位,所以查询会通过,但 orange 实际没有加入;lemon 对应的 0、1、2 则有未置位的位置。这里用于揭示“实际加入过什么”的集合是教学辅助,不是 Bloom filter 自身的查询依据。官方页面中 Space 查询、Enter 添加,体验时不要混淆两个动作。固定版本模型
Mutex 的重点则是读与写之间的关系:两台泵都依据旧水位作决定时会产生冲突;钥匙应约束包含读取在内的临界区。画一扇轮流开关的门只能表达“排队”,必须看出为什么共享状态需要互斥。上述对象映射来自官方作品;将正常路径与反例并排检查,是本文建议的阅读和制作方法。
对其纯模型的核验可以把问题说得更具体:水箱已有 500 L,目标是 1000 L,A 启动后 0.3 秒再启动 B。关闭互锁时,两方都读取 500 L,各自决定补 500 L,最终溢出 500 L;启用互锁后,B 等 A 完成再读到 1000 L,无需再补水。这些数值来自教学模型,不是实物水箱测试。固定版本模型
Early examples 更接近软件源码的讲解
这组作品最初为 WebGL 玻璃库而作,很多直接解释计算资源、图像处理和缓存条件。它们没有后来所有主题与细节规范,却更适合学习“如何解剖一段软件”。组件库说明
Anatomy 因而不只有“把算法比作机器”这一种用法:发动机、水波箱解释真实对象自身;书架、钥匙把抽象规则变成物理类比;这组早期作品则把软件原本就有的图像、缓冲与中间结果摆出来。对于源码文章,第三种常常能减少读者理解比喻所需的额外步骤。
| 作品 | 规则如何成为动作或形状 | 可以借鉴什么 |
|---|---|---|
| One context | 同一个打印头逐个访问多个位置,对应共享渲染资源轮流工作 | 对象数量与资源数量分开;移动必须对应实际处理对象 |
| Separable blur | 二维针床对应成片采样,两把正交梳子对应两次一维处理;中间图像也改变 | 同时展示计算量与中间结果,不能只把“更快”写在表上 |
| One stage | 抽屉高度对应不同中间缓冲每 texel 的存储字节数 | 用有单位的尺寸解释真实数量,不能把状态编号当距离 |
| Field key | 锁的匹配条件对应缓存字段的匹配 | 展示哪些输入改变会使缓存失效,哪些改变仍能复用 |
One context 的运行顺序是移动、渲染、复制、离开;工作头离开后,各画布保留已经复制的结果。它同时表现了“共享一个计算资源”和“各对象保留自己的输出”,比一列任务卡片移动多解释了一层。为便于观察而放慢的动作是教学时间,不能据此推断真实 GPU 调度也以秒为单位执行。固定版本运行代码
以 Separable blur 为例,宽度为 49 的可分离核,直接二维计算需要每个输出点 49 × 49 = 2401 次采样;分成两个方向是 49 + 49 = 98 次。这里比较的是采样次数,不是实测帧率;两次 pass 的开销、内存读写和实现方式仍影响性能。这一简化也不适用于任意二维核。图像先沿一个方向变模糊,再沿另一个方向处理,才解释了“两次一维处理”到底做了什么。作品
这个作品还有两个容易漏掉的细节。第一,blur 改变采样间距,固定方案的核宽仍是 49;9 px 与 14 px 都是 98 对 2401 次采样,blur=0 则直接读取一次。第二,为了可读性,画面并没有画出全部采样针,不能用肉眼数针代替核大小。针高表达权重,中间图像表达处理结果,读数表达采样总量,三者各有含义。固定版本实现
One stage 也不只是七个贴标签的抽屉:其中四个 rgba16f target 每 texel 为 8 B,三个 rgba8 target 为 4 B,前四个抽屉因此画成两倍高;抽屉内还能看到距离场、梯度、原图、横向模糊图和最终模糊图。每个 target 的实际宽高仍须另计,不能将格式字节相加就称为任意画布每像素的总显存。数据表与绘制实现
对源码文章而言,最值得搬用的是这种对应关系。解释文本变更就让字符真的保留、删除和插入;解释帧合成就让输入层与最终画面一起变化;解释版本校验则可以直接显示字符串规范化与比较条件。并非所有程序都需要被设计成机械装置。
原理二:图形、动画和读数共用一个模型
The motion and the readout are derived from the same model. Skill 要求先收集真实参数与规则,将它们写入一个小模型,再让零件位置、动画、数值和说明读取这个模型。Workflow
下面的流程根据源码职责整理,图中的分支表示共用数据:
flowchart TD
A["概念与一手资料"] --> B["明确行为、参数与适用范围"]
B --> C["编写共享模型"]
C --> D["选择对应装置,列出零件"]
D --> E["建立坐标、相机与 SVG 几何"]
C --> F["计算状态变化"]
F --> G["更新零件与动画"]
F --> H["更新读数与可访问文本"]
E --> G
G --> I["geometry audit、线端检查与截图复核"]
H --> I
I --> J["修正后交付网页或组件"]
这在仓库中有具体实现。dial-indicator 示例让测头、表针、数字和 aria-valuenow 使用同一个位移状态;ripple-tank 的模型计算波数、波长、相速和群速,再供图形与读数使用。这样修改参数时,图形、动画和读数能够一起变化。dial-indicator、ripple-tank/model.mjs
共用模型能减少“动画与数字对不上”的问题,但模型本身仍可能错误。公式、单位、输入条件与类比范围需要单独核验。
原理三:用三维坐标组织零件,用 SVG 表现结构
多数插图先在世界坐标中组织零件,再经正交投影生成屏幕上的 SVG 路径。远处的零件不会因为距离而缩小,平行线仍然平行,适合阅读机械结构。静态路径提前计算,运动优先更新变换,形状发生变化的部分才重新计算。iso-kit.ts
作者以 isometric 命名这种视觉风格;默认相机方位角为 45°、俯视角为 30°,严格数学分类属于 dimetric。称它为“类等距的正交插图”更准确,并非所有作品都采用标准等轴投影。作者的相机说明
SVG 的遮挡来自绘制顺序:后画的覆盖先画的。如果弹簧绕着一根杆,弹簧后半段应先画,杆居中,弹簧前半段最后画;一整根弹簧不能用一个排序位置同时满足这两个关系。Anatomy 的 kit、拆分规范和 geometry audit 用于处理这类问题。kit.md
它的线稿规范包括实体填充、四档侧面阴影、较亮的顶面,以及一个引导注意力的强调部件。只有颜色本身属于被解释的内容时才使用相应色彩,不能靠多色仪表盘替代层次。这些约束写入 Skill 与参考材料,用于帮助 Agent 保持相近的视觉语言。craft.md
SVG 不等于平面状态图
Anatomy 的 SVG 先有空间模型,再有路径。齿轮、针床、转轮、书架和弹簧都可以有厚度、遮挡与运动;“没有 WebGL”不意味着只能画几个矩形。反过来,给矩形加三面阴影,也不会自动增加解释能力。
它至少有两种运动成本:刚体平移可以更新一组路径的变换;转动、变形或可见面发生变化时,需要按姿态更新对应几何与排序。判断选型时应先问“哪些形状必须变”,再问采用什么 API。绘图 kit、motion.md
WebGL 与 3D 分别解决什么
| 方式 | 主要用途 | 实现与边界 |
|---|---|---|
| SVG | 零件、线条、仪器与大多数算法类比 | 用路径、填充和排序表现体积 |
| SVG + WebGL | 火焰、水、气流、光与等离子体 | shader 与 SVG 共用相机参数,并通过图层或几何遮罩表现遮挡 |
| 3D beta | 需要在深度方向转动的部件 | 转动部分每帧重新投影、着色和排序,仍保留 SVG 风格 |
WebGL 与 3D 是分别选择的能力。提示词中的 interactive 请求交互,WebGL 请求 shader 效果,3D 请求真正的深度转动。选择方式应由解释需要决定:讲缓存顺序通常用 SVG 就够了,讲火焰和气流可能需要 WebGL,讲季节的地球姿态才需要考虑 3D。SKILL.md
SVG 和 WebGL 无法直接共用一个深度缓冲区,配套规范提供后层 SVG、canvas、前层 SVG 的组合;具体作品还可用 shader 中的几何遮罩处理遮挡。3D 模式要求转动的几何为凸零件,凹物体需要拆分,循环遮挡仍需处理。webgl.md、3d.md
WebGL:把连续变化放到装置内部
Ripple tank 是比“加一层发光”更好的学习起点。支架、水槽和纸面定义空间,水面的波与纸上的光学变化由模型驱动。调整频率后,新频率从波源传播出去,不应让整个水面在同一瞬间换成新的波纹。
其 model.mjs 将水深、频率与波数联系起来,再求波长、相速与群速;live.js 维护频率历史供 shader 读取。这里的 WebGL 有明确任务:表现空间中连续变化的波形。它不是用漂浮粒子装饰一个并未建模的“数据流”。模型、运行代码
本次直接运行该模型,在默认水深 6 mm 下,8、18、28 Hz 分别得到约 28.662、13.048、9.079 mm 的波长。模型中的水深是常量,不能据此称官方页面提供水深滑块;这些计算验证也不代表真实水槽的实验精度。读数有物理量与单位,才有依据判断水面变化是否合理。
Raptor 与 Turbofan 的参考价值还在遮挡和过渡:火焰要处在管路、喷口或支架之间;启动、稳定、熄灭要连续变化;所有效果必须在边界前淡出。相同的 shader 颜色直接放到白底上可能成为脏色,因此明暗主题分别设计,关闭 WebGL 后仍保留可读的 SVG。实现时读取 references/webgl.md 和相应 example,不能仅照抄三层容器。WebGL 规范
3D:深度关系本身就是解释的一部分
Anatomy’s 3D mode reprojects moving geometry; it is not a synonym for WebGL. 它以 group 表达转动、滑动、铰链或自由运动,每帧重新计算活动部件的投影、表面明暗与前后关系,静态环境保留原来的绘图结果。这里不必把整幅图转换为 Three.js 场景。3D 运行模型
Seasons 需要观察地轴、轨道位置与受光关系;只让一个圆沿轨道平移,会遗漏空间姿态。Turning dial 则适合学习转盘、手指铰链与跟随运动的光源。软件文档中的调用顺序、布尔判断或版本状态一般没有这种空间自由度,增加自由旋转往往只增加操作负担。这是本文的选型建议,不是对题材的技术限制。
Seasons 中改变日期与改变观察角度是两件事:日期改变地球的公转位置,转台帮助观察空间关系。传动模型还用反向转角抵消公转,保持地轴指向。其太阳位置与昼长模型在北纬 50° 给出六月至日约 16 小时 22 分、十二月至日约 8 小时 04 分;本次已从发布源码提取纯函数复核这两个结果。这里的数值来自该模型采用的日出日落阈值,不应当作任意地点的实际观测时间。固定版本实现
3D beta 需要单独做旋转轨迹和姿态检查;不能用一张初始截图证明所有角度都正确。上游性能记录也只适用于它测过的装置和设备,不应直接变成本项目的帧率承诺。3D 检查与边界
检查脚本能保证到哪一步
geometry audit 读取零件的几何记录,检查管路距离、端点连接、支撑、屏幕重叠区域的前后顺序,以及拆解过程中的部分姿态。另有线端检查,补充几何记录看不到的 SVG 线条问题;截图和放大检查用于发现接缝、明暗、动作突变等视觉问题。audit.mjs、lines.mjs、verify.md
The audit checks recorded geometry with sampling and tolerances. 源码中的重叠检查、距离检查与运动检查使用采样步长和数值阈值。因此,“检查通过”应限定在所记录的几何、检查姿态和阈值范围内;它不能替代工程级 CAD 碰撞分析,也不验证讲解的算法、物理参数或结论是否正确。这是根据检查实现作出的范围判断。overlapsOf 与 clearances
制作时间也主要花在复核。作者报告的 Watch 完整制作约为 1 小时 54 分钟,Raptor 为 10 小时 33 分钟,Turbofan 为 14 小时,均包含复核修正。这些是作者记录,不是本次实测或交付承诺。制作时间
适合哪些场景
以下使用建议基于现有作品和实现范围:
| 场景 | 适合解释的内容 | 判断是否值得做 |
|---|---|---|
| 技术博客与开发者文档 | 缓存淘汰、排队、互斥、重试与限流 | 一次输入是否能显示一个明确的状态变化 |
| 教学与课程 | 算法步骤、传动、波与时间变化 | 读者能否先预测结果,再通过操作核对 |
| 产品机制介绍 | 请求如何经过某个装置,参数如何影响输出 | 能否用一个小机制讲清关键行为 |
| 机械或科学科普 | 拆解、旋转、流动与可量化关系 | 是否有可靠参数,是否能清楚限定简化条件 |
如果问题主要是“哪些服务相连、谁调用谁”,流程图或 sequence diagram 更直接;如果要比较几十组数据,统计图更合适。Anatomy 侧重精细的实体装置。需要快速出图、精确工程设计或大型场景建模时,它的制作成本和能力范围都不适合。
从源码到图:一份可以执行的制作方法
Anatomy 是可选的表达工具,技术文档不默认配装置,也不要求先试做一个。只有运动、空间关系或中间产物能够直接帮助解释机制,且不会让读者先花力气理解一套陌生的机械规则时,才考虑引入。正文、数据例子、Mermaid 或普通图表已经能讲清的问题,保持这些表达即可。
以下流程用于已经确认适合 Anatomy 的题材。是否采用,应在投入几何、动画和测试之前判断;做得精细、能够播放和检查通过,都不能反过来证明题材选得合适。
1. 先写一句需要解释的因果关系
不要从“给这个项目做一个 Anatomy”开始。改为明确问题,例如:“改变影片时间后,两个页面各自收到哪个局部时间,怎样组成这一帧?”接着固定源码版本,列出输入、关键函数、状态、输出以及没有模拟的部分。图解一个模块时,也要说明它在整个项目中的作用。
2. 先寻找最接近的工作方式
同时看 Collection 和 Skill 自带 examples:前者帮助选概念,后者帮助实现几何和运行行为。缓存匹配可参考 Field key;共享资源调度可参考 One context;连续波动参考 ripple-tank;真正空间转动参考 turning-dial。不要每次都从“底板、三条轨道、一个结果游标”起步。
画图前填写下面四列。如果第三列始终只能写“亮灯”“换字”“移到 PASS 一侧”,需要重新选表达。
| 真实规则 | 模型中的量 | 读者能观察的变化 | 可验证的反例 |
|---|---|---|---|
| LRU 命中改变访问顺序 | 有序 key 列表 | 已有书移动到最近使用端,其余书相应移位 | 再访问同一项不增加占位 |
| 可分离卷积有中间结果 | 横向输出与纵向输出 | 先沿一轴模糊,再沿另一轴模糊 | blur 为 0 时跳过中间缓冲,仅一次读取 |
| OpenFilm 换算页面时间 | 全局时间、开始时间、局部时间 | 页面画面与合成帧同时改变 | 尚未开始或已经结束的页面不进入当前合成 |
3. 先排动作,再做精细 Figure
草图用于证明讲解有效,不作为成品交付。先排一次完整动作:读取、取件、移动、转换、接触、放件,最后保持输出。让读者追踪同一个对象,看到中间状态在哪里改变,再改一个关键条件,预测动作会在哪里不同。隐藏旁边的结果说明后,图中仍应保留这些关系。
“有交互”还不够。输入框改变后立即更新一张分数表,能帮助核对计算,却没有呈现 Anatomy 的运动表达。LRU 命中时是同一本书回到最近使用端;One context 是同一个工作头访问不同画布,留下各自的复制结果。复制必须保留源对象,搬运必须连续,结果应在对应动作完成后出现。任意滑动标签或给表格淡入,不能补上缺失的过程。
通过后再按上游 Figure 要求安排有实际用途的零件、实体厚度、四档侧面阴影、单一视觉重点与卡片四角。上游要求 Figure 有 40–80 个部件;这是制作密度要求,不能当作教学有效的评分。螺丝再多,也不能补上缺失的转换。
4. 分别检查语义、动画、几何和运行行为
| 检查层 | 要验证的内容 | 不能拿什么替代 |
|---|---|---|
| 语义 | 正常输入、边界输入、反例与固定版本规则一致;画面能解释差异 | TypeScript 通过、结果标签正确 |
| 动画 | 实际观看正常速度和慢放;同一对象连续,中间转换可见,接触与释放合理,输出在完成后出现 | 只检查 transform 改变、静态终点正确 |
| 几何 | 实际形状、支撑、遮挡、连接与线端;运动中间帧和 4× 局部 | 只看初始姿态、只报部件数量 |
| 运行 | 键盘、触控、明暗主题、离屏暂停、减少动画、WebGL 降级 | 只在桌面用鼠标点一次 |
自制几何应执行对应的 audit 和 line checks;3D 还需要旋转与姿态检查。复用作者组件时,应核验本站的挂载、切换、主题、交互和降级,不把“使用了官方包”写成“已重新通过全部上游审计”。
浏览器验收应分别覆盖正常动画与减少动画。前者录制连续播放并检查取件、接触、放件的中间帧;后者显示可阅读的静态结果,允许手动查看分镜。默认演示还需要暂停、慢放、进度控制和离屏停止。若所有测试都启用了减少动画,即使截图和模型断言通过,也没有检验读者实际看到的动作。
5. 允许选择更直接的表达
以版本校验为例,版本号之间未必有适合用距离表达的数量关系。将不同字符串放到固定间距、再把 PASS/WARN/FAIL 排在另一根尺上,只显示分类结果。更清楚的办法是显示去掉 v/V 前缀后的字符串,指出哪两个字段不同,再展示 SemVer 与 Tag 的比较条件。
本站的 Waza 版本校验实验 采用这种直接表达;OpenFilm 分层摄影台 则保留装置,因为图层的画面和合成帧确实参与了被解释的转换。前者适合校验实验,后者适合 Anatomy,两者不必统一外观。
对旧示例也采用同一标准。普通交互实验有用,可以按其本来用途保留;装置只重复文字或增加比喻负担,就撤下装置。没有必要为被撤下的部分再做一个交互替代品。
怎样开始使用
先体验已有作品
建议先打开 LRU cache,通过 A–J 选择书,观察上层四个位置的顺序以及下层取回动作。再看 Message queue 和 Mutex,比较它们怎样用装置表达不同规则。
初次调研打开了 LRU cache 的实际页面,确认书架、实时读数和键盘操作入口能够呈现。后续实践把 Anatomy 用于项目原理讲解,例如 OpenFilm 的分层动画摄影台:两层画面对应两个 HTML 页面,共用的影片时间分别换算成各页的 frame(t) 参数,旁边显示合成结果。
这类图的目标是解释项目核心原理和模块运行机制。OpenFilm 的画面层、共用时间与合成结果直接对应被解释的对象,读者能看见转换发生在哪里。选装置前,应先用最小草图验证这种对应关系:改变输入后,中间转换和输出都能被观察,读者能预测变化。若关键机制仍全靠周边文字解释,图里只剩卡片移动、颜色或版本号变化,就不应把精细造型当作有效讲解。
下面两项局部机制保留装置表达,字段明细放在图外供核对。它们的选型不应推广成所有项目分析的模板:
| 要解释的问题 | 直接体验 | 应能观察或预测的变化 |
|---|---|---|
| 保存输入怎样与恢复决定组合 | Mastra 保存与恢复 | 180 原件留存,恢复副本直接回到 approval;60 草稿受阻,false 决定接合后形成 rejected:180.00 |
| 高相关记忆为何没有进入结果 | Ruflo 候选窗口与评分 | 同一张 C 卡从 1001 移到 1000 后才被取走评分;三项量尺形成后再按实际分数入槽 |
这些是教学装置,动作经过放慢,不代表框架真实执行的秒数或内部硬件。它们是否有效,要看动作能否让人追踪来源、转换与约束;正确的最终字段只是核对依据。Waza 版本校验 仍采用直接实验,因为版本字符串的差异没有合适的等距物理含义。
让 Agent 制作新作品
在希望保存插图的代码项目中执行,需已安装 Node.js、npm 和对应 Coding Agent。下面是项目范围的安装示例;Skills CLI 的参数已通过 Context7 对照当前官方 README 核对。本站后来将 Anatomy 的固定源码快照保存在项目 .agents/skills/anatomy/,与内容仓库一起提交。Skills CLI README
Anatomy 本地构建与检查脚本要求 Node.js 20.10 及以上;自动截图等步骤还需要本地 Chrome 或 Chromium。安装 Skill 只是准备资源,制作时仍需要 Agent 执行代码、浏览器检查并修正结果。运行条件
# 只列出可安装的 Skill
npx skills add wheresryan22/anatomy --list
# 选择所用 Agent,执行对应的一条安装命令
npx skills add wheresryan22/anatomy --skill anatomy --agent claude-code
npx skills add wheresryan22/anatomy --skill anatomy --agent codex
Claude Code 使用 /anatomy,Codex 使用 $anatomy。安装后按所用 Agent 的要求重新加载技能,再提出制作任务。以下是本文建议的任务示例,尚未实际生成:
/anatomy explain how an LRU cache evicts entries, interactive.
Use a capacity of 4 and keys A through J.
Make the MRU-to-LRU order and hit/miss readout visible.
Use a shared model for the motion and readout.
Deliver a browser page with keyboard controls and reduced-motion support.
在 Codex 中将首行的 /anatomy 换成 $anatomy。验收时先用确定的访问序列检查规则:依次访问 A、B、C、D,随后访问 B,再访问 E。容量为 4 时,B 应成为最近访问项,加入 E 时应淘汰 A。然后检查动画和读数是否表达同一结果。调用入口
这比只要求“画一个漂亮的缓存图”更容易验收。题材、参数、输出载体与通过标准都已写清;复杂机器还应先收窄到一个需要解释的子机制。
已经判断某个源码机制明显适合装置表达时,可以使用下面这份任务框架,将方括号替换为真实信息。它不是项目分析的默认步骤,也不是运行命令:
$anatomy explain [one mechanism] in [project at commit].
First confirm that motion, spatial relations, or intermediate artifacts
explain this mechanism directly without adding an unrelated metaphor.
If prose, a data example, or a diagram is already clear, stop here;
do not create a figure or a replacement interactive demo.
Read [source files/functions] and the closest shipped example first.
State the input, intermediate state, output, and one counterexample.
Choose an object whose working demonstrates that exact transformation.
Explain what the reader will see before writing detailed geometry.
Use SVG for parts. Add WebGL only for a modeled continuous field;
use 3D only if depth motion is necessary to understand the mechanism.
Drive art, motion, readout, and accessible text from the same model.
Keep the same object visible through each movement; preserve originals on copy.
Show intermediate transformations and let contact or eligibility control action.
Provide an idle tour, pause, slow playback, scrubbing, and reduced-motion frames.
Record normal playback and slow playback; inspect contact and release frames.
If a direct diagram or experiment explains it better, use that instead
and do not label it as an Anatomy figure.
Embed the result in the article and verify the relevant behaviors.
直接复用组件
如果现有作品已经合适,可以使用 anatomy-figures。本次核对 npm 包版本为 0.1.0,以下实现说明对应其发布关联提交 d4590e3。在已有 React 18 及以上的项目中安装,再按独立入口导入,避免把全部作品都打包进来。package.json
npm install anatomy-figures@0.1.0
import LruCache from "anatomy-figures/lru-cache";
export default function CacheExplainer() {
return <LruCache theme="light" />;
}
这段 TSX 用于已有 React 客户端页面,显示交互式书架。本文上方的对照组件已安装该版本并使用相同子路径,在 Astro MDX 中通过 client:visible 启用交互,再按所选作品动态导入。React wrapper 在客户端挂载图形,服务端输出占位容器;能够输出服务端 HTML,并不表示图形本体已经完整 SSR。因此重要结论仍保留在静态正文中。React wrapper
不使用 React 时,新系列作品提供 Custom Elements,例如导入 anatomy-figures/element/lru-cache 的 define,调用后使用 <anatomy-lru-cache>。19 个 early examples 的内部实现仍依赖 React,不能把所有自定义标签都当作完全无 React 的组件。新系列提供五种主题和细粒度 tokens;early examples 的主题覆盖较少,应以组件库说明为准。组件库 README
Skill 和组件库均采用 MIT 许可。实际复用时仍须保留相应版权与许可说明。Skill LICENSE、组件库 LICENSE
进一步阅读
- How I built it:作者怎样将视觉反馈转成规则,以及投影、运动、shader 和检查过程。
- Matt Pocock Skills:从需求澄清到工程交付的 Agent 工作流:对照另一类 Skill,看任务步骤、参考资料与可验收结果怎样组织。
- Agent 开发中的测试方法:Specification、Test Oracle 与验证证据:进一步区分实现自检与判断结果是否正确的依据。
- Agent 栏目导航。