# mini_3d_blender **Repository Path**: being_xyk/mini_3d_blender ## Basic Information - **Project Name**: mini_3d_blender - **Description**: 通过Coding Agent,组织调用Blender能力,完成3D建模 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-28 - **Last Updated**: 2026-11-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 3D-Blender 面向 Coding Agent 的单体刚性道具生成、受控重建与资产验证工作区。 生产路线包括:**照片 → 在线 Image-to-3D(默认腾讯混元,经 Provider 抽象层接入)→ 本地 Blender 后处理**,以及经批准的**多视图统一参考 → 默认 Blender 受控重建、按需混元单图部件 → Blender 组装与 Web 验收**。当前多视图在线部件适配尚未实现,真实混合案例须先补齐 Adapter 与测试。项目不进入多物体场景、世界模型或公网多用户。 ## 当前主链路 ```text 单张照片与文字要求 → Generative Asset Spec → 在线图生 3D 服务(默认腾讯混元 hy-3d-3.1,经 `adapters/providers` Provider 抽象层接入) → 轮询原任务并当场下载 GLB/OBJ/MTL/贴图/预览 → 复杂单体经批准可选部件分离、规则几何与 Blender 受控组装 → 本地 Blender 减面、UV/烘焙保留或补齐、贴图预算处理 → model.blend + model.glb + preview.png + Manifest → FBX/OBJ 按需导出与重导入验证 → Workspace 持久化与 Web 查看、验收、删除 ``` 在线生成服务只负责原始三维生成,当前默认腾讯混元 TokenHub,可通过 `SourceCode/adapters/providers/` 的协议与 raw bundle 契约接入其他服务。Blender 仍负责本地后处理、`.blend` 主交付物、格式导出和重导入检查,不再承担旧参数化 Recipe 建模。 生成模型允许基于先验补全不可见几何与纹理。验收关注正面轮廓、比例、主要结构、面数与材质预算,不承诺背面或遮挡区域与实物一致。 ## 功能边界 - 单图在线生成,原始资产永久保留本地副本,云端临时 URL 不作为持久化来源。 - 已有 UV 和高质量烘焙贴图优先保留,只按预算降采样;缺失时才展开或烘焙。 - Web 提供模型库、参考图对照、Three.js 整体预览、历史构建查看与版本对比;只有多部件 Manifest 才显示条件式结构部件定位。静态模型可选摄影棚效果,增强表面反射并显示柔和落地阴影;这只影响浏览器展示,不改模型。 - 支持指定构建 Review、Blender/GLB/FBX/OBJ 下载,以及保留文件和彻底删除两种模型库移除方式。 - 既有参数化与 Legacy Workspace 以只读方式查看、对比、导出和验收,不再提供参数重放或旧模型重建。 - 在线生成由 Coding Agent 调用受控 Adapter 完成;当前没有前端在线生成按钮,也不支持直接网格编辑。 ## 目录职责 ```text SourceCode/ ├── adapters/ # Provider 抽象层(providers/)、TokenHub 默认实现、Blender 后处理与统一导出 ├── backend/ # Workspace、Build、Artifact、Review 与删除 API ├── evaluation/ # 混元与多视图重建资产真实浏览器验收 ├── frontend/ # React + Three.js 资产工作区 ├── shared/ # Generative/Reconstruction Asset、Presentation 与组件组装契约 ├── tests/ # 当前生产回归测试 ├── acceptance.py # 本地在线生成资产全栈验收 ├── package.py # 私有分发包 └── start.py / start.bat # Windows 启动入口 Workspaces/ # 用户输入、Spec、Build、Artifact 与 Review,默认不入库 Document/ # 需求、设计、验收、决策与研究资料 output/ # 测试、验收和浏览器证据,默认不入库 spike/archive/ # 已停止技术路线与历史资源,不属于生产运行时 .tools/ # 本地 Blender,默认不入库 .agents/skills/ # 项目操作手册与 BWorkflow skills .b_workflow/ # BWorkflow runtime、阶段状态与流程报告 ``` 旧参数化 Recipe、Translator、知识服务、旧评测和参数编辑器统一归档在 `spike/archive/parametric-pipeline/`。归档代码不能直接被生产模块导入,也不进入分发包。 ## 本地运行 Windows 双击 `SourceCode/start.bat`,或在项目根目录执行: ```bash SourceCode/.venv/Scripts/python.exe -m SourceCode.backend ``` 默认地址为 `http://127.0.0.1:28080`,可通过 `PORT` 覆盖。启动脚本会复用已有服务。 首次安装或排障: ```bash python -m venv SourceCode/.venv SourceCode/.venv/Scripts/python.exe -m pip install -r SourceCode/requirements.txt npm install --prefix SourceCode/frontend npm --prefix SourceCode/frontend run build ``` Blender 默认读取 `.tools/blender-5.2.3-windows-x64/blender.exe`,可通过 `BLENDER_PATH` 指定。`WORKSPACES_PATH` 可隔离用户实例。 ## 在线生成与本地登记 凭证优先读取 `TOKENHUB_API_KEY` 环境变量,缺省只读项目内 `SourceCode/.env`。凭证不得进入命令行参数、源码、日志、Manifest 或提交。真实在线生成会产生费用,必须由用户单独授权。 ```bash # 不计费模型可用性检查 SourceCode/.venv/Scripts/python.exe -m SourceCode.adapters.providers.tokenhub preflight # 经授权后提交一次图生;已有 submission.json 时只恢复原任务 SourceCode/.venv/Scripts/python.exe -m SourceCode.adapters.providers.tokenhub generate # 经单独授权后提交一次文生部件;prompt 使用 UTF-8 文件 SourceCode/.venv/Scripts/python.exe -m SourceCode.adapters.providers.tokenhub generate-text # 对已下载原始资产执行本地后处理并登记 Workspace SourceCode/.venv/Scripts/python.exe -m SourceCode.adapters.generative_asset # 经批准的后续修订与受控组装 SourceCode/.venv/Scripts/python.exe -m SourceCode.adapters.generative_asset --revision --assembly ``` Base64 只放在请求体内。OBJ 必须连同 MTL 和贴图整目录保存。每次用户操作最多提交一个计费任务,网络或超时失败不得自动重复生成。 复杂单体采用最小必要拆分,按部件选择 Blender 规则几何、图生、文生或镜像复用。`component_assembly` 配置记录来源、任务证据、实例变换和逐来源面数预算;部件先验证并独立减面,再在 Blender 中组装。文生只用于缺少局部参考且容许补全的细节,不作为精确修复工具。最终仍交付一个刚性资产,技术验证与用户视觉验收分离。具体契约见 `Document/plan-online-generative-assets.md`,操作步骤见 `.agents/skills/image-to-model-spec/SKILL.md`。 ## 固定几何材质与贴花修订 后续材质修订复用同一 CLI,来源必须是同资产父 revision 的成功构建: ```bash SourceCode/.venv/Scripts/python.exe -m SourceCode.adapters.material_revision ``` `materials.revision_method` 支持三种方式: - `blender_material_only`:按归一化区域修订 PBR 参数并保留原贴图。 - `blender_texture_only`:替换为受控成品贴图,记录 URI 与 SHA-256。 - `blender_decal_projection`:将受控透明 PNG 按 XY/XZ/YZ 平面、世界坐标范围和显式观察侧逐三角面投射进原 UV,可选 `dark_mask` 局部清除旧标。 贴花输入必须同时包含透明与非透明像素;未命中三角面或没有可见投射像素会失败。生产投射由 Blender+NumPy 完成,UV 清除遮罩外扩 1 像素,不依赖 Chrome、Playwright、SVG 引擎或前端运行时,也不增加贴花几何。SVG、字体和轮廓追踪仅用于投射前的贴花准备。 新 Build 保存 `decals/`、`decal-manifest.json` 和 `decal-projection-result.json`,并在 Verification/Manifest 中记录输入哈希、命中面数、清除/投射像素数、输出哈希及几何/UV 不变签名。最终仍需正反面近景、四格式重导入和真实浏览器验收。契约与边界见 `Document/plan-online-generative-assets.md`,操作步骤见 `.agents/skills/image-to-model-spec/SKILL.md`。 ## 多视图受控重建与按需混合 当前生产实现支持豹 2A8、Skydio X10 和 FA-50 三个经批准主体,由 Agent 在本地 Blender 建立整体刚性资产,不调用在线计费接口。三者的工作尺度分别为 7 米车体长度、1 米桨尖展开和 13 米机身长度;尺度与其他比例均为参考推导,不表示真实测量。 proposal-0034 已锁定多视图证据驱动的按需混合设计: ```text 多张参考图统一分析与哈希登记 → Blender 主体灰模与比例/布局门禁 → 最小必要部件来源计划 → Blender 规则几何/经授权的混元单图部件/镜像复用 → 部件独立验证与减面、Blender 受控组装 → 多视角与近景门禁、统一导出和浏览器验收 ``` Blender 默认负责主体大形、规则结构和安装关系;混元图生只用于清晰可见且适合单图生成的复杂主体或部件;文生只用于缺少参考且容许补全的细节。Provider 继续保持单图输入,不得把不同视角独立生成的完整模型自动拼接或叠加交付。主体灰模未通过前不得提交在线任务,每次在线生成仍需单独授权。 **当前 `reconstruction_asset` 尚未接入在线部件。**新会话开展真实混合案例时,必须先阅读 `AGENTS.md`、`.agents/skills/reconstruction-asset/SKILL.md` 和 `Document/plan-guided-reconstruction.md`,完成必要 Adapter 适配与本地测试,再申请具体在线任务;不得仅凭本设计直接提交计费生成。 纯本地重建入口保持为: ```bash SourceCode/.venv/Scripts/python.exe -m SourceCode.adapters.reconstruction_asset ``` 受信任的本地 Agent 也可将模型专用脚本与 `model.json` 放入对应 `Workspaces//model/`,在上述命令后加 `--workspace-model`。框架将声明文件复制并校验到 Build 的 `build-inputs/`,执行快照并在 `execution.json` 保存哈希与执行证据。后续修订使用 `--revision`,失败 Build 的同输入重试使用 `--retry-build `。旧内置入口保持兼容;快照用于追溯,不保证不同环境逐字节复现,也不是运行不可信代码的沙箱。声明格式、执行约定和限制见 `Document/plan-guided-reconstruction.md`。 登记后,Presentation 声明运动的资产可在 Three.js 中第三人称跟随固定折线轨迹,支持播放、暂停和复位;不实现履带/车轮、炮塔、车辆物理或地形。具体契约见 `Document/plan-guided-reconstruction.md`,操作步骤见 `.agents/skills/reconstruction-asset/SKILL.md`。 ## 验证入口 ```bash # 流程完整性 node .b_workflow/bin/bwf.js validate # 单元测试 SourceCode/.venv/Scripts/python.exe -m unittest discover -s SourceCode/tests -v npm --prefix SourceCode/frontend test # 编译与生产构建 SourceCode/.venv/Scripts/python.exe -m compileall -q -x "[\\/]\.venv[\\/]" SourceCode npm --prefix SourceCode/frontend run build # 全栈验收与私有分发包 SourceCode/.venv/Scripts/python.exe SourceCode/acceptance.py SourceCode/.venv/Scripts/python.exe SourceCode/package.py ``` 全栈验收复用 `Workspaces/s5-real-chair-photo/` 中已下载的在线生成原始资产,在独立 Workspace 中真实执行 Blender 后处理,不调用在线 API,也不覆盖已验收模型。验收覆盖四种格式、重导入、服务重启、真实浏览器、保留文件删除、分发包内容与隔离启动。 ## 文档指针 - 当前基本约定:`Document/constitution.md` - 当前交付规格:`Document/spec.md` - 当前生产架构:`Document/design/current-architecture.md` - 在线生成 Provider 接入:`SourceCode/adapters/providers/README.md` - 当前生成计划:`Document/plan-online-generative-assets.md` - 固定几何贴花投射提案:`Document/archive/proposal-0036-20261106-merged.md` - 多视图受控重建计划:`Document/plan-guided-reconstruction.md` - 多视图操作手册:`.agents/skills/reconstruction-asset/SKILL.md` - 按需混合设计提案:`Document/archive/proposal-0034-20261106-merged.md` - 验收与证据:`Document/验收.md` - 工程收敛提案:`Document/archive/proposal-0014-20261030-merged.md` - 历史归档索引:`Document/archive/INDEX.md` - 混元在线研究:`Document/research/side-chair-hunyuan-online.md`