Skip to content

"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/

Python

Move Unreal Insights guide into harness README

aimidi0f8d4f306a0e
diff --git a/.gitignore b/.gitignore
index bac27a596..627b253a8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -225,8 +225,6 @@
!/safari/
!/safari/agent-harness/
!/unrealinsights/agent-harness/
-!/unrealinsights/README.md
-!/unrealinsights/README_CN.md
# Step 7: Ignore build artifacts within allowed dirs
**/__pycache__/
diff --git a/README.md b/README.md
index cb6924e3a..5c709baa9 100644
--- a/README.md
+++ b/README.md
@@ -965,7 +965,7 @@ Each application received complete, production-ready CLI interfaces — not demo
<td align="center">✅ 40</td>
</tr>
<tr>
-<td align="center"><strong>📈 <a href="unrealinsights/README.md">Unreal Insights</a></strong></td>
+<td align="center"><strong>📈 <a href="unrealinsights/agent-harness/">Unreal Insights</a></strong></td>
<td>Performance Profiling</td>
<td><code>cli-anything-unrealinsights</code></td>
<td>Unreal trace capture + engine-matched UnrealInsights export</td>
@@ -1100,8 +1100,6 @@ cli-anything/
├── 🎮 godot/agent-harness/ # Godot Engine CLI (24 tests)
├── 🎨 sketch/agent-harness/ # Sketch CLI (19 tests, Node.js)
├── 🔬 renderdoc/agent-harness/ # RenderDoc CLI (59 tests)
-├── 📈 unrealinsights/README.md # Unreal Insights human guide (English)
-├── 📈 unrealinsights/README_CN.md # Unreal Insights human guide (Chinese)
├── 📈 unrealinsights/agent-harness/ # Unreal Insights CLI (46 tests)
├── 🎬 videocaptioner/agent-harness/ # VideoCaptioner CLI (26 tests)
├── 🎬 openscreen/agent-harness/ # Openscreen CLI — screen recording editor (101 tests)
diff --git a/README_CN.md b/README_CN.md
index b14f13116..d9d1307cc 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -581,7 +581,7 @@ CLI-Anything 适用于任何有代码库的软件 —— 不限领域,不限
<td align="center">✅ 50</td>
</tr>
<tr>
-<td align="center"><strong>📈 <a href="unrealinsights/README_CN.md">Unreal Insights</a></strong></td>
+<td align="center"><strong>📈 <a href="unrealinsights/agent-harness/">Unreal Insights</a></strong></td>
<td>性能分析</td>
<td><code>cli-anything-unrealinsights</code></td>
<td>Unreal trace 采集 + 匹配版 UnrealInsights 导出</td>
@@ -699,8 +699,6 @@ cli-anything/
├── 📞 zoom/agent-harness/ # Zoom CLI(22 项测试)
├── 📐 drawio/agent-harness/ # Draw.io CLI(138 项测试)
├── ✨ anygen/agent-harness/ # AnyGen CLI(50 项测试)
-├── 📈 unrealinsights/README.md # Unreal Insights 人类说明(英文)
-├── 📈 unrealinsights/README_CN.md # Unreal Insights 人类说明(中文)
├── 📈 unrealinsights/agent-harness/ # Unreal Insights CLI(46 项测试)
└── 🎨 sketch/agent-harness/ # Sketch CLI(19 项测试,Node.js)
```
diff --git a/unrealinsights/README.md b/unrealinsights/README.md
deleted file mode 100644
index 5764913da..000000000
--- a/unrealinsights/README.md
+++ /dev/null
@@ -1,127 +0,0 @@
-# Unreal Insights Human Guide
-
-This document is for people collaborating with AI, not for Python package maintainers.
-
-`unrealinsights/agent-harness` gives AI agents a reliable way to drive Unreal
-trace capture and Unreal Insights analysis workflows from the terminal.
-
-## What This Capability Can Do
-
-- find or build an `UnrealInsights.exe` matching your current Unreal Engine
-- start a one-shot trace capture
-- start a background capture and let it run until you decide to stop
-- inspect the current background capture status
-- create a best-effort snapshot copy of the active trace
-- stop the tracked capture session
-- export an existing `.utrace` into:
- - `threads`
- - `timers`
- - `timing-events`
- - `timer-stats`
- - `timer-callees`
- - `counters`
- - `counter-values`
-- read exported CSV files and summarize hotspots, waits, and likely bottlenecks
-
-## How Humans Should Ask AI To Use It
-
-The most effective prompt is not “analyze performance,” but a prompt that gives:
-
-1. engine path
-2. project path or target executable
-3. whether you care about startup or runtime behavior
-4. what output you want back
-
-## Good Prompt Patterns
-
-### Startup performance
-
-```text
-Use D:\code\D5\d5render-ue5_3 to analyze startup performance for
-D:\code\D5\FusionEffectBuild.
-First ensure a matching UnrealInsights.exe exists, then capture a startup trace,
-export timer-stats, and summarize the top 20 hotspots.
-```
-
-### Long-running capture until I say stop
-
-```text
-Use D:\code\D5\d5render-ue5_3 and D:\code\D5\FusionEffectBuild
-to start a background performance capture.
-Do not block and do not exit the project immediately.
-Tell me the trace path and current status first.
-When I say "stop", stop the capture, make a snapshot, export timer-stats and
-timing-events, then summarize the results.
-```
-
-### Runtime scene analysis
-
-```text
-Start a background trace for this project, let me interact with the scene
-manually, and wait.
-When I say "stop now", export timer-stats and timing-events and focus on
-GameThread, RenderThread, and task-system waits.
-```
-
-### Source-built engine without UnrealInsights.exe
-
-```text
-This is a source-built engine.
-First find or build UnrealInsights.exe under D:\code\D5\d5render-ue5_3,
-then use it to analyze the trace.
-```
-
-## Keywords AI Handles Well
-
-These phrases are especially useful:
-
-- “ensure matching UnrealInsights”
-- “background continuous capture”
-- “wait until I say stop”
-- “make a snapshot”
-- “export timer-stats”
-- “export timing-events”
-- “summarize top hotspots”
-- “look at GameThread / RenderThread / WaitForTasks”
-
-## What AI Can Usually Do Automatically
-
-If you give enough context, AI can usually:
-
-- resolve the `.uproject`
-- infer `UnrealEditor.exe`
-- choose or build a matching `UnrealInsights.exe`
-- generate `.utrace`
-- export CSV reports
-- extract hotspots from CSV
-- tell you whether the trace looks more like:
- - startup waiting
- - task-scheduler blocking
- - GameThread stalls
- - RenderThread / render-pass pressure
- - audio or streaming side effects
-
-## Current Scope
-
-The current version supports:
-
-- `capture run`
-- `capture start`
-- `capture status`
-- `capture stop`
-- `capture snapshot`
-- `backend ensure-insights`
-
-It is not full Unreal GUI automation:
-
-- it does not drive an already-open Unreal Insights GUI panel directly
-- it does not fully manage live SessionFrontend / TraceStore UI workflows
-- `capture stop` is a best-effort stop of the harness-launched process tree, not
- full SessionServices remote `Trace.Stop`
-- `capture snapshot` is a best-effort filesystem snapshot of the active trace,
- not a full live trace-store control path
-
-## One-Sentence Rule
-
-Give AI the path, the scene, the timing, and the desired output, and it will be
-able to use this capability much more effectively.
diff --git a/unrealinsights/README_CN.md b/unrealinsights/README_CN.md
deleted file mode 100644
index 0fa3c3cb5..000000000
--- a/unrealinsights/README_CN.md
+++ /dev/null
@@ -1,121 +0,0 @@
-# Unreal Insights 使用说明
-
-这份文档是给正在和 AI 协作的人看的,不是给 Python 包维护者看的。
-
-`unrealinsights/agent-harness` 提供的是一套 AI 可调用的 Unreal 性能采集与分析能力,让 Agent 能比较稳定地驱动 Unreal trace capture 和 Unreal Insights 导出流程。
-
-## 这个能力能做什么
-
-- 找到或构建与你当前 Unreal Engine 匹配的 `UnrealInsights.exe`
-- 启动一次性 trace 采集
-- 启动后台持续采集,并在你指定时机停止
-- 查看当前后台采集状态
-- 对当前活跃 trace 做 best-effort 快照
-- 停止当前追踪会话
-- 对已有 `.utrace` 导出:
- - `threads`
- - `timers`
- - `timing-events`
- - `timer-stats`
- - `timer-callees`
- - `counters`
- - `counter-values`
-- 读取导出的 CSV,并总结热点、等待链和可能瓶颈
-
-## 人类应该怎么调 AI
-
-最有效的方式不是说“帮我分析性能”,而是补齐下面四类信息:
-
-1. 引擎路径
-2. 项目路径或目标可执行文件
-3. 你关心的是“启动阶段”还是“运行时场景”
-4. 你希望 AI 最终给你什么输出
-
-## 推荐提法
-
-### 只分析启动性能
-
-```text
-用 D:\code\D5\d5render-ue5_3 这套引擎,
-分析 D:\code\D5\FusionEffectBuild 这个项目的启动性能。
-先确保匹配版 UnrealInsights 可用,再抓一份启动 trace,
-导出 timer-stats,并总结前 20 个热点。
-```
-
-### 持续采集,等我说停
-
-```text
-用 D:\code\D5\d5render-ue5_3 和 D:\code\D5\FusionEffectBuild
-启动一份后台性能采集,不要阻塞,不要立刻退出项目。
-先告诉我 trace 输出路径和当前状态。
-等我说“停”时,再停止采集、做一次 snapshot,
-导出 timer-stats 和 timing-events。
-```
-
-### 指定场景分析运行时性能
-
-```text
-先启动后台 trace,让我在项目里手动操作某个场景。
-我说“现在停”之后,你帮我导出 timer-stats、timing-events,
-重点看 GameThread、RenderThread 和任务系统等待时间。
-```
-
-### 自定义引擎没有 Insights 可执行文件
-
-```text
-这套引擎是源码版,
-先帮我在 D:\code\D5\d5render-ue5_3 下面找或构建 UnrealInsights.exe,
-然后再用它分析 trace。
-```
-
-## AI 最容易接住的关键词
-
-下面这些关键词很适合直接写进需求:
-
-- “确保匹配版 UnrealInsights”
-- “后台持续采集”
-- “等我说停”
-- “做一次 snapshot”
-- “导出 timer-stats”
-- “导出 timing-events”
-- “总结 top hotspots”
-- “看 GameThread / RenderThread / WaitForTasks”
-
-## 你可以期待 AI 自动做的事
-
-如果描述足够完整,AI 通常会自动:
-
-- 解析 `.uproject`
-- 推导 `UnrealEditor.exe`
-- 选择或构建匹配版 `UnrealInsights.exe`
-- 生成 `.utrace`
-- 导出 CSV
-- 从 CSV 中提取热点
-- 告诉你这份 trace 更像是:
- - 启动等待
- - 任务调度阻塞
- - GameThread 卡住
- - RenderThread / 渲染 pass 偏重
- - 音频或 streaming 相关问题
-
-## 当前能力边界
-
-当前版本已经支持:
-
-- `capture run`
-- `capture start`
-- `capture status`
-- `capture stop`
-- `capture snapshot`
-- `backend ensure-insights`
-
-但它还不是完整的 Unreal GUI 自动化:
-
-- 不直接驱动已经打开的 Unreal Insights 图形界面
-- 不完整覆盖 live SessionFrontend / TraceStore 的 GUI 工作流
-- `capture stop` 当前是对 harness 启动的进程树做 best-effort 停止,不是完整的 SessionServices 远程 `Trace.Stop`
-- `capture snapshot` 当前是对活跃 trace 的 best-effort 文件快照,不是完整的 live trace-store 控制路径
-
-## 一句话原则
-
-把“路径 + 场景 + 时机 + 输出物”说清楚,AI 就最容易把这个能力真正调起来。
diff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/README.md b/unrealinsights/agent-harness/cli_anything/unrealinsights/README.md
index a81449bf1..1153588d4 100644
--- a/unrealinsights/agent-harness/cli_anything/unrealinsights/README.md
+++ b/unrealinsights/agent-harness/cli_anything/unrealinsights/README.md
@@ -171,6 +171,51 @@ Behavior:
- `capture snapshot` creates a best-effort copy of the current `.utrace` without requiring you to end the session first
- `capture stop` performs a best-effort stop of the tracked process tree launched by the harness
+## Human + AI Workflow
+
+When a human is directing an AI agent, the best requests usually specify:
+
+1. engine root
+2. project path or target executable
+3. whether the focus is startup or runtime behavior
+4. the artifact or summary you want back
+
+Example prompts:
+
+```text
+Use D:\code\D5\d5render-ue5_3 to analyze startup performance for
+D:\code\D5\FusionEffectBuild.
+First ensure a matching UnrealInsights.exe exists, then capture a startup trace,
+export timer-stats, and summarize the top 20 hotspots.
+```
+
+```text
+Use D:\code\D5\d5render-ue5_3 and D:\code\D5\FusionEffectBuild
+to start a background performance capture.
+Do not block and do not exit the project immediately.
+Tell me the trace path and current status first.
+When I say "stop", stop the capture, make a snapshot, export timer-stats and
+timing-events, then summarize the results.
+```
+
+```text
+Start a background trace for this project, let me interact with the scene
+manually, and wait.
+When I say "stop now", export timer-stats and timing-events and focus on
+GameThread, RenderThread, and task-system waits.
+```
+
+Useful phrases in prompts:
+
+- `ensure matching UnrealInsights`
+- `background continuous capture`
+- `wait until I say stop`
+- `make a snapshot`
+- `export timer-stats`
+- `export timing-events`
+- `summarize top hotspots`
+- `look at GameThread / RenderThread / WaitForTasks`
+
## Export Filters
`timing-events` and `timer-stats` support: