test-ue-project/Plugins/UnrealAgentLink/Resources/Docs/内容管理文档.md

内容浏览器接口

UEContentBrowserAgent - 管理 UE 编辑器内的文件与文件夹结构

遵循 奥卡姆剃刀 原则，仅保留 CRUD（增删改查） 对应的 4 个原子工具。

工具矩阵

动词	工具名称	核心职责	说明
查 (Read)	content.search	搜索资产路径、类名	获取操作目标的唯一途径
增 (Create)	content.import	导入外部文件 (FBX/PNG/WAV)	外部资源进入 UE 的唯一入口
改 (Update)	content.move	移动 / 重命名	合并了 Move 和 Rename，移动到原目录+新名字=重命名
删 (Delete)	content.delete	删除资产 / 文件夹	必要的清理能力

---

搜索资产 content.search

在 Content Browser 中查找匹配的资产路径。支持模糊匹配和类型过滤。

请求（JSON-RPC）

{"ver":"1.0","type":"req","id":"cb1","method":"content.search","params":{
  "query":"Red",                      // 必填，模糊匹配关键词
  "filter_class":"Material",          // 可选，类型过滤（如 Material, Texture2D, StaticMesh, Blueprint）
  "limit":10                          // 可选，返回数量限制（默认 50，最大 200）
}}

响应

{"ver":"1.0","type":"res","id":"cb1","code":200,"result":{
  "ok":true,
  "count":3,
  "results":[
    {"name":"M_Red","path":"/Game/Materials/M_Red","class":"Material"},
    {"name":"M_RedBrick","path":"/Game/Materials/M_RedBrick","class":"MaterialInstanceConstant"},
    {"name":"T_RedTexture","path":"/Game/Textures/T_RedTexture","class":"Texture2D"}
  ]
}}

说明

• query 会同时匹配资产名称和路径，大小写不敏感。
• filter_class 支持常见类名：Material、Texture2D、StaticMesh、SkeletalMesh、Blueprint、SoundWave 等。
• 搜索范围固定为 /Game/ 目录下所有资产。
• 返回结果按匹配顺序排列，达到 limit 后截止。

---

导入外部文件 content.import

将磁盘上的文件导入到 UE 项目中。UE 会自动识别文件类型并调用对应的导入器。

请求（JSON-RPC）

{"ver":"1.0","type":"req","id":"cb2","method":"content.import","params":{
  "files":[                           // 必填，外部文件绝对路径列表
    "C:/Downloads/Texture_01.png",
    "C:/Downloads/Hero.fbx"
  ],
  "destination_path":"/Game/Imported/Textures",  // 可选，目标目录（默认 /Game/Imported）
  "overwrite":true                    // 可选，是否覆盖同名文件（默认 false）
}}

响应

{"ver":"1.0","type":"res","id":"cb2","code":200,"result":{
  "ok":true,
  "imported_count":2,
  "requested_count":2,
  "imported":[
    {"name":"Texture_01","path":"/Game/Imported/Textures/Texture_01.Texture_01","class":"Texture2D"},
    {"name":"Hero","path":"/Game/Imported/Textures/Hero.Hero","class":"SkeletalMesh"}
  ]
}}

说明

• files 中的路径必须是绝对路径，支持 Windows 和 Unix 风格。
• 不存在的文件会被跳过，并在日志中输出警告。
• destination_path 不存在时会自动创建。
• 支持的文件格式取决于 UE 内置导入器：
  • 贴图：PNG, JPG, TGA, PSD, BMP, EXR
  • 模型：FBX, OBJ, glTF (UE 5.0+)
  • 音频：WAV, MP3, OGG, FLAC
  • 其他：HDRI, Alembic 等

---

移动/重命名资产 content.move

移动资产到新目录，或通过修改目标路径名称实现重命名。两种操作合二为一。

请求（JSON-RPC）

{"ver":"1.0","type":"req","id":"cb3","method":"content.move","params":{
  "source_path":"/Game/OldFolder/MyAsset",      // 必填，资产当前路径
  "destination_path":"/Game/NewFolder/MyAsset_Renamed"  // 必填，目标路径（包含新名字）
}}

响应

{"ver":"1.0","type":"res","id":"cb3","code":200,"result":{
  "ok":true,
  "source_path":"/Game/OldFolder/MyAsset",
  "destination_path":"/Game/NewFolder/MyAsset_Renamed",
  "message":"Asset moved/renamed successfully"
}}

逻辑说明

source	destination	效果
/Game/A	/Game/Folder/A	移动到新目录
/Game/A	/Game/B	重命名（同目录）
/Game/A	/Game/Folder/B	移动并重命名

说明

• 内部使用 IAssetTools::RenameAssets，会自动处理引用更新（Redirectors）。
• 若源资产不存在返回 code: 404。
• 若目标路径已存在同名资产，操作可能失败。
• 移动后建议执行 FixupRedirectors 清理重定向器（可通过编辑器手动操作）。

---

删除资产 content.delete

彻底删除指定的资产。支持批量删除。

请求（JSON-RPC）

{"ver":"1.0","type":"req","id":"cb4","method":"content.delete","params":{
  "paths":[                           // 必填，要删除的资产路径列表
    "/Game/Temp/TestActor",
    "/Game/OldFolder/UnusedMaterial"
  ]
}}

响应

