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
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,10 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough.

Install bundled diagnostic workflows with `pt-snap skill install`. Agent integration uses skills plus the CLI; there is no MCP server. See the [Agent Skills guide](docs/en/skills.md).

Ascend NPU capture can proceed without `pt-snap` when the host has loaded
`pt-snap-ascend-npu-collect`; the helper routes collection before CLI setup.
Analysis still requires the CLI and a SnapshotDB, with trusted import as a separate decision.

## Documentation

See the [documentation index](docs/README.md) for all English and Chinese guides.
Expand Down
3 changes: 3 additions & 0 deletions README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,9 @@ pt-snap split snapshot.pkl --slices 4 --output snapshot-slices

使用 `pt-snap skill install` 安装随包诊断工作流。Agent 集成入口是 skills 与 CLI,不再提供 MCP 服务器。详见 [Agent Skills 指南](docs/zh/skills.md)。

宿主已加载 `pt-snap-ascend-npu-collect` 时,没有 `pt-snap` 也能进行昇腾 NPU 采集;
helper 会先路由采集,无需先安装 CLI。分析仍需要 CLI 和 SnapshotDB,可信导入是独立决定。

## 文档

全部中英文指南见[文档索引](docs/README.md)。
Expand Down
20 changes: 20 additions & 0 deletions docs/en/skills.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,26 @@

`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 accept 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.

## Collection when the CLI is missing

For Ascend NPU capture, `pt-snap-helper` routes to `pt-snap-ascend-npu-collect`
without requiring `pt-snap-setup` first. The exact collection skill must already
be loaded by the host or load successfully through its supported loader; the
collection skill owns TorchNPU/environment verification. Without the CLI,
catalog/directory status is `unchecked`, reported separately from host-loading
evidence. Readable skill source is not proof of loading.

If loading fails or is unavailable, the helper pauses collection handoff and
explains how to make the known skill directory discoverable and restart, or use
a supported loader. Acquiring a missing skill is a separate user choice; the
helper does not implicitly install packages or skills.

Existing SnapshotDB analysis with a missing CLI still routes to setup. For
capture followed by analysis, collect first, then use setup if the CLI is still
missing. Pickle-only analysis requires an independent trusted-import decision;
setup approval does not approve import. Diagnostic handoff starts only after a
SnapshotDB exists, with the normal capabilities/overview preflight.

## List skills

```bash
Expand Down
16 changes: 16 additions & 0 deletions docs/zh/skills.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,22 @@

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

## CLI 缺失时的采集路由

对于昇腾 NPU 采集,`pt-snap-helper` 会选择 `pt-snap-ascend-npu-collect`,无需先走
`pt-snap-setup`。该采集 skill 必须已被宿主加载,或通过宿主支持的加载器成功加载;
TorchNPU 与环境验证由采集 skill 负责。缺少 CLI 时,目录源和安装目录状态记为
`unchecked`(未检查),与宿主加载证据分别报告。源码可读不能证明已加载。

如果加载失败或没有可用的加载方式,helper 会暂停采集交接,说明如何让宿主发现已知的
skill 目录并重启,或使用支持的加载器。获取缺失的 skill 是独立的用户选择;helper
不会隐式安装 Python 包或 skill。

已有 SnapshotDB 的分析任务在缺 CLI 时仍先交给 setup。先采集再分析的任务先完成采集,
之后若 CLI 仍缺失再走 setup。仅有 pickle 的分析任务需要独立的可信导入决定;批准
setup 不代表批准导入。只有 SnapshotDB 已存在时才交给诊断 skill,并执行正常的
capabilities/overview 前置检查。

## 列出 skill

```bash
Expand Down
52 changes: 44 additions & 8 deletions skills/pt-snap-helper/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,13 @@ 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 `pt-snap` is missing, report catalog/directory status as `unchecked`, not
`missing` or `installed`; do not attempt CLI probes. Choose by the current goal.
For Ascend NPU capture, choose `pt-snap-ascend-npu-collect` first, subject to
host-loading evidence below. For existing SnapshotDB analysis or CLI
installation/verification, stop routing diagnostics and hand off to
`pt-snap-setup`. Pickle-only analysis still requires a separate trusted import
decision. Do not install the Python package from this skill.

### Interpret availability in the inspected scope

Expand Down Expand Up @@ -181,10 +186,15 @@ overview and apply these same checks. Metadata alone does not replace overview.
Choose one next skill. If the goal is still ambiguous after this table, ask
the user; do not start all diagnostic skills.

Apply the capture row first when capture is the current stage, including a
capture-then-analysis request. The missing-CLI analysis cells apply when the
user is ready for analysis, not to the earlier collection stage. Every handoff
requires host-loading evidence; a next-skill name alone is not a completed handoff.

| 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` |
| Collect an Ascend NPU pickle | `pt-snap-ascend-npu-collect` | `pt-snap-ascend-npu-collect` | `pt-snap-ascend-npu-collect` | `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 |
Expand Down Expand Up @@ -282,13 +292,38 @@ If they need to capture a pickle on Ascend NPU first, hand off to

### `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.
For collection, use the collection branch below even without the CLI. For
existing SnapshotDB analysis or an explicit CLI install/verify request, 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.

