dsh-ugui-preset

UGUI制作模式（DSH Agent Preset）

让 AI agent 以任意美术合成 PSD 为起点，在浏览器里生成、校对和批准平台中立 UI Spec，模拟运行时状态与交互，再显式构建等价的 Unity Production/Preview Prefab。v2.0 稳定版的定位是视觉驱动、人工批准、可移交的 uGUI 生产工作台：生产交付与原型 Controller/mock 数据严格分离。

实机演示

过程：agent 产出 DSL → 浏览器模拟交互 → 显式构建 Unity Prefab（演示录制于早期版本；v2.0.0 的生产/Preview 双产物、语义锚点与视觉基准所有权规则以本文为准）。

https://github.com/user-attachments/assets/fae23504-ad3e-40ac-ab31-3ef53a69478b

功能

• 多画布设计器与稳定身份：浏览器内可视化编辑 uGUI DSL（多 Canvas Workspace、稳定 nodeId、结构化验收），可先用 PascalCase 名称新建独立空白画布再导入新 PSD，并以 expectedVersion 保护删除不再需要的 Workspace Canvas。既有 Canvas 的新节点必须省略 nodeId 交给 Host 分配；Host 会拒绝未知显式 ID以及把旧 ID 改绑到另一语义节点的整体替换，防止历史消息、runtime/component 引用和 Unity ownership 静默漂移；升级前已有的纯英文 legacy 根身份保持兼容。
• 版本化 UI Spec 与校对闸门：每次变更都会形成 uiSpecVersion: 2 历史快照并使旧批准失效；「校对」页集中处理可视化决策、记录 once|screen|project|global 作用域并支持历史恢复。只有 review.status=approved 且 approvedVersion 等于当前 Canvas 版本时才能构建。
• 领域无关的新界面契约：非 PSD 新界面在首次写入前同时声明功能轮廓与视觉规格，把实体数量/导航、集合与主从详情、只读/可变操作、状态和交互逐项标记为已确认或假设；会改变层级与绑定的假设最多合并成一个范围问题。多区域、多状态或大量重复内容先写骨架和交互所有者、验收后再按稳定 nodeId 分区 patch，避免一次性整体重建。
• 项目/全局记忆：模式长期规则保存在 preset 的 docs/MEMORY.md/memory/tool-registry.json；项目决策、交付记录与工具哈希保存在目标工程 ProjectSettings/UGUIMaker/project-memory.json。最新 UI Spec 与版本历史写入 Assets/GeneratedUI/<Name>/Source，不把 PSD 二进制提交进工程。
• Agent 分析式 PSD 导入：程序解析图层、把可安全映射的文字转换为 TMP_Text、按可配置的末尾标记（默认“原图”）在整份 PSD 中全局查找素材源并暂存 PNG，再产出带 psdSource 的初始草稿；标记查找不受 Group 限制。未配对但有像素的素材源会去掉标记后作为独立 runtime state candidate 导入，不再静默丢失；无可用像素者会进入明确 ignored 统计。隐藏的非素材组和叶子同样是潜在运行时状态，必须保留其初始显隐和语义候选信息。明显的底图/图标 + 可编辑文字会先组成紧边界非渲染父容器，由父节点统一承担移动、锚点、显隐、交互和整体动画，Image/TMP 叶子仍可独立编辑；随后 UGUI Agent 按运行时职责、动画边界、状态、重复项与交互控件生成可维护 DSL；导入器统一生成的 topLeft 只作为精确保像素的暂存坐标，完成态会把满铺内容、大面积内嵌区域和固定节点分别转换为 stretch、边缘或中心语义锚点，当前绝对像素保持不变。「校对」页的“整理语义锚点”可对既有 Canvas 执行相同的版本化迁移，并通过逐节点 frame round-trip 防止漂移；到两个响应位置等距的节点不会静默猜测，而是生成一次性人工决策。UI Spec 阶段同时把 node.name 统一为同级唯一的语义英文 PascalCase；原始美术层名只保存在 psdSource，因此 Web 层级与 Unity GameObject 名始终一致且可追溯。「校对」页也可对既有 Canvas 执行版本化的“整理整体层级”：除普通 Image/TMP 组合外，位于 Button 范围内却被按图层类型拆走的文字会归入对应 Button，使移入动画、相对锚点和整体显隐由同一控件所有；当控件拥有满铺的实际背景 Image 时，内容边距容器会成为该 Image 的后代，以背景 RectTransform 而不是同级几何巧合作为坐标基准，Button/Toggle 仍留在外层语义控件。未引用的 inferred 纯透传包装会安全清理；runtime/review 引用、Layout 职责或绘制顺序使移动不安全时转为人工决策。同一语义锚点诊断也覆盖非 PSD Canvas：LayoutGroup 控制的子节点不产生噪声，高置信几何错误和自由定位交互控件的错误边缘所有权会阻止交付，其他可疑固定锚点作为 warning 供 Agent 检查。所有幸存节点保持绝对像素和 nodeId，扁平 graphic 绘制顺序保持不变。
• 静态结构验收与运行时证据：ugui_visual_acceptance_check 只检查 UI Spec 的锚点、所有权、引用、布局尺寸和重叠等静态契约，不渲染浏览器或 Unity 像素。LayoutGroup、ScrollRect、Mask、重复内容、状态或交互发生变化时，Agent 必须另外核对初始与边界状态；滚动界面至少验证首尾端、最后单元可达和直属 cell 尺寸，并分别报告静态结构、浏览器渲染与 Unity 渲染证据。裁切来源图只证明连续性，滚动不能恢复素材中不存在的像素；受控 LayoutGroup 只接收同构 cell，装饰、覆盖层和来源参考图留在布局节点之外。来源叶子被完整替代后不会静默保留为死节点，也不会无授权删除；只有该叶子的 remove-source 决策被人类解决后，Host 才允许移除。
• PPU Profile 与安全文字：通用 PSD Profile 默认 Canvas.referencePixelsPerUnit=100、Sprite.pixelsPerUnit=100；项目可在嵌套 psdImport.ppuProfile 中配置为 100/25 等组合。该配置是项目唯一权威值，浏览器会显示并锁定它；单次请求或既有 DSL 漂移时会在写 Assets 前拒绝。普通文字安全转换为 TMP；可通过每屏 Export Profile 的 fontAssetPath 明确指定 Unity TMP_FontAsset，省略时使用项目 TMP Settings 默认字体；无法可靠还原的文字才栅格化。浏览器字体只在 Canvas 暂存，上传时会修复常见的短 OS/2 v5 表以兼容 Chromium OTS，不修改工程源字体；字体按实际承载设计器/预览器的 popup Document 附着并以 Document 为缓存作用域，关闭重开窗口会重新注册。目标栏持续显示“加载中/已加载/加载失败”徽章，失败时明确回退系统字体并可重试。Host 静态结构验收只把文件存在、格式/哈希正确及全部导入 TMP 引用一致记为素材就绪，不把 previewFont* 元数据冒充浏览器已应用；浏览器徽章与 Unity TMP/最终截图仍是彼此独立的验收层。静态结构验收会对 PSD 单行 TMP 的临界宽高给出换行/溢出警告，最终仍需核对 Unity 截图。
• 图片渲染契约：Image.imageType 支持 simple|sliced|tiled|filled；spriteBorder 使用原图像素 [left,bottom,right,top]，fillCenter 控制中心区域；Filled Image 共享 fillAmount/fillMethod/fillOrigin/fillClockwise 语义，Web 模拟与 Unity Image.Type.Filled 使用同一 UI Spec；Unity Sprite 固定使用 Point、无压缩、无 Mipmap、sRGB/Alpha、Full Rect 导入设置。
• 命名状态与跨平台交互：DSL 顶层 runtime.stateGroups / runtime.interactions 表达状态族和声明式机械交互；动作支持 setState|cycleState|setActive|setText|addNumber|setFill|emit，cycleState.textTargets 可让角色切换同时更新多块文字。设计器支持查看当前/全部状态，预览器支持运行模拟、选中子树和全屏预览，事件日志默认折叠并仅在用户主动展开后显示；Unity 生成代码以相同顺序执行同一动作。
• 分析进度可见：UGUI 窗口持续显示“排队 → 读取 → 规划 → 写入 → 静态验收 → 完成”的进度；摘要只呈现可操作的高层决策，不暴露模型隐藏思维链。
• 显式双产物与 Demo Scene：PSD 导入始终只暂存；每屏 Export Profile 默认输出到 Assets/GeneratedUI/<Name>/{Prefabs,Runtime,Preview,Sprites,Source,Demo}。每次构建必须提供已批准的当前 expectedVersion，并在脚本/图片写入前通过 workbench、Manifest、binding、输出 ownership 与配置预检。生产 <Name>.prefab 只挂载生成的 <Name>View；<Name>.Preview.prefab 才增加临时 <Name>PreviewController/<Name>PreviewMock，并生成 <Name>.Demo.unity。Preview 源自动加 #if UNITY_EDITOR，项目 Agent 后续可替换业务逻辑而无需改变视觉 Prefab 层级。
• 所有权与冲突契约：所有权 Manifest 与三方冲突策略只更新生成器拥有的内容，保留用户节点、用户组件和 UnityEvents，冲突时明确报错而非静默覆盖。Preview/Production 节点优先按 persistent local ID 和原始 sibling-index hierarchy 映射，重复同级名称不会再造成歧义。缺少或不匹配 Manifest 时一律拒绝接管，当前不暴露可由模型自行设置的采用开关。
• 完整输入事务与可观测性：生成脚本、PNG 与对应 .meta 共同进入可逆事务；Worker 未提交时按并发修改保护逆序恢复，dirty Worker 事务则明确返回 retained 状态。构建结果统一包含结构化 code/details/classification/mutation，以及 Host 模块 revision、生效配置、配置加载时间和磁盘漂移检测；发现旧实例时在写入前返回 reload-required。
• 显式两阶段 PSD 制作：pending-agent 阶段只允许保持导入视觉叶子并完成运行时结构分析；验收完成后才进入普通 DSL 业务增强，可新增选中态、文字颜色副本和透明点击层。若跨阶段修改，错误会直接返回下一阶段操作提示。
• 逻辑同步闸门：logic.js 领先 view.cs 时浏览器显示“逻辑同步中”，当前 Agent 完成语义核对后继续原构建，界面徽章持续显示进度。

