unity-pipeline

Unity 流水线（Agent 控制）

使用 unity command <name> [args] 调用命令。不带名称运行 unity command，即可列出实例提供的命令。存在两个服务：Editor（7800-7849，随编辑器自动启动）和 Runtime（7900-7949，仅在开发版 Player 构建中运行）。unity command --query <term> 可按名称、描述或标签筛选列表。

1. 安装与验证

unity pipeline install            # install into current project (or --project-path)
unity pipeline list               # confirm the editor instance + server are reachable
unity status --until-ready        # wait until the editor server is ready
unity command editor_status       # confirm the editor server answers

已经打开的 Editor 需要等到下次刷新（通常是其窗口重新获得焦点时）才会加载该包。在此之前，unity status 会报告 STATUS_PIPELINE_LOAD_PENDING；如果该状态持续存在，请让用户切换到 Unity Editor 窗口，然后重新运行 unity status --until-ready。

2. 自主编辑循环（Editor）

这是核心 Agent 工作流：保持编辑器运行、修改代码、重新编译并测试。

# 1. Keep the editor ticking even when unfocused/minimized. REQUIRED before headless work —
#    Unity otherwise throttles or stalls update/compile when it isn't the active app.
unity command set_autotick --enable true

# 2. Edit C# source files on disk normally.

# 3. Recompile (async: triggers a domain reload, then poll until done).
unity command recompile
unity command recompile_status    # repeat until "completed" or "up_to_date"
#   Tolerate connection errors while the domain reload is in flight — that is expected.
#   If recompile_status reports failed=true, read its "errors" array and fix before testing.

# 4. (Optional) List available tests without running them.
unity command list_tests --mode editor            # mode: all | editor | playmode

# 5. Run tests (filter to keep it fast).
unity command run_tests --mode editor --filter MyFixture.MyTest

run_tests 模式：all | editor | playmode。filter_type：testName | assembly | category。对于长时间运行的测试，使用 --async_tests true，然后轮询 unity command test_status（使用 unity command cancel_tests 中止）。

已知问题： 只要任何选中的测试失败，run_tests 就可能返回含糊不清的结果，而不显示失败详情。请重新运行范围更窄的 --filter，或查看编辑器的 Test Runner／日志以获取实际失败信息。

解读退出代码。 退出代码用于区分“重写调用方式”和“Editor 出错”，而这个区别正是该循环的关键：

退出代码	含义	处理方式
2	参数错误——标志拼写有误、类型错误或位置参数过多。命令未执行。	修正命令行后重试。错误信息会指出问题，通常还会建议正确的标志。
6	命令已运行但失败，或无法连接到 Editor。	查看错误信息。如果提示未找到 Pipeline 实例，则无法连接到 Editor：使用 unity status --until-ready 等待（或检查 unity pipeline list，确认是否处于 Safe Mode），然后重试。否则，重复相同的调用并无帮助。

退出代码为 2 时，不要原样重试；退出代码为 6 时，不要改写命令行。

3. Runtime 方法热重载

无需域重载，即可在游戏运行中更改游戏逻辑代码。游戏必须处于运行状态：进入 Editor Play Mode（unity command editor_play）或运行开发版 Player。Runtime Pipeline 驱动程序（通过 Project Settings > Pipeline > Runtime 启用）会在 Awake 时自动发现带标记的方法（无需手动注册）。仅适用于 Mono——Editor Play Mode 和 Mono 桌面开发版构建，不适用于 IL2CPP。本地请求会自动注入令牌。

reload_file

直接编辑方法体；无需单独的文件，也无需样板代码。

1. 进入 Play Mode 之前，在 MonoBehaviour 上为方法添加 [MethodReload] 标记并重新编译。 重载钩子会编译进方法，因此游戏运行时添加标记不会生效：退出 Play Mode，重新编译，然后再次进入。
2. 游戏运行时，在磁盘上编辑方法体。
3. 应用更改（可重复运行以继续迭代）：

   unity command reload_file --filename Assets/Spinner.cs
   

   添加 --pdb 以启用调试——生成与源代码映射的可移植 PDB，使原始文件中的断点能够绑定（连接 IDE 并启用 Editor Attaching；编译时不进行优化）：

   unity command reload_file --filename Assets/Spinner.cs --pdb
   

限制：仅支持 void 实例方法；仅支持公共成员；调试需要使用 --pdb（默认不生成符号）。

unity command methodreload_status 会显示当前激活的覆盖项。reload_file 选项：--timeout <ms> （默认值为 30000）、--assemblyDir <dir>（持久化 DLL，而非存储在内存中）； cleanup_methodreload --assemblyDir <dir> 会清除旧 DLL。

CLI 会自行处理 --timeout，单位为秒。若要传入包的 --timeout，请将命令参数放在 -- 之后：

unity command reload_file -- --filename Assets/Spinner.cs --timeout 60000

4. 批量构建：run_script（构建器模式）

