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 .github/ISSUE_TEMPLATE/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
## For AI Agents

### Working In This Directory
- Keep issue forms scoped to this Python CLI/MCP project.
- Keep issue forms scoped to this Python CLI project.
- Preserve valid GitHub issue form YAML structure.
- Ordering is controlled by numbered filenames; `config.yml` has no `issue_templates` key.

Expand Down
22 changes: 10 additions & 12 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ facts here; user-facing behavior belongs in `README.md` and `docs/`.
## Project Scope

`pt-snap-cli` is a Python 3.10+ package for importing, splitting, inspecting,
and querying PyTorch memory snapshots. It exposes a Typer CLI, a Python API,
and an MCP server over shared service-layer behavior.
and querying PyTorch memory snapshots. It exposes a Typer CLI and a Python API
over shared service-layer behavior.

## Development Commands

Expand Down Expand Up @@ -53,7 +53,6 @@ when they exist.
| --- | --- | --- |
| 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 |
| Python API | `src/pt_snap_cli/api.py` (`SnapshotAnalyzer`) | Programmatic focus, query, and metadata facade |
| MCP | `src/pt_snap_cli/mcp/server.py` via `pt_snap_cli.mcp.server:main` | Agent tools/resources backed by `SnapshotAnalyzer` |
| 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 |
| Query engine | `src/pt_snap_cli/query/` | YAML loading, registry, parameter validation, SQL rendering/execution, and result mapping |
Expand All @@ -66,12 +65,12 @@ templates under category subdirectories are included by

## Repository Invariants

### CLI, API, and MCP
### CLI and Python API

- Keep normalized CLI and MCP behavior in shared API/core services; adapters may
format output differently but must not redefine focus, query, metadata, or
error semantics.
- Update `tests/test_contract_cli_mcp.py` when a shared CLI/MCP capability or
- Keep normalized CLI and `SnapshotAnalyzer` behavior in shared API/core
services; adapters may format output differently but must not redefine focus,
query, metadata, or error semantics.
- Update `tests/test_contract_cli_api.py` when a shared CLI/API capability or
normalized result changes.

### Focus and database selection
Expand Down Expand Up @@ -100,7 +99,7 @@ templates under category subdirectories are included by
leave `callstack_layout` unset and fail only variant templates. Do not
persist layout in `focus.json` or migrate databases on open.
- When template metadata or behavior changes, review the YAML, config, registry,
executor, `core/query_service.py`, CLI/MCP presentation, and focused tests
executor, `core/query_service.py`, CLI/API presentation, and focused tests
together.

### Agent skills
Expand All @@ -114,8 +113,7 @@ templates under category subdirectories are included by
Agent Skills hosts) plus Claude's independent `~/.claude/skills` or
`$CLAUDE_CONFIG_DIR/skills`. `--target cursor` and `--target codex` keep
the host-native extras; `--dir` covers anything else. List reports
`installed`, `outdated`, or `missing`. Skill management is CLI-only and
is not exposed on the MCP server.
`installed`, `outdated`, or `missing`. Skill management is CLI-only.

### Snapshot import and split

