unity-mcp `manage_ui` 工具全解：用 AI 驱动 Unity UI Toolkit（UXML / USS / UIDocument）-平芜编程栈

unity-mcp`manage_ui`工具全解：用 AI 驱动 Unity UI Toolkit（UXML / USS / UIDocument）

【免费下载链接】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

导读

本文围绕 unity-mcp 的manage_ui工具展开，讲解如何让 AI 助手直接读取、创建、修改和删除 Unity UI Toolkit 的 UXML 文档、USS 样式表与 UIDocument 组件，并能对界面视觉树进行运行时检查与截图自评。读完本文，你将掌握manage_ui的全部 14 种 action 的用法、参数语义与调用限制，并能基于仓库源码理解其路径校验、内容编码、UXML 预校验等底层机制，直接在自己的 Unity 项目中搭建「AI 驱动的前端式 UI 工作流」。

manage_ui定义于 Python 工具注册文件，其 Unity 侧实现位于 ManageUI.cs，工具分组为ui，默认在 tool-groups 中属于可开关的工具组。从源码看，它同时覆盖了「文件操作」「组件挂载」「运行时修改」「视觉截图」四类能力，是 Unity MCP 中处理 UI Toolkit 的核心入口。

一、为什么需要`manage_ui`：从「写死 UI」到「对话式建 UI」

Unity 项目中的 UI 通常有两种体系：基于 Canvas 的 uGUI 和现代的UI Toolkit。UI Toolkit 采用接近前端开发的模式——UXML 负责结构（类似 HTML），USS 负责样式（类似 CSS），并通过UIDocument组件挂到场景 GameObject 上渲染。unity-mcp 的manage_ui就是为这套工作流量身定制的桥梁：AI 助手无需手动打开编辑器、拖拽组件，只需按工具约定的参数发起调用，即可在 Unity 编辑器内完成从「创建 UXML 文件」到「挂载到场景」再到「运行时改样式、截图验证」的闭环。

在技能参考文档中，UI Toolkit 场景被明确指向使用manage_ui；而 workflows.md 则进一步强调：对于新项目，UI Toolkit 是首选 UI 体系，manage_ui是其唯一入口。

二、参数总表：一次看懂全部入参

manage_ui的参数覆盖四类用途：文件操作、组件挂载、截图渲染、运行时元素修改。下表汇总全部参数（对应工具签名与参考文档）：

