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: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,18 @@
# Changelog

## [0.5.0] - Unreleased

### 新增

- `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。

### 兼容性提示

- 文本模式保持原样:人类可读输出不变,`_error()` 与查询/报告说明行仍写 stdout。缺失模板的 `query --template-info` 已在 0.4.0 以退出码 1 失败。数据库无设备时,文本模式查询仍退出 0;JSON 模式改为 `DEVICE_NOT_FOUND` 且退出码非零。
- 已有 `metadata --json`、`report peak-memory --json` 与 `skill list/install/upgrade/uninstall --json` 成功字段保持兼容,不包进新信封。它们在 `--json` 失败时改走 stderr 错误信封。

## [0.4.0] - Unreleased

相对 v0.3.0:关闭 MCP 产品面,Agent 集成入口收敛到 bundled skills 与 CLI;并补上 helper 引导技能、查询参数白名单,以及易误读字段的语义元数据。本段覆盖 `v0.3.0` 之后已合入 `main` 的全部用户可见变更。
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough.
| `pt-snap config` | Manage global configuration |
| `pt-snap skill` | List and install bundled agent skills |

`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`.
`pt-snap --help` includes an agent hint: prefer `--json` on the command that supports it, start with the `pt-snap-helper` skill, and check availability with `pt-snap skill list --json`. `focus`, `import`, `split`, `query`, `config`, `metadata`, `report peak-memory`, and `skill list/install/upgrade/uninstall` accept `--json`.

## Agent Skills

Expand Down
2 changes: 1 addition & 1 deletion README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ pt-snap split snapshot.pkl --slices 4 --output snapshot-slices
| `pt-snap config` | 管理全局配置 |
| `pt-snap skill` | 列出并安装随包 agent skill |

`pt-snap --help` 含 Agent 提示:在当前已支持的命令上优先使用 `--json`,从 `pt-snap-helper` skill 开始,并用 `pt-snap skill list --json` 检查是否已安装。
`pt-snap --help` 含 Agent 提示:在支持该选项的命令上优先使用 `--json`,从 `pt-snap-helper` skill 开始,并用 `pt-snap skill list --json` 检查是否已安装。`focus`、`import`、`split`、`query`、`config`、`metadata`、`report peak-memory` 和 `skill list/install/upgrade/uninstall` 均接受 `--json`。

## Agent Skills

Expand Down
5 changes: 5 additions & 0 deletions docs/en/database.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ SnapshotDB is the SQLite database format for persisting PyTorch memory profiling

```bash
pt-snap import snapshot.pkl
pt-snap import snapshot.pkl --json
```

The import command uses pt-snap-cli's first-party snapshot runtime to produce `snapshot.pkl.db` next to the input file by default, then updates project focus so subsequent commands can use it directly:
Expand All @@ -48,6 +49,10 @@ pt-snap metadata snapshot.pkl.db --json
pt-snap import snapshot.pkl --force
```

`import --json` reports `db_path`, `device_id`, `reused`, `cache_miss_reason`,
`metadata`, `focus_state`, and top-level `focus_source`. `metadata --json` keeps its existing field names (`db_path`,
`status`, `reason`, `metadata`) for compatibility.

