素材生成工具 · 实现方案

⚠️ 本文档已过时（2026-09-17 起）。 这是工具动手之前的选型方案，其中 「Hyper3D 三通道 / MCP 分工」的结论未采用：实际落地的是 asset-forge 一体工具（前端 Vue3 + 后端 FastAPI），3D 走「AI 写脚本 + Blender 执行」与 「腾讯混元生3D」双引擎。 - 现状与用法 → 提示词体系与3D双引擎.md - 部署与运维 → 一体部署与运维.md 本文档保留的原因：第〇章对三条通道的实测对比（扣费时点、参数集差异）仍是 有效的选型依据，将来若重新评估外部 3D 服务，这份对比可以直接复用。

目标项目：PC 端 · 窗口化 · Q 版低模（COC 风格）· Sect Management + 挂机 + SLG 工具性质：离线素材生产管线（非作品运行时组件） 制定日期：2026-09-16 · 版本 v2 · 状态：形态已定，方案待评审，不投入实现

v2 修订说明：v1 建议 3D 阶段在「Hyper3D 网页版（人工、免费抽卡）」与「腾讯云/纯 API（自动、付费）」间二选一。实测本机 Hyper3D MCP 已可用后重新比对，发现 MCP 是一条独立且更优的通道，遂将形态收敛为按资产类型分工的三通道。核心结论见第〇章与第 3.4 节。

---

〇、形态决策：三条通道，按资产类型分工

0.1 三条通道的实测能力差异

本机 Hyper3D MCP 已加载（7 个工具：rodin_create_uploads / rodin_import_images / rodin_generate / rodin_generate_bang / rodin_wait / rodin_get_status / rodin_get_result）。三者横向对比：

0.2 决定性事实：MCP 优于纯 REST API

MCP 与纯 REST API 都是「生成即扣费」，但 MCP 返回 display_url（结果页），而纯 API 的 /api/v2/status 只返回 uuid / status / queue_length 三个字段，看不到任何图。

→ 纯 REST API 在本项目中被淘汰。 同样付费，MCP 至少能看到结果。

0.3 MCP 的硬伤：参数集极小

MCP 的 rodin_generate 参数仅 6 个，且 schema 为 additionalProperties: false：

没有 TAPose。 这意味着走 MCP 生成的角色拿不到规范的 T-Pose / A-Pose，绑骨时需美术手动调整姿态——对角色是实质性损失。

也没有 material，无法选择 PBR / Shaded，只能吃默认。

0.4 因此，通道按资产类型分工

一句话：角色和风格探索走网页（免费 + 有 TAPose），建筑道具量产走 MCP（自动）。

---

一、工具定位与边界

是什么：把「一句中文描述」变成「Unity 可直接用的 FBX」的离线批处理管线。

1.1 人工只做四件事（工具职责的精确边界）

除这四件事外全部自动：提示词拼接、2D 生成与抽卡、三视图裁切、上传、生成、轮询、下载、Blender 规整、FBX 导出、成本记账。

注意第 3 条：走 MCP 时连"丢文件"都不需要——工具能自己拿结果落盘。人工动作可降到 3 件。

1.2 明确不做

• 不写入、不修改 Unity 工程目录（只产出到 export/）
• 不做骨骼绑定与动画（AI 出网格，绑骨仍由美术在 Blender 完成）
• 不做复合体建模：让 AI 直接生成"一座完整大殿（含飞檐、台阶、匾额、灯笼）"会得到不可控的一坨。AI 只出单体零件，拼装交给人——零件还可跨建筑复用。

---

二、流水线总览

flowchart TD
    S0["阶段 0 · 风格基准<br/>3 张锚图 + 色板 + 模板（人工一次性）"]
    S1["阶段 1 · 2D 抽卡<br/>豆包 API，全自动，0.2 元/张"]
    G1{"G1 · 选图 人工"}
    S2["阶段 2 · 三视图<br/>正/侧/背正交图"]
    CH{"按资产类型分通道"}
    WA["通道1 网页<br/>免费抽卡 + TAPose"]
    MB["通道2 MCP<br/>自动生成 + display_url"]
    G2{"G2 · 定稿 人工"}
    S4["阶段 4 · 规整导入<br/>blender_unity_prep.py → FBX"]

    S0 --> S1 --> G1 --> S2 --> CH
    CH -->|"角色 / 探索期"| WA --> G2
    CH -->|"建筑 / 道具"| MB --> G2
    G2 --> S4