环境要求

• DSH（DeepSeek Harness）Web 部署
• Node.js 20+ 与 pnpm 10.28.2（插件依赖使用已提交的 frozen lockfile 安装）
• 一个运行中的 Unity 工程（已用 Unity Editor 打开；当前语义缓存钉住 uGUI 2.0.0 / Unity 6000.3，其他版本按文档过期流程重核即可）
• Unity 官方 CLI（unity 在 PATH 上）
• macOS / Linux / Windows 均支持（macOS/Linux 走 bash 入口；Windows 自动切换到 unity-cli.py Python 入口，需要 Python 3；无需 bash/jq）

安装

# 1. 克隆到 DSH preset 目录（DSH 按目录发现 preset）
git clone https://github.com/BaronCyrus/dsh-ugui-preset.git ~/.dsh/.agent-presets/ugui
#    Windows PowerShell: git clone ... "$env:USERPROFILE\.dsh\.agent-presets\ugui"

# 2. 注册浏览器端插件包（跨平台，幂等）
node ~/.dsh/.agent-presets/ugui/setup/install.mjs

# 3. 配置目标 Unity 工程
cd ~/.dsh/.agent-presets/ugui
cp setup/ugui.config.example.json ugui.config.json
#    编辑 ugui.config.json：projectPath 必填；asmdef 工程需把 assemblyName 改成对应程序集名
#    productionPrefabDir/scriptDir 配 Production；previewPrefabDir 留在 Editor，previewScriptDir 必须在非 Editor 的可挂载程序集目录
#    无 asmdef 时 previewAssemblyName 使用 Assembly-CSharp；有 asmdef 时填写其名称且不得是纯 Editor-only/排除 Editor 的程序集
#    Host 会自动给 view/testdata 源加 #if UNITY_EDITOR，Preview Prefab 仍不会进入 Player
#    psdImport.sourceLayerMarker 配置素材源末尾标记；psdImport.ppuProfile 配置 Canvas/Sprite PPU
#    通用默认值为 100/100；若项目采用放大素材工作流可配置为 100/25
#    defaultPsdTextMode 控制文字默认导入为 editable TMP_Text 或 raster Image
#    PSD 导入的 TMP_Text 使用项目 TMP Settings 默认字体；浏览器 TTF/OTF 仅暂存到工作区

