diff --git a/.agents/quickstart/01-cli.md b/.agents/quickstart/01-cli.md index 9c9fb5c..f375eb9 100644 --- a/.agents/quickstart/01-cli.md +++ b/.agents/quickstart/01-cli.md @@ -9,12 +9,12 @@ ### `app` (Typer) Typer 应用实例,管理所有 CLI 命令。 -### `use_database()` +### `focus_database()` 设置当前分析的数据库文件,验证有效性并显示可用设备。 ### `query_database()` 执行查询命令,支持: -- `--template`: 指定查询模板 +- `--template-use`: 指定查询模板 - `--params`: JSON 格式参数 - `--device`: 指定设备 ID - `--list`: 列出可用模板 @@ -31,7 +31,7 @@ Typer 应用实例,管理所有 CLI 命令。 ## 使用示例 ```python -from pt_snap_analyzer.cli import app +from pt_snap_cli.cli import app # 运行 CLI app() @@ -42,10 +42,10 @@ 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 @@ -53,6 +53,6 @@ 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) - 查询执行器 diff --git a/.agents/quickstart/02-context.md b/.agents/quickstart/02-context.md index 4aa522c..97671e1 100644 --- a/.agents/quickstart/02-context.md +++ b/.agents/quickstart/02-context.md @@ -41,7 +41,7 @@ ## 使用示例 ```python -from pt_snap_analyzer.context import Context +from pt_snap_cli.context import Context # 初始化并验证 ctx = Context("snapshot.pkl.db") @@ -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 命令 diff --git a/.agents/quickstart/03-models.md b/.agents/quickstart/03-models.md index 2db6414..9ceff96 100644 --- a/.agents/quickstart/03-models.md +++ b/.agents/quickstart/03-models.md @@ -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` - 分配事件 @@ -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) - 枚举定义 diff --git a/.agents/quickstart/04-query.md b/.agents/quickstart/04-query.md index 8024428..97d00ac 100644 --- a/.agents/quickstart/04-query.md +++ b/.agents/quickstart/04-query.md @@ -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/) - 查询模板 diff --git a/.agents/quickstart/ARCHITECTURE.md b/.agents/quickstart/ARCHITECTURE.md index 9ffd73f..47c303e 100644 --- a/.agents/quickstart/ARCHITECTURE.md +++ b/.agents/quickstart/ARCHITECTURE.md @@ -1,4 +1,4 @@ -# pt-snap-analyzer 架构概览 +# pt-snap-cli 架构概览 ## 项目定位 @@ -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/ # 查询引擎与模板 ``` ## 模块依赖关系 @@ -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 ``` ## 相关文件 diff --git a/.agents/quickstart/README-for-agents.md b/.agents/quickstart/README-for-agents.md index c3f682c..ae7c006 100644 --- a/.agents/quickstart/README-for-agents.md +++ b/.agents/quickstart/README-for-agents.md @@ -3,7 +3,7 @@ ## 📚 文档结构 ``` -docs/agents/ +.agents/quickstart/ ├── README-for-agents.md # 本文件 - 导航索引 ├── ARCHITECTURE.md # 整体架构概览 ├── 01-cli.md # CLI 模块详情 @@ -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 内存快照分析工具。 请问需要我帮助你做什么? # 执行任务时 diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..6f484a0 --- /dev/null +++ b/.gitattributes @@ -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 diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md index 8f39cdc..ed5f6fd 100644 --- a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md +++ b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md @@ -16,6 +16,15 @@ Fixes # - [ ] No new warnings introduced - [ ] Changes tested locally +### Snapshot Runtime Provenance + + +- [ ] Snapshot provenance evaluation completed when snapshot runtime files change +Snapshot provenance decision: +Snapshot provenance no-update reason: + ## 📸 Screenshots (if applicable) diff --git a/.github/scripts/check_snapshot_provenance.py b/.github/scripts/check_snapshot_provenance.py new file mode 100644 index 0000000..110eae7 --- /dev/null +++ b/.github/scripts/check_snapshot_provenance.py @@ -0,0 +1,111 @@ +from __future__ import annotations + +import argparse +import os +import re +import subprocess +import sys +from collections.abc import Sequence +from pathlib import Path + +SNAPSHOT_PREFIX = "src/pt_snap_cli/snapshot/" +PROVENANCE_PATH = f"{SNAPSHOT_PREFIX}PROVENANCE.md" +DECISION_LABEL = "Snapshot provenance decision" +REASON_LABEL = "Snapshot provenance no-update reason" +_DECLARATION = re.compile( + rf"^[ \t]*(?P