For pickle-only analysis, explain the independent trusted-input decision and
route to setup if CLI preparation is needed; setup approval is not import
approval. Do not import or deserialize the pickle from this helper.

### 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.
Hand off to `pt-snap-ascend-npu-collect` only when that exact skill is already
loaded by the host or the host's supported loader succeeds. Missing `pt-snap`
does not block collection and does not require setup first. Keep catalog/directory
status `unchecked` when the CLI is absent, and report host-loading evidence
separately. Source readability is not host-loading evidence.

If loading fails or no loader is available, pause the collection handoff and
report the failure or unverified loading. Ask the user to configure the known
skill directory for host discovery and restart, or provide a supported loader
for that exact skill. If no copy is available, explain skill acquisition and
restart as a separate user choice; if the user chooses CLI-based installation,
setup owns package-install approval. Do not install packages or skills implicitly.
Do not replace the unavailable skill with this helper's own collection procedure.

TorchNPU/environment verification remains owned by the collection skill.
Collection ends when a pickle exists on disk. It does not import or diagnose.

For capture followed by analysis, route collection first and record analysis as
a later stage. After capture, route to setup if the CLI is still missing;
trusted import remains an independent decision. Hand off to a diagnostic skill
only after a SnapshotDB exists, with the normal diagnostic preflight.

## Boundaries

Expand All @@ -305,7 +340,8 @@ Report:

- `Goal`
- `Input type` (`snapshotdb`, `pickle`, `missing-cli`, or `npu-collect`)
- `Needed skills` and their `pt-snap skill list --json` status when available
- `Needed skills` and their `pt-snap skill list --json` status when available;
otherwise catalog/directory status `unchecked`, plus separate host-loading evidence
- `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
Expand Down
52 changes: 44 additions & 8 deletions src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,13 @@ 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 `pt-snap` is missing, report catalog/directory status as `unchecked`, not
`missing` or `installed`; do not attempt CLI probes. Choose by the current goal.
For Ascend NPU capture, choose `pt-snap-ascend-npu-collect` first, subject to
host-loading evidence below. For existing SnapshotDB analysis or CLI
installation/verification, stop routing diagnostics and hand off to
`pt-snap-setup`. Pickle-only analysis still requires a separate trusted import
decision. Do not install the Python package from this skill.

### Interpret availability in the inspected scope

Expand Down Expand Up @@ -181,10 +186,15 @@ overview and apply these same checks. Metadata alone does not replace overview.
Choose one next skill. If the goal is still ambiguous after this table, ask
the user; do not start all diagnostic skills.

Apply the capture row first when capture is the current stage, including a
capture-then-analysis request. The missing-CLI analysis cells apply when the
user is ready for analysis, not to the earlier collection stage. Every handoff
requires host-loading evidence; a next-skill name alone is not a completed handoff.

| 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` |
| Collect an Ascend NPU pickle | `pt-snap-ascend-npu-collect` | `pt-snap-ascend-npu-collect` | `pt-snap-ascend-npu-collect` | `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 |
Expand Down Expand Up @@ -282,13 +292,38 @@ If they need to capture a pickle on Ascend NPU first, hand off to

### `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.
For collection, use the collection branch below even without the CLI. For
existing SnapshotDB analysis or an explicit CLI install/verify request, 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.

For pickle-only analysis, explain the independent trusted-input decision and
route to setup if CLI preparation is needed; setup approval is not import
approval. Do not import or deserialize the pickle from this helper.

### 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.
Hand off to `pt-snap-ascend-npu-collect` only when that exact skill is already
loaded by the host or the host's supported loader succeeds. Missing `pt-snap`
does not block collection and does not require setup first. Keep catalog/directory
status `unchecked` when the CLI is absent, and report host-loading evidence
separately. Source readability is not host-loading evidence.

