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
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@
### 新增

- 新增 `pt-snap-helper` 引导技能,并在 `pt-snap --help` 末尾加入 Agent 提示(优先使用已支持的 `--json`,用 `pt-snap skill list --json` 检查技能)。helper 只读路由,不自动安装包、导入 pickle 或改写 focus;随包分发走 `pt-snap skill`。
- helper 与泄漏/碎片/峰值诊断 skill 补充 focus 目标缺失但同目录或当前目录存在候选 `.db` 时的恢复规则:不按名称/大小/时间自动选库(即使只有一个候选也需用户确认),确认前不诊断、不用 Python/`sqlite3` 绕过 CLI,确认后先执行 `pt-snap metadata` 再继续原有预检;合法旧库的 `unavailable` / `metadata_missing` 不强制重新 import,换库不继承旧 device,且不持久化 focus、不代跑 import。
- `--template-info` 与 `get_template_info()` 展示参数 `choices`。`order_by` / `order_dir` 等会写入 SQL 标识符或关键字的参数必须声明封闭取值列表;字符串 `choices` 大小写不敏感,并规范化为声明拼写(如 `desc` → `DESC`)。
- `output_schema` 可声明字段语义(`units`、`metric_semantics`、`scope`、`denominator`、`sentinel`、`interpretation_limits`),查询级可声明 `semantics_version` 与解释限制。`--template-info` 与 `get_template_info()` 透出同一份契约。`execute_query()` 结果增加 `template` 与 `semantics_version`,行数据仍为原始 SQLite 值。优先覆盖 `leak_detection`、`memory_peak`、`allocator_gap`、`active_memory_callstack_at_event`。
- `leak_detection` 的对外描述改为「捕获范围内无释放完成记录的候选」,不再写成已确认泄漏。
Expand Down
29 changes: 29 additions & 0 deletions skills/pt-snap-helper/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,35 @@ A SnapshotDB is a pt-snap SQLite database (typically `.db`) with a
4. Do not run `pt-snap focus <database_path>` to persist a new focus from this
skill. Diagnostic skills may read the current focus with no arguments.

#### Missing focus target with sibling candidates

Enter this recovery branch only when the next diagnostic skill would depend on
the current effective focus (environment variable, project `.pt-snap/focus.json`,
or global config) and that database file is missing. A displayed path or exit
code 0 from `pt-snap focus` does not mean the target is usable; text mode prints
`Warning: Database file does not exist!` and `pt-snap focus --json` reports
`db_exists: false`. If the user already supplied a valid database path, use that
explicit path and do not enter this branch.

1. List candidate files only in the missing database's directory and the current
working directory. Do not recurse. Deduplicate paths. Discover `*.db` and
`*.pickle.db` by suffix only; a matching suffix is not proof the file is a
SnapshotDB. Do not auto-select by name, size, or mtime. Even a single
candidate requires an explicit user choice.
2. Ask the user to use one listed candidate or to treat pickle import as a
separate trusted-input decision. With zero candidates, ask for a valid
SnapshotDB path or explain that trusted import. Do not run `pt-snap import`
and do not persist focus.
3. Before the user confirms a path, do not run diagnostic queries, reports, or
metadata against any candidate, and do not inspect candidates with Python,
the `sqlite3` CLI, or hand-assembled SQL.
4. After the user confirms a path, hand off to the matching diagnostic skill
with that explicit database path. Tell it that the next inspect step is
`pt-snap metadata '<db_path>' --json`, not `pt-snap query`. Do not inherit
the focused device from the missing target; the diagnostic skill must
re-resolve device from the confirmed database. This helper must not run
metadata, query, import, or persist focus.