对于批量任务——创建许多对象、连接字段、生成内容——将代码放入有版本控制的项目脚本，并使用 run_script 运行一个具名静态入口点。无需重新加载域，也无需通过协议传递代码；迭代只需进行内存编译（< 约 2 秒），而不是耗时 15–20 秒的重新编译。

# 1. Write the builder OUTSIDE Assets/ (so the write triggers no asset import / domain reload),
#    e.g. AgentScripts/Build.cs:  public static class Build { public static int All() { ... } }
# 2. Run it — relative paths resolve against the project root (the parent of Assets/):
unity command run_script --file AgentScripts/Build.cs --entry Build.All
# 3. Iterate: edit the file, re-run. Useful extras:
unity command run_script --file AgentScripts/Build.cs --dry_run true   # compile-only check: diagnostics, nothing loaded or executed
unity command run_script --file AgentScripts/Build.cs --entry Build.All --args '[3, "Green"]'

经验法则：

• 代码通过 run_script 写入磁盘上的文件；eval 仅用于真正临时的一行命令。 切勿通过 eval 发送多行转义的 C# 字符串——应写入文件并运行入口点。
• 编译时会使用项目的活动编辑器定义（UNITY_EDITOR、版本/平台符号）； --defines 会在此基础上追加额外符号。
• 入口点可以是 async Task/Task<T>——它们会以异步方式等待（编辑器会持续运行，因此在 Unity 上下文中恢复的 await 可以正常工作），并返回 Task<T>.Result。等待时间受 timeout_ms 限制；超时后任务会脱离等待并继续运行。
• 运行时异常会返回映射到源代码的 file:line（执行时总会生成源映射 PDB；代码会以未优化模式编译）。
• --mode hotpatch 会改为原地应用 [MethodReload] 方法替换（委托给 reload_file）；此模式不接受 entry/args/dry_run，且 references/defines 不适用。

5. 快速 C# 求值（Editor 或开发版 Player）

仅用于真正临时的一行命令——更长的内容应放入文件并通过 run_script 运行。 eval 默认面向 Editor；添加 --runtime <process name> 可在开发版 Player 中运行。

unity command eval "return 2 + 2;"
unity command eval "return UnityEngine.Time.timeScale;" --runtime MyGame
# Or evaluate a .cs file on disk. Keep it outside Assets/, where Unity would compile it as project source:
unity command eval_file AgentScripts/Scratch.cs

6. 项目审计（Editor）

通过 Project Auditor 进行静态分析扫描，生成包含待修复问题的 CSV。触发、轮询、读取。

unity command audit                              # optional: --categories Code,ProjectSetting --output my.csv
unity command audit_status                       # repeat until terminal status

当 audit_status 返回 completed（包含 csvPath + issueCount）、failed、unavailable 或 interrupted（域重新加载导致扫描终止——只需重新运行 audit）时，即为终态。Code 类别的扫描在编译程序集并占用主线程期间，轮询仍会及时响应。一次只能运行一个扫描：第二次 audit 会返回 busy。无法取消——停止轮询即可放弃扫描。

CSV 列：Category, Severity, Areas, Description, RelativePath, Line, DescriptorId, Recommendation （仅包含诊断结果，因此每一行都是待修复的问题；Recommendation 说明如何修复）。

需要 Project Auditor 及其规则。 unavailable 表示 Editor 中没有 Project Auditor， 或者没有分析规则——在内置模块版 Editor 中，规则位于单独的 com.unity.project-auditor-rules 包中（unity command package_add --identifier com.unity.project-auditor-rules --confirm true）。请读取 message 字段；该命令不会报告看似项目干净的空 completed 扫描结果。

注意事项

• 先运行 set_autotick。 否则，编辑器失焦时重新编译和测试可能会卡住。该包的看门狗依赖 tick 循环持续运行。
• **命令卡住可能是因为打开了模态对话框，**而非程序挂起——对话框会阻塞主线程，直到将其关闭。如果命令运行时间过长，请检查 unity command editor_status（即使被阻塞也会立即响应）；status: "blocked_by_dialog" 表示应停止重试，并告知人工操作人员是什么原因导致阻塞（其 dialog.title/message/buttons）——无法通过 CLI 点击对话框。
• 方法重新加载需要游戏正在运行。 reload_file 会应用到正在运行的游戏——请先进入 Editor Play Mode（unity command editor_play），或运行开发版 Player。
• 仅限 Player 的命令需要开发版 Player。 log、set_timescale、runtime_status 等会访问 Runtime 服务，该服务不会在 Editor 中运行。
• 异步命令需要轮询。 recompile→recompile_status、run_tests --async_tests→ test_status。切勿仅凭触发调用的响应就认定操作已完成。
• 运行多个实例时，请指定目标实例： --project-path <path> 用于选择 Editor，--runtime <process name> 或 --runtime-path <port file> 用于选择开发版 Player。