参数	类型	必填	说明
`action`	`Literal`枚举	是	要执行的动作（14 种，见下节）
`path`	`str \\| None`	—	Assets 相对路径，如`Assets/UI/MainMenu.uxml`、`Assets/UI/Styles.uss`；对`render_ui`也可是直接渲染的 UXML 路径（无需场景 GameObject）
`contents`	`str \\| None`	—	文件内容（UXML 或 USS 标记），纯文本，编码自动处理
`target`	`str \\| None`	—	目标 GameObject 名称或路径（`attach_ui_document`/`get_visual_tree`/`render_ui`使用）
`source_asset`	`str \\| None`	—	UXML VisualTreeAsset 路径，如`Assets/UI/MainMenu.uxml`
`panel_settings`	`str \\| None`	—	PanelSettings 资源路径；省略时自动创建默认项
`sort_order`	`int \\| None`	—	UIDocument 排序顺序（默认 0）
`scale_mode`	`Literal`枚举 \| None	—	Panel 缩放模式（`ConstantPixelSize`/`ConstantPhysicalSize`/`ScaleWithScreenSize`）。遗留简写，推荐用`settings`字典
`reference_resolution`	`dict[str, int] \\| None`	—	参考分辨率`{width, height}`。遗留简写，推荐用`settings`字典
`settings`	`dict[str, Any] \\| None`	—	通用 PanelSettings 属性字典（见下节详解）
`max_depth`	`int \\| None`	—	视觉树遍历最大深度（默认 10）
`width`	`int \\| None`	—	渲染宽度像素（默认 1920），用于`render_ui`
`height`	`int \\| None`	—	渲染高度像素（默认 1080），用于`render_ui`
`include_image`	`bool \\| None`	—	是否在响应中内联返回 base64 PNG（默认 false），用于`render_ui`
`max_resolution`	`int \\| None`	—	内联 base64 图片最大分辨率（默认 640），用于`render_ui`
`screenshot_file_name`	`str \\| None`	—	渲染输出自定义文件名（默认自动生成），用于`render_ui`
`output_folder`	`str \\| None`	—	渲染输出目录。项目相对路径（如`Assets/Screenshots`、`Captures`）或项目内绝对路径；覆盖用户的编辑器偏好设置。省略时回退到编辑器偏好，再回退到内置默认`Assets/Screenshots`，用于`render_ui`
`stylesheet`	`str \\| None`	—	要链接的 USS 样式表路径，如`Assets/UI/Styles.uss`，用于`link_stylesheet`
`filter_type`	`str \\| None`	—	按类型过滤 UI 资源：`uxml`、`uss`、`PanelSettings`，或省略表示全部，用于`list`
`page_size`	`int \\| None`	—	每页结果数（默认 50），用于`list`
`page_number`	`int \\| None`	—	页码，从 1 开始（默认 1），用于`list`
`element_name`	`str \\| None`	—	要修改的视觉元素名称（UXML 中的`name`属性），用于`modify_visual_element`
`text`	`str \\| None`	—	Label / Button 元素的新文本内容，用于`modify_visual_element`
`add_classes`	`list[str] \\| None`	—	要添加到元素的 USS class 名称，用于`modify_visual_element`
`remove_classes`	`list[str] \\| None`	—	要从元素移除的 USS class 名称，用于`modify_visual_element`
`toggle_classes`	`list[str] \\| None`	—	要在元素上切换的 USS class 名称，用于`modify_visual_element`
`style`	`dict[str, Any] \\| None`	—	要设置的内联样式，如`{'backgroundColor': '#FF0000', 'fontSize': 24}`，用于`modify_visual_element`
`enabled`	`bool \\| None`	—	设置元素启用/禁用状态，用于`modify_visual_element`
`visible`	`bool \\| None`	—	设置元素可见性（`display: flex/none`），用于`modify_visual_element`
`tooltip`	`str \\| None`	—	设置元素 tooltip 文本，用于`modify_visual_element`

返回值：一个dict，包含 Unity 的响应。具体结构随 action 不同而变化，下文逐一说明。

三、14 种 action 逐一拆解

3.1`ping`：连通性检查

返回pong，附带tool: "manage_ui"标识，用于确认 Unity 侧工具已正确注册。Unity 侧实现见 ManageUI.cs。

3.2 文件操作：`create`/`read`/`update`/`delete`

这四个 action 负责.uxml与.uss文件的生命周期，源码层面存在一套严格的双层校验：

Python 侧前置校验（manage_ui.py）：路径必须位于Assets/下、不允许..路径穿越、扩展名必须是.uxml或.uss。对应集成测试见 test_manage_ui.py。
Unity 侧写入校验（ManageUI.cs）：
- 写入前对 UXML 做 XML 合法性解析（ValidateUxmlContent），解析失败则拒绝写盘并返回带行列号的错误；校验通过后还会自动注入editor-extension-mode="False"属性（EnsureEditorExtensionMode），保证文件能被 UI Builder 正常打开；
- 文件使用UTF-8 无 BOM编码写入（Utf8NoBom）——Unity 6 的 UI Builder 无法打开带 BOM 的 UXML；
- 写盘后通过AssetDatabase.ImportAsset(path, ImportAssetOptions.ForceUpdate)强制导入，并尝试加载为VisualTreeAsset做导入后验证，解析失败时以 warning 形式提示。
- create时若文件已存在会报错，提示改用update覆盖；update时若文件不存在会提示先用create。