This helper may mention that `pt-snap overview '<db_path>' --json` and
`pt-snap capabilities --json` exist. Running those orientation commands
belongs to the diagnostic skill. Do not import pickle or persist focus.
Expand Down
40 changes: 36 additions & 4 deletions skills/pt-snap-memory-fragmentation/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,9 +58,9 @@ If either input was not supplied, inspect the current state:
pt-snap focus
```

Use the displayed database and focused device only when both are present. If
either remains absent or ambiguous, ask the user to select it and stop until it
is explicit. Do not run `pt-snap focus <database_path>`, use `--session`, or
Use the displayed database and focused device only when both are present and
the database file exists. If either remains absent or ambiguous, ask the user
to select it and stop until it is explicit. Do not run `pt-snap focus <database_path>`, use `--session`, or
otherwise persist or modify focus. After resolving the scope, pass both the
database and device explicitly to every diagnostic query and report command.

Expand All @@ -69,6 +69,36 @@ pickle, or deserialize a pickle. If only a pickle is available, stop and explain
that conversion requires a separate trusted-input decision because pickle
loading is not a sandbox.

#### Missing focus target with sibling candidates

Enter this recovery branch only when diagnosis depends on the current effective
focus (environment variable, project `.pt-snap/focus.json`, or global config)
and that database file is missing. A displayed path or exit code 0 from
`pt-snap focus` does not mean the target is usable; text mode prints
`Warning: Database file does not exist!` and `pt-snap focus --json` reports
`db_exists: false`. If the user already supplied a valid database path, use that
explicit path and do not enter this branch.

1. List candidate files only in the missing database's directory and the
current working directory. Do not recurse. Deduplicate paths. Discover
`*.db` and `*.pickle.db` by suffix only; a matching suffix is not proof the
file is a SnapshotDB. Do not auto-select by name, size, or mtime. Even a
single candidate requires an explicit user choice.
2. Ask the user to use one listed candidate or to treat pickle import as a
separate trusted-input decision. With zero candidates, ask for a valid
SnapshotDB path or explain that trusted import. Do not run `pt-snap import`
and do not persist focus.
3. Before the user confirms a path, do not run diagnostic queries, reports, or
metadata against any candidate, and do not inspect candidates with Python,
the `sqlite3` CLI, or hand-assembled SQL.
4. After the user confirms a path, the next inspect step is
`pt-snap metadata "<db_path>" --json`. Do not start with `pt-snap query`.
Re-resolve the device from the confirmed database; do not inherit the
focused device from the missing target. Then continue the checks below. A
schema-valid legacy database may report metadata status `unavailable` with
reason `metadata_missing`; record unknown import provenance and do not force
a re-import. Stop on schema errors or invalid metadata.

### 3. Verify metadata and required templates before diagnosis

Run these checks before any diagnostic query:
Expand Down Expand Up @@ -181,7 +211,9 @@ the result retained memory.
Packaged templates expose ordered event rows and same-event gaps at peak events,
but they do not aggregate segment operation counts/sizes or locate maximum gaps
over the full runtime range. Only when one of those aggregates is needed, and
only when the `sqlite3` CLI is available, use this read-only fallback. Scope
only when the `sqlite3` CLI is available, use this read-only fallback. This
read-only aggregate fallback applies only after a confirmed SnapshotDB path. It
is not available during missing-focus recovery. Scope
these aggregates to the same validated range: substitute `<range_start>` for
the literal `0` in the predicates below, and append `AND id <= <range_end>` to
every statement when the scope has a validated upper bound.
Expand Down
11 changes: 10 additions & 1 deletion skills/pt-snap-memory-leak/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,12 +50,21 @@ If the user did not provide a database or device, inspect the current state:
pt-snap focus
```

Use the displayed database and focused device only when both are present and the user has not requested another target. If the database or device remains ambiguous, ask the user to select it before analysis.
Use the displayed database and focused device only when both are present, the database file exists, and the user has not requested another target. If the database or device remains ambiguous, ask the user to select it before analysis.

Do not run `pt-snap focus <database_path>` or otherwise persist focus from this skill. Pass the database and device explicitly to every diagnostic query.

This skill accepts SnapshotDB files only. Do not run `pt-snap import` or deserialize a pickle snapshot. If the user has only a pickle file, stop and explain that importing requires a separate, explicit trusted-input decision because pickle loading is not a sandbox.

#### Missing focus target with sibling candidates

Enter this recovery branch only when diagnosis depends on the current effective focus (environment variable, project `.pt-snap/focus.json`, or global config) and that database file is missing. A displayed path or exit code 0 from `pt-snap focus` does not mean the target is usable; text mode prints `Warning: Database file does not exist!` and `pt-snap focus --json` reports `db_exists: false`. If the user already supplied a valid database path, use that explicit path and do not enter this branch.

