git:20261006.645263a to git:20261011.7d175a8

29 added, 29 removed. Audit A to A.

---

name: unity-cli

- description: 安装和修复 DGame Unity CLI，使用内嵌 Pipeline 与项目级 Workflow 排查 CLI/MCP 连接，查询 Unity Editor/Development Player，执行编译、测试和受控验证。涉及 CLI 安装、连接配置或实际 Unity 状态时使用；纯源码或文档任务不连接 Editor。

+ description: 使用本项目 Unity CLI 查询和验证 Editor/Development Player，操作场景、Prefab、组件和资源数据库，执行编译、测试和构建预检。涉及实际 Unity 状态、CLI 安装或连接排查时使用；纯源码或文档任务不连接 Editor。

---

# DGame Unity CLI

- ## 版本约束

- 本项目 Unity CLI 的指定版本以 [tool-versions.json](../../scripts/tool-versions.json) 的 `unityCli` 字段为唯一依据，操作前读取该值。安装、修复及 PATH 回退都必须匹配该值；`doctor` 对实际 `--version` 做精确比较，不匹配时报告 blocked，不自动替换工具。

+ ## 执行入口

- `beta` 渠道或 `latest` 不代表本项目指定版本。用户明确要求调整版本时，更新版本配置，再按操作规程重新验收。

+ Unity CLI 原生命令通过客户端已加载的 MCP 工具或 `unity command <name>` 调用。MCP 工具已暴露时直接使用其描述与参数，先以 `editor_status.projectPath` 核对当前工程；不要求服务名为 `unity-dgame`，也不要求每次读取客户端配置或运行本地 CLI。未暴露对应工具时，直接 CLI 固定 `--project-path <GameUnity 绝对路径>`；Player 使用明确的 `--runtime-path`。

- ## 执行入口

+ 直接 CLI 优先解析 `GameUnity/Tools/unity.exe`，缺少时解析 PATH 中的 `unity`，首次使用或入口变化时核对实际 `--version` 与 [版本配置](../../scripts/tool-versions.json)。无命令名的 `unity command --project-path <绝对路径>` 可发现当前注册命令。CLI 不是 Unity Editor 的同名程序。

- 从仓库根目录运行 `python .agents/scripts/workflow.py doctor`。脚本固定把 `GameUnity` 作为 Unity 工程；CLI 优先使用 `GameUnity/Tools/unity.exe`，文件缺少时从系统 `PATH` 查找 `unity`。此 CLI 与 Unity Editor 自身的 `Unity.exe` 是不同程序。

+ MCP 工具由客户端配置的 `unity mcp` 服务提供，Pipeline 为原生命令提供描述和参数 Schema；技能不注册工具，Workflow 也不负责 MCP 发现。`agents/openai.yaml` 的自动调用策略用于技能选择，不设置工具优先级。普通原生命令不需要 Workflow 白名单、包装脚本或审批文件。

- 用户要求安装或修复 CLI 时，按 [操作规程](references/operations.md) 的安装与验收步骤处理。常规使用先运行 `python .agents/scripts/workflow.py doctor` 记录当前 CLI 的绝对路径、版本和 SHA-256，再运行 `python .agents/scripts/workflow.py unity list` 获取当前 DGame 工程注册命令。查询示例：`python .agents/scripts/workflow.py unity query list_open_scenes`。

+ 查询、验证、安装与 MCP 接入统一见 [操作规程](references/operations.md)，按任务读取对应章节。组合验证、CI 和报告按需使用 [项目 Workflow](../../README.md)，Luban 生产导表使用 [luban-dev](../luban-dev/SKILL.md)。

- 用户要求 MCP 接入时，使用 CLI 自带的 `mcp` stdio 服务，固定 CLI 和工程的绝对路径；具体配置与验证见操作规程。

+ | 操作 | 原生命令 / 对应 MCP 工具 |

+ |---|---|

+ | 工程与场景查询 | `editor_status`、`list_open_scenes` |

+ | 脚本编译 | `test_status` 确认无活动测试 → `recompile` → `recompile_status` |

+ | 测试 | `list_tests` → `test_status` 确认无活动测试 → `run_tests` → `test_status` |

## 不变量

- - Unity Editor 查询、编译、测试和写入串行；只绑定当前 `DGame/GameUnity` 的绝对路径。新操作前要求唯一实例且 ready；已审核的状态轮询允许观察 busy/compiling。

