diff --git a/docs/api/XCEngine/Resources/Resources/Resources.md b/docs/api/XCEngine/Resources/Resources/Resources.md
index 676c0076..c2ff1138 100644
--- a/docs/api/XCEngine/Resources/Resources/Resources.md
+++ b/docs/api/XCEngine/Resources/Resources/Resources.md
@@ -6,19 +6,46 @@
 
 **头文件**: `XCEngine/Resources/Resources.h`
 
-**描述**: 资源模块 umbrella header，统一汇总资源类型、loader、import settings、资源管理器以及资源 IO 辅助入口。
+**描述**: `Resources` 模块的 umbrella header，统一汇总资源类型、loader、import settings、artifact IO 以及资源管理相关入口。
 
-## 概述
+## 概览
 
 `Resources.h` 本身不是某个单独类或系统的实现，而是 `Resources` 模块的聚合入口。它把常用的资源相关 public API 一次性包含进来，主要包括：
 
-- Core/Asset 层的 `IResource`、`ResourceHandle`、`ResourceManager`、`ResourceCache`、`AsyncLoader`
-- 各类资源对象与 loader，例如 `Texture`、`Mesh`、`Material`、`Shader`、`AudioClip`
-- 资源导入设置与若干资源 IO 辅助类型
+- Core/Asset 层的基础类型
+  - `IResource`
+  - `ResourceHandle`
+  - `ResourceManager`
+  - `ResourceCache`
+  - `AsyncLoader`
+- 常见资源对象与 loader
+  - `Texture` / `TextureLoader` / `TextureImportSettings`
+  - `Mesh` / `MeshLoader` / `MeshImportSettings`
+  - `Material` / `MaterialLoader`
+  - `Shader` / `ShaderLoader`
+  - `AudioClip` / `AudioClipLoader`
+  - `VolumeField` / `VolumeFieldLoader`
+  - `Model` / `ModelLoader`
+  - `GaussianSplat` / `GaussianSplatLoader`
+- 资源 artifact / IO 辅助入口
+  - `ModelArtifactIO`
+  - `GaussianSplatArtifactIO`
+- builtin 资源路径入口
+  - `BuiltinResources`
 
-适合想一次引入整个资源子系统 public API 的调用方使用。
+适合想一次性引入整个资源子系统 public API 的调用方使用。
+
+## 当前作用边界
+
+- 这是“对外聚合入口”，不是资源系统内部依赖的最小 include 集。
+- 它优先覆盖调用方最常见的 public API，不保证把 `Resources` 模块下所有内部辅助头文件都一并导出。
+- 随着 `Model` 和 `GaussianSplat` 进入正式资源链路，这个 umbrella header 也已经把对应类型、artifact IO 和 loader 纳入默认暴露范围。
 
 ## 相关文档
 
-- [当前目录](../Resources.md) - 返回 `Resources` 平行目录
-- [API 总索引](../../../main.md) - 返回顶层索引
+- [当前目录](../Resources.md) - 返回 `Resources` 并行目录
+- [Model](../Model/Model.md)
+- [GaussianSplat](../GaussianSplat/GaussianSplat.md)
+- [Volume](../Volume/Volume.md)
+- [BuiltinResources](../BuiltinResources/BuiltinResources.md)
+- [API 总索引](../../../main.md)
diff --git a/docs/api/XCEngine/UI/Widgets/UISelectionModel/UISelectionModel.md b/docs/api/XCEngine/UI/Widgets/UISelectionModel/UISelectionModel.md
index 511ee3ad..a1541d36 100644
--- a/docs/api/XCEngine/UI/Widgets/UISelectionModel/UISelectionModel.md
+++ b/docs/api/XCEngine/UI/Widgets/UISelectionModel/UISelectionModel.md
@@ -8,32 +8,60 @@
 
 **源文件**: `engine/src/UI/Widgets/UISelectionModel.cpp`
 
