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 @@ -51,7 +51,7 @@ when they exist.

| Surface | Entry point | Responsibility |
| --- | --- | --- |
| CLI | `src/pt_snap_cli/cli.py` via `pt_snap_cli.cli:_safe_call` | Typer commands for focus, import, split, metadata, query, reports, config, and skill install/list |
| CLI | `src/pt_snap_cli/cli.py` via `pt_snap_cli.cli:_safe_call` | Typer commands for focus, import, split, metadata, capabilities, overview, query, reports, config, and skill install/list |
| Python API | `src/pt_snap_cli/api.py` (`SnapshotAnalyzer`) | Programmatic focus, query, and metadata facade |
| Product services | `src/pt_snap_cli/core/` | Shared focus, import, split, query, report, metadata, and error semantics |
| Database access | `src/pt_snap_cli/context.py` | Read-only SQLite validation, connection management, and device discovery |
Expand Down
5 changes: 4 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@

### 新增

- 新增 `pt-snap capabilities`:一次输出 CLI 版本、全部查询模板/参数契约(含字段语义)和技能清单。`--json` 使用 #138 成功信封,替代逐个 `--template-info` 探测。
- 新增 `pt-snap overview`:只读输出设备列表、各设备首/末 event id,以及导入 metadata 状态。`--json` 使用同一信封;分析路径不写数据库、不持久化 focus。
- 新增 `preexisting_live` 与 `freed_block_lifetime` 查询模板,泄漏技能不再依赖 `sqlite3` CLI 回退。`preexisting_live` 排除 `freeEventId = -1` 的 static 块,与 `active_memory_callstack_at_event` 的 `[preexisting live]` 分组一致。诊断前置探测从 7 次(`metadata` + 六个 `--template-info`)降为 2 次(`capabilities` + `overview`)。helper 引导「先概览、再诊断」。
- `focus`、`import`、`split`、`query`、`config` 支持 `--json`。成功结果带 `schema_version` / `ok` 信封,以及 `db_path`、`focus_source`、`device_id`、`template`、`effective_params` 等上下文。`query --list` / `--template-info` / 执行共用该选项;`--template-info --json` 透出 #147 字段语义。
- JSON 模式失败时 stdout 为空,stderr 为带稳定错误码的结构化对象(如 `TEMPLATE_NOT_FOUND`、`INVALID_PARAMETER`、`DATABASE_NOT_FOUND`、`DEVICE_NOT_FOUND`),退出码非零。`pt-snap` 控制台入口返回 Typer/Click 的退出码(不再丢弃非 standalone 返回值),在检测到 `--json` 时也会把 Click 用法/解析错误写成 `INVALID_PARAMETER` 信封(退出码 2),并把 Ctrl-C / EOF 写成 `ERROR` / `Aborted!`。解析失败时的 `--json` 判定是 argv 词法扫描(best-effort):忽略 `--` 之后的词,`--opt=value` 与数字词不吞后续参数。`query --json` 的 `effective_params.limit` 是尾部 SQL `LIMIT`(模板 `limit` 与 `-n` 的合并,或追加的 `-n`);CTE 内的 `top_n` 仍是独立参数。
- `split --json` 只控制 stdout 清单,与 `--format json` 的分片文件格式相互独立。`focus --session --json` 返回验证结果与 `PT_SNAP_DB_PATH` 赋值信息,不暗示已修改父 shell。
Expand All @@ -12,7 +15,7 @@
### 兼容性提示

