Skip to content

Commit fed7ec3

Browse files
codeasiercodeasier
andauthored
fix(skills): route Ascend collection before CLI setup (#190)
Co-authored-by: codeasier <liuyekang@huawei.com>
1 parent d269dfa commit fed7ec3

7 files changed

Lines changed: 191 additions & 16 deletions

File tree

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,10 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough.
7373

7474
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).
7575

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+
7680
## Documentation
7781

7882
See the [documentation index](docs/README.md) for all English and Chinese guides.

‎README_zh.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,9 @@ pt-snap split snapshot.pkl --slices 4 --output snapshot-slices
6868

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

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

7376
全部中英文指南见[文档索引](docs/README.md)。

‎docs/en/skills.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,26 @@
44

55
`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.
66

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.
26+
727
## List skills
828

929
```bash

‎docs/zh/skills.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,22 @@
44

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

7+
## CLI 缺失时的采集路由
8+
9+
对于昇腾 NPU 采集,`pt-snap-helper` 会选择 `pt-snap-ascend-npu-collect`,无需先走
10+
`pt-snap-setup`。该采集 skill 必须已被宿主加载,或通过宿主支持的加载器成功加载;
11+
TorchNPU 与环境验证由采集 skill 负责。缺少 CLI 时,目录源和安装目录状态记为
12+
`unchecked`(未检查),与宿主加载证据分别报告。源码可读不能证明已加载。
13+
14+
如果加载失败或没有可用的加载方式,helper 会暂停采集交接,说明如何让宿主发现已知的
15+
skill 目录并重启,或使用支持的加载器。获取缺失的 skill 是独立的用户选择;helper
16+
不会隐式安装 Python 包或 skill。
17+
18+
已有 SnapshotDB 的分析任务在缺 CLI 时仍先交给 setup。先采集再分析的任务先完成采集,
19+
之后若 CLI 仍缺失再走 setup。仅有 pickle 的分析任务需要独立的可信导入决定;批准
20+
setup 不代表批准导入。只有 SnapshotDB 已存在时才交给诊断 skill,并执行正常的
21+
capabilities/overview 前置检查。
22+
723
## 列出 skill
824

925
```bash

‎skills/pt-snap-helper/SKILL.md‎

Lines changed: 44 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,13 @@ pt-snap skill list --json
3232
Parse `skills[].name` and `skills[].status`. Status is `installed`, `outdated`,
3333
or `missing`.
3434

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.
3742

3843
### Interpret availability in the inspected scope
3944

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

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+
184194
| User goal | Existing SnapshotDB | Only pickle | `pt-snap` missing | Need Ascend NPU capture |
185195
| --- | --- | --- | --- | --- |
186196
| 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` |
188198
| 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 |
189199
| 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 |
190200
| 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
282292

283293
### `pt-snap` missing
284294

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.
287303

288304
### Need Ascend NPU collection
289305

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.
292327

293328
## Boundaries
294329

@@ -305,7 +340,8 @@ Report:
305340

306341
- `Goal`
307342
- `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
309345
- `Next skill` (one of the five names)
310346
- `Install/restart notes` when a skill is missing or outdated
311347
- `Trusted import notes` when the user only has pickle

‎src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md‎

Lines changed: 44 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,13 @@ pt-snap skill list --json
3232
Parse `skills[].name` and `skills[].status`. Status is `installed`, `outdated`,
3333
or `missing`.
3434

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.
3742

3843
### Interpret availability in the inspected scope
3944

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

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+
184194
| User goal | Existing SnapshotDB | Only pickle | `pt-snap` missing | Need Ascend NPU capture |
185195
| --- | --- | --- | --- | --- |
186196
| 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` |
188198
| 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 |
189199
| 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 |
190200
| 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
282292

283293
### `pt-snap` missing
284294

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.
287303

288304
### Need Ascend NPU collection
289305

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.
292327

293328
## Boundaries
294329

@@ -305,7 +340,8 @@ Report:
305340

306341
- `Goal`
307342
- `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
309345
- `Next skill` (one of the five names)
310346
- `Install/restart notes` when a skill is missing or outdated
311347
- `Trusted import notes` when the user only has pickle

‎tests/skills/test_helper_contract.py‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
from pathlib import Path
22

3+
import pytest
34
from typer.main import get_command
45

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

105106

107+
@pytest.mark.parametrize(
108+
("goal", "missing_cli_route"),
109+
[
110+
("Install or verify the CLI", "`pt-snap-setup`"),
111+
("Collect an Ascend NPU pickle", "`pt-snap-ascend-npu-collect`"),
112+
("Leak / live allocations at end of trace", "`pt-snap-setup` first"),
113+
("What was live at a peak event", "`pt-snap-setup` first"),
114+
("Allocator gaps / reserved-pool pressure", "`pt-snap-setup` first"),
115+
],
116+
)
117+
def test_helper_missing_cli_matrix_routes_by_goal(goal: str, missing_cli_route: str) -> None:
118+
matrix = _skill().split("## Routing matrix", 1)[1].split("Exact next-skill names:", 1)[0]
119+
rows = [
120+
[cell.strip() for cell in line.strip("|").split("|")]
121+
for line in matrix.splitlines()
122+
if line.startswith("|")
123+
]
124+
missing_cli_column = rows[0].index("`pt-snap` missing")
125+
row = next(row for row in rows[2:] if row[0] == goal)
126+
assert row[missing_cli_column] == missing_cli_route
127+
128+
129+
def test_helper_missing_cli_preserves_unchecked_status_and_collection_priority() -> None:
130+
prerequisite = " ".join(
131+
_skill()
132+
.split("## Prerequisite: check skill availability", 1)[1]
133+
.split("### Interpret availability", 1)[0]
134+
.split()
135+
)
136+
assert "report catalog/directory status as `unchecked`" in prerequisite
137+
assert "For Ascend NPU capture, choose `pt-snap-ascend-npu-collect` first" in prerequisite
138+
assert "For existing SnapshotDB analysis or CLI installation/verification" in prerequisite
139+
assert "hand off to `pt-snap-setup`" in prerequisite
140+
141+
142+
def test_helper_collection_handoff_requires_host_loading_and_handles_failure() -> None:
143+
collection = " ".join(
144+
_skill().split("### Need Ascend NPU collection", 1)[1].split("## Boundaries", 1)[0].split()
145+
)
146+
assert "already loaded by the host or the host's supported loader succeeds" in collection
147+
assert "Missing `pt-snap` does not block collection" in collection
148+
assert "If loading fails or no loader is available, pause the collection handoff" in collection
149+
assert "configure the known skill directory for host discovery and restart" in collection
150+
assert "Source readability is not host-loading evidence" in collection
151+
assert "Do not install packages or skills implicitly" in collection
152+
assert "TorchNPU/environment verification remains owned by the collection skill" in collection
153+
154+
155+
def test_helper_capture_then_analysis_keeps_separate_stage_decisions() -> None:
156+
missing_cli = " ".join(
157+
_skill().split("### `pt-snap` missing", 1)[1].split("## Boundaries", 1)[0].split()
158+
)
159+
assert "For capture followed by analysis, route collection first" in missing_cli
160+
assert "After capture, route to setup if the CLI is still missing" in missing_cli
161+
assert "trusted import remains an independent decision" in missing_cli
162+
assert "only after a SnapshotDB exists" in missing_cli
163+
assert "For pickle-only analysis, explain the independent trusted-input decision" in missing_cli
164+
165+
106166
def test_helper_skill_keeps_pickle_import_and_focus_as_handoffs() -> None:
107167
skill = _skill()
108168

0 commit comments

Comments
 (0)