- - 源码使用代码编辑工具修改；CLI 与 MCP 都只调用已审核的查询和验证能力，不绕过 Workflow 的写入预览与审批。

- - 未知命令、任意 eval、菜单透传和跨工程实例默认阻塞。

- - 写入操作先 preview，再由用户明确确认后执行；请求超时先检查实际状态，禁止自动重放。

- - 测试先发现用例，分别核对模式、筛选器、执行数和终态；零用例、全跳过、失败或取消都不通过。

- - 缺少工具、命令或连接时报告具体原因。安装、替换和配置按用户当前任务及已有授权处理；Workflow 本身不会自动安装、升级或启动 Editor。

- - 不将 Pipeline 实例描述文件中的鉴权信息输出到日志或提交到仓库。

+ - 只绑定当前 DGame 工程；导入、编译、测试与写入串行。新操作前核对唯一目标及状态，查询和轮询允许观察忙操作；直接 MCP/CLI 不经过 Workflow 工程锁。

+ - 源码用代码编辑工具修改，对象、序列化与资产用已注册命令；不通过文本写入、任意 eval、菜单或 Scene/Prefab YAML 绕过编辑和授权规则。

+ - 普通操作按用户任务及已有授权执行；先明确目标和影响范围，支持 `dry_run` 时直接预览，不支持时读取目标并说明变更。删除、覆盖、依赖、设置、平台和真实构建按仓库授权边界处理，`confirm` 不代替用户授权。

+ - 按命令真实实现核对副作用、`dry_run`/`confirm` 与 Undo 能力，执行后回读目标。超时先检查状态，禁止换入口自动重放写入。

+ - 编译或测试启动前查询 `test_status`；已有测试运行时等待，不依赖 `editor_status=ready` 判断测试空闲，不取消或覆盖已有测试。

+ - 异步命令检查触发响应，在调用方设定的总体期限内轮询终态；编译/测试默认每阶段 300 秒，超期报告 blocked/结果未知并保留现场，不自动取消或重放。测试先发现用例，按任务选择模式和筛选器，核对执行数与结果。零用例、全跳过、失败、取消或旧结果不能通过。

+ - 连接、命令或必需依赖缺失时报告具体 blocked 原因；不自动安装、升级、启动 Editor、修改用户配置或借用其他工程。Pipeline 鉴权信息不得输出。

- ## 常用命令

+ ## 权威资料

- ```powershell

- python .agents/scripts/workflow.py doctor

- python .agents/scripts/workflow.py check

- python .agents/scripts/workflow.py unity list

- python .agents/scripts/workflow.py unity query list_open_scenes

- python .agents/scripts/workflow.py unity runtime-status --runtime-path <player-working-directory>

- python .agents/scripts/workflow.py unity preview <mutation> --params-file request.json

- python .agents/scripts/workflow.py verify --profile code

- python .agents/scripts/workflow.py verify --profile unity --test-filter GameLogic

- ```

+ 按任务读取 `GameUnity/Packages/com.unity.pipeline/Documentation~/`：

- CLI 启动参数以当前可执行文件的帮助为准；Editor 命令以实时注册描述和 `GameUnity/Packages/com.unity.pipeline/Documentation~` 为准。截图、资源写入、构建和 Player 操作需要单独验证和授权。

+ | 场景 | 包内文档 |

+ |---|---|

+ | 连接、鉴权、Player | `connectivity.md`、`runtime-setup.md` |

+ | 路径、预览、Undo | `safety-and-mutations.md`、`authoring-commands.md` |

+ | 编译、测试、构建 | `commands/build-and-compilation.md` |

+ | 资源、对象、Prefab | `commands/assets-and-files.md`、`commands/gameobjects-and-components.md`、`commands/prefabs.md` |

+ | 截图、场景、设置 | `commands/capture.md`、`commands/scenes.md`、`commands/project-settings.md` |

+ | 新增项目命令 | `creating-commands.md` |

- 配置表导出交给 [luban-dev](../luban-dev/SKILL.md)，业务框架 API 交给 [dgame-dev](../dgame-dev/SKILL.md)。

+ 实时工具描述、CLI 帮助和源码优先于示例。截图需核对真实视图及输出路径，不等于视觉验收；业务框架 API 使用 [dgame-dev](../dgame-dev/SKILL.md)。