OpenFigura：AI Agent 工具实践指南

面对实际交付，我看OpenFigura的重点不在星标，而在这项能力：reynold-hu/OpenFigura。这类软件开发工具真正难在依赖、接口和异常处理往往比主路径更影响采用，仓库说明只能作为第一层证据。先在隔离分支完成一个可回滚的小任务更稳妥；过程中要观察安装步骤、接口契约、测试结果和错误信息，失败也应能解释原因。整体来看，它适合需要可检查开发流程而非单次演示的工程师拿来做对照测试，最终决定仍应回到真实结果和维护状态。

OpenFigura是一个本地的、代理驱动的3D资产生产框架。 添加参考图片和通俗易懂的简介；找回有纹理的 GLB，Blender 可检查场景、多视图渲染和出处记录 这准确地说明了每件文物是如何制作的。

代理用户： 手册为 docs/usage.md — 或 注册MCP服务器（openfigura-mcp）并让figura_*工具 自我描述。

还没有参考图吗？ docs/input-guide.md 有 GPT Image / Seedream / Grok / Midjourney 的复制粘贴提示 产生 OpenFigura-friendly 输入。

它是付费“将您的艺术作品上传到某人的云端”的替代品 工作流程 — Tripo、Mesy 和朋友 — 不适用于任何特定工具。的 一代本身来自可交换的开放后端（Pixal3D/TRELLIS.2 运行时，以及您稍后注册的任何内容）。 OpenFigura 提供镗孔、 有价值的部分：稳定的工具表面、能力检测、再现性 账本和真正的基于渲染的检查，而不是相信一个漂亮的 预览。

reference image + brief
        │
        ▼
  ┌───────────────┐    backends: pixal3d.cpp, trellis, …   ┌──────────────┐
  │ openfigura-core│ ─────────────────────────────────────▶ │  GLB + PBR   │
  │  (engine)      │    generate → render → inspect → export│              │
  └───────┬───────┘                                         └──────────────┘
          │
   ┌─────────────┬─────────────┐
   ▼              ▼             ▼
 CLI         MCP server    (later: own
 (scripts,   (Codex,       agent loop)
  CI)        opencode,
             Claude…)

为什么不只是代理？

代理（Codex、opencode、Claude Code、pi）已安排工具调用 比我们今天可以发布的任何框架都要好。他们缺少的是一个 本地、私有、免费、可检查 3D 管道，具有稳定的工具合约。 这正是 OpenFigura 层。 MCP 服务器是主服务器 接口；对于脚本和 CI，存在具有相同命令的 CLI，并且 可选的自托管代理循环可能会稍后出现——所有三个共享一个核心。

快速启动

代理和人类的完整手册：docs/usage.md。

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"           # core + CLI
pip install -e ".[mcp]"           # + MCP server

# Register a backend binary (e.g. a prebuilt pixal3d.cpp runtime)
openfigura backends

# Generate → render → inspect → export, one task, one ledger
openfigura generate input.png --backend pixal3d --seed 42 -o out/
openfigura render  out/task.json
openfigura inspect out/task.json
openfigura export  out/task.json --format glb

每次运行都会写入provenance.json：输入SHA-256，确切的命令行， 后端版本、挂机时间、峰值内存、输出哈希值。如果不能的话 从该文件重新运行，这是一个错误。

要求和诚实的限制

• 一代后端有自己的硬件需求。 Pixal3D Q8路径是 在 Apple Silicon（金属）上验证； CPU-only x86 可以工作，但速度很慢 — 本地+私有+免费是承诺，速度是每个后端的属性。
• 输出是密集的三角形网格（~10⁶ tris）。 Rigging/animation 需要 重新拓扑学； OpenFigura 跟踪作为后处理步骤，它不 假装一次性生成已准备好进行游戏。
• 视觉质量是通过渲染视图来判断的，而不是通过生成器自己的 预览。这是设计规则，而不是免责声明。