diff --git a/README.md b/README.md index 86ad394..1ec60f8 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/README_zh.md b/README_zh.md index 6492873..49661a6 100644 --- a/README_zh.md +++ b/README_zh.md @@ -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)。 diff --git a/docs/en/skills.md b/docs/en/skills.md index a4a0bb5..15dc547 100644 --- a/docs/en/skills.md +++ b/docs/en/skills.md @@ -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 diff --git a/docs/zh/skills.md b/docs/zh/skills.md index ba7dc5b..9217481 100644 --- a/docs/zh/skills.md +++ b/docs/zh/skills.md @@ -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 diff --git a/skills/pt-snap-helper/SKILL.md b/skills/pt-snap-helper/SKILL.md index 0ddba31..1468fd6 100644 --- a/skills/pt-snap-helper/SKILL.md +++ b/skills/pt-snap-helper/SKILL.md @@ -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 @@ -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 | @@ -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 @@ -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 diff --git a/src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md b/src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md index 0ddba31..1468fd6 100644 --- a/src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md +++ b/src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md @@ -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 @@ -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 | @@ -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 @@ -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 diff --git a/tests/skills/test_helper_contract.py b/tests/skills/test_helper_contract.py index adc35fa..a7ed21d 100644 --- a/tests/skills/test_helper_contract.py +++ b/tests/skills/test_helper_contract.py @@ -1,5 +1,6 @@ from pathlib import Path +import pytest from typer.main import get_command from pt_snap_cli.cli import app @@ -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()