glbforge

GLBForge — 面向 AI 生成 3D 内容的网页就绪层

glbforge.dev · 输入原始 AI 网格，输出可交付资产

3D 生成后的确定性处理层，专为 Agent 和 CI 构建。提供两项功能：编辑网格时作为 Agent 的眼睛（inspect 在几十毫秒内读取网格的语义信息，diff 指出上次编辑破坏了什么），以及发布前的关卡（analyze → optimize → verify，使用版本化性能预算作为可用于 CI 的契约，并以 SSIM 数值衡量“无可见损失”）。还可将 2D 作品锻造成水密 3D 模型，将照片路由给生成器，并导出 GLB / STL / USDZ。

状态

• ✅ glbforge inspect — 编辑循环中的读取（亚秒级）：检查模型是一个整体还是包含悬浮部件、是否水密或存在孔洞/重叠、尺寸（米）、朝上轴、原点位置、未应用/镜像变换——每项发现都带有版本化规则 ID（如 core-geometry@1 中的 topo/open-edges）、测量/启发式置信度、可能原因及其置信度，以及具体的修复方法。绝不猜测 front。与 MCP inspect 工具功能相同：每次编辑后都调用它。
• ✅ glbforge diff <before> <after> — 显示上次编辑以来的变化，包括编辑造成的问题：各部件尺寸差异（“‘legs’ 沿 X 轴窄了 30%”）、三角形和壳体数量差异、拓扑退化（之前水密，现在有 3 个开放环）、原点漂移、节点变换、新增或移除的网格，以及 --visual 前/侧/顶/等轴视图 SSIM（摄像机固定为编辑前的取景）。与 MCP diff 工具功能相同。
• ✅ glbforge analyze — 预算评估报告 + 命名 lint 规则
• ✅ glbforge optimize — 焊接/简化/LOD/压缩，以满足预算
• ✅ glbforge scaffold — 为优化后的资产生成 React Three Fiber 查看器
• ✅ glbforge meshy — 通过 Meshy REST API 生成/下载（图像/文本 → 3D，--optimize 胶合流程）
• ✅ glbforge ship <input> — 一次调用即可将 GLB、徽标或照片转为通过预算门槛的资产：路由（优化 / 锻造 / 生成）→ 分析 → 优化 → 过关。--json 会将路由、锻造决策和完整优化报告作为一份文档输出。
• ✅ MCP 服务封装以上全部功能（@glbforge/mcp，28 个工具，在官方 MCP 注册表中的条目为 dev.glbforge/glbforge）
• ✅ GLBForge Studio（glbforge ui）— 本地 Web UI：拖放分析、一键优化，并在视口中通过前后对比滑块查看效果；支持徽标锻造、带实时进度的 Meshy 生成、STL 导出。无需托管；完全在你的机器上运行。
• ✅ glbforge extrude — 确定性地将徽标/图形转为 3D（无需 AI 或额度）：描摹轮廓（行进方格 → Douglas-Peucker → earcut），将其拉伸为水密模型，并将源图像投射回模型作为纹理。对于 2D 作品（徽标、字标），它远胜于图像转 3D 生成：约 1.5k 个三角形，而非约 2M 个；轮廓精确，颜色保留原样。--bevel 可添加标牌风格的圆角边缘（采用斜接限制和经钳位探测的内缩，加上裂缝缝合步骤，即使在细窄的涂鸦笔画上也能保持水密；在真实徽标样例上验证，边界边和非流形边均为 0 条）。系统会检测照片输入并将其路由给 Meshy；也可以通过 --matte auto 先将主体从背景中提取出来（见下文）。也可通过 MCP 工具 extrude_image 使用。

--matte auto — 提取主体，锻造贴纸

照片没有 alpha 通道，也没有白色底面，因此锻造器无法处理。matte（matte/border@2，core/src/extrude/matte.ts）是第三种方案：它将画面边缘视为背景，沿着这种颜色向内扩展，并将剩下的部分视为主体——这正是手机“提取主体”功能背后的思路。它只使用简单的连通性算法，因此无需下载模型，在 Node 和浏览器中运行结果完全一致，而且逐字节确定。颜色决定每个像素的类别，连通性决定如何处理它，因此杯子的把手不会被填上：被背景色包围的区域是孔洞，不是主体。较小的封闭区域（高光、JPEG 杂点）会被填充，较小的不连通部分则会作为碎屑丢弃。匹配会以一种方向感知色度：如果某个像素颜色接近背景且比背景更暗，它就是背景的阴影，因此投射阴影不会再与物体焊在一起；而灰色桌面上的白色杯子（更亮、色相相同）则绝不会被吞掉。描摹前会用 3x3 多数滤波器平滑遮罩，避免边缘处的 JPEG 振铃产生数百个轮廓。