Legacy or externally generated compatible databases without this table remain
queryable for templates that do not require a recognized callstack layout.
`pt-snap` detects the callstack layout from table columns (and treats
Expand Down
5 changes: 5 additions & 0 deletions docs/en/focus-management.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,8 @@ pt-snap focus

This shows the resolved database path, device ID, and where they came from (project focus, session env, or global config). `pt-snap focus`, `pt-snap focus <db>`, `pt-snap focus --global`, and `pt-snap focus --device` also print `Callstack layout: v1 (inline text)` or `v2 (deduplicated)` when the schema is recognized, or a warning when the layout conflicts. `pt-snap focus --session` prints only the `export PT_SNAP_DB_PATH=...` line so it can be evaluated by the shell. The layout is detected read-only from the database; it is not stored in `.pt-snap/focus.json`.

`--json` covers read, set, device-only, `--global`, and `--session`. The success object includes `schema_version`, `ok`, `action`, `configured`, `db_path`, `focus_source`, `focus_file`, `device_id`, `available_devices`, `callstack_layout`, `callstack_layout_error`, and `db_exists`. Without a database path, `focus --json` still reads the current focus and reports `action: "read"`, including when `--session` or `--global` is also passed; that matches text mode. `focus --session <db> --json` validates the database and returns `session_applied: false` plus `env.name` / `env.value` / `env.export`. It does not print a bare shell line and does not change the parent shell.

## Override Focus

Even with focus configured, you can temporarily specify a different database or device on the command line:
Expand Down Expand Up @@ -85,8 +87,11 @@ pt-snap focus /path/to/your/snapshot.db --global
pt-snap config # View global configuration
pt-snap config --path # Show config file path
pt-snap config --clear # Clear global configuration
pt-snap config --json # Same actions as machine-readable JSON
```

`config` still manages only the legacy global file. `--json` adds `action` (`show` / `path` / `clear`), `path`, and either `config` or `cleared`.

## Focus File Locations

| Scope | File |
Expand Down
57 changes: 56 additions & 1 deletion docs/en/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Run memory analysis queries against your snapshot database.
```bash
pt-snap query [DB_PATH] [--template-use <template_name>] [--params <json>] \
[--device <id>] [--list] [--category <category>] \
[--template-info <template>] [-n <rows>]
[--template-info <template>] [-n <rows>] [--json]
```

**Parameters:**
Expand All @@ -24,6 +24,7 @@ pt-snap query [DB_PATH] [--template-use <template_name>] [--params <json>] \
| `--category` | Filter templates by category: `basic`, `statistical`, `business` |
| `--template-info` | Show template details (parameters, output schema, and field semantics) |
| `-n` | Maximum displayed rows; zero or a negative value means unlimited |
| `--json` | Emit machine-readable JSON (execute, `--list`, and `--template-info`) |

## Query Templates

Expand Down Expand Up @@ -193,6 +194,60 @@ The report command combines:

and prints either a human-readable summary or JSON.

## JSON Output

`--json` writes one JSON object to stdout. Success payloads include
`schema_version` (currently `1`), `ok: true`, and command fields:

| Branch | Extra fields |
|--------|----------------|
| Execute | `db_path`, `focus_source`, `device_id`, `template`, `effective_params`, `semantics_version`, `total`, `returned`, `rows` |
| `--list` | `category`, `templates` (`name`, `description`, `category`) |
| `--template-info` | Template metadata matching `get_template_info()`, plus `template` |

`-n` still caps `rows` and `returned`. `total` remains the untruncated count.
`effective_params` is the validated parameter set after defaults and `choices`
normalization. When `-n` is set, `limit` is the trailing SQL LIMIT after the
same merge the executor applies: `min` of a declared template `limit` and
`-n`, or `-n` appended when the rendered SQL has no trailing LIMIT. Inner
caps such as `top_n` stay their own parameters; they do not rewrite
`limit` when they sit inside a CTE. `--template-info --json` includes
`semantics_version`, `interpretation_limits`, and field semantics from
`output_schema`.

On `--json` failure, stdout is empty. stderr is:
Comment thread
codeasier marked this conversation as resolved.
Resolved

```json
{
"schema_version": 1,
"ok": false,
"error": {
"code": "TEMPLATE_NOT_FOUND",
"message": "Template 'missing' not found",
"hint": "Use 'pt-snap query --list --json' to list available templates."
}
}
```

Stable codes include `TEMPLATE_NOT_FOUND`, `INVALID_PARAMETER`,
`DATABASE_NOT_FOUND`, `DEVICE_NOT_FOUND`, and `FOCUS_NOT_CONFIGURED`. The
exit code is nonzero. Usage and parse errors from the `pt-snap` console
entry (for example `query -n abc --json`) also write this envelope with
`INVALID_PARAMETER` and exit code 2. When Click fails before the `--json`
callback runs, that path is a best-effort argv scan: an exact `--json`
token before `--`, and not the value of the previous option.
`--opt=value` and numeric tokens such as `-1` do not consume the next
argument. The `pt-snap` console entry returns the Typer/Click exit code
(nonzero on failure). Ctrl-C / EOF write `Aborted!` to stderr in text
mode (exit 1, or 130 when Typer returns 130). With `--json`, stdout stays
empty and stderr is this envelope (`ERROR`, message `Aborted!`). Text
mode is unchanged: `Error:` lines still go to stdout (including
missing-template `--template-info`, which already exits 1).

Existing `metadata --json` and `report peak-memory --json` field names stay
compatible. Those commands use the same stderr error envelope when `--json`
is set.

## Output Format

All results are displayed by default. Use `-n` to limit the number of rows shown:
Expand Down
2 changes: 1 addition & 1 deletion docs/en/skills.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

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

`pt-snap-cli` ships agent skills for routing (`pt-snap-helper`), setup, Ascend NPU collection, and memory diagnostics. Agents should start with `pt-snap-helper` and prefer `--json` on commands that currently support it. The `pt-snap skill` commands copy those skills into the shared Agent Skills directory and into host-specific directories that Claude Code still requires.
`pt-snap-cli` ships agent skills for routing (`pt-snap-helper`), setup, Ascend NPU collection, and memory diagnostics. Agents should start with `pt-snap-helper` and prefer `--json` on commands that accept it. The `pt-snap skill` commands copy those skills into the shared Agent Skills directory and into host-specific directories that Claude Code still requires.

## List skills

Expand Down
6 changes: 5 additions & 1 deletion docs/en/splitting.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,8 @@ pt-snap split SNAPSHOT_PATH \
--output OUTPUT_DIRECTORY \
[--device DEVICE_ID] \
(--slices COUNT | --max-entries COUNT) \
[--format pickle|json]
[--format pickle|json] \
[--json]
```

The source must be an existing regular `.pkl` or `.pickle` file. `--output` is
Expand All @@ -34,6 +35,9 @@ Exactly one strategy is required:
| `--max-entries COUNT` | Limit each slice to a positive maximum event count |

`--format` accepts exactly `pickle` or `json` and defaults to `pickle`.
`--json` prints the split inventory on stdout (`output`, `files`, `devices`,
`format`) and is independent of `--format`, which only selects slice file
format.

Exclusive atomic directory publication requires `renamex_np(RENAME_EXCL)` on
Darwin, `renameat2(RENAME_NOREPLACE)` on Linux, or Windows rename semantics.
Expand Down
5 changes: 5 additions & 0 deletions docs/zh/database.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ SnapshotDB 是内存快照数据的 SQLite 数据库存储格式,用于持久

```bash
pt-snap import snapshot.pkl
pt-snap import snapshot.pkl --json
```

默认情况下,内建快照运行时会在输入文件旁生成 `snapshot.pkl.db`,并更新当前项目的
Expand All @@ -44,6 +45,10 @@ pt-snap metadata snapshot.pkl.db --json
pt-snap import snapshot.pkl --force
```

`import --json` 报告 `db_path`、`device_id`、`reused`、`cache_miss_reason`、
`metadata`、`focus_state` 和顶层 `focus_source`。`metadata --json` 保持现有字段名(`db_path`、`status`、`reason`、
`metadata`)以兼容已有调用方。

旧版或外部生成且结构兼容的 DB 仍可查询不依赖可识别调用栈布局的模板。`pt-snap`
根据表列识别调用栈布局,并把 `pt_snap_metadata.import_format_version` 当作辅助
校验,而不是唯一依据。调用栈相关模板会自动选择匹配的 SQL。
Expand Down
5 changes: 5 additions & 0 deletions docs/zh/focus-management.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,8 @@ pt-snap focus

显示已解析的数据库路径、设备 ID 及其来源(项目 focus、session 环境变量或全局配置)。`pt-snap focus`、`pt-snap focus <db>`、`pt-snap focus --global` 和 `pt-snap focus --device` 在识别到调用栈 schema 时还会打印 `Callstack layout: v1 (inline text)` 或 `v2 (deduplicated)`;布局冲突时打印警告。`pt-snap focus --session` 只输出 `export PT_SNAP_DB_PATH=...`,以便被 shell 直接执行。该信息从数据库只读识别,不会写入 `.pt-snap/focus.json`。

`--json` 覆盖读取、设置、仅改设备、`--global` 与 `--session`。成功对象包含 `schema_version`、`ok`、`action`、`configured`、`db_path`、`focus_source`、`focus_file`、`device_id`、`available_devices`、`callstack_layout`、`callstack_layout_error` 和 `db_exists`。未提供数据库路径时,`focus --json` 仍读取当前 focus 并报告 `action: "read"`;同时带 `--session` 或 `--global` 也一样,与文本模式一致。`focus --session <db> --json` 只验证数据库,并返回 `session_applied: false` 以及 `env.name` / `env.value` / `env.export`;不会打印可直接 eval 的裸 shell 行,也不表示已修改父 shell。

## 覆盖焦点

即使已配置 focus,仍可在命令行中临时指定不同的数据库或设备:
Expand Down Expand Up @@ -84,8 +86,11 @@ pt-snap focus /path/to/your/snapshot.db --global
pt-snap config # 查看全局配置
pt-snap config --path # 显示配置文件路径
pt-snap config --clear # 清除全局配置
pt-snap config --json # 同一组操作用机器可读 JSON 输出
```

`config` 仍然只管理 legacy 全局配置文件。`--json` 增加 `action`(`show` / `path` / `clear`)、`path`,以及 `config` 或 `cleared`。

## Focus 文件位置

| 范围 | 文件 |
Expand Down
49 changes: 48 additions & 1 deletion docs/zh/querying.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
```bash
pt-snap query [DB_PATH] [--template-use <template_name>] [--params <json>] \
[--device <id>] [--list] [--category <category>] \
[--template-info <template>] [-n <rows>]
[--template-info <template>] [-n <rows>] [--json]
```

**参数说明:**
Expand All @@ -24,6 +24,7 @@ pt-snap query [DB_PATH] [--template-use <template_name>] [--params <json>] \
| `--category` | 按分类过滤模板:`basic`、`statistical`、`business` |
| `--template-info` | 显示模板详情(参数、输出 schema 和字段语义) |
| `-n` | 最大显示行数;零或负数表示不限制 |
| `--json` | 输出机器可读 JSON(执行、`--list` 与 `--template-info`) |

## 查询模板

Expand Down Expand Up @@ -185,6 +186,52 @@ pt-snap report peak-memory /path/to/snapshot.db --json

并输出人类可读摘要或 JSON。

## JSON 输出

`--json` 向 stdout 写一个 JSON 对象。成功结果包含 `schema_version`(当前为 `1`)、
`ok: true` 以及命令字段:

| 分支 | 额外字段 |
|------|----------|
| 执行 | `db_path`、`focus_source`、`device_id`、`template`、`effective_params`、`semantics_version`、`total`、`returned`、`rows` |
| `--list` | `category`、`templates`(`name`、`description`、`category`) |
| `--template-info` | 与 `get_template_info()` 对齐的模板元数据,另加 `template` |

`-n` 仍然限制 `rows` 与 `returned`。`total` 仍是未截断的总数。
`effective_params` 是应用默认值并按 `choices` 规范化后的参数。带 `-n` 时,
`limit` 是与执行器相同的**尾部** SQL `LIMIT`:已声明的模板 `limit` 与 `-n`
取较小值;渲染后的 SQL 没有尾部 `LIMIT` 时追加 `-n`。CTE 内部的 `top_n`
仍是独立参数,不会改写 `limit`。
`--template-info --json` 包含 `semantics_version`、`interpretation_limits`
以及 `output_schema` 上的字段语义。

`--json` 失败时 stdout 为空,stderr 为:

```json
{
"schema_version": 1,
"ok": false,
"error": {
"code": "TEMPLATE_NOT_FOUND",
"message": "Template 'missing' not found",
"hint": "Use 'pt-snap query --list --json' to list available templates."
}
}
```

稳定错误码包括 `TEMPLATE_NOT_FOUND`、`INVALID_PARAMETER`、
`DATABASE_NOT_FOUND`、`DEVICE_NOT_FOUND` 和 `FOCUS_NOT_CONFIGURED`,退出码非零。
`pt-snap` 控制台入口的用法/解析错误(例如 `query -n abc --json`)也走同一信封,
错误码为 `INVALID_PARAMETER`,退出码 2。Click 在 `--json` 回调之前失败时,
该路径是 best-effort 的 argv 扫描:`--` 之前的精确 `--json` 词,且不是前一个
选项的值。`--opt=value` 与 `-1` 这类数字词不会吞掉下一个参数。
`pt-snap` 控制台入口返回 Typer/Click 的退出码(失败非零)。Ctrl-C / EOF
在文本模式向 stderr 写 `Aborted!`(退出码 1;Typer 返回 130 时为 130)。
带 `--json` 时 stdout 仍为空,stderr 为本信封(`ERROR`,message 为 `Aborted!`)。
文本模式保持不变:`Error:` 仍写到 stdout(包括缺失模板的 `--template-info`,它已经以退出码 1 失败)。

已有的 `metadata --json` 与 `report peak-memory --json` 字段名保持兼容。这两条命令在带 `--json` 失败时也使用同一套 stderr 错误信封。

## 输出格式

默认情况下显示所有结果。使用 `-n` 限制显示行数:
Expand Down
2 changes: 1 addition & 1 deletion docs/zh/skills.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

[English](../en/skills.md) | 中文

`pt-snap-cli` 附带用于路由(`pt-snap-helper`)、环境安装、昇腾 NPU 采集和内存诊断的 agent skill。Agent 应先使用 `pt-snap-helper`,并在当前已支持的命令上优先使用 `--json`。`pt-snap skill` 命令会把这些 skill 复制到共享的 Agent Skills 目录,以及 Claude Code 仍然需要的独立目录。
`pt-snap-cli` 附带用于路由(`pt-snap-helper`)、环境安装、昇腾 NPU 采集和内存诊断的 agent skill。Agent 应先使用 `pt-snap-helper`,并在支持 `--json` 的命令上优先使用该选项。`pt-snap skill` 命令会把这些 skill 复制到共享的 Agent Skills 目录,以及 Claude Code 仍然需要的独立目录。

## 列出 skill

Expand Down
5 changes: 4 additions & 1 deletion docs/zh/splitting.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@ pt-snap split SNAPSHOT_PATH \
--output OUTPUT_DIRECTORY \
[--device DEVICE_ID] \
(--slices COUNT | --max-entries COUNT) \
[--format pickle|json]
[--format pickle|json] \
[--json]
```

源文件必须是已存在的普通 `.pkl` 或 `.pickle` 文件。`--output` 必须提供;其父目录必须
Expand All @@ -30,6 +31,8 @@ pt-snap split SNAPSHOT_PATH \
| `--max-entries COUNT` | 将每个切片的最大事件数限制为正数 `COUNT` |

`--format` 只接受 `pickle` 或 `json`,默认值为 `pickle`。
`--json` 向 stdout 打印分片清单(`output`、`files`、`devices`、`format`),
与只控制分片文件格式的 `--format` 相互独立。

排他原子目录发布在 Darwin 上依赖 `renamex_np(RENAME_EXCL)`,在 Linux 上依赖
`renameat2(RENAME_NOREPLACE)`,Windows 使用其重命名语义。不支持的平台或缺少所需
Expand Down
2 changes: 1 addition & 1 deletion skills/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ install or upgrade, the host agent must be restarted.

## Focused Tests
- Run `pytest tests/skills/test_helper_contract.py` after helper-skill changes.
Static coverage checks routing names, current `--json` capability, skill-list
Static coverage checks routing names, command `--json` coverage, skill-list
availability, and the pickle/focus/install read-only boundary.
- Run `pytest tests/skills/test_setup_contract.py` after setup-skill changes. The current executable test covers active-interpreter path preservation; review the remaining approval and reporting instructions statically.
- Run `pytest tests/skills/test_ascend_npu_collect_contract.py` after
Expand Down
Loading
Loading