前言¶

用 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。