前言¶

用 FairyGUI 做客户端界面时，常见路径是：策划或美术给一张示意图，程序或 UI 同学在编辑器里逐项搭元件、对坐标、补控制器，再手写或维护 C# 视图类里的 GetChildAt 索引。示意图进大模型时还会被整体缩放，小字和细线容易看不清，识别误差会一路传到 XML 和预览图。

DeepSeek Harness（DSH）把能力拆成插件交给 Agent 调用。FairyUI（仓库名 dsh-fairyui，维护者 swc0506）是一套面向 FairyGUI 的 Host 插件：直接读写工程的 .fairy、package.xml 与各元件 XML，提供识图辅助、按 JSON 布局规格生成元件、预览、校验视图类，以及在示意图上叠框核对。社区目录由 SkillHub 收录，与 DeepSeek / 幻方无官方从属关系；安装与运行以你本机 DSH 会话权限为准。

这是什么¶

FairyUI 的定位是：让 Agent 能读工程、读示意图，并按规范把界面落成合法 FairyGUI XML，不必长期开着 FairyGUI 编辑器。插件版本在 package.json 中为 0.2.3，许可证 MIT。

FairyGUI 工程结构插件按原文处理：<工程>.fairy、各包下的 assets/<包>/package.xml，以及每个元件对应的 XML 文件。

核心功能¶

下面按 README 中的工具表归纳；名称均以 fairyui_* 暴露给 Agent。

工程与规范¶

• fairyui_inspect：读取包、图片（id/名称/尺寸/九宫格）、元件（含扩展类型、ui://、控制器、齿轮）、设计分辨率与规范；details:true 可展开控制器与齿轮。
• fairyui_conventions：读取或保存命名与目录规范（默认 defaults/conventions.json，工程内 design/conventions.json 可覆盖）。
• fairyui_package_create：按规范新建空包。
• fairyui_lint：扫描包/组件/图片命名违规，可用 folder / components 聚焦。
• fairyui_open：用 FairyGUI 编辑器打开工程。

示意图识读与对齐¶

整张示意图缩放后细节易丢，README 推荐「先裁、再标、后拼、用 diff 收口」：

1. fairyui_crop（例如 grid 3×3、scale 2）裁块后逐块查看；支持单块 rect 或 cols/rows 网格，输出到 _crops。
2. fairyui_ocr：Windows 自带 OCR，默认按 ≤800px 分块并每块 2× 识别，坐标映射回原图；lang 可设 zh-Hans-CN / en-GB。
3. fairyui_annotate：把候选区域画成编号框，便于复核。
4. fairyui_palette：采样主色/文字色 HEX 与占比。
5. fairyui_build 拼装后，用 fairyui_diff 对比预览与示意图，关注 meanDiff / changedPct（默认超过阈值 24 的像素占比）。
6. fairyui_mockup_grid 可在示意图上叠刻度网格，便于量 x/y/w/h；fairyui_overlay 把组件框叠到示意图上做逐像素核对。

辅助工具还包括 fairyui_asset_sheet（包内图片缩略图总览）、fairyui_guide（组件对照表与规范格式说明）。

布局生成与 C# 视图¶

• fairyui_build：按 JSON 布局规格创建或替换元件，写入 XML、输出预览、返回 ui://；支持 previewPages、indexChanged、批量 components，覆盖已有组件时保留已有 extention（除非显式指定）。
• fairyui_template：创建 Button/Label/ProgressBar/Slider/ComboBox/Tree/WindowFrame 等扩展模板或列表项模板。
• fairyui_sync_views：按 XML 显示列表重生成 C# 视图类，使 GetChildAt 索引与发布一致。
• fairyui_check_views：校验 XML 与视图类在基类、字段、GetChildAt/GetControllerAt 索引、字段类型上是否一致。

示意图元素与 FairyGUI 节点类型的对应关系（如 image、text、list、button、combobox 等）由 fairyui_guide 与 README 表格给出；识别由模型看图完成，插件负责分类约束、模板检查与 XML 落地。

安装与启用¶

插件为纯 ESM + PowerShell，README 写明无 npm 依赖，拷贝目录即可。环境要求包括：

• Windows（预览、资源总览、网格依赖 PowerShell + GDI+；FairyGUI 编辑器亦为 Windows 程序）。
• 已安装 DSH，且能使用 plugin_manager。
• 已安装 FairyGUI 编辑器（默认路径 D:\FairyGUI\FairyGUI-Editor.exe）。

安装步骤摘要：

