FairyGUI Agent Bridge

通过 MCP (Model Context Protocol) 或 CLI，让 AI 编程 Agent（如 Cursor、Claude、Codex、VS Code 等）以结构化指令直接操作 FairyGUI Editor，实现自动拼 UI 界面、动效制作与一键发布。

• 版本：0.9.6

• 队列协议：1.0

• 已验证 FairyGUI Editor：6.1.4

• 通信方式：本地 JSON 队列 + MCP stdio

本仓库是由 957685825 持续维护的独立版本，基于 Wilson520403 的原始工程，保留原始 Git 历史和 MIT 许可证。这里的版本号只表示本维护分支，不代表已合并原仓库的全部后续功能。完整源码不压缩、不混淆，可直接修改和二次开发。

插件卸载清理（0.9.6）

通过入口导出的 onDestroy 解绑更新、工程和焦点事件，并恢复后台运行设置；不再直接赋值给加载阶段的 PluginInfo.onDestroy，该值会被宿主加载流程覆盖。事件解绑先于菜单清理，避免旧回调访问已销毁的 JsEnv。更新文件不会清除旧实例已经残留的委托，需要完全退出并重新打开 FairyGUI Editor。布局与游戏验收范围保持各自记录。

效果图对齐检查（0.9.5）

新增 fgui_get_layout_snapshot(max_depth=12, include_image=True) / CLI layout：读取当前组件的根画布四角与外接矩形、锚点、缩放/旋转/斜切、字体排版、Controller 当前页及设计图偏移。坐标通过宿主原生变换换算，消除画布平移/缩放与嵌套坐标混用；不切换、选择、保存或发布文档。

默认从组件显示对象获取原生预览（不是桌面截图），MCP 直接返回 PNG 图片内容。CLI layout 默认只读布局；layout --output /ABSOLUTE/PATH/TO/SCRATCH/preview.png 导出 PNG，父目录须存在且拒绝覆盖。原生 RGBA 仅转换为 PNG，不重画、裁切或替换美术素材；临时纹理在成功/失败后均释放，不增加图像依赖。

对照流程：先明确效果图原始画布尺寸、裁切原点、当前状态及参考图偏移，再用同一坐标系比较当前预览；记录具体元素的横纵偏差，修改后再次读取预览复查。文字框与图片布局框不等于可见字形或非透明边缘，不能仅靠 x/y/width/height 宣称视觉一致。设计图字段只报告编辑器已有绑定，不擅自导入或设置参考图。

限制：仅反映编辑器当前状态，不含游戏动态加载的图标、文本或逻辑；不自动识别设计图元素或生成匹配分数，也不自动移动组件。预览尺寸与根画布不一致时明确报错，不能默认为同尺寸直接套坐标。默认遍历深度 12，超过深度明确标记 childrenTruncated；节点上限 10000。图像要求整数尺寸、单边不超过 4096、面积不超过 4194304 像素，超限可 include_image=False 仅读布局。旧插件只在调用新工具时提示升级，不影响已有工具。

0.9.5 修复锚点造成的半画布坐标偏移，以及原生截图继承编辑器视口裁切的问题。坐标使用显示对象四角变换；截图先刷新离屏绘制状态，结束后恢复。多组件真实 Editor 验收记录见当前能力参考。更新全局插件后需重启 Editor，新增 MCP 工具需重启 MCP 服务。

编辑器输入状态保护（0.9.3）

Bridge 请求成功、失败或编辑器重新获得焦点后，等待窗口在前台且真实按键/鼠标均松开并连续空闲 0.5 秒，再通过宿主原生接口恢复一次指针和方向键输入状态。恢复不保存文档、不切换文档、不修改组件或当前选择；按住修饰键、多选及拖动期间会等待。定时心跳不会触发恢复。客户端等待较慢响应时，心跳正常则不再额外激活编辑器。