-**描述**: 单选字符串 id 模型，适合列表、树和属性面板中“当前选中项”这类最基础的选择状态。
+**描述**: 以字符串 ID 为键的轻量选择模型，支持多选集合和一个“主选中项”，适合列表、树和属性面板这类 UI 控件复用。
 
 ## 概览
 
-公开接口非常直接：
+`UISelectionModel` 已经不是早期那种“只保存一个选中 ID”的极简模型。当前公开接口围绕两层状态展开：
 
-- `HasSelection()`
-- `GetSelectedId()`
-- `IsSelected(...)`
-- `SetSelection(...)`
-- `ClearSelection()`
-- `ToggleSelection(...)`
+- `m_selectedIds`
+  保存当前所有选中项，顺序稳定，且会去重
+- `m_primarySelectedId`
+  表示当前主选中项；通常用于键盘焦点、属性面板绑定或默认操作对象
+
+## 当前公开能力
+
+- 查询接口
+  - `HasSelection()`
+  - `GetSelectedId()`
+  - `GetSelectedIds()`
+  - `GetSelectionCount()`
+  - `HasMultipleSelection()`
+  - `IsSelected(...)`
+- 覆盖 / 主选中管理
+  - `SetSelection(...)`
+  - `SetSelections(...)`
+  - `SetPrimarySelection(...)`
+- 增删切换
+  - `AddSelection(...)`
+  - `RemoveSelection(...)`
+  - `ClearSelection()`
+  - `ToggleSelection(...)`
+  - `ToggleSelectionMembership(...)`
 
 ## 当前实现行为
 
-- 内部状态当前只有一个 `std::string m_selectedId`。
-- `HasSelection()` 只检查字符串是否为空，因此空字符串等价于“无选择”。
-- `SetSelection(...)` 在传入和当前相同的 id 时返回 `false`；否则直接覆盖当前选中项。
-- `ToggleSelection(...)` 在命中当前选中 id 时会清空选择，否则把它设为新的选中项。
-- 当前模型是严格单选，不提供多选集合或 anchor/range 语义。
+- `SetSelection(...)` 会把整个选择集合替换成单个 ID；传空字符串时等价于清空选择。
+- `SetSelections(...)` 会先移除空 ID、再去重；如果未指定 `primarySelectionId`，默认把最后一个有效 ID 设为主选中项。
+- `SetPrimarySelection(...)` 只允许把“已经在选择集合里的项”设为主选中项。
+- `AddSelection(...)` 会把新项追加到集合尾部；当 `makePrimary == true` 或当前没有主选中项时，也会同步更新 `m_primarySelectedId`。
+- `RemoveSelection(...)` 删除主选中项时，会把最后一个剩余项提升为新的主选中项；删空后主选中项也会一起清空。
+- `ToggleSelection(...)` 的语义是“命中则移除，未命中则切成单选”。
+- `ToggleSelectionMembership(...)` 的语义是“命中则移除，未命中则保留原集合并追加进去”，更适合 Ctrl / Cmd 一类多选交互。
+
+## 当前实现边界
+
+- 这是纯逻辑模型，不负责通知、事件派发或视图刷新。
+- 选择 ID 只是普通字符串，没有内建树层级、range anchor 或排序语义。
+- 去重和主选中规则都在模型内部固定实现；如果控件需要更复杂的策略，仍要在更上层包装。
 
 ## 测试与调用链
 
-- `tests/UI/Core/unit/test_ui_selection_model.cpp` 当前覆盖 set/clear/toggle 的基础行为。
+- `tests/UI/Core/unit/test_ui_selection_model.cpp` 当前覆盖了单选、多选、主选中切换和 toggle 行为。
+- 属性编辑、键盘导航或拖拽等 UI 层逻辑可以在此之上复用统一的选择状态约定。
 
 ## 相关文档
 
 - [Widgets](../Widgets.md)
 - [UIKeyboardNavigationModel](../UIKeyboardNavigationModel/UIKeyboardNavigationModel.md)
+- [UIDragDropInteraction](../UIDragDropInteraction/UIDragDropInteraction.md)