Hera Agent Unity

hera-agent-unity

让 AI 编码 Agent 在 Unity 中拥有双手、双眼和检查清单。

_{Codex、Claude、Cursor、Copilot、AntiGravity 以及其他支持 shell 的 Agent，可以检查实时运行的 Unity Editor、对其进行更改、运行和测试、查看结果，并持续修复，直到证据表明任务已完成。}

3 步开始使用 · 它能做什么？ · 为什么选择 Hera？ · 效果如何？ · 示例 · 命令

English · 한국어

一分钟了解 Hera

即使没有 Hera，AI 也能编写 Unity C#，但代码写完后，它无法可靠地了解你的实时 Editor是什么状态。

通常的工作循环如下：

You ask the AI
   ↓
AI writes code
   ↓
You open Unity and wait for compile
   ↓
You copy the error back to the AI
   ↓
AI fixes it
   ↓
You press Play and explain what happened
   ↓
repeat...

Hera 补上了这个循环：

You ask the AI
   ↓
AI uses Hera
   ↓
Unity compiles, runs, tests, clicks UI, captures the result
   ↓
Hera gives the real result back to the AI
   ↓
AI fixes what failed and checks again
   ↓
verified result

可以这样简单理解：

AI 是大脑。Hera 为这个大脑提供操作 Unity 的双手、检查结果的双眼，以及一份检查清单，确保项目仍有问题时它不会停下。

Hera 不会取代 Unity，也不会取代编码 Agent。它将两者连接起来，让 Agent 能根据你实际项目中的事实开展工作，而不是仅凭源代码猜测。

它解决什么问题？

Unity 开发的反馈循环发生在源文件之外。

一项更改在代码中看起来正确，仍可能因为以下原因而失败：

• Unity 未能编译；
• 打开了错误的 Scene；
• 缺少 GameObject 或 Component；
• Inspector 中的序列化值不同；
• Unity API 在你的 Editor 版本中发生了变化；
• Console 中有异常；
• Play Mode 的表现与 Edit Mode 不同；
• 按钮在视觉上存在，却无法接收输入；
• UI 布局从技术上看有效，外观却不正确；
• AI 在实际检查这些问题之前就声称“已完成”。

Hera 让 Agent 能够直接询问真实的 Editor。

hera-agent-unity status
hera-agent-unity console --type error
hera-agent-unity scene info
hera-agent-unity editor play --wait
hera-agent-unity test --mode PlayMode

如果所选的 Editor 尚未运行，Hera 可以在发现 Connector 之前启动对应的项目：

hera-agent-unity --project C:/Projects/Game editor launch
hera-agent-unity --project C:/Projects/Game editor restart

项目版本来自 ProjectSettings/ProjectVersion.txt；匹配的 Unity Hub 安装来自 UNITY_HUB_EDITOR 或平台默认路径（Windows 上为 %ProgramFiles%\Unity\Hub\Editor）。自定义 Hub 位置可通过 --hub-root 指定。启动时采用 Package Manager 的常规行为，而非 -noUpm，并会在新进程发布该项目对应的心跳信号后返回。在 Windows 上，如果 Agent shell 未设置标准的通用配置文件环境，Hera 也会为 Unity 子进程恢复该环境，确保 UPM 路径解析仍以与常规桌面启动相同的基准开始。

重要的不是命令名称，而是 Agent 能够观察 → 更改 → 运行 → 验证 → 修复，无需你在 AI 和 Unity 之间传递信息。

它究竟能做什么？

你可以用 Hera 执行一行的小型检查，也可以用它完成由 AI 辅助的完整 Unity 工作流。

简而言之，Hera 不只是一个“按下 Play”的远程工具。它是围绕运行中的 Unity 项目，贯穿整个编辑与检查循环的桥梁。

为什么使用 Hera？

1. AI 可以检查自己的工作

没有 Editor 访问权限时，Agent 往往会以这样一句话收尾：

“这应该能正常运行。”

借助 Hera，它可以用以下证据收尾：

compile: passed
console errors: 0
EditMode tests: 18/18
PlayMode tests: 6/6
button click: verified through EventSystem
final Game View: captured

这就是 Hera 存在的主要原因。

2. 你不再需要充当复制粘贴的中间人

你不再需要反复：

1. 从 AI 复制代码；
2. 切换到 Unity；
3. 等待编译；
4. 把错误复制回去；
5. 解释 Scene 层级结构；
6. 按下 Play；
7. 描述发生了什么。

AI 可以自行完成其中的大部分流程。

3. 它能与您现有的工具配合使用

常规的生产使用方式是 CLI。任何可以运行 shell 命令的 Agent 都能使用它。

• Codex
• Claude Code
• Cursor
• GitHub Copilot
• AntiGravity
• 脚本和 CI 作业
• 你自己的自动化工具

无需 Python 服务端，也不必配置宿主协议。

4. 它面向 AI 上下文设计，而不只是面向人类

庞大的工具响应意味着模型要读取更多输入。因此，Hera 会为常用命令提供精简视图，例如仅返回 ID 的 GameObject 搜索结果，以及按需提供的工具架构。

目标很简单：只向 Agent 发送足以做出下一步决策的最少 Unity 状态信息。

5. 它明白“请求已发送”不等于“工作已完成”

Unity 会重新编译脚本、重新加载域、更改端口、进入 Play Mode、运行测试，有时还会在此过程中断开连接。

Hera 会跟踪这些工作流，而不会把 HTTP 请求发送成功当作 Unity 已完成工作的证明。

6. 它可以随项目一起成长

从内置命令开始。之后，你可以为项目中每天重复的工作流添加一个 [HeraTool]：构建地牢房间、验证任务图、烘焙表格、生成测试战斗，或检查工作室专属的资源规则。

效果如何？

Hera 不会含糊地宣称拥有“AI 魔法”。仓库会保留具体的测量数据和兼容性证据。

常见 Agent 读取的响应较小

在测试的 Unity 版本中，list --compact 的实测低令牌基线约为 93 个估算令牌。在保留的跨版本测试样本中，find_gameobjects --ids 的实测结果为49 至 55 个估算令牌。

| Unity 编辑器 | list --compact | find_gameobjects --ids | | list --tool <name> --action <action> | 只读取所选操作的参数、结果和安全性。 | |:---|---:|---:| | 2022.3.62f2 | 93 T | 54 T | | 2023.2.22f1 | 93 T | 54 T | | 6000.3.5f2 | 93 T | 49 T | | 6000.5.0f1 | 93 T | 55 T |

T 是仅针对 Hera CLI 负载的简单估算值，计算方式为 ceil(UTF-8 bytes / 4)。它不是提供商的计费遥测数据。完整方法：令牌缩减基准测试。

在多个 Unity 代际中检查兼容性

支持的 Unity 版本为 Unity 6.6+（最低版本为 6000.6）。发布编译门禁会在一次性空项目中，将 Connector 的确切源代码作为常规 UPM 依赖项安装到指定的代表性编辑器版本中，并要求编译无误、发布门禁测试套件全部通过，且控制台错误为零：

该最低版本仅说明实际验证过的范围：单个代表性编辑器，不对任何其他 Unity 版本系列作出兼容性声明。AgentConnector/package.json 设定了 6000.6 的最低版本，因此 Package Manager 会在较旧的编辑器上拒绝安装 Connector，而不是等到编译时才失败。

CLI 和 Connector 的版本有意保持独立。

v0.2.0 在真实编辑器中进行了测试，而不只是通过编译测试

最终发布候选版本以 Connector 0.0.86 的身份加载到 Unity 6000.5.6f1 中，使用 Input System 1.20.0，并在发布前通过真实的 Play Mode 驱动。保留的冒烟测试证据记录了：

• 实时目录中包含 31 个工具 / 80 个操作；
• 在 Play Mode 中合成键盘按下/抬起和鼠标位置；
• 有界输入序列成功完成；
• 一次输入录制包含 5 个事件 / 588 字节，随后对同一文件成功重放两次；
• 重放后没有任何由 Hera 控制的输入仍处于按住状态；
• Connector ReleaseGateTests：18/18 PASS；
• 运行结束后 Unity Console 错误数：0；
• 编辑器正常关闭，且没有新增场景恢复备份（0）；同时，一次性测试清单和锁文件已恢复。

这为五版本编译矩阵补充了针对已发布功能集的端到端编辑器回归测试。

一次真实的游戏创建任务达成了经过验证的可玩结果

