unity-uitoolkit

**调用此模块中的任何技能之前：**如果你准备根据技能名称或描述猜测参数后调用技能，请停止——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其 schema）。如果你已经从 recommend/schema 获取参数定义，则可以直接进行 dryRun。

触发条件

• 使用 UI Toolkit 编写运行时或编辑器 UI
• 编写 USS/UXML
• 接入 UIDocument
• 将 UI 绑定到数据
• 构建世界空间 UI
• 用 UI Toolkit 编写运行时或编辑器 UI、编写 USS/UXML、接入 UIDocument、把 UI 绑定到数据源、做世界空间 UI

Unity UI Toolkit 技能

此模块仅用于 Unity UI Toolkit：使用 UXML 定义结构、使用 USS 设置样式、使用 UIDocument 挂接场景，以及使用 PanelSettings 进行运行时渲染。

需要 Unity 2022.3+。不要将此模块与 ui_* UGUI/Canvas 技能混用。 本地化：可见 UI 文本应与用户使用的语言一致。中文对话 -> 中文标签/占位符/按钮文本。USS 类名和 CSS 变量保持英文。

操作模式

• Approval：查询类 skill（uitk_read_file / uitk_find_files / uitk_get_panel_settings / uitk_list_documents / uitk_inspect_uxml / uitk_list_uss_variables / uitk_inspect_document / uitk_runtime_binding_list / uitk_worldspace_panel_get / uitk_element_reference_get，源码标 SkillMode.SemiAuto）直接执行；其余文件/场景写入类（uitk_create_* / uitk_write_file / uitk_add_* / uitk_modify_element / uitk_runtime_binding_add / uitk_uxml_upgrade / uitk_worldspace_panel_create 等，标 SkillMode.FullAuto）需用户授权，授权后由服务端一步执行并返回结果。
• Auto / Bypass：未被禁止列表拦截的 skill 直接执行。
• 本模块含有 Delete 类 skill：uitk_delete_file、uitk_remove_element、uitk_remove_uss_rule 标记为 SkillOperation.Delete，会被 IsForbiddenInSemi 静态拦截 —— 仅 Bypass 模式或加入 Allowlist 后才能调用。
• 本模块还含有 2 个域重载类 skill：uitk_create_editor_window 与 uitk_create_runtime_ui 会生成 .cs 文件，必然触发域重载，因此标记为 MayTriggerReload = true。IsForbiddenInSemi 会直接读取此 flag，因此它们和上面的 Delete 类一样会被静态拦截 —— 在 Approval 与 Auto 下都会返回 MODE_FORBIDDEN，这并非“需要授权”，授权也无法解决，仅 Bypass 或命中 Allowlist 才能调用。这两个是上面第一条“其余写入类需用户授权”的例外。
• 同一个 flag 还有第二个后果：?mode=transactional 的批量链中如果包含这两个步骤，会在执行前被 400 拒绝，错误信息会指出违规的 steps[i]。原因是域重载会清空编辑器 undo 栈，事务批量的回滚承诺无法兑现，因此服务端选择预先拒绝，而不是事后失败。要在事务批量流程中生成脚本，请将这两步拆开单独调用。
• 资源重导行为：所有写文件/删文件 skill 都会通过 AssetDatabase.ImportAsset(path) 单独触发单个 USS/UXML 资产的导入，不会调用 AssetDatabase.Refresh() 触发全项目扫描；批量创建时也会依次单独 Import。但 USS/UXML 属于 ScriptedImporter 类型，Import 仍会重建依赖此资产的 PanelSettings/UIDocument 引用，并触发 IMGUI 检查器刷新和场景视图重绘。

不要（常见臆造）：

