cli-anything-unrealinsights 是一个面向智能体的命令行工具，用于在 Windows 上访问 Unreal Insights 的追踪捕获与导出工作流。
用途
当需要在 Windows 上以智能体友好的方式捕获 Unreal Engine 追踪、检查 Trace Store 文件、保持 Unreal Insights GUI 打开，并导出或汇总计时与计数器数据时，可使用此 CLI。
前置条件
- Windows 系统
- 已安装 Unreal Engine 工具，包含 UnrealInsights.exe
- 已验证兼容 UE 5.5；无头计时导出器在可能的情况下包含对 UE 5.3 风格命令解析的兼容处理
- 可选显式环境变量：UNREALINSIGHTS_EXE、UNREAL_TRACE_SERVER_EXE、UNREALINSIGHTS_TRACE
主要能力
后端发现
使用 cli-anything-unrealinsights --json backend info 查看后端信息。若需使用源码构建引擎匹配的 UnrealInsights.exe，可执行 backend ensure-insights --engine-root，它会先在指定引擎根目录下查找 Engine\Binaries\Win64\UnrealInsights.exe，必要时使用该引擎的 Build.bat 构建。
追踪会话状态
通过 trace set 设置当前追踪文件，通过 trace info 查看信息。
Trace Store 发现
支持 store info、store list --live-only、store latest --set-current 等命令。
捕获编排
capture run 支持指定项目、引擎根目录、输出追踪文件、通道、执行命令、等待与超时等参数，也支持显式传入 UnrealEditor.exe 路径与目标参数。
连续捕获会话控制
支持 capture start、capture status、capture snapshot、capture stop。当智能体需要立即开始分析并在后续轮次停止或快照时，这是首选流程。若已有被跟踪的捕获会话仍在运行，capture start 需要 --replace 以先停止之前的进程。
实时追踪控制后端
通过设置 UNREALINSIGHTS_LIVE_EXEC 或使用 --backend-command，可执行 live processes、live trace-status、live bookmark、live stop-trace 等命令。实时命令投递需要配置后端，否则返回 JSON 错误且不会声称成功。live stop-trace 停止追踪收集但不终止 UE 进程；capture stop 仍会终止由工具启动的进程树。
GUI 协同
支持 gui status、gui open --trace、gui open-latest。GUI 命令省略 -NoUI 和 -AutoQuit，使 Unreal Insights 保持打开。
离线导出器
支持导出线程（threads）、计时器统计（timer-stats）、计数器值（counter-values）等。建议使用等号形式的通配符过滤器，如 --timers=* 和 --counter=*。
批量响应文件
通过 batch run-rsp 执行批量响应文件。
分析摘要
analyze summary 可生成摘要，报告顶部计时器、聚焦的 GameThread/RenderThread/RHIThread 热点、等待/任务相关计时器、计数器峰值以及未覆盖领域。它还返回 export_status 和 summary.diagnostics.export_status_counts，帮助区分成功导出与完成但无行的追踪/过滤器组合。
使用方式
推荐在智能体工作流中使用 --json 输出。导出命令返回 trace_path、exec_command、output_files、output_status、status_message、log_path、exit_code、warnings、errors、succeeded 等字段。捕获命令返回 command、trace_path、trace_exists、trace_size、pid 或 exit_code。连续捕获状态返回 pid、running、target_exe、project_path、trace_path、trace_size、started_at。Trace Store 命令返回 store_dir、trace_count、traces、latest。实时命令返回 pid、live_command、backend、exit_code、succeeded。分析摘要返回 exports、export_status、summary.top_timers、summary.focus_threads、summary.wait_timers、summary.counter_peaks、summary.diagnostics、summary.uncovered_domains。
应将 output_status == "ok" 视为已物化导出；output_status == "no_output" 视为空追踪/过滤器结果，而非后端崩溃；使用 exporter_error、process_failed 和 timed_out 决定重试或调试。
适用场景
适用于需要在 Windows 上通过智能体自动化 Unreal Engine 性能分析流程的场景，包括追踪捕获、Trace Store 浏览、GUI 协同、离线导出与摘要分析。
限制
- v1 以 Windows 优先。
- capture stop 是对工具启动进程树的最佳努力停止。
- capture snapshot 是对活动追踪的最佳努力文件系统快照。
- 回归测试在存在时自动发现 UE 示例 example_trace.decomp.utrace 样本；二进制追踪文件未随附。
- 实时命令投递需要配置 UNREALINSIGHTS_LIVE_EXEC 或 --backend-command，否则返回 JSON 错误。