"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/
Python
Add Nsight Graphics docs and GPU Trace summary
aimidi57bd6a5ce9b8
diff --git a/.gitignore b/.gitignoreindex 84aad877f..acdc15011 100644--- a/.gitignore+++ b/.gitignore@@ -225,6 +225,8 @@!/safari/!/safari/agent-harness/!/nsight-graphics/agent-harness/+!/nsight-graphics/README.md+!/nsight-graphics/README_CN.md# Step 7: Ignore build artifacts within allowed dirs**/__pycache__/diff --git a/README.md b/README.mdindex f739d72d3..385eea4d7 100644--- a/README.md+++ b/README.md@@ -15,7 +15,7 @@ CLI-Anything: Bridging the Gap Between AI Agents and the World's Software</stron<a href="#-quick-start"><img src="https://img.shields.io/badge/Quick_Start-5_min-blue?style=for-the-badge" alt="Quick Start"></a><a href="https://hkuds.github.io/CLI-Anything/"><img src="https://img.shields.io/badge/CLI_Hub-Browse_%26_Install-ff69b4?style=for-the-badge" alt="CLI Hub"></a><a href="#-demonstrations"><img src="https://img.shields.io/badge/Demos-16_Apps-green?style=for-the-badge" alt="Demos"></a>- <a href="#-test-results"><img src="https://img.shields.io/badge/Tests-2%2C130_Passing-brightgreen?style=for-the-badge" alt="Tests"></a>+ <a href="#-test-results"><img src="https://img.shields.io/badge/Tests-2%2C162_Passing-brightgreen?style=for-the-badge" alt="Tests"></a><a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge" alt="License"></a></p>@@ -566,7 +566,7 @@ The catalog auto-updates whenever `registry.json` changes — new community CLIs| **📐 Diagramming & Visualization** | Create and manipulate diagrams, flowcharts, architecture diagrams, and visual documentation programmatically | Draw.io (diagrams.net), Mermaid, PlantUML, Excalidraw, yEd || **🌐 Network & Infrastructure** | Manage network services, DNS, ad-blocking, and infrastructure through structured CLI commands | AdGuardHome || **🧪 Testing & Mocking** | Control HTTP mock servers, manage test stubs, record and replay API traffic for integration testing | **[WireMock](https://wiremock.org)** |-| **🔬 Graphics & GPU Debugging** | Analyze GPU frame captures, inspect pipeline state, export shaders, diff rendering state, and orchestrate Nsight Graphics captures | RenderDoc, Nsight Graphics |+| **🔬 Graphics & GPU Debugging** | Analyze GPU frame captures, inspect pipeline state, export shaders, diff rendering state, orchestrate Nsight Graphics captures, and summarize GPU Trace hotspots | RenderDoc, Nsight Graphics || **🎬 Video & Subtitles** | Transcribe speech, translate subtitles, burn styled captions into video — full captioning pipeline | VideoCaptioner || **🔍 AI-Native Search** | Neural and deep web search with structured content retrieval through embedding-based APIs | [Exa](https://exa.ai) || **✨ AI Content Generation** | Generate professional deliverables (slides, docs, diagrams, websites, research reports) through AI-powered cloud APIs | [AnyGen](https://www.anygen.io), Gamma, Beautiful.ai, Tome |@@ -586,7 +586,7 @@ AI agents are great at reasoning but terrible at using real professional softwar| 💸 "UI automation breaks constantly" | No screenshots, no clicking, no RPA fragility. Pure command-line reliability with structured interfaces || 📊 "Agents need structured data" | Built-in JSON output for seamless agent consumption + human-readable formats for debugging || 🔧 "Custom integrations are expensive" | One Claude plugin auto-generates CLIs for ANY codebase through proven 7-phase pipeline |-| ⚡ "Prototype vs Production gap" | 1,839+ tests with real software validation. Battle-tested across 16 major applications |+| ⚡ "Prototype vs Production gap" | 2,162+ tests with real software validation. Battle-tested across 16 major applications |---@@ -956,11 +956,13 @@ Each application received complete, production-ready CLI interfaces — not demo<td><code>cli-anything-godot</code></td><td>Godot 4.x headless subprocess</td><td align="center">✅ 24</td>-<td align="center"><strong>🟩 Nsight Graphics</strong></td>+</tr>+<tr>+<td align="center"><strong>🟩 <a href="nsight-graphics/">Nsight Graphics CLI</a></strong></td><td>GPU Debugging & Profiling</td><td><code>cli-anything-nsight-graphics</code></td>-<td>Official ngfx / ngfx-capture orchestration</td>-<td align="center">✅ <a href="nsight-graphics/agent-harness/">New</a></td>+<td>Official ngfx / ngfx-capture orchestration + GPU Trace summary</td>+<td align="center">✅ 32</td></tr><tr><td align="center"><strong>🅲🅲 CloudCompare</strong></td>@@ -985,11 +987,11 @@ Each application received complete, production-ready CLI interfaces — not demo</tr><tr><td align="center" colspan="4"><strong>Total</strong></td>-<td align="center"><strong>✅ 2,130</strong></td>+<td align="center"><strong>✅ 2,162</strong></td></tr></table>-> **100% pass rate** across all 2,130 tests — 1,551 unit tests + 560 end-to-end tests + 19 Node.js tests.+> **100% pass rate** across all 2,162 tests — 1,582 unit tests + 561 end-to-end tests + 19 Node.js tests.---@@ -1027,10 +1029,11 @@ ollama 98 passed ✅ (87 unit + 11 e2e)sketch 19 passed ✅ (19 jest, Node.js)renderdoc 59 passed ✅ (45 unit + 14 e2e)cloudcompare 88 passed ✅ (49 unit + 39 e2e)+nsight-graphics 32 passed ✅ (31 unit + 1 e2e)openscreen 101 passed ✅ (78 unit + 23 e2e)cloudanalyzer 14 passed ✅ (7 unit + 7 e2e)──────────────────────────────────────────────────────────────────────────────-TOTAL 2,120 passed ✅ 100% pass rate+TOTAL 2,162 passed ✅ 100% pass rate```---@@ -1109,7 +1112,7 @@ cli-anything/├── ☁️ cloudcompare/agent-harness/ # CloudCompare CLI (88 tests)├── 🔍 exa/agent-harness/ # Exa CLI (40 tests)└── ⛅ cloudanalyzer/agent-harness/ # CloudAnalyzer CLI (14 tests)-├── 🟩 nsight-graphics/agent-harness/ # Nsight Graphics CLI (new)+├── 🟩 nsight-graphics/ # Nsight Graphics CLI (32 tests)```Each `agent-harness/` contains an installable Python package under `cli_anything.<software>/` with Click CLI, core modules, utils (including `repl_skin.py` and backend wrapper), and comprehensive tests.@@ -1335,7 +1338,7 @@ MIT License — free to use, modify, and distribute.**CLI-Anything** — *Make any software with a codebase Agent-native.*-<sub>A methodology for the age of AI agents | 16 professional software demos | 1,839 passing tests</sub>+<sub>A methodology for the age of AI agents | 16 professional software demos | 2,162 passing tests</sub><br>diff --git a/nsight-graphics/README.md b/nsight-graphics/README.mdnew file mode 100644index 000000000..0c9003c38--- /dev/null+++ b/nsight-graphics/README.md@@ -0,0 +1,81 @@+# Nsight Graphics++This directory contains the CLI-Anything integration for **NVIDIA Nsight Graphics**.++It is designed for humans coordinating AI agents as well as for agents calling+the harness directly.++## What This Integration Does++- detects installed Nsight Graphics versions+- selects a specific install with `--nsight-path`+- launches a target or attaches to a running PID+- captures a frame+- collects a GPU Trace report+- summarizes exported GPU Trace timing results+- generates a C++ capture++## Recommended Human-to-AI Prompt Format++Give the AI these fields explicitly:++```text+Nsight version: 2026.1.0+Program: D:/path/to/YourApp.exe+Working dir: D:/path/to+Args: "D:\path\project.uproject" -dx12 -log -newconsole+Action: Graphics Capture / GPU Trace / C++ Capture+Trigger: after 10 seconds / frame 300 / I will press F11+Output: capture path / trace path / top 10 GPU hotspots / summary+```++## Prompt Examples++### Inspect installations++```text+Use the Nsight Graphics harness. List installed versions, tell me which one is selected, and switch to 2026.1.0 if available.+```++### One-step GPU Trace summary++```text+Use Nsight Graphics 2026.1.0 and run a GPU Trace on this executable.+Wait for me to press F11 manually.+After it finishes, give me:+- frame time+- estimated FPS+- draw count and dispatch count+- top 10 GPU events+- short diagnosis of what looks expensive+Program: D:/path/to/App.exe+Working dir: D:/path/to+Args: ...+```++### Automatic frame capture++```text+Launch this program under Nsight Graphics and automatically capture one frame after 10 seconds. Return the capture file path.+```++## Operator Notes++- If multiple Nsight versions are installed, pin one with `--nsight-path`+ when reproducibility matters.+- For one-step performance triage, prefer:++```bash+cli-anything-nsight-graphics gpu-trace capture --auto-export --summarize+```++- If a running process is already attached to a different Nsight activity,+ ask the AI to launch a fresh process for GPU Trace instead of reusing it.+- This harness is Windows-first and wraps the official CLI tools, not the full GUI.++## Related Docs++- Chinese guide: [README_CN.md](D:\code\D5\CLI-Anything-nsight-graphics-dev\nsight-graphics\README_CN.md)+- Package usage: [agent-harness/cli_anything/nsight_graphics/README.md](D:\code\D5\CLI-Anything-nsight-graphics-dev\nsight-graphics\agent-harness\cli_anything\nsight_graphics\README.md)+- Software notes: [agent-harness/NSIGHT_GRAPHICS.md](D:\code\D5\CLI-Anything-nsight-graphics-dev\nsight-graphics\agent-harness\NSIGHT_GRAPHICS.md)+- Agent skill: [agent-harness/cli_anything/nsight_graphics/skills/SKILL.md](D:\code\D5\CLI-Anything-nsight-graphics-dev\nsight-graphics\agent-harness\cli_anything\nsight_graphics\skills\SKILL.md)diff --git a/nsight-graphics/README_CN.md b/nsight-graphics/README_CN.mdnew file mode 100644index 000000000..939455906--- /dev/null+++ b/nsight-graphics/README_CN.md@@ -0,0 +1,78 @@+# Nsight Graphics++这个目录包含 **NVIDIA Nsight Graphics** 的 CLI-Anything 集成。++它既面向直接调用 harness 的 AI,也面向“由人来调度 AI 使用这个能力”的工作流。++## 这个能力可以做什么++- 检测本机安装了哪些 Nsight Graphics 版本+- 用 `--nsight-path` 显式选择某个安装版本+- 启动目标程序或附加到已有 PID+- 抓取一帧图形捕获+- 收集一轮 GPU Trace+- 自动总结 GPU Trace 导出的耗时结果+- 生成 C++ Capture++## 推荐的人类提示格式++建议把这些信息明确告诉 AI:++```text+Nsight版本:2026.1.0+程序:D:/path/to/YourApp.exe+工作目录:D:/path/to+参数:"D:\path\project.uproject" -dx12 -log -newconsole+动作:Graphics Capture / GPU Trace / C++ Capture+触发方式:10秒后 / 第300帧 / 我会按 F11+输出:capture 路径 / trace 路径 / Top10 GPU 热点 / 总结+```++## 提示示例++### 查看安装版本++```text+使用 Nsight Graphics harness,列出本机已安装版本,告诉我当前默认选中哪个,如果有 2026.1.0 就切过去。+```++### 一步式 GPU Trace 总结++```text+使用 Nsight Graphics 2026.1.0 对这个程序做一轮 GPU Trace。+等我手动按 F11 触发。+结束后给我:+- 帧时间+- 估算 FPS+- draw count 和 dispatch count+- 最耗时前 10 个 GPU 事件+- 一段简短诊断,说明主要瓶颈在哪里+程序:D:/path/to/App.exe+工作目录:D:/path/to+参数:...+```++### 自动抓帧++```text+用 Nsight Graphics 启动这个程序,10 秒后自动抓 1 帧,并把 capture 文件路径返回给我。+```++## 使用建议++- 多版本共存时,建议始终用 `--nsight-path` 固定版本。+- 如果你想让 AI 一步完成“抓 trace + 导出 + 总结”,优先让它使用:++```bash+cli-anything-nsight-graphics gpu-trace capture --auto-export --summarize+```++- 如果目标进程已经挂在其他 Nsight activity 上,建议让 AI 新起一个进程来跑 GPU Trace。+- 这个 harness 当前是 Windows-first,封装的是官方 CLI,不是完整 GUI 的全部功能。++## 相关文档++- 英文说明:[README.md](D:\code\D5\CLI-Anything-nsight-graphics-dev\nsight-graphics\README.md)+- 包内使用说明:[agent-harness/cli_anything/nsight_graphics/README.md](D:\code\D5\CLI-Anything-nsight-graphics-dev\nsight-graphics\agent-harness\cli_anything\nsight_graphics\README.md)+- 软件说明:[agent-harness/NSIGHT_GRAPHICS.md](D:\code\D5\CLI-Anything-nsight-graphics-dev\nsight-graphics\agent-harness\NSIGHT_GRAPHICS.md)+- Agent 技能:[agent-harness/cli_anything/nsight_graphics/skills/SKILL.md](D:\code\D5\CLI-Anything-nsight-graphics-dev\nsight-graphics\agent-harness\cli_anything\nsight_graphics\skills\SKILL.md)diff --git a/nsight-graphics/agent-harness/HARNESS.md b/nsight-graphics/agent-harness/HARNESS.mdindex 8267c0fa3..c6482b997 100644--- a/nsight-graphics/agent-harness/HARNESS.md+++ b/nsight-graphics/agent-harness/HARNESS.md@@ -55,7 +55,7 @@ agent-harness/| `doctor` | `info` || `launch` | `detached`, `attach` || `frame` | `capture` |-| `gpu-trace` | `capture` |+| `gpu-trace` | `capture`, `summarize` || `cpp` | `capture` |## Backend Strategydiff --git a/nsight-graphics/agent-harness/NSIGHT_GRAPHICS.md b/nsight-graphics/agent-harness/NSIGHT_GRAPHICS.mdindex 73221ed4f..e558e9e19 100644--- a/nsight-graphics/agent-harness/NSIGHT_GRAPHICS.md+++ b/nsight-graphics/agent-harness/NSIGHT_GRAPHICS.md@@ -21,6 +21,7 @@ This harness targets the official command-line interfaces rather than the GUI.- attach to a running PID with an activity- Frame Debugger capture orchestration- GPU Trace capture orchestration+- GPU Trace export summarization- Generate C++ Capture orchestration- artifact discovery in output directories@@ -29,6 +30,7 @@ This harness targets the official command-line interfaces rather than the GUI.- replay-helper public commands- pipeline/resource/shader inspection APIs- deep analysis comparable to RenderDoc's Python bindings+- full GUI-level replay investigation and editing workflows## Compatibility Notes@@ -37,3 +39,12 @@ This harness targets the official command-line interfaces rather than the GUI.- On newer installs, `ngfx-capture` / `ngfx-replay` may exist alongside `ngfx`.- This harness prefers capability detection over hard-coded version branching.- `--nsight-path` can explicitly select one installation when multiple versions coexist.++## AI Operator Workflow++For one-step performance triage, the intended flow is:++1. run `doctor versions`+2. optionally pin a version with `--nsight-path`+3. run `gpu-trace capture --auto-export --summarize`+4. inspect the returned summary and the exported `.xls` tables if you need more detaildiff --git a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/README.md b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/README.mdindex 9cff828c4..ba2d302d2 100644--- a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/README.md+++ b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/README.md@@ -8,7 +8,7 @@ terminal:- installation and capability probing- detached launch and PID attach- Frame Debugger capture-- GPU Trace capture and auto-export+- GPU Trace capture, auto-export, and summary generation- Generate C++ CaptureIt does not provide RenderDoc-style offline inspection of shaders, pipeline@@ -85,7 +85,15 @@ cli-anything-nsight-graphics --output-dir D:\traces gpu-trace capture ^--exe "C:\VulkanSDK\1.3.290.0\Bin\vkcube.exe" ^--start-after-ms 1000 ^--limit-to-frames 1 ^- --auto-export+ --auto-export ^+ --summarize+```++### Summarize an existing GPU Trace export++```bash+cli-anything-nsight-graphics gpu-trace summarize ^+ --input-dir D:\traces```### Generate a C++ capture@@ -119,7 +127,8 @@ cli-anything-nsight-graphics --output-dir D:\cpp cpp capture ^| `launch` | `detached` | Launch a target under Nsight without blocking the CLI || `launch` | `attach` | Attach Nsight to a running PID || `frame` | `capture` | Trigger a Frame Debugger capture |-| `gpu-trace` | `capture` | Trigger a GPU Trace capture |+| `gpu-trace` | `capture` | Trigger a GPU Trace capture and optionally summarize the exported result |+| `gpu-trace` | `summarize` | Summarize an existing GPU Trace export directory || `cpp` | `capture` | Trigger Generate C++ Capture |## JSON Output@@ -139,6 +148,14 @@ Capture-producing commands also include:- `output_dir`- `artifacts`+When `gpu-trace capture --summarize` is used, the result also includes:++- `summary.frame_time_ms`+- `summary.fps_estimate`+- `summary.metrics`+- `summary.top_events`+- `summary.highlights`+## Environment Variables| Variable | Purpose |@@ -175,3 +192,23 @@ not currently have a discovered Nsight executable path. They are useful fordiagnosis, but not enough by themselves to launch captures. The harness alsoscans standard `Program Files` locations on all fixed Windows drives, sonon-`C:` installs can still be promoted to normal filesystem-backed entries.++## One-Step GPU Trace Triage++If you want the harness to behave like a single-shot performance assistant,+prefer this pattern:++```bash+cli-anything-nsight-graphics --output-dir D:\traces gpu-trace capture ^+ --exe "C:\Path\To\App.exe" ^+ --start-after-hotkey ^+ --limit-to-frames 1 ^+ --auto-export ^+ --summarize+```++That gives you:++- the `.ngfx-gputrace` artifact+- exported `FRAME.xls`, `GPUTRACE_FRAME.xls`, and `D3DPERF_EVENTS.xls`+- a parsed summary with frame time, estimated FPS, selected counters, and top GPU eventsdiff --git a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/core/gpu_trace.py b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/core/gpu_trace.pyindex 56b88f10d..2795c6fa8 100644--- a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/core/gpu_trace.py+++ b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/core/gpu_trace.py@@ -1,11 +1,200 @@-"""GPU Trace orchestration."""+"""GPU Trace orchestration and export summarization."""from __future__ import annotations-from typing import Sequence+import csv+from pathlib import Path+from typing import Any, Sequencefrom cli_anything.nsight_graphics.utils import nsight_graphics_backend as backend+SUMMARY_METRICS = {+ "draw_count": "fe__draw_count.sum",+ "dispatch_count": "gr__dispatch_count.sum",+ "graphics_engine_active_pct": "gr__cycles_active.avg.pct_of_peak_sustained_elapsed",+ "compute_queue_sync_active_pct": "gr__compute_cycles_active_queue_sync.avg.pct_of_peak_sustained_elapsed",+ "compute_queue_async_active_pct": "gr__compute_cycles_active_queue_async.avg.pct_of_peak_sustained_elapsed",+ "sm_throughput_pct": "sm__throughput.avg.pct_of_peak_sustained_elapsed",+ "l1tex_throughput_pct": "l1tex__throughput.avg.pct_of_peak_sustained_elapsed",+ "l2_throughput_pct": "lts__throughput.avg.pct_of_peak_sustained_elapsed",+ "dram_throughput_pct": "dramc__throughput.avg.pct_of_peak_sustained_elapsed",+ "pcie_throughput_pct": "pcie__throughput.avg.pct_of_peak_sustained_elapsed",+}+++def _find_first(output_dir: str, name: str) -> str | None:+ """Find the first matching file under an export directory."""+ matches = sorted(Path(output_dir).rglob(name))+ return str(matches[0]) if matches else None+++def _read_kv_file(path: str) -> dict[str, str]:+ """Read a simple tab-separated key/value file."""+ data: dict[str, str] = {}+ with open(path, "r", encoding="utf-8-sig", errors="replace") as handle:+ for raw in handle:+ line = raw.strip()+ if not line or "\t" not in line:+ continue+ key, value = line.split("\t", 1)+ data[key.strip()] = value.strip()+ return data+++def _read_event_rows(path: str) -> list[dict[str, str]]:+ """Read D3DPERF event rows from the exported TSV."""+ with open(path, "r", encoding="utf-8-sig", errors="replace", newline="") as handle:+ reader = csv.DictReader(handle, delimiter="\t")+ rows = []+ for row in reader:+ event_text = (row.get("event_text") or "").rstrip()+ time_ms = (row.get("time_ms") or "").strip()+ if not event_text or not time_ms:+ continue+ rows.append({"event_text": event_text, "time_ms": time_ms})+ return rows+++def _safe_float(value: str | None) -> float | None:+ """Convert a string to float when possible."""+ if value is None:+ return None+ try:+ return float(value)+ except (TypeError, ValueError):+ return None+++def _safe_int(value: float | None) -> int | None:+ """Convert a float to int when available."""+ if value is None:+ return None+ return int(round(value))+++def _pick_metric(metrics: dict[str, str], needle: str) -> float | None:+ """Find the first metric whose key ends with the requested suffix."""+ for key, value in metrics.items():+ if key.endswith(needle):+ return _safe_float(value)+ return None+++def _event_depth(event_text: str) -> int:+ """Compute indentation depth for an event row."""+ return len(event_text) - len(event_text.lstrip(" "))+++def _make_highlights(+ frame_time_ms: float | None,+ metrics: dict[str, float | int | None],+ top_events: list[dict[str, Any]],+) -> list[str]:+ """Generate short heuristic findings."""+ highlights: list[str] = []++ if frame_time_ms is not None:+ if frame_time_ms > 33.3:+ highlights.append("GPU frame is slower than 30 FPS budget.")+ elif frame_time_ms > 16.7:+ highlights.append("GPU frame exceeds 60 FPS budget.")++ draw_count = metrics.get("draw_count")+ dispatch_count = metrics.get("dispatch_count")+ if isinstance(draw_count, int) and isinstance(dispatch_count, int):+ if dispatch_count > max(draw_count * 2, 500):+ highlights.append("Frame is compute-heavy relative to draw count.")++ compute_sync = metrics.get("compute_queue_sync_active_pct")+ if isinstance(compute_sync, float) and compute_sync > 50.0:+ highlights.append("Synchronous compute queue activity is high.")++ dram_pct = metrics.get("dram_throughput_pct")+ if isinstance(dram_pct, float) and dram_pct > 60.0:+ highlights.append("DRAM throughput is high enough to suggest memory pressure.")++ if top_events:+ top = top_events[0]+ if frame_time_ms and top["time_ms"] >= frame_time_ms * 0.25:+ highlights.append(f"Largest GPU event is '{top['event']}' at {top['time_ms']:.3f} ms.")++ return highlights+++def summarize_export_dir(output_dir: str, top_n: int = 10) -> dict[str, Any]:+ """Summarize exported GPU Trace tables from an output directory."""+ output_root = str(Path(output_dir).resolve())+ frame_path = _find_first(output_root, "FRAME.xls")+ trace_frame_path = _find_first(output_root, "GPUTRACE_FRAME.xls")+ events_path = _find_first(output_root, "D3DPERF_EVENTS.xls")+ regimes_path = _find_first(output_root, "GPUTRACE_REGIMES.xls")++ if not frame_path or not trace_frame_path or not events_path:+ missing = [+ name+ for name, path in {+ "FRAME.xls": frame_path,+ "GPUTRACE_FRAME.xls": trace_frame_path,+ "D3DPERF_EVENTS.xls": events_path,+ }.items()+ if not path+ ]+ raise RuntimeError(+ "GPU Trace export summary requires exported tables. Missing: "+ + ", ".join(missing)+ )++ frame_data = _read_kv_file(frame_path)+ trace_metrics = _read_kv_file(trace_frame_path)+ event_rows = _read_event_rows(events_path)++ frame_time_ms = _safe_float(frame_data.get("GPU frame time"))+ fps_estimate = (1000.0 / frame_time_ms) if frame_time_ms and frame_time_ms > 0 else None++ summary_metrics: dict[str, float | int | None] = {}+ for name, needle in SUMMARY_METRICS.items():+ value = _pick_metric(trace_metrics, needle)+ if name in {"draw_count", "dispatch_count"}:+ summary_metrics[name] = _safe_int(value)+ else:+ summary_metrics[name] = value++ ranked_events: list[dict[str, Any]] = []+ for row in event_rows:+ event_name = row["event_text"]+ if event_name.startswith("Frame "):+ continue+ time_ms = _safe_float(row["time_ms"])+ if time_ms is None or time_ms <= 0:+ continue+ ranked_events.append(+ {+ "event": event_name.strip(),+ "time_ms": time_ms,+ "depth": _event_depth(event_name),+ }+ )++ ranked_events.sort(key=lambda item: item["time_ms"], reverse=True)+ top_events = ranked_events[:top_n]+ top_level_events = [item for item in top_events if item["depth"] == 0]++ return {+ "output_dir": output_root,+ "files": {+ "frame": frame_path,+ "trace_frame": trace_frame_path,+ "events": events_path,+ "regimes": regimes_path,+ },+ "frame_time_ms": frame_time_ms,+ "fps_estimate": fps_estimate,+ "metrics": summary_metrics,+ "top_events": top_events,+ "top_level_events": top_level_events,+ "highlights": _make_highlights(frame_time_ms, summary_metrics, top_events),+ }+def capture_trace(*,@@ -30,6 +219,8 @@ def capture_trace(metric_set_id: str | None,multi_pass_metrics: bool,real_time_shader_profiler: bool,+ summarize: bool = False,+ summary_limit: int = 10,) -> dict:"""Run a GPU Trace capture."""report = backend.probe_installation(nsight_path=nsight_path)@@ -55,6 +246,10 @@ def capture_trace()if metric_set_id and not architecture:raise ValueError("--metric-set-id requires --architecture.")+ if summary_limit < 1:+ raise ValueError("--summary-limit must be at least 1.")++ auto_export = auto_export or summarizeextra_args: list[str] = []if start_after_frames is not None:@@ -104,4 +299,8 @@ def capture_trace(result["tool_mode"] = "unified"result["activity"] = "GPU Trace Profiler"result["output_dir"] = output_dir or backend.default_output_dir()+ result["auto_export"] = auto_export++ if summarize:+ result["summary"] = summarize_export_dir(result["output_dir"], top_n=summary_limit)return resultdiff --git a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/nsight_graphics_cli.py b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/nsight_graphics_cli.pyindex 127d38e1e..cb832e395 100644--- a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/nsight_graphics_cli.py+++ b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/nsight_graphics_cli.py@@ -49,6 +49,48 @@ def _common_kwargs(ctx: click.Context) -> dict:}+def _print_gpu_trace_summary(summary: dict) -> None:+ """Render a compact human-readable GPU Trace summary."""+ frame_time = summary.get("frame_time_ms")+ fps = summary.get("fps_estimate")+ if frame_time is not None:+ click.echo(f"Frame time: {frame_time:.3f} ms")+ if fps is not None:+ click.echo(f"Estimated FPS: {fps:.2f}")++ metrics = summary.get("metrics", {})+ if metrics:+ click.echo("Metrics:")+ for label, key in [+ ("Draws", "draw_count"),+ ("Dispatches", "dispatch_count"),+ ("Graphics active %", "graphics_engine_active_pct"),+ ("Compute sync active %", "compute_queue_sync_active_pct"),+ ("SM throughput %", "sm_throughput_pct"),+ ("L2 throughput %", "l2_throughput_pct"),+ ("DRAM throughput %", "dram_throughput_pct"),+ ]:+ value = metrics.get(key)+ if value is None:+ continue+ if isinstance(value, float):+ click.echo(f" {label}: {value:.3f}")+ else:+ click.echo(f" {label}: {value}")++ top_events = summary.get("top_events", [])+ if top_events:+ click.echo("Top GPU events:")+ for item in top_events:+ click.echo(f" - {item['event']}: {item['time_ms']:.3f} ms")++ highlights = summary.get("highlights", [])+ if highlights:+ click.echo("Highlights:")+ for line in highlights:+ click.echo(f" - {line}")++@click.group(invoke_without_command=True)@click.option("--json", "json_mode", is_flag=True, help="Output in JSON format.")@click.option("--debug", is_flag=True, help="Show debug tracebacks on errors.")@@ -253,6 +295,8 @@ def gpu_trace_group():@click.option("--metric-set-id", default=None, help="Metric set id for the selected architecture.")@click.option("--multi-pass-metrics", is_flag=True, help="Enable multi-pass metrics.")@click.option("--real-time-shader-profiler", is_flag=True, help="Enable real-time shader profiler.")[email protected]("--summarize", is_flag=True, help="Parse exported GPU Trace tables and include a summary.")[email protected]("--summary-limit", type=int, default=10, show_default=True, help="Number of top GPU events to include in the summary.")@click.pass_contextdef gpu_trace_capture_cmd(ctx,@@ -272,6 +316,8 @@ def gpu_trace_capture_cmd(metric_set_id,multi_pass_metrics,real_time_shader_profiler,+ summarize,+ summary_limit,):"""Run a GPU Trace capture."""try:@@ -292,9 +338,32 @@ def gpu_trace_capture_cmd(metric_set_id=metric_set_id,multi_pass_metrics=multi_pass_metrics,real_time_shader_profiler=real_time_shader_profiler,+ summarize=summarize,+ summary_limit=summary_limit,**_common_kwargs(ctx),)- _output(ctx, data)+ _output(+ ctx,+ data,+ lambda payload: (+ click.echo(f"Output dir: {payload.get('output_dir')}"),+ click.echo(f"Artifacts: {payload.get('artifact_count', 0)}"),+ _print_gpu_trace_summary(payload["summary"]) if payload.get("summary") else None,+ ),+ )+ except Exception as exc:+ _handle_exc(ctx, exc)+++@gpu_trace_group.command("summarize")[email protected]("--input-dir", required=True, type=click.Path(exists=True, file_okay=False), help="GPU Trace export directory to summarize.")[email protected]("--summary-limit", type=int, default=10, show_default=True, help="Number of top GPU events to include in the summary.")[email protected]_context+def gpu_trace_summarize_cmd(ctx, input_dir, summary_limit):+ """Summarize an existing exported GPU Trace directory."""+ try:+ data = gpu_trace.summarize_export_dir(input_dir, top_n=summary_limit)+ _output(ctx, data, _print_gpu_trace_summary)except Exception as exc:_handle_exc(ctx, exc)@@ -346,7 +415,7 @@ def repl(ctx):"doctor": "info|versions","launch": "detached|attach","frame": "capture",- "gpu-trace": "capture",+ "gpu-trace": "capture|summarize","cpp": "capture","help": "Show this help","quit": "Exit REPL",diff --git a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/skills/SKILL.md b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/skills/SKILL.mdindex 6fbb3c0de..2b52ceda0 100644--- a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/skills/SKILL.md+++ b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/skills/SKILL.md@@ -24,7 +24,7 @@ Command-line orchestration of official NVIDIA Nsight Graphics activities.- Launch an application detached under Nsight- Attach Nsight to a running PID- Trigger Frame Debugger capture-- Trigger GPU Trace capture and auto-export+- Trigger GPU Trace capture, auto-export, and summarize- Trigger Generate C++ Capture## Commands@@ -59,7 +59,11 @@ cli-anything-nsight-graphics --output-dir D:\traces gpu-trace capture ^--exe "C:\Path\To\App.exe" ^--start-after-ms 1000 ^--limit-to-frames 1 ^- --auto-export+ --auto-export ^+ --summarize++cli-anything-nsight-graphics gpu-trace summarize ^+ --input-dir D:\traces```### Generate C++ Capture@@ -76,6 +80,7 @@ cli-anything-nsight-graphics --output-dir D:\cpp cpp capture ^- Use `doctor versions` to list detected installs when multiple Nsight Graphics versions exist.- Use `--nsight-path` to force a specific install directory or `ngfx.exe`.- Use `--json` for programmatic workflows.+- Prefer `gpu-trace capture --auto-export --summarize` for one-step performance triage.- Frame/GPU/C++ capture commands require a launch target through `--exe` or apreconfigured root-level `--project`.- V1 is orchestration-focused; it does not expose shader, pipeline, or resourcediff --git a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/tests/TEST.md b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/tests/TEST.mdindex 31677e193..85c318637 100644--- a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/tests/TEST.md+++ b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/tests/TEST.md@@ -2,7 +2,7 @@## Test Inventory Plan-- `test_core.py`: 28 unit tests planned+- `test_core.py`: 31 unit tests planned- `test_full_e2e.py`: 4 E2E tests planned## Unit Test Plan@@ -18,12 +18,14 @@- fixed-drive discovery for non-`C:` installs- unified and split command construction- artifact diffing behavior+- exported GPU Trace summary parsing### `core/*.py`- frame capture command routing- split-mode fallback restrictions- GPU Trace validation for trigger/limit options+- GPU Trace one-step summary behavior- launch attach/detached wrapping### `nsight_graphics_cli.py`@@ -62,8 +64,8 @@ python -m pytest cli_anything/nsight_graphics/tests -v --tb=no============================= test session starts =============================platform win32 -- Python 3.11.9, pytest-9.0.3, pluggy-1.6.0 -- C:\Users\aimidi\AppData\Local\Programs\Python\Python311\python.execachedir: .pytest_cache-rootdir: D:\code\D5\CLI-Anything-nsight-graphics\nsight-graphics\agent-harness-collecting ... collected 32 items+rootdir: D:\code\D5\CLI-Anything-nsight-graphics-dev\nsight-graphics\agent-harness+collecting ... collected 35 itemscli_anything/nsight_graphics/tests/test_core.py::TestOutputAndErrors::test_output_json PASSEDcli_anything/nsight_graphics/tests/test_core.py::TestOutputAndErrors::test_handle_error_debug PASSED@@ -79,11 +81,13 @@ cli_anything/nsight_graphics/tests/test_core.py::TestHelpParsing::test_parse_unicli_anything/nsight_graphics/tests/test_core.py::TestCommandBuilders::test_build_unified_command_formats_args_and_env PASSEDcli_anything/nsight_graphics/tests/test_core.py::TestCommandBuilders::test_build_split_capture_command_maps_wait_seconds PASSEDcli_anything/nsight_graphics/tests/test_core.py::TestCommandBuilders::test_diff_snapshots_reports_new_nonempty_files PASSED+cli_anything/nsight_graphics/tests/test_core.py::TestCommandBuilders::test_gpu_trace_summary_from_export_dir PASSEDcli_anything/nsight_graphics/tests/test_core.py::TestCoreModules::test_frame_capture_uses_unified_ngfx PASSEDcli_anything/nsight_graphics/tests/test_core.py::TestCoreModules::test_frame_capture_split_mode_rejects_perf_exports PASSEDcli_anything/nsight_graphics/tests/test_core.py::TestCoreModules::test_gpu_trace_requires_arch_for_metric_set PASSEDcli_anything/nsight_graphics/tests/test_core.py::TestCoreModules::test_launch_attach_returns_unified_result PASSEDcli_anything/nsight_graphics/tests/test_core.py::TestCoreModules::test_cpp_capture_sets_activity PASSED+cli_anything/nsight_graphics/tests/test_core.py::TestCoreModules::test_gpu_trace_capture_with_summary PASSEDcli_anything/nsight_graphics/tests/test_core.py::TestCLIHelp::test_root_help PASSEDcli_anything/nsight_graphics/tests/test_core.py::TestCLIHelp::test_nsight_path_is_forwarded_to_doctor PASSEDcli_anything/nsight_graphics/tests/test_core.py::TestCLIHelp::test_group_help[args0-info] PASSED@@ -91,20 +95,21 @@ cli_anything/nsight_graphics/tests/test_core.py::TestCLIHelp::test_group_help[arcli_anything/nsight_graphics/tests/test_core.py::TestCLIHelp::test_group_help[args2-detached] PASSEDcli_anything/nsight_graphics/tests/test_core.py::TestCLIHelp::test_group_help[args3-capture] PASSEDcli_anything/nsight_graphics/tests/test_core.py::TestCLIHelp::test_group_help[args4-capture] PASSED-cli_anything/nsight_graphics/tests/test_core.py::TestCLIHelp::test_group_help[args5-capture] PASSED+cli_anything/nsight_graphics/tests/test_core.py::TestCLIHelp::test_group_help[args5-summarize] PASSED+cli_anything/nsight_graphics/tests/test_core.py::TestCLIHelp::test_group_help[args6-capture] PASSEDcli_anything/nsight_graphics/tests/test_core.py::TestCLISubprocess::test_cli_help_subprocess PASSEDcli_anything/nsight_graphics/tests/test_full_e2e.py::TestDoctorE2E::test_doctor_info PASSEDcli_anything/nsight_graphics/tests/test_full_e2e.py::TestTargetedE2E::test_frame_capture SKIPPEDcli_anything/nsight_graphics/tests/test_full_e2e.py::TestTargetedE2E::test_gpu_trace_capture SKIPPEDcli_anything/nsight_graphics/tests/test_full_e2e.py::TestTargetedE2E::test_cpp_capture SKIPPED-======================== 29 passed, 3 skipped in 1.83s ========================+======================== 32 passed, 3 skipped in 1.92s ========================```## Summary Statistics-- Total tests collected: 32-- Passed: 29+- Total tests collected: 35+- Passed: 32- Skipped: 3- Pass rate for executed tests: 100%diff --git a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/tests/test_core.py b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/tests/test_core.pyindex c3c21f2c1..1a33a6ea4 100644--- a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/tests/test_core.py+++ b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/tests/test_core.py@@ -286,6 +286,42 @@ class TestCommandBuilders:assert diff[0]["path"].endswith("capture.ngfx-capture")assert diff[0]["size"] > 0+ def test_gpu_trace_summary_from_export_dir(self, tmp_path):+ base = tmp_path / "BASE"+ base.mkdir()+ (base / "FRAME.xls").write_text("GPU frame time\t31.0446\n", encoding="utf-8")+ (base / "GPUTRACE_FRAME.xls").write_text(+ "\n".join(+ [+ "FE_B.TriageAC.fe__draw_count.sum\t309",+ "FE_A.TriageAC.gr__dispatch_count.sum\t2561",+ "FE_B.TriageAC.gr__cycles_active.avg.pct_of_peak_sustained_elapsed\t98.1079",+ "FE_A.TriageAC.gr__compute_cycles_active_queue_sync.avg.pct_of_peak_sustained_elapsed\t84.24",+ "TriageAC.sm__throughput.avg.pct_of_peak_sustained_elapsed\t23.6331",+ "LTS.TriageAC.lts__throughput.avg.pct_of_peak_sustained_elapsed\t32.0437",+ "FBSP.TriageAC.dramc__throughput.avg.pct_of_peak_sustained_elapsed\t19.5897",+ ]+ ),+ encoding="utf-8",+ )+ (base / "D3DPERF_EVENTS.xls").write_text(+ "event_text\ttime_ms\n"+ "Frame 1221\t31.0431\n"+ "Scene\t29.9644\n"+ " DirectLighting\t15.3828\n"+ " ReSTIRDI\t14.0627\n",+ encoding="utf-8",+ )++ summary = gpu_trace.summarize_export_dir(str(tmp_path), top_n=3)+ assert summary["frame_time_ms"] == pytest.approx(31.0446)+ assert summary["fps_estimate"] == pytest.approx(1000.0 / 31.0446)+ assert summary["metrics"]["draw_count"] == 309+ assert summary["metrics"]["dispatch_count"] == 2561+ assert summary["top_events"][0]["event"] == "Scene"+ assert summary["top_events"][1]["event"] == "DirectLighting"+ assert summary["highlights"]+class TestCoreModules:@patch("cli_anything.nsight_graphics.core.frame.backend.run_with_artifacts")@@ -440,6 +476,66 @@ class TestCoreModules:assert result["activity"] == "Generate C++ Capture"assert result["tool_mode"] == "unified"+ @patch("cli_anything.nsight_graphics.core.gpu_trace.backend.run_with_artifacts")+ @patch("cli_anything.nsight_graphics.core.gpu_trace.backend.build_unified_command")+ @patch("cli_anything.nsight_graphics.core.gpu_trace.backend.probe_installation")+ def test_gpu_trace_capture_with_summary(self, probe_mock, build_mock, run_mock, tmp_path):+ base = tmp_path / "BASE"+ base.mkdir()+ (base / "FRAME.xls").write_text("GPU frame time\t16.0\n", encoding="utf-8")+ (base / "GPUTRACE_FRAME.xls").write_text(+ "FE_B.TriageAC.fe__draw_count.sum\t100\nFE_A.TriageAC.gr__dispatch_count.sum\t50\n",+ encoding="utf-8",+ )+ (base / "D3DPERF_EVENTS.xls").write_text(+ "event_text\ttime_ms\nFrame 1\t16.0\nScene\t10.0\n",+ encoding="utf-8",+ )++ probe_mock.return_value = {+ "binaries": {"ngfx": "C:/Nsight/ngfx.exe", "ngfx_capture": None, "ngfx_replay": None},+ }+ build_mock.return_value = ["C:/Nsight/ngfx.exe", "--activity", "GPU Trace Profiler"]+ run_mock.return_value = {+ "ok": True,+ "returncode": 0,+ "stdout": "",+ "stderr": "",+ "command": "ngfx",+ "artifacts": [],+ "artifact_count": 0,+ }++ result = gpu_trace.capture_trace(+ nsight_path=None,+ project=None,+ output_dir=str(tmp_path),+ hostname=None,+ platform_name=None,+ exe="C:/demo.exe",+ working_dir=None,+ args=(),+ envs=(),+ start_after_frames=1,+ start_after_submits=None,+ start_after_ms=None,+ start_after_hotkey=False,+ max_duration_ms=None,+ limit_to_frames=1,+ limit_to_submits=None,+ auto_export=False,+ architecture=None,+ metric_set_id=None,+ multi_pass_metrics=False,+ real_time_shader_profiler=False,+ summarize=True,+ summary_limit=5,+ )++ assert result["auto_export"] is True+ assert result["summary"]["frame_time_ms"] == pytest.approx(16.0)+ assert result["summary"]["top_events"][0]["event"] == "Scene"+class TestCLIHelp:def test_root_help(self):@@ -478,6 +574,7 @@ class TestCLIHelp:(["launch", "--help"], "detached"),(["frame", "--help"], "capture"),(["gpu-trace", "--help"], "capture"),+ (["gpu-trace", "--help"], "summarize"),(["cpp", "--help"], "capture"),],)diff --git a/registry.json b/registry.jsonindex 977253810..54f521b76 100644--- a/registry.json+++ b/registry.json@@ -657,9 +657,9 @@},{"name": "nsight-graphics",- "display_name": "Nsight Graphics",+ "display_name": "Nsight Graphics CLI","version": "0.1.0",- "description": "Windows-first orchestration of Nsight Graphics launch, Frame Debugger capture, GPU Trace, and Generate C++ Capture",+ "description": "Windows-first Nsight Graphics CLI for Graphics/Frame capture, GPU Trace, Generate C++ Capture, and one-step GPU Trace summary","requires": "NVIDIA Nsight Graphics installation with ngfx.exe or newer split capture/replay tools","homepage": "https://developer.nvidia.com/nsight-graphics","install_cmd": "pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=nsight-graphics/agent-harness",