云资源 MCP 下载与明文导出

官方云资源适合直接在编辑器和游戏中引用，但 AI 在手写或修改 .effect、prefab 时需要看到真实的资源结构、引用路径和参数组合。资源目录 MCP 提供一条受控的样例获取流程：先从云素材目录找到资源，再下载完整资源，最后把资源导出为项目中的明文副本。这样可以用真实官方资源帮助 AI 理解格式，也可以把副本作为项目自己的修改起点。

导出的副本不会改写官方云资源缓存。资源目录 MCP 面向编辑器云资源目录中的受支持资源文件。

从目录找到资源

先用 resource_catalog_list_categories 查看分类，需要标签时传 includeLabels: true，再用 resource_catalog_search 缩小结果。云资源搜索应显式使用 source: "cloud"，并尽量提供 category、labels 或关键词；不要用显示名替代资源 path。

{
  "source": "cloud",
  "category": "特效/其他特效",
  "resourceType": "particle",
  "maxResults": 5
}

从结果中取 path，例如：

effect/effect_new/effect_mofa/eff_mofa_012/particle.effect

需要确认资源类型或预览摘要时，再调用 resource_catalog_get_detail 和 resource_get_preview_info。resource_get_preview_info 只返回结构化摘要，不会把明文文件内容直接交给 AI。

下载与导出

单个资源使用 resource_download，多个资源使用 resource_download_batch。下载结果按资源返回 downloaded、already_present 或失败状态。

{
  "path": "effect/effect_new/effect_mofa/eff_mofa_012/particle.effect"
}

导出单个资源使用 resource_export：

{
  "path": "effect/effect_new/effect_mofa/eff_mofa_012/particle.effect",
  "destinationRoot": "D:/MyGameSamples/official-effects",
  "includeDependencies": true,
  "overwrite": "skip"
}

模型的 model.prefab 和粒子的 particle.effect 默认按资源目录导出，以保留目录内的材质、贴图、模型等依赖；目录外的引用需要另外检查和准备。resource_export_batch 可以把多个资源导出到同一个目标根目录，每项结果独立返回，单次最多 128 项。

destinationRoot 必须是绝对路径，导出会保留资源的相对目录。例如上述文件会写到 D:/MyGameSamples/official-effects/effect/effect_new/effect_mofa/eff_mofa_012/particle.effect。如果希望直接生成项目资源，可将目标根目录设为项目的 res/ 绝对路径。

如果不确定资源是否已下载，可以在导出时传 downloadIfMissing: true：

{
  "paths": [
    "effect/effect_new/effect_mofa/eff_mofa_012/particle.effect",
    "effect/effect_new/effect_hero/eff_smoke_005/particle.effect"
  ],
  "destinationRoot": "D:/MyGameSamples/official-effects",
  "downloadIfMissing": true,
  "includeDependencies": true,
  "overwrite": "skip"
}

先用 dryRun: true 查看导出计划；它不会写文件，也不会下载缺失资源，即使同时传了 downloadIfMissing: true。资源未下载时，应先下载再预览计划。默认 overwrite: "skip"，已有目标会整项跳过；error 会返回目标已存在错误，replace 会替换该资源对应的目标文件或整个目标目录。

用导出结果帮助 AI 手写资源

导出结果适合当作 AI 的真实格式样例：

1. 保留导出的目录结构，先阅读 particle.effect、model.prefab 及其相邻材质和贴图文件。
2. 观察真实资源中的节点层级、材质引用、粒子发射器、贴图路径和常用参数，再在项目自己的 res/ 目录创建副本。
3. 修改项目副本，不直接修改编辑器缓存中的官方文件。
4. 将导出的引用路径替换为项目内实际存在的资源，并通过 resource_reload、资源库预览或 PIE 检查结果。

例如，AI 可以先导出一个官方 particle.effect 作为粒子发射器和材质引用的参考，再根据用户需求手写一个新的 res/effect/custom/.../particle.effect。对于 prefab，应保留 model.prefab 所在目录和依赖文件，再修改节点变换或材质引用；不要只复制一个入口文件后猜测依赖路径。

导出样例是参考和项目制作素材，不代表每个字段都适用于所有资源。修改后仍需通过资源预览、PIE 或运行时画面检查材质、贴图、粒子效果和资源引用。

支持范围与边界

• 支持编辑器云资源目录中的模型、粒子、图片、音频、动画和相关材质/配置文件；实际可导出路径以目录搜索结果和工具返回为准。
• 只接受受支持的资源目录和文件扩展名；导出路径应来自资源目录搜索结果。
• 资源导出保留官方缓存不变，目标目录由调用方指定；导出到项目 res/ 后才成为项目自己的资源副本。
• 显示名只用于搜索和展示，后续下载、预览和导出始终使用目录返回的 path。

完整的 MCP 工具参数见 SCE Editor MCP 工具速查，AI 执行规则见 云资源目录与明文导出 Skill。