hz-unity-fbx-import

使用完整 URL 导入 Unity FBX

导入外部 3D 模型最常见的失败原因是源路径不完整。本技能可确保每个 FBX 源都是完整的、完全限定的 URL 或绝对文件系统路径，并通过 unity-cli 完成导入。

何时使用本技能

在以下情况中自动使用本技能：

• 从外部来源导入 FBX 文件
• 向 Unity 项目添加 3D 模型
• 从 URL 或文件路径加载资源
• 用户提到：“导入模型”“添加 FBX”“加载 3D 资源”“引入模型”

核心原则

FBX 文件始终使用完整、完全限定的 URL 或绝对路径。

切勿使用相对路径、不完整的 URL，或假定路径会自动补全。

unity command import_asset 接受绝对文件系统路径，不会下载文件。 已验证：传入 URL 会失败，并提示 "Source file 'https://…' does not exist." 因此，远程模型始终需要分两步处理：先下载到磁盘，再导入本地文件。

操作说明

步骤 1：确定 FBX 源

用户请求导入模型时，确定其来源：

1. 远程 URL（HTTP/HTTPS）：

   • 必须以 http:// 或 https:// 开头
   • 必须包含完整的域名和路径
   • 文件名必须以 .fbx 或 .zip 结尾
   • 重要：扩展名后面的所有查询参数和令牌都必须包含在内
   • 查询参数（例如 ?param=value&other=data）是身份验证所必需的
   • 示例：https://example.com/models/character.fbx?token=abc123&auth=xyz
   • 示例：https://cdn.fbcdn.net/path/file.fbx?_nc_gid=xxx&_nc_oc=yyy&oh=zzz

2. 本地文件（文件系统）：

   • 必须是绝对路径（不能是相对路径）
   • Windows：C:/Users/name/Downloads/model.fbx
   • Unix/Mac：/home/user/models/model.fbx
   • 必须以 .fbx 或 .zip 结尾

3. ZIP 压缩包：

   • 可以是 URL 或本地路径
   • 必须包含 FBX 文件，导入前需先解压
   • 示例：https://example.com/assets.zip

步骤 2：验证源格式

关键：对于包含查询参数（例如 ?token=...&auth=...）的 URL，必须包含完整 URL 及其所有参数。查询参数通常包含下载所需的身份验证令牌。

有效示例：

• https://cdn.example.com/assets/models/chair.fbx
• https://cdn.example.com/models/chair.fbx?token=abc123&auth=xyz789（含查询参数）
• https://scontent.fbcdn.net/model.fbx?_nc_gid=xxx&_nc_oc=yyy&oh=zzz（带身份验证的 Meta CDN）
• http://localhost:8000/models/character.fbx
• C:/Projects/Models/tree.fbx（Windows 绝对路径）
• /home/user/assets/car.fbx（Unix 绝对路径）
• https://github.com/user/repo/releases/download/v1.0/model.zip

无效示例（切勿使用）：

• models/chair.fbx（相对路径）
• ~/Downloads/robot.fbx（不支持波浪号展开）
• example.com/model.fbx（缺少协议）
• ../assets/model.fbx（相对路径）
• model.fbx（完全没有路径）

步骤 3：将远程源下载到磁盘

本地文件可跳过此步骤。请将 URL 括在引号中，避免 shell 在查询参数中的 & 处分割 URL——这是下载内容被截断并失败的最常见原因。

# macOS / Linux
curl -fSL "https://example.com/models/office_chair.fbx" -o /tmp/office_chair.fbx

# Windows (PowerShell)
Invoke-WebRequest -Uri "https://example.com/models/office_chair.fbx" -OutFile "$env:TEMP\office_chair.fbx"

导入前请确认文件存在且非空。被截断的文件或保存为 .fbx 的 HTML 错误页面会作为损坏的资源导入，而不会明确报错。

如果是 .zip 文件，请先解压并找到其中的 .fbx 文件，然后导入该文件。

步骤 4：导入文件

unity status --format json          # look for state "ready"

# Validate first — reports what would be imported, writes nothing
unity command import_asset --source "C:/Users/name/Downloads/office_chair.fbx" \
  --path "Assets/Models/office_chair.fbx" --dry_run true --format json

# Then import for real
unity command import_asset --source "C:/Users/name/Downloads/office_chair.fbx" \
  --path "Assets/Models/office_chair.fbx" --format json

• --source 是外部文件的绝对文件系统路径。
• --path 是相对于创作根目录的目标路径（通常为 Assets/），且需包含扩展名。Assets/ 前缀可省略。
• 仅在覆盖目标位置已有资源时才需要 --confirm true。
• --dry_run true 会进行验证并报告结果，但不会写入文件；只要源文件来自用户，就应使用此选项。

连接、--project-path 和安全模式恢复说明见 unity-cli 技能。

步骤 5：设置缩放比例和骨架类型

import_asset 会按文件创建时的比例复制并导入文件。与一次性“按高度 H 导入”的工具不同，规范化尺寸是一个单独的步骤：

unity command set_import_settings --asset "Assets/Models/office_chair.fbx" \
  --settings '{"globalScale": 0.46, "useFileScale": false}' --format json

将 globalScale 计算为 targetHeight / currentHeight。对于人形骨架，还要将 animationType 设置为 Humanoid。请参阅 hz-unity-meta-movement-sdk-retargeting，了解骨架尺寸过大会导致偏斜的原因，以及涉及的 ModelImporter 字段。