容差会自动调节。 tuneMatte 会遍历八档阶梯并保留得分最高的切分结果，因为旋钮两端的置信度都会下降——过于严格会留下背景，过于宽松则会吞掉物体。Studio 会在放入图片时自动执行（滑块会设为调优后的值，并标记为 auto）；CLI 中的 --matte-tolerance auto 会执行此操作并打印阶梯；MCP 的 matte_preview 默认也会自动调节。

先预览，再锻造。 看不到容差，就无法选择容差，因此所有提供该功能的地方都可以预览切分结果：glbforge extrude photo.jpg --matte auto --matte-preview cut.png 会写出切分结果（主体不透明，被移除的背景以淡影显示），并打印相关数值，但不构建几何体；extrude_image 接受 matte_preview: true，并返回该图像及列出建议尝试容差的 nextActions；Studio 则会在移动滑块时，于提取按钮下方实时重绘切分结果。

遮罩是一种推断结果，因此也会报告相关信息——覆盖率、碎片数、孔洞数，以及根据边缘均匀程度、切分所经过区域的对比度和结果尺寸是否合理而得出的置信度。低于 0.4 时，锻造器会拒绝处理并提供这些数值，而不是返回一团模糊结果；MCP 会将通过的情况显示为 SUBJECT_LIFTED 诊断信息，让 Agent 知道该轮廓是推断出来的，而非直接读取的。CLI 中的 --matte auto、extrude_image 中的 matte，以及 Studio 中的 ✂ 提取主体并锻造，都恰好出现在原本只能碰壁的拒绝提示位置。

用法

pnpm install && pnpm build
node packages/cli/dist/index.js analyze fixtures/veiled-guardian.glb --profile mobile-hero
node packages/cli/dist/index.js optimize fixtures/veiled-guardian-tex4k.glb -o out.web.glb --lods 40000,10000
node packages/cli/dist/index.js scaffold out.web.glb -o viewer && cd viewer && pnpm install --ignore-workspace && pnpm dev
node packages/cli/dist/index.js ui model.glb   # GLBForge Studio on localhost:5177

inspect <file>（glb/gltf/usdz/usda/usdc）可以回答 Agent 在盲目编辑网格时容易弄错的问题：对于一个 15 万三角形的资产，耗时约 0.1 秒；对于一个未经处理的 200 万三角形生成结果，耗时约 0.8 秒（焊接拓扑处理本身每 15 万个三角形约需 70 毫秒）。--profile authoring （默认）会将拓扑问题视为警告，因为这些问题最可能是上一次编辑造成的；预算配置文件（mobile-hero）则会将其报告为信息。--packs core-geometry@1,core-scene@1 可固定规则包，--no-topology 会跳过焊接处理（规则会列为已跳过，绝不会悄然消失），--strict 遇到警告时以状态码 1 退出，--json 会输出完整报告。 --expect "chair, Z-up, meters, single-shell, 0.4-1.2m tall, front -Y, watertight, origin base" 会将本次运行转为一份契约（intent@1）：测量壳体数量、是否水密、尺寸范围和原点，并在不符合时作为错误处理（以状态码 1 退出）；仅提供类别时，会根据粗略尺寸表发出合理性警告，并注明置信度；front 会被记录为声明，绝不会进行测量；GLB 中的 Z-up 仅作为信息提示，因为 glTF 按定义采用 Y-up。解析器无法归类的标记会报告出来，不会丢弃。

glbforge usage 是本地的可选启用计数器，用于统计唯一能说明 GLBForge 是否参与流程的指标：每个资产的调用次数。默认关闭；使用 glbforge usage --enable 或 GLBFORGE_USAGE=1 启用。此后，每次 inspect / diff / analyze（以及每次 MCP 调用）都会向 ~/.config/glbforge/usage.jsonl 追加一行 JSON（使用 GLBFORGE_CONFIG_DIR 可更改目录）。数据绝不会发送到任何地方；--clear 会将其删除。由于每次编辑都会更改文件哈希，资产会按谱系分组：同一会话中的同一路径、两小时内的同一路径、diff 边（之前 → 之后），或显式指定的 --lineage <id>。报告会给出每个谱系调用次数的中位数 / p90，以及至少检查过五次的资产占比。

