diff --git a/README.md b/README.md
index 67ec7a6..147b326 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,67 @@
[中文文档](README_zh.md) | English
-A command-line tool for analyzing PyTorch memory snapshots. Set a snapshot database, run built-in queries, and inspect memory usage, leaks, and timelines.
+**High-efficiency, replay-enriched, agent-native CLI and Python toolkit for PyTorch GPU/NPU memory snapshot forensics.**
+
+`pt-snap-cli` (`pt-snap`) transforms opaque PyTorch memory snapshot `.pkl` dumps into an indexed, relational **SnapshotDB (SQLite)** through a full allocator replay. Inspect peak occupancy, same-event allocator fragmentation, block lifecycles, leak candidates, and interactive frame-level memory flamegraphs in milliseconds—from your terminal, Python scripts, or AI coding agents—without needing PyTorch or a GPU/NPU environment offline.
+
+```mermaid
+flowchart LR
+ A["PyTorch / TorchNPU
Snapshot (.pkl)"] -->|"pt-snap import
(Allocator Replay)"| B[("SnapshotDB (SQLite)
trace_entry · block
callstack · frame")]
+ B --> C["13 Parameterized
Query Templates"]
+ B --> D["Peak & Frame-Tree
Reports (Text / JSON / HTML)"]
+ B --> E["Agent Skills + CLI
(--json · Zero MCP)"]
+ B --> F["SnapshotAnalyzer
Python API"]
+```
+
+## Why `pt-snap`?
+
+| Dimension | Raw `.pkl` / Ad-hoc Scripts / Static HTML | `pt-snap-cli` (`SnapshotDB`) |
+| --- | --- | --- |
+| **Efficiency** | Re-parses multi-hundred-MB pickles on every question; heavy browser DOM on large traces | **Import once, query in milliseconds.** Indexed SQLite with SHA-256 cache reuse, read-only `mode=ro` queries, `--timeout` deadlines, and bounded dataset work budgets |
+| **Data Structure** | Deeply nested dicts/lists; implicit pool counters and unlinked alloc/free events; repeated inline callstack strings | **Replay-enriched relational schema.** Post-event `allocated`/`active`/`reserved` counters, explicit `allocEventId → freeEventId` block lifecycles, deduplicated `callstack` table, and lossless ordered `(filename, line, name)` `frame` arrays |
+| **Analysis Depth** | Visual timeline inspection or custom one-off Python loops | **13 built-in query templates + composite reports.** Same-event `reserved - active` gap analysis, peak callstack attribution with coverage metrics, leak candidate & lifetime buckets, and standalone interactive HTML memory-tree flamegraphs |
+| **Agent Readiness** | Raw dumps overflow context windows; unstructured output causes unit/denominator hallucinations | **Agent-native CLI (no MCP server needed).** Deterministic `--json` envelopes, machine-readable `capabilities` & column semantics, `--stack-bytes` token budgeting, honest `has_more`/`truncated` flags, and 6 installable diagnostic skills |
+
+### 1. High Efficiency — Import Once, Query in Milliseconds
+
+- **Zero Accelerator Dependency Offline**: Offline import, querying, and reporting require only **Python 3.10+** and standard SQLite—no PyTorch, CUDA, or CANN runtime needed on your analysis machine.
+- **Cryptographic Cache Reuse**: `pt-snap import` records source `SHA-256`, import format version, and device selection in `pt_snap_metadata`. Re-importing an unchanged snapshot reuses the validated `.db` in `<1 ms`.
+- **Deduplicated Storage**: Callstacks and structured frames are interned once across all devices rather than repeated on every trace event, drastically shrinking disk footprint and scan I/O.
+- **Bounded & Predictable Execution**: Every analysis opens SQLite with `mode=ro`, reuses cached connections in `SnapshotAnalyzer`, enforces wall-clock `--timeout` via SQLite progress handlers, and bounds sharded dataset queries with explicit work budgets (`--max-work-rows`, `--max-work-bytes`, `--max-scratch-db-bytes`).
+
+### 2. Friendlier, Replay-Enriched Data Structure (`SnapshotDB`)
+
+Instead of dumping raw pickle dictionaries directly into tables, `pt-snap` replays the allocator state machine during import and materializes explicit relational entities:
+
+| Table | What Replay Materializes | Why It Is Easier to Query |
+| --- | --- | --- |
+| `trace_entry_` | Chronological events (`alloc`, `free_requested`, `free_completed`, `segment_alloc`, `segment_free`, `segment_map`, `segment_unmap`, `workspace_snapshot`) | Every row carries exact post-event **`allocated`**, **`active`**, and **`reserved`** byte counters plus `callstackId` |
+| `block_` | Full memory block lifecycle (`id`, `address`, `size`, `requestedSize`, `state`, `allocEventId`, `freeEventId`) | Instantly join an allocation to its completion event, compare alignment overhead (`size` vs. `requestedSize`), and separate dynamic blocks (`id >= 0`) from preexisting/static blocks (`id < 0`, `allocEventId = -1`) |
+| `callstack` | Deduplicated callstack text shared across all devices | Group or filter by `callstackId` without scanning megabytes of repeated stack strings |
+| `frame` & `callstack_frame` | Lossless ordered `(filename, line, name)` frame tuples and `position` index (Format 3) | Build exact caller-to-callee memory trees and handle recursive frames or special characters without fragile regex/colon splitting |
+| `dictionary` & `pt_snap_metadata` | Self-describing enum key/value mappings and provenance metadata | Portable, self-contained SQLite files that remain compatible across v1 (inline text), v2 (deduplicated text), and v3 (structured frame) layouts |
+
+### 3. Deep Forensic Analysis Capabilities
+
+- **Peak Memory & Same-Event Fragmentation (`report peak-memory`)**: Automatically locates independent `allocated`, `active`, and `reserved` peak events, computes **same-event allocator gaps** (`reserved - active` and `reserved - allocated` at the exact peak event instead of misleadingly subtracting peaks from different timestamps), and attributes live blocks to callstacks with explicit `coverage_percent` and `included_bytes`.
+- **Frame-Level Live Memory Flamegraphs (`report memory-tree`)**: Decomposes live active memory at any `event_id` into a caller-first frame hierarchy (`size_bytes` inclusive vs. `self_bytes` exclusive). Export to terminal text, JSON, or a **self-contained interactive HTML flamegraph** (`--format html`) with zoom, full-tree search, and keyboard navigation where even tiny or zero-byte frames stay reachable.
+- **Lifecycle, Retention & Leak Candidate Forensics**:
+ - Distinguish unfreed dynamic survivors (`leak_detection`), stream-deferred frees (`free_requested` vs. `free_completed`), and pre-snapshot occupancy (`preexisting_live`).
+ - Analyze block duration distributions by event-ID distance (`freed_block_lifetime`).
+- **Multi-Format & Sharded Scale**: Analyze standalone `.db` files, native sharded datasets (`--events-per-slice`), msinsight-compatible exports (`--format msinsight`), or split multi-device pickles into replay-validated per-device slices (`pt-snap split`).
+
+### 4. Agent-Native CLI by Design
+
+`pt-snap` is engineered so AI coding agents (Claude Code, Cursor, Codex, OpenCode, Cline) can diagnose complex OOMs and leaks reliably **without an MCP server**:
+
+- **Self-Discoverable Contracts**: `pt-snap capabilities --json` and `pt-snap query --template-info --json` expose parameter schemas, `semantics_version`, column `units` (`bytes`, `percent`, `event_id`), `metric_semantics`, `denominator`, `sentinel` (`-1`), and `interpretation_limits`—preventing agents from hallucinating units or denominators.
+- **Context-Window Budgeting (`--stack-bytes`)**: Deep PyTorch callstacks quickly exhaust LLM context windows. Passing `stack_bytes` (e.g., `--stack-bytes 256`) returns a UTF-8-safe prefix plus canonical `stack_id`, `stack_truncated`, and `stack_event_id`, allowing the agent to rank hundreds of groups compactly and fetch full stacks via `event(id=stack_event_id)` only for top suspects.
+- **Honest Completeness Signals**: Every JSON response reports `total`, `returned`, `has_more`, `truncated`, and `total_is_exact`. Agents know immediately when a `LIMIT` or `top_n` window is partial and can widen the window or pass `--exact-total`.
+- **Strict Parameter Validation & Error Envelopes**: Misspelled parameters (e.g., `min_sze`) fail fast with `INVALID_PARAMETER` and accepted keys instead of silently running unfiltered SQL. On `--json` failure, `stdout` stays empty while `stderr` emits a structured error object with `code`, `message`, and actionable `hint`.
+- **6 Bundled Agent Skills**: Installable in one command (`pt-snap skill install`) to guide agents through read-only preflight, bounded evidence gathering, and output recovery.
+
+---
## Start Here
@@ -43,6 +103,12 @@ pt-snap query snapshot.pkl.db --device 0 --template-use memory_peak --json
pt-snap report peak-memory snapshot.pkl.db --device 0 --metric active --limit 20
```
+Generate an interactive HTML frame-level memory flamegraph at the peak event (for example, event `100`):
+
+```bash
+pt-snap report memory-tree snapshot.pkl.db --device 0 --event-id 100 --format html > memory-tree.html
+```
+
Default import writes `snapshot.pkl.db` beside the pickle and updates project
`.pt-snap/focus.json` in the current directory. Add `--no-focus` to avoid that
focus change, not to prevent DB replacement: a standalone cache miss/`--force`
@@ -58,6 +124,28 @@ byte units, allocated/active/reserved counters, expected output and partial repo
- [Replayable pickle splitting](docs/en/splitting.md): one split strategy and a new output directory; separate from dataset import.
- [Complete-dataset addressing](docs/en/sharded-snapshotdb.md#complete-dataset-focus-and-addressing-p1), [global built-in support](docs/en/querying.md#dataset-global-built-in-support-p3), and [recorded interoperability acceptance](docs/en/interop-acceptance.md): advanced contracts and evidence, not prerequisites for a first report.
+## Built-in Query Templates & Reports
+
+Use `pt-snap query --list` or `pt-snap capabilities --json` to inspect all 13 built-in templates and their parameter/output schemas:
+
+| Category | Template / Command | Purpose |
+| --- | --- | --- |
+| **Basic** | `event` | Filter trace events by ID bounds, action code, size, stream, or compact `stack_bytes` |
+| **Basic** | `block` | Filter memory blocks by size, state, address, or lifecycle event bounds |
+| **Basic** | `allocation` | Query `(id, allocated, active, reserved)` timeline trajectory |
+| **Basic** | `event_frames` | Read the ordered `(position, filename, line, name)` frame array for a specific event (Format 3) |
+| **Statistical** | `memory_peak` | Independent `allocated`, `active`, and `reserved` maxima and earliest peak event IDs |
+| **Statistical** | `allocator_gap` | Peak events plus same-event `reserved - active` and `reserved - allocated` fragmentation gaps |
+| **Statistical** | `active_blocks_at_event` | Enumerate blocks live at `event_id` (`allocEventId <= E < freeEventId` or unfreed), with optional static/preexisting blocks |
+| **Statistical** | `callstack_analysis` | Aggregate count, total/min/max/average size across all stack-bearing trace actions |
+| **Business** | `active_memory_callstack_at_event` | Group active memory at `event_id` by allocation callstack with byte share percentages |
+| **Business** | `active_memory_frame_tree_at_event` | Caller-first tree breakdown (`size_bytes` inclusive vs. `self_bytes` exclusive) at `event_id` |
+| **Business** | `leak_detection` | Find dynamic blocks allocated during capture that never recorded a `free_completed` event |
+| **Business** | `preexisting_live` | Summarize pre-capture blocks (`allocEventId = -1`) still live at `event_id` |
+| **Business** | `freed_block_lifetime` | Bucket completed block lifecycles by `freeEventId - allocEventId` event distance |
+| **Report** | `report peak-memory` | One-shot `allocator_gap` + `active_memory_callstack_at_event` with coverage and completeness metadata |
+| **Report** | `report memory-tree` | Text, JSON, or self-contained interactive HTML flamegraph of live memory by call frame |
+
## Commands
| Command | Description |
@@ -96,13 +184,30 @@ deep-pagination costs and all-or-error semantics.
## Agent Skills
+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).
+
+```bash
+# Install bundled skills for shared Agent Skills hosts (~/.agents/skills) and Claude Code (~/.claude/skills)
+pt-snap skill install
+
+# Verify installation status as machine-readable JSON
+pt-snap skill list --json
+```
+
+| Bundled Skill | Role |
+| --- | --- |
+| `pt-snap-helper` | Entry router: inspects user goal and input type, runs `capabilities` + `overview` preflight, and dispatches to the right workflow |
+| `pt-snap-setup` | Verifies or installs `pt-snap-cli` in the active Python environment with shebang/interpreter ownership checks |
+| `pt-snap-ascend-npu-collect` | Guides Ascend NPU memory snapshot `.pkl` capture (works even before `pt-snap` CLI is installed) |
+| `pt-snap-memory-peak-breakdown` | Explains active memory at peak events, callstack attribution, and static/preexisting occupancy |
+| `pt-snap-memory-leak` | Diagnoses end-of-trace unfreed dynamic candidates vs. pending frees and preexisting memory |
+| `pt-snap-memory-fragmentation` | Investigates `reserved - active` allocator gaps, `segment_map`/`segment_unmap` behavior, and pool pressure |
+
For long diagnostic stacks, opt into `stack_bytes` on `event` or
`active_memory_callstack_at_event`, or `report peak-memory --stack-bytes 256`.
See [compact callstack text](docs/en/querying.md#compact-callstack-text) for
identity, byte-budget metadata and full-text retrieval.
-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.
diff --git a/README_zh.md b/README_zh.md
index 922c33c..3e824c1 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -7,7 +7,67 @@
中文文档 | [English](README.md)
-用于分析 PyTorch 内存快照的命令行工具。设置快照数据库,运行内置查询,检查内存使用、泄漏和时间线。
+**面向 PyTorch GPU/NPU 内存快照诊断的高效、重放增强型、Agent 原生命令行与 Python 工具集。**
+
+`pt-snap-cli`(`pt-snap`)通过完整的分配器状态机重放(Allocator Replay),将晦涩的 PyTorch 原始内存快照 `.pkl` 转换为带索引的关系型 **SnapshotDB(SQLite)**。无需在分析机上安装 PyTorch 或 GPU/NPU 驱动,即可在毫秒级完成峰值内存归因、同事件碎片化差距(`reserved - active`)诊断、内存块完整生命周期追踪、泄漏候选筛查以及交互式调用栈帧火焰图生成——无论是在终端、Python 脚本还是 AI 编程 Agent 中。
+
+```mermaid
+flowchart LR
+ A["PyTorch / TorchNPU
原始快照 (.pkl)"] -->|"pt-snap import
(分配器重放)"| B[("SnapshotDB (SQLite)
trace_entry · block
callstack · frame")]
+ B --> C["13 个参数化
内置查询模板"]
+ B --> D["峰值归因与帧内存树
报告 (Text / JSON / HTML)"]
+ B --> E["Agent Skills + CLI
(--json · 零 MCP 依赖)"]
+ B --> F["SnapshotAnalyzer
Python API"]
+```
+
+## 为什么选择 `pt-snap`?
+
+| 维度 | 原始 `.pkl` / 临时脚本 / 静态大网页 | `pt-snap-cli`(`SnapshotDB`) |
+| --- | --- | --- |
+| **高效性** | 每次提问都要重新反序列化数百 MB 的 pickle;超大轨迹下浏览器 DOM 极易卡顿 | **一次导入,毫秒级查询。** SQLite 索引加速 + SHA-256 缓存复用(命中 `<1 ms`)、只读 `mode=ro` 连接、`--timeout` 进度中断与显式数据集工作预算 |
+| **数据结构** | 深层嵌套字典/列表;内存池水位隐式变化、申请与释放事件未关联、长调用栈重复存储 | **重放增强的关系型模型。** 每个事件后精确记录 `allocated`/`active`/`reserved` 水位,显式构建 `allocEventId → freeEventId` 块生命周期,跨设备去重 `callstack`,无损保留有序 `(filename, line, name)` 结构化帧(`frame`) |
+| **分析能力** | 仅靠肉眼拖拽时间线,或每次手写一次性 Python 遍历逻辑 | **13 个内置查询模板 + 高阶组合报告。** 支持同事件 `reserved - active` 碎片分析、带覆盖率的峰值调用栈归因、泄漏候选与生命周期分桶、单文件交互式 HTML 内存帧火焰图 |
+| **Agent 友好** | 原始输出瞬间撑爆上下文窗口;缺少字段单位与分母约定易引发大模型幻觉 | **专为 Agent 设计的 CLI(无需 MCP Server)。** 确定性 `--json` 信封、可自发现的 `capabilities` 与字段语义契约、`--stack-bytes` 上下文预算控制、诚实的 `has_more`/`truncated` 完整性标记,以及 6 个随包诊断 Skill |
+
+### 1. 高效:一次重放导入,毫秒级受控查询
+
+- **离线分析零加速器依赖**:离线导入、查询与报告仅需 **Python 3.10+** 与标准 SQLite,分析环境无需安装 PyTorch、CUDA 或 CANN。
+- **哈希校验缓存复用**:`pt-snap import` 在 `pt_snap_metadata` 中记录源文件 `SHA-256`、导入格式版本及设备选择;未发生变化的快照重复导入时在 `<1 ms` 内直接复用。
+- **跨设备调用栈与帧去重**:海量事件共享少量调用栈与代码帧,`callstack` 与 `frame` 表仅存储唯一条目并通过整数 ID 关联,显著降低磁盘占用与扫描开销。
+- **严格只读与资源边界**:所有分析均以 `mode=ro` 打开 SQLite,支持 SQLite progress handler 驱动的 `--timeout` 超时控制,以及面向分片数据集的显式工作上限(`--max-work-rows`、`--max-work-bytes`、`--max-scratch-db-bytes`)。
+
+### 2. 更友好的数据结构:分配器重放构建的 `SnapshotDB`
+
+`pt-snap` 并非简单地把 pickle 字典平铺进数据库,而是在导入阶段完整重放内存分配器状态机,提炼出直观、易查询的关系表:
+
+| 数据表 | 重放阶段构建的核心信息 | 为什么对分析更友好 |
+| --- | --- | --- |
+| `trace_entry_` | 按时序排列的分配器动作(`alloc`、`free_requested`、`free_completed`、`segment_alloc`、`segment_free`、`segment_map`、`segment_unmap`、`workspace_snapshot`) | 每条事件直接附带该时刻之后的精确 **`allocated`**、**`active`**、**`reserved`** 字节水位与 `callstackId` |
+| `block_` | 内存块完整生命周期(`id`、`address`、`size`、`requestedSize`、`state`、`allocEventId`、`freeEventId`) | 直接关联某次分配何时释放、对比对齐损耗(`size` vs `requestedSize`),并清晰区分采集中动态分配块(`id >= 0`)与采集前已存在的存量/静态块(`id < 0`, `allocEventId = -1`) |
+| `callstack` | 跨设备共享的去重调用栈文本 | 按 `callstackId` 高效聚合,无需反复扫描重复字符串 |
+| `frame` & `callstack_frame` | 无损有序的 `(filename, line, name)` 结构化帧元组与 `position` 序号(Format 3) | 直接构建从外层调用者到内层分配点的内存占比树,妥善处理递归帧与特殊字符,无需脆弱的冒号/换行文本切分 |
+| `dictionary` & `pt_snap_metadata` | 自描述的枚举值映射字典与来源校验元数据 | 单文件自包含,同时无感兼容 v1(内联文本)、v2(去重文本)和 v3(结构化帧)数据库布局 |
+
+### 3. 深度分析能力:从宏观水位到逐帧火焰图
+
+- **峰值归因与同事件碎片差距(`report peak-memory`)**:独立定位 `allocated`、`active`、`reserved` 各自的峰值事件,计算**同一事件时刻**的 `reserved - active` 与 `reserved - allocated` 差距(避免将不同时刻的峰值直接相减产生误导),并按调用栈归因存活内存及输出 `coverage_percent` 与 `included_bytes`。
+- **逐帧存活内存树与交互式火焰图(`report memory-tree`)**:在任意 `event_id` 将存活内存按调用链拆解为包含子节点占用(`size_bytes`)与自身终点占用(`self_bytes`),支持输出终端文本、JSON 或**零服务端依赖的单文件交互式 HTML 火焰图**(`--format html`),内置全树搜索与键盘导航,极小或零字节帧也可直达。
+- **生命周期、延迟释放与泄漏候选分析**:
+ - 区分采集中未完成释放的动态块(`leak_detection`)、流同步前挂起释放的块(`free_requested` 但未 `free_completed`)以及采集前存量块(`preexisting_live`)。
+ - 按 `freeEventId - allocEventId` 事件跨度统计已释放块的生命周期分布(`freed_block_lifetime`)。
+- **多形态数据支持**:支持独立 `.db` 单库、原生分片数据集(`--events-per-slice`)、msinsight 兼容数据集导出(`--format msinsight`)以及按设备/切片的可回放 pickle 拆分(`pt-snap split`)。
+
+### 4. 原生 Agent 友好的命令行设计
+
+`pt-snap` 从底层交互协议上为 Claude Code、Cursor、Codex、OpenCode、Cline 等 AI Agent 量身定制,**无需额外部署 MCP Server**:
+
+- **契约自发现(防幻觉)**:`pt-snap capabilities --json` 与 `pt-snap query --template-info --json` 完整输出参数类型/枚举、语义版本(`semantics_version`)、输出列单位(`bytes`、`percent`、`event_id`)、分母含义(`denominator`)、哨兵值(`-1`)及解读边界(`interpretation_limits`)。
+- **上下文窗口预算控制(`--stack-bytes`)**:深度学习调用栈往往极长;通过 `--stack-bytes 256` 可按 UTF-8 安全边界截断调用栈文本,同时保留唯一身份 `stack_id`、`stack_truncated` 与定位事件 `stack_event_id`,让 Agent 先低成本扫描全局排名,再对关键嫌疑项按需拉取完整调用栈。
+- **诚实的完整性信号**:所有 `--json` 查询与报告均包含 `total`、`returned`、`has_more`、`truncated` 与 `total_is_exact`,防止 Agent 将受 `LIMIT` 或 `top_n` 截断的局部窗口误判为全量数据。
+- **严格参数校验与结构化错误信封**:拼写错误的参数(如 `min_sze`)会立即触发 `INVALID_PARAMETER` 并提示合法参数名,绝不静默退化为无过滤全表查询;`--json` 失败时 `stdout` 保持为空,`stderr` 输出带 `code`、`message`、`hint` 的标准 JSON 错误对象。
+- **随包内置 6 个诊断 Skill**:一行 `pt-snap skill install` 即可将标准化预检、有界取证与截断恢复工作流安装到主流 Agent 宿主目录。
+
+---
## 从这里开始
@@ -42,6 +102,12 @@ pt-snap query snapshot.pkl.db --device 0 --template-use memory_peak --json
pt-snap report peak-memory snapshot.pkl.db --device 0 --metric active --limit 20
```
+在指定事件(例如事件 `100`)生成按调用栈帧拆解的交互式 HTML 内存火焰图:
+
+```bash
+pt-snap report memory-tree snapshot.pkl.db --device 0 --event-id 100 --format html > memory-tree.html
+```
+
默认导入在 pickle 旁写出 `snapshot.pkl.db`,并更新当前目录的项目
`.pt-snap/focus.json`;加 `--no-focus` 只避免 focus 变化,不防止 DB 替换:单库缓存
未命中或 `--force` 可能替换同名 DB,必要时选择其他 `--output-dir`。显式路径的检查/查询/报告
@@ -55,6 +121,28 @@ allocated/active/reserved 指标、预期输出和报告不完整的情况。
- [可回放 pickle 拆分](docs/zh/splitting.md):只选一种拆分策略并使用新目录,与数据集导入不同。
- [完整数据集寻址](docs/zh/sharded-snapshotdb.md#完整数据集-focus-与寻址p1)、[全局内建支持](docs/zh/querying.md#数据集全局内建支持p3)和[已记录的互操作验收](docs/zh/interop-acceptance.md):按需查看高级合同与证据,不是第一份报告的前置条件。
+## 内置查询模板与报告
+
+可执行 `pt-snap query --list` 或 `pt-snap capabilities --json` 查看全部 13 个内置查询模板及其参数与输出契约:
+
+| 分类 | 模板 / 命令 | 用途说明 |
+| --- | --- | --- |
+| **Basic** | `event` | 按事件 ID 范围、动作码、大小、流或紧凑 `stack_bytes` 过滤分配器事件 |
+| **Basic** | `block` | 按块大小、状态码、地址或分配/释放事件范围检索内存块 |
+| **Basic** | `allocation` | 查询 `(id, allocated, active, reserved)` 内存水位时间线 |
+| **Basic** | `event_frames` | 读取指定事件的有序 `(position, filename, line, name)` 结构化调用栈帧(Format 3) |
+| **Statistical** | `memory_peak` | 获取 `allocated`、`active`、`reserved` 各自的最大值及最早达到峰值的事件 ID |
+| **Statistical** | `allocator_gap` | 对比三类峰值事件,并计算同一事件时刻的 `reserved - active` 与 `reserved - allocated` 碎片差距 |
+| **Statistical** | `active_blocks_at_event` | 列出在 `event_id` 时刻仍存活的内存块(`allocEventId <= E < freeEventId` 或未释放),可选包含静态/存量块 |
+| **Statistical** | `callstack_analysis` | 按调用栈聚合全部带栈事件的数量、总字节、最小/最大/平均大小 |
+| **Business** | `active_memory_callstack_at_event` | 将 `event_id` 时刻的存活内存按分配调用栈聚合,计算字节占比 |
+| **Business** | `active_memory_frame_tree_at_event` | 在 `event_id` 时刻按外层调用者优先构建逐帧内存树(含子树汇总 `size_bytes` 与本帧终点 `self_bytes`) |
+| **Business** | `leak_detection` | 查找采集期间动态分配且直到结束仍未记录 `free_completed` 的泄漏候选块 |
+| **Business** | `preexisting_live` | 统计采集开始前已分配(`allocEventId = -1`)且在 `event_id` 时刻仍存活的内存占用 |
+| **Business** | `freed_block_lifetime` | 按 `freeEventId - allocEventId` 事件跨度对已完成释放的内存块进行生命周期分桶 |
+| **Report** | `report peak-memory` | 一键组合 `allocator_gap` + `active_memory_callstack_at_event`,附带覆盖率与完整性元数据 |
+| **Report** | `report memory-tree` | 输出指定事件时刻的终端文本树、JSON 树或单文件交互式 HTML 内存帧火焰图 |
+
## 命令
| 命令 | 说明 |
@@ -91,12 +179,29 @@ included bytes 为分母。解读有上限的分组结果前,请参阅
## Agent Skills
+使用 `pt-snap skill install` 安装随包诊断工作流。Agent 集成入口是 skills 与 CLI,不再提供 MCP 服务器。详见 [Agent Skills 指南](docs/zh/skills.md)。
+
+```bash
+# 安装随包 Skill 到通用 Agent Skills 目录(~/.agents/skills)与 Claude Code 目录(~/.claude/skills)
+pt-snap skill install
+
+# 以机器可读 JSON 检查安装状态
+pt-snap skill list --json
+```
+
+| 随包 Skill | 职责说明 |
+| --- | --- |
+| `pt-snap-helper` | 诊断总入口路由:根据用户目标与输入类型完成 `capabilities` + `overview` 预检,并分发至对应子工作流 |
+| `pt-snap-setup` | 在当前 Python 环境中验证或安装 `pt-snap-cli`,校验 shebang 与解释器归属一致性 |
+| `pt-snap-ascend-npu-collect` | 指导昇腾 NPU 内存快照 `.pkl` 采集(宿主已加载该 Skill 时无需预先安装 `pt-snap` CLI) |
+| `pt-snap-memory-peak-breakdown` | 诊断峰值事件时刻的存活内存构成、调用栈归因及静态/存量内存占比 |
+| `pt-snap-memory-leak` | 排查轨迹末尾未释放的动态分配候选块,区分挂起释放(pending free)与采集前存量块 |
+| `pt-snap-memory-fragmentation` | 诊断 `reserved - active` 分配器差距、`segment_map`/`segment_unmap` 行为与内存池膨胀压力 |
+
诊断长调用栈时,可在 `event` 或 `active_memory_callstack_at_event` 上显式设置
`stack_bytes`,或使用 `report peak-memory --stack-bytes 256`。
身份、字节预算元数据及完整文本检索方式见[紧凑调用栈文本](docs/zh/querying.md#紧凑调用栈文本)。
-使用 `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,可信导入是独立决定。