unity-mcp 中unity_reflect工具全解析用实时反射校验 Unity C# API告别过时的训练数据【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcpunity_reflect是 unity-mcp 提供的docs工具组核心工具之一它直接对正在运行的 Unity Editor 进行 .NET 反射返回真实的类、方法、属性与字段信息用于在编写 C# 代码前校验 API 是否存在。本文以 工具参考文档 为骨架结合 Python 服务端实现、Unity 端反射实现 与 单元测试系统讲解三种 action 的用法、全部参数与取值、底层反射原理、作用域搜索规则、CLI 命令以及和unity_docs搭配的完整校验工作流。读完后你将能准确使用该工具验证任意 Unity API从根本上减少 AI 助手写代码时的 API 幻觉。为什么需要实时反射而不是依赖模型记忆LLM 的训练数据往往包含错误、过时甚至完全虚构的 Unity API。这在涉及包特定 APIInput System、Cinemachine、ProBuilder、NavMesh、URP/HDRP以及跨 Unity 版本变化的 API 时尤为严重。unity_reflect的价值在于它不依赖任何静态文档或模型记忆而是直接对当前编辑器进程中已加载的程序集执行反射reflection返回正在运行的 Unity 版本的事实真相。该工具在 MCP 服务端被声明为只读工具readOnlyHintTrue、destructiveHintFalse不会对项目产生任何副作用可以放心在写代码前反复调用。它属于docs工具组——在 tool_registry.py 中TOOL_GROUPS[docs]的描述是 Unity API reflection and documentation lookup。注意DEFAULT_ENABLED_GROUPS仅包含core即docs 工具组默认不启用需要通过会话级工具管理manage_toolsmeta-tool或配置启用后才能看到并使用该工具。参数详解unity_reflect的全部参数定义在 unity_reflect.py 中均为可选参数但具体到每种 action 时则有必填项详见下一节参数类型必填说明actionstr是要执行的反射动作get_type、get_member、searchclass_namestr \| None视 action 而定类的完全限定名或简单名如UnityEngine.Transform或Transformmember_namestr \| None视 action 而定要检查的方法、属性或字段名如position、Raycastquerystr \| None视 action 而定类型名搜索关键字用于searchscopestr \| None否search的程序集搜索范围unity、packages、project、all有两个值得注意的实现细节均由源码确认action 大小写不敏感服务端会将action统一转为小写再校验action.lower()测试test_action_case_insensitive验证了Get_Type会被规范化为get_type。所以你可以放心传GET_TYPE或Get_Type。scope 只对 search 生效即使你在get_type调用中传了scope服务端也不会把它写入发送给 Unity 的参数包见 unity_reflect.py 中if action_lower search and scope is not None的条件以及测试test_scope_not_sent_for_get_type。三种 Action 的用法与参数约束服务端在发送命令前会做严格的参数校验unity_reflect.py参数不满足要求时不会请求 Unity而是直接返回success: false与错误消息get_type获取类的成员摘要仅名称对指定类返回方法、属性、字段、事件等成员的名称列表不含签名细节用于快速确认一个类存在哪些可用的 API。必填class_name返回要点found、full_name、namespace、assembly、base_class、interfaces、is_abstract/is_sealed/is_static/is_enum/is_interface、members含methods、properties、fields、events名称数组、extension_methods、obsolete_membersget_member获取单个成员的完整签名对指定类的指定成员返回完整细节包括方法重载列表、每个参数的out/ref/params修饰与默认值、返回类型、泛型参数、是否 static / virtual / abstract、是否标记[Obsolete]及弃用消息、声明类型用于区分继承自基类的成员等。必填class_namemember_name缺失任一参数都会报错get_member requires class_name and member_name.search跨程序集搜索类型名在已加载程序集中按名称搜索类型。匹配优先级为精确匹配exact→ 前缀匹配starts with→ 包含匹配contains按此排序后最多返回25条结果超出时返回truncated: true标志每条包含name、full_name、namespace、assembly以及类型分类标志is_class/is_enum/is_interface/is_struct。必填query可选scope服务端会校验取值必须在VALID_SCOPES [unity, packages, project, all]内否则返回Invalid scope .... Valid scopes: ...。scope 的四种取值及其程序集匹配规则scope 的实际过滤逻辑在 Unity 端的 UnityReflect.csMatchesScope方法中实现判断依据是程序集名称scope匹配规则典型用途unity默认程序集名以UnityEngine、UnityEditor或Unity.开头引擎与编辑器内置 APIpackages排除以System、mscorlib、netstandard开头的程序集包管理器安装的第三方包 APIproject仅匹配Assembly-CSharp、Assembly-CSharp-Editor及Assembly-CSharp-firstpass*/Assembly-CSharp-Editor-firstpass*项目自身脚本all匹配所有程序集全局搜索不传scope时默认unityUnity 端p.Get(scope, unity)且服务端在search未传 scope 时不会把该字段写入参数包测试test_search_default_scope验证了这一点。返回值结构工具返回一个包含 Unity 响应的dict整体形状遵循 unity-mcp 的统一约定成功时通常形如{success: true, data: { ... }}data的具体字段取决于 action见上文各 action 返回要点参数校验失败、action 未知或 Unity 端出错时返回{success: false, message: ...}特殊兜底若 Unity 返回的不是 dict例如异常字符串服务端会将其包装为{success: false, message: str(result)}unity_reflect.py对应测试test_non_dict_response_wrapped。Unity 端实现原理缓存、歧义处理与泛型安全unity_reflect的反射能力实现在 MCPForUnity/Editor/Tools/UnityReflect.cs工具声明为[McpForUnityTool(unity_reflect, AutoRegister false, Group docs)]。理解其内部机制有助于你更好地使用它程序集类型缓存与失效工具使用_assemblyTypeCacheDictionarystring, Type[]缓存每个已加载程序集的导出类型避免每次调用都执行昂贵的GetExportedTypes()通过AssemblyReloadEvents.afterAssemblyReload在程序集重载domain reload后自动清空缓存保证反射结果始终反映最新编译的代码UnityReflect.cs扩展方法结果也有独立缓存ExtensionMethodCache。编译期间拒绝反射HandleCommand入口处首先检查EditorStateCache.GetActualIsCompiling()若 Unity 正在编译会直接返回错误Cannot reflect while Unity is compiling. Wait for domain reload to complete.——因为此时程序集处于不一致状态反射结果不可信。简单名的歧义检测当class_name是不带命名空间的简单名如Button时Unity 端会先扫描所有程序集统计同名类型FindAllTypesByShortName。若存在多个匹配例如UnityEngine.UI.Button与UnityEngine.Experimental.UI.Button会返回{ found: true, ambiguous: true, matches: [UnityEngine.UI.Button, ...], hint: Use the fully qualified name (e.g., UnityEngine.UI.Button) to disambiguate. }此时应当改用完全限定名重新查询。get_type与get_member都有该歧义检测逻辑。类型解析与泛型名称规范化类型解析优先使用共享的UnityTypeResolver带缓存、命名空间前缀、player-over-editor 优先级与TypeCache回退解析失败后再回退到内置的NamespacePrefixes前缀列表覆盖UnityEngine.、UnityEditor.、Unity.Cinemachine.、UnityEngine.InputSystem.、UnityEngine.ProBuilder.、UnityEngine.Rendering.Universal./.HighDefinition.、UnityEngine.AI.等 16 个常用命名空间逐前缀匹配。泛型名会被规范化ListT→List1、DictionaryK,V→Dictionary2NormalizeGenericName因此你可以直接用Listint这类 C# 语法书写类名。返回时又会把List1反向格式化为友好的List形式FormatTypeName同时把System.Int32等显示为int、float、bool等 C# 关键字FriendlyTypeNames 映射。开放泛型类型的安全防护对开放泛型类型定义如List做成员反射在 Unity 2021.3 的 Mono 下可能触发mono_metadata_generic_param_equal_internal段错误因此实现中对IsGenericTypeDefinition的类型只返回最小安全信息名称、程序集、is_generic_type_definition: true并提示Open generic type — consult docs for member details。附加能力扩展方法与过时成员检测get_type会额外列出扩展方法名extension_methods通过扫描UnityEngine/UnityEditor/Unity.程序集中标记[ExtensionAttribute]的静态类匹配首参类型兼容性得出——这对发现像transform.SetPositionAndRotation这类看起来不像成员的 API 很有帮助。get_type与get_member都会识别[Obsolete]标记前者汇总obsolete_members名称数组后者在成员详情中给出is_obsolete与obsolete_message帮你避开即将移除的 API。命令行用法unity-mcp reflect除通过 MCP 协议调用外该功能还暴露为 CLI 子命令实现在 Server/src/cli/commands/reflect.py便于本地快速验证# 获取类型成员摘要对应 actionget_type unity-mcp reflect type NavMeshAgent unity-mcp reflect type UnityEngine.Physics # 获取成员完整签名对应 actionget_member unity-mcp reflect member Physics Raycast unity-mcp reflect member NavMeshAgent SetDestination # 搜索类型对应 actionsearch默认 scopeunity unity-mcp reflect search NavMesh unity-mcp reflect search Camera --scope all unity-mcp reflect search MyScript --scope projectsearch的--scope/-s选项限定在unity、packages、project、all四个取值内与 MCP 参数保持一致。该子命令在 CLI 参考文档 中登记为mcp-for-unity reflect功能描述为 Inspect Unity APIs via reflection。与unity_docs搭配的完整校验工作流unity_reflect解决API 是否存在、签名是什么而官方文档抓取工具unity_docs解决这个 API 怎么用、有什么坑。系统提示词Server/src/main.py为 AI 助手规定了官方推荐流程unity_reflect search—— 搜索类型名确认类存在于当前版本unity_reflect get_type—— 获取类的成员名称摘要unity_reflect get_member—— 获取目标成员的完整签名细节unity_docs get_doc——如需用法示例与注意事项抓取官方 ScriptReference 文档。unity_docs的工具描述中也明确说明其定位Use after unity_reflect confirms a type exists, to get usage patterns, gotchas, and code examples before writing implementation code反之若get_doc404其建议也是Try unity_reflect search action to verify the type name。两者互为补充、形成闭环。该能力在 v10 迁移文档 中被列为 v10 的重要新增Addsunity_docsandunity_reflect用于替代此前依赖外部文档或本地项目检查的 API 发现方式。错误处理与边界情况速查结合服务端校验逻辑与 测试用例以下边界情况均有明确行为场景行为action为未知值返回success: false消息列出合法动作Unknown action x. Valid actions: get_type, get_member, searchget_type缺class_nameget_type requires class_name.不请求 Unityget_member缺任一必填参数分别提示class_name或member_name缺失search缺querysearch requires query.scope非法Invalid scope x. Valid scopes: unity, packages, project, all类型不存在返回success: true但data.found: falsequery原样回显成员不存在返回success: true但data.found: false附type_name与member_nameUnity 返回非 dict包装为{success: false, message: 原始内容}Unity 正在编译Cannot reflect while Unity is compiling. Wait for domain reload to complete.简单名有歧义返回ambiguous: true与全部候选完全限定名提示使用全名开放泛型类型只返回最小安全信息is_generic_type_definition: true典型实战场景场景一写 C# 前确认 API 存在。模型想用NavMeshAgent.SetDestination()但不确定方法名先search(queryNavMeshAgent)确认类名再get_member(class_nameNavMeshAgent, member_nameSetDestination)拿到完整签名与重载。场景二区分同名类型。直接get_type(class_nameButton)返回ambiguous: true与候选列表按提示改用class_nameUnityEngine.UI.Button。场景三检查包特定 API 与弃用风险。用search(queryCinemachine, scopepackages)或scopeall查找包类型get_type返回的obsolete_members与get_member返回的obsolete_message可提前发现已标记弃用的成员。场景四搜项目自己的脚本。search(queryGameManager, scopeproject)只匹配Assembly-CSharp系列程序集快速定位项目自定义类型。小结unity_reflect以对当前 Unity 进程实时反射的方式为 AI 助手提供了最可靠的 Unity API 事实来源。它通过服务端参数校验unity_reflect.py、Unity 端的类型缓存与歧义/泛型/过时/扩展方法处理UnityReflect.cs、CLI 命令reflect.py以及完善的测试覆盖test_unity_reflect.py与unity_docs共同构成了先反射验证、再查文档、最后写代码的 API 校验闭环。需要提醒的是该工具属于默认关闭的docs工具组使用前请确认已在会话中启用该组。【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考