analyze 标记：--profile mobile-hero|desktop-hero|product-configurator、 --json、--no-topology。资产超出预算时会以非零状态码退出，可像 linter 一样将其接入 CI。optimize 标记：--target <tris>、--lods a,b、 --no-textures、--no-compress、--no-verify。LOD 文件（--lods 40000,10000）仅包含几何数据：剥离材质、焊接位置、使用 meshopt 简化；当非流形拓扑导致简化过程停滞时（堆叠的 forge 图层、重复的壳体），会改用网格顶点聚类，确保始终达到目标 ——— 如果发生这种情况，CLI 和 Action 报告会注明 grid-clustered。

在附带的 Meshy 7 测试素材（4K 纹理，199 万三角形）上测得： 89.4MB → 5.5MB（缩小 93.8%），评分 25 → 100，耗时约 7 秒。 流程： 去重 → 焊接 → 使用 meshopt 按预算简化（误差阶梯）→ 补齐缺失法线 → 缩小纹理并转换为 WebP（法线贴图接近无损）→ 修剪 → EXT_meshopt_compression → 感知验证。

“无可见损失”是经过测量的，而非口头保证

每次 optimize / ship 都会从四个固定摄像机视角渲染资产的前后版本（确定性软件光栅器，2 倍超采样，平滑着色，基础颜色纹理），并使用 SSIM 为图像对评分。最差视角必须达到配置文件的 minSsim 下限（mobile-hero 为 0.94，product-configurator 为 0.95，desktop-hero 为 0.96），否则报告卡会生成一条错误级别的 fidelity/perceptual 检查结果，命令也会以非零状态码退出，与违反预算时完全相同。通过时，该数值会作为信息类检查结果记录，因此所有地方的报告都会附带此评分（CLI、--json、MCP、Studio）。

  visual fidelity ✓ SSIM 96.7%  weakest view 95.8% @ verify_135 · floor 94.0% · geometric deviation ≤ 0.1%

在测试素材上：预算处理（199 万 → 15 万个三角形）的测量结果为 0.958；强制降至 4 万个三角形时降到 0.896（未通过，而且这是预期结果 ——— 发丝会合并）；1 万个三角形时测得 0.73。glbforge verify <candidate> <reference> 可用同样的方式为任意两个文件评分。摄像机的位置和取景范围固定为参考文件的边界，因此偏移或缩小后的结果无法通过重新取景来获得高分。

软件包

软件包	用途
@glbforge/core	纯分析库：统计信息、拓扑、规则、预算
glbforge (CLI)	glbforge 命令行界面
@glbforge/meshy	类型化 Meshy REST 客户端：任务、带退避的轮询、下载
@glbforge/mcp	MCP 服务：验证 / 检查 / 渲染 GLB 和 USD，并提供稳定的错误代码 + prim 路径、紧凑报告卡片、优化 / 发布 / 锻造 / STL / USDZ（支持 dry-run + diff）以及生成

MCP 服务

.mcp.json 会自动为 Claude Code 注册该服务（请先构建： pnpm build）。对于其他客户端：

claude mcp add glbforge -- node /path/to/XUI/packages/mcp/dist/index.js

专为 Agent 打造。每个工具都返回同一种封装 — { ok, summary, duration_ms, errors[], data } — 其中 errors[] 包含 每条诊断信息及其稳定代码（docs/error-codes.md）、严重级别和 对应的 prim 路径，并且每个响应都通过 schemas/<tool>.output.json 验证。validate、inspect_geometry、 inspect_animation、inspect_materials、analyze_performance 和 inspect_all 可读取 GLB、glTF、USDZ、USDA 和 USDC（纯 TypeScript USD 读取器，单层）；render / render_animation_strip 可渲染其中任意格式， 并可呈现任意动画时间点的姿势。修改类工具支持 dry_run，并返回 diff 和 post_validation，还会将所做的每项更改（生成法线、合并图元、转码纹理……）作为带代码的条目逐一报告。 结果以紧凑卡片呈现（判定、关键数字、所有 错误和主要发现、nextActions、drillDown 指针）；需要时可通过 inspect_report 查看完整的发现 / 纹理 / 拓扑信息；每个接触 GLB 的 工具都会返回渲染缩略图或 2x2 转台图，而优化失败时会返回参考 | 结果 | 变化热力图，以便 Agent 了解损失发生的位置（任意两个文件可使用 compare_glb）。capabilities 会在制定计划前说明哪些提供方已配置密钥，以及 KTX2 是否可用；每个写入的文件都会报告其 sha256；只读工具带有 readOnlyHint，以便客户端自动批准。生成工具特意拆分为 create/status/download 三步——任务需要几分钟，Agent 可按自己的节奏轮询，而无需让工具调用一直等待。