• 不存在 uitoolkit_create_button / uitoolkit_create_label -> 请使用 uitk_add_element
• 不存在 uitoolkit_set_style -> 请使用 uitk_add_uss_rule、uitk_remove_uss_rule 或 uitk_modify_element
• 不存在 uitoolkit_create_canvas -> UI Toolkit 使用 UIDocument，而非 Canvas
• uitk_* 和 ui_* 是不同的系统。不要将 UI Toolkit 的结构/样式假设混用到 UGUI 工作流中
• USS 并非完整的 CSS。不支持 display:grid、box-shadow、calc()、@media、::before、z-index 和渐变
• binding-path（用于 uitk_add_element / uitk_modify_element）是旧版 SerializedObject 编辑器绑定。它不是运行时数据绑定 -> 运行时数据绑定请使用 uitk_runtime_binding_add
• 不要通过 component_add 添加 PanelRenderer；它需要世界空间设置 -> 请使用 uitk_worldspace_panel_create

路由：

• 对于 UGUI Canvas/Button/Text/Image -> 使用 ui 模块
• 对于 XR 世界空间 Canvas 转换 -> 使用 xr_setup_ui_canvas
• 对于生成入门布局 -> 使用 uitk_create_from_template
• 对于将现有 UXML 挂接到场景对象 -> 使用 uitk_create_document 或 uitk_set_document

技能

文件技能

技能	用途	关键参数
uitk_create_uss	创建 USS 文件	savePath、content?
uitk_create_uxml	创建 UXML 文件	savePath、content?、ussPath?
uitk_read_file	读取 USS/UXML 内容	filePath
uitk_write_file	覆盖 USS/UXML 内容	filePath（必须以 .uss 或 .uxml 结尾）、content
uitk_delete_file	删除 USS/UXML 文件	filePath
uitk_find_files	按名称/路径搜索文件	type?、folder?、filter?、limit?
uitk_create_batch	一次调用创建 2 个或更多文件	items

uitk_write_file 不是通用文件写入工具。 filePath 必须以 .uss 或 .uxml 结尾（不区分大小写）。其他任何扩展名（包括没有扩展名）都会被拒绝，并返回 SEMANTIC_INVALID、validValues: [".uss", ".uxml"]，以及指向 script_create 的 relatedSkills。检查会在创建目标目录之前运行，因此被拒绝的调用不会留下文件或多余目录。不要用它来写入 .cs 文件：请使用 script_create，它会正确声明写入脚本所导致的域重新加载。

场景技能

技能	用途	关键参数
uitk_create_document	创建 UIDocument GameObject	name、uxmlPath?、panelSettingsPath?、sortOrder?、parentName?/parentInstanceId?/parentPath?
uitk_set_document	更改 UIDocument 资源绑定	name/instanceId、uxmlPath?、panelSettingsPath?
uitk_create_panel_settings	创建 PanelSettings 资源	savePath、scaleMode、referenceResolutionX/Y、Unity 6 世界空间选项
uitk_get_panel_settings	读取 PanelSettings 值	assetPath
uitk_set_panel_settings	有选择地更新 PanelSettings	assetPath，仅包含已更改的字段
uitk_list_documents	列出场景中的 UIDocument	无
uitk_inspect_document	检查实时 VisualElement 树	name/instanceId/path、depth

受版本限制的 PanelSettings 参数——按名称拒绝，绝不静默丢弃。 对于 uitk_create_panel_settings 和 uitk_set_panel_settings，renderMode、forceGammaRendering、bindingLogLevel、colliderUpdateMode、colliderIsTrigger 和 vertexBudget 要求使用 Unity 6.0+，而 textureSlotCount 要求使用 Unity 6000.3+。在较旧的编辑器中传入这些参数之一时，会返回指出该参数名称的 SEMANTIC_INVALID，而不是忽略它。因此，传入的值要么已生效，要么会作为错误返回，绝不会被悄悄丢弃。这两个技能还会在首次写入前解析所有枚举和资源路径，因此被拒绝的调用不会改变资源的任何字节；无需清理部分应用的更改。

UXML 结构技能

技能	用途	关键参数
uitk_add_element	添加子元素	filePath、elementType、parentName?、elementName?、text?、classes?
uitk_remove_element	按 name 移除元素	filePath、elementName
uitk_modify_element	更改属性/类/文本	filePath、elementName、text?、classes?、style?、newName?、bindingPath?、自定义属性字段
uitk_clone_element	复制元素子树	filePath、elementName、newName?
uitk_inspect_uxml	解析 UXML 层级结构	filePath、depth?

