Unity Tools

Unity Tools 是 Codely CLI 内置的 实时 Unity Editor 控制工具集，通过直接 TCP Socket 连接到运行中的 Unity Editor，对场景、GameObject、脚本、资产、烘焙等进行读写操作。

与 Unity Insight（基于索引的只读分析）不同，Unity Tools 直接操控 实时运行 的 Unity Editor，支持创建、修改、删除等写操作。

属性	说明
工具数量	17 个核心工具 + 1 个刷新工具（`unity_refresh`），共 18 个
连接方式	直接 TCP Socket（非 MCP 协议）
默认端口	`25916`
配置文件	`.com-unity-codely.json`（项目根目录）
注册位置	`UnityToolsManager` + `UnityRefreshTool`
前提条件	Unity Editor 需运行并安装 Codely Bridge 包

连接管理

配置文件

Unity Tools 通过 .com-unity-codely.json 配置文件自动检测 Unity 项目。该文件由 Unity Editor 中的 Codely Bridge 包自动生成。

{
  "unity_port": 25916,
  "unity_host": "localhost",
  "created_date": "2025-09-17T06:45:29Z",
  "project_path": "E:/UnityProject/Assets",
  "reloading": false,
  "reason": "ready",
  "seq": 1,
  "last_heartbeat": "2025-09-17T09:09:29Z"
}

字段	类型	必填	说明
`unity_port`	number	是	TCP 端口
`unity_host`	string	否	主机地址，默认 `localhost`
`created_date`	string	否	创建时间
`project_path`	string	否	Unity 项目 Assets 路径
`reloading`	boolean	否	Unity 是否正在重载
`reason`	string	否	当前状态原因
`seq`	number	否	序列号
`last_heartbeat`	string	否	最后心跳时间

自动检测行为

配置文件存在：Codely 自动使用指定端口连接
无配置文件：Codely 正常运行，不启用 Unity 集成
配置无效：记录警告，继续运行不启用 Unity 集成

配置文件查找：从当前目录开始 向上遍历目录树，直到找到配置文件或到达文件系统根。

CLI 连接命令

在 CLI 中使用 /upm 斜杠命令管理连接：

命令	说明
`/upm status`	查看连接状态和工具数量
`/upm refresh`	重新读取 `.com-unity-codely.json` 并重连（不接受端口参数）
`/upm install`	安装/更新 Codely Bridge 包到当前 Unity 项目

自动连接流程

Codely CLI 启动时，对于包含 .com-unity-codely.json 的工作区：

读取 .com-unity-codely.json 获取端口
BuiltinUpmManager.getInstance() 创建 TCP 客户端
UnityTcpClient.getInstance() 建立连接（单例模式，host/port 从配置文件读取）
连接成功后调用 UnityIntegrationService.onUpmConnected()
UnityToolsManager.registerTools(toolRegistry) 注册 17 个工具
UnityRefreshTool.register(toolRegistry) 注册刷新工具
注入 Unity 系统提示

工具总览

核心工具（17 个，由 `UnityToolsManager` 注册）

