Anatomy 项目贡献指南:从环境搭建、构建示例到四类质量检查与 PR 全流程
Anatomy 项目贡献指南:从环境搭建、构建示例到四类质量检查与 PR 全流程
导读
本文是开源仓库 Anatomy(一个用于生成高细节交互式等距插画 SVG 的 Agent Skill)的完整贡献指南,基于仓库根目录的 CONTRIBUTING.md 展开,并结合 kit/audit.mjs、scripts/drive.mjs、scripts/lines.mjs、.github/workflows/ci.yml 等源码与配置逐一印证。读完本文,你将掌握:零依赖环境搭建与 skill 软链接入方式、全部示例页面的构建命令(含 --light/--audit 等开关)、浏览器驱动回归、几何审计、线端检查、截图捕获、脚本驱动与 3D 图检查四类质量门禁的使用方法,以及项目要求每位贡献者遵守的 House Rules 与完整的 Pull Request 提交流程。
核心事实前提:Anatomy 的成图质量以 4 倍缩放下的视觉效果为评判标准("judged by how its figures look at 4× zoom"),因此本指南的绝大部分篇幅都在讲"在别人看到之前,先自己检查自己的工作"。
一、环境搭建与开发准备
1.1 需要的运行环境
| 依赖 | 用途 | 说明 |
|---|---|---|
| Node.js 20.10 或更高 | 构建脚本、kit 库、所有检查脚本 | 完全使用 Node 内置模块,无需安装任何第三方依赖(npm install 都不需要) |
| Google Chrome 或 Chromium | 浏览器类检查(capture / drive / lines / turn-check) | 脚本会在 macOS、Linux、Windows 的常规路径以及 Playwright 缓存目录中自动查找;找不到时通过环境变量 CHROME_PATH 显式指定二进制文件路径 |
| Claude Code、OpenCode 或 Codex | 亲自试用 skill 本身 | 三者均支持;Codex 中技能以 $anatomy 调用 |
克隆仓库:
git clone https://github.com/wheresryan22/anatomy.git
cd anatomy
1.2 把工作副本链接为本地 skill
改代码时想让自己的工作副本直接作为 skill 生效,可以把它软链到个人 skills 目录(如果该目录已有安装副本,先移走):
# Claude Code
ln -s "$PWD" ~/.claude/skills/anatomy
# OpenCode
ln -s "$PWD" ~/.config/opencode/skills/anatomy
# Codex
ln -s "$PWD" ~/.agents/skills/anatomy
软链方式意味着你对 $PWD 下任何文件的修改会立即被 agent 读到,无需重新安装。
二、构建示例页面(Building the examples)
2.1 构建模型与命令清单
每个无框架(framework-free)示例都是一个构建脚本,脚本会在自身所在目录旁写出可独立运行的页面,且构建产物(页面)是提交进仓库的。也就是说:你改动示例后必须重新构建并提交页面,否则 CI 会因页面与源码不一致而失败。
node examples/dial-indicator/build.mjs
node examples/dial-indicator/build.mjs --light
node examples/desk-computer/build.mjs
node examples/desk-computer/build.mjs --light
node examples/arcade-cabinet/build.mjs
node examples/arcade-cabinet/build.mjs --light
node examples/ripple-tank/build.mjs
node examples/ripple-tank/build.mjs --light
node examples/raptor-engine/build.mjs
node examples/raptor-engine/build.mjs --light
node examples/turning-dial/build.mjs
node examples/turning-dial/build.mjs --light
node examples/turning-dial/build.mjs --light --verify
node examples/turning-dial/stress.mjs --light
关键开关说明:
--light:以浅色主题构建(写出<name>-light.html)。浅色是项目优先设计的主题("light ships"),改动涉及视觉时必须同时检查浅、深两个主题的页面。--audit:触发 kit/audit.mjs 的几何审计(见第四节),如node examples/raptor-engine/build.mjs --audit。--verify:构建带window.__isoVerify(记录形状数据)的页面,供scripts/turn-check.mjs --order做 WebGL z-buffer 顺序校验。- 各示例构建耗时差异很大:Raptor(raptor-engine)构建需要几分钟,其余只需几秒。
- examples/test-rig/ 与 examples/spot-plate/ 是 React 组件,没有构建脚本,需复制进 React 工程使用。
2.2 构建后的验收标准
构建完成后,git status --short 必须为空——除非你本意就是要改某个图。CI(.github/workflows/ci.yml)会精确执行上面这些构建命令,随后执行 git diff --exit-code 与 test -z "$(git status --porcelain)",任何多余改动都会让流水线失败。以 CI 中 Turning dial 一步为例:
node examples/turning-dial/build.mjs
node examples/turning-dial/build.mjs --light
node examples/turning-dial/build.mjs --light --verify
node examples/turning-dial/stress.mjs --light
如果某个改动有意改变图面,必须在 Pull Request 中说明,并在同一提交里带上重建后的页面。
三、检查体系总览
项目把检查按"你改了什么就运行哪些"来组织。截图输出统一放入 shots/ 目录(该目录在 .gitignore 中被忽略,不会污染 git 状态)。每一张 PNG 都必须打开肉眼查看——机器检查只是必要而非充分条件。
四类检查与对应脚本的映射关系:
| 检查 | 脚本 | 针对的修改 |
|---|---|---|
| 浏览器驱动回归 | node --test scripts/drive.test.mjs |
改动 scripts/drive.mjs 时 |
| 几何审计 | node examples/<name>/build.mjs --audit |
含管道、线缆、圆形零件的图 |
| 线端检查 | scripts/lines.mjs | 任何涉及线条标记的图 |
| 截图与脚本驱动 | scripts/capture.mjs、scripts/drive.mjs | 视觉与交互验证 |
| 3D 图专项 | scripts/turn-check.mjs、scripts/turn-bench.mjs | 带转动组的 3D 图 |
以下逐类展开。完整参数说明与评审清单见 references/verify.md,3D 检查细则见 references/3d.md。
四、浏览器驱动回归(Browser driver regressions)
改动 scripts/drive.mjs 时,需要确认失败的浏览器求值以非零状态退出、成功的求值仍然正常工作:
node --test scripts/drive.test.mjs
这一回归之所以存在,是因为 drive.mjs 是后面所有浏览器检查的底层驱动:它通过 --remote-debugging-port=0 拉起 headless Chrome、用 WebSocket 与其调试端口通信(chrome-port.mjs 负责等端口就绪)。从 CHANGELOG.md 可看到相关修复历史:浏览器求值抛出或拒绝时必须令进程失败退出;until 条件超时必须以状态 1 退出并停止后续动作;未知 action 必须在运行前被拒绝——"一个拼错的校验步骤不能报告成功"。
五、几何审计(Geometry audit)
5.1 适用对象与运行方式
只要图里有管道、线缆或圆形零件,就必须跑几何审计。以 Raptor 为例:
node examples/raptor-engine/build.mjs --audit
它必须以 audit passed 结尾,且每一行失败计数为 0。
5.2 审计的底层原理
审计由 kit/audit.mjs 提供,工作流是"记录 → 沉降 → 审计"三段式:
- 记录(recorder):
A.recorder(P, { order, spring })创建记录器,绘制辅助函数把每个实体的真实形状、管道路由与装配关系登记进去——recorder 实现 中R.put登记实体(带key/bias/shapes)、R.solid登记实体形状、R.route登记管道与线缆(含gaps缝隙、端帽ends、free标记)。 - 沉降(settle):
A.settle(R, P)用射线对每一对重叠实体求真实深度,在静置、拆解、重放 explode 的每一帧上求值,并据此设置画家算法(painter's order)的 key——见 settle 实现。 - 审计(auditOrExit):
A.auditOrExit(R, P)是--audit钩子,运行全部检查(clearances、solidClearances、terminals、looseEnds、supports、folds、selfOverlaps、crowding、coverage、wobble、seats、depthOrder),打印报告,发现任何问题即以非零状态退出——见 auditOrExit 实现。
一个典型的通过输出(来自 references/verify.md 的记录):
clearance: 0 problems
clearance apart: 0 problems
terminals: 0 ends not on a mount
loose ends: 0
screen folds: 0
support: 0 unsupported solids · 0 hanging tubes · 0 sunk pairs
depth order: 0 problems
through in mid-flight: 0 pairs
...
audit · 80 tubes · 267 solids · 478 items · 1119 depth states · 1707702 overlaps · 4292 order rules · 151.9 s
audit passed
注意末行统计了重叠对数与排序规则数——在 Raptor 这种 267 实体、478 条目的图上,深度状态达 1119 个,重叠对超过 170 万。这种规模是肉眼无法排错的,这正是审计存在的理由。
5.3 审计覆盖的状态空间
审计不仅检查静置状态,还覆盖:
- 拆解态(apart):每个装配沿 explode 向量分开后的状态,检查管道是否穿透、松散端是否悬空;
- 飞行动态(mid-flight):弹簧开合直至稳定前的每一帧,以及每个 stagger 边界前后 8 ms 的反转帧(
reversalsOf); - 前缀状态(prefixStates):各装配按份额
[0.25, 0.5, 0.75, 1]部分拆解的状态。
5.4 常见失败行速查(部分)
| 输出行 | 含义 | 修复思路 |
|---|---|---|
through A × B clearance -2.4 |
管道 A 在该弧长段穿入 B | 让 A 绕 B 重排,留出约 1.5 倍半径的余量 |
terminals: A end 1.40 from B |
A 的端部(或法兰缘)没落在安装面上 | 让路由精确终止在表面法线方向;法兰宽度不超过其下的凸台;曲面体上用法兰垫(saddle pad) |
self-overlap: A:3 its outline folds back |
单个 chunk 的轮廓在屏幕上自交(指向观察者的腿在端口附近转弯) | 通过肘球(elbow ball)离开端口,或给转弯更长的直段 |
wobble: A dr/ds turns at s = … |
手打节点平滑出的轮廓斜率反转,色调带成阶梯 | 给出解析 r(s) 并传 smooth: { slope } |
crowding: A bend × B outlines overlap 0.05 px |
A 的弯或端落在 B 的轮廓线上,看起来像接头 | 重排路由,让交汇处是两条直段的清晰交叉 |
stand-in shapes: A its shapes cover 4% of its drawing |
记录的形状只覆盖绘制的 4%,审计形同虚设 | 记录真实形状(如用 A.slide 记录从压盖滑出的杆) |
order A is in front of B but drawn first |
A 表面更近却被 B 覆盖 | 通常是某个循环丢了排序规则,找该循环中互相联锁的配对 |
审计有一条铁律:"以假形状哄骗审计通过是一个 bug"——
coverage检查专门用来抓这种 stand-in 形状。修复联锁必须改几何(裁切、切向接触),绝不能用 key 偏置(key bias)硬调。
六、线端检查(Line ends)
6.1 为什么需要它
审计只看记录的几何形状,永远看不到线条标记:一条缝、肋线、刻度线或指针若在半空中停住,审计无从发现。因此需要 scripts/lines.mjs 在 headless Chrome 里直接检查绘制成品:
node scripts/lines.mjs examples/dial-indicator/dial-indicator-light.html --out shots/lines-light.png
node scripts/lines.mjs examples/dial-indicator/dial-indicator.html --out shots/lines.png
它必须打印 line ends: 0;--out 会把失败处圈出来写进 PNG。
6.2 判定规则
卡片内每条 .iso-line 的每个开放子路径(缝、槽、肋、标尺线、刻度、指针、导线等),其两端必须落在另一条描边、圆点或轮廓的 1 个 viewBox 像素以内,或者被其后绘制的填充覆盖。短直线标记(≤7 px 的刻度线)只需要一端生根,两端都悬空即失败。kit 自有的轮廓、折痕、倒角与管边不参与检查,fadeLineSvg 渐隐出的端也豁免。
对刻意终止的端(表示印刷文字的字线、指针尾、指针尖),用 lineSvg(d, { free: true }) 标记,其他场合一律禁用。
6.3 常见问题与修复
| 现象 | 修复 |
|---|---|
| 盒子上的缝线距角部内缩 | 用 k.sideSeam(plan, z, P, steps) 作为 slab 的 inner,让它绕角并终止于轮廓 |
| 单面面板线两端内缩 | 让它从面的底部贯穿到顶部,或从一端到另一端 |
| 肋线未到达缝线 | ribsOf(…, { seams: true }),或在带端给 s0/s1 |
| 刻度线悬浮在裸板上 | 放到标尺条上,从边缘生根(topTicks edge、sideTicks top) |
| 通风口/格栅线 | 改成闭合槽(细圆角轮廓,而非线条) |
| 标签板上的字线 | free: true——它们代表文字 |
七、截图捕获与脚本驱动(Capture / Drive)
7.1 Capture:静态截图、手机宽度、悬停、键盘、4× 特写
scripts/capture.mjs 自带 headless Chrome(WebGL 开启:--enable-unsafe-swiftshader --ignore-gpu-blocklist),默认裁切到第一个 .iso-plate,同时打印读数、控制台错误/异常与页面是否横向滚动:
node scripts/capture.mjs examples/ripple-tank/ripple-tank-light.html --out shots/desk.png
node scripts/capture.mjs examples/ripple-tank/ripple-tank-light.html --out shots/phone.png --width 390
node scripts/capture.mjs examples/ripple-tank/ripple-tank-light.html --out shots/joint.png --zoom 200,80,220,170
node scripts/capture.mjs examples/ripple-tank/ripple-tank-light.html --out shots/still.png --reduced
常用选项:--width(默认 1440)、--height(1000)、--scale(2,即 dpr)、--zoom(卡片像素坐标 x,y,w,h 的 4× 特写)、--zoom-scale(4)、--wait(首拍前等待毫秒数)、--key(发按键,7 映射为 Digit7、. 为 Period)、--times(多个时刻补拍,输出 name-<ms>.png)、--select(任意 CSS 选择器,可抓 dev-server 页面中的指定图)、--reduced(模拟减弱动效)、--theme(仅模拟 prefers-color-scheme)。
7.2 Drive:脚本化会话与慢动作连续画幅
scripts/drive.mjs 运行一段脚本化会话,适合时序性场景:悬停 → 点击 → 按键 → 等待某一阶段,也用于慢放连续画幅(contact sheet)捕捉 shader 跳变,以及 --no-webgl 验证 SVG 回退:
node scripts/drive.mjs examples/raptor-engine/raptor-engine-light.html '[["wait",1500],["key","i"],["wait",3000],["shot","shots/firing.png"]]'
node scripts/drive.mjs examples/raptor-engine/raptor-engine.html '[["wait",1500],["shot","shots/no-webgl.png"]]' --no-webgl
node scripts/drive.mjs examples/raptor-engine/raptor-engine-light.html --actions ignite.json
含 until 或 eval 的脚本必须放入 actions 文件(内联 JSON 引号极易写坏)。示例 ignite.json 等待引擎冷却到静止,再以 20 倍慢动作拍摄点火瞬间的连续画幅:
[
["key", "Escape"],
["until", "document.querySelector('[data-readout]').textContent.includes('cold')", 15000],
["slow", 0.05],
["key", "i"],
["sheet", "shots/ignite.png", 100, 16],
["slow", 1]
]
核心 action 速查(完整表见 references/verify.md):
| Action | 作用 |
|---|---|
["wait", ms] |
等待 |
["move", sel, fx, fy] |
分 10 步滑移鼠标到元素内相对位置(触发 pointermove) |
["click"/"drag", sel, ...] |
点击 / 真实指针事件的拖拽(drag 走 setPointerCapture,可用于拖拽转动测试) |
["key", key, sel?, code?] |
聚焦后按键;数字发 DigitN,字母发 KeyX,同名键可传 code |
["slow", factor] |
把页面 rAF 时钟与 performance.now 按倍数放慢(0.05 即 20× 慢动作) |
["until", js, timeoutMs?] |
每 25 ms 轮询表达式直至真(默认 10 s),超时以状态 1 退出 |
["eval", js] |
在页面内执行 JS 并打印结果 |
["shot", out, sel?, scale?, [x,y,w,h]?] |
截图元素或其 CSS 像素区域 |
["sheet", out, every, count, ...] |
每 every ms 拍一帧,拼成带编号的连续画幅 |
["turn"/"orbit", ...] |
3D 图:设转角 / 跨角度连续画幅 |
["lines", out?] |
在当前姿态(拆解、半程)下做线端检查,失败令运行以 1 退出 |
7.3 驱动脚本的四个经典陷阱
scroll后截图才正确:可先滚动到页面上更靠下的图;但用足够高的视口(--height 1300)让整卡可见仍是最简单的方案(图在 scroll 0 即可见,IntersectionObserver会启动它)。- 连续画幅的帧距是
every加截图耗时(60–200 ms,重型 WebGL 页更久):更快的转场要["slow", 0.05]前置、["slow", 1]后置。注意慢放不慢定时器——setTimeout走墙钟,长慢放期间 idle tour 的恢复定时器(Raptor 的 3.6 squietTour)可能在画幅中途重启巡游并关闭引擎。对策:用--preload打桩该定时器、先按Escape、until等到cold再触发转场。 - 等待一个阶段,不要猜:用
["until", "…includes('main stage')", 8000]等读数到位,而非固定延时。 - 页面以内联
<script type="module">注入 live 代码,顶层变量对eval不可见:应通过 DOM 读状态(读数文本、aria-valuetext、data-*),要逐帧计数或读值时用--preload装钩子(它先于页面脚本运行,可包裹requestAnimationFrame或getContext)。
八、3D 图的专项检查(Orbit / turn-check)
8.1 轨道审计(Orbit audit)
带转动组的 3D 图(如 examples/turning-dial)需要额外的轨道审计。它很慢——完整运行每个零件预算 30–40 秒,所以迭代时用 --quick,完整审计放后台跑:
node examples/turning-dial/build.mjs --light --audit --quick
node examples/turning-dial/build.mjs --light --audit > audit.txt 2>&1 &
node scripts/turn-check.mjs examples/turning-dial/build.mjs --fidelity
node scripts/turn-check.mjs examples/turning-dial/turning-dial-verify-light.html --order --step 1
node scripts/turn-check.mjs examples/turning-dial/turning-dial-light.html --lines
node scripts/turn-check.mjs examples/turning-dial/turning-dial-light.html --perf --width 390 --throttle 4
node scripts/turn-bench.mjs examples/turning-dial/build.mjs
只有完整运行的 turn audit passed 才算数:--quick 约少 10 倍状态(continuity 只查 100 个对半候选而非 800 个),只能用于迭代引导;带 --only 的局部运行以 turn audit partial 结束,同样不作数。根据 references/verify.md 的实测记录:一个 28 零件(一个转动组、一个铰链、一个卡扣)的图,quick 运行 85 秒,完整运行 17 分钟——已超出 10 分钟 shell 超时,因此文档明确要求后台运行。
审计扫过每个转动组每 0.3°(order)与每 0.05°(continuity),外加 2000 个随机状态与每个 order 变更事件 ±0.001°;运动片段(gesture / grasp / break-apart)逐帧走查。完整审计源码见 kit/turn-audit.mjs。
8.2 turn-check 的浏览器检查
--fidelity:在 Node 里把每个 live 图元与 kit 构建器逐项对比(每种零件都有对应的"故意画偏 2° 必须失败"的对照实验)。--order:把记录形状渲染进 WebGL z-buffer,与 DOM 填充顺序比对——任意角度与片段下 live 配对的内点像素 ≥4 即失败(对照:反转每层顺序必须产生 ≥1000 个失配像素)。--pops:逐度求一阶差分(θ→θ+0.02°)与 0.1° 二阶差分,全程不允许存活区域与 ≥6 px 的核心(对照:某零件填充隐藏一帧必须失败)。--lines:24 个角度上的线端检查。--perf:1440 宽与 390 宽 + 4× CPU 节流下的帧预算(脚本时间、任务、样式、布局、帧间隔中位数与 p95、live 元素与写入数)。
九、House Rules:必须遵守的项目规矩
这些规则来自 SKILL.md 与 references 目录,破坏任何一条的 PR 都会被要求修改:
- 代码零注释:不写文件头、不在棘手代码旁写说明、不写 JSDoc。解释放在命名与结构里。工具指令(如
"use client")不是注释,予以保留。 - kit 改动必须 opt-in:改动 kit/ 或 scripts/inline-kit.mjs 时,必须新增一个默认保持旧行为的选项或函数;每个既有示例必须重建后逐字节一致(CI 检查)。若改动有意改变图面,需在 PR 中说明并随附重建页面。
- 双主题都要能用,且浅色是出货主题:每个颜色都是 token,带有浅色值与深色覆盖,绝不把字面颜色写进图的 CSS 或 shader。浅色 shader 是为纸张设计的(正常预乘 alpha,绝不用
screen混合),而不是"把深色辉光调暗"。构建用--light,两个页面都要检查。 - 零重叠:任何管道/线缆不得穿过任何物体——静置、拆解、运动每一帧都不行。每个交叉都必须按真实深度顺序绘制(由审计证明,绝不靠肉眼调 key)。修复联锁要改几何,绝不用 key 偏置;记录你实际绘制的真实形状,用 stand-in 哄骗审计是 bug。
- 线条必须有着落、纹理必须渐隐:每条线终止于某个东西。肋排、螺栓圆、缝、规则线终止于真实边缘或渐隐,绝不悬在曲面中央。曲面平滑着色,无色调阶梯。
- shader 永不跳变:每个 uniform 都要有 attack/decay 包络,相位变化必须交叉淡化,每个项在任何边界或画布边缘之前归零。效果活在图的自身相机中的世界空间里,且无 WebGL 时 SVG 仍然可读。
- 每个数字都必须是真实的:读数、运动、图注来自同一个携带真实数值的模型。文档同此规则:没核实过的数字或功能绝不写。
- 逐张读 PNG:请人评审前,先在两个主题下 4× 特写检查每一个接头。
十、修改 skill 的文本(SKILL.md 与 references)
SKILL.md 与 references 是 Claude 实际遵循的指令,因此要求简短、精确、保持同一平实语气:
- 改动 kit API 时,必须在同一个 PR 里更新 references/kit.md。
- 新增示例时:在 examples/ 下建一个目录,内含
build.mjs,写出<name>.html;带--light时写出<name>-light.html;同时把示例加进 SKILL.md 的列表、README 的表格,以及 .github/workflows/ci.yml 的构建列表。
十一、Pull Request 提交流程
按顺序执行:
- 任何大于"修复"的改动,先开 issue 对齐方案。
- Fork 仓库并从
main切分支。 - 一个 PR 只做一个改动。
- 重建每个示例,确认
git status --short只显示你本意要改的文件。 - 运行适用的检查,任何视觉改动都要附带两个主题的截图。
- 在 CHANGELOG.md 的
Unreleased下加一行记录。 - 填写 PR 模板(.github/PULL_REQUEST_TEMPLATE.md)。
CI 必须通过才能合并。 模板的 Checks 清单与 House Rules 一一对应:每个示例可重建且 git 状态干净、代码无注释、kit 改动 opt-in 且字节一致、双主题检查、审计 audit passed、line ends: 0、shader 慢放无跳变且 --no-webgl 可读、3D 图 turn audit passed 且 turn-check 通过、所有数字真实、CHANGELOG 有记录——外加浅色与深色及每个受影响接头的 4× 特写截图。
十二、报告 bug 或请求插图
使用仓库的 issue 表单(bug 报告 / figure request 模板)。如果是图生成错误,请附上:提示词(prompt)、主题(light/dark)、图所在载体(HTML、SVG 还是 React),以及故障截图或特写。提交前请先遵循 CODE_OF_CONDUCT.md,安全问题按 SECURITY.md 的说明处理。
结语
Anatomy 的质量闭环可以用一句话概括:"以 4× 缩放为评判标准,让机器证明几何、让脚本驱动浏览器、让人眼读每一张 PNG"。几何审计证明"没有穿透、没有悬空、深度有序",线端检查补上审计看不见的线条细节,capture/drive 覆盖视觉与交互,turn-check 守护 3D 图,而 House Rules 与 CI 保证每一次改动都不会悄悄降低这套标准。你的贡献路径也很清晰:搭建零依赖环境 → 重建示例确认字节一致 → 跑适用的检查 → 附上双主题截图 → 填好 PR 模板。相关深入资料可按需查阅 references/verify.md(全部检查选项与评审清单)、references/3d.md(3D 检查)与 references/kit.md(kit API)。