v3.2.8 — 文生3D 接入（Hyper3D 云端 + 本地 Hunyuan3D-2 免费回退）

v3.2.8 — 文生3D 接入（M1：Hyper3D 云端 + 本地开源 Hunyuan3D-2）

背景

结合开源 Blender MCP 项目（见 docs/BLENDER_MCP_INTEGRATION.md）的 M1 方案：为「生成飞机」等需求提供云端文生3D 能力，并补齐免费本地替代，使「文生3D」在无付费 Key 时仍可零成本使用。

新增能力

• 云端文生3D：runHyper3DTextTo3D 调用 Hyper3D(Rodin) text-to-3d，新增 POST /api/text-to-3d 路由（复用 /api/split 的二进制 + manifest 响应格式）。
• 本地开源文生3D（免费）：新增 scripts/hunyuan3d_text_infer.py，调用腾讯开源 Hunyuan3D-2（hy3dgen）本地生成 GLB；runLocalTextTo3D 负责 spawn 与结果回收。
• 智能回退：handleTextTo3D 支持 mode=auto|cloud|local；auto 默认有 Hyper3D Key 走云端，否则回退本地 Hunyuan3D-2。
• 前端：AI 绘画面板新增「🌐文生3D」按钮 + 提供方模式下拉（自动/云端/本地），复用现有加载与拆解流程（生成后点「爆炸」即可拆解）。

测试

• tests/provider-test.mjs 新增 runHyper3DTextTo3D 成功路径、空提示词 400、缺 Key 400 三个用例。
• Node 测试 32/32 通过（含新增用例）。
• 本地推理脚本错误守卫验证：未装 hy3dgen 时返回清晰安装引导，退出码 1。
• 端到端链路验证（本机无 GPU）：POST /api/text-to-3d?mode=local 正确走到本地脚本并返回清晰错误 JSON。
• 注：本机为 macOS 无 NVIDIA GPU，未做「成功生成」实测；需在带 CUDA 的机器 pip install hy3dgen 后验证真实生成。

验证

• 语法检查通过（server.js / ai-paint-panel.js / hunyuan3d_text_infer.py）。
• markdownlint 对涉及文档校验通过。

v3.2.7 — 拆解进度反馈改进

v3.2.7 — 拆解进度反馈改进（消除「卡在已上传」误判）

背景

用户反馈「Blender 正在拆解模型... (已上传)」长时间无变化，以为卡死。经排查，后端 /api/split 本身正常（curl 复现返回 X-Success: true、响应头与 body 大小一致，真实拆解 80s 内成功完成并落盘）。问题在前端缺乏长耗时反馈与解析失败被静默吞掉。

修复

• 上传完成后文案明确为「已上传，等待后端处理」，避免误以为卡死。
• 新增 xhr 下载进度监听：Blender 边生成边返回时，界面实时显示 ⏳ Blender 拆解中... xx%（无 Content-Length 时显示已接收 MB 数），长耗时（数十秒）期间有可见进度。
• load 回调的 catch 由静默 resolve(null) 改为 console.error 打印完整错误栈 + 界面提示「⚠️ 响应解析失败，回退到 JS 拆解」，不再掩盖真实错误。

验证

• node --check main.js 通过，无 lint 错误。
• 后端 /api/split 经 curl 复现响应头与 body 一致，X-Success: true。

v3.2.6 — 修复飞机等预设生成不准 + 派发测试

v3.2.6 — 修复「飞机」等预设生成不准 + 派发回归测试

修复

• 根因：blender_ai_paint.py 的 match_prompt 此前强制把任何匹配到的预设都改走 create_lego_style(prompt)，丢弃了模板对应的真实生成器 creator。结果「飞机」等预设不再调用 create_airplane，而是坠入乐高兜底的随机积木分支，表现为「生成不准」。
• 修复：恢复 match_prompt 的 creator 派发，让「飞机/汽车/机器人/房子/火箭/Quest3」等预设真正调用各自的真实几何体生成器。
• 连带回归修复：乐高模板的 creator 是特殊标记字符串 'lego_style'，恢复派发后会导致 main() 中 creator() 抛 TypeError。已在 match_prompt 中对 'lego_style' 特殊标记单独处理，返回可调用对象。

工程改进

• 新增 tests/ai_paint_test.py（stdlib unittest，注入 bpy/bmesh/mathutils stub 以在 Blender 外运行），覆盖 match_prompt 关键词→生成器派发，锁定本次修复不再回归。9 项测试全部通过。
• 从 .gitignore 移除 blender_ai_paint.py（它是 server.js 调用的核心 AI 绘画脚本，此前被错误忽略导致修复无法入库）。
• package.json 新增 npm run test:py 脚本。
• 版本号同步至 3.2.6。

