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
16 changes: 8 additions & 8 deletions .agents/quickstart/01-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,12 @@
### `app` (Typer)
Typer 应用实例,管理所有 CLI 命令。

### `use_database()`
### `focus_database()`
设置当前分析的数据库文件,验证有效性并显示可用设备。

### `query_database()`
执行查询命令,支持:
- `--template`: 指定查询模板
- `--template-use`: 指定查询模板
- `--params`: JSON 格式参数
- `--device`: 指定设备 ID
- `--list`: 列出可用模板
Expand All @@ -31,7 +31,7 @@ Typer 应用实例,管理所有 CLI 命令。
## 使用示例

```python
from pt_snap_analyzer.cli import app
from pt_snap_cli.cli import app

# 运行 CLI
app()
Expand All @@ -42,17 +42,17 @@ app()
pt-snap --version

# 设置数据库
pt-snap use examples/snapshot.pkl.db
pt-snap focus examples/snapshot.pkl.db

# 执行查询
pt-snap query snapshot.pkl.db --template leak_detection --params '{"min_size": 1024}'
pt-snap query snapshot.pkl.db --template-use leak_detection --params '{"min_size": 1024}'

# 列出模板
pt-snap query snapshot.pkl.db --list
```

## 相关文件

- [cli.py](../../pt_snap_analyzer/cli.py) - 完整实现
- [context.py](../../pt_snap_analyzer/context.py) - 数据库上下文
- [query/executor.py](../../pt_snap_analyzer/query/executor.py) - 查询执行器
- [cli.py](../../src/pt_snap_cli/cli.py) - 完整实现
- [context.py](../../src/pt_snap_cli/context.py) - 数据库上下文
- [query/executor.py](../../src/pt_snap_cli/query/executor.py) - 查询执行器
6 changes: 3 additions & 3 deletions .agents/quickstart/02-context.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@
## 使用示例

```python
from pt_snap_analyzer.context import Context
from pt_snap_cli.context import Context

# 初始化并验证
ctx = Context("snapshot.pkl.db")
Expand All @@ -59,5 +59,5 @@ with ctx.connect() as conn:

## 相关文件

- [context.py](../../pt_snap_analyzer/context.py) - 完整实现
- [cli.py](../../pt_snap_analyzer/cli.py) - 使用 Context 的 CLI 命令
- [context.py](../../src/pt_snap_cli/context.py) - 完整实现
- [cli.py](../../src/pt_snap_cli/cli.py) - 使用 Context 的 CLI 命令
53 changes: 28 additions & 25 deletions .agents/quickstart/03-models.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,26 +6,25 @@

## 核心组件

### `Block` 类
### `MemoryBlock` 类
内存块模型,表示一次内存分配。

**关键属性:**
- `address` - 内存地址
- `size` - 分配大小(字节)
- `device_id` - 设备 ID
- `stream_id` - 流 ID
- `start_ns` - 开始时间(纳秒)
- `call_stack` - 调用栈信息
- `requested_size` - 用户请求的大小
- `state` - 内存块状态
- `alloc_event_id` / `free_event_id` - 生命周期事件 ID

### `Event` 类
### `MemoryEvent` 类
内存事件模型,表示内存分配/释放事件。

**关键属性:**
- `external_id` - 外部 ID
- `block_info` - 关联的内存块
- `start_ns` - 事件时间戳
- `id` - 事件 ID
- `action` - 事件类型
- `allocated` / `active` / `reserved` - 事件后的内存统计

### `MemoryEventType` 枚举
### `EventType` 枚举
事件类型定义:
- `UNKNOWN` - 未知类型
- `ALLOC` - 分配事件
Expand All @@ -39,30 +38,34 @@
## 使用示例

```python
from pt_snap_analyzer.models import Block, Event, MemoryEventType
from pt_snap_cli.models import BlockState, EventType, MemoryBlock, MemoryEvent