USS 样式技能

技能	用途	关键参数
uitk_add_uss_rule	添加或替换选择器规则	filePath、selector、properties
uitk_remove_uss_rule	移除选择器规则	filePath、selector
uitk_list_uss_variables	检查设计令牌 / var() 用法	filePath

模板和代码生成技能

技能	用途	关键参数
uitk_create_from_template	生成成对的 UXML+USS	template、savePath、name?
uitk_create_editor_window	生成 EditorWindow 脚本	savePath、className、uxmlPath?、ussPath?、menuPath?
uitk_create_runtime_ui	生成运行时 MonoBehaviour 查询脚手架	savePath、className、elementQueries?

支持的入门模板包括 menu、hud、dialog、settings、inventory、list、tab-view、toolbar、card 和 notification。

Unity 6 技能（受版本限制）

这些技能会调用并非所有受支持编辑器都具备的 API。每项技能都会先检查正在运行的编辑器，并返回包含 requiredUnityVersion 和 currentUnityVersion 的结构化 SEMANTIC_INVALID 错误，而不是以不透明的方式失败。调用前请先查看最低版本要求。

技能	最低 Unity 版本	用途	关键参数
uitk_runtime_binding_add	6000.0	在 UXML 元素上添加/更新 <DataBinding>	filePath、elementName、property、bindingMode?、dataSource?、dataSourcePath?、extraAttributes?
uitk_runtime_binding_list	无（只读）	列出 UXML 文件中声明的绑定和数据源	filePath
uitk_uxml_upgrade	6000.3（并非所有版本都支持——见下文）	对资源运行已注册的 UXML 升级器	filePath?、folder?、upgraderNames?、listOnly?、limit?
uitk_worldspace_panel_create	6000.2	创建世界空间 UI 面板 GameObject	name、uxmlPath?、panelSettingsPath?、sizeMode?、worldSpaceSizeX/Y?、pivot?、pivotReferenceSize?、setPanelRenderMode?
uitk_worldspace_panel_get	6000.2	读取世界空间面板的配置	name/instanceId/path
uitk_element_reference_get	无（只读）	列出 authoring-id 值和嵌套的 authoring-id 路径	filePath、maxTemplateDepth?

运行时数据绑定

uitk_runtime_binding_add 会将绑定写入 UXML 资源，因此绑定会保留下来——它不是仅在运行时调用的代码。它生成的标记与 Unity 的 UI Builder 生成的一致：

<engine:Label text="Label" data-source="ExampleObject.asset" data-source-path="simpleLabel">
    <Bindings>
        <engine:DataBinding property="text" binding-mode="ToTarget" />
    </Bindings>
</engine:Label>

• data-source / data-source-path 会写入元素；property / binding-mode 则写入 <DataBinding>。
• bindingMode 会针对 TwoWay、ToSource、ToTarget、ToTargetOnce 进行验证。无效值会在写入前被拒绝，因为错误的 binding-mode 会导致整个 UXML 资源导入失败。
• 对相同的 elementName + property 调用两次会原位更新（响应中的 action 为 added 或 updated），因此可以安全地重复运行。
• extraAttributes 接受 JSON 对象（例如 {"update-trigger":"OnSourceChanged"}），并将其原样写入 <DataBinding> 节点。技能不会对这些属性进行架构验证——错误的属性名称会导致资源导入失败。仅使用已确认的属性。
• 将数据源绑定到 C# 对象，需要在源属性上添加 [CreateProperty]（Unity.Properties）。此技能只写入标记；不会创建或验证数据源类型。

世界空间面板

底层组件因编辑器版本而异，响应中的 component 字段会告诉你使用了哪种组件：

• Unity 6000.5+ — PanelRenderer 组件（UnityEngine.UIElements.PanelRenderer，Renderer 的子类）。
• Unity 6000.2–6000.4 — 设置了世界空间属性的 UIDocument。