验证

• Node 测试：118/118 通过（96 单元 + 22 provider）
• Python 测试：9/9 通过

v3.2.5 — WebView getBoundingClientRect null 报错修复

v3.2.5 修复说明

修复内容

• 修复 WebView 预览（http://localhost:3001/）偶发的 Uncaught TypeError: Cannot read properties of null (reading 'getBoundingClientRect')。
• 根因：index.html 引用的 main.js 缓存破版字符串停留在 ?v=3.2.2，WebView 复用了加入 null 守护之前的旧模块；getBoundingClientRect 两处调用点（main.js、vendor/OrbitControls.js）本身已带守护，但旧版无守护导致报错。

改动文件

• index.html：main.js 缓存破版字符串 ?v=3.2.2 → ?v=3.2.4，强制 WebView 重新拉取最新模块。
• main.js：OrbitControls 的 import 加 ?v=3.2.4 破版字符串；两处顶层 renderer.domElement.addEventListener 改为可选链 renderer?.domElement?.addEventListener 防御性守护。
• package.json / package-lock.json：版本号同步至 3.2.4（与已发布 tag 一致）。

验证建议

在 WebView 中硬刷新（或重启预览）后，错误应不再出现。

v3.2.4

v3.2.4 补丁发布

新增 markdownlint 修复脚本并修复剩余实质警告（MD009 / MD026 / MD029 / MD034 / MD037 / MD040）。

🛠️ 新增工具

• scripts/fix_md_warnings.py：一键修复 markdownlint 实质警告。
  • MD009 / MD026 / MD029 / MD037 委托 markdownlint --fix（参考实现，正确处理嵌套有序列表与强调边界）。
  • MD034（裸 URL）→ 包裹为 <>；MD040（围栏缺语言）→ 按内容猜测 bash / json / html / js / text。
  • 状态感知处理围栏（闭合围栏保持无语言），并屏蔽行内代码块内的 URL，避免误改。

🐛 文档修复

• MD029（有序列表前缀）：全量 docs/ 与根目录 .md 重排为 1,2,3…；被代码块打断的列表按要求重启为 1。
• MD034（裸 URL）：START.md 等裸 URL 包裹为 <>（代码块内的 URL 保持不变）。
• MD040（围栏缺语言）：README.md / DEVELOPER_GUIDE.md 等围栏补全语言标记。
• MD009 / MD026 / MD037：全量文档清理行尾空格、标题尾标点、强调内多余空格。

⚙️ 配置

• .markdownlint.json 启用 MD029（有序列表前缀已修复，纳入强制校验）。

📌 说明

• 剩余警告 MD058（表格前后空行）、MD047（文件结尾换行）、MD060（表格列样式）不在本次范围内。

v3.2.3

v3.2.3 补丁发布

图片转 3D VLM 脚本 Bug 修复 + 全量文档 markdownlint 治理。

🐞 Bug 修复

• VLM 默认模型回退错误：scripts/vlm_img_to_blender.py 各 provider 新增 default_model，未显式指定模型时按 provider 回退（StepFun / Kimi / Claude / OpenAI 各自默认），避免选 Claude / OpenAI 时误用 StepFun 的默认模型。
• GLB 误导出：仅当本次在 Blender 中成功执行过代码才导出 GLB，防止 VLM 调用失败时把场景中残留的旧 GLM_VLM_* 对象误导出。

🧹 工程化