内容编码细节：create/update的contents在传输前会被 base64 编码为encodedContents并置contentsEncoded=true（manage_ui.py），测试中明确断言原始contents不会出现在参数里（test_manage_ui.py）；read的响应同样以 base64 返回，Python 侧收到后自动解码还原为明文contents字段（manage_ui.py）。

调用示例：

# 创建 UXML（结构） manage_ui( action="create", path="Assets/UI/MainMenu.uxml", contents='''<ui:UXML xmlns:ui="UnityEngine.UIElements"> <ui:Label text="Hello World" /> </ui:UXML>''' ) # 读取现有文件（响应中 contents 为解码后的明文） result = manage_ui(action="read", path="Assets/UI/MainMenu.uss") # 更新文件 manage_ui( action="update", path="Assets/UI/MainMenu.uss", contents=".title { font-size: 64px; color: yellow; }" ) # 删除资源（通过 AssetDatabase，删除失败有兜底 File.Delete） manage_ui(action="delete", path="Assets/UI/OldPanel.uxml")

注意：create传入非法扩展名（如.cs）会直接返回错误「Invalid file extension… Must be .uxml or .uss.」，这部分逻辑由 Python 侧与 Unity 侧各自实现、双重把关。

3.3`link_stylesheet`：给 UXML 挂上 USS

该 action 在 UXML 根节点<ui:UXML>起始标签之后插入一行<ui:Style src="project://database/Assets/UI/Styles.uss" />（实现见 ManageUI.cs）。细节：

会先检查是否已存在相同链接（同时匹配src="..."与src="project://database/..."两种写法），重复调用幂等返回alreadyLinked=true；
插入点查找FindUxmlBodyStart会跳过 XML 注释中的伪匹配，且根节点若为自闭合标签则拒绝插入；
若 UXML 中已有<ui:Style>或<Style>引用，此 action 主要用于「结构上补挂样式表」，例如在工作流第 1~4 步中把新建的 USS 挂进新建的 UXML。

3.4`attach_ui_document`/`detach_ui_document`：挂载与卸载

attach_ui_document完成三件事（ManageUI.cs）：

通过ObjectResolver.Resolve按名称/路径查找目标 GameObject（找不到报错）；
加载source_asset指定的VisualTreeAsset（找不到报错）；
解析 PanelSettings：显式传入panel_settings则加载该资源；否则先全局查找现有t:PanelSettings，找不到就在Assets/UI/DefaultPanelSettings.asset自动创建默认项；
用Undo记录操作后，为 GameObject 添加（或复用）UIDocument组件，设置visualTreeAsset、panelSettings、sortingOrder。

示例（完整建 UI 屏幕，出自 workflows.md）：

# 1. 创建 UXML（结构） manage_ui( action="create", path="Assets/UI/MainMenu.uxml", contents='''<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements"> <ui:Style src="Assets/UI/MainMenu.uss" /> <ui:VisualElement name="root" class="root-container"> <ui:Label text="My Game" class="title" /> <ui:Button text="Play" name="play-btn" class="menu-button" /> <ui:Button text="Settings" name="settings-btn" class="menu-button" /> <ui:Button text="Quit" name="quit-btn" class="menu-button" /> </ui:VisualElement> </ui:UXML>''' ) # 2. 创建 USS（样式） manage_ui( action="create", path="Assets/UI/MainMenu.uss", contents='''.root-container { flex-grow: 1; justify-content: center; align-items: center; background-color: rgba(0, 0, 0, 0.8); } .title { font-size: 48px; color: white; -unity-font-style: bold; margin-bottom: 40px; } .menu-button { width: 300px; height: 60px; font-size: 24px; margin: 8px; background-color: rgb(50, 120, 200); color: white; border-radius: 8px; } .menu-button:hover { background-color: rgb(70, 140, 220); }''' ) # 3. 创建 GameObject 并挂载 UIDocument（panel_settings 省略时自动创建） manage_gameobject(action="create", name="UIRoot") manage_ui( action="attach_ui_document", target="UIRoot", source_asset="Assets/UI/MainMenu.uxml" ) # 4. 验证视觉树 manage_ui(action="get_visual_tree", target="UIRoot", max_depth=5)