从 v2.0.4 升级到 v2.0.5 时，拉取代码后必须重启 DSH 并刷新现有 Web 页面；本版本把 ugui_visual_acceptance_check 明确限定为静态 UI Spec 检查，新增布局/滚动/状态/交互的运行时证据矩阵，强化 Grid 来源图形与 ignoreLayout 覆盖层检查，并要求 PSD 来源叶子只能通过已解决的 remove-source 决策退役。已有 Web Profile link 不变，无需重新安装。

从 v2.0.3 升级到 v2.0.4 时，拉取代码后必须重启 DSH 并刷新现有 Web 页面；该版本让浏览器命中遵循 Unity GraphicRaycaster 的被动 Graphic 遮挡语义，新增最小交互所有权合同，并加强重复区域的布局/滚动拓扑识别与运行时语义歧义闸门。已有 Web Profile link 不变，无需重新安装。

从 v2.0.2 升级到 v2.0.3 时，拉取代码后必须重启 DSH 并刷新现有 Web 页面；该版本把 PSD 预览字体附着到实际承载设计器/预览器的 popup Document，升级素材验收协议到 v8，并增加浏览器/Host 协议漂移保护。若从更早版本跨级升级，仍按下述 v2.0.2 步骤执行安装脚本。

从 v2.0.0 或 v2.0.1 升级到 v2.0.2 时，请在拉取新代码后重新执行一次 node ~/.dsh/.agent-presets/ugui/setup/install.mjs。DSH 0.1.2 起不再从 preset 直接子树发现浏览器 bundle，安装脚本会把 host-noop Client 发现行补入 Web Profile；v2.0.2 同时让入口显隐读取可变的 agentPreset Session projection，而不是会在空会话切换模式后保留旧值的不可变 Header。随后必须重启 DSH 并刷新页面。

