wehub-resource-sync
84 lines
3.9 KiB
Markdown
84 lines
3.9 KiB
Markdown
# HARNESS.md – RenderDoc CLI Harness Specification
|
||
|
||
## Overview
|
||
|
||
This harness wraps the **RenderDoc** graphics debugger Python API into a Click-based
|
||
CLI tool called `cli-anything-renderdoc`. It enables headless, scriptable analysis
|
||
of GPU frame captures (`.rdc` files) without requiring the RenderDoc GUI.
|
||
|
||
## Architecture
|
||
|
||
```
|
||
agent-harness/
|
||
├── HARNESS.md # This file
|
||
├── RENDERDOC.md # Software-specific SOP
|
||
├── setup.py # PEP 420 namespace package
|
||
└── cli_anything/ # NO __init__.py (namespace package)
|
||
└── renderdoc/ # HAS __init__.py
|
||
├── renderdoc_cli.py # Main CLI entry point (Click)
|
||
├── core/
|
||
│ ├── capture.py # Capture file open/close/metadata/convert
|
||
│ ├── actions.py # Draw call / action tree navigation
|
||
│ ├── textures.py # Texture listing, pixel picking, export
|
||
│ ├── pipeline.py # Pipeline state, shader export, diff, cbuffers
|
||
│ ├── resources.py # Buffer/resource enumeration and reading
|
||
│ ├── mesh.py # Vertex input/output decoding
|
||
│ └── counters.py # GPU performance counters
|
||
├── utils/
|
||
│ ├── output.py # JSON/table output formatting
|
||
│ └── errors.py # Error handling
|
||
├── skills/
|
||
│ └── SKILL.md # AI-discoverable skill definition
|
||
└── tests/
|
||
├── TEST.md # Test plan and results
|
||
├── test_core.py # Unit tests (mock-based, no renderdoc dep)
|
||
└── test_full_e2e.py # E2E tests (requires renderdoc + .rdc files)
|
||
```
|
||
|
||
## Command Groups
|
||
|
||
| Group | Commands |
|
||
|-------------|--------------------------------------------------|
|
||
| `capture` | `info`, `thumb`, `convert` |
|
||
| `actions` | `list`, `summary`, `find`, `get` |
|
||
| `textures` | `list`, `get`, `save`, `save-outputs`, `pick` |
|
||
| `pipeline` | `state`, `shader-export`, `cbuffer`, `diff` |
|
||
| `resources` | `list`, `buffers`, `read-buffer` |
|
||
| `mesh` | `inputs`, `outputs` |
|
||
| `counters` | `list`, `fetch` |
|
||
|
||
## Global Options
|
||
|
||
- `--capture / -c <path>`: Path to the `.rdc` capture file (or `$RENDERDOC_CAPTURE`)
|
||
- `--json`: Output in JSON format (machine-readable)
|
||
- `--debug`: Show tracebacks on errors
|
||
- `--version`: Show version
|
||
|
||
## Patterns
|
||
|
||
1. **Lazy loading**: `renderdoc` module is only imported when a command runs, not at
|
||
CLI parse time. This allows `--help` to work without renderdoc installed.
|
||
2. **CaptureHandle**: Single context manager that owns the CaptureFile and
|
||
ReplayController lifecycle.
|
||
3. **Dict-based returns**: Every core function returns plain `dict`/`list` for
|
||
direct JSON serialisation.
|
||
4. **Dual output**: `_output()` helper picks JSON or human-readable based on `--json`.
|
||
5. **Error dicts**: Errors returned as `{"error": "message"}` rather than exceptions
|
||
at the boundary layer.
|
||
|
||
## Testing Strategy
|
||
|
||
- **Unit tests** (`test_core.py`): Test all core module functions using mocks.
|
||
No dependency on `renderdoc` module. Uses synthetic data.
|
||
- **E2E tests** (`test_full_e2e.py`): Require a real RenderDoc installation and
|
||
at least one `.rdc` capture file. Test full CLI invocation via subprocess.
|
||
- **Subprocess tests**: Invoke the CLI with
|
||
`python -m cli_anything.renderdoc.renderdoc_cli` from `agent-harness/` (see
|
||
`test_core.py` / `test_full_e2e.py`).
|
||
|
||
## Dependencies
|
||
|
||
- **Required**: `click>=8.0`, `prompt-toolkit>=3.0`, `python>=3.10`
|
||
- **Optional** (runtime): `renderdoc` Python module (from RenderDoc installation)
|
||
- **Test**: `pytest>=7.0`
|