1. List candidate files only in the missing database's directory and the current working directory. Do not recurse. Deduplicate paths. Discover `*.db` and `*.pickle.db` by suffix only; a matching suffix is not proof the file is a SnapshotDB. Do not auto-select by name, size, or mtime. Even a single candidate requires an explicit user choice.
2. Ask the user to use one listed candidate or to treat pickle import as a separate trusted-input decision. With zero candidates, ask for a valid SnapshotDB path or explain that trusted import. Do not run `pt-snap import` and do not persist focus.
3. Before the user confirms a path, do not run diagnostic queries, reports, or metadata against any candidate, and do not inspect candidates with Python, the `sqlite3` CLI, or hand-assembled SQL.
4. After the user confirms a path, the next inspect step is `pt-snap metadata '<db_path>' --json`. Do not start with `pt-snap query`. Re-resolve the device from the confirmed database; do not inherit the focused device from the missing target. Then continue the checks below. A schema-valid legacy database may report metadata status `unavailable` with reason `metadata_missing`; record unknown import provenance and do not force a re-import. Stop on schema errors or invalid metadata.

### 3. Verify capabilities and the database in two calls

Run:
Expand Down
36 changes: 33 additions & 3 deletions skills/pt-snap-memory-peak-breakdown/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,9 @@ Require one coherent database/device pair:
- Prefer a database path and device ID explicitly supplied by the user.
- Otherwise, run `pt-snap focus` with no arguments to read the current database
and focused device. This invocation is read-only.
- If either value is absent, ask the user for it and stop. Do not silently select
the first device, combine an explicit database with an unrelated focused
device, or persist new focus.
- If either value is absent, or the effective focus path is missing on disk,
ask the user for it and stop. Do not silently select the first device, combine
an explicit database with an unrelated focused device, or persist new focus.
- Normalize the selected values as `<DB>` and `<DEVICE>`, then substitute them
into every analysis command. Every executable `report` or `query` command must
pass both the database and device explicitly.
Expand Down Expand Up @@ -78,6 +78,36 @@ Use the explicit pair or the read-only current-focus lookup described above.
Never run `pt-snap focus` with a database, `--device`, `--session`, or `--global`.
Never run `pt-snap import` or `pt-snap split`.

#### Missing focus target with sibling candidates

Enter this recovery branch only when diagnosis depends on the current effective
focus (environment variable, project `.pt-snap/focus.json`, or global config)
and that database file is missing. A displayed path or exit code 0 from
`pt-snap focus` does not mean the target is usable; text mode prints
`Warning: Database file does not exist!` and `pt-snap focus --json` reports
`db_exists: false`. If the user already supplied a valid database path, use that
explicit path and do not enter this branch.

1. List candidate files only in the missing database's directory and the
current working directory. Do not recurse. Deduplicate paths. Discover
`*.db` and `*.pickle.db` by suffix only; a matching suffix is not proof the
file is a SnapshotDB. Do not auto-select by name, size, or mtime. Even a
single candidate requires an explicit user choice.
2. Ask the user to use one listed candidate or to treat pickle import as a
separate trusted-input decision. With zero candidates, ask for a valid
SnapshotDB path or explain that trusted import. Do not run `pt-snap import`
and do not persist focus.
3. Before the user confirms a path, do not run diagnostic queries, reports, or
metadata against any candidate, and do not inspect candidates with Python,
the `sqlite3` CLI, or hand-assembled SQL.
4. After the user confirms a path, the next inspect step is
`pt-snap metadata "<DB>" --json`. Do not start with `pt-snap query`.
Re-resolve the device from the confirmed database; do not inherit the
focused device from the missing target. Then continue the checks below. A
schema-valid legacy database may report metadata status `unavailable` with
reason `metadata_missing`; record unknown import provenance and do not force
a re-import. Stop on schema errors or invalid metadata.

### 3. Verify SnapshotDB metadata

Run with the resolved absolute database path:
Expand Down
29 changes: 29 additions & 0 deletions src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,35 @@ A SnapshotDB is a pt-snap SQLite database (typically `.db`) with a
4. Do not run `pt-snap focus <database_path>` to persist a new focus from this
skill. Diagnostic skills may read the current focus with no arguments.

#### Missing focus target with sibling candidates

Enter this recovery branch only when the next diagnostic skill would depend on
the current effective focus (environment variable, project `.pt-snap/focus.json`,
or global config) and that database file is missing. A displayed path or exit
code 0 from `pt-snap focus` does not mean the target is usable; text mode prints
`Warning: Database file does not exist!` and `pt-snap focus --json` reports
`db_exists: false`. If the user already supplied a valid database path, use that
explicit path and do not enter this branch.