detach_ui_document则查找目标 GameObject 上的UIDocument组件，通过Undo.DestroyObjectImmediate移除并返回被移除的sourceAsset路径（ManageUI.cs）。目标上没有 UIDocument 时会明确报错。

3.5`create_panel_settings`/`update_panel_settings`：PanelSettings 资产

PanelSettings 控制 UI 面板如何渲染（缩放、DPI、清屏、动态图集等）。create_panel_settings的路径支持.asset自动补全（传入Assets/UI/MyPanel会自动补成.asset），已存在则报错；update_panel_settings则要求settings字典至少含一个可识别属性，否则报错「No recognised properties were applied. Check the key names.」（ManageUI.cs）。

settings字典支持的键（工具签名与 ApplyPanelSettingsProperties 实现完全一致）：

键	取值/结构	说明
`scaleMode`	`ConstantPixelSize`\|`ConstantPhysicalSize`\|`ScaleWithScreenSize`	缩放模式
`referenceResolution`	`{width, height}`	参考分辨率
`screenMatchMode`	`MatchWidthOrHeight`\|`ShrinkToFit`\|`ExpandToFill`	屏幕匹配模式
`match`	0–1 浮点	宽高匹配权重（实现中会`Mathf.Clamp01`钳制）
`referenceDpi`/`fallbackDpi`	浮点	参考/回退 DPI
`sortingOrder`	整数	排序顺序
`targetDisplay`	整数	目标显示器
`clearColor`	布尔	是否清屏颜色
`colorClearValue`	`#RRGGBB`或`{r,g,b,a}`	清屏颜色值
`clearDepthStencil`	布尔	是否清理深度模板
`themeStyleSheet`	资源路径	主题样式表（需能加载为`ThemeStyleSheet`）
`dynamicAtlasSettings`	`{minAtlasSize, maxAtlasSize, maxSubTextureSize, activeFilters}`	动态图集设置

两个额外实现细节：

键名匹配是大小写与下划线不敏感的：scale_mode、scaleMode、ScaleMode都会命中同一个scalemode分支（NormalizeKey去下划线并小写）；
未识别的键会被静默忽略（不影响已识别键生效），所以在update_panel_settings中「一个属性都没生效」时才会报错。

遗留简写：scale_mode与reference_resolution两个顶层参数仍被支持（见 test_manage_ui.py 的断言），但当传入settings字典时，字典优先、简写被跳过。

示例：

# 创建 ScaleWithScreenSize 面板 manage_ui( action="create_panel_settings", path="Assets/UI/GamePanelSettings.asset", scale_mode="ScaleWithScreenSize", reference_resolution={"width": 1920, "height": 1080} ) # 或推荐写法：用 settings 字典一次性配置 manage_ui( action="create_panel_settings", path="Assets/UI/GamePanelSettings.asset", settings={ "scaleMode": "ScaleWithScreenSize", "referenceResolution": {"width": 1920, "height": 1080}, "screenMatchMode": "MatchWidthOrHeight", "match": 0.5, "colorClearValue": "#000000" } ) # 挂载时指定自定义 PanelSettings manage_ui( action="attach_ui_document", target="UIRoot", source_asset="Assets/UI/MainMenu.uxml", panel_settings="Assets/UI/GamePanelSettings.asset" )

3.6`get_visual_tree`：检查运行时视觉树

对目标 GameObject 上的 UIDocument 视觉树做深度优先序列化（ManageUI.cs）：