# 创建内存块
block = Block(
block = MemoryBlock(
id=1,
address=0x7f8b4c000000,
size=1024,
device_id=0,
stream_id=0,
start_ns=1234567890,
call_stack="main.py:10"
requested_size=1000,
state=BlockState.ACTIVE_ALLOCATED,
alloc_event_id=1,
)

# 创建事件
event = Event(
external_id=1,
block_info=block,
event_type=MemoryEventType.ALLOC,
start_ns=1234567890
event = MemoryEvent(
id=1,
action=EventType.ALLOC,
address=block.address,
size=block.size,
stream=0,
allocated=1024,
active=1024,
reserved=2048,
)
```

## 相关文件

- [models/__init__.py](../../pt_snap_analyzer/models/__init__.py) - 模块导出
- [models/block.py](../../pt_snap_analyzer/models/block.py) - Block 实现
- [models/event.py](../../pt_snap_analyzer/models/event.py) - Event 实现
- [models/_enums.py](../../pt_snap_analyzer/models/_enums.py) - 枚举定义
- [models/__init__.py](../../src/pt_snap_cli/models/__init__.py) - 模块导出
- [models/block.py](../../src/pt_snap_cli/models/block.py) - MemoryBlock 实现
- [models/event.py](../../src/pt_snap_cli/models/event.py) - MemoryEvent 实现
- [models/_enums.py](../../src/pt_snap_cli/models/_enums.py) - 枚举定义
52 changes: 15 additions & 37 deletions .agents/quickstart/04-query.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,47 +57,25 @@ Fluent API 构建 SQL 查询。

位于 `query/templates/` 目录,按分类组织:

- **Basic**: `active_blocks.yaml`, `blocks_by_size.yaml`, `events_by_action.yaml`, `memory_timeline.yaml`
- **Statistical**: `memory_peak.yaml`, `callstack_analysis.yaml`
- **Business**: `leak_detection.yaml`
- **Basic**: `allocation`, `block`, `event`
- **Statistical**: `active_blocks_at_event`, `allocator_gap`, `callstack_analysis`, `memory_peak`
- **Business**: `active_memory_callstack_at_event`, `leak_detection`

## 使用示例

```python
from pt_snap_analyzer.query import QueryExecutor
from pt_snap_analyzer.context import Context
from pathlib import Path

# 初始化
ctx = Context("snapshot.pkl.db")
executor = QueryExecutor(ctx, template_dir=Path("query/templates"))

# 执行模板查询
results = executor.execute_template(
"leak_detection",
params={"min_size": 1024},
device_id=0
)

# 使用 QueryBuilder
from pt_snap_analyzer.query import QueryBuilder, Condition

builder = QueryBuilder()
sql = (builder
.from_table("trace_entry_0")
.columns("address", "size", "start_ns")
.where(Condition("size").gt(1024))
.order_by("start_ns")
.limit(100)
.build())
```bash
pt-snap query snapshot.pkl.db --template-use leak_detection \
--params '{"min_size": 1024}' --device 0
pt-snap query --list
pt-snap query --template-info leak_detection
```

## 相关文件

- [query/__init__.py](../../pt_snap_analyzer/query/__init__.py) - 模块导出
- [query/executor.py](../../pt_snap_analyzer/query/executor.py) - 执行器
- [query/builder.py](../../pt_snap_analyzer/query/builder.py) - 构建器
- [query/condition.py](../../pt_snap_analyzer/query/condition.py) - 条件
- [query/mapper.py](../../pt_snap_analyzer/query/mapper.py) - 映射器
- [query/registry.py](../../pt_snap_analyzer/query/registry.py) - 注册表
- [query/templates/](../../pt_snap_analyzer/query/templates/) - 查询模板
- [query/__init__.py](../../src/pt_snap_cli/query/__init__.py) - 模块导出
- [query/executor.py](../../src/pt_snap_cli/query/executor.py) - 执行器
- [query/builder.py](../../src/pt_snap_cli/query/builder.py) - 构建器
- [query/condition.py](../../src/pt_snap_cli/query/condition.py) - 条件
- [query/mapper.py](../../src/pt_snap_cli/query/mapper.py) - 映射器
- [query/registry.py](../../src/pt_snap_cli/query/registry.py) - 注册表
- [query/templates/](../../src/pt_snap_cli/query/templates/) - 查询模板
16 changes: 9 additions & 7 deletions .agents/quickstart/ARCHITECTURE.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# pt-snap-analyzer 架构概览
# pt-snap-cli 架构概览

## 项目定位

Expand All @@ -7,11 +7,13 @@ PyTorch Memory Snapshot Analysis Tool - 用于分析 PyTorch 内存快照的命
## 核心架构

```
pt_snap_analyzer/
src/pt_snap_cli/
├── cli.py # CLI 入口,提供 pt-snap 命令
├── context.py # 数据库上下文管理
├── core/ # 共享服务与产品错误
├── context.py # 只读数据库上下文
├── snapshot/ # 内建快照导入与回放运行时
├── models/ # 数据模型定义
└── query/ # 查询引擎
└── query/ # 查询引擎与模板
```

## 模块依赖关系
Expand Down Expand Up @@ -58,13 +60,13 @@ Models 模块

```bash
# 1. 设置数据库
pt-snap use snapshot.pkl.db
pt-snap focus snapshot.pkl.db

# 2. 执行泄漏检测
pt-snap query snapshot.pkl.db --template leak_detection
pt-snap query snapshot.pkl.db --template-use leak_detection

# 3. 调用栈分析
pt-snap query snapshot.pkl.db --template callstack_analysis
pt-snap query snapshot.pkl.db --template-use callstack_analysis
```

## 相关文件
Expand Down
9 changes: 4 additions & 5 deletions .agents/quickstart/README-for-agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
## 📚 文档结构

```
docs/agents/
.agents/quickstart/
├── README-for-agents.md # 本文件 - 导航索引
├── ARCHITECTURE.md # 整体架构概览
├── 01-cli.md # CLI 模块详情
Expand Down Expand Up @@ -66,16 +66,15 @@ ARCHITECTURE.md (5 分钟)

## 🔗 与现有文档的关系

- `docs/agents/` - **Agent 快速参考**(本文档)
- `docs/superpowers/` - **设计文档**(PRDs、specs、plans)
- `.agents/quickstart/` - **Agent 快速参考**(本文档)
- `README.md` - **用户使用指南**

## ✨ 最佳实践

```markdown
# 新会话开场
你好!我已阅读 [ARCHITECTURE.md](docs/agents/ARCHITECTURE.md),
了解到 pt-snap-analyzer 是一个 PyTorch 内存快照分析工具。
你好!我已阅读 [ARCHITECTURE.md](ARCHITECTURE.md),
了解到 pt-snap-cli 是一个 PyTorch 内存快照分析工具。
请问需要我帮助你做什么?

# 执行任务时
Expand Down
2 changes: 2 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
tests/fixtures/snapshots/snapshot_import_131k_sanitized.pickle filter=lfs diff=lfs merge=lfs -text
tests/fixtures/snapshots/snapshot_import_628k_sanitized.pickle filter=lfs diff=lfs merge=lfs -text
9 changes: 9 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,15 @@ Fixes #
- [ ] No new warnings introduced
- [ ] Changes tested locally

### Snapshot Runtime Provenance
<!-- Required when this PR changes src/pt_snap_cli/snapshot/**. -->
<!-- Use exactly "updated" or "no-update". For "updated", this PR must change
src/pt_snap_cli/snapshot/PROVENANCE.md. For "no-update", replace the reason
placeholder with a specific, nonempty explanation. -->
- [ ] Snapshot provenance evaluation completed when snapshot runtime files change
Snapshot provenance decision: <!-- updated | no-update -->
Snapshot provenance no-update reason: <!-- required only for no-update -->

## 📸 Screenshots (if applicable)
<!-- Add screenshots if this PR involves UI changes -->

Expand Down
Loading
Loading