• 新增 .markdownlint.json（关闭 MD013 / MD022 / MD024 / MD031 / MD032 / MD036 / MD029 等噪声规则）。
• 全量 docs/*.md 修复 markdownlint 实质警告：裸 URL 加 <>、标题去尾标点、无语言代码块补语言标记、清理行尾空白。

📄 文档

• docs/CHANGELOG.md 顶部补 v3.2.3 条目。

v3.2.2 · VLM 下拉精简 + OpenAI 支持

相对 v3.2.1 的改动

• VLM 图片转 3D · 视觉模型下拉精简：「视觉模型」下拉显示文字仅保留提供商名（OpenAI / StepFun / Kimi / Claude），不再展示具体模型版本号；实际模型在 ai-config.html 各提供商的配置区选择。
• 新增 OpenAI 作为 VLM provider：scripts/vlm_img_to_blender.py 的 VLM_PROVIDERS 增加 openai（OpenAI 兼容 /chat/completions），使 UI 下拉中的 OpenAI 选项可真正调用。
• 文档更新：docs/VLM_IMAGE_TO_3D.md 的模型表、配置示例、base_url 列表去掉具体模型名并补充 OpenAI 条目；UI 步骤与默认回退说明同步简化。

使用提示

• VLM 路线为程序化几何近似重建，需 Blender 运行且 MCP 插件监听 localhost:9876。
• 选 OpenAI / Kimi / Claude 需在 ai-config.json 配置对应 API Key 并保存。

v3.2.1 — 各 AI 提供商最新模型补全

更新内容

本次更新为各 AI 提供商补全最新模型，并将默认模型切换至最新版本。

OpenAI

• 新增 gpt-5.6-sol（默认）、gpt-5.6-terra、gpt-5.6-luna
• 新增 gpt-4.6
• 保留 gpt-4o / gpt-4o-mini / o3 / o4-mini
• 默认模型由 gpt-3.5-turbo 切换为 gpt-5.6-sol

Anthropic

• 新增 claude-sonnet-5（默认）、claude-opus-4-8、claude-haiku-4-5-20251001
• 默认模型由 claude-3-sonnet-20240229 切换为 claude-sonnet-5

Kimi（Moonshot）

• 新增 kimi-k3（默认）、kimi-k2.7-code、kimi-k2.6
• Moonshot V1 系列标注 8/31 下线
• 默认模型由 moonshot-v1-8k 切换为 kimi-k3

其他

• StepFun 已含 step-3.7-flash
• NVIDIA / Ollama / LM Studio 增加模型建议列表（<datalist>）
• 图片转3D 提供商 UI 现已可选 Meshy / Tripo / Hyper3D
• 新增三厂商 API Key 测试连通性预检（/api/test-provider）
• Hyper3D 帮助链接改为开发者门户 developer.hyper3d.ai

注：gpt-4.6 为按需求保留项，若账号未开通该模型会返回模型不存在错误，可改选 GPT-5.6 系列。

安装

下载对应系统的启动脚本，双击即可启动本地服务。

v3.2.0 · 图片转3D VLM 视觉模型路线

亮点

• 图片转3D 新增 VLM 视觉模型路线：视觉模型"看"图 → 生成 Blender Python 代码 → 沙箱执行 + 自动修复循环 → 导出 GLB（程序化近似重建）。
• 可选视觉模型：StepFun step-3.7-flash / Kimi kimi-k3 / Claude claude-3-sonnet，在 ai-config.html 的"图片转3D → AI 视觉模型（VLM）"下拉切换。

改动

• ai-config.html：新增 VLM 单选与视觉模型下拉，含切换 / 保存 / 加载。
• server.js：handleImageTo3D 新增 vlm 分支（runVLMImageTo3D），GET /api/ai-config 补充 vlm 字段。
• scripts/vlm_img_to_blender.py：多 provider 支持（OpenAI 兼容走 /chat/completions，Claude 走原生 Messages API），沙箱自动修复 + GLB 导出。

使用提示

• 默认走 StepFun（需已配置 StepFun Key）。
• 选 Kimi / Claude 需先在配置页填入对应 API Key 并保存。
• VLM 路线为程序化几何重建，非高保真纹理网格；实时重建需 Blender 运行且 MCP 插件监听 9876。

v3.1.0 — 多模态生成增强 & 架构重构

🆕 新功能

• 图片转3D 完善：接入统一 provider 配置体系，支持本地重建与去背景
• NVIDIA API 支持：支持 NVIDIA GLM-5.2 模型，可配置 base_url/api_key/model
• StepFun API 支持：接入阶跃星辰大模型，支持多个模型选项
• AI 配置界面：可视化 AI 模型配置页面 (ai-config.html)
• 交互与多模态能力增强：所有提示词实时调用 Blender 生成模型
• 乐高风格增强：人仔/汽车/房子更有区分度（梯形腿部、圆柱手臂、三角屋顶等）
• AI 生成多样化模型：大象、超人、蝙蝠侠、跑车等 GLB 模型

🔧 改进

• 代码重构：消除 server.js 重复代码，6 个 AI 提供商合并为 3 个
• 纹理烘焙修复：改用 trimesh 内嵌纹理到 GLB，替换 xatlas 导出方式
• 乐高砖块生成：支持 2x4, 2x2, 1x2 等标准砖块，正确凸点位置和旋转

🏗️ 基础设施

• CI/CD：添加 GitHub Actions Node.js 构建 + Python lint，GitHub → Gitee 同步
• 双平台启动脚本：start.command (macOS) + start.bat (Windows)
• 仓库清理：移除敏感信息、大文件、重复文件

🐛 修复

• StepFun API 模型和超时问题
• ESLint 配置修复，浏览器全局变量声明
• match_prompt 返回类型修复
• clear_scene 完全清除 Blender 数据