两种方式都接受相同的参数。sizeMode 为 Dynamic 或 Fixed（Fixed 使用 worldSpaceSizeX/Y）；pivot 接受 Center、TopLeft、TopCenter、TopRight、LeftCenter、RightCenter、BottomLeft、BottomCenter、BottomRight；pivotReferenceSize 接受 BoundingBox 或 Layout。不支持的值会被拒绝，并返回有效值列表，而不会被静默忽略。

世界空间渲染还需要将关联的 PanelSettings 设为世界空间渲染模式。setPanelRenderMode 默认值为 true，会为你切换该资源（会创建快照，且可撤销）；响应会报告 panelRenderModeSetToWorldSpace。将其设为 false 可保持资源不变。

UXML 升级

uitk_uxml_upgrade 会调用 UnityEditor.UIElements.UxmlUpgradeService。Unity 从 6000.3 起开始介绍该服务，但并非每个 6000.3 版本中都有（6000.3.9f1 未包含该服务），因此该技能通过反射绑定此服务；如果编辑器中没有该服务，则会返回常见的 SEMANTIC_INVALID 拒绝结果——使用 6000.3+ 并不保证此调用一定能运行。首先使用 listOnly=true 调用，以查看此处是否存在该服务，以及注册并启用的升级器有哪些——升级器集合并非固定，第三方软件包也可以注册自己的升级器。然后传入 upgraderNames（逗号分隔）以运行部分升级器，或省略该参数以运行所有已启用的升级器。

响应会通过比较每个资源升级前后的 .uxml 文本，报告其 changed: true/false，以便你判断升级器是否确实重写了文件，而不是想当然地认为它已重写。

核心领域知识

USS 与 CSS

模式	USS 是否支持	操作建议
Flex 布局	是	使用 flex-direction、flex-wrap、align-items、justify-content
border-radius、opacity、overflow:hidden	是	可以安全使用
变换 / 过渡	是	translate、scale、rotate 均可使用
CSS 变量	是	优先使用 :root 令牌
display:grid / display:block / display:inline	否	所有布局都是 flex；使用换行的行来模拟网格
box-shadow	否	使用嵌套的背景元素模拟
linear-gradient() / radial-gradient()	否	使用图像纹理
calc() / @media	否	使用明确的值和 PanelSettings.scaleMode
::before / ::after	否	添加实际的子 VisualElement
z-index	否	后面的同级元素会渲染在上层

常见 USS 变通方案

需求	兼容 USS 的变通方案
阴影	在内容后方添加额外的子 VisualElement
响应式缩放	PanelSettings.scaleMode = ScaleWithScreenSize
网格卡片	flex-direction: row + flex-wrap: wrap + 子元素宽度
圆形头像	宽度和高度相等 + 半径为尺寸的一半 + overflow:hidden
伪元素装饰	添加额外的绝对定位子元素

高频参数

技能	通常首先需要的参数
uitk_create_panel_settings	savePath、scaleMode、referenceResolutionX、referenceResolutionY
uitk_create_document	name、uxmlPath、panelSettingsPath、sortOrder?
uitk_add_element	filePath、elementType、parentName?、elementName?、text?、classes?
uitk_modify_element	filePath、elementName、仅填写已更改的属性
uitk_add_uss_rule	filePath、selector、properties

PanelSettings 选项

• ScaleWithScreenSize：运行时 HUD/菜单 UI 的默认选项
• ConstantPixelSize：需要严格像素映射时使用
• ConstantPhysicalSize：较少使用；仅用于需要按物理尺寸显示 UI 的情况

对于世界空间（3D）UI（Unity 6000.2+），请先配置 PanelSettings，然后使用 uitk_worldspace_panel_create 创建场景对象，而不是使用 uitk_create_document。

文件和结构规则

• 优先使用一个 UXML 根文件，并通过 <Style src="..."/> 引用共享的令牌/样式文件。
• 尽可能将 USS 与 UXML 放在一起，以缩短相对样式引用。
• 如果文件不是你创建的，请在进行复杂结构编辑前使用 uitk_inspect_uxml。
• 提供 ussPath 时，uitk_create_uxml 可以自动引用样式表。

工作流说明