返回每个节点的type（C# 类型名）、name、classes、text（TextElement 才有）、以及resolvedStyle（含 width、height、color、backgroundColor、fontSize，非默认值才输出，颜色为#RRGGBBAA十六进制）；
max_depth控制遍历深度（默认 10），超过深度时以childCount+truncated: true截断提示；
若目标没有 UIDocument 或视觉树尚未构建，返回明确的错误/空树提示。

这是 AI 确认「UI 到底长什么样」的关键动作——先get_visual_tree拿到结构，再据此modify_visual_element。

3.7`modify_visual_element`：运行时改元素

按element_name（UXML 的name属性）在视觉树中用root.Q(elementName)查找元素并就地修改（ManageUI.cs）。支持的修改项：

文本：text（仅 Label/Button 等TextElement支持，其他元素报错）；
class 操作：add_classes（去重后添加）、remove_classes、toggle_classes；
内联样式：style字典，支持backgroundColor/background-color、color、fontSize/font-size、width、height、opacity、display、visibility、flexGrow/flex-grow、flexShrink/flex-shrink、四边margin*、四边padding*、borderRadius/border-radius（四角统一设置）。未知样式键不会让调用失败，而是记入skipped列表并提示（见 ApplyInlineStyles）；
状态：enabled（SetEnabled）、visible（映射为display: Flex/None）、tooltip。

响应中返回modifications（实际生效项列表）、currentClasses、elementType；若没有任何修改项生效会返回错误并给出可用参数提示。此 action 是「AI 实时调 UI」的核心：无需改文件、无需重新导入，立即作用于运行中的视觉树。

manage_ui( action="modify_visual_element", target="UIRoot", element_name="play-btn", text="START", add_classes=["highlight"], toggle_classes=["menu-button"], style={"backgroundColor": "#FF0000", "fontSize": 24}, enabled=True, tooltip="Click to start" )

3.8`render_ui`：截图自评（编辑器与运行模式两套机制）

render_ui把 UI 面板渲染成 PNG 截图，供 AI 自评界面效果。实现位于 ManageUI.cs，其关键约束与行为：

运行模式（Play Mode）：

由于PanelSettings.targetTexture在同一帧内赋值后无法同步读取，工具采用协程两段式截图：第一次调用通过ScreenshotCapturer.Begin排队一帧WaitForEndOfFrame屏幕捕获（含 UI Toolkit 覆盖层），返回pending=true与提示「Call render_ui again to retrieve the rendered image」；第二次调用时取出保存的 PNG，写入文件并返回hasContent=true与图片数据。
同一时间只允许一个捕获在途，重复发起会返回capture_in_progress错误（附retry_after_ms: 100）。

编辑器模式（Editor Mode）：

为 PanelSettings 创建/复用RenderTexture（作为资源保存在Assets/UI/RT_MCP_UI_Render_*.renderTexture，并按s_panelRTs字典按 PanelSettings 实例 ID 缓存），targetTexture赋值后强制重绘；首次赋值当帧内容为空，响应会提示「Call render_ui again to capture the rendered UI」，读取成功后把targetTexture置回 null 恢复屏幕渲染。该模式为尽力而为，可能返回空白图（hasContent=false提示「no visible content detected」）。
不传target时，可通过path传 UXML 路径直接渲染（工具内部创建隐藏临时 GameObject__MCP_UI_Render_Temp__挂载 UIDocument，用完后销毁）。

通用输出行为：

分辨率由width（默认 1920）/height（默认 1080）控制；
输出目录解析顺序：output_folder参数 → 编辑器偏好（ScreenshotPreferences）→ 内置默认Assets/Screenshots；
文件名默认ui-render-{yyyyMMdd-HHmmss}.png，screenshot_file_name可覆盖（自动补.png），重名自动追加-1、-2后缀；
include_image=true时在响应中内联 base64 PNG，超过max_resolution（默认 640）时先降采样；同时返回path（项目相对路径）、fullPath、width、height、hasContent，命中 Assets 目录时自动AssetDatabase.ImportAsset以便资源管理器可见。