从 v1.2.0 或更早版本升级时，旧的 Assets/Editor/DshUguiPreview/Generated / Assembly-CSharp-Editor 配置会被明确拒绝，因为其中的 MonoBehaviour 在 Unity 6 无法可靠挂载。请先备份工程，将整个生成脚本目录连同每个 .meta 迁移到非 Editor 目录（默认 Assets/DshUguiPreview/Generated）并改用运行时兼容程序集；保留 .meta 才能维持 Preview Prefab 的脚本 GUID。首次安全构建会只识别这一精确旧目录格式，自动把 generated-script ownership sidecar 路径迁到当前配置，并通过 C/B/D 规则给仍等于旧 baseline 的源添加 UNITY_EDITOR guard；任何自定义旧路径或内容分歧仍会阻塞而不猜测。完成文件/配置迁移后必须重启 DSH，当前 Host 实例不会热替换。

重启 DSH 并刷新现有 Web 页面后，可在 plugins/dsh-ugui-tools/ 运行 npm run test:runtime-psd，确认当前 127.0.0.1:3080 已启用语义分析协议 v8、静态验收证据边界和进度路由；随后新建「UGUI制作模式」会话即可开始使用。可提前让 Agent 调用一次 ugui_setup，也可以直接首次构建：Host 会在预检发现 UIDslWorkbench 缺失时自动创建并继续同一次请求。

使用

1. 会话中描述界面需求 → Agent 产出 DSL 并在浏览器设计器/预览器中呈现；有新的 PSD 且不想覆盖现有内容时，先在 Canvas 标签栏点击「＋ 新建」，填写唯一 UI 类名与参考分辨率，再点击「导入 PSD」。预览字体只暂存到工作区，设计器/预览器目标栏会显示当前 popup Document 的字体加载状态；“已加载”才表示浏览器当前窗口已附着该字体，“加载失败”会明确回退并可重试。Unity 的 TMP_Text 仍使用项目 TMP Settings 默认字体。导入只替换当前 Canvas 为暂存草稿并提交 Agent 分析，不自动生成 Prefab。标签栏「删除」会用当前 expectedVersion 删除该 Workspace Canvas 及本地草稿，但为保护 Unity 引用，不会自动删除 Production/Preview Prefab、生成脚本或已导入图片。
2. PSD 中可见效果层负责布局；名称以 psdImport.sourceLayerMarker（默认“原图”）结尾的素材层在整份 PSD 中全局参与配对，与效果层是否同组无关。配对素材保持自身像素尺寸；未配对但有像素的素材层会去掉末尾标记、按 Canvas/Sprite PPU 比例形成独立 runtime state candidate，初始 hidden 状态会保留；无像素者会进入 ignored 统计并给出原因。隐藏的普通 Group/叶子同样作为运行时状态候选保留，不得因初始不可见而删除或强制激活。普通文字安全转换为 TMP；无法可靠还原的特殊文字才回退为 Image。隐私边界：PSD 文件名、图层名称和文字元数据会发送给当前 Agent/模型；所选 TTF/OTF 二进制只保留在本机工作区。
3. Agent 可在顶层 runtime.stateGroups / runtime.interactions 中声明状态与机械交互。设计器切换“当前状态/全部状态”检查结构，预览器执行状态矩阵、按钮事件、数值和 Fill 模拟；业务数据仍属于项目或可选 Preview。
4. 在「校对」页处理未决项并由人类批准当前版本。任一 DSL、Profile 或决定变更都会自动撤销旧批准；未批准版本的「生成 Prefab」保持禁用。
5. 显式点击「生成 Prefab」（或调用带当前 expectedVersion 的 ugui_build）后才导入暂存素材。默认生成 <Name>.prefab、可交互 <Name>.Preview.prefab、<Name>.Demo.unity 与带 [SerializeField] private 引用的 <Name>View.cs；Worker 保存 Prefab 后逐项回读绑定，Production 不引用 Preview Controller/mock。
6. 更新既有 Prefab 遵循所有权 Manifest/三方冲突合同：用户节点、组件与 UnityEvents 不应被静默覆盖；冲突需处理后重试。没有有效 Manifest 的旧资产当前一律拒绝接管；必须先通过受信任的项目迁移/备份流程建立基线，不能靠删除 TestData.cs 作为移交步骤。