1. 先创建 USS/UXML，然后通过 uitk_create_document 附加它们。
2. 运行时渲染需要有效的 PanelSettings 资源。
3. 当 USS 和 UXML 位于同一文件夹时，优先使用 <Style src="MyStyle.uss" />；仅在跨文件夹引用时使用完整资源路径。
4. 先从设计令牌开始，然后编写组件规则，最后编写布局容器。
5. 对于增量编辑，优先使用 uitk_read_file -> 编辑 -> uitk_write_file。
6. 创建 2 个或更多文件时，使用 uitk_create_batch。
7. Unity 6000.2+ 的世界空间（3D）UI：创建 PanelSettings -> uitk_worldspace_panel_create（它会为你设置世界空间渲染模式）。
8. 用户需要快速创建起始屏幕时，使用 uitk_create_from_template；对现有文件进行针对性编辑时，使用 uitk_add_element / uitk_add_uss_rule。
9. 运行时数据绑定：先创建 UXML 元素，然后对每个绑定属性调用 uitk_runtime_binding_add；使用 uitk_runtime_binding_list 验证。

最小示例

import unity_skills

unity_skills.call_skill("uitk_create_panel_settings",
    savePath="Assets/UI/GamePanel.asset",
    scaleMode="ScaleWithScreenSize",
    referenceResolutionX=1920,
    referenceResolutionY=1080
)

unity_skills.call_skill("uitk_create_uss",
    savePath="Assets/UI/HUD.uss",
    content=":root { --accent: #E8632B; } .title { color: var(--accent); }"
)

unity_skills.call_skill("uitk_create_uxml",
    savePath="Assets/UI/HUD.uxml",
    content="<?xml version=\"1.0\" encoding=\"utf-8\"?><engine:UXML xmlns:engine=\"UnityEngine.UIElements\"><Style src=\"HUD.uss\" /><engine:Label class=\"title\" text=\"Start\" /></engine:UXML>"
)

unity_skills.call_skill("uitk_create_document",
    name="HUD",
    uxmlPath="Assets/UI/HUD.uxml",
    panelSettingsPath="Assets/UI/GamePanel.asset"
)

限制

本模块有意不支持以下操作，避免你浪费调用去寻找这些功能：

不支持	原因	改用此方案
将绑定转换器 / update-trigger 作为一等参数	Unity 的 Scripting API 或手册未记录类型转换器和更新触发器的 UXML 属性名称，猜测属性名称会导致整个资源导入失败	通过 uitk_runtime_binding_add 的 extraAttributes 传入已确认的属性
移除单个运行时绑定	没有专用技能	通过工作流历史记录回滚，或使用 uitk_write_file 重写元素
在资源上构造 VisualElementReference / AuthoringIdPath	这些是运行时类型，通过 Inspector 在 MonoBehaviour 字段中设置；没有编辑器端 API 可从外部将其写入场景或预制件	使用 uitk_element_reference_get 查找 authoring-id 路径，然后在 Inspector 或你自己的 C# 中分配引用
编写 authoring-id	该技能可以读取现有的 authoring-id 属性，但不会分配新的属性	在 UI Builder（Unity 6000.5+）中编写
Unity 6000.2 以下版本的世界空间 UI	UIDocument 在 6000.2 中才获得世界空间属性，且 PanelRenderer 仅在 6000.5+ 中存在	使用 UGUI 世界空间 Canvas（ui 模块）或 xr_setup_ui_canvas
Unity 6000.0 以下版本的运行时数据绑定	2022.3 中不存在 DataBinding / BindingMode	对编辑器 UI 使用 binding-path SerializedObject 绑定

uitk_element_reference_get 会通过跟踪 <Template src="..."> 声明解析嵌套路径， 并递归进入其他 .uxml 文件（受 maxTemplateDepth 限制，默认值为 3，并启用循环保护）。 无法解析的模板会在 unresolvedTemplates 中报告，而不会被静默丢弃。

精确签名

确切名称、参数、默认值和返回值由 GET /skills/schema 或 unity_skills.get_skill_schema() 定义，而非由本文件定义。 在生成复杂 USS 系统、布局模式、组件样式或完整示例之前，请先加载 USS_REFERENCE.md。