- 文本模式保持原样:人类可读输出不变,`_error()` 与查询/报告说明行仍写 stdout。缺失模板的 `query --template-info` 已在 0.4.0 以退出码 1 失败。数据库无设备时,文本模式查询仍退出 0;JSON 模式改为 `DEVICE_NOT_FOUND` 且退出码非零。
- 已有 `metadata --json`、`report peak-memory --json` 与 `skill list/install/upgrade/uninstall --json` 成功字段保持兼容,不包进新信封。它们在 `--json` 失败时改走 stderr 错误信封。
- 已有 `metadata --json`、`report peak-memory --json` 与 `skill list/install/upgrade/uninstall --json` 成功字段保持兼容,不包进新信封。它们在 `--json` 失败时改走 stderr 错误信封。新的 `capabilities --json` 与 `overview --json` 使用 #138 成功/失败信封。`capabilities` 在技能目录不可读时走 `SKILL_ERROR`;`overview` 把损坏的设备表/边界查询翻译为 `DATABASE_SCHEMA_INVALID`,并把损坏的 focus 文件翻译为 `FOCUS_FILE_INVALID`。
- 查询默认 `total` 不再在触达 `-n` 时自动变成匹配集合 `COUNT`。依赖该旧语义的调用方必须显式传 `--exact-total` / `exact_total=True`。

## [0.4.0] - Unreleased
Expand Down
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,12 +60,14 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough.
| `pt-snap import <snapshot.pkl>` | Import a PyTorch memory snapshot pickle into a SnapshotDB |
| `pt-snap split <snapshot.pkl>` | Create replayable per-device snapshot slices |
| `pt-snap metadata [database.db]` | Inspect SnapshotDB import provenance and compatibility metadata |
| `pt-snap capabilities` | List CLI version, query template contracts, and bundled skills |
| `pt-snap overview [database.db]` | Read-only device list, per-device event-id bounds, and import-metadata status |
| `pt-snap query` | Run memory analysis queries |
| `pt-snap report` | Generate higher-level memory analysis reports |
| `pt-snap config` | Manage global configuration |
| `pt-snap skill` | List and install bundled agent skills |

`pt-snap --help` includes an agent hint: prefer `--json` on the command that supports it, start with the `pt-snap-helper` skill, and check availability with `pt-snap skill list --json`. `focus`, `import`, `split`, `query`, `config`, `metadata`, `report peak-memory`, and `skill list/install/upgrade/uninstall` accept `--json`.
`pt-snap --help` includes an agent hint: prefer `--json` on the command that supports it, start with the `pt-snap-helper` skill, use `pt-snap capabilities --json` and `pt-snap overview --json` before diagnosing, and check availability with `pt-snap skill list --json`. `focus`, `import`, `split`, `query`, `config`, `capabilities`, `overview`, `metadata`, `report peak-memory`, and `skill list/install/upgrade/uninstall` accept `--json`.

## Agent Skills

Expand Down
4 changes: 3 additions & 1 deletion README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,12 +55,14 @@ pt-snap split snapshot.pkl --slices 4 --output snapshot-slices
| `pt-snap import <snapshot.pkl>` | 将 PyTorch 原始内存快照导入 SnapshotDB |
| `pt-snap split <snapshot.pkl>` | 创建可回放的逐设备快照切片 |
| `pt-snap metadata [database.db]` | 查看 SnapshotDB 的导入来源与兼容性 metadata |
| `pt-snap capabilities` | 列出 CLI 版本、查询模板契约和随包 skill |
| `pt-snap overview [database.db]` | 只读输出设备列表、各设备 event id 边界和导入 metadata 状态 |
| `pt-snap query` | 运行内存分析查询 |
| `pt-snap report` | 生成高层内存分析报告 |
| `pt-snap config` | 管理全局配置 |
| `pt-snap skill` | 列出并安装随包 agent skill |

`pt-snap --help` 含 Agent 提示:在支持该选项的命令上优先使用 `--json`,从 `pt-snap-helper` skill 开始,并用 `pt-snap skill list --json` 检查是否已安装。`focus`、`import`、`split`、`query`、`config`、`metadata`、`report peak-memory` 和 `skill list/install/upgrade/uninstall` 均接受 `--json`。
`pt-snap --help` 含 Agent 提示:在支持该选项的命令上优先使用 `--json`,从 `pt-snap-helper` skill 开始,诊断前先用 `pt-snap capabilities --json` 和 `pt-snap overview --json`,并用 `pt-snap skill list --json` 检查是否已安装。`focus`、`import`、`split`、`query`、`config`、`capabilities`、`overview`、`metadata`、`report peak-memory` 和 `skill list/install/upgrade/uninstall` 均接受 `--json`。