#	工具名	类	Unity 命令	说明
1	`unity_editor`	`ManageEditorTool`	`manage_editor`	编辑器状态、编译、Play 控制、标签/层
2	`unity_workflow`	`UnityWorkflowTool`	`manage_workflow`	高级工作流压缩
3	`unity_scene`	`ManageSceneTool`	`manage_scene`	场景管理
4	`unity_gameobject`	`ManageGameObjectTool`	`manage_gameobject`	GameObject 和组件操作
5	`unity_console`	`ReadConsoleTool`	`read_console`	控制台消息读取/清除
6	`unity_script`	`ManageScriptTool`	`manage_script`	C# 脚本 CRUD
7	`unity_shader`	`ManageShaderTool`	`manage_shader`	着色器管理
8	`unity_asset`	`ManageAssetTool`	`manage_asset`	资产管理
9	`unity_package`	`ManagePackageTool`	`manage_package`	UPM 包管理
10	`unity_bake`	`ManageBakeTool`	`manage_bake`	NavMesh/光照烘焙
11	`unity_ui_toolkit`	`ManageUIToolkitTool`	`manage_ui_toolkit`	UI Toolkit 资产
12	`unity_menu`	`ExecuteMenuItemTool`	`execute_menu_item`	菜单项执行
13	`unity_screenshot`	`ScreenShotTool`	`manage_screenshot`	截图
14	`unity_gameview`	`ManageGameViewTool`	`manage_gameview`	Game View 分辨率
15	`unity_input`	`ManageInputTool`	`manage_input`	模拟输入
16	`execute_custom_tool`	`ExecuteCustomTool`	(自定义)	执行自定义工具
17	`execute_csharp_script`	`ExecuteCSharpScript`	(C# 脚本)	执行 C# 脚本（内联代码或文件路径）

额外工具（单独注册）

#	工具名	类	说明
18	`unity_refresh`	`UnityRefreshTool`	重新读取配置并重连 TCP（参数为空 `{}`）

工具详解

`unity_editor` — 编辑器控制

控制 Unity 编辑器状态（播放/暂停/停止）、检索项目信息、管理编译、窗口、选择、标签和层。

必填参数： action

Action	说明	关键参数
`get_current_state`	获取完整 UnityCurrentState 状态快照	—
`request_compile`	请求编译（返回 `op_id`）	—
`start_compilation_pipeline`	启动编译流水线（返回 `op_id` + `since_token`）	—
`wait_for_compile`	等待编译完成	`op_id`（必填）、`timeoutSeconds`（默认 60）
`get_compilation_summary`	获取编译摘要	—
`wait_for_idle`	等待编辑器空闲	`timeoutSeconds`（默认 600）
`play` / `pause` / `stop`	Play Mode 控制	—
`get_state`	获取状态（同 `get_current_state`）	—
`get_project_root`	获取项目根路径	—
`get_windows`	获取打开的窗口列表	—
`get_active_tool`	获取当前激活工具	—
`set_active_tool`	设置编辑器工具	`toolName`（View, Move, Rotate, Scale, Rect, Transform, Pan）
`get_selection`	获取当前选择	—
`focus_window`	聚焦窗口	`windowType`（Console, Inspector, Hierarchy, Project, Scene, Game 等）
`ensure_tag` / `add_tag` / `remove_tag` / `get_tags`	标签管理	`tagName`（1-255 字符）
`ensure_layer` / `add_layer` / `remove_layer` / `get_layers`	层管理	`layerName`（≥1 字符）

限制： request_compile 和 start_compilation_pipeline 在 Play/Paused 模式下被阻止（错误码 compile_blocked_in_play_mode）。最多 32 个层（8 个内置 + 24 个用户槽位 8-31）。ensure_tag/ensure_layer 为幂等操作。

`unity_workflow` — 高级工作流

将常见多步骤模式压缩为单次工具调用。

必填参数： action

Action	等价操作	说明
`init_session`	`get_current_state` → `console.clear`（返回 sinceToken）→ `wait_for_idle`	初始化会话
`compile_and_validate`	`start_compilation_pipeline`（返回 op_id + since_token）→ `wait_for_compile(op_id)` → `console.get(since_token)`（返回 hasErrors/hasWarnings）	编译并验证
`checkpoint`	`ensure_scene_saved` → 可选截图	检查点保存
`install_package_and_validate`	安装 UPM 包并验证编译	`id_or_url`（必填）、`version`、`screenshot`（默认 true）、`screenshotAction`、`screenshotPath`、`screenshotFilename`、`timeoutSeconds`

`unity_scene` — 场景管理

管理场景的创建、加载、保存、层级查看和构建设置。

必填参数： action

Action	说明	关键参数
`ensure_scene_open`	确保场景已打开（幂等）	`name`、`path`（默认 `Assets/Scenes/`）
`ensure_scene_saved`	确保场景已保存（幂等）	—
`create`	创建新场景	`name`、`path`（默认 `Assets/Scenes/`）
`load`	加载场景	`name` 或 `build_index`
`save`	保存当前场景	—
`get_hierarchy`	获取场景层级	—
`get_active`	获取当前活动场景信息	—
`get_build_settings`	获取构建设置	—

注意： Unity 引擎使用 .unity 扩展名；Tuanjie 引擎使用 .scene 扩展名。搜索场景文件时需同时检查 *.unity 和 *.scene。

`unity_gameobject` — GameObject 管理

对 GameObject 进行创建、修改、删除、查找、子级列举和组件管理。

必填参数： action

Action	说明
`create_batch`	批量创建（最多 10 个操作，支持 `captureAs` + `$alias` 引用）
`edit_batch`	批量编辑（查找后写入，0 匹配时提前停止返回成功）
`ensure_component`	确保组件存在（幂等）
`ensure_renderer_material`	确保渲染器材质（幂等）
`ensure_mesh_collider_mesh`	确保网格碰撞器网格（幂等）
`ensure_prefab_default_sprite`	确保预制体默认精灵（幂等）
`create`	创建单个 GameObject
`modify`	修改 GameObject
`delete`	删除 GameObject
`find`	查找 GameObject
`list_children`	列出子级
`select`	选择 GameObject
`add_component` / `remove_component`	添加/移除组件
`set_component_property` / `set_component_properties`	设置组件属性（后者为前者的别名）
`get_components`	获取组件列表

关键参数：

target（string|number）或 targetRef（对象：id、name、hierarchy_path）
searchMethod：by_name、by_id、by_path、by_tag、by_layer、by_component（默认 by_name）
position/rotation/scale：各为 3 元素数字数组
primitiveType：Cube、Sphere、Capsule、Cylinder、Plane、Quad
componentsToAdd/componentsToRemove：字符串数组
saveAsPrefab（默认 false）、prefabPath、prefabFolder（默认 Assets/Prefabs）
resultMode：auto、inline、file（默认 auto）、maxInlineItems（默认 200）
批量参数：mode（stop_on_error/continue_on_error，默认 stop_on_error）、ops（数组，maxItems 10）

`unity_console` — 控制台

读取或清除 Unity 编辑器控制台消息。清除操作返回 since_token 用于增量读取。

必填参数： 无（action 默认 get）

Action	说明
`get`	获取控制台消息
`clear`	清除控制台（返回 `since_token`）

get 参数：

types：消息类型数组（error、warning、log、assert、exception、all），默认 ["error", "warning", "log"]
count：1-1000，默认 200
filterText：文本过滤
since_token：增量读取令牌（来自 clear）
format：plain、detailed、json（默认 detailed）
includeStacktrace：默认 true

clear 参数：

scope：all、errors_only（默认 all）

`unity_script` — 脚本管理

创建、读取、更新、删除和验证 C# 脚本。支持事务性文本编辑（apply_text_edits）。

必填参数： action、name

Action	说明
`create`	创建 C# 脚本
`read`	读取脚本内容
`update`	更新脚本内容
`delete`	删除脚本
`validate`	验证脚本
`get_sha`	获取脚本 SHA256 哈希
`apply_text_edits`	事务性文本编辑
`edit`	编辑操作

关键参数：

name：脚本名（不含 .cs，必填）
path：文件夹路径（默认 Assets/Scripts）
contents：脚本内容
scriptType：MonoBehaviour、ScriptableObject、Editor、EditorWindow、Custom（默认 MonoBehaviour）
namespace：命名空间
level：验证级别（basic、standard、strict、comprehensive，默认 standard）
edits：文本编辑数组，每项含 startLine/startCol/endLine/endCol/newText（1 索引）
precondition_sha256：安全编辑前置哈希
options：validate、refresh（immediate/debounced）、applyMode（sequential/atomic）

`unity_shader` — 着色器管理

创建、读取、更新、删除 Unity 着色器文件。还支持 SRP 检测和按 SRP 映射设置材质着色器。

必填参数： action

Action	说明
`detect_render_pipeline`	检测当前渲染管线
`ensure_material_shader_for_srp`	按 SRP 确保材质着色器正确（幂等）
`create`	创建着色器
`read`	读取着色器
`update`	更新着色器
`delete`	删除着色器

关键参数：

name：着色器名（不含 .shader）
path：默认 Shaders
contents：着色器内容
shader_for_srp：对象，包含 builtin（必填）、urp?、hdrp?

`unity_asset` — 资产管理

创建、修改和管理 Unity 资产，包括材质、预制体、纹理、物理材质、脚本化对象等。

必填参数： action

Action	说明
`create_batch`	批量创建（最多 10 个操作）
`edit_batch`	批量编辑（查找后写入）
`import` / `import_asset`	导入资产（两者互为别名）
`ensure_has_meta`	确保 `.meta` 文件存在（幂等）
`ensure_meta_integrity`	确保 meta 完整性（幂等）
`create`	创建资产
`modify`	修改资产
`delete`	删除资产
`duplicate`	复制资产
`move`	移动资产
`rename`	重命名资产
`search`	搜索资产
`get_info`	获取资产信息
`create_folder`	创建文件夹
`get_components`	获取组件

asset_type 枚举值： Material、Texture、PhysicsMaterial、Prefab、Folder、AudioClip、AnimationClip、ScriptableObject

关键参数：

path：必须以 Assets/ 开头
asset_type / assetType：资产类型（create 必填）
properties：类型特定属性对象
destination：复制/移动/重命名目标路径
search_pattern、filter_type、filter_date_after（ISO 8601）
page_size（1-1000）、page_number（≥1）

限制： create action 仅允许 Folder/Material/PhysicsMaterial/ScriptableObject 四种 asset_type（其他类型会返回错误）。rename 需要目标完整路径在 Assets/ 下。资产（重新）导入开销大，应优先使用正常 Unity 导入、ensure_* 和脚本重编译。

`unity_package` — UPM 包管理

通过 UPM 管理包：安装/移除/列表/等待异步操作。

必填参数： action

Action	说明	关键参数
`install_package`	安装包	`id_or_url`（必填）、`version`
`remove_package`	移除包	`package_name`（必填）
`list_packages`	列出已安装包	—
`wait_for_upm`	等待 UPM 异步操作完成	`op_id`（必填）、`timeoutSeconds`（默认 300）

`unity_bake` — 烘焙

处理 NavMesh 和光照烘焙，支持异步操作追踪。可清除已烘焙的 NavMesh 和光照数据。

必填参数： action

Action	说明	关键参数
`bake_navmesh`	烘焙 NavMesh	`scope`、`async`（默认 false）、`options`
`bake_lighting`	烘焙光照	`scope`、`options`
`wait_for_bake`	等待烘焙完成	`op_id`、`timeoutSeconds`（默认 600）
`clear_navmesh`	清除 NavMesh 数据	—
`clear_baked_data`	清除已烘焙数据	—

scope 参数： active_scene、selection、whole_project（默认 active_scene）

`unity_ui_toolkit` — UI Toolkit

管理 UI Toolkit 资产，包括 PanelSettings、UXML 和 USS。

必填参数： action

Action	说明
`ensure_panel_settings_asset`	确保 PanelSettings 存在（幂等）
`link_uss_to_uxml`	链接 USS 到 UXML
`create_uxml`	创建 UXML 文件
`create_uss`	创建 USS 文件

`unity_menu` — 菜单执行

通过菜单路径执行 Unity 编辑器菜单项，或列出可用菜单。包含安全黑名单。

必填参数： 无（action 默认 execute）

Action	说明
`execute`	执行菜单项
`get_available_menus`	列出可用菜单

参数：

menu_path / menuPath：完整菜单路径（如 File/Save）
parameters：可选参数对象
timeout_ms：超时毫秒（默认 2000）
alias：别名

安全限制： 存在安全黑名单，当前仅包含 File/Quit 和 File/Exit。此外，工具描述中明确警告 Assets/Reimport All 等"极重"操作"几乎永远不应被模型使用"（但并未被黑名单硬阻止）。

`unity_screenshot` — 截图

从 Unity 编辑器捕获截图。支持 Game 视图、主相机、场景相机或指定名称的相机。

必填参数： action

Action	说明
`capture`	捕获 Game 视图截图
`capture_main_camera`	捕获主相机截图
`capture_specific_camera`	捕获指定相机截图
`capture_scene_camera`	捕获场景相机截图

参数：

path：保存路径
filename：文件名
width / height：分辨率（≥1）
cameraName：相机名称（capture_specific_camera 必填）

注意： Scene View 支持 shaded/wireframe/shadedwireframe 模式和动画 GIF 捕获。

`unity_gameview` — Game View 分辨率

获取、设置和列出 Unity Game View 分辨率。

必填参数： action

Action	说明	关键参数
`get_resolution`	获取当前分辨率	—
`set_resolution`	设置分辨率（选择已有或创建新的）	`width`（1-8192，必填）、`height`（1-8192，必填）
`list_resolutions`	列出可用分辨率	—

`unity_input` — 模拟输入

在 Unity PlayMode 中模拟鼠标和键盘输入，支持多帧序列。

必填参数： action

Action	说明
`mouse_click`	鼠标点击
`mouse_move`	鼠标移动
`mouse_drag`	鼠标拖拽
`mouse_scroll`	鼠标滚轮
`mouse_down` / `mouse_up`	鼠标按下/抬起
`key_press`	按键
`key_down` / `key_up`	按下/抬起
`type_text`	输入文本
`create_virtual_devices` / `destroy_virtual_devices`	创建/销毁虚拟设备
`sequence`	多步骤序列

关键参数：

x、y：目标坐标（Unity 屏幕空间，左下角原点，Y 向上）
button：0=左键、1=右键、2=中键（默认 0）
target：auto、ui、world（默认 auto）
key：Input System Key 枚举名（如 W、A、Space、Enter、LeftShift）
text：type_text 的文本内容
steps：sequence 的步骤数组，每步含 action + 参数 + 可选 delay_after
start_delay（默认 0 帧）、step_delay（默认 1 帧）、stop_on_error（默认 true）
drag_speed：拖拽速度（像素/秒，默认 500，0=瞬时）

重要限制：

设备键盘输入需要 Input System 包（com.unity.inputsystem），Active Input Handling 需设为 "Input System Package (New)" 或 "Both"

create_virtual_devices 必须在设备键盘输入或非 UI 鼠标操作之前调用

虚拟设备激活时，真实鼠标/键盘被禁用

type_text 不需要虚拟设备

点击 UI 前先截图以获取精确坐标

`execute_custom_tool` — 自定义工具

执行在 Unity 编辑器中注册的自定义工具。

必填参数： tool_name

参数：

tool_name：注册的自定义工具名（≥1 字符，必填）
parameters：工具特定参数对象（additionalProperties: true）

`execute_csharp_script` — 执行 C# 脚本

在 Unity 编辑器中执行 C# 脚本，使用 Microsoft.CodeAnalysis.CSharp.Scripting。捕获并返回脚本执行期间产生的日志。

必填参数： script、summary

参数：

script：C# 脚本代码或 .cs 文件的绝对路径（≥1 字符，必填）。当提供文件路径时，Unity 自动检测并读取文件内容，对于已存在的脚本文件优先使用此方式（无需先用 read_file 读取）
summary：脚本的简要目的说明（≥1 字符，必填），用于日志和审查
execution_mode：可选，play（脚本在 Play Mode 下运行）或 editor（脚本依赖编辑模式 API 如 AssetDatabase、场景编辑等）
capture_logs：是否捕获日志（默认 true）

`unity_refresh` — 连接刷新

重新读取 .com-unity-codely.json 并重新连接到 Unity Bridge。当其他 Unity 工具因 Bridge 过时/断开而失败时，调用此工具（参数为空 {}），然后重试原工具。

参数： 无（空对象 {}）

状态管理与异步操作

UnityCurrentState

每个工具响应可能包含 state（完整 UnityCurrentState）和 state_delta（增量变化）。状态修订追踪是内部的，不暴露模型提供的修订参数。

UnityCurrentState 包含：

字段	子字段	说明
`editor`	`playMode`、`isCompiling`、`isUpdating`、`lastCompilation`、`focusedWindow`、`requiresFocusForOperations`	编辑器状态
`project`	`srp`、`defineSymbols`、`packages`、`dirty`	项目信息
`scene`	`activeScenePath`、`dirty`、`hasNavMeshData`、`hasLightingData`	场景状态
`selection`	`activeObject`	当前选择
`console`	`sinceToken`、`unreadCount`、`lastErrors`	控制台状态
`assets`	`touched`（数组）	已触碰的资产
`operations`	`pending`（数组）	待处理操作
`policy`	`writeGuardInPlayMode`、`refreshMode`、`consoleReadPolicy`	策略配置

异步操作

异步操作（编译、烘焙、UPM）返回 PendingResponse：

{
  "status": "pending",
  "op_id": "abc123",
  "poll_interval": 2,
  "success": true
}

调用者必须使用对应的 wait_* action 和 op_id 轮询：

请求操作	等待操作
`unity_editor.start_compilation_pipeline`	`unity_editor.wait_for_compile(op_id)`
`unity_bake.bake_navmesh` / `bake_lighting`	`unity_bake.wait_for_bake(op_id)`
`unity_package.install_package` / `remove_package`	`unity_package.wait_for_upm(op_id)`

当 status 为 pending 时，必须继续轮询或处理超时，不可假设已完成。使用 poll_interval 控制轮询频率。

观察失效通知

成功的写操作可能标记状态为 dirty。系统可能发送中性软提醒（非错误）：[Unity notification: observation invalidated]、state=stale、console=token_invalidated，表示之前的状态/控制台观察可能已过时。

最佳实践

系统提示定义了 10 条最佳实践：

规则 1：State First（状态优先）— 写操作前必须读状态

写操作不需要模型提供修订参数；Unity 状态同步在内部处理。观察失效通知是中性提示，不是错误。推荐的会话启动模式：

首选（1 次调用）：unity_workflow { "action": "init_session" } — 读状态 + 清控制台 + 等待空闲
手动回退（3 步）：get_state → console.clear → wait_for_idle

规则 2：优先使用幂等 `ensure_*` 操作

对于配置类变更（标签、层、组件、材质、Mesh Collider、预制体默认精灵、PanelSettings、.meta 文件等），始终优先使用 ensure_* 操作。当目标状态已满足时，ensure_* 返回 state_delta.dirty: false 且不执行额外写入。

规则 2b：优先使用批量/工作流工具

优先 unity_workflow 压缩常见序列
优先 unity_asset.create_batch 处理重复/批量只写操作
优先 unity_gameobject.create_batch / edit_batch，使用 captureAs + $alias 引用避免手动 instanceID 管理

规则 3：脚本变更后必须编译 + 验证

首选（1 次调用）：unity_workflow { "action": "compile_and_validate" }
手动回退：start_compilation_pipeline（记录 op_id + since_token）→ wait_for_compile(op_id) → console.get(since_token)
永远不要仅依据 lastCompilation、wait_for_compile 或 get_compilation_summary 的字段判断"无编译错误"，必须检查 unity_console 输出

规则 4：在关键边界调用 `ensure_scene_saved`

不要盲目自动保存场景，但在以下操作前必须调用 unity_scene.ensure_scene_saved：

调用 unity_bake（NavMesh/光照烘焙）之前
调用 unity_editor.play（进入 Play Mode）之前
向用户报告任务"完成"之前

规则 5：长时间运行任务使用 request/wait 对

所有长时间运行操作必须拆分为请求 + 等待对，使用 op_id + status/poll_interval 轮询。

规则 6：控制台读取必须使用 `sinceToken` 分隔

对于需要区分新旧日志的操作，遵循 快照 → 操作 → 读新日志 模式：

操作前记录 sinceToken 或清除控制台并记录新 token
操作后使用原 sinceToken 调用 unity_console，只查看操作后的日志
收到观察失效通知后，之前的 token 可能已失效，需建立新的控制台边界

规则 7：Play Mode 默认写保护

当 editor.playMode != 'stopped' 时，应避免写操作，除非任务明确是调试 Play Mode 行为。如果工具返回 write_blocked_in_play_mode 错误，切换为只读策略。

规则 8：禁止使用资产重新导入作为常规刷新

禁止通过 unity_menu 使用 Assets/Reimport All 等菜单命令作为通用"刷新/编译"方案。

规则 9：每个写操作必须是"执行 → 确认 → 继续"循环

任何写操作（包括 ensure_*）后，必须在叠加更复杂逻辑之前显式确认新状态。不确定时调用 unity_editor.get_state 检查 state_delta / scene.dirty / assets.touched。

规则 10：工具职责不混用

每个工具有明确职责范围，不应混用。例如 unity_menu 仅用于真正需要菜单命令的场景，不是刷新/编译/保存的主路径。

配置选项

工具排除

UnityToolsManager.registerTools() 接受 excludeTools 参数，按工具名排除。排除逻辑通过 normalizeExcludedToolSet() 处理，同时影响工具注册和系统提示生成。UnityRefreshTool.register() 同样接受 excludeTools，支持通配符匹配（* 后缀）。

事件日志

UnityToolsManager.setUserConfig(token, options) 配置工具调用事件日志：

选项	类型	默认	说明
`baseUrl`	string	`https://codely.tuanjie.cn`	事件上报地址
`profileId`	string	—	用户 ID
`projectName`	string	—	项目名
`repoName`	string	—	仓库名
`enabled`	boolean	true	是否启用
`platform`	string	`""`	平台标识

在 CODELY_OAUTH 认证成功后通过 UnityIntegrationService.configureUnityToolEventLogging() 自动配置。

调试模式

UnityTcpClient.setDebugMode(boolean) — 启用详细 TCP 日志
config.getDebugMode() — 控制工具注册日志

故障排查

无法连接到 Unity

症状： CLI 启动时显示连接失败。

排查步骤：

确认 Unity Editor 正在运行。
确认 Codely Bridge 包已安装到 Unity 项目。
确认项目根目录存在 .com-unity-codely.json 文件。
使用 /upm status 检查连接状态。
使用 /upm refresh 重新读取 .com-unity-codely.json 并重连。
默认端口为 25916；如 Unity 使用其他端口，在 .com-unity-codely.json 中检查 unity_port。

Unity 域重载期间工具超时

症状： 工具调用在 Unity 编译/重载期间超时。

说明： 这是预期行为。Unity 域重载期间，TCP 客户端会自动重试：每 1000ms 轮询一次，最多 40 次（40 秒窗口）。连接失败最多重试 10 次，使用指数退避 + 抖动。

解决方案： 等待 Unity 完成域重载后重试，或使用 unity_refresh 工具重新连接。

工具返回 `write_blocked_in_play_mode`

症状： 在 Play Mode 下执行写操作时返回此错误。

解决方案： 先调用 unity_editor.stop 退出 Play Mode，或切换为只读策略。

工具返回 `compile_blocked_in_play_mode`

症状： 在 Play/Paused 模式下调用 request_compile 或 start_compilation_pipeline 时返回此错误。

解决方案： 退出 Play Mode 后再编译。

Unity Bridge 断开后工具不可用

症状： Unity Tools 调用失败，提示连接断开。

解决方案：

调用 unity_refresh（参数 {}）重新读取配置并重连。
或在 CLI 中执行 /upm refresh。
重连成功后重试原工具。

项目路径不匹配

症状： 连接后报错提示 Unity 的项目根路径与预期不匹配。

解决方案： 确保在正确的 Unity 项目目录下运行 Codely CLI，且 .com-unity-codely.json 中的 project_path 指向当前项目的 Assets 文件夹。

连接管理​

配置文件​

自动检测行为​

CLI 连接命令​

自动连接流程​

工具总览​

核心工具（17 个，由 UnityToolsManager 注册）​

额外工具（单独注册）​

工具详解​

unity_editor — 编辑器控制​

unity_workflow — 高级工作流​

unity_scene — 场景管理​

unity_gameobject — GameObject 管理​

unity_console — 控制台​

unity_script — 脚本管理​

unity_shader — 着色器管理​

unity_asset — 资产管理​

unity_package — UPM 包管理​

unity_bake — 烘焙​

unity_ui_toolkit — UI Toolkit​

unity_menu — 菜单执行​

unity_screenshot — 截图​

unity_gameview — Game View 分辨率​

unity_input — 模拟输入​

execute_custom_tool — 自定义工具​

execute_csharp_script — 执行 C# 脚本​

unity_refresh — 连接刷新​

状态管理与异步操作​

UnityCurrentState​

异步操作​

观察失效通知​

最佳实践​

规则 1：State First（状态优先）— 写操作前必须读状态​

规则 2：优先使用幂等 ensure_* 操作​

规则 2b：优先使用批量/工作流工具​

规则 3：脚本变更后必须编译 + 验证​

规则 4：在关键边界调用 ensure_scene_saved​

规则 5：长时间运行任务使用 request/wait 对​

规则 6：控制台读取必须使用 sinceToken 分隔​

规则 7：Play Mode 默认写保护​

规则 8：禁止使用资产重新导入作为常规刷新​

规则 9：每个写操作必须是"执行 → 确认 → 继续"循环​

规则 10：工具职责不混用​

配置选项​

工具排除​

事件日志​

调试模式​

故障排查​

无法连接到 Unity​

Unity 域重载期间工具超时​

工具返回 write_blocked_in_play_mode​

工具返回 compile_blocked_in_play_mode​

Unity Bridge 断开后工具不可用​

项目路径不匹配​

连接管理

配置文件

自动检测行为

CLI 连接命令

自动连接流程

工具总览

核心工具（17 个，由 `UnityToolsManager` 注册）

额外工具（单独注册）

工具详解

`unity_editor` — 编辑器控制

`unity_workflow` — 高级工作流

`unity_scene` — 场景管理

`unity_gameobject` — GameObject 管理

`unity_console` — 控制台

`unity_script` — 脚本管理

`unity_shader` — 着色器管理

`unity_asset` — 资产管理

`unity_package` — UPM 包管理

`unity_bake` — 烘焙

`unity_ui_toolkit` — UI Toolkit

`unity_menu` — 菜单执行

`unity_screenshot` — 截图

`unity_gameview` — Game View 分辨率

`unity_input` — 模拟输入

`execute_custom_tool` — 自定义工具

`execute_csharp_script` — 执行 C# 脚本

`unity_refresh` — 连接刷新

状态管理与异步操作

UnityCurrentState

异步操作

观察失效通知

最佳实践

规则 1：State First（状态优先）— 写操作前必须读状态

规则 2：优先使用幂等 `ensure_*` 操作

规则 2b：优先使用批量/工作流工具

规则 3：脚本变更后必须编译 + 验证

规则 4：在关键边界调用 `ensure_scene_saved`

规则 5：长时间运行任务使用 request/wait 对

规则 6：控制台读取必须使用 `sinceToken` 分隔

规则 7：Play Mode 默认写保护

规则 8：禁止使用资产重新导入作为常规刷新

规则 9：每个写操作必须是"执行 → 确认 → 继续"循环

规则 10：工具职责不混用

配置选项

工具排除

事件日志

调试模式

故障排查

无法连接到 Unity

Unity 域重载期间工具超时

工具返回 `write_blocked_in_play_mode`

工具返回 `compile_blocked_in_play_mode`

Unity Bridge 断开后工具不可用

项目路径不匹配