# 第一次调用：排队捕获（Play Mode） result = manage_ui(action="render_ui", target="UIRoot", width=1280, height=720) # -> {"pending": true, "note": "A screen capture was scheduled..."} # 第二次调用：取回 PNG result = manage_ui(action="render_ui", target="UIRoot", width=1280, height=720, include_image=True, max_resolution=480, screenshot_file_name="my-preview", output_folder="Assets/Screenshots") # -> {"path": "Assets/Screenshots/my-preview.png", "hasContent": true, # "imageBase64": "...", "imageWidth": ..., "imageHeight": ...}

3.9`list`：发现 UI 资源

按filter_type（uxml/uss/PanelSettings，或省略全部）与path作用域（默认Assets）搜索资源（ManageUI.cs）：

底层使用AssetDatabase.FindAssets("t:VisualTreeAsset" / "t:StyleSheet" / "t:PanelSettings")；
支持page_size（默认 50）与 1 基page_number分页，响应包含total、pageSize、pageNumber、assets（每项含path、type、name）。

# 列出全部 UI 资产 result = manage_ui(action="list") # 只列 USS，分页查看第 2 页 result = manage_ui(action="list", filter_type="uss", page_size=20, page_number=2)

四、源码级机制：调用路由与安全边界

4.1 读操作与写操作走不同通道

manage_ui在 Python 侧把 action 分为两类（manage_ui.py）：

变更类（mutation）：create、update、delete、attach_ui_document、detach_ui_document、create_panel_settings、update_panel_settings、render_ui、link_stylesheet、modify_visual_element—— 走send_mutation；
只读类：ping、read、get_visual_tree、list—— 走send_with_unity_instance(async_send_command_with_retry, ...)。

集成测试 test_manage_ui.py 专门验证了这种路由：read走非变更路径、create走变更路径，且None参数会被完全剔除，不会进入发送给 Unity 的参数包。

4.2 双端路径校验：防穿越、限 Assets

无论是 Python 侧（os.path.normpath后检查..段、首段必须为assets、扩展名白名单）还是 Unity 侧（AssetPathUtility.SanitizeAssetPath+ValidExtensions），都对path做了严格约束。测试覆盖了「路径在 Assets 之外」「Assets/../etc/passwd.uxml穿越」「非法扩展名」三种场景（test_manage_ui.py）。这意味着 AI 无法通过manage_ui在项目外写入任意文件，安全边界由工具本身强制保证。

4.3 资源生命周期管理

ManageUI类在静态构造时注册了EditorApplication.quitting与AssemblyReloadEvents.beforeAssemblyReload回调，统一清理缓存的所有 RenderTexture（CleanupRenderTextures：释放、按资产路径删除或DestroyImmediate），避免域重载/退出时泄漏（ManageUI.cs）。

五、实战组合拳：一个完整的主菜单制作流程

把上面的能力串起来，一套「AI 从零建主菜单」的完整调用序列（摘自 workflows.md 并补充 render_ui 自评环节）：