## Agent Skills

Expand Down
2 changes: 1 addition & 1 deletion docs/en/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
| `splitting.md` | Snapshot slicing strategies, output formats, replay validation, and publication guarantees. |
| `skills.md` | Bundled agent-skill listing, helper entry, install destinations, and status meanings. |
| `database.md` | Snapshot SQLite table/schema reference. |
| `snapshot-analyzer-api.md` | High-level Python API for focus, template discovery, queries, and import metadata. |
| `snapshot-analyzer-api.md` | High-level Python API for focus, template discovery, capabilities, overview, queries, and import metadata. |
| `result-mapper-api.md` | Result mapping API documentation. |

## Subdirectories
Expand Down
7 changes: 6 additions & 1 deletion docs/en/database.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,10 @@ existing target only when the full source SHA-256, import format version, and de
Package version changes alone do not invalidate the cache.

```bash
# Inspect devices, trace bounds, and import-metadata status
pt-snap overview snapshot.pkl.db
pt-snap overview snapshot.pkl.db --json

# Inspect provenance and compatibility metadata
pt-snap metadata snapshot.pkl.db
pt-snap metadata snapshot.pkl.db --json
Expand Down Expand Up @@ -77,7 +81,8 @@ pt-snap query --template-use memory_peak
pt-snap query --template-use block --params '{"min_size": 1048576}'
```

Use `pt-snap query --list` and `pt-snap query --template-info <name>` to inspect
Use `pt-snap capabilities --json` for the full template catalog, or
`pt-snap query --list` and `pt-snap query --template-info <name>` to inspect
the supported query surface. `event`, `callstack_analysis`, and
`active_memory_callstack_at_event` work on both the current deduplicated
callstack schema and older inline-text databases; see
Expand Down
6 changes: 5 additions & 1 deletion docs/en/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ pt-snap query [DB_PATH] [--template-use <template_name>] [--params <json>] \

## Query Templates

Templates are organized into three categories. Use `pt-snap query --list` to see them all, or filter with `--category`.
Templates are organized into three categories. Use `pt-snap capabilities --json` for the full catalog (CLI version, every template contract, and bundled skills), or `pt-snap query --list` to see names and descriptions. Filter with `--category`.

### Basic Queries

Expand Down Expand Up @@ -65,6 +65,8 @@ Domain-specific analysis.
|----------|-------------|
| `leak_detection` | Find captured allocations with no recorded free-completion event (leak candidates) |
| `active_memory_callstack_at_event` | Aggregate blocks active at a specific event by allocation callstack, with static and preexisting memory classified separately |
| `preexisting_live` | Count preexisting-live blocks at an event (`allocEventId=-1` still live, including `freeEventId IS NULL`) |
| `freed_block_lifetime` | Bucket successfully freed blocks by `freeEventId - allocEventId` distance (not elapsed time) |

## Leak Detection

Expand Down Expand Up @@ -206,6 +208,8 @@ and prints either a human-readable summary or JSON.
| Execute | `db_path`, `focus_source`, `device_id`, `template`, `effective_params`, `semantics_version`, `total`, `returned`, `has_more`, `truncated`, `total_is_exact`, `timeout_s`, `rows` |
| `--list` | `category`, `templates` (`name`, `description`, `category`) |
| `--template-info` | Template metadata matching `get_template_info()`, plus `template` |
| `capabilities` | `cli_version`, full `templates` contracts, and `skills` |
| `overview` | `db_path`, `focus_source`, `devices` (`device_id`, `first_event_id`, `last_event_id`), `import_metadata` |