这是针对“检查后输入失常、按两次 Shift 可恢复”的输入状态保护，尚未证明编辑器漏收 KeyUp 的具体原因；自动化宿主替身验证不等于真实编辑器手工回归。更新全局插件后需重启编辑器，客户端更新需重启 MCP 服务。

说明：Bridge 仓库与业务 FairyGUI 工程分开存放。轻量插件按当前用户全局安装一次，所有 FairyGUI 工程共用；在宿主 IDE 中可按需安装 Skill 提高 AI 操作准确率。

🏗️ 工作原理

graph LR
    Agent["AI Agent / IDE<br>(Cursor / Claude / Codex / VSCode)"] 
    -->|MCP stdio| Bridge["FairyGUI Agent Bridge<br>(Python CLI / MCP Server)"]
    Bridge -->|读写 .agent/ 队列| Plugin["Editor 全局插件<br>(~/.config/FairyGUI-Editor/plugins/agent-bridge)"]
    Plugin -->|FairyGUI API| Editor["FairyGUI Editor<br>(运行中的 UI 工程)"]

Related MCP server: Agent Bridge for Unity

💡 AI 使用示例

安装完成后，在支持 MCP / Skill 的 AI 对话框中直接输入类似以下指令：

• 帮我制作一个登录界面，包含账号输入框、密码输入框和登录按钮

• 根据蓝湖 MCP 导出的切图帮我拼出这个背包界面

• 帮我给 MainMenu 界面的 StartBtn 添加一个弹出的缩放动画效果

• 帮我检查当前界面的大图图集设置，保存并发布 Lobby 包

若安装了 Skill，也可以通过 /fgui-agent-bridge 帮我制作一个登录界面 精准触发。

依赖要求

• Python 3.10+

• uv 包管理器

• FairyGUI Editor（推荐 6.1.4）

🚀 安装指南

方式一：AI 智能安装（推荐）

将下面的提示词发送给能够操作本地终端和文件的 AI 编程 Agent（如 Cursor、Claude Code、Codex 等）：

请帮我在这台电脑上完整安装 FairyGUI Agent Bridge。你可以执行终端命令和编辑本地文件，请实际完成安装，不要只给操作说明。

源仓库：https://github.com/957685825/fgui-agent-bridge.git
插件安装范围：当前用户的 FairyGUI Editor 全局插件目录；
目标 FairyGUI 工程：仅用于 MCP 连接，优先从当前工作区自动查找 .fairy 文件；找不到或找到多个时停下来询问我。
目标代码仓库：当前工作区；

方式二：手动安装

1. 克隆 Bridge 仓库并准备环境

git clone https://github.com/957685825/fgui-agent-bridge.git
cd fgui-agent-bridge
uv sync --frozen

2. 安装 FairyGUI Editor 插件

运行同步脚本，将插件安装到当前用户的 FairyGUI Editor 全局插件目录：

uv run python scripts/sync_to_project.py --global-plugin --apply

仅在旧版 Editor 或隔离环境不允许全局插件时，才按单个工程安装：

uv run python scripts/sync_to_project.py \
  --project /ABSOLUTE/PATH/TO/FAIRYGUI-PROJECT \
  --apply

注意：

• 全局插件安装到 ~/.config/FairyGUI-Editor/plugins/agent-bridge/，所有 .fairy 工程共用。

• 安装完成后，请重新启动 FairyGUI Editor以加载插件。

• 不要同时保留同 ID 的工程级插件副本，避免重复注册菜单和重复轮询队列。

• 插件运行时目录 .agent/ 会在工程内自动创建，请将其加入 .gitignore，不要提交到 Git。

3. 配置 MCP Server

你可以根据所使用的 AI 客户端添加 MCP 配置。通用配置格式如下（可参考 .mcp.example.json）：

