Anatomy 项目贡献指南:从环境搭建、构建示例到四类质量检查与 PR 全流程

原创2026-10-13 22:21:071,853 阅读
文章标签:AI 技能人工智能图形学前端

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 提供,工作流是"记录 → 沉降 → 审计"三段式:

  1. 记录(recorder):A.recorder(P, { order, spring }) 创建记录器,绘制辅助函数把每个实体的真实形状、管道路由与装配关系登记进去——recorder 实现 中 R.put 登记实体(带 key/bias/shapes)、R.solid 登记实体形状、R.route 登记管道与线缆(含 gaps 缝隙、端帽 ends、free 标记)。
  2. 沉降(settle):A.settle(R, P) 用射线对每一对重叠实体求真实深度,在静置、拆解、重放 explode 的每一帧上求值,并据此设置画家算法(painter's order)的 key——见 settle 实现。
  3. 审计(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 驱动脚本的四个经典陷阱

  1. scroll 后截图才正确:可先滚动到页面上更靠下的图;但用足够高的视口(--height 1300)让整卡可见仍是最简单的方案(图在 scroll 0 即可见,IntersectionObserver 会启动它)。
  2. 连续画幅的帧距是 every 加截图耗时(60–200 ms,重型 WebGL 页更久):更快的转场要 ["slow", 0.05] 前置、["slow", 1] 后置。注意慢放不慢定时器——setTimeout 走墙钟,长慢放期间 idle tour 的恢复定时器(Raptor 的 3.6 s quietTour)可能在画幅中途重启巡游并关闭引擎。对策:用 --preload 打桩该定时器、先按 Escape、until 等到 cold 再触发转场。
  3. 等待一个阶段,不要猜:用 ["until", "…includes('main stage')", 8000] 等读数到位,而非固定延时。
  4. 页面以内联 <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 都会被要求修改:

  1. 代码零注释:不写文件头、不在棘手代码旁写说明、不写 JSDoc。解释放在命名与结构里。工具指令(如 "use client")不是注释,予以保留。
  2. kit 改动必须 opt-in:改动 kit/ 或 scripts/inline-kit.mjs 时,必须新增一个默认保持旧行为的选项或函数;每个既有示例必须重建后逐字节一致(CI 检查)。若改动有意改变图面,需在 PR 中说明并随附重建页面。
  3. 双主题都要能用,且浅色是出货主题:每个颜色都是 token,带有浅色值与深色覆盖,绝不把字面颜色写进图的 CSS 或 shader。浅色 shader 是为纸张设计的(正常预乘 alpha,绝不用 screen 混合),而不是"把深色辉光调暗"。构建用 --light,两个页面都要检查。
  4. 零重叠:任何管道/线缆不得穿过任何物体——静置、拆解、运动每一帧都不行。每个交叉都必须按真实深度顺序绘制(由审计证明,绝不靠肉眼调 key)。修复联锁要改几何,绝不用 key 偏置;记录你实际绘制的真实形状,用 stand-in 哄骗审计是 bug。
  5. 线条必须有着落、纹理必须渐隐:每条线终止于某个东西。肋排、螺栓圆、缝、规则线终止于真实边缘或渐隐,绝不悬在曲面中央。曲面平滑着色,无色调阶梯。
  6. shader 永不跳变:每个 uniform 都要有 attack/decay 包络,相位变化必须交叉淡化,每个项在任何边界或画布边缘之前归零。效果活在图的自身相机中的世界空间里,且无 WebGL 时 SVG 仍然可读。
  7. 每个数字都必须是真实的:读数、运动、图注来自同一个携带真实数值的模型。文档同此规则:没核实过的数字或功能绝不写。
  8. 逐张读 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 提交流程

按顺序执行:

  1. 任何大于"修复"的改动,先开 issue 对齐方案。
  2. Fork 仓库并从 main 切分支。
  3. 一个 PR 只做一个改动。
  4. 重建每个示例,确认 git status --short 只显示你本意要改的文件。
  5. 运行适用的检查,任何视觉改动都要附带两个主题的截图。
  6. 在 CHANGELOG.md 的 Unreleased 下加一行记录。
  7. 填写 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)。

登录后查看全文
anatomy