From a6627a525e81ad9c61cedd1dbb00fdba8d460188 Mon Sep 17 00:00:00 2001 From: codeasier Date: Sat, 19 Sep 2026 16:25:36 +0800 Subject: [PATCH 1/2] feat(query): distinguish truncated pages without a default COUNT Agents cannot tell a complete result from a capped page when total silently becomes a COUNT at the row limit. Probe one extra row for has_more, keep exact totals opt-in, and time-bound execution separately from output limits. Fixes #140 --- CHANGELOG.md | 1 + docs/en/querying.md | 39 ++- docs/en/snapshot-analyzer-api.md | 10 +- docs/zh/querying.md | 34 +- docs/zh/snapshot-analyzer-api.md | 10 +- skills/pt-snap-helper/SKILL.md | 3 + skills/pt-snap-memory-fragmentation/SKILL.md | 15 +- skills/pt-snap-memory-leak/SKILL.md | 14 +- skills/pt-snap-memory-peak-breakdown/SKILL.md | 6 +- src/pt_snap_cli/api.py | 9 + .../bundled_skills/pt-snap-helper/SKILL.md | 3 + .../pt-snap-memory-fragmentation/SKILL.md | 15 +- .../pt-snap-memory-leak/SKILL.md | 14 +- .../pt-snap-memory-peak-breakdown/SKILL.md | 6 +- src/pt_snap_cli/cli.py | 30 +- src/pt_snap_cli/core/__init__.py | 2 + src/pt_snap_cli/core/error_codes.py | 7 + src/pt_snap_cli/core/errors.py | 6 + src/pt_snap_cli/core/models.py | 4 + src/pt_snap_cli/core/query_service.py | 79 ++++- src/pt_snap_cli/query/AGENTS.md | 4 + src/pt_snap_cli/query/executor.py | 178 +++++++++-- .../query/templates/basic/allocation.yaml | 2 +- .../query/templates/basic/block.yaml | 2 +- .../query/templates/basic/event.yaml | 4 +- tests/core/test_query_service.py | 16 +- tests/query/AGENTS.md | 1 + tests/query/test_callstack_schema_compat.py | 3 + tests/query/test_query_completeness.py | 302 ++++++++++++++++++ tests/query/test_query_max_rows_pushdown.py | 14 +- tests/skills/test_helper_contract.py | 2 + .../test_memory_fragmentation_contract.py | 1 + tests/skills/test_memory_leak_contract.py | 3 + .../test_memory_peak_breakdown_contract.py | 2 + tests/test_api.py | 3 + tests/test_cli_json.py | 8 +- tests/test_contract_cli_api.py | 16 +- 37 files changed, 782 insertions(+), 86 deletions(-) create mode 100644 tests/query/test_query_completeness.py diff --git a/CHANGELOG.md b/CHANGELOG.md index f6cde3b..428cac6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ - `focus`、`import`、`split`、`query`、`config` 支持 `--json`。成功结果带 `schema_version` / `ok` 信封,以及 `db_path`、`focus_source`、`device_id`、`template`、`effective_params` 等上下文。`query --list` / `--template-info` / 执行共用该选项;`--template-info --json` 透出 #147 字段语义。 - JSON 模式失败时 stdout 为空,stderr 为带稳定错误码的结构化对象(如 `TEMPLATE_NOT_FOUND`、`INVALID_PARAMETER`、`DATABASE_NOT_FOUND`、`DEVICE_NOT_FOUND`),退出码非零。`pt-snap` 控制台入口返回 Typer/Click 的退出码(不再丢弃非 standalone 返回值),在检测到 `--json` 时也会把 Click 用法/解析错误写成 `INVALID_PARAMETER` 信封(退出码 2),并把 Ctrl-C / EOF 写成 `ERROR` / `Aborted!`。解析失败时的 `--json` 判定是 argv 词法扫描(best-effort):忽略 `--` 之后的词,`--opt=value` 与数字词不吞后续参数。`query --json` 的 `effective_params.limit` 是尾部 SQL `LIMIT`(模板 `limit` 与 `-n` 的合并,或追加的 `-n`);CTE 内的 `top_n` 仍是独立参数。 - `split --json` 只控制 stdout 清单,与 `--format json` 的分片文件格式相互独立。`focus --session --json` 返回验证结果与 `PT_SNAP_DB_PATH` 赋值信息,不暗示已修改父 shell。 +- 查询结果增加完整性与分页字段:`has_more` / `truncated` / `total_is_exact`。默认 `total` 等于本页 `returned`;`--exact-total`(API `exact_total=True`)才对匹配集合做 `COUNT`。有限 `LIMIT` 时多取一行判断是否还有后续,不再在触达 `-n` 时自动计数。`event` / `block` / `allocation` 在 `order_by` 后用 `id` 做稳定分页次序。`--timeout` 与 `PT_SNAP_QUERY_TIMEOUT` 经 SQLite progress handler 限制执行时间,与 `-n` 行数上限分离;超时错误码为 `QUERY_TIMEOUT`。诊断 skill 默认有界查询,并按 `has_more` 续页。 ### 兼容性提示 diff --git a/docs/en/querying.md b/docs/en/querying.md index 193c93b..a826d31 100644 --- a/docs/en/querying.md +++ b/docs/en/querying.md @@ -9,7 +9,7 @@ Run memory analysis queries against your snapshot database. ```bash pt-snap query [DB_PATH] [--template-use ] [--params ] \ [--device ] [--list] [--category ] \ - [--template-info