{
  "mcpServers": {
    "fgui": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/ABSOLUTE/PATH/TO/fgui-agent-bridge",
        "fgui-agent-mcp"
      ],
      "env": {
        "FGUI_PROJECT_PATH": "/ABSOLUTE/PATH/TO/FAIRYGUI-PROJECT"
      }
    }
  }
}

常见客户端配置入口：

• Cursor：在 ~/.cursor/mcp.json 或项目根目录 .cursor/mcp.json 中粘贴上述配置。

• Claude Desktop：编辑 claude_desktop_config.json（macOS: ~/Library/Application Support/Claude/，Windows: %APPDATA%\Claude\）。

• Codex CLI：

  codex mcp add fgui \
    --env FGUI_PROJECT_PATH=/ABSOLUTE/PATH/TO/FAIRYGUI-PROJECT \
    -- uv run --project /ABSOLUTE/PATH/TO/fgui-agent-bridge fgui-agent-mcp

• VS Code (Cline / Roo Code)：在扩展的 MCP Settings 中添加名为 fgui 的 stdio 服务。

4. 验证连接

启动 FairyGUI Editor 并打开目标工程，然后执行：

uv run --project /ABSOLUTE/PATH/TO/fgui-agent-bridge \
  fgui-agent --project /ABSOLUTE/PATH/TO/FAIRYGUI-PROJECT ping

若返回 {"status": "ok", ...} 则表明连接成功。

可选：安装 Agent Skill

Skill 可以让 AI 更好地遵循 FairyGUI 的属性规范与动画约定。使用同步脚本可一键将 Skill 同步至目标业务代码仓库：

uv run python scripts/sync_to_project.py \
  --global-plugin \
  --skill-root /ABSOLUTE/PATH/TO/YOUR-CODE-REPOSITORY \
  --apply

或手动将 .agents/skills/fgui-agent-bridge/ 目录复制到目标代码仓库的 .agents/skills/ 目录下。

🔄 检查与拉取更新

当 Bridge 源仓库有功能更新或 Bug 修复时，可通过一条命令自动从源仓库安全拉取最新代码（git pull --ff-only）、同步 Python 环境（uv sync），并刷新全局插件与 Skill：

# 从源仓库拉取最新代码并同步全局插件与业务代码仓库 Skill
uv run python scripts/sync_to_project.py \
  --pull \
  --global-plugin \
  --skill-root /ABSOLUTE/PATH/TO/YOUR-CODE-REPOSITORY \
  --apply

# 或通过 CLI update 子命令执行
uv run fgui-agent update --pull --apply

提示：

• fgui_status 会自动比对当前 Bridge 服务端与 FairyGUI 编辑器内运行的插件版本，若版本不一致会在状态中返回 updateWarning 提示。

• 若插件文件被更新，请重新启动 FairyGUI Editor以加载新版插件。

🛠️ 常用 CLI 指令

在 fgui-agent-bridge 仓库根目录下执行（也可以通过 --project PATH 指定工程）：

# 状态与连接检查
uv run fgui-agent status
uv run fgui-agent ping

# 查看工程与资源结构
uv run fgui-agent project
uv run fgui-agent packages
uv run fgui-agent items ViewHub
uv run fgui-agent open ViewHub ViewHubBtnItem
uv run fgui-agent active
uv run fgui-agent tree
uv run fgui-agent layout
uv run fgui-agent layout --output /ABSOLUTE/PATH/TO/SCRATCH/preview.png

# 历史与保存
uv run fgui-agent save
uv run fgui-agent undo
uv run fgui-agent redo

# 发布资源
uv run fgui-agent publish --scope active

创建与导入资源：