`-n` still caps `rows` and `returned`. By default `total` equals `returned`
(this page's row count) and `total_is_exact` is true only when the page is
Expand Down
2 changes: 1 addition & 1 deletion docs/en/skills.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,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-helper` | Choosing the next skill from the user goal and input type; for an existing SnapshotDB, start with `capabilities` then `overview` before diagnosis |
| `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
36 changes: 34 additions & 2 deletions docs/en/snapshot-analyzer-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,9 @@
[中文](../zh/snapshot-analyzer-api.md) | English

`SnapshotAnalyzer` is the high-level Python facade for focus inspection,
template discovery, query execution, and SnapshotDB import metadata. Import it
from `pt_snap_cli.api`; it is not re-exported from the package root.
template discovery, capability listing, database overview, query execution, and
SnapshotDB import metadata. Import it from `pt_snap_cli.api`; it is not
re-exported from the package root.

## Create an Analyzer

Expand Down Expand Up @@ -68,6 +69,19 @@ explicit `db_path`, a validated device-only analyzer override is reported by
See [Focus Management](focus-management.md) for the complete resolution and
persistence model.

## List Capabilities

```python
catalog = analyzer.list_capabilities()
print(catalog["cli_version"])
print([item["name"] for item in catalog["templates"]])
print([item["name"] for item in catalog["skills"]])
```

`list_capabilities()` returns the same catalog as `pt-snap capabilities --json`
without the CLI envelope: `cli_version`, full template contracts (matching
`get_template_info()`), and bundled skill listings.

## Discover Templates

```python
Expand Down Expand Up @@ -139,6 +153,21 @@ Rows contain raw SQLite values. Template `output_schema` metadata is not applied
automatically; use the optional [ResultMapper API](result-mapper-api.md) when
converted values or model mapping are required.

## Inspect Database Overview

```python
overview = analyzer.get_database_overview()
print(overview["devices"])
print(overview["import_metadata"]["status"])
```

`get_database_overview()` is the read-only orientation used by
`pt-snap overview`: device list, per-device first/last event id, and import
metadata status. It does not persist focus or write the database. Missing
focus raises `RuntimeError`; a missing file raises `FileNotFoundError`; an
invalid SnapshotDB schema or a damaged `.pt-snap/focus.json` raises
`ValueError`.

## Inspect Import Metadata

```python
Expand All @@ -162,6 +191,9 @@ metadata schema version returns `status="invalid"`.
- `execute_query()` raises `RuntimeError` when no database can be resolved;
query, parameter, device, and database errors otherwise follow the shared
service-layer exceptions.
- `get_database_overview()` raises `RuntimeError` without a resolved database,
`FileNotFoundError` for a missing file, and `ValueError` for an invalid schema
or an invalid `.pt-snap/focus.json`.
- `get_database_metadata()` raises `RuntimeError` without a resolved database,
`FileNotFoundError` for a missing file, and `ValueError` for an invalid schema.
- `SnapshotAnalyzer` does not import or split raw pickle snapshots and does not
Expand Down
2 changes: 1 addition & 1 deletion docs/zh/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
| `splitting.md` | Chinese guide to snapshot slicing, formats, replay validation, and publication. |
| `skills.md` | Chinese guide to bundled agent-skill listing, helper entry, and installation. |
| `database.md` | Chinese snapshot SQLite schema reference. |
| `snapshot-analyzer-api.md` | Chinese guide to the high-level focus, query, and metadata Python API. |
| `snapshot-analyzer-api.md` | Chinese guide to the high-level focus, query, capabilities, overview, and metadata Python API. |
| `result-mapper-api.md` | Chinese result mapping API guide. |

## Subdirectories
Expand Down
5 changes: 4 additions & 1 deletion docs/zh/database.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,8 @@ pt-snap query --list
才会复用已有 DB;仅升级 `pt-snap-cli` 包版本不会让缓存失效。

```bash
pt-snap overview snapshot.pkl.db
pt-snap overview snapshot.pkl.db --json
pt-snap metadata snapshot.pkl.db
pt-snap metadata snapshot.pkl.db --json
pt-snap import snapshot.pkl --force
Expand Down Expand Up @@ -69,7 +71,8 @@ pt-snap query --template-use memory_peak
pt-snap query --template-use block --params '{"min_size": 1048576}'
```

使用 `pt-snap query --list` 和 `pt-snap query --template-info <name>` 查看受支持的
使用 `pt-snap capabilities --json` 查看完整模板清单,或用
`pt-snap query --list` 和 `pt-snap query --template-info <name>` 查看受支持的
查询入口。`event`、`callstack_analysis` 和 `active_memory_callstack_at_event`
同时支持当前去重调用栈结构和旧版内联文本库;见
[调用栈布局兼容](database.md#调用栈布局兼容)。完整流程见[运行查询](querying.md)。
Expand Down
6 changes: 5 additions & 1 deletion docs/zh/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ pt-snap query [DB_PATH] [--template-use <template_name>] [--params <json>] \

## 查询模板

模板分为三个分类。使用 `pt-snap query --list` 查看所有模板,或用 `--category` 过滤。
模板分为三个分类。用 `pt-snap capabilities --json` 一次查看完整清单(CLI 版本、全部模板契约和随包 skill),或用 `pt-snap query --list` 查看名称与描述。用 `--category` 过滤。

### Basic Queries

Expand Down Expand Up @@ -65,6 +65,8 @@ pt-snap query [DB_PATH] [--template-use <template_name>] [--params <json>] \
|------|------|
| `leak_detection` | 查找已采集分配且没有释放完成记录的候选(不是已确认泄漏) |
| `active_memory_callstack_at_event` | 对某个事件时刻的活跃内存块按分配调用栈做聚合,并单独标识静态与 preexisting 内存 |
| `preexisting_live` | 统计某个事件时刻仍存活的 preexisting 块(`allocEventId=-1`,包含 `freeEventId IS NULL`) |
| `freed_block_lifetime` | 按 `freeEventId - allocEventId` 距离分桶统计已成功释放的块(不是经过时间) |

## 泄漏检测

Expand Down Expand Up @@ -198,6 +200,8 @@ pt-snap report peak-memory /path/to/snapshot.db --json
| 执行 | `db_path`、`focus_source`、`device_id`、`template`、`effective_params`、`semantics_version`、`total`、`returned`、`has_more`、`truncated`、`total_is_exact`、`timeout_s`、`rows` |
| `--list` | `category`、`templates`(`name`、`description`、`category`) |
| `--template-info` | 与 `get_template_info()` 对齐的模板元数据,另加 `template` |
| `capabilities` | `cli_version`、完整 `templates` 契约、`skills` |
| `overview` | `db_path`、`focus_source`、`devices`(`device_id`、`first_event_id`、`last_event_id`)、`import_metadata` |

`-n` 仍然限制 `rows` 与 `returned`。默认 `total` 等于 `returned`(本页行数);
仅当本页就是完整匹配集合(`has_more` 为 false 且 `offset` 为 0)时
Expand Down
2 changes: 1 addition & 1 deletion docs/zh/skills.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ pt-snap skill uninstall --project --target cursor

| Skill | 适用场景 |
|-------|----------|
| `pt-snap-helper` | 根据用户目标和输入类型选择下一步 skill |
| `pt-snap-helper` | 根据用户目标和输入类型选择下一步 skill;已有 SnapshotDB 时先 `capabilities` 再 `overview`,然后才诊断 |
| `pt-snap-setup` | 在当前 Python 环境安装或验证 `pt-snap-cli` |
| `pt-snap-ascend-npu-collect` | 采集昇腾 NPU 内存快照 pickle |
| `pt-snap-memory-leak` | 在 SnapshotDB 中诊断仍存活分配和泄漏候选 |
Expand Down
Loading
Loading