给Anatomy提PR:贡献者指南——构建示例、跑检查与'字节级一致'铁律
给Anatomy提PR:贡献者指南——构建示例、跑检查与'字节级一致'铁律
本文为 Anatomy 贡献者指南:Anatomy 是一个 Claude Code 技能,能把技术概念变成可交互的等距机器图解(SVG + WebGL + 3D)。下面带你从零开始,学会构建示例、跑检查,并理解它最严格的"字节级一致"铁律,最终提交一个能过 CI 的 Pull Request。
先看懂你要改的东西
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 组件,没有构建脚本。
构建后的第一件事:运行 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 才算数 |
几条实操提示(摘自 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、无重叠(交叠必须由审计证明深度顺序)、着色器永不跳变
提 PR 的 7 步清单
来自 CONTRIBUTING.md,照着做即可:
- 比修 bug 更大的改动,先开 issue 对齐方案
- Fork 仓库,从
main拉分支 - 一个 PR 只做一件事
- 重建所有示例,确认
git status --short只显示你有意改的内容 - 跑适用的检查;视觉改动附上双主题截图
- 在 CHANGELOG.md 的
Unreleased下加一行 - 如实填写 PR 模板——它本身就是一份检查清单(重建干净、无注释、byte-identical、
audit passed、line ends: 0……)
最后:CI 必须全绿才能合并。CI 会重跑全部构建并执行 git diff --exit-code,任何未被声明的字节变化都会失败。
小结
给 Anatomy 提 PR 的心法就三句话:构建示例、跑对检查、字节级一致。它的自动化验证(几何审计、线条端点、截图特写、字节对比)比你想象的挑剔,但正是这些规则,才让每张图在 4× 放大下依然无懈可击。祝你的第一个 PR 一次通过 ✅