uv run fgui-agent create-component ViewHub NewPanel --width 1920 --height 1080
uv run fgui-agent import-image ViewHub /absolute/path/button.png
uv run fgui-agent import-font ViewHub /absolute/path/font.ttf
uv run fgui-agent import-sound ViewHub /absolute/path/click.mp3
uv run fgui-agent create-movieclip ViewHub Loading --frame /path/01.png --frame /path/02.png --fps 12
uv run fgui-agent create-button ViewHub NewButton --mode common
uv run fgui-agent upsert-transition '{"name":"fadeIn","frameRate":60,"items":[{"type":"Alpha","frame":0,"tween":{"duration":12,"start":0,"end":1}}]}'
uv run fgui-agent preview-transition play fadeIn

🧩 MCP 工具一览

⚙️ 关键机制与规范

换皮位置核对

换皮先固定主参考，复用旧皮肤结构、锚点、列表间距及动态奖励挂点。随 Skill 分发的只读脚本递归核对已保存基础 XML；任何未确认差异返回非零，有意变化需按精确值逐条写明原因。

python3 .agents/skills/fgui-agent-bridge/scripts/compare_skin_layout.py \
  --reference PATH/TO/OLD/FairyGUI.fairy --target PATH/TO/NEW/FairyGUI.fairy \
  --component ju_example/PopupExample

流程与确认格式见 换皮位置复用与差异验收。工具不移动节点、不连接编辑器、不新增 Bridge Action；源检查不代替编辑器默认状态或游戏动态状态验收，插件无需因此重启。

百分比进度条验收

FTS 百分比条使用同一 0–100 显示值更新条与文字，默认平铺填充纹理。随 Skill 分发的 scripts/check_progress_bars.py --project <FGUI_PROJECT> --component <PACKAGE/COMPONENT> 只读检查有效实例值、数字百分比与填充资源；可重复指定组件。完整适用范围及边界见 进度条制作与验收。此项为 Skill 检查，不新增 Bridge Action，不替代原生预览或游戏验收。

组件化制作与结构验收（0.9.1）

新 UI 先按职责确定组件清单，查找已有资源，先制作子组件再组装父组件；独立功能区和重复项使用真实组件引用，普通装饰不强制包装。MCP instructions 提供入口约束，Skill 同时覆盖 MCP/CLI 和直接生成 XML；Group、未引用的空组件或一整张截图不算完成组件化。

制作前保存结构计划，完成后用随 Skill 分发的只读脚本检查已保存 XML。完整规则、计划格式和边界见 组件化制作与验收。

# 独立样例：功能区拆分、跨包重复复用，以及直接保留的普通装饰
uv run python .agents/skills/fgui-agent-bridge/scripts/check_component_structure.py \
  --project tests/fixtures/componentization \
  --plan tests/fixtures/componentization/structure-plan.json
uv run python -m unittest discover -s tests -p 'test_component_structure.py' -v

脚本只读、不连接或唤醒编辑器，检查引用/归属/循环依赖等结构；它不判断业务边界，也不能替代编辑器重开、视觉、动态资源或运行时验证。当前未增加“提取旧节点为组件”工具，不自动修改已有界面。

MCP instructions 需要重启对应 MCP 服务后重新加载；Skill 更新时需同步 references 和 scripts。测试代码只写临时副本，Editor 实测应使用样例副本且不得切换用户工作中的业务文档。组件化能力自 0.9.1 提供，无需为使用只读脚本改动业务工程。

1. Transition 动效规范

• 全轨道支持：覆盖 XY、Size、Pivot、Scale、Skew、Alpha、Rotation、Color、Animation、Visible、Sound、Transition、Shake、ColorFilter、Text、Icon 全部原生轨道。

• 时间单位：统一使用 FairyGUI frame 帧单位。

• 事务性：整段声明式更新或关键帧原子操作均进入事务栈，支持 fgui_undo / fgui_redo。

2. MovieClip 序列帧机制

• 接收有序本地图片列表，通过 FairyGUI AniData.ImportImages 嵌入 .jta 文件，不会在包内产生多余的散图 ui://。

• FPS 范围 1..255，支持 Repeat Delay、每帧 Delay、Speed 与 Swing。