{"ver":"1.0","type":"res","id":"cb4","code":200,"result":{
  "ok":true,
  "deleted_count":2,
  "requested_count":2,
  "deleted":[
    "/Game/Temp/TestActor",
    "/Game/OldFolder/UnusedMaterial"
  ],
  "failed":[]
}}

部分失败响应

{"ver":"1.0","type":"res","id":"cb4","code":200,"result":{
  "ok":true,
  "deleted_count":1,
  "requested_count":2,
  "deleted":["/Game/Temp/TestActor"],
  "failed":["/Game/Referenced/InUseMaterial"]
}}

说明

• 删除操作不可逆，请确认后再执行。
• 被其他资产引用的资产可能无法删除（UE 会阻止以保护引用完整性）。
• 路径不存在的资产会被记入 failed 列表。
• 暂不支持删除文件夹（仅支持资产路径）。

---

错误码

Code	含义	说明
200	成功	操作全部完成
400	参数错误	缺少必填参数或参数格式错误
404	未找到	资产或路径不存在
500	内部错误	UE 操作失败

---

与 AssetManagerAgent 的区别

UEContentBrowserAgent	AssetManagerAgent
管理 Project Content（项目内容）	管理 Asset Library（资产库）
操作硬盘上的 .uasset 文件	操作云端资产、标签、备注
路径以 /Game/ 开头	使用资产库 ID
功能：搜索、导入、移动、删除	功能：下载、标签、备注、收藏

路由规则：

• 用户提到 "导入贴图"、"移动资产"、"删除蓝图" → ue_content_browser
• 用户提到 "资产库"、"打标签"、"写备注" → asset_manager

---

使用示例

场景1：导入并整理资产

用户：把 C:/Downloads 下的 hero.fbx 导入到 /Game/Characters/Hero 目录

步骤：
1. content.import { files: ["C:/Downloads/hero.fbx"], destination_path: "/Game/Characters/Hero" }

场景2：搜索并重命名

用户：找到所有包含 Test 的材质，把第一个重命名为 M_Final

步骤：
1. content.search { query: "Test", filter_class: "Material" }
   → 返回 [{ path: "/Game/Materials/M_TestRed" }, ...]
2. content.move { source_path: "/Game/Materials/M_TestRed", destination_path: "/Game/Materials/M_Final" }

场景3：清理临时资产

用户：删除 /Game/Temp 下的所有测试资产

步骤：
1. content.search { query: "Temp" }
   → 返回 [{ path: "/Game/Temp/TestActor" }, { path: "/Game/Temp/TestMaterial" }]
2. content.delete { paths: ["/Game/Temp/TestActor", "/Game/Temp/TestMaterial"] }

---

资产优化审计 content.audit_optimization

检测项目中 Nanite、Lumen 等功能的使用情况，提供优化建议。用于构建优化和包体大小分析。

请求（JSON-RPC）

{"ver":"1.0","type":"req","id":"audit1","method":"content.audit_optimization","params":{
  "check_type":"NaniteUsage"  // 可选，检查类型：NaniteUsage, LumenMaterials, TextureSize, All（默认 All）
}}

响应

{"ver":"1.0","type":"res","id":"audit1","code":200,"result":{
  "nanite_usage":{
    "enabled_in_config":true,
    "mesh_count":150,
    "meshes_with_nanite":0,
    "suggestion":"检测到您开启了 Nanite 支持，但场景中没有任何模型使用了 Nanite。建议在 Project Settings 中关闭 Nanite 以剔除相关着色器变体，可显著提升构建速度。"
  },
  "lumen_usage":{
    "enabled_in_config":true,
    "using_lumen_gi":true,
    "materials_with_emissive":5,
    "suggestion":"检测到 5 个材质使用了自发光，Lumen 功能正在被使用。"
  },
  "texture_analysis":{
    "total_textures":120,
    "large_textures_4k":15,
    "estimated_memory_bytes":2147483648,
    "estimated_memory_mb":2048,
    "suggestion":"发现 15 个 4K 或更大的纹理，考虑压缩或降低分辨率以减少包体大小。"
  }
}}

说明

检查类型说明

• NaniteUsage：检测 Nanite 的使用情况

  • 检查 r.Nanite.ProjectEnabled 配置
  • 扫描所有 StaticMesh 资产，统计启用 Nanite 的网格数量
  • 如果配置启用但未使用，提供优化建议

• LumenMaterials：检测 Lumen 的使用情况

  • 检查 r.Lumen.Enabled 和 r.DynamicGlobalIlluminationMethod 配置
  • 扫描材质资产，统计使用自发光的材质数量（Lumen 特征）
  • 提供基于实际使用情况的建议

• TextureSize：分析纹理大小

  • 统计所有纹理的数量和大小
  • 识别 4K 或更大的纹理
  • 估算总纹理内存使用

• All：执行所有检查（默认）

优化建议示例

• Nanite 未使用：建议关闭以减小包体和提升构建速度
• Lumen 已启用但材质较少使用自发光：可以考虑禁用 Lumen
• 大纹理过多：建议压缩或降低分辨率

注意事项

• 资产扫描操作可能需要较长时间，建议在项目资产加载完成后执行
• 仅在 UE 5.0+ 支持 Nanite 和 Lumen 检测
• 材质自发光检测使用简化方法，可能不完全准确

---