在保留的 Crystal Forge 场景中，要求 AI 编写代码和测试、构建 UI、编译、通过 Unity EventSystem 驱动输入、运行测试、捕获渲染结果，并保持 Editor 干净。

最终结果：修复后通过。首次尝试：失败。

测得的执行时长为 15 分钟 52 秒。这次运行很有参考价值，因为失败过程没有被删改。它展示了闭环验证为何重要：UI 真正显示之前，隐藏状态看起来是正确的；而 Agent 必须再次观察、修复并验证。

这并不是说 Hera 能让每项任务都一次成功，也不是「AI 智能提升 X%」的基准测试。它展示的是更实用的一点：Hera 能为 Agent 提供足够的真实 Editor 反馈，让 Agent 找出并修复集成故障，而不是在给出第一个看似合理的答案后就停止。

完整证据：Crystal Forge 真实场景基准测试。

如何使用？

只需要两部分：

your computer                 your Unity project
──────────────                ──────────────────
Hera CLI        <---------->  Hera Unity Connector

第 1 步：安装 CLI

最简单的跨平台方式是使用 npm：

npm install --global hera-agent-unity

或者使用原生安装程序。

Windows PowerShell

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/NotNull92/hera-agent-unity/main/install.ps1 | iex"

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/NotNull92/hera-agent-unity/main/install.sh | bash

检查安装情况：

hera-agent-unity version

go install github.com/NotNull92/hera-agent-unity@latest

hera-agent-unity install

第 2 步：添加 Unity 包

在 Unity 中：

Window -> Package Manager -> Add package from git URL

粘贴：

https://github.com/NotNull92/hera-agent-unity.git?path=AgentConnector

或者将其添加到 Packages/manifest.json：

"com.notnull92.hera-agent-unity": "https://github.com/NotNull92/hera-agent-unity.git?path=AgentConnector"

Editor 打开时，Connector 会自动启动。

若要固定现有的 Connector 标签：

"com.notnull92.hera-agent-unity": "https://github.com/NotNull92/hera-agent-unity.git?path=AgentConnector#connector-<version>"

当前已发布的 Connector 固定版本为：

https://github.com/NotNull92/hera-agent-unity.git?path=AgentConnector#connector-0.2.13

第 3 步：打开 Unity 并检查连接

hera-agent-unity doctor --json
hera-agent-unity status

你应该能看到真实的项目路径、Unity 版本、Editor 状态和连接信息。

现在，你只需告诉 Agent：

Use hera-agent-unity for this Unity project.
Check the current Editor state first.
Make the requested change.
Compile it, read the real Console errors, verify the changed object or UI,
and do not say it is finished until Unity is in a clean state.

这就是 Hera 的常规工作流。

可以用它做什么？

修复编译器或运行时错误

Use Hera. Read the Unity Console, find the actual error, fix the code,
compile again, and keep repeating until the error Console is clean.

后台常用的命令：

hera-agent-unity console --type error --lines 20
hera-agent-unity editor refresh --compile
hera-agent-unity console --type error --lines 20

构建功能并验证其可用性

Implement the inventory filter.
Use Hera to compile it, run the relevant EditMode and PlayMode tests,
enter Play Mode if needed, and report the final evidence.

复现游戏漏洞

Open the correct Scene, enter Play Mode, inspect the related objects,
reproduce the bug, fix it, then reproduce the same path again to prove the fix.

根据参考图构建 UI

Hera 可以为 Agent 提供测量反馈循环，而不只是凭感觉调整：

reference image
   ↓ sample colors / measure layout
Unity UI
   ↓ capture
compare
   ↓ fix
capture again

示例命令：

hera-agent-unity manage_ui create --element panel --name HUD
hera-agent-unity manage_ui set_anchor --path /Canvas/HUD --preset stretch --snap true
hera-agent-unity manage_components set --path /Canvas/HUD --property m_Color --value '#1A1A2E'
hera-agent-unity screenshot --overlay --output_path hud_built.png

分小批次使用 manage_ui、manage_components 和 screenshot --overlay，并逐批验证。

无需猜测屏幕坐标即可验证按钮

hera-agent-unity input state
hera-agent-unity input inspect --path /Canvas/StartButton --details true
hera-agent-unity input click --path /Canvas/StartButton --settle_frames 2