动画资源

蒙皮网格和变形目标会经过骨骼感知处理路径：meshoptimizer 的属性感知简化器会将蒙皮权重（以及每个目标的变形 增量）视为顶点属性，主导关节边界上的顶点会被锁定，并且每个属性 — JOINTS_n、WEIGHTS_n、每个目标 — 都会使用相同的重映射进行 压缩。蒙皮、逆绑定矩阵和动画片段均保持不变；analyze 会报告 scene/animated-asset。 已在带有旋转片段和变形目标的绑定圆柱体上测试（混合带保持不变，权重已归一化，结果确定）。

面向 iOS AR 的 USDZ

npx glbforge animate model.web.glb       # → model.idle.glb (looping idle clip, no rig; -p spin|bob|sway|breathe|hop)
npx glbforge companion model.idle.glb    # a talking desktop character (Electron via npx -y @glbforge/companion; --mcp registers its bridge, --hooks puts every Claude Code session on its face)
npx glbforge usdz model.web.glb          # → model.usdz (PNG textures; --jpeg for smaller)

写入包含 UsdPreviewSurface 材质（基础颜色、通过通道输出实现的金属度／粗糙度、法线、遮蔽、自发光、Alpha 遮罩／混合）的二进制 USD（usdc，crate 0.8.0）图层，将 WebP 纹理转码为 PNG/JPEG，并按规范要求，将有效载荷按 64 字节对齐后打包为仅存储模式的 zip。crate 写入器由 GLBForge 自行实现，使用纯 TypeScript 编写；其字节布局已按区段与 Pixar 写入器生成的文件逐一核对，test/usd-oracle.py 会使用 Pixar 的 USD 打开 usdc 及其 usda 对应文件，并检查每个 prim、值、连接和关系是否完全相同（设置 GLBFORGE_PXR_PYTHON，指向安装了 usd-core 的 Python，即可运行）。在 Meshy 测试样例中，二进制图层大小为 5.4MB，而 ASCII 图层为 13.4MB。--usda 会改为写入文本图层。动画资源导出为 UsdSkel：关节按父级优先排序，并包含绑定和静止变换；网格上使用 SkelBindingAPI 存储关节索引／权重；以 30 fps 对首个动画片段采样，并写入 SkelAnimation（平移、四元数旋转、半精度缩放）。Oracle 测试会让 Pixar 的 UsdSkel 根据结果重新计算关节变换。变形目标会转换为 UsdSkel BlendShape prim，并同步采样权重轨迹（只有变形目标的网格会获得一个单关节骨架，以便 UsdSkel 应用变形）。没有材质的图元会获得一个中性默认材质，因为未绑定的网格会渲染为 RealityKit 的品红色“缺少材质”图案。KTX2 输入会被拒绝，并提供相应说明。MCP 服务中也提供 export_usdz，Studio 中则有 Export USDZ 按钮（浏览器内也可使用——纹理通过 canvas 转码）。在 <model-viewer ios-src="model.usdz"> 中引用它，即可在 iOS 上显示 AR 按钮。已在 iPhone 的 AR Quick Look 中验证：纯平面材质、完整纹理（JPEG 颜色、PNG 法线和金属度／粗糙度）、蒙皮加动画，以及 BlendShape 导出，均可正常打开和播放。

glbforge init — 让项目为 Agent 做好准备

npx glbforge init            # in your project; idempotent

在 CLAUDE.md 中写入由标记界定的章节（预算内容、要使用的脚本和 MCP 工具、forge 与 generate 的路由规则，以及“无可见损失”的衡量方式），添加 glb:check / glb:analyze / glb:optimize / glb:ship / glb:verify / glb:studio npm 脚本（并将 glbforge 添加为 devDependency），同时在 .mcp.json 中注册 MCP 服务（使用 --client cursor|both 可配置 .cursor/mcp.json）。现有内容、其他 MCP 服务和自定义脚本都会保留；再次运行时会报告所有内容均未更改。标志：--profile、--assets <dir>、--local、--dry-run、--force、--no-claude-md、--no-scripts、--no-mcp。从此以后，该项目中的任何 Agent 会话都能自动使用 GLBForge。

glb:check 会运行 glbforge audit <dir>：检查文件夹中的每个 GLB 是否符合预算；只要有一个不符合，就会以非零状态退出——这是 pre-commit / CI 的门禁。

GitHub Action