---

三、各阶段技术规格

3.0 阶段 0：风格基准（一次性，最关键）

三个产出物，必须在人工手里做扎实：

（1）风格锚图 ×3 —— 挑 3 张最能代表目标观感的图，作为后续一切 image-to-image 的参考。

（2）色板 palette.json

{
  "name": "menpai_v1",
  "colors": {
    "roof_tile":    "#8C3A2B",
    "roof_ridge":   "#C9A227",
    "wall_plaster": "#E8DCC0",
    "wood_beam":    "#6B4A2F",
    "stone_grey":   "#5A6B72",
    "jade_green":   "#4E7A5E"
  }
}

（3）风格前缀模板，写入 prompts/style_prefix.txt。模板即资产一致性的真正来源，必须纳入版本管理。

3.1 阶段 1：五层提示词模板系统

核心设计：五层拼接。前四层全局固定，只有 L2 随资产变化。

[L1 风格前缀]  ← 全局固定
[L2 主体描述]  ← 用户输入，唯一变量
[L3 视角姿态]  ← 按用途切换（设定图 / 三视图）
[L4 技术约束]  ← 全局固定
[L5 负向约束]  ← 全局固定（4.0 无 negative_prompt 参数，只能用自然语言写）

L1 风格前缀（示例，按阶段 0 产出定稿）

极简Q版低模作品美术风格，等距视角，硬边平面着色 flat shading，
无平滑法线，几何体块化，轮廓清晰；参考《部落冲突》的建筑与角色造型语言；
主色板严格限定为：朱红#8C3A2B、赭金#C9A227、米白#E8DCC0、深木#6B4A2F、青灰#5A6B72；
光照为柔和顶部主光加环境光，明暗对比中等；画面干净、无噪点。

L3-a 设定图视角（阶段 1 用）

主体居中完整展示，正视微俯约15度三分之四视角，正交投影无透视变形，
主体占画面高度75%，四周留白。

L3-b 三视图（阶段 2 用）

生成该对象的正交三视图，分别为正视图、侧视图、背视图，
三个视图等大并排，纯白背景，无阴影，无投影，同一比例与朝向基准。

三视图必须正交投影。 若带透视，Hyper3D 会把透视变形当成真实形状学进去。

L4 技术约束

纯白色背景#FFFFFF，无地面，无投影，无场景元素，无文字水印，
模型边缘清晰锐利，便于抠图。

L5 负向约束（自然语言）

不要真实感渲染，不要写实材质，不要高清照片风格，不要景深虚化，
不要复杂背景，不要多余装饰物，不要人形比例失调。

3.2 阶段 1/2：豆包 API 调用规格

• 端点：POST https://ark.cn-beijing.volces.com/api/v3/images/generations
• 认证：Authorization: Bearer $ARK_API_KEY
• 模型：doubao-seedream-4-0-250828

计费：0.20 元/张，输入图免费，生成失败（含Review未过）不计费。限流 500 张/分钟。

抽卡策略——用迭代代替盲抽

关键点：R2、R3 把上一轮胜出图作为 image 传入。 这是把"抽卡"收敛成"迭代"的手法，也是弥补豆包 4.0 大概率无 seed 的主要手段。

为什么不能靠固定提示词或 seed 保证一致性？ 1 固定提示词只能保证风格倾向，无法保证同一角色的造型。 2 官方 4.0 示例参数表无 seed；第三方镜像文档明确标注 seed 仅 doubao-seedream-3.0-t2i / seededit-3.0-i2i 支持；另有第三方网关列出 4.0 含 seed → 口径冲突，列为上线前必测项。

3.3 阶段 2：2D → 3D 的交接规格

（1）三视图生成：用 L3-b 模板 + 定稿图作 image 参考，生成含正/侧/背的画面。

（2）裁切：切成 3 张单图。

（3）上传前合规检查（不过会 400 或上传失败）：

• 豆包侧：jpeg / png，≤10MB，总像素 ≤6000×6000，宽高比 ∈ [1/3, 3]
• MCP rodin_create_uploads 支持格式更宽：jpeg/png/webp/tiff/gif/avif/heic/heif/bmp/jp2/jpx/jpm/mj2
• 三视图需裁成正方形或接近正方形

（4）视角标注——仅通道3（纯 REST API）可用

纯 API 的 image_label 支持 F/FL/FR/B/BL/BR/L/R/U/D/?，位置与 images 数组一一对应：