这会验证 Unity 的 EventSystem 路径。它不是实际的 Windows/macOS 鼠标点击，因此 Hera 会分别报告这两类证据。

已经使用可选 Input System 包的项目，也可以验证游戏输入，无需添加 Hera 依赖：

hera-agent-unity input state --backend inputsystem
hera-agent-unity input keyboard --key space --mode press
hera-agent-unity input mouse --mode click --button left --position 640,360
hera-agent-unity call input --json '{"action":"sequence","steps":[{"action":"keyboard","key":"space","mode":"down"},{"action":"keyboard","key":"space","mode":"up"}]}'
hera-agent-unity call input --json '{"action":"record","mode":"start"}'
hera-agent-unity call input --json '{"action":"record","mode":"stop"}'
hera-agent-unity call input --json '{"action":"replay","path":"Library/HeraAgent/Recordings/input.json"}'

键盘、鼠标、有界序列、录制捕获和回放都需要 Play Mode。录制内容采用有界的 hera.input-recording/1 JSON 格式，存放在项目目录或系统临时目录下；回放会在修改前验证整个文件，并复用由序列管理的清理机制。Hera 会在运行时解析该包，不会创建设备，并会在 Play Mode 退出时释放所有按住的控件。

自动化重复的 Scene 操作

你可以让 Agent：

• 创建测试竞技场；
• 将预制件放置在新的根节点下；
• 添加并配置 Components；
• 创建 ScriptableObject 资源；
• 连接 Animator 状态；
• 保存 Scene；
• 随后运行验证。

创建工作室专属工具

如果你的项目有重复的工作流，可以将其封装为自定义 [HeraTool]。该工具会自动出现在 Hera 的实时目录中。

示例：

• build_test_battle
• validate_item_database
• spawn_quest_fixture
• bake_localization_table
• check_prefab_rules

因此，Hera 可以从通用的 Unity 桥接工具起步，逐步发展为服务于你自己的游戏制作流程的 CLI。

Ultra Hera：让“完成”意味着已检查

完成工作。检查工作。然后再报告结果。

Ultra Hera 是一项用于 AI 辅助 Unity 工作的验证规则。它本身不会编写功能，而是告诉 Agent 如何通过 Hera 仔细检查刚完成的工作。

在以下位置找到它：

HeraAgent -> Hera Settings -> Ultra Hera

可以把 Light 看作系好安全带，把 Ultra 看作飞行前检查。

当请求听起来像这样时，请使用 Ultra：

• “准确验证”；
• “运行并确认”；
• “匹配这个 UI”；
• “也检查 Inspector”；
• “所有测试通过前不要结束”。

目标很简单：Unity 仍处于故障状态时，Agent 不应结束任务。

不只是控制 Editor

Hera 包含可选的指导和创作系统，帮助 Agent 不止于修改原始对象。

Game Feel Mode（Beta）

帮助 Agent 思考游戏玩法的感受，而不仅仅是能否运行：操控手感与输入容错、Update / FixedUpdate / LateUpdate 的分工、屏幕震动、受击停顿、击退、镜头、音效、奖励呈现、触觉反馈、游玩节奏和无障碍限制。

hera-agent-unity asset-config gamefeel on
hera-agent-unity game_feel hit_stop
hera-agent-unity game_feel unity_frame_loops

这些知识用于提供指导。Hera 不会暗中向你的游戏添加沉重的运行时系统。

Game Feel UI Mode（Beta）

添加实用的 UI 反馈方案，例如悬停缩放、按压挤压、弹窗入场、数字递增文本、生命条响应、冷却反馈和无障碍基准。

hera-agent-unity asset-config gamefeel-ui on

Unity De-slop Mode（Beta）

帮助 Agent 发现常见的、看起来像生成内容的 UI 习惯：不必要的装饰、薄弱的间距系统、层层嵌套的方框布局、装饰性斜体、不一致的颜色，以及其他视觉特征。

hera-agent-unity asset-config uislop on
hera-agent-unity ui_slop box-in-box

这些规则包含例外情况，因此像物品栏格子这样的功能性游戏 UI 不会仅仅因为重复而被简化。

资源偏好和编译器默认值

