You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit fed7ec3
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: README.md
+4Lines changed: 4 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -73,6 +73,10 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough.
73
73
74
74
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).
75
75
76
+
Ascend NPU capture can proceed without `pt-snap` when the host has loaded
77
+
`pt-snap-ascend-npu-collect`; the helper routes collection before CLI setup.
78
+
Analysis still requires the CLI and a SnapshotDB, with trusted import as a separate decision.
79
+
76
80
## Documentation
77
81
78
82
See the [documentation index](docs/README.md) for all English and Chinese guides.
Copy file name to clipboardExpand all lines: docs/en/skills.md
+20Lines changed: 20 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,26 @@
4
4
5
5
`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.
6
6
7
+
## Collection when the CLI is missing
8
+
9
+
For Ascend NPU capture, `pt-snap-helper` routes to `pt-snap-ascend-npu-collect`
10
+
without requiring `pt-snap-setup` first. The exact collection skill must already
11
+
be loaded by the host or load successfully through its supported loader; the
12
+
collection skill owns TorchNPU/environment verification. Without the CLI,
13
+
catalog/directory status is `unchecked`, reported separately from host-loading
14
+
evidence. Readable skill source is not proof of loading.
15
+
16
+
If loading fails or is unavailable, the helper pauses collection handoff and
17
+
explains how to make the known skill directory discoverable and restart, or use
18
+
a supported loader. Acquiring a missing skill is a separate user choice; the
19
+
helper does not implicitly install packages or skills.
20
+
21
+
Existing SnapshotDB analysis with a missing CLI still routes to setup. For
22
+
capture followed by analysis, collect first, then use setup if the CLI is still
23
+
missing. Pickle-only analysis requires an independent trusted-import decision;
24
+
setup approval does not approve import. Diagnostic handoff starts only after a
25
+
SnapshotDB exists, with the normal capabilities/overview preflight.
Copy file name to clipboardExpand all lines: skills/pt-snap-helper/SKILL.md
+44-8Lines changed: 44 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -32,8 +32,13 @@ pt-snap skill list --json
32
32
Parse `skills[].name` and `skills[].status`. Status is `installed`, `outdated`,
33
33
or `missing`.
34
34
35
-
If `pt-snap` is missing, stop routing diagnostics and hand off to
36
-
`pt-snap-setup`. Do not install the Python package from this skill.
35
+
If `pt-snap` is missing, report catalog/directory status as `unchecked`, not
36
+
`missing` or `installed`; do not attempt CLI probes. Choose by the current goal.
37
+
For Ascend NPU capture, choose `pt-snap-ascend-npu-collect` first, subject to
38
+
host-loading evidence below. For existing SnapshotDB analysis or CLI
39
+
installation/verification, stop routing diagnostics and hand off to
40
+
`pt-snap-setup`. Pickle-only analysis still requires a separate trusted import
41
+
decision. Do not install the Python package from this skill.
37
42
38
43
### Interpret availability in the inspected scope
39
44
@@ -181,10 +186,15 @@ overview and apply these same checks. Metadata alone does not replace overview.
181
186
Choose one next skill. If the goal is still ambiguous after this table, ask
182
187
the user; do not start all diagnostic skills.
183
188
189
+
Apply the capture row first when capture is the current stage, including a
190
+
capture-then-analysis request. The missing-CLI analysis cells apply when the
191
+
user is ready for analysis, not to the earlier collection stage. Every handoff
192
+
requires host-loading evidence; a next-skill name alone is not a completed handoff.
193
+
184
194
| User goal | Existing SnapshotDB | Only pickle |`pt-snap` missing | Need Ascend NPU capture |
185
195
| --- | --- | --- | --- | --- |
186
196
| Install or verify the CLI |`pt-snap-setup`|`pt-snap-setup`|`pt-snap-setup`|`pt-snap-setup`|
187
-
| Collect an Ascend NPU pickle |`pt-snap-ascend-npu-collect`|`pt-snap-ascend-npu-collect`|`pt-snap-setup` first|`pt-snap-ascend-npu-collect`|
197
+
| 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`|
188
198
| 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 |
189
199
| 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 |
190
200
| 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 |
@@ -282,13 +292,38 @@ If they need to capture a pickle on Ascend NPU first, hand off to
282
292
283
293
### `pt-snap` missing
284
294
285
-
Hand off to `pt-snap-setup`. That skill owns interpreter selection, ownership
286
-
checks, and install approval. This helper must not run `pip` or assume Conda.
295
+
For collection, use the collection branch below even without the CLI. For
296
+
existing SnapshotDB analysis or an explicit CLI install/verify request, hand off
297
+
to `pt-snap-setup`. That skill owns interpreter selection, ownership checks, and
298
+
install approval. This helper must not run `pip` or assume Conda.
299
+
300
+
For pickle-only analysis, explain the independent trusted-input decision and
301
+
route to setup if CLI preparation is needed; setup approval is not import
302
+
approval. Do not import or deserialize the pickle from this helper.
287
303
288
304
### Need Ascend NPU collection
289
305
290
-
Hand off to `pt-snap-ascend-npu-collect`. Collection ends when a pickle exists
291
-
on disk. It does not import or diagnose.
306
+
Hand off to `pt-snap-ascend-npu-collect` only when that exact skill is already
307
+
loaded by the host or the host's supported loader succeeds. Missing `pt-snap`
308
+
does not block collection and does not require setup first. Keep catalog/directory
309
+
status `unchecked` when the CLI is absent, and report host-loading evidence
310
+
separately. Source readability is not host-loading evidence.
311
+
312
+
If loading fails or no loader is available, pause the collection handoff and
313
+
report the failure or unverified loading. Ask the user to configure the known
314
+
skill directory for host discovery and restart, or provide a supported loader
315
+
for that exact skill. If no copy is available, explain skill acquisition and
316
+
restart as a separate user choice; if the user chooses CLI-based installation,
317
+
setup owns package-install approval. Do not install packages or skills implicitly.
318
+
Do not replace the unavailable skill with this helper's own collection procedure.
319
+
320
+
TorchNPU/environment verification remains owned by the collection skill.
321
+
Collection ends when a pickle exists on disk. It does not import or diagnose.
322
+
323
+
For capture followed by analysis, route collection first and record analysis as
324
+
a later stage. After capture, route to setup if the CLI is still missing;
325
+
trusted import remains an independent decision. Hand off to a diagnostic skill
326
+
only after a SnapshotDB exists, with the normal diagnostic preflight.
292
327
293
328
## Boundaries
294
329
@@ -305,7 +340,8 @@ Report:
305
340
306
341
-`Goal`
307
342
-`Input type` (`snapshotdb`, `pickle`, `missing-cli`, or `npu-collect`)
308
-
-`Needed skills` and their `pt-snap skill list --json` status when available
343
+
-`Needed skills` and their `pt-snap skill list --json` status when available;
344
+
otherwise catalog/directory status `unchecked`, plus separate host-loading evidence
309
345
-`Next skill` (one of the five names)
310
346
-`Install/restart notes` when a skill is missing or outdated
311
347
-`Trusted import notes` when the user only has pickle
Copy file name to clipboardExpand all lines: src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md
+44-8Lines changed: 44 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -32,8 +32,13 @@ pt-snap skill list --json
32
32
Parse `skills[].name` and `skills[].status`. Status is `installed`, `outdated`,
33
33
or `missing`.
34
34
35
-
If `pt-snap` is missing, stop routing diagnostics and hand off to
36
-
`pt-snap-setup`. Do not install the Python package from this skill.
35
+
If `pt-snap` is missing, report catalog/directory status as `unchecked`, not
36
+
`missing` or `installed`; do not attempt CLI probes. Choose by the current goal.
37
+
For Ascend NPU capture, choose `pt-snap-ascend-npu-collect` first, subject to
38
+
host-loading evidence below. For existing SnapshotDB analysis or CLI
39
+
installation/verification, stop routing diagnostics and hand off to
40
+
`pt-snap-setup`. Pickle-only analysis still requires a separate trusted import
41
+
decision. Do not install the Python package from this skill.
37
42
38
43
### Interpret availability in the inspected scope
39
44
@@ -181,10 +186,15 @@ overview and apply these same checks. Metadata alone does not replace overview.
181
186
Choose one next skill. If the goal is still ambiguous after this table, ask
182
187
the user; do not start all diagnostic skills.
183
188
189
+
Apply the capture row first when capture is the current stage, including a
190
+
capture-then-analysis request. The missing-CLI analysis cells apply when the
191
+
user is ready for analysis, not to the earlier collection stage. Every handoff
192
+
requires host-loading evidence; a next-skill name alone is not a completed handoff.
193
+
184
194
| User goal | Existing SnapshotDB | Only pickle |`pt-snap` missing | Need Ascend NPU capture |
185
195
| --- | --- | --- | --- | --- |
186
196
| Install or verify the CLI |`pt-snap-setup`|`pt-snap-setup`|`pt-snap-setup`|`pt-snap-setup`|
187
-
| Collect an Ascend NPU pickle |`pt-snap-ascend-npu-collect`|`pt-snap-ascend-npu-collect`|`pt-snap-setup` first|`pt-snap-ascend-npu-collect`|
197
+
| 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`|
188
198
| 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 |
189
199
| 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 |
190
200
| 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 |
@@ -282,13 +292,38 @@ If they need to capture a pickle on Ascend NPU first, hand off to
282
292
283
293
### `pt-snap` missing
284
294
285
-
Hand off to `pt-snap-setup`. That skill owns interpreter selection, ownership
286
-
checks, and install approval. This helper must not run `pip` or assume Conda.
295
+
For collection, use the collection branch below even without the CLI. For
296
+
existing SnapshotDB analysis or an explicit CLI install/verify request, hand off
297
+
to `pt-snap-setup`. That skill owns interpreter selection, ownership checks, and
298
+
install approval. This helper must not run `pip` or assume Conda.
299
+
300
+
For pickle-only analysis, explain the independent trusted-input decision and
301
+
route to setup if CLI preparation is needed; setup approval is not import
302
+
approval. Do not import or deserialize the pickle from this helper.
287
303
288
304
### Need Ascend NPU collection
289
305
290
-
Hand off to `pt-snap-ascend-npu-collect`. Collection ends when a pickle exists
291
-
on disk. It does not import or diagnose.
306
+
Hand off to `pt-snap-ascend-npu-collect` only when that exact skill is already
307
+
loaded by the host or the host's supported loader succeeds. Missing `pt-snap`
308
+
does not block collection and does not require setup first. Keep catalog/directory
309
+
status `unchecked` when the CLI is absent, and report host-loading evidence
310
+
separately. Source readability is not host-loading evidence.
311
+
312
+
If loading fails or no loader is available, pause the collection handoff and
313
+
report the failure or unverified loading. Ask the user to configure the known
314
+
skill directory for host discovery and restart, or provide a supported loader
315
+
for that exact skill. If no copy is available, explain skill acquisition and
316
+
restart as a separate user choice; if the user chooses CLI-based installation,
317
+
setup owns package-install approval. Do not install packages or skills implicitly.
318
+
Do not replace the unavailable skill with this helper's own collection procedure.
319
+
320
+
TorchNPU/environment verification remains owned by the collection skill.
321
+
Collection ends when a pickle exists on disk. It does not import or diagnose.
322
+
323
+
For capture followed by analysis, route collection first and record analysis as
324
+
a later stage. After capture, route to setup if the CLI is still missing;
325
+
trusted import remains an independent decision. Hand off to a diagnostic skill
326
+
only after a SnapshotDB exists, with the normal diagnostic preflight.
292
327
293
328
## Boundaries
294
329
@@ -305,7 +340,8 @@ Report:
305
340
306
341
-`Goal`
307
342
-`Input type` (`snapshotdb`, `pickle`, `missing-cli`, or `npu-collect`)
308
-
-`Needed skills` and their `pt-snap skill list --json` status when available
343
+
-`Needed skills` and their `pt-snap skill list --json` status when available;
344
+
otherwise catalog/directory status `unchecked`, plus separate host-loading evidence
309
345
-`Next skill` (one of the five names)
310
346
-`Install/restart notes` when a skill is missing or outdated
311
347
-`Trusted import notes` when the user only has pickle
0 commit comments