images      = [front.png, left.png, back.png]
image_label = ["F",       "L",        "B"]

⚠️ MCP 无此参数——但 rodin_generate 的说明明写 "Preserve the intended image order"，上传顺序即语义。故走 MCP 时按 [正, 侧, 背] 固定顺序传 reference_upload_ids 即可，虽然表达力弱于显式 label，但非无解。

3.4 阶段 3：Hyper3D 三通道操作规格

通道1 网页工作区（角色 + 探索期）

• 入口：https://hyper3d.ai
• 人工动作：粘贴 L2 提示词 / 上传三视图 → 选 tier → 生成 → 挑 → 下载
• 免费（下载才扣 credit），支持 TAPose / material / seed
• 支持 rodin_generate_bang（BANG 拆件）对应的网页功能
• 下载后 GLB 丢进 inbox/

网页版是唯一能免费抽卡的通道，但也是唯一无法自动化的通道。用于风格探索期性价比最高。

通道2 MCP（建筑 / 道具量产）

完整链路（5 步，仅第 3 步扣费）：

参数配方（MCP 可用参数内）

三个必须注意的坑

1. tier 只有两档：Gen-2.5-Medium / Gen-2.5-Extreme-Low。缺 Low/High/Extreme-High。面数靠 quality_override 调（Quad 上限 50,000）。
2. rodin_generate 超时不要自动重试——工具说明明确写着 "If this call times out, do not retry it automatically"，因为重试会再扣一次 credit。超时应转而引导去 Hyper3D Mine 查看。
3. files[].url 是临时签名链接，且工具说明要求 "Only use files[].url to download a file when the user explicitly asks" → 下载动作需经用户确认，正好与"G2 定稿"闸门对齐。

通道3 纯 REST API（已淘汰）

保留规格备查，本项目不采用。理由见 0.2：同样付费，但 status 看不到结果。

• 提交 POST https://api.hyper3d.com/api/v2/rodin（返 uuid + jobs.subscription_key + consumed）
• 查状态 POST /api/v2/status（传 subscription_key；状态 Waiting/Generating/Done/Failed；起点 5s 退避至 30s）
• 下载 POST /api/v2/download（传 task_uuid = 顶层 uuid）
• tier 必填，漏填静默降级到 Regular（Gen-1/1.5 模型）
• mesh_mode Gen-2.5 默认 Raw，要四边形须显式 Quad
• material 四值官方定义（已查证 fal.ai / pixazo 文档）：PBR 完整 PBR 贴图 / Shaded baked lighting with no PBR maps（带烘焙光照、无 PBR 解析）/ All 两者都出 / None geometry only with no textures（仅几何、完全无贴图）
• texture_delight 官方定义：removes baked-in lighting from textures → 与 material=Shaded（定义即带烘焙光照）不是互斥，而是后者修正前者：两者组合 = 得到一张纯 albedo 的简单贴图（无 PBR maps、无烘焙光），正是量化到色板所需的干净输入
• 计费：基础 0.5 credit；Gen-2.5-Extreme-High +0.5；texture_mode=extreme-high +2.0

3.5 阶段 4：规整与导入

python blender_unity_prep.py --batch ./inbox --outdir ./export/unity_fbx \
       --preset clash-style --auto-role --flat \
       --palette config/palette.json --bake-vertex-color --strip-textures

工具需实现 inbox/ 目录监视：无论是人工从网页下载的 GLB，还是 MCP 自动落盘的结果，统一进 inbox/ 后触发规整。

验证闸门：先只跑 3~5 个，Unity 里确认尺寸/面数/顶点色/朝向正常，并用 Frame Debugger 确认能合批，再全量。

---

四、成本模型

4.1 单资产固定成本（2D 阶段）

4.2 3D 阶段成本（两条通道）

关键：MCP 的成本由订阅档位决定，直购 credit 最贵（¥5.4/次）。 若走 MCP 量产，必须配订阅，否则单次直购贵过腾讯云。

4.3 60 资产规模的三方案对比

假设每资产平均 3 次 3D 尝试：

值得注意的反直觉结论：MCP 在纯成本上并不便宜。它换的是人工时间（全自动、无需搬运文件）。 若人工时间不值钱 → 走网页 + 腾讯云最省；若要压缩人工 → MCP + Creator 是合理溢价。

4.4 推荐分期策略

---

五、工程架构

5.1 目录结构

