编辑器视图
概述
编辑器视图是允许您在 AI 对话界面中直接操控 Unity/Tuanjie 编辑器。它不是一个 3D WebGL 场景查看器，而是一个工具执行与结果展示系统——通过 TCP 桥接与运行中的 Unity 编辑器实时通信，将工具调用结果以卡片形式呈现在聊天界面中。
支持引擎
- Unity
- Tuanjie
环境要求与安装
前置条件
| 项目 | 要求 |
|---|---|
| Node.js | ≥ 20.19.0 |
| Unity 编辑器 | 需正在运行且项目已打开 |
| 桥接包 | cn.tuanjie.codely.bridge |
安装 Unity 桥接包
项目检测
系统会自动检测当前目录是否为 Unity 项目，检查内容：
- 项目根目录中是否包含 Unity 项目标识文件
- 是否已安装
cn.tuanjie.codely.bridgeMCP 包 - 引擎类型（Unity 或 Tuanjie）及版本号
连接状态与指示器
状态类型
| 状态 | 含义 | 图标颜色 |
|---|---|---|
connected | 已连接到 Unity 编辑器 | 🟢 绿色 |
connecting | 正在连接中 | 🟡 黄色 |
not-connected | 未连接 | - |
reconnecting | 重连中 | 🟡 黄色 |
error | 连接错误 | 🔴 红色 |
截图功能
支持的相机类型
| 相机 | 说明 |
|---|---|
| Game View | 游戏视图截图 |
| Scene View | 场景视图截图 |
| Main Camera | 主相机截图 |
| Custom Camera | 指定相机截图 |
截图卡片 UI
截图完成后，聊天界面中会显示截图卡片：
- 显示截图图片（
object-fit: contain，最大高度 400px） - 标注相机视图 来源（Game View / Scene View）
- 加载中显示旋转动画
- 截图失败显示错误状态
- 支持点击放大查看
附加选项
- 自定义分辨率
- 正交投影模式
截一张 Game View 的截图
从 Scene View 截取一张 1920x1080 的截图
故障排除
常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 状态显示"未连接" | Unity 编辑器未运行或桥接包未安装 | 启动 Unity 编辑器并确认桥接包已安装 |
| 连接后频繁断开 | TCP 端口被占用或防火墙拦截 | 检查端口 25916 是否可用，检查防火墙规则 |
| 工具调用无响应 | Unity 编辑器正在编译/加载中 | 等待编译完成后重试 |
| 脚本修改后报错 | 编译失败 | 查看控制台错误日志，修正代码 |
| 截图捕获失败 | Game View 未打开或相机不存在 | 确保目标视图/相机可用 |
| 资产生成卡在进度中 | 生成器异常或网络问题 | 检查 Unity 控制台错误，确认网络连接 |
最佳实践
- 先读后写：修改前先读取当前状态，避免覆盖重要更改
- 幂等优先：使用
ensure_*操作替代add/create，避免重复创建 - 编译验证：修改脚本后始终检查编译结果
- 场景保存：在烘焙、播放或完成重要操作前保存场景
- 控制台分离：在执行有风险的操作前记录
sinceToken，只关注新产生的日志 - 避免播放模式写入：除非明确调试播放行为，否则不在播放模式下修改场景
重置连接
如果连接异常，可以尝试：
- 点 击 Unity 开关按钮禁用后重新启用
- 在 Unity 编辑器中重新导入桥接包
- 重启 Unity 编辑器
附录：工具输出卡片类型
UnityToolOutput 组件根据工具和操作的返回数据类型，渲染不同的卡片：
| 输出类型 | 渲染形式 |
|---|---|
| 控制台日志 | 日志条目列表 |
| GameObject 信息 | 对象详情卡片 |
| 组件列表 | 组件属性表格 |
| 数据网格 | 表格形式 |
| 警告 | 黄色提示条 |
| 错误 | 红色错误卡片 |
| 截图 | 图片展示 |
| 资产预览 | 带缩放的预览图 + 元信息 |
| JSON 数据 | 格式化代码块 |