From 63975621f8fceadd0411462d5cbd638d8f89db34 Mon Sep 17 00:00:00 2001 From: codeasier Date: Sun, 12 Apr 2026 16:15:22 +0800 Subject: [PATCH] feat: add query template layering with category-based filtering - Rename 7 YAML templates to remove _v2 suffix - Add category metadata (basic/statistical/business) to each template - Extend QueryTemplate model with category field - Add list_by_category() / list_by_category_with_details() to registry - CLI --list outputs grouped by category - CLI --category parameter filters templates by category - Update README, README_zh, and Agent docs - Add 12 new test cases for category functionality --- .agents/quickstart/01-cli.md | 2 +- .agents/quickstart/04-query.md | 10 +- .agents/quickstart/ARCHITECTURE.md | 4 +- README.md | 97 ++++++------------- README_zh.md | 97 ++++++------------- pt_snap_cli/cli.py | 56 ++++++++--- pt_snap_cli/query/config.py | 2 + pt_snap_cli/query/registry.py | 62 ++++++++++++ ...tive_blocks_v2.yaml => active_blocks.yaml} | 3 +- ...ks_by_size_v2.yaml => blocks_by_size.yaml} | 3 +- ...alysis_v2.yaml => callstack_analysis.yaml} | 3 +- ...y_action_v2.yaml => events_by_action.yaml} | 3 +- ..._detection_v2.yaml => leak_detection.yaml} | 3 +- ...ry_summary_v2.yaml => memory_summary.yaml} | 3 +- ..._timeline_v2.yaml => memory_timeline.yaml} | 3 +- tests/test_cli.py | 43 ++++++-- tests/test_query_config.py | 28 ++++++ tests/test_query_registry.py | 51 ++++++++++ 18 files changed, 308 insertions(+), 165 deletions(-) rename pt_snap_cli/query/templates/{active_blocks_v2.yaml => active_blocks.yaml} (95%) rename pt_snap_cli/query/templates/{blocks_by_size_v2.yaml => blocks_by_size.yaml} (95%) rename pt_snap_cli/query/templates/{callstack_analysis_v2.yaml => callstack_analysis.yaml} (95%) rename pt_snap_cli/query/templates/{events_by_action_v2.yaml => events_by_action.yaml} (94%) rename pt_snap_cli/query/templates/{leak_detection_v2.yaml => leak_detection.yaml} (95%) rename pt_snap_cli/query/templates/{memory_summary_v2.yaml => memory_summary.yaml} (92%) rename pt_snap_cli/query/templates/{memory_timeline_v2.yaml => memory_timeline.yaml} (96%) diff --git a/.agents/quickstart/01-cli.md b/.agents/quickstart/01-cli.md index 83bfed2..9c9fb5c 100644 --- a/.agents/quickstart/01-cli.md +++ b/.agents/quickstart/01-cli.md @@ -45,7 +45,7 @@ pt-snap --version pt-snap use examples/snapshot.pkl.db # 执行查询 -pt-snap query snapshot.pkl.db --template leak_detection_v2 --params '{"min_size": 1024}' +pt-snap query snapshot.pkl.db --template leak_detection --params '{"min_size": 1024}' # 列出模板 pt-snap query snapshot.pkl.db --list diff --git a/.agents/quickstart/04-query.md b/.agents/quickstart/04-query.md index 9450a0e..8615e2a 100644 --- a/.agents/quickstart/04-query.md +++ b/.agents/quickstart/04-query.md @@ -55,11 +55,11 @@ Fluent API 构建 SQL 查询。 ## 预定义模板 -位于 `query/templates/` 目录: +位于 `query/templates/` 目录,按分类组织: -1. **leak_detection_v2.yaml** - 内存泄漏检测 -2. **callstack_analysis_v2.yaml** - 调用栈分析 -3. **memory_timeline_v2.yaml** - 内存时间线 +- **Basic**: `active_blocks.yaml`, `blocks_by_size.yaml`, `events_by_action.yaml`, `memory_timeline.yaml` +- **Statistical**: `memory_summary.yaml`, `callstack_analysis.yaml` +- **Business**: `leak_detection.yaml` ## 使用示例 @@ -74,7 +74,7 @@ executor = QueryExecutor(ctx, template_dir=Path("query/templates")) # 执行模板查询 results = executor.execute_template( - "leak_detection_v2", + "leak_detection", params={"min_size": 1024}, device_id=0 ) diff --git a/.agents/quickstart/ARCHITECTURE.md b/.agents/quickstart/ARCHITECTURE.md index 5ba8f93..9ffd73f 100644 --- a/.agents/quickstart/ARCHITECTURE.md +++ b/.agents/quickstart/ARCHITECTURE.md @@ -61,10 +61,10 @@ Models 模块 pt-snap use snapshot.pkl.db # 2. 执行泄漏检测 -pt-snap query snapshot.pkl.db --template leak_detection_v2 +pt-snap query snapshot.pkl.db --template leak_detection # 3. 调用栈分析 -pt-snap query snapshot.pkl.db --template callstack_analysis_v2 +pt-snap query snapshot.pkl.db --template callstack_analysis ``` ## 相关文件 diff --git a/README.md b/README.md index d520ca8..c70c35a 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ Use `PT_SNAP_DB_PATH` when one shell or agent needs an isolated database without ```bash export PT_SNAP_DB_PATH=/path/to/agent-specific/snapshot.db -pt-snap query --template-use memory_summary_v2 +pt-snap query --template-use memory_summary ``` You can also print the export command after validation: @@ -77,13 +77,13 @@ pt-snap use pt-snap query --list # Execute query (automatically uses the resolved database context) -pt-snap query --template-use memory_summary_v2 +pt-snap query --template-use memory_summary # Query with parameters -pt-snap query --template-use leak_detection_v2 --params '{"min_size": 1024}' +pt-snap query --template-use leak_detection --params '{"min_size": 1024}' # Specify device -pt-snap query --template-use active_blocks_v2 --device 0 +pt-snap query --template-use active_blocks --device 0 ``` #### Resolution Priority @@ -99,7 +99,7 @@ Even with context configured, you can still specify a different database on the ```bash # Use temporarily specified database (does not affect context) -pt-snap query /path/to/other.db --template-use memory_summary_v2 +pt-snap query /path/to/other.db --template-use memory_summary ``` #### Legacy Global Configuration @@ -142,7 +142,7 @@ Context content example: **Query without configured database:** ```bash -pt-snap query --template-use memory_summary_v2 +pt-snap query --template-use memory_summary # Error: No database path specified and no database configured. # Use 'pt-snap use ' to set a project database, or provide db_path argument. ``` @@ -152,7 +152,7 @@ pt-snap query --template-use memory_summary_v2 If the resolved database file is deleted or moved, `pt-snap` reports the context source and leaves the context file unchanged: ```bash -pt-snap query --template-use memory_summary_v2 +pt-snap query --template-use memory_summary # Error: Database from project context not found: /path/to/missing.db # Use 'pt-snap use ' to set a new project database, or provide db_path argument. ``` @@ -164,9 +164,9 @@ pt-snap query --template-use memory_summary_v2 pt-snap use examples/snapshot_expandable.pkl.db # 2. Then query directly without repeating path -pt-snap query --template-use memory_summary_v2 -pt-snap query --template-use active_blocks_v2 --device 0 -pt-snap query --template-use leak_detection_v2 +pt-snap query --template-use memory_summary +pt-snap query --template-use active_blocks --device 0 +pt-snap query --template-use leak_detection # 3. View the effective context and source pt-snap use @@ -202,7 +202,8 @@ pt-snap query [--template-use ] [--params ] [--device ] - `--template-use`: Query template name (required unless using --list or --template-info) - `--params`: Query parameters in JSON format (optional) - `--device`: Device ID (optional) -- `--list`: List available query templates +- `--list`: List available query templates (grouped by category) +- `--category`: Filter templates by category when using --list (`basic`, `statistical`, `business`) - `--template-info