ceshi

2026-02-26 23:45:31 +08:00
parent aa599ea653
commit dd642c8585
79 changed files with 6044 additions and 0 deletions
--- a/Plugins/UnrealAgentLink/Resources/Docs/内容管理文档.md
+++ b/Plugins/UnrealAgentLink/Resources/Docs/内容管理文档.md
@@ -0,0 +1,304 @@
+# 内容浏览器接口
+
+> **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）
+```json
+{"ver":"1.0","type":"req","id":"cb1","method":"content.search","params":{
+  "query":"Red",                      // 必填，模糊匹配关键词
+  "filter_class":"Material",          // 可选，类型过滤（如 Material, Texture2D, StaticMesh, Blueprint）
+  "limit":10                          // 可选，返回数量限制（默认 50，最大 200）
+}}
+```
+
+### 响应
+```json
+{"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）
+```json
+{"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）
+}}
+```
+
+### 响应
+```json
+{"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）
+```json
+{"ver":"1.0","type":"req","id":"cb3","method":"content.move","params":{
+  "source_path":"/Game/OldFolder/MyAsset",      // 必填，资产当前路径
+  "destination_path":"/Game/NewFolder/MyAsset_Renamed"  // 必填，目标路径（包含新名字）
+}}
+```
+
+### 响应
+```json
+{"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）
+```json
+{"ver":"1.0","type":"req","id":"cb4","method":"content.delete","params":{
+  "paths":[                           // 必填，要删除的资产路径列表
+    "/Game/Temp/TestActor",
+    "/Game/OldFolder/UnusedMaterial"
+  ]
+}}
+```
+
+### 响应
+```json
+{"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":[]
+}}
+```
+
+### 部分失败响应
+```json
+{"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）
+```json
+{"ver":"1.0","type":"req","id":"audit1","method":"content.audit_optimization","params":{
+  "check_type":"NaniteUsage"  // 可选，检查类型：NaniteUsage, LumenMaterials, TextureSize, All（默认 All）
+}}
+```
+
+### 响应
+```json
+{"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 检测
+- 材质自发光检测使用简化方法，可能不完全准确
+
+---