1. 将整个 dsh-fairyui 目录拷到本机，保持 index.js、lib/（含 lib/*.ps1）、defaults/、locale/、icon.svg、package.json、cordis.patch.yml 等相对结构。
2. 在 DSH 中安装本地 bundle。命令行方式为：

dsh plugin --profile <profile> add link:D:\path\to\dsh-fairyui

等价于：

plugin_manager install_bundle target=D:\path\to\dsh-fairyui

3. 确认插件行已启用（entryId 形如 include:dsh-fairyui）；若被禁用：

plugin_manager set_plugin target=include:dsh-fairyui enabled=true

4. 编辑器不在默认路径时，在 profile 的 cordis.patch.yml 中覆盖 editorPath，保存后 disable → enable 插件或重启 DSH。

5. 调用 fairyui_guide 验证；再对任意 .fairy 工程调用 fairyui_inspect。

安装与 install_bundle 属于高权限操作，README 要求会话具备 Full access，否则调用可能被拒绝。

典型用法¶

识图增强示例¶

对示意图标注区域时，可向 fairyui_annotate 传入图片路径与区域列表，例如：

{
  "image": "D:/UI/mockup.png",
  "regions": [
    { "rect": [28, 20, 260, 56], "label": "标题" },
    { "rect": [580, 420, 250, 110], "label": "按钮" }
  ]
}

经过裁块、OCR、取色与标注复核后，再进入 fairyui_build。

布局规格示例¶

fairyui_build 接受的布局 JSON 需包含 project、package、component、尺寸与 nodes。片段如下（完整字段见仓库 README）：

{
  "project": "D:/Game/UI/MyProject.fairy",
  "package": "Main",
  "component": "UI_Shop_Panel",
  "width": 900,
  "height": 640,
  "nodes": [
    { "type": "graph", "name": "bg", "rect": [0, 0, 900, 640], "fill": "#2a2340", "corner": 20 },
    { "type": "text", "name": "title", "rect": [40, 30, 300, 44], "text": "商店", "fontSize": 32, "bold": true, "color": "#ffffff" },
    { "type": "button", "name": "closeBtn", "rect": [820, 24, 56, 48], "title": "X" }
  ]
}

nodes 顺序即 z-order。按钮、列表等可自动匹配包内 Button 扩展组件；缺失模板时可由插件在 templateFolder（默认 Widgets）下创建 CommonBtn 等（autoTemplate:false 可关闭自动建模板）。

从示意图到发布的推荐流程¶

README 给出的端到端顺序可作为 Agent 工作流参考：

1. fairyui_mockup_grid 加网格后量坐标。
2. fairyui_guide / fairyui_inspect 确认类型映射与规范。
3. 有设计规范文档时解析并 fairyui_conventions 保存。
4. fairyui_build 生成并预览，对照示意图修正后再次 build。
5. 覆盖元件若返回 indexChanged，执行 fairyui_sync_views，再用 fairyui_check_views 校验。
6. fairyui_overlay 叠框核对；fairyui_lint 查命名；fairyui_open 在编辑器复核与发布。

规范与生成物位于 FairyGUI 工程内（design/conventions.json、.dsh-fairyui/），不绑定安装机器，可随工程迁移。

适用场景与注意¶

适合谁：在 Windows 上用 FairyGUI 做游戏或工具客户端 UI，且希望在 DSH 里用 Agent 协助读示意图、写 XML、出预览、维护 C# 视图索引的团队。

能力边界（README「限制」一节）：

• 预览为 GDI+ 近似渲染：列表/树等多为占位框，富文本只显示纯文本，九宫格按整图拉伸；最终效果以编辑器与运行库为准。
• 自动创建的扩展模板结构较简，精细交互与动效需在编辑器内补全；ScrollBar 不自动生成。
• 发布 .fui 与图集仍需 FairyGUI 编辑器完成。

安全与权限：插件以当前 DSH 进程权限读写工程路径与调用 PowerShell；安装前应阅读 GitHub 源码 与 MIT 许可证，仅在信任的工程目录上使用。

OCR 依赖 Windows 自带引擎；艺术字、描边字可能误识别，文本内容应以裁块图人工复核。

结尾¶

FairyUI 把 FairyGUI 的 XML 工程、示意图量化和 C# 视图校验收进同一套 fairyui_* 工具，适合在 DSH「一切皆插件」的生态里做客户端 UI 自动化。目录页：SkillHub - FairyUI；源码与文档：github.com/swc0506/FairyUI。