Expand All @@ -140,7 +138,7 @@ templates under category subdirectories are included by
| Focus precedence or persistence | `src/pt_snap_cli/config.py`, `src/pt_snap_cli/core/focus_service.py`, `src/pt_snap_cli/context.py` | `tests/test_config.py`, `tests/test_context.py`, `tests/core/test_focus_service.py` |
| Context/executor caching | `src/pt_snap_cli/core/context_cache.py`, `src/pt_snap_cli/api.py`, `src/pt_snap_cli/core/query_service.py` | `tests/core/test_context_cache.py`, `tests/test_snapshot_analyzer_cache.py`, `tests/test_query_cache_perf.py` |
| Query schema, SQL, or categories | `src/pt_snap_cli/query/`, `src/pt_snap_cli/core/query_service.py` | `tests/query/`, `tests/core/test_query_service.py` |
| MCP or Python API behavior | `src/pt_snap_cli/api.py`, `src/pt_snap_cli/mcp/server.py` | `tests/test_api.py`, `tests/test_mcp_server.py`, `tests/test_contract_cli_mcp.py` |
| Python API behavior | `src/pt_snap_cli/api.py` | `tests/test_api.py`, `tests/test_contract_cli_api.py` |
| Snapshot import or metadata | `src/pt_snap_cli/core/import_service.py`, `src/pt_snap_cli/core/import_metadata.py`, `src/pt_snap_cli/core/snapshot_import_backend.py` | `tests/core/test_import_*.py`, `tests/test_snapshot_db.py` |
| Snapshot splitting or replay | `src/pt_snap_cli/core/split_service.py`, `src/pt_snap_cli/snapshot/` | `tests/core/test_split_service.py`, `tests/snapshot/` |
| Reports | `src/pt_snap_cli/core/report_service.py`, report commands in `src/pt_snap_cli/cli.py` | `tests/core/test_report_service.py`, report cases in `tests/test_cli.py` |
Expand Down
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,18 @@
# Changelog

## [0.4.0] - Unreleased

本次发布将 Agent 集成入口统一到 bundled skills 与 CLI,并关闭 MCP 产品面。这是 0.x 阶段的 breaking 变更。

### 破坏性变更

- 移除 `pt-snap-mcp` 控制台入口、`src/pt_snap_cli/mcp/` 与核心依赖 `mcp`。安装 `pt-snap-cli`(无 extra)后依赖树不再包含 `mcp`、`starlette` 或 `uvicorn`。
- Agent 集成改为 skills + `pt-snap` CLI。`SnapshotAnalyzer` Python API 保留;`execute_query()` 默认仍为 `max_rows=None`(不截断),缺模板时 `get_template_info()` 仍返回 `None`。

### 兼容性提示

- 已配置 `pt-snap-mcp` 或 MCP 客户端的调用方需改用 CLI、bundled skills 或 Python API。历史 CHANGELOG 中的 MCP 条目仅作记录,不再对应已发布入口。

## [0.3.0] - 2026-09-17

本次发布聚焦 Agent 诊断技能与查询/导入性能:新增内存泄漏、碎片、峰值拆解与 Ascend NPU 采集等诊断 skill、`pt-snap skill` 共享安装命令及本地 skill 评测框架;SnapshotDB 采用去重 callstack 存储,叠加查询执行层优化,使导入、拆分与查询获得数量级加速,同时只读兼容 v1/v2 两种 callstack 布局;pickle 加载收敛到内建类型白名单,进一步降低反序列化风险。
Expand Down
13 changes: 2 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,20 +64,12 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough.
| `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-mcp` | Start the MCP server for agent integration |

`pt-snap --help` includes an agent hint: prefer `--json` where supported, start with the `pt-snap-helper` skill, and check availability with `pt-snap skill list --json`.

## MCP Server
## Agent Skills

`pt-snap-cli` provides an MCP (Model Context Protocol) server so AI agents can interact with PyTorch memory snapshots programmatically.

```bash
# Start the MCP server
pt-snap-mcp
```

See the [MCP guide](docs/en/mcp.md) for setup and usage details.
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).

## Documentation

Expand All @@ -90,7 +82,6 @@ See the [documentation index](docs/README.md) for all English and Chinese guides
| Running queries | [Querying](docs/en/querying.md) |
| Splitting snapshots | [Splitting Snapshots](docs/en/splitting.md) |
| Agent skills | [Agent Skills](docs/en/skills.md) |
| MCP server | [MCP Guide](docs/en/mcp.md) |
| Database format | [SnapshotDB Schema](docs/en/database.md) |
| Python API | [SnapshotAnalyzer API](docs/en/snapshot-analyzer-api.md) |
| Result mapping utility | [ResultMapper API](docs/en/result-mapper-api.md) |
Expand Down
13 changes: 2 additions & 11 deletions README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,20 +59,12 @@ pt-snap split snapshot.pkl --slices 4 --output snapshot-slices
| `pt-snap report` | 生成高层内存分析报告 |
| `pt-snap config` | 管理全局配置 |
| `pt-snap skill` | 列出并安装随包 agent skill |
| `pt-snap-mcp` | 启动 MCP 服务器以支持 Agent 集成 |

