Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ when they exist.
| Package source | [src/AGENTS.md](src/AGENTS.md) | Installable package boundaries and source-layout rules |
| Tests | [tests/AGENTS.md](tests/AGENTS.md) | Cross-surface contracts, service/query/runtime suites, and reviewed executable fixtures |
| Benchmarks | [benchmarks/AGENTS.md](benchmarks/AGENTS.md) | Import and SQLite performance measurement with temporary outputs |
| Agent skills | [skills/AGENTS.md](skills/AGENTS.md) | Installation approval, Ascend NPU collection, and read-only memory-diagnostic workflows |
| Agent skills | [skills/AGENTS.md](skills/AGENTS.md) | Helper routing, installation approval, Ascend NPU collection, and read-only memory-diagnostic workflows |

## Runtime Topology

Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,8 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough.
| `pt-snap skill` | List and install bundled agent skills |
| `pt-snap-mcp` | Start the MCP server for agent integration |

`pt-snap --help` includes an agent hint: prefer `--json` where supported, start with the `pt-snap-helper` skill, and check availability with `pt-snap skill list --json`.

## MCP Server

`pt-snap-cli` provides an MCP (Model Context Protocol) server so AI agents can interact with PyTorch memory snapshots programmatically.
Expand Down
2 changes: 2 additions & 0 deletions README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,8 @@ pt-snap split snapshot.pkl --slices 4 --output snapshot-slices
| `pt-snap skill` | 列出并安装随包 agent skill |
| `pt-snap-mcp` | 启动 MCP 服务器以支持 Agent 集成 |

`pt-snap --help` 含 Agent 提示:在当前已支持的命令上优先使用 `--json`,从 `pt-snap-helper` skill 开始,并用 `pt-snap skill list --json` 检查是否已安装。

## MCP 服务器

`pt-snap-cli` 提供了 MCP(Model Context Protocol)服务器,使 AI Agent 能够以编程方式与 PyTorch 内存快照交互。
Expand Down
2 changes: 1 addition & 1 deletion docs/en/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
| `focus-management.md` | Focus resolution, project focus files, environment variables, and global config behavior. |
| `querying.md` | Query listing, template info, parameter usage, result limits, and built-in templates. |
| `splitting.md` | Snapshot slicing strategies, output formats, replay validation, and publication guarantees. |
| `skills.md` | Bundled agent-skill listing, install destinations, and status meanings. |
| `skills.md` | Bundled agent-skill listing, helper entry, install destinations, and status meanings. |
| `mcp.md` | MCP server setup, tools, resources, prompts, and agent usage. |
| `database.md` | Snapshot SQLite table/schema reference. |
| `snapshot-analyzer-api.md` | High-level Python API for focus, template discovery, queries, and import metadata. |
Expand Down
3 changes: 2 additions & 1 deletion docs/en/skills.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

[中文](../zh/skills.md) | English

`pt-snap-cli` ships agent skills for setup, Ascend NPU collection, and memory diagnostics. The `pt-snap skill` commands copy those skills into the shared Agent Skills directory and into host-specific directories that Claude Code still requires.
`pt-snap-cli` ships agent skills for routing (`pt-snap-helper`), setup, Ascend NPU collection, and memory diagnostics. Agents should start with `pt-snap-helper` and prefer `--json` on commands that currently support it. The `pt-snap skill` commands copy those skills into the shared Agent Skills directory and into host-specific directories that Claude Code still requires.

## List skills

Expand Down Expand Up @@ -79,6 +79,7 @@ After an install, upgrade, or uninstall that changes skill files, restart the ag

| Skill | Use when |
|-------|----------|
| `pt-snap-helper` | Choosing the next skill from the user goal and input type |
| `pt-snap-setup` | Installing or verifying `pt-snap-cli` in the active Python environment |
| `pt-snap-ascend-npu-collect` | Collecting an Ascend NPU memory snapshot pickle |
| `pt-snap-memory-leak` | Diagnosing live allocations and leak candidates in a SnapshotDB |
Expand Down
2 changes: 1 addition & 1 deletion docs/zh/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
| `focus-management.md` | Chinese guide to focus resolution and persistence. |
| `querying.md` | Chinese guide to query templates, parameters, and output. |
| `splitting.md` | Chinese guide to snapshot slicing, formats, replay validation, and publication. |
| `skills.md` | Chinese guide to bundled agent-skill listing and installation. |
| `skills.md` | Chinese guide to bundled agent-skill listing, helper entry, and installation. |
| `mcp.md` | Chinese MCP server setup and tool reference. |
| `database.md` | Chinese snapshot SQLite schema reference. |
| `snapshot-analyzer-api.md` | Chinese guide to the high-level focus, query, and metadata Python API. |
Expand Down
3 changes: 2 additions & 1 deletion docs/zh/skills.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

[English](../en/skills.md) | 中文