asset_forge/
├── config/
│   ├── palette.json            # 色板
│   ├── recipes.json            # 各通道参数配方
│   └── budgets.json            # 成本闸门阈值
├── prompts/
│   ├── style_prefix.txt        # L1
│   ├── view_setting.txt        # L3-a
│   ├── view_orthographic.txt   # L3-b
│   ├── technical.txt           # L4
│   └── negative.txt            # L5
├── data/
│   ├── ledger.db               # SQLite 台账
│   └── cache/                  # 按 hash 缓存，防重复扣费
├── input/
│   └── assets.csv              # 名称 / 类型 / 描述 / 通道
├── work/
│   ├── 01_concept/             # 设定图候选
│   ├── 02_final/               # 定稿 + 三视图
│   ├── 03_upload/              # 裁切合规后的上传件
│   └── 04_raw_glb/             # 3D 原始产出
├── inbox/                      # ← 人工丢 GLB 或 MCP 自动落盘，监视触发
├── export/
│   └── unity_fbx/              # 最终交付
├── handoff/                    # ← 网页通道的交付包（提示词 txt + 图片）
└── forge.py                    # CLI 入口

5.2 模块职责

5.3 状态机与幂等（省钱的关键）

DRAFT → CONCEPT_GENERATING → G1_PENDING → CONCEPT_APPROVED
      → VIEWS_READY → ROUTED(通道1/2)
      → HANDOFF_PACKED | MODEL_SUBMITTED
      → MODEL_READY → G2_PENDING → DOWNLOADED → PREPPED → DONE

幂等四原则

1. 提交前先查台账：同 (prompt_hash, recipe_hash) 已提交过则复用，不重复扣费
2. rodin_generate 超时绝不自动重试（重试 = 再扣 0.5 credit），转人工确认
3. 下载 URL 立即落盘（会过期），不二次获取
4. 断点续跑：任何阶段中断，从台账 status 恢复

5.4 CLI 设计

forge.py concept  --asset "山门" --desc "中式门派山门……" --role building --n 4
forge.py approve  --asset "山门" --pick 2          # G1
forge.py views    --asset "山门"
forge.py route    --asset "山门"                    # 按角色/类型自动分通道
forge.py handoff  --asset "掌门"                    # 通道1：产出交付包
forge.py model    --asset "山门" --channel mcp      # 通道2
forge.py ingest   --watch inbox                    # 人工下载件入口
forge.py prep     --all --preset clash-style
forge.py ledger   --report cost

---

六、上线前必测清单（7 个探针）

其中探针 3 最关键：它验证整个"免费抽卡"前提是否成立。

---

七、与既有资产的衔接

统一收口：无论来自 AI、Poly Pizza 还是腾讯云，都必须过 clash-style 预设 + 色板归并——这是风格一致性的最后一道闸。

---

八、执行顺序

前 6 步只用 2 个资产，验证两条通道都通了再上批量。

---

附：核心参数速查

豆包 Seedream 4.0 POST https://ark.cn-beijing.volces.com/api/v3/images/generations · doubao-seedream-4-0-250828 · ¥0.20/张 · 输入图免费 · 失败不计费 · 参考图 ≤10 张 · sequential_image_generation + max_images · seed 支持情况待验

Hyper3D MCP（通道2，本机已加载） rodin_create_uploads（presigned PUT，1 小时）→ PUT → rodin_generate（扣 credit）→ rodin_wait（≤45s，超时不重试）→ rodin_get_result 参数仅 6 个：prompt / reference_upload_ids(≤5，顺序有意义) / mesh_mode(默认 Raw) / tier(仅 Medium、Extreme-Low) / quality_override(Quad 1,000~50,000) / geometry_file_format · 无 TAPose / material / seed / image_label

Hyper3D 网页版（通道1） https://hyper3d.ai · 下载时扣费 · 支持 TAPose / material / seed · 五档 tier · 唯一免费抽卡通道

Hyper3D 纯 REST API（通道3，已淘汰） 提交 /api/v2/rodin · 状态 /api/v2/status（传 subscription_key，无预览图）· 下载 /api/v2/download（传 task_uuid = 顶层 uuid）· tier 必填（漏填静默降级 Gen-1/1.5）· 基础 0.5 credit

---

核心判断：形态收敛为「2D 全自动抽卡 + 3D 按资产类型分通道」——角色与风格探索走网页（免费 + 有 TAPose），建筑道具量产走 MCP（全自动）。MCP 并不比网页便宜，它买的是人工时间；纯 REST API 因看不到结果而被淘汰。