一、它是啥：一张参考图，AI 直接写 Three.js 代码重建 3D 模型
brief 一句话：不给网格文件、不下载素材包，AI 直接写 Three.js 代码把图里的物体重建出来——8 阶段雕刻流水线自动打磨，每个细节都过质量门，模型自带动画可用。这跟「图生 3D」的几条老路（摄影测量 / 网格提取 / 下载现成素材包）都不一样，它叫 reconstruction-by-code：产物是一行行可继续改的过程式 Three.js 代码，不是一个 .glb 死网格。
先按数据红线实查主仓（2026-10-04 查）：img2threejs/img2threejs，★17464 / fork 1462 / Apache-2.0 / Python / 35MB / 09-23 还在推 / 104 个 open issues。仓库描述原话：「Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.」——brief 里写的「16.3k 星」已经涨到 17.5k 了，Apache-2.0 这条核对✓。Trendshift 日榜双第一是 brief 的口播，我这边查不到实时榜单，如实不代证。
顺带确认它跟 brief 说的两个官方事实对得上：①「Claude Code、Codex 都能挂它当技能」——主仓带一份 33KB 的 SKILL.md，front-matter 写 license: Apache-2.0、正文「Agent-agnostic: works under Claude Code, Codex, or OpenCode」；②「官网 demo 免安装在线玩」——见下节 showcase 仓 + 官网 img2threejs.io。
二、双仓结构：主仓是引擎，showcase 是官方画廊
| 仓库 | 角色 | ★ | license | 它存什么 |
|---|---|---|---|---|
| img2threejs（主仓） | 8 阶段雕刻流水线引擎 + 技能 | 17464 | Apache-2.0 | forge/ 流水线、SKILL.md、docs/grimoire |
| img2threejs-showcase | 官网在线画廊（brief 的「demo 可玩」） | 170 | 无 license | Vite demo，纯代码几何，零外部网格/CDN |
两仓关系值得点破：主仓有标准 Apache-2.0、能商用；showcase 仓本身没挂 license（它的模型是主仓引擎跑出来的产物展示）。brief 只说「仓库地址在置顶评论」，我实查是两个仓——写「它」的时候主仓和官网画廊别混了。showcase 的 README 有句关键设计：「Demo code cannot depend on remote meshes, CDNs, or network calls」+「Runtime geometry live in the repository」——所有 3D 都是纯过程式代码生成、页面不下载任何网格文件，这正是 brief「不给网格文件」这句话的技术落地。
三、机制：8 阶段雕刻流水线，「质量门驱动」而非「一口气生成」
「每个细节都过质量门」这句，读 forge/ 源码才信。它不是个「输入图→输出模型」的黑盒，而是一条编排器驱动的阶段流水线，目录摆得很清楚：
forge/
stage1_intake/ 摄取：提取 PBR/毛发/特征点/细节清单/拟合相机位姿（extract_pbr_evidence 33KB …）
stage2_spec/ 规格：new_sculpt_spec 103KB 生成规格，validate_sculpt_spec 149KB 校验它
stage3_build/ 构建：generate_threejs_factory 212KB 生成 Three.js 工厂代码 + run_gates 跑质量门
stage4_review/ 审查：33 个门脚本（self_intersection / turntable_gate / hair_gate / vlm_gate …）
stage5_rig/ 绑定：action_design 90KB + geodesic_skinning + emit_animation_runtime（模型自带动画）三个「只有看代码才写得出」的机制点：
① 质量门是编排器卡住的，不是模型自觉。入口 forge/next.py 每次只报「当前 pass + 未满足的 acceptance criteria + 下一条命令」，一旦某条不过就打印 STOP: <stopReason> 并 exit 3，SKILL.md 原话「Obey a hard stop; never continue from memory」。它不盲目往下走——过不了门就不许进下一阶段，这就是「每个细节都过质量门」的字面实现。
② 返工有界，防 AI 卡死。状态机 state.py 默认 --max-per-pass 3 --max-total 6：每个 pass 最多修 3 轮、全链路最多 6 轮，超了就 stop。这是「雕刻流水线自动打磨」能收敛的关键——没有这个上限，一个细节反复打补丁能把整个流程拖死。README 不会写这条，只有看 state.py 的 argparse 默认值才见得到。
③ 校验比生成还重。stage2 里校验规格的 validate_sculpt_spec.py（149KB）比生成规格的 new_sculpt_spec.py（103KB）还大 40%；最大的单文件是 stage3 的 generate_threejs_factory.py（212KB，负责把规格翻成可运行的 Three.js 工厂代码）。stage4_review 一个阶段就堆了 33 个门脚本（自交检测、转台门、毛发门、VLM 视觉门、顶点区域门…），投入产出的重心全压在「验」上。
四、我把官方 demo 画廊真跑了一遍（本地无头浏览器）
主仓那条 8 阶段流水线要挂 Claude Code / Codex 的 vision loop（SKILL.md 明确要 agent 视觉自纠循环）才能真跑，手头这台机没有那套 agent 宿主，跑不了完整雕刻——这条我如实写边界，不硬凑。但 showcase 是纯 Vite 静态画廊，能在本地裸跑：clone → npm install → vite 起服务 → 无头浏览器真渲染，截 3 个 brief 点名的可玩模型（都是 registry.ts 里的实 id，非 PPT）：
这三个 demo 的共同点正好证了主仓的 code-only 承诺：showcase 页面不 fetch 任何远程网格/贴图，几何全靠运行时的过程式 Three.js 代码画出来（皮卡丘那张左侧就写着 PROCEDURAL SCENE），所以「每个都能转着看、还能看源码」——右侧 Model Inspector 的 Motion/Parts/Export/Explode Parts 面板 + 仓库里那个 .ts 文件本身就是证据，不是个黑盒模型文件。截图在本地无头浏览器跑的，跑完即销毁（停 vite、删本地 clone+chrome 缓存），不留垃圾。
brief 里「CS 的 AWP 皮肤（37K 三角面 · 150 个部件）」这两个具体数字我没逐一实查（showcase 里 AWP 的真 id 是 awp-medusa-v2），按数据红线我把它标成「brief 口播值、非我实测」，不挂进正文当硬数据。
五、跟同类比：什么时候用它，什么时候别用
| 路线 | 产物 | 强 | 何时别用 |
|---|---|---|---|
| 摄影测量 / NeRF / 3DGS | 稠密网格+贴图（数据驱动） | 拍照多张能还原真物体 | 只有一张图、或要可控可继续编辑的模型时，它出的是「死网格」 |
| 「图生 3D」下载现成模型 | .glb 网格文件 | 快、有现成资产 | brief 明确「不下载素材包」——涉及版权/风格不可控/跟不了你的品牌 |
| 裸 Three.js 手写 | 手写代码 | 完全可控 | 从一张图重建「这个物体长啥样」这一步得自己啃，且没有质量门兜底 |
| 其他 AI 出 3D 图床 | 模型文件/贴图 | 端到端省事 | 产物不可代码级修改、不能「回炉精修」、不好进 CI |
| img2threejs | 过程式 Three.js 代码 | 一张图→可继续改的代码；8 阶段质量门卡细节；模型自带动画；agent-agnostic 挂 Claude Code/Codex | 只有一张参考图、藏着的背面它猜不到（要如实说「近似/风格化」）；完整流水线要 agent 视觉宿主 |
一句话定位：它把「从一张图到 3D 模型」这件苦差事，做成了「生成 + 质量门」的工程流水线，产物是可读的代码而非黑盒文件。适合要「可控、可交接、能回炉精修」的场景；一次性要个大概网格，摄影测量更快。
六、坑与边界（红线，别照搬旧文案）
① 星数/榜单要刷新：brief 写「16.3k 星」，实查已 17,464（涨 1.1k）；「Trendshift 日榜双第一」是口播，查不到实时榜，不代证。
② 两个仓、两套 license：主仓 Apache-2.0（可商用），showcase 官方画廊无 license——引用/二次分发 showcase 的 demo 代码前要看它的 CONTRIBUTING，别默认「主仓 Apache 就等于 showcase 也 Apache」。
③ 完整 8 阶段流水线要 agent 视觉宿主（Claude Code / Codex / OpenCode 的 vision loop）。没有那套宿主，你只能跑 showcase 静态展示、或手动一步步喂 next.py，自动「打磨收敛」这块是断的。
④ 单图天花板：一张参考图看不到背面/内部，官方 SKILL.md 自己要求「State explicitly when output is approximate/stylized/low-poly」——出图后别当它像素级还原，藏面是它猜的。
⑤ 「37K 三角面 / 150 部件」是 brief 口播，我没逐一实测（AWP 真 id 是 awp-medusa-v2），正文不把它当硬数据。
七、我的判断
适合：要「一张图 → 可控可继续改的 3D 模型」、且已经在用 Claude Code / Codex 做工作流的团队。把 SKILL.md 软链进 agent，让 AI 按 8 阶段流水线出一版过程式 Three.js，再进 img2threejs.io 那种画廊看效果、看源码，这条「生成 → 质量门 → 可玩展示 → 看源码」的闭环是目前「图生 3D」里工程化最完整的之一。
不适合：想要「像素级还原一张图」、或没有 agent 视觉宿主只能手动啃 next.py；一次性要个大致网格（摄影测量更快）。另外商用前把「主仓 Apache-2.0 / showcase 无 license」这条边界搞清楚，别把「公开」当「无约束」。它 17.5k 星 + 38KB CHANGELOG + 104 open issues，社区活跃度是实打实的，但「能出好模型」和「能在你的宿主里顺畅跑通」是两回事，进 CI 前先拿你自己的图走一遍 8 阶段试试收敛。