可以将 Odin 和 DOTween 等已知资源设为偏好。启用某项资源并不会安装它；这会让生成的 Agent 规则和 AI JSON 在项目实际包含该资源时优先使用其 API。

hera-agent-unity asset-config enable odin_inspector
hera-agent-unity asset-config --json
hera-agent-unity asset-config set-csc <path-to-csc>
hera-agent-unity asset-config set-dotnet <path-to-dotnet>

编译器默认值会由下一次 exec 调用读取，无需重启 Editor。你也可以通过 HeraAgent -> Hera Settings 配置相同的值。

命令概览

你无需记住这些内容。列出它们是为了让你了解 Hera 向 Agent 提供的功能。

完整参考：docs/COMMANDS.md。

教你的 AI Agent 自动使用 Hera

你可以将 Hera 的操作规则放入项目中，让 Agent 知道在猜测之前先检查 Unity。

Codex 插件

codex plugin marketplace add NotNull92/hera-agent-unity --ref main

然后打开 /plugins，选择 Hera Agent Unity，并启用 Hera Unity。

独立 Agent Skill

npx skills add NotNull92/hera-agent-unity --skill hera-agent-unity --agent codex

共享的 AGENTS.md

hera-agent-unity doctor --agent-rules --compact >> AGENTS.md

精简版默认指导有意保持简短。经审核的基线为 2,315 UTF-8 字节，包含引导、目标选择、审批、安全和验证方面的重要规则。完整指南可按需获取。

此仓库还在 examples/rules 下提供了适用于 Cursor、Copilot、AntiGravity、Continue 和其他 Agent 环境的模板。

通俗说明安全性和可靠性

Hera 可以对 Unity 项目进行实际更改，因此仅仅“快”还不够。它还需要知道何时停止。

它识别的是项目，而不仅仅是端口号

Unity 可能会在域重新加载或重启后更改本地端口。Hera 优先使用规范化后的完整项目路径作为 Editor 标识，并将端口视为临时端点。

如果打开了多个 Editor，请使用：

hera-agent-unity --project /full/path/to/project status

如果目标不明确，操作会失败，而不是进行猜测。

高风险操作可能需要审批

需要审批的工作会先进行预检。返回的令牌与该请求精确绑定，且只能使用一次。更改目标或参数会使审批失效。在你已信任的 shell 或 CI 任务中，--yes（环境变量：HERA_AGENT_APPROVE=1）会在同一次调用中通过预检，而不是返回 APPROVAL_REQUIRED——预检和操作记录仍会照常执行。

不会盲目重复不确定的变更操作

如果在重新加载或超时期间响应丢失，Hera 会在符合条件的重试前检查 Editor 的最新所有权和状态。不会仅仅因为网络响应不明确就重新发送变更操作。

可以恢复耗时测试，而不必重新启动

长时间运行的 Test Runner 任务可能超出常规请求时限。Hera 会保存持久化的运行状态，以便 Agent 可以继续等待同一次运行，而不会意外启动另一轮测试执行。

Unity 版本

版本特有的行为会通过运行中的 Editor 进行检查，而不是根据某个 Unity 版本进行推断。

• 代表性 Editor 与作者游戏所用的 Unity 系列保持一致：目前为 6000.6，以 6000.6.6f1 为代表。
• 新系列发布稳定版后两周内，添加一个代表版本并运行 Connector 发布门禁；不跟踪 alpha 和 beta 版本。门禁通过前，将该系列标记为 检查中。
• 游戏开发冲刺优先：冲刺期间延后这些检查，并将该系列保持为 检查中。
• 仅当游戏迁移到新系列，或实际案例表明旧系列阻碍必要修复时，才提高最低版本要求。提前一个小版本在本 README 和 CHANGELOG 中公告，在 Connector 的次要版本中提高最低要求，并在此列出支持旧系列的最后一个 Connector 标签，以便用户固定到 #connector-X.Y.Z。

单一 Agent 接口：CLI

Hera 是一个纯命令行二进制程序。

AI / terminal -> Hera CLI -> localhost Connector -> Unity Editor

任何支持 shell 的编码 Agent 都可以使用它；每条命令都会通过同一目录、审批流程和操作记录，返回格式统一的精简 JSON 封装。