• 已有 MovieClip 的更新支持文件快照回退；全新创建/删除属于磁盘级操作，删除时需显式提供 force=true 且无外部引用。

3. 大图自动独立图集规则

• 规则触发：图片分辨率达到 1920×1080，或任意一边达到 2048（2K）时，会自动标记为 FairyGUI alone 单独纹理集。

• 自动补齐：通过 fgui_import_image 导入时即时生效；执行 fgui_publish 发布时还会自动扫描目标包并纠正历史大图配置，防止大图与小图碎图混排导致图集膨胀。

4. 编辑器内公共包同步

• FairyGUI 的“工具”菜单提供“同步公共包到当前工程”和“同步公共包到全部已接入工程”。

• 插件从当前工程向上定位最高层的 assets/ju_common 作为真源，同时支持 ju_common_coins。

• “同步当前工程”会安装或镜像更新公共包；“同步全部”只处理已经存在任一公共包的 .fairy 工程，并为这些工程补齐两个公共包，不会把公共包强行安装到无关工程。

• 同步采用临时目录切换，目标包会与真源完全一致并清除遗留文件；存在未保存文档时拒绝执行，完成后自动刷新当前工程。

❓ 常见问题与排错 (FAQ)

⚠️ 当前限制

• 兼容基线：以 FairyGUI Editor 6.1.4 为主要验证版本。

• 动画类型：专注于 FairyGUI 原生 Transition 与 MovieClip，不支持 Spine、DragonBones、Loader3D、SWF 等第三方动画格式。

• 资源管理边界：暂不支持通用包内资源的任意重命名与跨包移动；MovieClip 删除需带引用校验与 force=true。

• 平台环境：macOS 已有部分真实 Editor 验收记录，具体范围见 当前能力参考；Windows 及其他 Editor 版本尚未完整验证。

🔄 升级与同步

git pull
uv sync --frozen
uv run python scripts/sync_to_project.py --global-plugin --apply

提示：也可以直接对你的 Agent 说 “/fgui-agent-bridge 帮我更新”。更新插件后重新启动 FairyGUI Editor 即可。只有当 Bridge 仓库路径或启动命令变更时才需更新 MCP 配置。

🛠️ 开发与维护

• 插件 TypeScript 源码：plugin/main.ts

• 插件运行时编译文件：plugin/main.js

• Python MCP & CLI：src/fairygui_agent/

• Agent Skill：.agents/skills/fgui-agent-bridge/

• 同步脚本：scripts/sync_to_project.py

开发需要 Node.js / npm（编译插件和运行宿主回归），Python 依赖由 uv.lock 固定。main.ts 是插件源码，main.js 是随仓库交付的可读运行文件，必须由源码生成，不手工修改。Python、Skill 和检查脚本均以原始文本源码交付。

uv sync --frozen
npx -y -p typescript@5.4.5 tsc -p plugin/tsconfig.json --pretty false
uv run python -m unittest discover -s tests -v
git diff --check

每次维护先修改源码，再同步受影响的 MCP / CLI、测试、Skill、README 和 更新记录。插件行为变化时同步版本与编译文件；检查生成文件未漂移、回归通过后提交并推送本仓库。编辑器实测使用隔离工程，报告已验证和未验证范围；单个界面通过不代表全部皮肤通用。不要上传业务工程、美术资源、运行队列、日志、凭据、缓存或个人路径。欢迎通过本仓库的 Issue / Pull Request 参与修改。

维护注意：修改 plugin/main.ts 后必须重新生成并提交 plugin/main.js；版本升级需同步修改 plugin/package.json、pyproject.toml、Python __version__ 以及插件源码版本号。

🔗 相关生态推荐

• 蓝湖 MCP (lanhu-mcp)：配合本工具，可以让 AI 编程 Agent 自动从蓝湖设计稿下载切图、导出标注，并直接在 FairyGUI 中拼装好 UI 界面并发布。

📄 许可证

MIT License