# 内容浏览器接口

> **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 检测
- 材质自发光检测使用简化方法，可能不完全准确

---