`pt-snap --help` 含 Agent 提示:在当前已支持的命令上优先使用 `--json`,从 `pt-snap-helper` skill 开始,并用 `pt-snap skill list --json` 检查是否已安装。

## MCP 服务器
## Agent Skills

`pt-snap-cli` 提供了 MCP(Model Context Protocol)服务器,使 AI Agent 能够以编程方式与 PyTorch 内存快照交互。

```bash
# 启动 MCP 服务器
pt-snap-mcp
```

详见 [MCP 指南](docs/zh/mcp.md)。
使用 `pt-snap skill install` 安装随包诊断工作流。Agent 集成入口是 skills 与 CLI,不再提供 MCP 服务器。详见 [Agent Skills 指南](docs/zh/skills.md)。

## 文档

Expand All @@ -85,7 +77,6 @@ pt-snap-mcp
| 运行查询 | [Querying](docs/zh/querying.md) |
| 拆分快照 | [拆分快照](docs/zh/splitting.md) |
| Agent skill | [Agent Skills](docs/zh/skills.md) |
| MCP 服务器 | [MCP 指南](docs/zh/mcp.md) |
| 数据库格式 | [SnapshotDB Schema](docs/zh/database.md) |
| Python API | [SnapshotAnalyzer API](docs/zh/snapshot-analyzer-api.md) |
| 结果映射工具 | [ResultMapper API](docs/zh/result-mapper-api.md) |
Expand Down
7 changes: 3 additions & 4 deletions docs/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
# docs

## Purpose
`docs` contains end-user and API documentation for the CLI, focus management, query templates, agent skills, MCP integration, snapshot database format, high-level and result mapping Python APIs, and retained legal evidence. It is split into English and Chinese language trees with a top-level README for navigation.
`docs` contains end-user and API documentation for the CLI, focus management, query templates, agent skills, snapshot database format, high-level and result mapping Python APIs, and retained legal evidence. It is split into English and Chinese language trees with a top-level README for navigation.

## Key Files
| File | Description |
Expand All @@ -22,21 +22,20 @@

### Working In This Directory
- Keep English and Chinese docs synchronized when changing user-visible behavior.
- Verify command names, options, template names, and MCP tool names against source code before updating docs.
- Verify command names, options, and template names against source code before updating docs.
- Prefer updating existing guides over creating new documentation pages.

### Testing Requirements
- For documentation-only changes, review rendered Markdown structure and verify referenced commands/options exist.
- If examples depend on behavior changes, run the matching CLI or service tests.

### Common Patterns
- The two language trees mirror the same topics: quick start, focus management, querying, snapshot splitting, agent skills, MCP, database schema, SnapshotAnalyzer API, and result mapper API.
- The two language trees mirror the same topics: quick start, focus management, querying, snapshot splitting, agent skills, database schema, SnapshotAnalyzer API, and result mapper API.

## Dependencies

### Internal
- `src/pt_snap_cli/cli.py` defines documented CLI commands and options.
- `src/pt_snap_cli/mcp/server.py` defines documented MCP tools, resource, and prompt.
- `src/pt_snap_cli/query/templates/` defines documented built-in template names and parameters.

### External
Expand Down
2 changes: 0 additions & 2 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@
| Reports | [en/querying.md](en/querying.md) |
| Splitting Snapshots | [en/splitting.md](en/splitting.md) |
| Agent skills | [en/skills.md](en/skills.md) |
| MCP server | [en/mcp.md](en/mcp.md) |
| Database Schema | [en/database.md](en/database.md) |
| Import metadata | [en/database.md](en/database.md) |
| SnapshotAnalyzer API | [en/snapshot-analyzer-api.md](en/snapshot-analyzer-api.md) |
Expand All @@ -28,7 +27,6 @@
| 分析报告 | [zh/querying.md](zh/querying.md) |
| 拆分快照 | [zh/splitting.md](zh/splitting.md) |
| Agent skill | [zh/skills.md](zh/skills.md) |
| MCP 服务器 | [zh/mcp.md](zh/mcp.md) |
| 数据库格式 | [zh/database.md](zh/database.md) |
| 导入 metadata | [zh/database.md](zh/database.md) |
| SnapshotAnalyzer API | [zh/snapshot-analyzer-api.md](zh/snapshot-analyzer-api.md) |
Expand Down
5 changes: 2 additions & 3 deletions docs/en/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
# en

