272 lines
14 KiB
Markdown
272 lines
14 KiB
Markdown
# UE5.8 MCP Toolsets 完整分析
|
||
|
||
## 总体架构
|
||
|
||
所有Toolset都位于 `Engine\Plugins\Experimental\Toolsets`，共18个插件。它们通过 `ToolsetRegistry` 插件（核心基础设施）将 AI-callable 工具暴露给 MCP 系统（如 UnrealMCP）。
|
||
|
||
### 核心概念
|
||
|
||
- **UToolsetDefinition**: 所有工具集的基类，定义了一组 AI-callable 工具的接口
|
||
- **meta=(AICallable)**: UFUNCTION 标记，被 ToolsetRegistry 识别并暴露为 MCP 工具
|
||
- **UToolsetRegistry::RegisterToolsetClass**: 运行时注册工具集
|
||
- **FToolsetJsonConverter**: 自定义 JSON 序列化/反序列化器，用于非标准类型
|
||
- **UAgentSkill**: 为 AI 提供 prompt 上下文的辅助类
|
||
- **UToolCallAsyncResult** / **UToolCallAsyncResultString**: 长时间异步操作的结果包装
|
||
|
||
### 实现模式分类
|
||
|
||
| 模式 | 使用方 |
|
||
|------|--------|
|
||
| **UToolsetDefinition + 静态 AICallable 函数** | 几乎所有已实现的工具集 |
|
||
| **EditorSubsystem 生命周期管理** | AutomationTest, LiveCoding, SlateInspector, MCPClient |
|
||
| **多工具集模块注册** | GASToolsets (3个), NiagaraToolsets (4个) |
|
||
| **ON_SCOPE_EXIT 回滚保护** | GameFeaturesToolset |
|
||
| **纯 Python 实现** | SequencerAnimMixerToolset |
|
||
| **聚合器（描述符仅含依赖）** | AllToolsets |
|
||
| **空壳/占位符** | AIModuleToolset, AnimationAssistant, Conversation, StateTree |
|
||
|
||
---
|
||
|
||
## 一、已完整实现的 Toolset
|
||
|
||
### 1. AutomationTestToolset —— 自动化测试
|
||
- **功能**: 暴露 UE5 自动化测试框架，发现、列出、过滤、运行测试，获取结果
|
||
- **模块**: `AutomationTestToolset` + `AutomationTestToolsetTests`
|
||
- **架构**: `UAutomationTestToolset` (静态工具类) + `UAutomationTestToolsetSubsystem` (EditorSubsystem 管理 IAutomationControllerManager 生命周期)
|
||
- **AI 工具 (6个)**:
|
||
- `DiscoverTests()` - 初始化 worker 发现 (异步)
|
||
- `ListTests(NameFilter, TagFilter, Limit)` - 列出测试路径 JSON
|
||
- `RunTests(TestNames)` - 运行指定测试 (异步)
|
||
- `GetTestResults()` - 获取结果 JSON (状态/耗时/错误/警告)
|
||
- `GetTestStatus()` - 轻量状态查询
|
||
- `StopTests()` - 停止当前运行
|
||
- **关键实现**: 订阅 `OnTestsRefreshed` delegate，60秒发现超时，递归收集报告树叶子节点
|
||
|
||
### 2. DataflowAgent —— Dataflow 图编辑
|
||
- **功能**: 完整的 Dataflow 图（用于破坏/模拟，如 Geometry Collection）编辑，18个 MCP 工具
|
||
- **模块**: `DataflowAgent` (Editor)
|
||
- **架构**: `UDataflowAgentToolset` + `UDataflowGraphEditingSkill` (AgentSkill)
|
||
- **AI 工具 (17个)**:
|
||
- **图**: `CreateGraph`, `GetGraphStructure`
|
||
- **节点类型**: `ListNodeTypes`, `GetNodeTypeSchema`
|
||
- **节点操作**: `AddNode`, `UpdateNode`, `GetNodeInfo`, `RepositionNode`, `RemoveNode`
|
||
- **连接**: `ConnectNodePins`, `DisconnectNodePins`
|
||
- **变量**: `ListVariables`, `AddVariable`, `RemoveVariable`, `SetVariable`
|
||
- **注释**: `AddCommentBox`, `RemoveCommentBox`
|
||
- **关键实现**: `FScopedTransaction` 撤销支持，`FJsonObjectConverter::JsonValueToUProperty` 类型转换，变量类型系统支持基础类型/结构体/对象
|
||
|
||
### 3. GameFeaturesToolset —— 游戏功能插件管理
|
||
- **功能**: 列出、检查、创建 Game Feature 插件
|
||
- **模块**: `GameFeaturesToolset` (Editor)
|
||
- **架构**: `UGameFeaturesToolset` (静态工具类)
|
||
- **AI 工具 (5个)**:
|
||
- `ListGameFeatures()` - 列出所有 GFP
|
||
- `FindGameFeatureData(PluginName)` - 加载 UGameFeatureData 资产
|
||
- `GetPluginName(Data)` - 获取插件名
|
||
- `GetActions(Data)` - 获取所有 UGameFeatureAction
|
||
- `CreateGameFeaturePlugin(PluginName, Description)` - 完整创建流程
|
||
- **关键实现**: `ON_SCOPE_EXIT` + `bCommitted` 标志的回滚模式（7步：目录→.uplugin→挂载→资产→保存），验证仅允许字母数字和下划线
|
||
|
||
### 4. GASToolsets —— Gameplay Ability System 工具集 (3合1)
|
||
- **功能**: GAS 运行时检测 + 属性集发现 + GameplayCue 完整生命周期管理
|
||
- **模块**: `GASToolsets` (Editor)，包含3个独立工具集
|
||
- **架构**: 模块注册三个 UToolsetDefinition 子类
|
||
|
||
#### 4a. UAbilitySystemInspectorToolset (4个工具)
|
||
- `GetAttributeValues(Actor)` - 获取所有属性的 Base/Current 值
|
||
- `GetActiveEffects(Actor)` - 活跃效果 (堆栈/持续时间/剩余/标签)
|
||
- `GetGrantedAbilities(Actor)` - 已授予的技能
|
||
- `GetActiveTags(Actor)` - 拥有的 GameplayTag
|
||
|
||
#### 4b. UAttributeSetToolset (2个工具)
|
||
- `FindAttributeSetClasses()` - 发现所有 AttributeSet 子类及其属性
|
||
- `ListAttributes(ClassName)` - 列出特定类的属性
|
||
|
||
#### 4c. UGameplayCueToolset (8个工具)
|
||
- `ListCues(ParentTag)` - 列出派生 Cue 标签
|
||
- `GetCueInfo(CueTag)` - 获取通知资产路径
|
||
- `ExecuteCueOnSelectedActor(...)` - 在选中 Actor 上触发 Cue
|
||
- `FindCueNotifyAssets(ParentTag)` - 查找通知资产
|
||
- `CreateCueNotifyAsset(...)` - 创建 Blueprint GCN 资产
|
||
- `AddCueTag(CueTag, Comment)` - 添加 Cue 标签到 INI
|
||
- `RemoveCueTag(CueTag)` - 移除标签
|
||
- `FindCueTagsWithoutNotifies()` - 查找缺少通知资产的标签
|
||
|
||
### 5. GameplayTagsToolset —— GameplayTag 管理
|
||
- **功能**: 完整的 GameplayTag 管理（增删改查 + 引用者搜索）
|
||
- **模块**: `GameplayTagsToolset` (Editor)
|
||
- **AI 工具 (6个)**:
|
||
- `ListTags(ParentTag)` - BFS 遍历子标签
|
||
- `GetTagInfo(TagName)` - 注释/来源/子标签
|
||
- `AddTag`, `RemoveTag`, `RenameTag` - 需用户权限确认
|
||
- `FindReferencersByTag(TagName)` - 资产引用搜索
|
||
|
||
### 6. LiveCodingToolset —— 热编译
|
||
- **功能**: 触发 Live Coding 编译，收集编译日志和错误
|
||
- **模块**: `LiveCodingToolset` (Editor)
|
||
- **AI 工具 (1个)**:
|
||
- `CompileLiveCoding()` - 触发编译并返回结果 + MSVC 诊断
|
||
- **关键实现**: 线程安全日志捕获 (`FLiveCodingOutputCollector` 实现 `FOutputDevice`)，时间戳检测 UBT Log.txt，`#if WITH_LIVE_CODING` 守卫
|
||
|
||
### 7. MCPClientToolset —— MCP 客户端桥接
|
||
- **功能**: 将 Unreal Editor 连接到外部 MCP 服务器，将其工具呈现给 AI
|
||
- **模块**: `MCPClientToolset` (Editor)
|
||
- **架构**: `FMCPClientToolset` (FToolset 子类) + `UMCPClientToolsetSubsystem` + `UMCPToolsetSettings` (DeveloperSettings)
|
||
- **AI 工具**: 动态，取决于连接的外部 MCP 服务器
|
||
- **传输协议**:
|
||
- Legacy SSE: GET `/sse` + POST `/message`
|
||
- Streamable HTTP: 单一 POST 端点
|
||
- OAuth 2.0 + PKCE: 完整 OAuth 流程
|
||
- **关键实现**: SPSC 队列跨线程流式传输，JSON-RPC 2.0 与 TPromise/TFuture，SHA-256 实现用于 PKCE
|
||
|
||
### 8. NiagaraToolsets —— Niagara 粒子系统 (4合1)
|
||
- **功能**: Niagara 系统/发射器/模块/渲染器的完整 CRUD + 运行时组件操作 + 编译诊断
|
||
- **模块**: `NiagaraToolsets` (Editor)
|
||
- **架构**: 基类 `UNiagaraToolset` + 4个专用子工具集 + 2个 JSON 转换器 + 1个 AgentSkill
|
||
|
||
#### 8a. UNiagaraToolset_Info
|
||
- `UEnum_Info` - 枚举查找
|
||
- `GetAssetDiscoveryInfo` - 资产发现路径
|
||
- `UAgentSkill_NiagaraBase` - AI prompt 增强
|
||
|
||
#### 8b. UNiagaraToolset_System (最大的工具集)
|
||
- **Schema**: GetSystemSchema, GetEmitterSchema, GetRendererSchema, GetDataInterfaceSchema, GetStackInputSchema, GetModuleSchema, GetDynamicInputSchema (+ 基于资产的变体)
|
||
- **Topology**: GetSystemTopology, GetScriptStackTopology, GetEmitterTopology, GetModuleTopology, GetStackInputTopology
|
||
- **Data**: GetUserVariables, GetSystemData, GetEmitterData, GetRendererData, GetStackInputData
|
||
- **Edit**: SetSystemData, SetEmitterData, SetRendererData, AddUserVariables, RemoveUserVariables, AddEmitter, RemoveEmitter, AddRenderer, RemoveRenderer, AddModule, RemoveModule, SetModuleEnabled, AddSetParametersModule, AddSetParameterEntry, RemoveSetParameterEntry, SetStackInputData
|
||
- **Diagnostics**: GetSystemCompileState, GetStackIssues, ApplyStackIssueFix (全部异步)
|
||
|
||
#### 8c. UNiagaraToolset_Component
|
||
- `SetSystem`, `GetUserVariables`, `SetVariable`, `GetVariable`
|
||
|
||
#### 8d. UNiagaraToolset_Blueprint
|
||
- `ConstructNiagaraBPWrapperFromSystem`, `ConstructNiagaraBPWrapperFromComponent`
|
||
|
||
### 9. PhysicsToolsets —— 物理资产
|
||
- **功能**: 创建和操作物理资产（碰撞体、形状、约束）
|
||
- **模块**: `PhysicsToolsets` (Editor)
|
||
- **架构**: `UPhysicsAssetToolset`
|
||
- **AI 工具 (14个)**:
|
||
- **形状**: SetSphere, SetCapsule, SetBox, RemoveShape (upsert 模式)
|
||
- **体 CRUD**: AddBody, RemoveBody, GetBodyNames
|
||
- **体属性**: Get/SetBodyPhysicsMode, Get/SetBodyMassScale
|
||
- **约束**: GetConstraints, AddConstraint, SetConstraintLimits, RemoveConstraint
|
||
- **创建**: CreateFromMesh
|
||
- **关键实现**: 使用 Chaos 物理引擎类型，Modify() 撤销支持，RemoveBody 级联删除约束
|
||
|
||
### 10. SequencerAnimMixerToolset —— Sequencer 动画混合器
|
||
- **功能**: Sequencer 动画混合器轨道管理（唯一纯 Python 实现的工具集）
|
||
- **模块**: 无 C++ 模块，纯 Python (`Content/Python/`)
|
||
- **架构**: Python 类 `SequencerAnimMixerTools` 装饰为 `unreal.ToolsetDefinition`
|
||
- **AI 工具 (20个)**:
|
||
- **Layers & Content (11个)**: get_mixer_layers, get_mixer_layer_count, add_mixer_layer, insert_mixer_layer, add_animation_to_mixer, add_child_track_to_layer, get/set_layer_name, get_layer_sections, get_layer_index, is_layer_empty
|
||
- **Transitions (5个)**: get_transitions_for_section, get_transition_between, get_transition_info, change_transition_type, get_transition_name
|
||
- **Decorations (5个)**: get_compatible_decorations, get_decorations, find_decoration, add_decoration, remove_decoration
|
||
|
||
### 11. SlateInspectorToolset —— UI 自动化（Playwright 风格）
|
||
- **功能**: Slate UI 检查和自动化，AI 可驱动编辑器界面的点击/输入/截图
|
||
- **模块**: `SlateInspectorToolset` (Editor) + `SlateInspectorToolsetTests`
|
||
- **架构**: `USlateInspectorToolset` + 3个支持系统:
|
||
- **RefCache**: SWidget ↔ ref string 双向映射，按角色前缀计数器分配 (如 "b1", "b2")
|
||
- **SnapshotRenderer**: DFS 遍历 widget 树，缩进文本快照，结构容器省略
|
||
- **ObserverManager**: ~100ms 间隔连续子树观察，缓存快照
|
||
- **AI 工具 (14个)**:
|
||
- **检查**: Snapshot, Observe/Unobserve/ListObservers, Screenshot, WaitFor
|
||
- **交互**: Click (左右中/修饰符/双击), Hover, Type (逐字符+提交), PressKey (组合键), SelectOption (下拉选择), Drag (鼠标拖动), FillForm (批量表单)
|
||
- **窗口**: Windows (列表/选择/关闭)
|
||
- **关键实现**: 使用直接 Slate 事件 API 而非 AutomationDriver（避免死锁），SelectOption 打开下拉→Tick两次→搜索文本→点击
|
||
|
||
### 12. UMGToolSet —— UMG Widget 蓝图
|
||
- **功能**: 通过反射创建和操作 UMG Widget Blueprint
|
||
- **模块**: `UMGToolSet` (EditorNoCommandlet)
|
||
- **架构**: `UUMGToolSet`
|
||
- **AI 工具 (11个)**:
|
||
- **创建**: CreateWidgetBlueprint, AddWidget, SetNamedSlotContent
|
||
- **查询**: GetWidgets (深度优先树), GetNamedSlots, ListWidgetBlueprints, ListWidgetClasses
|
||
- **修改**: MoveWidget, RemoveWidget, RenameWidget, SetWidgetAsVariable, ReparentWidgetBlueprint
|
||
- **生命周期**: CompileWidgetBlueprint
|
||
- **关键实现**: BindWidget 属性验证，ContentWidget 单子容器检测，GUID 管理，编译错误收集（图节点 + MessageLog），类路径解析
|
||
|
||
### 13. WorldConditionsToolset —— 世界条件检查
|
||
- **功能**: 获取世界条件查询和人可读描述
|
||
- **模块**: `WorldConditionsToolset` (Editor)
|
||
- **架构**: `UWorldConditionTools` + `FWorldConditionQueryConverter` (JSON 转换器)
|
||
- **AI 工具 (2个)**:
|
||
- `GetQueryDescription(FWorldConditionQueryDefinition)` - 查询描述
|
||
- `GetConditionDescription(FInstancedStruct)` - 条件描述
|
||
|
||
---
|
||
|
||
## 二、空壳/占位符 Toolset（模块存在但无功能）
|
||
|
||
### 14. AIModuleToolset
|
||
- 描述: "AI module toolset"
|
||
- 状态: `StartupModule()` 空，未注册任何工具
|
||
- 依赖: Core
|
||
|
||
### 15. AnimationAssistantToolset
|
||
- 描述: 意图为动画系统（Control Rig, Sequencer）
|
||
- 状态: 空实现，仅占位注释
|
||
- 依赖: ControlRig, LevelSequenceEditor, SequencerScripting
|
||
|
||
### 16. ConversationToolset
|
||
- 描述: 意图为 CommonConversation 对话树/编辑器工具
|
||
- 状态: 空实现
|
||
- 依赖: CommonConversation
|
||
|
||
### 17. StateTreeToolset
|
||
- 描述: "StateTree Inspection"
|
||
- 状态: 最简模块，仅日志类别和空 StartupModule
|
||
- 依赖: StateTree
|
||
|
||
---
|
||
|
||
## 三、聚合器
|
||
|
||
### 18. AllToolsets
|
||
- **类型**: "元插件" / 聚合器，无源代码
|
||
- **功能**: 依赖所有其他工具集，一次启用全部
|
||
- **架构**: 描述符仅含依赖列表 (14个插件)
|
||
- **Source 目录**: 不存在
|
||
|
||
---
|
||
|
||
## 四、启用工具集的建议配置
|
||
|
||
根据实际需求选择：
|
||
|
||
| 场景 | 需要的工具集 |
|
||
|------|-------------|
|
||
| C++ 编译辅助 | LiveCodingToolset |
|
||
| 自动化测试 | AutomationTestToolset |
|
||
| Gameplay Ability System | GASToolsets |
|
||
| Gameplay 标签管理 | GameplayTagsToolset |
|
||
| Niagara 粒子/特效 | NiagaraToolsets |
|
||
| 物理资产 | PhysicsToolsets |
|
||
| Dataflow/破坏系统 | DataflowAgent |
|
||
| UMG UI 构建 | UMGToolSet |
|
||
| Sequencer 动画混合 | SequencerAnimMixerToolset |
|
||
| 编辑器 UI 自动化 | SlateInspectorToolset |
|
||
| 外部 MCP 服务器 | MCPClientToolset |
|
||
| GameFeature 插件 | GameFeaturesToolset |
|
||
| 世界条件 | WorldConditionsToolset |
|
||
| （占位）AI 模块 | AIModuleToolset |
|
||
| （占位）动画辅助 | AnimationAssistantToolset |
|
||
| （占位）对话系统 | ConversationToolset |
|
||
| （占位）状态树 | StateTreeToolset |
|
||
| 全部启用 | AllToolsets |
|
||
|
||
---
|
||
|
||
## 五、统计总览
|
||
|
||
| 类别 | 数量 |
|
||
|------|------|
|
||
| 完全实现的功能工具集 | 13 (含子工具集) |
|
||
| 空壳占位符 | 4 |
|
||
| 聚合器 | 1 |
|
||
| **总 AI 工具数** | **~120+** |
|
||
| C++ 实现 | 16 |
|
||
| Python 实现 | 1 |
|
||
| 纯描述符 | 1 |
|