`pt-snap-cli` 附带用于环境安装、昇腾 NPU 采集和内存诊断的 agent skill。`pt-snap skill` 命令会把这些 skill 复制到共享的 Agent Skills 目录,以及 Claude Code 仍然需要的独立目录。
`pt-snap-cli` 附带用于路由(`pt-snap-helper`)、环境安装、昇腾 NPU 采集和内存诊断的 agent skill。Agent 应先使用 `pt-snap-helper`,并在当前已支持的命令上优先使用 `--json`。`pt-snap skill` 命令会把这些 skill 复制到共享的 Agent Skills 目录,以及 Claude Code 仍然需要的独立目录。

## 列出 skill

Expand Down Expand Up @@ -79,6 +79,7 @@ pt-snap skill uninstall --project --target cursor

| Skill | 适用场景 |
|-------|----------|
| `pt-snap-helper` | 根据用户目标和输入类型选择下一步 skill |
| `pt-snap-setup` | 在当前 Python 环境安装或验证 `pt-snap-cli` |
| `pt-snap-ascend-npu-collect` | 采集昇腾 NPU 内存快照 pickle |
| `pt-snap-memory-leak` | 在 SnapshotDB 中诊断仍存活分配和泄漏候选 |
Expand Down
9 changes: 8 additions & 1 deletion skills/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
# skills

## Purpose
`skills` contains agent workflows shipped with the repository. Setup owns the
`skills` contains agent workflows shipped with the repository. The helper
skill is a read-only router by user goal and input type. Setup owns the
only Python-environment mutation boundary and installs after explicit approval;
collection skills guide Ascend NPU snapshot capture without importing
or diagnosing the pickle; diagnostic skills consume installed `pt-snap`
Expand All @@ -12,6 +13,7 @@ surfaces against existing SnapshotDB data without writes.
## Scope
| Path | Responsibility |
| --- | --- |
| `pt-snap-helper/SKILL.md` | Routes by user goal and input type to the five skills; checks `pt-snap skill list --json`; does not install, import, or persist focus. |
| `pt-snap-setup/SKILL.md` | Detect the active interpreter, verify CLI ownership, request install approval, and re-verify the same environment. |
| `pt-snap-ascend-npu-collect/SKILL.md` | Collect Ascend NPU pickles via native APIs, framework config, or OOM env; inventory artifacts without import or diagnosis. |
| `pt-snap-memory-leak/SKILL.md` | Diagnose end-of-trace live allocations, peak survival, callstack attribution, and release evidence without persisting analysis state. |
Expand All @@ -32,6 +34,8 @@ surfaces against existing SnapshotDB data without writes.
turn allocator gaps into definitive fragmentation claims.
- Diagnostic skills pass the database and device explicitly and delegate missing
tooling to `pt-snap-setup`.
- Helper skills stay read-only navigation. They must not install packages, copy
skills, import pickle, persist focus, or run diagnostic analysis.
- Prefer packaged query templates for diagnostics. Any raw SQLite fallback must
document why a template is insufficient and enforce read-only access.

Expand All @@ -45,6 +49,9 @@ an explicit `--dir`. After install or upgrade, the host agent must be
restarted.

## Focused Tests
- Run `pytest tests/skills/test_helper_contract.py` after helper-skill changes.
Static coverage checks routing names, current `--json` capability, skill-list
availability, and the pickle/focus/install read-only boundary.
- Run `pytest tests/skills/test_setup_contract.py` after setup-skill changes. The current executable test covers active-interpreter path preservation; review the remaining approval and reporting instructions statically.
- Run `pytest tests/skills/test_ascend_npu_collect_contract.py` after
collection-skill changes. The v1 evaluation harness accepts only
Expand Down
169 changes: 169 additions & 0 deletions skills/pt-snap-helper/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
---
name: pt-snap-helper
description: Use as the first pt-snap entry when the next skill is unclear. Routes by user goal and input type (existing SnapshotDB, pickle-only, missing CLI, Ascend NPU collection) to pt-snap-setup, pt-snap-ascend-npu-collect, pt-snap-memory-leak, pt-snap-memory-peak-breakdown, or pt-snap-memory-fragmentation. Prefers --json on commands that currently support it.
---

# pt-snap-helper

## Overview

This is a read-only navigator. Choose the next skill from the user's goal and
input type. Do not install packages, do not copy skills into agent directories,
do not import or deserialize pickle, and do not persist focus.

Use this skill when:

- The user first asks about pt-snap and the next skill is unclear.
- The host has several pt-snap skills and needs a routing decision.
- The user has a SnapshotDB, a pickle, no CLI, or needs Ascend NPU collection.

Do not use this skill to run leak, peak, or fragmentation analysis. Hand off to
the matching diagnostic skill after routing.

## Prerequisite: check skill availability

If `pt-snap` is on PATH, inspect bundled skill status with JSON:

```bash
command -v pt-snap
pt-snap skill list --json
```

Parse `skills[].name` and `skills[].status`. Status is `installed`, `outdated`,
or `missing`.

If `pt-snap` is missing, stop routing diagnostics and hand off to
`pt-snap-setup`. Do not install the Python package from this skill.

If a needed skill is `missing` or `outdated`, tell the user how to install or
upgrade it. Do not run install or upgrade from this skill.

Install or upgrade examples the user can run after they confirm they want
the skills installed or updated. Do not run these commands from this skill:

```bash
pt-snap skill install pt-snap-helper --json
pt-snap skill install --json
Comment thread
codeasier marked this conversation as resolved.
Resolved
pt-snap skill upgrade pt-snap-helper --json
pt-snap skill upgrade --json
```

After any install, upgrade, or uninstall that changes skill files, the host
agent must be restarted before the change is visible:

Restart the agent after install, upgrade, or uninstall so the skill change takes effect.

`pt-snap skill list` does not require a restart.

## Prefer `--json` where supported

Prefer `--json` on commands that currently accept it:

- `pt-snap skill list --json`
- `pt-snap skill install --json`
- `pt-snap skill upgrade --json`
- `pt-snap skill uninstall --json`
- `pt-snap metadata '<db_path>' --json`
- `pt-snap report peak-memory '<db_path>' --device <device_id> --json`

Do not add `--json` to `query`, `focus`, `import`, `split`, or `config`. Those
commands do not support it yet. Do not invent a global `--json` flag on `pt-snap`.

This skill itself does not run analysis queries. The diagnostic skills own
those commands.

## Routing matrix

Choose one next skill. If the goal is still ambiguous after this table, ask
the user; do not start all diagnostic skills.

| User goal | Existing SnapshotDB | Only pickle | `pt-snap` missing | Need Ascend NPU capture |
| --- | --- | --- | --- | --- |
| Install or verify the CLI | `pt-snap-setup` | `pt-snap-setup` | `pt-snap-setup` | `pt-snap-setup` |
| Collect an Ascend NPU pickle | `pt-snap-ascend-npu-collect` | `pt-snap-ascend-npu-collect` | `pt-snap-setup` first | `pt-snap-ascend-npu-collect` |
| Leak / live allocations at end of trace | `pt-snap-memory-leak` | Trusted import first, then leak | `pt-snap-setup` first | Collect first, then trusted import, then leak |
| What was live at a peak event | `pt-snap-memory-peak-breakdown` | Trusted import first, then peak | `pt-snap-setup` first | Collect first, then trusted import, then peak |
| Allocator gaps / reserved-pool pressure | `pt-snap-memory-fragmentation` | Trusted import first, then fragmentation | `pt-snap-setup` first | Collect first, then trusted import, then fragmentation |

Exact next-skill names:

- `pt-snap-setup`
- `pt-snap-ascend-npu-collect`
- `pt-snap-memory-leak`
- `pt-snap-memory-peak-breakdown`
- `pt-snap-memory-fragmentation`

CSV, SVG, and other visualization files are not SnapshotDB input. If the user
only has those, stop and ask for a `.db` or a trusted pickle.

### Existing SnapshotDB

A SnapshotDB is a pt-snap SQLite database (typically `.db`) with a
`dictionary` table. When the user already has one:

1. Confirm the goal is leak, peak, or fragmentation.
2. Hand off to the matching diagnostic skill. Pass the database path and
device if the user supplied them.
3. Do not run `pt-snap focus <database_path>` to persist a new focus from this
skill. Diagnostic skills may read the current focus with no arguments.

This helper may mention that `pt-snap metadata '<db_path>' --json` exists.
Running that check belongs to the diagnostic skill.

### Only pickle

A `.pkl` / `.pickle` file is not a SnapshotDB. Pickle import is trusted-code
execution, not a sandbox.

From this skill:

- Do not open, import, inspect, or deserialize pickle input.
- Do not run `pt-snap import`.
- Do not run `pt-snap split`.
- Do not run `pt-snap focus` with a database path.

Tell the user that import is an independent trusted-input decision. If they
confirm the pickle is trusted and they want a SnapshotDB, they can run:

```bash
pt-snap import <snapshot.pkl>
```

That command currently has no `--json` option. Import may update focus unless
they pass `--no-focus`. This helper must not run that command or change focus.

After the user has a SnapshotDB, route to the matching diagnostic skill.

If they need to capture a pickle on Ascend NPU first, hand off to
`pt-snap-ascend-npu-collect` instead of importing.

### `pt-snap` missing

Hand off to `pt-snap-setup`. That skill owns interpreter selection, ownership
checks, and install approval. This helper must not run `pip` or assume Conda.

### Need Ascend NPU collection

Hand off to `pt-snap-ascend-npu-collect`. Collection ends when a pickle exists
on disk. It does not import or diagnose.

## Boundaries

- Keep this skill read-only. Do not install Python packages, and do not write files.
- Do not run `pt-snap skill install` / `upgrade` / `uninstall`.
- Do not persist focus or edit configuration.
- Do not start leak, peak, fragmentation, or OOM-root-cause analysis here.
- Do not classify allocations or allocator gaps.
- Use the five skill names above exactly; do not invent aliases.

## Output

Report:

- `Goal`
- `Input type` (`snapshotdb`, `pickle`, `missing-cli`, or `npu-collect`)
- `Needed skills` and their `pt-snap skill list --json` status when available
- `Next skill` (one of the five names)
- `Install/restart notes` when a skill is missing or outdated
- `Trusted import notes` when the user only has pickle
- `Unknowns`
Loading
Loading