给Anatomy提PR:贡献者指南——构建示例、跑检查与'字节级一致'铁律

原创2026-10-12 21:49:251,989 阅读
文章标签:AI 技能人工智能图形学前端

给Anatomy提PR:贡献者指南——构建示例、跑检查与'字节级一致'铁律

本文为 Anatomy 贡献者指南:Anatomy 是一个 Claude Code 技能,能把技术概念变成可交互的等距机器图解(SVG + WebGL + 3D)。下面带你从零开始,学会构建示例、跑检查,并理解它最严格的"字节级一致"铁律,最终提交一个能过 CI 的 Pull Request。

Anatomy 等距机器图解示例:Raptor 火箭发动机分解视图

先看懂你要改的东西

Anatomy 的每个"图"都是一台真实感很强的机器:由几十上百个小零件组成、带读数、可交互,并且用自动化检查自我验证。贡献之前,建议先打开一个已构建的页面(examples/ 下的 .html 直接双击即可)感受一下质量基准:

模块 作用
SKILL.md 技能本体:Claude 遵循的工作流与工艺规则
kit/ 绘图库:等距相机、实体零件、几何审计、WebGL 层、3D 运行时
examples/ 8 个完整示例,构建产物已提交进仓库
scripts/ 无头 Chrome 检查脚本:截图、驱动、线条端点、3D 校验
references/ 长文指南:verify.md、3d.md 等

参与即表示同意遵守 CODE_OF_CONDUCT.md。

环境准备:3 样东西就够

Anatomy 的设计哲学是零依赖——不需要 npm install:

  • Node.js 20.10+:构建脚本、kit 和检查全部只用 Node 内置模块
  • Google Chrome 或 Chromium:浏览器检查用;找不到时设置 CHROME_PATH 指向二进制
  • Claude Code:用于体验技能本身
git clone https://gitcode.com/gh_mirrors/anato/anatomy
cd anatomy

想在本地边改边试这个技能,把工作副本软链到个人技能目录(先移走已安装的副本):

ln -s "$PWD" ~/.claude/skills/anatomy

一键构建示例:最快的本地验证

每个非框架示例都是一个构建脚本,把独立的 HTML 页面写到脚本旁边——这些页面是提交在仓库里的(见 CONTRIBUTING.md):

node examples/dial-indicator/build.mjs
node examples/dial-indicator/build.mjs --light
node examples/raptor-engine/build.mjs
node examples/raptor-engine/build.mjs --light

🕒 小示例几秒完成,Raptor 发动机需要几分钟。examples/test-rig/ 和 examples/spot-plate/ 是 React 组件,没有构建脚本。

dial-indicator 指针量表示例:Anatomy 最小的示例,约 300 行

构建后的第一件事:运行 git status --short,它必须没有任何输出(除非你本来就打算改某个图)。这正是 CI 做的事——跑完全部构建命令后执行 git diff --exit-code,定义见 .github/workflows/ci.yml。

检查清单:按改动类型跑对工具

CONTRIBUTING.md 的原则是:跑与你改动匹配的检查,并且打开它生成的每一张 PNG 亲眼看。截图放进被忽略的 shots/ 目录。

改了什么 跑什么 通过标准
带管道/线缆/圆零件的图 node examples/raptor-engine/build.mjs --audit 结尾 audit passed,所有失败项为 0
线条、刻度、指针 node scripts/lines.mjs examples/dial-indicator/dial-indicator.html --out shots/lines.png 打印 line ends: 0
页面外观/交互 node scripts/capture.mjs <页面> --out shots/desk.png(--zoom 截 4× 特写) 肉眼通过
运动/着色器时序 node scripts/drive.mjs <页面> '[["wait",1500],["shot","shots/x.png"]]',--no-webgl 验 SVG 回退 无闪烁跳变
3D 图(turning-dial) node examples/turning-dial/build.mjs --light --audit --quick 迭代,完整审计放后台 只有完整运行的 turn audit passed 才算数

ripple-tank 波纹槽示例:capture 与 drive 脚本的常用检查对象

几条实操提示(摘自 references/verify.md):

  • 带 until 或 eval 的复杂会话,写进 actions JSON 文件用 --actions 传入
  • 着色器检查用 ["slow", 0.05] 放慢 20 倍,用联系表抓"pop"(跳变)
  • 3D 轨道审计很慢(完整跑约 30–40 秒/零件),用 --quick 迭代、完整跑放后台

"字节级一致"铁律:kit/ 改动必须 opt-in

这是 Anatomy 最有名的规矩,写在 CONTRIBUTING.md 的 House rules 里:

对 kit/ 或 scripts/inline-kit.mjs 的任何改动,只能新增选项或函数,且默认行为等于旧行为。所有现有示例必须能逐字节重建(byte-identical);CI 会检查这一点。

为什么这么严?因为 8 个示例的构建页面都提交在仓库里,任何一个 kit 改动都可能悄悄改变所有图的输出。所以:

  • ✅ 改 kit 后,重新构建每一个示例,git status --short 必须干净
  • ✅ 如果你的改动本意就是要改变某个图,必须在 PR 中说明,并把重建后的页面一并提交
  • ✅ 其他铁律同样硬:代码里不写注释(解释放进命名与结构)、双主题都要工作且 light 是"设计优先"的主题、颜色只走 token、无重叠(交叠必须由审计证明深度顺序)、着色器永不跳变

turning-dial 3D 模式示例:完整轨道审计约 15–20 分钟,是 3D 贡献的重点检查对象

提 PR 的 7 步清单

来自 CONTRIBUTING.md,照着做即可:

  1. 比修 bug 更大的改动,先开 issue 对齐方案
  2. Fork 仓库,从 main 拉分支
  3. 一个 PR 只做一件事
  4. 重建所有示例,确认 git status --short 只显示你有意改的内容
  5. 跑适用的检查;视觉改动附上双主题截图
  6. 在 CHANGELOG.md 的 Unreleased 下加一行
  7. 如实填写 PR 模板——它本身就是一份检查清单(重建干净、无注释、byte-identical、audit passed、line ends: 0……)

最后:CI 必须全绿才能合并。CI 会重跑全部构建并执行 git diff --exit-code,任何未被声明的字节变化都会失败。

小结

给 Anatomy 提 PR 的心法就三句话:构建示例、跑对检查、字节级一致。它的自动化验证(几何审计、线条端点、截图特写、字节对比)比你想象的挑剔,但正是这些规则,才让每张图在 4× 放大下依然无懈可击。祝你的第一个 PR 一次通过 ✅

登录后查看全文
anatomy