## Purpose
`docs/en` contains the English documentation set for installing and using `pt-snap-cli`, managing focus, querying and splitting snapshots, installing bundled agent skills, running the MCP server, understanding the SQLite schema, and using the high-level and result mapping Python APIs.
`docs/en` contains the English documentation set for installing and using `pt-snap-cli`, managing focus, querying and splitting snapshots, installing bundled agent skills, understanding the SQLite schema, and using the high-level and result mapping Python APIs.

## Key Files
| File | Description |
Expand All @@ -14,7 +14,6 @@
| `querying.md` | Query listing, template info, parameter usage, result limits, and built-in templates. |
| `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. |
| `mcp.md` | MCP server setup, tools, resources, prompts, and agent usage. |
| `database.md` | Snapshot SQLite table/schema reference. |
| `snapshot-analyzer-api.md` | High-level Python API for focus, template discovery, queries, and import metadata. |
| `result-mapper-api.md` | Result mapping API documentation. |
Expand All @@ -41,7 +40,7 @@
## Dependencies

### Internal
- CLI, MCP, query template, and schema details should be checked against `src/pt_snap_cli/` before editing.
- CLI, query template, and schema details should be checked against `src/pt_snap_cli/` before editing.

### External
- Markdown only.
Expand Down
2 changes: 1 addition & 1 deletion docs/en/database.md
Original file line number Diff line number Diff line change
Expand Up @@ -339,7 +339,7 @@ on each `trace_entry_<device>` table and have no shared `callstack` table
template name, parameter set, and output schema. The query engine selects v1 or
v2 SQL from the detected layout. Other templates do not depend on this split.

Detection is read-only: `focus`, `query`, reports, the Python API, and MCP all
Detection is read-only: `focus`, `query`, reports, and the Python API all
open the database with SQLite `mode=ro`. Layout is not stored in
`.pt-snap/focus.json`. Conflicting columns, mixed devices, a damaged
`callstack` table, or metadata that disagrees with the physical schema leave
Expand Down
112 changes: 0 additions & 112 deletions docs/en/mcp.md

This file was deleted.

11 changes: 5 additions & 6 deletions docs/en/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,8 +95,8 @@ pt-snap query --template-info allocation
pt-snap query --template-use allocation --params '{"order_by": "reserved", "order_dir": "desc"}' -n 5
```

The same rules apply to `SnapshotAnalyzer.execute_query()` and the MCP
`execute_query` tool, which raise `TemplateRenderError` with the same message.
The same rules apply to `SnapshotAnalyzer.execute_query()`, which raises
`TemplateRenderError` with the same message.

## Peak Memory Attribution Workflow

Expand Down Expand Up @@ -214,11 +214,10 @@ Found 150 results, showing 2:
... and 148 more (use -n to show more)
```

The "Found N" count is exact even when output is capped. Note that the MCP
`execute_query` tool applies a default cap of 100 rows, unlike the CLI; see
[MCP Server: Query Results and Row Limits](mcp.md#query-results-and-row-limits).
The "Found N" count is exact even when output is capped. `SnapshotAnalyzer.execute_query()`
defaults to `max_rows=None` (no cap), matching the CLI unless `-n` / `max_rows` is set.

CLI, Python API, and MCP query results contain raw SQLite values. A template's
CLI and Python API query results contain raw SQLite values. A template's
`output_schema` is metadata and is not applied automatically during query
execution. Use `ResultMapper` explicitly when converted values such as
hexadecimal address strings are required.
Expand Down
Loading
Loading