diff --git a/07-Other/AI/AI Agent/UnrealEngine/UnrealMcp/UE5.8 MCP 1.md b/07-Other/AI/AI Agent/UnrealEngine/UnrealMcp/UE5.8 MCP 1.md new file mode 100644 index 0000000..06f3b4e --- /dev/null +++ b/07-Other/AI/AI Agent/UnrealEngine/UnrealMcp/UE5.8 MCP 1.md @@ -0,0 +1,40 @@ +# UAgentSkill 分析 + +## 1. 它是什么 + +UAgentSkill 是 UE5.8 MCP 的 AI prompt 增强机制，功能等价于 Claude Code 的 Skill： + +| | UE5.8 UAgentSkill | Claude Code Skill | +|---|---|---| +| 载体 | Blueprint 资产（UAgentSkill 子类） | Markdown 文件 | +| 作用 | 注入领域知识 + 指令到 AI 上下文 | 注入工作流指引到对话 | +| 依赖 | Toolsets 字段声明需加载哪些 toolset | 无 | +| 动态生成 | GeneratePrompt() 虚函数可编程 | 静态内容 | +| 创建 | AI 通过 MCP CreateSkill 创建 | 文件写入 | + +它不是功能性工具，不执行编辑器操作——只提供上下文："这个领域怎么用、工具有哪些、最佳实践是什么"。 + +## 2. 相关类 + +- **UAgentSkill**：基类，核心属性 Description + Instructions + Toolsets，虚函数 GeneratePrompt() +- **UAgentSkillBestPractices**：改写 GeneratePrompt，追加技能编写规范 +- **UAgentSkill_NiagaraBase**：改写 GeneratePrompt，前置 Niagara 概述 + 资产发现路径 +- **UAgentSkillToolset**：继承 UToolsetDefinition，暴露 MCP CRUD（ListSkills / GetSkills / CreateSkill / UpdateSkill） +- **FAgentSkillDetails**：DTO，最终生成的 Instructions + 依赖 toolset 名列表 + +核心流程：GetDetails() → GeneratePrompt(Instructions) → FAgentSkillDetails → AI 拿到最终 prompt。 + +## 3. 编写一个基础 UAgentSkill + +**C++ 子类方式：** + +1. 继承 UAgentSkill +2. 设置 Description（简短摘要，ListSkills 返回它） +3. 设置 Instructions（详细指令，会被 GeneratePrompt 处理） +4. 在 Toolsets 中声明依赖的功能性 toolset（软引用，系统据此自动加载） +5. 重写 GeneratePrompt_Implementation() 在指令前后注入额外上下文 + +Niagara 实现模式：前置概念概述 → 遍历 toolset 获取专属 prompt → 插入原始 Instructions → 追加资产发现路径。 + +**MCP 运行时创建（AI 调用，需用户许可）：** +CreateSkill(/Game/Skills/, MySkill, "描述", {Instructions:"...", Toolsets:["/Script/..."]})，本质是创建以 UAgentSkill 为父类的 Blueprint 资产，写入 CDO 属性。 \ No newline at end of file diff --git a/07-Other/AI/AI Agent/UnrealEngine/UnrealMcp/UE5.8 MCP.md b/07-Other/AI/AI Agent/UnrealEngine/UnrealMcp/UE5.8 MCP.md index 51736b0..a605e74 100644 --- a/07-Other/AI/AI Agent/UnrealEngine/UnrealMcp/UE5.8 MCP.md +++ b/07-Other/AI/AI Agent/UnrealEngine/UnrealMcp/UE5.8 MCP.md @@ -1,17 +1,98 @@ -# UE5.8 MCP Toolsets 完整分析 - +# UE5.8 MCP Toolsets 分析 ## 总体架构 - 所有Toolset都位于 `Engine\Plugins\Experimental\Toolsets`，共18个插件。它们通过 `ToolsetRegistry` 插件（核心基础设施）将 AI-callable 工具暴露给 MCP 系统（如 UnrealMCP）。 +### 功能维度总览 +#### 核心编辑器操作 + +| Toolset | 核心功能 | +| ------------------------------------------------------------------------------ | ---------------------------------------- | +| [[#11. SlateInspectorToolset —— UI 自动化（Playwright 风格）\|SlateInspectorToolset]] | Playwright 风格 UI 自动化：点击、输入、截图、widget 树快照 | +| [[#六、MCP 运行时实际检测\|EditorAppToolset]] | 控制台变量、资产成像、Actor/资产选择、视口相机、内容浏览器导航 | +| [[#六、MCP 运行时实际检测\|LogsToolset]] | 输出日志读取、日志类别详细级别控制 | +| [[#六、MCP 运行时实际检测\|SceneTools]] | 关卡加载/放置/移除 Actor、相机、Outliner 文件夹管理 | +| [[#六、MCP 运行时实际检测\|PrimitiveTools]] | 图元几何组件（球体、立方体等）添加 | +| [[#6. LiveCodingToolset —— 热编译\|LiveCodingToolset]] | 编辑器运行时 C++ 热编译 | + +#### 资产与资源管理 + +| Toolset | 核心功能 | +|---------|----------| +| [[#六、MCP 运行时实际检测\|AssetTools]] | 资产搜索/加载/保存/删除/移动/复制，文件读写 | +| [[#六、MCP 运行时实际检测\|ObjectTools]] | UObject / UClass 属性检查/修改，子类发现 | +| [[#六、MCP 运行时实际检测\|BlueprintTools]] | Blueprint 蓝图操作 | +| [[#六、MCP 运行时实际检测\|MaterialTools]] | Material 创建/编辑及表达式图 | +| [[#六、MCP 运行时实际检测\|MaterialInstanceTools]] | MaterialInstanceConstant 创建/修改 | +| [[#六、MCP 运行时实际检测\|TextureTools]] | Texture 资产操作 | +| [[#六、MCP 运行时实际检测\|StaticMeshTools]] | 静态网格检查与修改 | +| [[#六、MCP 运行时实际检测\|SkeletalMeshTools]] | 骨骼网格检查与修改（网格/材质/骨骼/插槽） | +| [[#六、MCP 运行时实际检测\|CurveTableTools]] | CurveTable 创建/编辑 | +| [[#六、MCP 运行时实际检测\|DataTableTools]] | DataTable 创建/编辑 | +| [[#六、MCP 运行时实际检测\|DataAssetTools]] | DataAsset 操作 | +| [[#六、MCP 运行时实际检测\|StringTableTools]] | StringTable 创建/编辑 | +| [[#12. UMGToolSet —— UMG Widget 蓝图\|UMGToolSet]] | UMG Widget Blueprint 创建/修改/编译 | + +#### Gameplay + +| Toolset | 核心功能 | +|---------|----------| +| [[#4. GASToolsets —— Gameplay Ability System 工具集 (3合1)\|GASToolsets]] | GAS 运行时检测 + AttributeSet 发现 + GameplayCue 管理 | +| [[#5. GameplayTagsToolset —— GameplayTag 管理\|GameplayTagsToolset]] | GameplayTag 增删改查 + 引用者搜索 | +| [[#13. WorldConditionsToolset —— 世界条件检查\|WorldConditionsToolset]] | 世界条件查询/条件描述 | +| [[#六、MCP 运行时实际检测\|ActorTools]] | Actor 变换/标签/父子关系/组件检查修改 | +| [[#9. PhysicsToolsets —— 物理资产\|PhysicsToolsets]] | 物理资产：碰撞体、形状、约束创建/编辑 | +| [[#16. ConversationToolset\|ConversationToolset]] | 对话图资产检查（Python 实现） | +| [[#17. StateTreeToolset\|StateTreeToolset]] | StateTree 结构检查与导航（Python 实现） | + +#### Sequence + +| Toolset | 核心功能 | +|---------|----------| +| [[#10. SequencerAnimMixerToolset —— Sequencer 动画混合器\|SequencerAnimMixerToolset]] | Sequencer 动画混合器：层/动画内容/过渡/装饰 | + +#### 动画系统 + +| Toolset | 核心功能 | +|---------|----------| +| [[#15. AnimationAssistantToolset\|AnimationAssistantToolset]] | Control Rig + Sequencer 全套动画工具（超大 Python 实现，8 类 100+ 工具） | + +#### 特效系统 (Niagara) + +| Toolset | 核心功能 | +|---------|----------| +| [[#8. NiagaraToolsets —— Niagara 粒子系统 (4合1)\|NiagaraToolsets]] | Niagara 系统/发射器/模块/渲染器 CRUD + 编译诊断 + 组件操作 | + +#### PCG + +| Toolset | 核心功能 | +|---------|----------| +| [[#2. DataflowAgent —— Dataflow 图编辑\|DataflowAgent]] | Dataflow 图编辑（Geometry Collection 破坏系统） | + +#### 测试与配置 + +| Toolset | 核心功能 | +|---------|----------| +| [[#1. AutomationTestToolset —— 自动化测试\|AutomationTestToolset]] | 自动化测试框架：发现、列出、运行、结果获取 | + +#### 插件与功能管理 + +| Toolset | 核心功能 | +|---------|----------| +| [[#3. GameFeaturesToolset —— 游戏功能插件管理\|GameFeaturesToolset]] | GameFeature 插件列出/检查/创建 | +| [[#7. MCPClientToolset —— MCP 客户端桥接\|MCPClientToolset]] | 外部 MCP 服务器桥接（SSE/StreamableHTTP/OAuth） | + +#### 其他工具 + +| Toolset | 核心功能 | +|---------|----------| +| [[#六、MCP 运行时实际检测\|ProgrammaticToolset]] | 沙盒 Python 脚本执行，可编排调用其他工具 | +| [[#六、MCP 运行时实际检测\|AgentSkillToolset]] | Agent Skill 的列表/读取/创建/更新 | +| [[#14. AIModuleToolset\|AIModuleToolset]] | 行为树检查与导航（Python 实现） | + + +> 以上 3 个工具集均有 Python 实现，C++ 模块仅负责加载插件，实际逻辑和工具注册均在 Python 侧完成。 ### MCP 服务器连接配置 - -- **服务器地址**: `http://localhost:8000/mcp` -- **协议版本**: `2025-11-25` (Streamable HTTP) -- **配置文件**: `Engine\Plugins\Experimental\Toolsets\.mcp.json` -- **状态**: 已连接，正常运行 - ```json { "mcpServers": { @@ -48,9 +129,8 @@ | **EditorSubsystem 生命周期管理** | AutomationTest, LiveCoding, SlateInspector, MCPClient | | **多工具集模块注册** | GASToolsets (3个), NiagaraToolsets (4个) | | **ON_SCOPE_EXIT 回滚保护** | GameFeaturesToolset | -| **纯 Python 实现** | SequencerAnimMixerToolset | -| **聚合器（描述符仅含依赖）** | AllToolsets | -| **空壳/占位符** | AIModuleToolset, AnimationAssistant, Conversation, StateTree | +| **纯 Python 实现 (C++ 模块仅作加载器)** | AIModuleToolset, AnimationAssistant, ConversationToolset, StateTreeToolset | +| **Python + C++ 混合实现** | SequencerAnimMixerToolset (仅 Python), NiagaraToolsets (C++ + Python 注册) --- @@ -182,7 +262,7 @@ - **关键实现**: 使用 Chaos 物理引擎类型，Modify() 撤销支持，RemoveBody 级联删除约束 ### 10. SequencerAnimMixerToolset —— Sequencer 动画混合器 -- **功能**: Sequencer 动画混合器轨道管理（唯一纯 Python 实现的工具集） +- **功能**: Sequencer 动画混合器轨道管理（纯 Python 实现） - **模块**: 无 C++ 模块，纯 Python (`Content/Python/`) - **架构**: Python 类 `SequencerAnimMixerTools` 装饰为 `unreal.ToolsetDefinition` - **AI 工具 (20个)**: @@ -224,139 +304,441 @@ --- -## 二、空壳/占位符 Toolset（模块存在但无功能） +## 二、Python 实现的 Toolset（C++ 模块仅为加载器） -### 14. AIModuleToolset -- 描述: "AI module toolset" -- 状态: `StartupModule()` 空，未注册任何工具 -- 依赖: Core +### 14. AIModuleToolset —— 行为树 AI 工具 +- **功能**: 行为树检查和导航（Python 实现） +- **C++ 模块**: `AIModuleToolset` (Editor, PostEngineInit) — 空 `StartupModule`，仅负责加载插件 +- **Python 实现**: `Content/Python/aimodule_toolset/toolsets/behavior_tree.py` +- **注册方式**: `Registration([BehaviorTreeTools])` +- **AI 工具 (7个)**: + - `get_blackboard(behavior_tree)` - 获取 BlackboardData 资产 + - `get_root_decorators(behavior_tree)` - 根级 BTDecorator + - `list_nodes(behavior_tree)` - DFS 遍历所有 BTNode + - `get_node_depth(behavior_tree, node_index)` - 节点在树中的深度 + - `get_node_depths(behavior_tree)` - 所有节点深度 + - `get_children(composite)` - Composite 节点的直接子节点 + - `get_subtree(node)` - RunBehavior 任务引用的子 BT -### 15. AnimationAssistantToolset -- 描述: 意图为动画系统（Control Rig, Sequencer） -- 状态: 空实现，仅占位注释 -- 依赖: ControlRig, LevelSequenceEditor, SequencerScripting +### 15. AnimationAssistantToolset —— 动画与 Sequencer 工具集（超大型 Python 实现） +- **功能**: 最庞大的工具集，覆盖 Control Rig、Sequencer、关键帧、大纲、条件、自定义绑定、导入导出 +- **C++ 模块**: `AnimationAssistantToolset` (Editor, PostEngineInit) — 空 `StartupModule` +- **Python 实现**: `Content/Python/animation_toolset/toolsets/` (21 个文件，~5000+ 行代码) +- **注册方式**: `init_unreal.py` 直接调用 `register_toolset_class()` 注册 8 个类 +- **8 个子工具集**: -### 16. ConversationToolset -- 描述: 意图为 CommonConversation 对话树/编辑器工具 -- 状态: 空实现 -- 依赖: CommonConversation +| 类 | 领域 | 工具数 | +|----|------|--------| +| `ControlRigTools` | 层级管理、图操作、节点/Pin 管理、变量 | 30+ | +| `SequencerTools` | Level Sequence 生命周期、回放、绑定、轨道、段、文件夹、复制粘贴、标签、烘焙 | 70+ | +| `SequencerKeyframingTools` | 关键帧增删、float/bool/int/string 通道、插值、默认值 | | +| `SequencerControlRigTools` | Sequencer 中 CR 控制值读写、关键帧、烘焙、空间切换 | | +| `SequencerOutlinerTools` | 大纲树检查、选择、折叠/展开、静音/独奏/锁定 | | +| `SequencerConditionTools` | 轨道/段运行时条件（平台/蓝图/组条件） | | +| `SequencerCustomBindingTools` | 转换 possessable/spawnable/自定义绑定，修改 Actor 模板类 | | +| `SequencerImportExportTools` | FBX 导入/导出、AnimSequence 导出 | | -### 17. StateTreeToolset -- 描述: "StateTree Inspection" -- 状态: 最简模块，仅日志类别和空 StartupModule -- 依赖: StateTree +### 16. ConversationToolset —— 对话图检查 +- **功能**: 检查 Conversation Graph (UConversationDatabase) 对话资产（Python 实现） +- **C++ 模块**: `ConversationToolset` (Editor, PostEngineInit) — 空 `StartupModule` +- **Python 实现**: `Content/Python/conversation_toolset/toolsets/conversation.py` +- **注册方式**: `Registration([ConversationTools])` +- **AI 工具 (7个)**: + - `list_entry_points(conversation)` - 入口点列表 + - `list_speakers(conversation)` - 说话者/参与者信息 + - `get_all_nodes(conversation)` - 所有可达 ConversationNode + - `get_node_guids(conversation)` - 所有节点 GUID + - `get_node_by_guid(conversation, guid)` - 按 GUID 查找节点 + - `get_node_connections(node)` - 输出连接 GUID (需要 ConversationNodeWithLinks) + - `get_sub_nodes(node)` - 任务节点的子节点 + +### 17. StateTreeToolset —— 状态树检查 +- **功能**: StateTree 状态树结构检查和导航（Python 实现） +- **C++ 模块**: `StateTreeToolset` (Editor, PostEngineInit) — 空 `StartupModule` +- **Python 实现**: `Content/Python/state_tree_toolset/toolsets/state_tree.py` +- **注册方式**: `Registration([StateTreeTools])` +- **AI 工具 (8个)**: + - `get_editor_data(state_tree)` - 获取 StateTreeEditorData + - `get_root_states(state_tree)` - 顶级状态 + - `get_children(state)` - 状态子节点 + - `get_tasks(state)` - 状态上的任务 + - `get_enter_conditions(state)` - 进入条件 + - `get_transitions(state)` - 状态转换 + - `get_global_tasks(state_tree)` - 全局任务 + - `get_evaluators(state_tree)` - 全局求值器 + - `get_node_description(state_tree, node)` - 节点可读描述 --- -## 三、聚合器 - -### 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 | +| 场景 | 需要的工具集 | +| ----------------------- | ------------------------- | +| 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 | +| Sequencer + Control Rig | AnimationAssistantToolset | +| 对话系统 | ConversationToolset | +| 状态树 | StateTreeToolset | + +--- +# 第三方 MCP 比较 + +## 概述 + +调研了 8 个第三方 Unreal MCP 开源仓库，均为 GitHub 社区项目。它们与官方 UE5.8 ToolsetRegistry 在架构理念、传输协议和实现方式上有本质差异。 + +## 各仓库速览 + +| 仓库 | 连接方式 | 需要插件? | 传输 | 语言 | 工具数 | UE 版本 | 核心定位 | +|------|---------|----------|------|------|--------|---------|---------| +| appleweed_UnrealMCPBridge | TCP | C++ 插件 | TCP :9000 | Python | ~35 | 5.5+ | 编辑器自动化 + Insights 性能追踪 | +| ChiR24_Unreal_mcp | HTTP 原生 / TCP | C++ 插件 (超大) | HTTP :3000 或 TCP :8091 | TS 或纯 C++ | 23 父工具(数百子动作) | 5.0-5.8 | **第三方中最全面** | +| chongdashu_unreal-mcp | TCP | C++ 插件 | TCP :55557 | Python | ~25 | 5.5+ | Blueprint + Actor 开发 | +| mcpanalyzer_UnrealMCP | **不连接 UE** | **无** | stdio | Python | 41 | 不限 | C++ 源码静态分析 | +| prajwalshettydev_UnrealGenAISupport | TCP | C++ 插件 | TCP :9877 | Python | ~25 | 5.4-5.7+ | LLM API 集成(主) + MCP(辅) | +| runeape-sats_unreal-mcp | HTTP | **无** (用 Remote Control API) | HTTP :30010 | Python | ~15 | 5.3 | 场景搭建 + TLA+ 形式化验证 | +| runreal_unreal-mcp | UDP + TCP | **无** (用 Python Remote Exec) | UDP 多播 + TCP | TypeScript | 19 | 5.4+ | 最快迭代，零插件 | +| winyunq_UnrealMotionGraphicsMCP | TCP 异步 | C++ UMG 插件 | TCP 异步 | Python | ~30 | 5.6+ | UMG / Material / Sequencer 设计 | + +## 架构差异 + +### 第三方主流模式：外部进程 + TCP 桥接 +``` +Claude Desktop → Python MCP Server (FastMCP) → TCP Socket → C++ Plugin (UE 内部) +``` + +6/8 的仓库都采用此模式（appleweed、ChiR24 (Option B)、chongdashu、prajwalshettydev、winyunq）。外部进程运行 MCP 协议，通过自定义 JSON 帧协议将命令转发到 UE 内部的 C++ TCP 服务器。 +- 特例 + - **runeape-sats**：直接 HTTP 调用 UE 内置的 Remote Control API (`/remote/object/call`)，无需任何 C++ 代码 + - **runreal**：通过 UE 内置的 Python Remote Execution (UDP 发现 + TCP 命令)，所有工具本质是生成 Python 代码字符串在编辑器内执行 + - **mcpanalyzer**：完全不连接运行中的编辑器，静态索引 C++ 源代码文件，提供 `ue_search_class`、`ue_parse_ufunction`、`ue_compile_project` 等代码分析工具 + +### 官方模式：引擎内原生 HTTP +``` +Claude Desktop → JSON-RPC over HTTP/SSE → UE 引擎内部 MCP Server (C++) +``` +TLS/SSE、会话管理、反射 Schema 生成全部在引擎进程内完成，无外部依赖。 + +## 架构对比表 + +| 维度 | 第三方主流方案 | 官方 UE5.8 ToolsetRegistry | +|------|--------------|--------------------------| +| **运行位置** | 外部 Python/Node.js 进程 + C++ 插件 | 所有逻辑在引擎进程内 | +| **传输协议** | 自定义 JSON-over-TCP（各仓库自造轮子） | JSON-RPC 2.0 over Streamable HTTP (MCP 标准) | +| **类型安全** | Python type hints 或 Zod，手动校验 | C++ USTRUCT 反射自动生成 JSON Schema | +| **工具发现** | 装饰器或硬编码注册 | `UToolsetRegistry` 自动扫描注册 | +| **会话管理** | 单会话为主（仅 ChiR24 支持多会话） | 原生多会话 + SSE 流式推送 | +| **错误处理** | 各仓库不一致 (`status:error` vs `success:false`) | 标准 JSON-RPC 错误码 | +| **流式传输** | 无（全为请求-响应模式） | SSE 实时推送长时间操作进度 | +| **生命周期** | 外部进程需独立启动/停止 | 编辑器启动即自动运行 | + +## 技术优势对比 +- 第三方方案优势 + 1. **开发速度快**：Python 工具可在数分钟内添加，无需 C++ 编译 + 2. **零插件可选**：runreal 和 runeape-sats 只需启用内置引擎插件即可工作 + 3. **Python 生态**：可引入任意 Python 库（requests、mss 截图等） + 4. **独立演化**：MCP Server 和 UE 插件可独立更新，不受引擎版本约束 + 5. **入门门槛低**：Python/TypeScript 开发者即可贡献，无需 C++ 知识 +- 第三方方案劣势 + 1. **协议脆弱**：每个仓库都自己实现 TCP 帧协议，缓冲区处理和断线重连无标准 + 2. **双进程管理**：外部进程 + UE 插件需要同时监控，调试困难 + 3. **无类型安全**：参数以原始字典/字符串传递，手动校验，Schema 漂移风险高 + 4. **无标准工具发现**：工具列表硬编码在源码中，运行时无动态注册机制 + 5. **线程安全脆弱**：多数通过 `register_slate_post_tick_callback` 切回主线程 +- 官方方案优势 + 1. **工程级集成**：引擎内运行，零 IPC 开销，无外部进程管理 + 2. **反射驱动类型安全**：C++ USTRUCT 自动生成 JSON Schema，始终与实现同步 + 3. **插件化可扩展**：第三方可通过发布 UE 插件注册自定义 Toolset + 4. **原生多会话**：SSE 流式推送 + Session ID 管理，支持并发 AI 客户端 + 5. **标准协议**：符合 MCP 规范的 JSON-RPC 2.0，任何 MCP 客户端可直接连接 +- 官方方案劣势 + 1. **高入门门槛**：需要 C++ 知识创建新 Toolset + 2. **编译周期长**：任何工具变更需要 C++ 重编译 + 3. **生态受限**：不能直接使用 Python 第三方库 + 4. **版本锁定**：紧耦合引擎版本 --- -## 五、统计总览 +## 功能缺口分析：第三方有而官方没有 / 官方有而第三方没有 +### 第三方 MCP 有，官方 UE5.8 MCP 没有 -| 类别 | 数量 | +| 功能 | 来源仓库 | 说明 | +| ------------------------ | -------------------- | -------------------------------------------------------------------------------------- | +| **C++ 源码静态分析** | mcpanalyzer | 搜索 UCLASS/USTRUCT/UFUNCTION、反射解析、AST 分析、Build 编译、最佳实践检查——完全不需要运行编辑器 | +| **Unreal Insights 性能追踪** | appleweed | 启动/停止/分析 Unreal Insights trace、CSV profiling | +| **战斗/背包/网络/AI 系统** | ChiR24 | `manage_combat`、`manage_inventory`、`manage_networking`、`manage_ai`——GaAS 层面的完整系统管理 | +| **PCG 管理** | ChiR24 | `manage_pcg`——程序化生成工具 | +| **音频管理** | ChiR24 | `manage_audio`——SoundCue/Metasound 操作 | +| **HLSL 代码编辑** | winyunq | `hlsl_set_target`、`hlsl_get`、`hlsl_set`、`hlsl_compile`——直接在 MCP 中编辑 Material 的 HLSL 节点 | +| **HTML 转 UMG** | winyunq | 将 HTML 结构自动转换为 UMG Widget 树 | +| **LLM API 内置集成** | prajwalshettydev | 在 UE 编辑器内直接调用 OpenAI/Anthropic/DeepSeek API（主功能，MCP 为副） | +| **TLA+ 形式化验证** | runeape-sats | 城堡搭建工作流的 TLA+ 形式化规格 | +| **OS 级截图** | prajwalshettydev | 使用 Python `mss` 库截取整个屏幕，用于 AI 看图理解编辑器状态 | +| **Blueprint 图节点级编辑** | appleweed/chongdashu | 获取 Blueprint 节点 ID、Pin 详情、连接 Pin、添加事件/函数节点——粒度比官方 BlueprintTools 更细 | +| **Arbitrary Python 执行** | runreal | `editor_run_python`——在编辑器内执行任意 Python 代码，给了 AI 无限的引擎 API 访问能力 | +| **系统控制** | ChiR24 | `system_control`——编辑器进程层面的控制（重启、退出等） | +| **环境搭建** | ChiR24 | `build_environment`——构建环境管理 | + +### 官方 UE5.8 MCP 有，第三方 MCP 没有 + +| 功能 | 来源 Toolset | 说明 | +|------|-------------|------| +| **Slate UI 自动化 (Playwright 风格)** | SlateInspectorToolset | 快照、观察者、截图、点击/拖拽/Hover/输入/表单填充——以 AI Agent 视角驱动编辑器 UI | +| **Dataflow 图编辑** | DataflowAgent | Geometry Collection 破坏系统的节点图完整编辑（17 个工具） | +| **GAS 运行时检测** | GASToolsets | 实时检测 AbilitySystemComponent 的属性值、活跃效果、技能、标签 | +| **GameplayCue 管理** | GASToolsets | GameplayCue 标签增删、通知资产创建、缺少通知资产的标签发现 | +| **GameplayTag 管理** | GameplayTagsToolset | 完整的增删改查 + 资产引用者搜索 | +| **Live Coding 热编译** | LiveCodingToolset | 触发编译 + 收集 MSVC 诊断 + 线程安全日志捕获 | +| **MCP 客户端桥接** | MCPClientToolset | 接入外部 MCP 服务器（SSE/StreamableHTTP/OAuth+PKCE），聚合第三方工具 | +| **GameFeature 插件创建** | GameFeaturesToolset | 完整的 GFP 创建流程（目录→.uplugin→挂载→资产→保存），带 ON_SCOPE_EXIT 回滚 | +| **WorldConditions 检查** | WorldConditionsToolset | 查询/条件描述 + 自定义 JSON 转换器 | +| **Conversation Graph 检查** | ConversationToolset | 对话资产节点遍历、入口点、说话者、GUID 查找 | +| **StateTree 检查** | StateTreeToolset | 状态树结构导航、任务/条件/转换/求值器查询 | +| **CurveTable / DataTable / StringTable** | Core Python 模块 | 专门的表格数据资产创建/编辑工具 | +| **ProgrammaticToolset** | Core Python 模块 | 沙盒 Python 脚本编排——在同一脚本中调用多个 MCP 工具并编写自定义逻辑 | +| **AgentSkill 系统** | AgentSkillToolset | Agent Skill 的列表/读取/创建/更新——AI Agent 的 prompt 上下文管理 | +| **EditorAppToolset** | Core Python 模块 | 控制台变量管理、资产缩略图成像、内容浏览器导航 | +| **LogsToolset** | Core Python 模块 | 输出日志类别动态控制、日志读取 | +| **C++ JSON Schema 自动生成** | 架构层 | 从 USTRUCT 反射自动生成工具参数 Schema，永远与实现同步 | +| **原生多会话 SSE 流式推送** | 架构层 | 支持多个 AI 客户端同时连接，长时间操作进度实时推送 | +| **插件化 Toolset 扩展** | 架构层 | 第三方只需发布 UE 插件并注册 UToolsetDefinition，无需适配任何外部进程 | +| **标准 JSON-RPC 2.0** | 架构层 | 完全符合 MCP 协议规范，任何 MCP 客户端可直连 | + +### 差距总结 + +| 对比维度 | 第三方领先 | 官方领先 | +|---------|-----------|---------| +| **代码分析** | mcpanalyzer 独有 | — | +| **性能分析** | appleweed 的 Insights 集成 | — | +| **Gameplay 高级系统** | ChiR24 的 combat/inventory/AI/PCG/audio | GAS 运行时检测 + GameplayCue 官方更深入 | +| **UI 自动化** | — | SlateInspectorToolset 独有 | +| **资产表格** | — | CurveTable/DataTable/StringTable 独有 | +| **容器/编排** | runreal 的任意 Python 执行 | ProgrammaticToolset 沙盒编排 | +| **工程架构** | — | 反射 Schema、多会话 SSE、插件化扩展、标准协议 | +| **部署复杂度** | runreal/runeape-sats 零 C++ 即可用 | 需引擎编译，但启动即运行 | + +**核心结论**：第三方 MCP 在**广度**上占优（覆盖了更多非编辑器核心的领域），官方 MCP 在**深度和工程品质**上占优（单个领域的工具细粒度、类型安全、协议标准、可扩展性）。两者并非替代关系——各有独特优势，可以互补使用。 + +--- + +# UAgentSkill 子系统分析 + +## 概述 + +`UAgentSkill` 是 UE5.8 ToolsetRegistry 中的一个子系统，用于为 AI Agent 提供**上下文和提示词增强**（prompt enrichment），而非功能性的执行工具。它类似于 Claude Code 的 Skill 系统——两者都在 prompt 层面为 AI 提供领域知识和操作指引。 + +核心文件位置： +- 头文件：`ToolsetRegistry\Public\ToolsetRegistry\AgentSkill.h` +- 实现：`ToolsetRegistry\Private\ToolsetRegistry\AgentSkill.cpp` +- 测试：`ToolsetRegistry\Private\Tests\AgentSkillsTest.cpp` + `AgentSkillsTest.h` +- Niagara 示例：`NiagaraToolsets\Private\NiagaraToolset_Info.h` + `.cpp` + +## 类体系 + +``` +UObject +├── UAgentSkill (AgentSkill.h) +│ ├── UAgentSkillBestPractices (AgentSkill.h) — 追加技能编写最佳实践 +│ ├── UAgentSkill_NiagaraBase (NiagaraToolset_Info.h) — 追加 Niagara 概述 + 资产发现 +│ └── UAgentSkillCustomPrompt (AgentSkillsTest.h) — 测试用子类 +│ +├── UToolsetDefinition +│ └── UAgentSkillToolset (AgentSkill.h) — MCP CRUD 工具暴露 +│ +└── FAgentSkillDetails (AgentSkill.h) — DTO 数据结构 +``` + +## 核心数据结构 + +### FAgentSkillDetails（返回给 AI 的 DTO） + +```cpp +USTRUCT(BlueprintType) +struct FAgentSkillDetails +{ + TArray Toolsets; // 技能依赖的 toolset 完整名称 + FString Instructions; // 经过 GeneratePrompt 处理后的最终指令 +}; +``` + +### UAgentSkill 关键属性 + +| 属性 | 类型 | 说明 | +|------|------|------| +| `Description` | `FString` | 简短描述，用于 ListSkills 的摘要 | +| `Instructions` | `FString` | 详细指令（原始），会被 GeneratePrompt 处理 | +| `Toolsets` | `TArray>` | 依赖的工具集软引用 | + +## 关键方法解析 + +### GetDetails() — `AgentSkill.cpp:21` + +```cpp +FAgentSkillDetails UAgentSkill::GetDetails() const +{ + FAgentSkillDetails SkillDetails; + SkillDetails.Instructions = GeneratePrompt(Instructions); // 🔑 调用可重写的生成方法 + for (const auto& Toolset : Toolsets) + { + UClass* ToolsetClass = Toolset.Get(); + FString ToolsetName = FFunctionLibraryToolset::GetToolsetClassName(ToolsetClass); + SkillDetails.Toolsets.Add(ToolsetName); // 转换为字符串形式 + } + return SkillDetails; +} +``` + +**关键点**：`GetDetails` 不是简单返回存储的值，而是通过 `GeneratePrompt(Instructions)` 对指令进行**动态处理**后才返回。这允许子类在运行时注入额外上下文。 + +### GeneratePrompt() — `AgentSkill.h:47` + +```cpp +UFUNCTION(BlueprintNativeEvent) +FString GeneratePrompt(const FString& InitialInstructions) const; + +// 默认实现：原样返回 +virtual FString GeneratePrompt_Implementation(const FString& InitialInstructions) const +{ + return InitialInstructions; +} +``` + +这是一个 **Template Method 模式**的核心。基类提供默认的直通实现，子类通过重写来丰富 prompt。 + +### 子类 Prompt 生成对比 + +**UAgentSkillBestPractices** — 追加编写规范 (`AgentSkill.cpp:42`)： +```cpp +return InitialInstructions + TEXT( + "- Skills should focus on providing essential info the LLM doesn't know...\n" + "- Skills should be written like a brief to a colleague...\n" + "- Shorter skills are more context efficient...\n" + // ... 共6条最佳实践 +); +``` + +**UAgentSkill_NiagaraBase** — 前置 Niagara 知识 (`NiagaraToolset_Info.cpp:128`)： +```cpp +TStringBuilder<16384> PromptBuilder; +PromptBuilder << NiagaraOverview; // ~100 行的 Niagara 概念概述 + +// 遍历依赖的 toolsets，调用 GetToolsetPrompt() 获取其专属提示 +for (const auto& SoftToolset : Toolsets) { + if (UFunction* PromptFunction = ToolsetClass->FindFunctionByName(TEXT("GetToolsetPrompt"))) + PromptBuilder << /* result */; +} + +PromptBuilder << InitialInstructions; // 原始指令放在后面 + +// 附加资产发现信息 +for (const auto& Group : AssetDiscoveryGroups) + PromptBuilder << Group.Description << Group.Paths; +``` + +**UAgentSkillCustomPrompt**（测试）— 后缀追加 (`AgentSkillsTest.h:17`)： +```cpp +return InitialInstructions + FString(TEXT("BishBosh")); // 测试验证用 +``` + +## UAgentSkillToolset — MCP CRUD 操作 + +这是暴露给 AI 的 4 个工具： + +### ListSkills() — `AgentSkill.cpp:53` +- 通过 `UToolsetLibrary::GetDerivedClasses(UAgentSkill::StaticClass())` 发现所有派生类（包括 C++ 和 Blueprint） +- 加载每个类的 CDO，收集 `Description` +- 返回 `TMap` — **路径 → 描述** + +### GetSkills(SkillPaths) — `AgentSkill.cpp:76` +- 按路径列表批量加载 UAgentSkill 类 +- 调用 `GetDetails()` 获取经过 prompt 生成的详细信息 +- 返回 `TMap` — **路径 → 详情** + +### CreateSkill(...) — `AgentSkill.cpp:94` +完整流程： +1. 校验 `FolderPath` 和 `AssetName` +2. 使用 `UBlueprintFactory` 以 `UAgentSkill` 为父类创建 Blueprint 资产 +3. 调用 `UpdateSkill` 设置描述、指令和工具集依赖 +4. 如果 UpdateSkill 失败，回滚删除已创建的 Blueprint +5. 返回生成的类路径（如 `/Game/Skills/MySkill.MySkill_C`） + +### UpdateSkill(...) — `AgentSkill.cpp:139` +1. 加载并校验类必须是 `UAgentSkill` 子类 +2. 通过 `ToolsetRegistrySubsystem->ToolsetRegistry.Find(ToolsetName)` 校验所有依赖的 toolset 名称有效 +3. 更新 `Description`、`Instructions`、`Toolsets` +4. `Modify()` + `MarkPackageDirty()` 标记保存 + +## 测试覆盖 — `AgentSkillsTest.cpp` + +| 测试用例 | 验证内容 | +|---------|---------| +| Can create skills | 创建后 CDO 的 Description/Instructions/Toolsets 正确 | +| Won't create when given bad folder paths | 空路径、空名称、不存在路径均返回空 | +| Can update skills | 更新后 Description/Instructions/Toolsets 正确覆盖 | +| Won't update when class does not exist | 不存在路径返回 false | +| Won't update when class is not a skill | 非 UAgentSkill 类返回 false | +| Won't update when given bad tools | 无效 toolset 名称返回 false，原有属性不变（原子性） | +| List skill summaries | 同时发现 C++ 原生和 BP 派生的 AgentSkill | +| Get skill details | GetDetails 返回内容与原始属性一致 | +| Can't load non-existant skills | 不存在路径返回空 map | +| Can customize prompt generation | 子类重写 GeneratePrompt 确实生效 | + +## 与 ToolsetRegistry 生态的关系 + +``` + ToolsetRegistry (核心注册表) + │ + ┌─────────────┼─────────────┐ + │ │ │ + UToolsetDefinition UAgentSkill FToolset (运行时) + (功能工具集基类) (上下文/技能) (工具集实例) + │ │ + Static AICallable ──────────→ 由 FToolset 包装注册 + UFUNCTIONs 到 ToolsetRegistry + │ + UAgentSkill.Toolsets ──→ 声明依赖关系，告诉系统 + (TSoftClassPtr) 加载 skill 时需同时加载哪些 toolset +``` + +**核心区别**： +- `UToolsetDefinition` 提供**可调用的工具函数**（AICallable UFUNCTIONs） +- `UAgentSkill` 提供**给 AI 的上下文知识**（prompt 增强），并声明"使用我时需要哪些 toolset" +- 加载一个 skill 时，系统会根据其 `Toolsets` 字段自动加载对应的 functional toolsets + +## 设计模式总结 + +| 模式 | 应用 | |------|------| -| 完全实现的功能工具集 | 13 (含子工具集) | -| 空壳占位符 | 4 | -| 聚合器 | 1 | -| **总 AI 工具数** | **~120+** | -| C++ 实现 | 16 | -| Python 实现 | 1 | -| 纯描述符 | 1 | +| **Template Method** | `GeneratePrompt()` — 基类定义框架，子类丰富内容 | +| **CDO as Template** | Skill 的 Description/Instructions 存在 CDO 中，运行时通过 GetDefaultObject 读取 | +| **Soft Reference** | `TSoftClassPtr` 避免硬加载依赖 | +| **Factory Pattern** | `CreateSkill` 内部使用 `UBlueprintFactory` | +| **DTO** | `FAgentSkillDetails` 作为 AI ↔ 引擎的数据传输对象 | +| **Atomic Update** | `UpdateSkill` 先校验所有 toolset 名称再修改，失败时原有属性不变 | ---- +## 与 Claude Code Skill 系统的类比 -## 六、MCP 运行时实际检测 +| 维度 | UE5.8 UAgentSkill | Claude Code Skill | +|------|-------------------|-------------------| +| **存储方式** | Blueprint 资产 / CDO 属性 | Markdown 文件 | +| **加载机制** | `GetDerivedClasses` + `GetDefaultObject` | 文件系统读取 | +| **prompt 生成** | `GeneratePrompt()` 虚函数动态生成 | 静态 Markdown 内容 | +| **依赖声明** | `Toolsets` 属性显式声明 | 无（skill 间独立） | +| **创建方式** | AI 通过 MCP 工具调用 `CreateSkill` | 文件写入 | +| **分发** | 作为 UE 插件内容分发 | 作为文件/插件分发 | +| **核心目的** | 为 AI 提供领域上下文 + 绑定 toolset | 为 AI 提供任务工作流指引 | -**检测时间**: 2026/06/01 -**连接状态**: 成功 -**协议版本**: 2025-11-25 -**Session ID**: 25ece1cd4985fb91e9041b97c47caa7d - -### 当前注册的工具集（运行时 list_toolsets 结果） - -共 **27 个工具集**已注册并可加载。注意：其中包括来自 `toolset_registry` 核心模块的 Python 工具集，以及部分未在上文 C++ 分析中列出的 Python 工具集。 - -#### 编辑器核心工具集 (ToolsetRegistry.*) -| 工具集 | 说明 | -|--------|------| -| `ToolsetRegistry.EditorAppToolset` | 编辑器状态查询/修改：控制台变量、资产成像、Actor/资产选择、视口相机、内容浏览器导航 | -| `ToolsetRegistry.AgentSkillToolset` | Agent Skill 的列表/读取/创建/更新 | -| `ToolsetRegistry.LogsToolset` | 读取 Unreal 输出日志，控制日志类别详细级别 | - -#### 已实现的功能工具集 (C++ 插件) -| 工具集 | 来源插件 | -|--------|----------| -| `GameFeaturesToolset.GameFeaturesToolset` | GameFeaturesToolset | -| `GASToolsets.GameplayCueToolset` | GASToolsets | -| `GASToolsets.AttributeSetToolset` | GASToolsets | -| `GASToolsets.AbilitySystemInspectorToolset` | GASToolsets | -| `LiveCodingToolset.LiveCodingToolset` | LiveCodingToolset | -| `GameplayTagsToolset.GameplayTagsToolset` | GameplayTagsToolset | -| `NiagaraToolsets.NiagaraToolset_Info` | NiagaraToolsets | -| `NiagaraToolsets.NiagaraToolset_Component` | NiagaraToolsets | -| `NiagaraToolsets.NiagaraToolset_Blueprint` | NiagaraToolsets | -| `NiagaraToolsets.NiagaraToolset_System` | NiagaraToolsets | -| `SlateInspectorToolset.SlateInspectorToolset` | SlateInspectorToolset | -| `UMGToolSet.UMGToolSet` | UMGToolSet | -| `conversation_toolset.toolsets.conversation.ConversationTools` | ConversationToolset (Python 实现) | - -#### 核心工具集 (toolset_registry Python 模块) -| 工具集 | 说明 | -|--------|------| -| `toolset_registry.toolsets.core.actor.ActorTools` | Actor 检查/修改（变换、标签、父子关系、组件）| -| `toolset_registry.toolsets.core.asset.AssetTools` | 资产和文件交互 | -| `toolset_registry.toolsets.core.blueprint.BlueprintTools` | Blueprint 操作 | -| `toolset_registry.toolsets.core.curve_table.CurveTableTools` | CurveTable 创建/编辑 | -| `toolset_registry.toolsets.core.data_asset.DataAssetTools` | DataAsset 操作 | -| `toolset_registry.toolsets.core.data_table.DataTableTools` | DataTable 创建/编辑 | -| `toolset_registry.toolsets.core.material.MaterialTools` | Material 创建/编辑及表达式图 | -| `toolset_registry.toolsets.core.material_instance.MaterialInstanceTools` | MaterialInstanceConstant 创建/修改 | -| `toolset_registry.toolsets.core.object.ObjectTools` | UObject/UClass 属性检查/修改及类发现 | -| `toolset_registry.toolsets.core.primitive.PrimitiveTools` | 图元几何组件添加 | -| `toolset_registry.toolsets.core.scene.SceneTools` | 关卡加载/放置/移除/相机/Outliner | -| `toolset_registry.toolsets.core.skeletal_mesh.SkeletalMeshTools` | 骨骼网格检查/修改 | -| `toolset_registry.toolsets.core.static_mesh.StaticMeshTools` | 静态网格检查/修改 | -| `toolset_registry.toolsets.core.string_table.StringTableTools` | StringTable 创建/编辑 | -| `toolset_registry.toolsets.core.programmatic.ProgrammaticToolset` | 沙盒 Python 脚本执行，可调用其他工具 | -| `toolset_registry.toolsets.core.texture.TextureTools` | Texture 资产操作 | - -### 重要发现 - -1. **ConversationToolset 实际有 Python 实现**: 注册为 `conversation_toolset.toolsets.conversation.ConversationTools`，用于检查 Conversation Graph 对话资产，而非纯空壳 -2. **toolset_registry 包含 16 个核心工具集**: 这些是 Python 实现的，不在 C++ 插件目录中，由 `toolset_registry` 插件自带的 Python 模块提供 -3. **运行时工具集总数**: 27 个（远多于分析目录中看到的 C++ 工具集数量） -4. **加载机制**: 使用 `load_toolset` 按需加载，工具在下一个 turn 生效（不是同一响应中）