用途
ue-ai-toolsets 面向在 UE 5.9 中通过 MCP 让 AI 代理操作编辑器的开发者:当需要了解工具如何命名、查找、过滤和调用,或需要为项目添加自定义工具(C++/Python)与项目级指令(技能),或排查工具、技能不出现、“toolset not found”、打包失败等问题,以及决定哪些 AI 插件可以随游戏发布时使用。资料内容全部来自 5.9 源码,所有相关插件均为实验性版本(IsExperimentalVersion),引擎更新后需重新核对名称。
系统组成
- ToolsetRegistry:位于 Engine/Plugins/Experimental/ToolsetRegistry,提供注册表、schema 烘焙、分发、AgentSkillToolset、Markdown 技能加载器与 Python 包 toolset_registry。
- 引擎工具集:位于 Engine/Plugins/Experimental/Toolsets/<Name>,每个领域一个插件,包括 EditorToolset、BlueprintToolsets、SceneCaptureToolset、SlateInspectorToolset、WidgetFinder、InputToolset、ConsoleToolset、AutomationTestToolset、StateTreeToolset、NiagaraToolsets、PCGToolset、MetaSoundToolset、AnimationAssistantToolset、MetaHuman 系列等约 40 个;AllToolsets 与 AllMetaHumanToolsets 是启用整组的元插件。
- Unreal MCP:位于 Engine/Plugins/Experimental/ModelContextProtocol,是编辑器内的 HTTP MCP 服务器,默认端口 8000,路径 /mcp。
- Unreal Assistant:位于 Engine/Plugins/Experimental/AIAssistant,是 Epic 的编辑器内聊天代理,同样使用该注册表。
- 引擎 Agent 工具:位于 Engine/Extras/AgentTools,为编辑器外的代理提供脚本与 Markdown 技能(构建诊断、无头运行、日志分析、体积裁剪)以及 ProjectTemplate/AGENTS.md。
命名与调用
一个工具对应一个函数,全名为 <ToolsetName>.<ToolName>。C++ 工具集名由 /Script/<Module> 包推导为 <module>.<去掉前缀的类名>,如 EditorToolset.EditorAppToolset、AutomationTestToolset.AutomationTestToolset;Python 工具集名为插件 Content/Python 下的点分模块路径加类名,如 editor_toolset.toolsets.python_scripting.PythonScriptingTools。只写裸类名是“not found”错误的主要原因。
调用方式:
- MCP:开启 bEnableToolSearch(默认)时 tools/list 只返回 list_toolsets、describe_toolsets、describe_tools、call_tool 四个工具,由客户端按需发现并通过 call_tool(toolset_name, tool_name, arguments) 分发;对象参数以引用形式传递({"refPath": "/Game/Path/Asset.Asset"})。
- 在 execute_python 运行的编辑器 Python 中:await call_tool("EditorToolset.EditorAppToolset.StartPIE", options={...})。
- 任意编辑器 Python:await toolset_registry.execute_tool(toolset_name, tool_name, {...})。
- C++/Blueprint:UToolsetRegistry::ExecuteTool(ToolsetName, ToolName, JsonInput) 返回 UAsyncFunctionResultString;GetAllToolsetJsonSchemas() 导出全部 schema。
参数名必须与工具自身一致:C++ 工具用 C++ 参数名(如 maxResolution、nameFilter),Python 工具用 Python 参数名(snake_case),写错会被拒绝并返回有效名称列表。每个工具的 schema 带 annotations.accessMode(read/write/execute,未声明视为 execute)。
服务器设置
UModelContextProtocolSettings(编辑器偏好,按用户)与 UModelContextProtocolProjectSettings(项目设置,DefaultGame.ini)包含 ServerPortNumber(默认 8000,可用 -ModelContextProtocolPort=N 覆盖,多个编辑器需各用独立端口)、bAutoStartServer、ServerUrlPath(默认 /mcp)、AdditionalAllowedOrigins、bEnableToolSearch、bDumpMediaToDisk(把发给客户端的图像/音频写入 Saved/ModelContextProtocol)。两个类都有 Instructions 字段,用于向每个连接的 MCP 客户端下发用户/项目指令;修改后需重连客户端。
编写工具集
C++:在依赖 ToolsetRegistry 的插件中建编辑器模块(LoadingPhase PostEngineInit、TargetAllowList Editor),继承 UToolsetDefinition,用 UFUNCTION(meta=(AICallable, AIAccessMode="Read")) 标记工具,未标记的函数被忽略;工具默认是静态的,除非类重写 IToolsetProvider::UsesInstanceDispatch() 或 UsesInstanceArgument()(二者不可同时使用)。类注释即工具集描述,函数文档注释即工具描述,@param 行描述参数。参数与结果经工具集 JSON 转换器处理,支持 FString、数字、bool、枚举、TArray/TMap、BlueprintType 结构体与对象引用;建议返回带命名字段的结构体而非裸 bool。IToolsetProvider 的 GetToolsToHide / IsToolsetHidden 可对受限宿主隐藏工具。模块在 StartupModule 中调用 RegisterToolsetClass,ShutdownModule 中调用 UnregisterToolsetClass。
Python:用 @unreal.uclass() 定义继承 unreal.ToolsetDefinition 的类,工具函数加 @toolset_registry.tool_call(mode=unreal.ToolAccessMode.READ),要求所有参数与返回值有类型注解,Google 风格 docstring 作为描述;在 init_unreal.py 中调用 Registration.register() 注册。开发时可用 toolset_registry.reload_module() 重载并重新注册。注意 Python 工具集在编辑器启动后可能延迟数秒才可用,可等待后重试。Python 工具集不支持编辑器外运行。
Agent 技能
两类技能均由 AgentSkillToolset.ListSkills({path: description})列出、GetSkills(skillPaths=[...])({path: {instructions}})加载,二者均为 AIRuntimeCallable、Read。
- 类技能:UAgentSkill 子类(Blueprint,或 Python 加 @toolset_registry.agent_skill.agent_skill 与 instructions 类属性),路径为类路径。CreateSkill 与 UpdateSkill 可写入技能资产,其注释要求仅在用户许可下调用。
- Markdown 技能:递归查找 SKILL.md,搜索根包括已启用插件的 <Plugin>/Skills/(键 /Skills/<PluginName>/<子目录>)、Engine/Platforms/<Platform>/Skills/、Engine/Extras/AgentTools/Skills/<name>、项目 <Project>/Skills/,以及 MarkdownSkills::AddSearchRoot 添加的目录。Frontmatter 逐行读取,仅使用 name 与 description;建议 description 写在一行,块标量写法会导致描述被截断为“>”。无 description 时取正文首行散文,描述为空则不出现在 ListSkills 中。GetSkills 返回去掉 frontmatter 的正文并加文件位置前缀,同时把相对 Markdown 链接改写为绝对路径。键按插件、平台、引擎、项目顺序去重,先到者胜;文件每次调用重新读取,编辑后无需重启编辑器。
过滤与发布
UToolsetRegistrySettings(项目设置 → Toolset Registry,DefaultGame.ini)提供 BlockedNames/AllowedNames 与 AgentSkillBlockedNames/AgentSkillAllowedNames:斜杠包围的模式按正则处理(如 /^Fake.*/),其余按不区分大小写的子串匹配,屏蔽优先于允许;匹配工具集名的模式切换整个工具集,其余按完整工具名过滤单个工具;技能过滤同时作用于类技能与 Markdown 键。SetObjectPropertiesBlockedClasses 等可阻止通用属性设置工具触碰指定类或属性。
AI 插件属于编辑器工具。在需要发布游戏的项目中,应在 .uproject 为每个启用的 AI 插件(AIAssistant、AllToolsets、AllMetaHumanToolsets、ToolsetRegistry、ModelContextProtocol、MCPClientToolset 及单个工具集插件)设置 "TargetAllowList": ["Editor"],Web 构建再加 "PlatformDenyList": ["Wasm"]。打包时 ToolsetRegistry 仍会在 /ToolsetRegistry/ToolsetManifestSeed 下生成 manifest,平台缺少该模块会导致 cook 失败,需添加 +DirectoriesToNeverCook=(Path="/ToolsetRegistry/ToolsetManifestSeed")(只能指向子目录,不能是插件根目录)。
限制
所有相关插件均为实验性,名称可能随引擎版本变化;Python 工具集仅限编辑器内;Python 工具集注册时机可能导致启动后短暂不可见;cooked 构建中的工具需标记 AIRuntimeCallable 并在模块 StartupModule 末尾调用 EnableCookedRuntimeSupport;MCP 客户端与服务器需分别配置端口与指令。