"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/.gitignoreindex 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.mdindex 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.mdindex 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mdindex 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: