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
13 changes: 7 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,13 @@ pip install -e .
## Quick Start

```bash
# Set the snapshot database (saves context for future queries)
pt-snap use examples/snapshot_expandable.pkl.db
# Set the snapshot database and device
pt-snap focus examples/snapshot_expandable.pkl.db --device 0

# List available queries
pt-snap query --list

# Run a query
# Run a query (automatically uses the focused device)
pt-snap query --template-use memory_summary

# Detect potential memory leaks
Expand All @@ -32,7 +32,7 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough.

| Command | Description |
|---------|-------------|
| `pt-snap use` | Set and manage snapshot database context |
| `pt-snap focus` | Set and manage analysis focus (database + device) |
| `pt-snap query` | Run memory analysis queries |
| `pt-snap config` | Manage global configuration |

Expand All @@ -41,7 +41,7 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough.
| Topic | Guide |
|-------|-------|
| Getting started | [Quick Start](docs/en/quickstart.md) |
| Managing contexts | [Context Management](docs/en/context-management.md) |
| Managing focus | [Focus Management](docs/en/focus-management.md) |
| Running queries | [Querying](docs/en/querying.md) |
| Database format | [SnapshotDB Schema](docs/en/database.md) |
| Python API | [ResultMapper API](docs/en/result-mapper-api.md) |
Expand All @@ -63,7 +63,8 @@ pt-snap-cli/
├── src/
│ └── pt_snap_cli/
│ ├── cli.py # CLI entry point
│ ├── context.py # Context management
│ ├── context.py # Database context manager
│ ├── config.py # Focus management
│ ├── query/
│ │ ├── builder.py # Query builder
│ │ ├── executor.py # Query executor
Expand Down
13 changes: 7 additions & 6 deletions README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,13 @@ pip install -e .
## 快速开始

```bash
# 设置快照数据库(保存上下文供后续查询使用)
pt-snap use examples/snapshot_expandable.pkl.db
# 设置快照数据库和设备
pt-snap focus examples/snapshot_expandable.pkl.db --device 0

# 列出可用查询
pt-snap query --list

# 运行查询
# 运行查询(自动使用 focus 中设置的设备)
pt-snap query --template-use memory_summary

# 检测潜在内存泄漏
Expand All @@ -32,7 +32,7 @@ pt-snap query --template-use leak_detection --params '{"min_size": 1024}'

| 命令 | 说明 |
|------|------|
| `pt-snap use` | 设置和管理快照数据库上下文 |
| `pt-snap focus` | 设置和管理分析焦点(数据库 + 设备) |
| `pt-snap query` | 运行内存分析查询 |
| `pt-snap config` | 管理全局配置 |

Expand All @@ -41,7 +41,7 @@ pt-snap query --template-use leak_detection --params '{"min_size": 1024}'
| 主题 | 指南 |
|------|------|
| 入门指南 | [Quick Start](docs/zh/quickstart.md) |
| Context 管理 | [Context Management](docs/zh/context-management.md) |
| Focus 管理 | [Focus Management](docs/zh/focus-management.md) |
| 运行查询 | [Querying](docs/zh/querying.md) |
| 数据库格式 | [SnapshotDB Schema](docs/zh/database.md) |
| Python API | [ResultMapper API](docs/zh/result-mapper-api.md) |
Expand All @@ -63,7 +63,8 @@ pt-snap-cli/
├── src/
│ └── pt_snap_cli/
│ ├── cli.py # CLI 入口
│ ├── context.py # 上下文管理
│ ├── context.py # 数据库连接管理器
│ ├── config.py # 焦点管理
│ ├── query/
│ │ ├── builder.py # 查询构建器
│ │ ├── executor.py # 查询执行器
Expand Down
104 changes: 0 additions & 104 deletions docs/en/context-management.md

This file was deleted.

115 changes: 115 additions & 0 deletions docs/en/focus-management.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
# Focus Management

[中文](../zh/focus-management.md) | English

`pt-snap` supports project-scoped focus so different terminals, agents, or working directories can analyze different databases and devices without interfering with each other.

## Resolution Priority

Focus is resolved in this order:

1. **Explicit argument**: `pt-snap query <db_path>`
2. **Environment variable**: `PT_SNAP_DB_PATH`
3. **Project focus**: Nearest `.pt-snap/focus.json`, searching upward from current directory
4. **Legacy global config**: `~/.config/pt-snap-cli/config.json`

## Set Project Database and Device

```bash
# Set database only
pt-snap focus /path/to/your/snapshot.db

# Set database and device together
pt-snap focus /path/to/your/snapshot.db --device 0

# Change device only (keeps current database)
pt-snap focus --device 1
```

After successful validation, the database path and device ID are saved to `.pt-snap/focus.json` in the current directory.

## Session-Scoped Override

When a shell or agent needs an isolated database without changing project focus:

```bash
export PT_SNAP_DB_PATH=/path/to/agent-specific/snapshot.db
pt-snap query --template-use memory_summary
```

Or validate and print the export command in one step:

```bash
pt-snap focus /path/to/agent-specific/snapshot.db --session
```

## View Current Focus

```bash
pt-snap focus
```

This shows the resolved database path, device ID, and where they came from (project focus, session env, or global config).

## Override Focus

Even with focus configured, you can temporarily specify a different database or device on the command line:

```bash
# Uses this database temporarily, does not affect saved focus
pt-snap query /path/to/other.db --template-use memory_summary

# Override device (ignores focused device_id)
pt-snap query --template-use memory_summary --device 2
```

## Legacy Global Configuration

Global configuration is kept for compatibility. For concurrent workflows, prefer project focus or session overrides.

```bash
# Store in ~/.config/pt-snap-cli/config.json
pt-snap focus /path/to/your/snapshot.db --global
```

### Manage Global Config

```bash
pt-snap config # View global configuration
pt-snap config --path # Show config file path
pt-snap config --clear # Clear global configuration
```

## Focus File Locations

| Scope | File |
|-------|------|
| Project | `.pt-snap/focus.json` (git-ignored, per-project) |
| Global | `~/.config/pt-snap-cli/config.json` |

### Focus File Format

```json
{
"db_path": "/path/to/your/snapshot.db",
"device_id": 0
}
```

## Error Handling

**No focus configured:**

```bash
pt-snap query --template-use memory_summary
# Error: No database path specified and no database configured.
# Use 'pt-snap focus <database_path>' to set a project database, or provide db_path argument.
```

**Database file not found:**

```bash
pt-snap query --template-use memory_summary
# Error: Database from project focus not found: /path/to/missing.db
# Use 'pt-snap focus <new_database_path>' to set a new project database, or provide db_path argument.
```
20 changes: 13 additions & 7 deletions docs/en/quickstart.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Quick Start

[English](quickstart.md) | [中文](../zh/quickstart.md)
[中文](../zh/quickstart.md) | English

Get up and running with `pt-snap-cli` in a few minutes.

Expand All @@ -12,15 +12,21 @@ pip install -e .

## Your First Analysis

### Step 1: Set the Snapshot Database
### Step 1: Set the Snapshot Database and Device

Point `pt-snap` to your SQLite snapshot database file:

```bash
pt-snap use examples/snapshot_expandable.pkl.db
pt-snap focus examples/snapshot_expandable.pkl.db --device 0
```

This validates the database and saves the path to `.pt-snap/context.json` in your current directory, so you don't need to repeat it.
This validates the database and saves the path and device ID to `.pt-snap/focus.json` in your current directory, so you don't need to repeat it.

If you only want to set the database (no device yet):

```bash
pt-snap focus examples/snapshot_expandable.pkl.db
```

### Step 2: List Available Queries

Expand All @@ -40,12 +46,12 @@ pt-snap query --template-use memory_summary
# Detect potential memory leaks
pt-snap query --template-use leak_detection --params '{"min_size": 1024}'

# View active memory blocks on device 0
pt-snap query --template-use active_blocks --device 0
# Query automatically uses the focused device, or you can override it
pt-snap query --template-use active_blocks --device 1
```

## What's Next

- [Context Management](context-management.md) — Learn how to manage multiple databases across projects and sessions
- [Focus Management](focus-management.md) — Learn how to manage database and device focus across projects and sessions
- [Querying](querying.md) — Full guide to all query templates, parameters, and output
- [Database Schema](database.md) — Understand the SnapshotDB format
Loading
Loading