CLI v0.1.0-v0.2.x 还曾包含一个默认关闭、仅支持 stdio 的实验性 MCP 适配器。该适配器已在 v0.3.0 中移除。它位于同一个执行核心之前，因此并未解锁 CLI 原本不具备的 Unity 功能；保留第二种协议接口意味着还要维护第二套发现、审批和结果路径。请直接使用 CLI：用 list 进行发现，用 call 执行类型化调用，在没有专用命令时使用 exec。

Hera 不是什么

• **不是 AI：**由编码 Agent 做出决策；Hera 提供对 Editor 的访问。
• **不是游戏运行时工具：**Connector 仅用于 Editor（HeraAgent.asmdef 仅包含 Editor）。
• **没有第二种协议：**CLI 是唯一的 Agent 接口；没有 MCP 适配器，也没有独立的常驻服务或中继服务。
• **没有实时通道：**每次调用都是一次请求和一次响应；没有进度流或推送通知。
• **不能在一条命令中控制多个 Editor：**每条命令只针对一个 Editor；如果同时打开了多个 Editor，请使用 --project 选择目标。
• 不是沙箱：exec 默认使用 Full Access；Restricted 只是其中一层防护。

新功能必须针对可复现的故障。请参阅贡献指南。

当前版本

• CLI / GitHub Release：v0.3.23，包含五个原生二进制文件
• npm：0.3.23（latest）
• Unity Connector：0.2.13（固定版本请使用 #connector-0.2.13）
• 许可证：Apache-2.0

npm 发布与 GitHub Release 串联，因此 npm install -g hera-agent-unity 与 GitHub 二进制文件保持同步。

这两个版本号有意分开。CLI 和 Unity 包可以独立演进，同时明确保持兼容性约定。 **从 v0.2.x 升级：**v0.3.8 是首个发布的 0.3 版本，因此也包含具有破坏性的 v0.3.0 变更。实验性 MCP 适配器已移除：不再提供 mcp 命令，也不再使用 HERA_MCP_* 环境变量。现在，失败的请求会声明可如何重试（retryable、state、retry_after_ms），并且心跳会公布目录架构哈希，以便在目录匹配时复用，而无需再次往返。Connector 0.2.x 要求 Unity 6.6（6000.6），其 instance_id 值为 64 位。实时目录提供 34 个工具 / 133 个操作。

v0.2.17 以来的新增内容：

Terminal / AI agent
        |
        | hera-agent-unity command
        v
Go CLI
        |
        | localhost HTTP
        v
Unity Editor package
        |
        | serialized Unity main-thread work
        v
Scene, Console, Play Mode, Assets, Tests, UI

常见问题

Hera 能让 AI 变得更聪明吗？

不能。Hera 为 AI 提供更好的方式来访问真实的 Unity 状态并验证结果。编码模型仍负责设计和实现决策。

需要 Python 吗？

不需要。常规安装只需一个原生 CLI 和一个 Unity 包。

需要宿主协议吗？

不需要。CLI 是唯一的操作界面。它通过本地主机 HTTP 与 Unity 包通信，不使用其他方式。

它能控制多个已打开的 Unity Editor 吗？

每条命令只面向一个 Editor。如果同时打开了多个 Editor，请使用完整的 --project 路径，以便更明确地选择。即使本地端口发生变化，Hera 也会跟踪所选项目的身份。

它能实际点击 Unity 窗口吗？

input 命令会发送 Unity EventSystem 事件，以进行 uGUI QA；在 Play Mode 中还可以选择性地模拟 Input System 键盘／鼠标状态。这两种方式都能验证 Unity 层面的行为，但不代表实际点击了操作系统。实际点击的证据必须单独报告。

如果无法连接，我该怎么办？

hera-agent-unity doctor --json

还要检查是否已安装 Unity 包，以及 Editor 是否已完成编译。

哪里可以找到详细文档？

• 命令
• 故障排除
• 架构
• C# 连接器
• Agent 操作指南

使用 Hera 的项目

作者

Victor - Unity／C# 开发者，拥有 6 年以上在线服务型 MMORPG 生产经验。

GitHub： @NotNull92

Discord：加入 Hera 社区

支持

Hera 免费，采用 Apache-2.0 许可。如果它为你节省了时间，可以支持项目开发：

许可证

Apache License 2.0。请参阅 LICENSE 和 NOTICE。