# .github/workflows/assets.yml
on: pull_request
permissions: { contents: write, pull-requests: write }
jobs:
  assets:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with: { fetch-depth: 0, lfs: true }
      - uses: glbforge/glbforge@main
        with:
          profile: mobile-hero
          optimize: true      # open a PR with the web-ready files

仅对拉取请求中发生更改的 GLB/glTF 文件运行。每次运行都会发布一条置顶报告卡评论，并根据预算决定检查是否通过。启用 optimize: true 后，还会优化每个未通过检查的资源（在原文件旁生成 <name>.web.glb，或通过 replace: true 原地替换），进行感知验证，并针对拉取请求分支创建或更新拉取请求，附上结果——包括优化前后对比表、视觉 SSIM 和流水线步骤。相同的输入、配置文件和 CLI 版本始终会生成完全一致的字节，因此会按内容哈希缓存输出（cache: true），重复运行不会产生变更。来自复刻仓库的拉取请求无法获得机器人分支；其输出会改为上传为工作流构件。创建拉取请求需要在仓库设置中启用 Allow GitHub Actions to create and approve pull requests（对于组织，还需要在组织设置中启用）；若未启用，运行仍会发布报告卡，并将优化后的文件上传为 glbforge-optimized 构件。在优化模式下，只要优化后的输出通过检查，门禁就会通过，因此修复只差一次合并。target-triangles 会覆盖配置文件中的三角形目标，lods: 40000,10000 会将仅包含几何数据的 LOD 文件（<name>.web.lodN.glb）添加到拉取请求；两者都会纳入缓存键。输入项：profile、fail-on-budget、optimize、optimize-all、replace、verify、target-triangles、lods、cache、open-pr、pr-branch、version、token。

Meshy API key

将 .env.example 复制为 .env，并设置 MESHY_API_KEY（已加入 gitignore，会自动加载，且绝不会覆盖真实环境变量）。也可以完全不使用文件，而改用 macOS Keychain：

security add-generic-password -a "$USER" -s meshy-api-key -w
# ~/.zshrc: export MESHY_API_KEY=$(security find-generic-password -s meshy-api-key -w)

完整流程只需一条命令：

node packages/cli/dist/index.js meshy image art.png --pbr --optimize -p mobile-hero -o hero.glb

开放模型生成（fal.ai）

通过 GPU 推理运行开放权重，实现真正的图像→3D 生成——成本通常比商业生成低 5-25 倍。设置 FAL_KEY（https://fal.ai/dashboard/keys）：

node packages/cli/dist/index.js gen photo.png --model hunyuan --optimize   # Hunyuan3D-2
node packages/cli/dist/index.js gen photo.png --model trellis             # TRELLIS
node packages/cli/dist/index.js gen photo.png --model triposr             # fastest

工作室的生成面板会自动显示所有已配置的提供商（Meshy 和三个开放模型并列显示；托管模式下会显示各模型的积分成本）。

规则

perf/* 预算违规会导致构建失败；geo/*、topo/*、mat/*、tex/*、scene/* 描述 AI 生成资源中常见的缺陷，每项都附有具体的修复方法。参见 packages/core/src/rules.ts。

设计决策

• 纯 Node/TS，无需依赖 Blender。 分析和优化基于 @gltf-transform + meshoptimizer + sharp 运行——原生支持 glTF，无有损 DCC 往返转换，可通过 npx 安装，适合 CI。各项操作设计为可插拔后端，因此以后可以添加仅 Blender 支持的功能（重拓扑、UV 展开、烘焙），而无需更改 CLI 接口。
• 在焊接空间中处理拓扑。 边界/非流形计数会在合并位置重复的顶点后计算，因此未焊接的导出不会产生无用数据。
• 预算是配置文件，而非建议。 资源会通过或未通过一个有名称且带版本的目标（mobile-hero@1 固定版本；不带版本的 mobile-hero = 最新版本；上限绝不会原地更改）。每项上限背后的方法以及版本变更日志见 docs/BUDGETS.md / glbforge.dev/budgets。确定性使其能够自动化。

测试资源

• fixtures/veiled-guardian.glb — Meshy 7 高细节几何阶段导出（1.99M 个三角形，仅含 POSITION，34MB）。已焊接且为流形；测试确保我们不会误报。
• fixtures/veiled-guardian-tex4k.glb — 同一资源经过 4K 纹理阶段后的版本（89MB）。其 77k 个位置重复顶点是 UV 接缝拆分，并非冗余；topo/unwelded 规则可以区分这些情况（已进行回归测试）。