工作流：AI 3D 生成 → 本地精修

ModelSyncBridge 负责**「找工厂生产」（异步任务 + 轮询），本地 MCP（blender-mcp / trident-mcp 等）负责「在软件里落地 / 精修」（即时命令 + 场景状态）。在同一个客户端注册两个服务，让 Agent 当调度员**——无需 MCP 协议桥接，文件系统就是共同语言：

Agent(调度员) → ModelSyncBridge(生成) → artifacts/ (manifest.json + model.glb)
                                          │
                                          └─ local_path ─► blender-mcp / trident-mcp (场景内精修)

1. 5 分钟快速上手

前置条件

需要	说明
Docker 或 Go 1.22+	运行 bridge，二选一
一个 Agent 客户端	Cursor / Claude Code / Trae / Cline 任一
（可选）Blender + blender-mcp	跑通「精修」环节需要；只想验证生成链路可不装
（可选）厂商 API Key	Meshy / Tripo3D / Hyper3D 任一个

Mock 模式说明：mock 厂商内置、无需 key，5 秒完成任务，适合验证「任务生命周期 + MCP 工具」链路。但它的产物 URL 是占位地址（mock.example.com），本地文件下载会失败——因此 Mock 模式下 local_path 为空、artifacts/ 里不会有实际 GLB。要拿到真实模型文件，请配置任一真实厂商。

Step 1 — 启动 bridge

# Docker
docker run -d --name msb -p 8080:8080 -p 8081:8081 \
  -e MSB_AUTH_ENABLE_API_KEY=true -e MSB_AUTH_API_KEYS=sk-local \
  ghcr.io/halor-qu/modelsyncbridge:latest

# 或源码
git clone https://github.com/HaloR-Qu/ModelSyncBridge.git && cd ModelSyncBridge
go build -o msb ./cmd/server/ && ./msb

curl http://localhost:8080/v1/3d/health   # {"status":"ok",...}

Step 2 —（可选）配置真实厂商

以 Hyper3D 为例（各厂商 ENV 变量见 deployment.zh.md「配置参考」）：

MSB_PROVIDER_HYPER3D_ENABLED=true MSB_PROVIDER_HYPER3D_API_KEYS=sk-xxx ./msb

不配置也可以——先用 Mock 把链路跑通，再补 key 重跑即可。

Step 3 — 在客户端注册两个 MCP 服务

Cursor 示例（~/.cursor/mcp.json，Windows：%USERPROFILE%\.cursor\mcp.json）：

{
  "mcpServers": {
    "modelsyncbridge": {
      "url": "http://localhost:8081/mcp",
      "headers": { "Authorization": "Bearer sk-local" }
    },
    "blender-mcp": {
      "command": "cmd",
      "args": ["/c", "uvx", "blender-mcp"]
    }
  }
}

其他客户端配置见 mcp-clients.zh.md。Windows 提示：本地命令型 MCP 必须用 cmd /c 包装。

Step 4 — 用一句话指挥 Agent

用 ModelSyncBridge 生成一个「赛博朋克风格的悬浮摩托，低多边形」。
任务成功后，把 download_3d_model_content 返回的 local_path 交给 blender-mcp，
在 Blender 里导入，简单整理后导出为 D:\models\final.glb。

Agent 会自动执行：generate_3d_model → 轮询 query_3d_task 直到 success → download_3d_model_content → local_path → blender-mcp 导入/精修 → 导出。若只想验证生成链路（未装 Blender）：

只用 ModelSyncBridge 生成一个「低多边形小猫」，生成成功后告诉我 local_path，不要导入。

Step 5 — 验证产物

artifacts/
├── t_<task_id>/
│   ├── model.glb        # ← 可直接拖入 Blender / Unity / Godot
│   ├── preview.png
│   └── manifest.json    # 任务元信息 + 各路径
└── latest.json          # 指向最近完成的任务产物

2. 工件目录约定

由 storage.artifacts_dir 配置（默认 ./artifacts，ENV MSB_STORAGE_ARTIFACTS_DIR）：

model.glb / preview.png 是 data/models|previews 下文件的硬链接（跨卷退化复制）——导入或移动不会重复占用大文件。
manifest.json / latest.json 中的 paths.* / manifest 均为绝对路径，脚本可直接读取。

3. Agent 获取模型的两种方式

推荐 — download_3d_model_content：query_3d_task 返回 success 后，用 task_id 调用；返回 local_path（本机绝对路径，免 base64 中转）+ content_b64（仅 ≤20MB）+ download_url。
直接读文件：从磁盘读 artifacts/latest.json 或 artifacts/t_<task_id>/manifest.json，适合脚本或有文件系统访问权的场景。

4. 各本地 MCP 的导入模板

Blender（blender-mcp）

import bpy
bpy.ops.import_scene.gltf(filepath=r'<local_path>')

Trident-MCP（Maya）

import maya.cmds as mc
mc.file(r'<local_path>', i=True, type='GLB')   # 按你的加载器调整

Godot / Unity / UE

Godot：ResourceLoader.load(path) 或直接把 .glb 拖进编辑器。
Unity：把 model.glb 拖入 Assets/（glTFast / Unity glTF importer）。
Unreal：Content Browser Import 该 .glb（glTF importer 插件）。

5. 常见问题

问题	处理
生成失败 / `NO_AVAILABLE_PROVIDER`	未配置真实厂商时给 `provider` 传 `mock`；或调 `list_3d_provider` 看可用厂商
拿到 `local_path` 但 Blender 打不开	bridge 与 Blender 必须同一台机器；Windows 路径用原始字符串 `r'...'`
只想拿 base64 数据	`download_3d_model_content` 返回的 `content_b64`（仅 ≤20MB 时返回）
Agent 不会自动轮询	使用 `polling-strategy` 提示词模板，或明示「每隔 10 秒查询一次直到 success」
想用图生 3D	`generate_3d_model` 传 `reference_image_url`，`prompt` 作为风格提示
多 key / 熔断 / 冷却	见 deployment.zh.md「配置参考」的 KeyRotator 章节

6. 上线前检查清单

storage.artifacts_dir 指向 bridge 与本地工具都能读的路径（同机默认 ./artifacts 即可）。
Bridge 与 Blender/Maya 在同一台机器（或 artifacts 目录为共享盘），保证 local_path 可直接导入。
生产环境开启 auth.enable_api_key，Agent 通过 header 携带密钥。
客户端同时注册两个服务：bridge（HTTP）+ 本地 MCP（command）。

FilesExpand file tree

workflow.zh.md

Latest commit

History