mcpField
C
cli-anything-unrealinsights

cli-anything-unrealinsights

github.com/hkuds开发57.6k443 次安装5 周前更新
代码仓库

关于 cli-anything-unrealinsights

cli-anything-unrealinsights 是面向 Windows 的 Unreal Insights 命令行工具，用于采集、导出和分析追踪数据。它面向使用 Unreal Engine 项目进行性能分析的 Agent 和开发者，并以结构化 JSON 提供采集控制、追踪浏览和计时摘要。

主要功能

  1. 01发现 Unreal Insights 和 Trace Store
  2. 02运行并控制追踪采集
  3. 03发送实时追踪命令和书签
  4. 04将追踪数据导出为文件
  5. 05汇总计时器、线程和计数器

适用场景

  1. 01采集项目启动追踪
  2. 02对实时采集进行快照或停止
  3. 03从追踪中导出计时统计
  4. 04查看线程热点和计数器峰值

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/hkuds/cli-anything --skill cli-anything-unrealinsights

安装后在 Claude Code 中输入/cli-anything-unrealinsights确认已加载。

详细介绍

cli-anything-unrealinsights

当你在 Windows 上需要以 Agent 友好的方式访问 Unreal Insights 跟踪捕获和导出器工作流时，请使用此 CLI。

前提条件

  • Windows
  • 已安装包含 UnrealInsights.exe 的 Unreal Engine 工具
  • 已在 UE 5.5 上验证；无头计时导出器在可能的情况下包含对 UE 5.3 风格命令解析的兼容性处理
  • 可选的环境变量（显式指定）：
    • UNREALINSIGHTS_EXE
    • UNREAL_TRACE_SERVER_EXE
    • UNREALINSIGHTS_TRACE

核心命令

后端发现
cli-anything-unrealinsights --json backend info

要使用源码构建引擎中匹配的 UnrealInsights.exe：

cli-anything-unrealinsights --json backend ensure-insights `
  --engine-root 'D:\code\D5\d5render-ue5_3'

这会首先在指定的引擎根目录下查找 Engine\Binaries\Win64\UnrealInsights.exe，然后在需要时使用该引擎的 Build.bat 构建它。

跟踪会话状态
cli-anything-unrealinsights trace set D:\captures\session.utrace
cli-anything-unrealinsights --json trace info
Trace Store 发现
cli-anything-unrealinsights --json store info
cli-anything-unrealinsights --json store list --live-only
cli-anything-unrealinsights --json store latest --set-current
捕获编排
cli-anything-unrealinsights --json capture run `
  --project 'D:\Projects\MyGame\MyGame.uproject' `
  --engine-root 'D:\Program Files\Epic Games\UE_5.5' `
  --output-trace D:\captures\boot.utrace `
  --channels "default,bookmark" `
  --exec-cmd "Trace.Bookmark BootStart" `
  --wait --timeout 300

你也可以继续使用显式形式：

cli-anything-unrealinsights --json capture run `
  'D:\Program Files\Epic Games\UE_5.5\Engine\Binaries\Win64\UnrealEditor.exe' `
  --target-arg 'D:\Projects\MyGame\MyGame.uproject'
持续捕获会话控制
cli-anything-unrealinsights --json capture start `
  --project 'D:\Projects\MyGame\MyGame.uproject' `
  --engine-root 'D:\Program Files\Epic Games\UE_5.5' `
  --output-trace D:\captures\live_session.utrace

cli-anything-unrealinsights --json capture status
cli-anything-unrealinsights --json capture snapshot D:\captures\live_snapshot.utrace
cli-anything-unrealinsights --json capture stop

当 Agent 需要现在开始性能分析、并在后续轮次中停止或快照时，这是首选流程。

如果已跟踪的捕获会话仍在运行，capture start 现在要求提供 --replace，以便在启动新进程之前停止之前的进程。

实时跟踪控制后端
$env:UNREALINSIGHTS_LIVE_EXEC='ushell-wrapper --pid {pid} --cmd "{cmd}"'
cli-anything-unrealinsights --json live processes
cli-anything-unrealinsights --json live trace-status --pid 1234
cli-anything-unrealinsights --json live bookmark --pid 1234 "BeforeExport"
cli-anything-unrealinsights --json live stop-trace --pid 1234

实时命令传递需要 UNREALINSIGHTS_LIVE_EXEC 或 --backend-command。 如果未配置后端，实时命令会返回 JSON 错误，而不会声称成功。live stop-trace 会在不终止 UE 进程的情况下停止跟踪收集；capture stop 仍会终止由该工具启动的进程树。

GUI 协同助手
cli-anything-unrealinsights --json gui status
cli-anything-unrealinsights --json gui open --trace D:\captures\session.utrace
cli-anything-unrealinsights --json gui open-latest

GUI 命令会省略 -NoUI 和 -AutoQuit，以便 Unreal Insights 保持打开。

离线导出器
cli-anything-unrealinsights --json -t D:\captures\session.utrace export threads D:\out\threads.csv
cli-anything-unrealinsights --json -t D:\captures\session.utrace export timer-stats D:\out\stats.csv --region=EXPORT_CAPTURE
cli-anything-unrealinsights --json -t D:\captures\session.utrace export counter-values D:\out\counter_values.csv --counter=*

优先使用等号形式的通配符过滤器，例如 --timers=* 和 --counter=*。 该工具会将简单值不带内层引号地传递给 UnrealInsights，以便通配符在 -ExecOnAnalysisCompleteCmd 中仍然可用。

批处理响应文件
cli-anything-unrealinsights --json -t D:\captures\session.utrace batch run-rsp D:\out\exports.rsp
Analyze 摘要
cli-anything-unrealinsights --json -t D:\captures\session.utrace analyze summary --out D:\out\summary
cli-anything-unrealinsights --json analyze summary --skip-export --out D:\out\summary

摘要会报告主要计时器、聚焦的 GameThread/RenderThread/RHIThread 热点、等待/任务相关计时器、计数器峰值，以及未来 Memory/Network/Slate/Asset/Cooking 分析尚未覆盖的领域。

analyze summary 还会返回 export_status 和 summary.diagnostics.export_status_counts，以便 Agent 区分成功导出与已完成但未产生任何行的跟踪/过滤器组合。

JSON 输出指南

  • 对于 Agent 工作流，优先使用 --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
  • Analyze 摘要返回：
    • 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 来做出重试或 调试决策。

说明

  • v1 以 Windows 为优先。
  • v1 包含 Trace Store 浏览、GUI 打开/状态、可插拔实时命令下发， 以及计时/计数器摘要。
  • capture stop 是对 harness 启动的进程树尽最大努力的停止。
  • capture snapshot 是对活动 trace 尽最大努力的文件系统快照。
  • 回归测试会在 UE example_trace.decomp.utrace 示例存在时自动发现它； 该二进制 trace 不随仓库提供。

评论

支持 Markdown