1. List candidate files only in the missing database's directory and the current
working directory. Do not recurse. Deduplicate paths. Discover `*.db` and
`*.pickle.db` by suffix only; a matching suffix is not proof the file is a
SnapshotDB. Do not auto-select by name, size, or mtime. Even a single
candidate requires an explicit user choice.
2. Ask the user to use one listed candidate or to treat pickle import as a
separate trusted-input decision. With zero candidates, ask for a valid
SnapshotDB path or explain that trusted import. Do not run `pt-snap import`
and do not persist focus.
3. Before the user confirms a path, do not run diagnostic queries, reports, or
metadata against any candidate, and do not inspect candidates with Python,
the `sqlite3` CLI, or hand-assembled SQL.
4. After the user confirms a path, hand off to the matching diagnostic skill
with that explicit database path. Tell it that the next inspect step is
`pt-snap metadata '<db_path>' --json`, not `pt-snap query`. Do not inherit
the focused device from the missing target; the diagnostic skill must
re-resolve device from the confirmed database. This helper must not run
metadata, query, import, or persist focus.

This helper may mention that `pt-snap overview '<db_path>' --json` and
`pt-snap capabilities --json` exist. Running those orientation commands
belongs to the diagnostic skill. Do not import pickle or persist focus.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -58,9 +58,9 @@ If either input was not supplied, inspect the current state:
pt-snap focus
```

Use the displayed database and focused device only when both are present. If
either remains absent or ambiguous, ask the user to select it and stop until it
is explicit. Do not run `pt-snap focus <database_path>`, use `--session`, or
Use the displayed database and focused device only when both are present and
the database file exists. If either remains absent or ambiguous, ask the user
to select it and stop until it is explicit. Do not run `pt-snap focus <database_path>`, use `--session`, or
otherwise persist or modify focus. After resolving the scope, pass both the
database and device explicitly to every diagnostic query and report command.

Expand All @@ -69,6 +69,36 @@ pickle, or deserialize a pickle. If only a pickle is available, stop and explain
that conversion requires a separate trusted-input decision because pickle
loading is not a sandbox.

#### Missing focus target with sibling candidates

Enter this recovery branch only when diagnosis depends on the current effective
focus (environment variable, project `.pt-snap/focus.json`, or global config)
and that database file is missing. A displayed path or exit code 0 from
`pt-snap focus` does not mean the target is usable; text mode prints
`Warning: Database file does not exist!` and `pt-snap focus --json` reports
`db_exists: false`. If the user already supplied a valid database path, use that
explicit path and do not enter this branch.

1. List candidate files only in the missing database's directory and the
current working directory. Do not recurse. Deduplicate paths. Discover
`*.db` and `*.pickle.db` by suffix only; a matching suffix is not proof the
file is a SnapshotDB. Do not auto-select by name, size, or mtime. Even a
single candidate requires an explicit user choice.
2. Ask the user to use one listed candidate or to treat pickle import as a
separate trusted-input decision. With zero candidates, ask for a valid
SnapshotDB path or explain that trusted import. Do not run `pt-snap import`
and do not persist focus.
3. Before the user confirms a path, do not run diagnostic queries, reports, or
metadata against any candidate, and do not inspect candidates with Python,
the `sqlite3` CLI, or hand-assembled SQL.
4. After the user confirms a path, the next inspect step is
`pt-snap metadata "<db_path>" --json`. Do not start with `pt-snap query`.
Re-resolve the device from the confirmed database; do not inherit the
focused device from the missing target. Then continue the checks below. A
schema-valid legacy database may report metadata status `unavailable` with
reason `metadata_missing`; record unknown import provenance and do not force
a re-import. Stop on schema errors or invalid metadata.

### 3. Verify metadata and required templates before diagnosis

Run these checks before any diagnostic query:
Expand Down Expand Up @@ -181,7 +211,9 @@ the result retained memory.
Packaged templates expose ordered event rows and same-event gaps at peak events,
but they do not aggregate segment operation counts/sizes or locate maximum gaps
over the full runtime range. Only when one of those aggregates is needed, and
only when the `sqlite3` CLI is available, use this read-only fallback. Scope
only when the `sqlite3` CLI is available, use this read-only fallback. This
read-only aggregate fallback applies only after a confirmed SnapshotDB path. It
is not available during missing-focus recovery. Scope
these aggregates to the same validated range: substitute `<range_start>` for
the literal `0` in the predicates below, and append `AND id <= <range_end>` to
every statement when the scope has a validated upper bound.
Expand Down
Loading
Loading