步骤 6：实例化，然后获取实际边界

unity command instantiate_prefab --prefab "Assets/Models/office_chair.fbx" --name office_chair --format json
unity command save_scene --format json

然后读取实际边界——切勿假设模型的尺寸。bounds 是一个计算属性，因此 get_component_properties 无法读取它（读取 MeshRenderer 会返回 m_Materials、 m_CastShadows 等属性，但不包含 bounds）。导入的 FBX 还会将其渲染器放在实例化根对象的子对象上，因此请使用 unity-placement 技能中的 GetBounds.cs，该脚本会合并子对象渲染器的边界：

unity command run_script --file AgentScripts/GetBounds.cs --entry GetBounds.Run \
  --args '[["office_chair"]]' --format json

向用户报告尺寸和中心点，并在后续定位时使用这些数据。

步骤 7：向用户报告

• 确认导入成功
• 显示资源路径和实例化的 GameObject 名称
• 显示测量所得的尺寸和中心点
• 建议后续步骤（放置、缩放、材质分配）

处理用户提供的路径

如果用户提供的是不完整路径

用户给出的路径不完整时，请索要完整路径：

用户：“导入 models/car.fbx”

请求澄清： “我需要 FBX 文件的完整路径。它是：

• 远程 URL？（例如 https://example.com/models/car.fbx）
• 本地文件？请提供绝对路径（例如 C:/Projects/models/car.fbx）

car.fbx 的完整路径是什么？”

如果用户提供的 URL 未包含协议

用户：“从 example.com/models/chair.fbx 导入”

澄清协议： “应该使用：

• https://example.com/models/chair.fbx（HTTPS）
• http://example.com/models/chair.fbx（HTTP）

应该使用哪种协议？”

如果用户提供的是相对路径

用户：“导入 ../models/tree.fbx”

请求绝对路径： “不支持相对路径。请提供 tree.fbx 的绝对路径。

例如：

• Windows：C:/Projects/models/tree.fbx
• Mac/Linux：/home/user/projects/tree.fbx

完整路径是什么？”

最佳实践

1. 下载或导入前，务必验证源格式
2. 切勿假设路径——始终使用明确提供的路径，或请求澄清
3. 优先使用绝对路径，而非任何形式的相对路径
4. 所有远程 URL 都要包含协议（http://、https://）
5. 在 shell 中为 URL 加引号，避免查询参数中的 & 被当作作业分隔符
6. 验证文件扩展名——必须是 .fbx 或 .zip
7. 对于用户提供的任何源，先使用 --dry_run true
8. 导入前确认下载的文件非空
9. 实例化后测量边界——切勿猜测模型尺寸
10. 与 unity-placement 配合——使用测量所得的边界进行定位
11. 在设备上抽查——干净导入后，部署并拉取 metavr capture screenshot，确认模型在头显中的显示效果正常，而不只是在 Editor 中检查

错误预防检查清单

导入前，请确认：

• 源是完整 URL 或绝对路径
• 如果是远程 URL，则包含协议（http:// 或 https://）
• 包含所有查询参数（URL 中 ? 之后的所有内容）
• shell 命令中的 URL 已加引号
• 如果是本地路径，则为绝对路径（以 C:/ 或 / 开头）
• 不含相对路径组件（不含 ../ 或 ./）
• 不使用波浪号展开（不含 ~/）
• 文件名以 .fbx 或 .zip 结尾（后面可以有查询参数）
• 远程源先下载到磁盘，且文件非空
• --path 目标路径包含扩展名
• 覆盖现有资源时，已提供 --confirm true
• 如果模型创建时并非真实世界尺寸，已通过 set_import_settings 规范化缩放比例

替代方案：MCP 单次导入器

搭配 Meta Unity 扩展的 Unity MCP 服务会提供 Unity_ImportExternalModel，可通过一次调用完成下载、导入、规范化高度、分配纹理和创建预制体。命令目录中没有对应项，因此只能通过 MCP 调用——其参数、启用该功能的设置，以及手动重新实现 Unity_RunCommand 的方法，请参阅 references/unity-mcp-fallback.md。

快速参考

源文件的必需格式

源类型	格式	示例	需要先下载？
远程 HTTPS	https://domain/path/file.fbx	https://cdn.example.com/models/chair.fbx	是
远程 HTTP	http://domain/path/file.fbx	http://localhost:8000/model.fbx	是
本地 Windows	C:/path/to/file.fbx	C:/Users/name/Downloads/robot.fbx	否
本地 Mac/Linux	/path/to/file.fbx	/home/user/models/tree.fbx	否
ZIP 归档	与上述相同，但使用 .zip	https://example.com/pack.zip	是，还需解压

与其他技能集成

• unity-placement：导入后使用测量出的边界进行定位。
• hz-unity-meta-movement-sdk-retargeting：为角色模型设置导入缩放和 Humanoid 骨架类型。
• unity-cli：连接到 Editor、使用 --project-path、从 Safe Mode 恢复。

请记住

导入失败几乎总是路径问题。如有疑问：

1. 请用户提供完整路径
2. 下载前验证格式
3. 为远程 URL 添加协议，并将整个 URL 用引号括起来
4. 使用 import_asset 前先将远程文件下载到磁盘——它不会获取 URL
5. 为 --source 使用绝对路径
6. 绝不猜测或自动补全不完整的路径
7. 绝不使用相对路径或波浪号展开