# ① 建 UXML 结构（含 ui:Style 前缀的样式引用） manage_ui(action="create", path="Assets/UI/MainMenu.uxml", contents='''<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements"> <ui:Style src="Assets/UI/MainMenu.uss" /> <ui:VisualElement name="root" class="root-container"> <ui:Label text="My Game" class="title" /> <ui:Button text="Play" name="play-btn" class="menu-button" /> <ui:Button text="Settings" name="settings-btn" class="menu-button" /> <ui:Button text="Quit" name="quit-btn" class="menu-button" /> </ui:VisualElement> </ui:UXML>''') # ② 建 USS 样式 manage_ui(action="create", path="Assets/UI/MainMenu.uss", contents='''.root-container { flex-grow: 1; justify-content: center; align-items: center; background-color: rgba(0, 0, 0, 0.8); } .title { font-size: 48px; color: white; -unity-font-style: bold; margin-bottom: 40px; } .menu-button { width: 300px; height: 60px; font-size: 24px; margin: 8px; background-color: rgb(50, 120, 200); color: white; border-radius: 8px; } .menu-button:hover { background-color: rgb(70, 140, 220); }''') # ③ 挂 UIDocument 到场景 GameObject（省略 panel_settings 自动创建默认面板） manage_gameobject(action="create", name="UIRoot") manage_ui(action="attach_ui_document", target="UIRoot", source_asset="Assets/UI/MainMenu.uxml") # ④ 检查视觉树 manage_ui(action="get_visual_tree", target="UIRoot", max_depth=5) # ⑤ 运行时微调：把 Play 按钮文本改掉并高亮 manage_ui(action="modify_visual_element", target="UIRoot", element_name="play-btn", text="START", add_classes=["highlight"]) # ⑥ 截图自评（Play Mode 需调用两次；编辑器模式首次可能空白，重试一次） manage_ui(action="render_ui", target="UIRoot", width=1280, height=720, include_image=True) manage_ui(action="render_ui", target="UIRoot", width=1280, height=720, include_image=True) # ⑦ 收尾：卸载 UIDocument、删除资源 manage_ui(action="detach_ui_document", target="UIRoot") manage_ui(action="delete", path="Assets/UI/MainMenu.uss")

六、常见报错与排查指引

现象	原因与对策
`Invalid file extension '.cs'. Must be .uxml or .uss.`	`create/read/update/delete`只接受`.uxml`/`.uss`，检查`path`扩展名
`path must be under 'Assets/'`/`path must not contain traversal sequences`	路径必须以`Assets/`开头且禁止`..`穿越
`File already exists at ... Use 'update' action to overwrite.`	`create`遇到已存在文件，改用`update`
`File not found: ... Use 'create' action for new files.`	`update`遇到不存在文件，先`create`
`UXML validation failed — file was NOT written. ...`	UXML 是畸形 XML，Unity 侧在写盘前拦截，按行列号修复
`Could not find target GameObject: ...`	`target`名称/路径无法被 ObjectResolver 解析
`GameObject '...' has no UIDocument component.`	目标上未挂`UIDocument`，先`attach_ui_document`
`Visual element with name '...' not found in the visual tree.`	`element_name`与 UXML 中`name`属性不一致，先`get_visual_tree`确认
`Cannot capture: another capture is already in progress.`	Play Mode 下同时只有一个截图在途，稍等（`retry_after_ms: 100`）再调
`No recognised properties were applied. Check the key names.`	`update_panel_settings`的`settings`键全部未识别，对照第三节键表
UI Builder 打不开生成的 UXML	检查是否用了裸`<Style>`（必须`<ui:Style>`）；工具已自动注入`editor-extension-mode`且用 UTF-8 无 BOM 写入，可先排除这两个因素

七、扩展阅读

工具完整签名与自动生成文档：manage_ui 参考文档；
Python 侧定义与参数路由：Server/src/services/tools/manage_ui.py；
Unity 侧 14 种 action 的完整实现：MCPForUnity/Editor/Tools/ManageUI.cs；
参数路由与 base64 编码的集成测试：Server/tests/integration/test_manage_ui.py；
UI 体系选型与完整工作流：unity-mcp-skill/references/workflows.md、unity-mcp-skill/references/tools-reference.md；
工具分组说明：website/docs/guides/tool-groups.md。

综上所述，manage_ui把 UI Toolkit 的「文件、挂载、检查、修改、截图」全链路暴露给 AI：既有前端式的 UXML/USS 文件工作流，也有运行时视觉树检查与元素级修改，还内置了截图自评能力与双端安全校验。结合仓库源码理解其底层实现后，你可以放心地在自动化管线中用它完成 UI 的创建、迭代与回归验证。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

unity-mcp `manage_ui` 工具全解：用 AI 驱动 Unity UI Toolkit（UXML / USS / UIDocument）