If loading fails or no loader is available, pause the collection handoff and
report the failure or unverified loading. Ask the user to configure the known
skill directory for host discovery and restart, or provide a supported loader
for that exact skill. If no copy is available, explain skill acquisition and
restart as a separate user choice; if the user chooses CLI-based installation,
setup owns package-install approval. Do not install packages or skills implicitly.
Do not replace the unavailable skill with this helper's own collection procedure.

TorchNPU/environment verification remains owned by the collection skill.
Collection ends when a pickle exists on disk. It does not import or diagnose.

For capture followed by analysis, route collection first and record analysis as
a later stage. After capture, route to setup if the CLI is still missing;
trusted import remains an independent decision. Hand off to a diagnostic skill
only after a SnapshotDB exists, with the normal diagnostic preflight.

## Boundaries

Expand All @@ -305,7 +340,8 @@ Report:

- `Goal`
- `Input type` (`snapshotdb`, `pickle`, `missing-cli`, or `npu-collect`)
- `Needed skills` and their `pt-snap skill list --json` status when available
- `Needed skills` and their `pt-snap skill list --json` status when available;
otherwise catalog/directory status `unchecked`, plus separate host-loading evidence
- `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
Expand Down
60 changes: 60 additions & 0 deletions tests/skills/test_helper_contract.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
from pathlib import Path

import pytest
from typer.main import get_command

from pt_snap_cli.cli import app
Expand Down Expand Up @@ -103,6 +104,65 @@ def test_helper_skill_routes_by_goal_and_input_type() -> None:
assert "CSV, SVG, and other visualization files are not SnapshotDB input" in skill


@pytest.mark.parametrize(
("goal", "missing_cli_route"),
[
("Install or verify the CLI", "`pt-snap-setup`"),
("Collect an Ascend NPU pickle", "`pt-snap-ascend-npu-collect`"),
("Leak / live allocations at end of trace", "`pt-snap-setup` first"),
("What was live at a peak event", "`pt-snap-setup` first"),
("Allocator gaps / reserved-pool pressure", "`pt-snap-setup` first"),
],
)
def test_helper_missing_cli_matrix_routes_by_goal(goal: str, missing_cli_route: str) -> None:
matrix = _skill().split("## Routing matrix", 1)[1].split("Exact next-skill names:", 1)[0]
rows = [
[cell.strip() for cell in line.strip("|").split("|")]
for line in matrix.splitlines()
if line.startswith("|")
]
missing_cli_column = rows[0].index("`pt-snap` missing")
row = next(row for row in rows[2:] if row[0] == goal)
assert row[missing_cli_column] == missing_cli_route


def test_helper_missing_cli_preserves_unchecked_status_and_collection_priority() -> None:
prerequisite = " ".join(
_skill()
.split("## Prerequisite: check skill availability", 1)[1]
.split("### Interpret availability", 1)[0]
.split()
)
assert "report catalog/directory status as `unchecked`" in prerequisite
assert "For Ascend NPU capture, choose `pt-snap-ascend-npu-collect` first" in prerequisite
assert "For existing SnapshotDB analysis or CLI installation/verification" in prerequisite
assert "hand off to `pt-snap-setup`" in prerequisite


def test_helper_collection_handoff_requires_host_loading_and_handles_failure() -> None:
collection = " ".join(
_skill().split("### Need Ascend NPU collection", 1)[1].split("## Boundaries", 1)[0].split()
)
assert "already loaded by the host or the host's supported loader succeeds" in collection
assert "Missing `pt-snap` does not block collection" in collection
assert "If loading fails or no loader is available, pause the collection handoff" in collection
assert "configure the known skill directory for host discovery and restart" in collection
assert "Source readability is not host-loading evidence" in collection
assert "Do not install packages or skills implicitly" in collection
assert "TorchNPU/environment verification remains owned by the collection skill" in collection


def test_helper_capture_then_analysis_keeps_separate_stage_decisions() -> None:
missing_cli = " ".join(
_skill().split("### `pt-snap` missing", 1)[1].split("## Boundaries", 1)[0].split()
)
assert "For capture followed by analysis, route collection first" in missing_cli
assert "After capture, route to setup if the CLI is still missing" in missing_cli
assert "trusted import remains an independent decision" in missing_cli
assert "only after a SnapshotDB exists" in missing_cli
assert "For pickle-only analysis, explain the independent trusted-input decision" in missing_cli


def test_helper_skill_keeps_pickle_import_and_focus_as_handoffs() -> None:
skill = _skill()

Expand Down
Loading