目录结构

├── preset.yml / agent.cordis.yml   # preset 元数据与组合（persona、工具行）
├── ugui.config.json                # 你的工程配置（不入库；参考 setup/ugui.config.example.json）
├── docs/                            # 开发合同与跨项目长期记忆
├── memory/tool-registry.json        # 持久 Unity Worker/CLI 工具注册表与版本
├── plugins/dsh-ugui-tools/         # 主插件：host 工具/路由 + 浏览器设计器/预览器
├── plugins/dsh-ugui-entry-guard/   # 入口守卫（web profile 常驻）：入口按钮缺失时自动刷新一次页面
│   ├── lib/                        # host.js（工具与构建管线）/ client.js（设计器与预览器）
│   ├── unity/BuildUiWorker.cs      # Unity 侧构建 worker（经 unity-cli 任务在工程内执行）
│   ├── test/                       # 行为测试（npm test）
│   ├── COMPONENTS.md               # DSL 组件契约
│   └── UNITY_SEMANTICS.md          # uGUI 交互语义本地缓存（按组件分节，含版本钉）
├── vendor/unity-cli/               # 内嵌的 Unity Editor 控制通道（bash 入口 + Windows 用 Python 移植入口）
├── setup/install.mjs               # Web Profile link 与 Client bundle 发现行注册
├── setup/ugui.config.example.json  # 工程配置样例
└── fixtures/canvases/              # 示例画布（测试背包：DSL + 逻辑 + 视图脚本三件套）

开发

cd plugins/dsh-ugui-tools && npm test

注意：ugui.config.json 存在且指向真实工程时，语义缓存新鲜度测试会对该工程生效。

• host.js、ugui.config.json、agent.cordis.yml：不会通过浏览器 HMR 替换当前 Host 实例；修改 Host 时还需递增 host 行 ?v=，然后重启 DSH。构建会比较磁盘 revision 与启动快照，发现漂移即返回 reload-required，不会继续用旧配置写工程。
• client.js：递增插件 package 版本；只有从 DSH checkout 运行 pnpm run dev:web 重建 bundle 时，现有页面的 Client HMR receiver 才能自动加载。其他情况请重启 DSH 并刷新现有 127.0.0.1:3080 页面；启动另一个 Vite server 不会替换该 GUI。
• 可调用 ugui_impl_probe 查看 hostModuleRevision、configLoadedAt 与当前生效的 Preview/PPU 配置，避免根据磁盘文件猜测运行实例。

架构与生命周期约定见 docs/DEVELOPMENT.md。

商业支持

本 preset 以 MIT 协议免费开放全部功能（含商用）。如果你的团队需要以下服务，欢迎联系洽谈：

• 接入支持：在你的 DSH + Unity 工程里完成部署、调通首块画布
• 定制开发：新 DSL 组件、私有交互语义、内部管线对接
• 培训咨询：uGUI 生产流程与 agent 协作模式落地

联系方式：378905096@qq.com / 微信 codiee_zhang（或 GitHub @BaronCyrus 私信/Issue）。

社区支持通过 GitHub Issues 进行（尽力而为，不保证时效）。

许可

MIT © 2026 BaronCyrus。本仓库全部内容（含 vendor/unity-cli）均为原创并以同一协议发布。