diff --git a/CHANGELOG.md b/CHANGELOG.md index 21e8cca..f6cde3b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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` 的全部用户可见变更。 diff --git a/README.md b/README.md index 2d93f1f..026d87a 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/README_zh.md b/README_zh.md index fb6fcb1..72e24f1 100644 --- a/README_zh.md +++ b/README_zh.md @@ -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 diff --git a/docs/en/database.md b/docs/en/database.md index f6a3e1b..ef339f8 100644 --- a/docs/en/database.md +++ b/docs/en/database.md @@ -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: @@ -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 diff --git a/docs/en/focus-management.md b/docs/en/focus-management.md index 183b859..4775e99 100644 --- a/docs/en/focus-management.md +++ b/docs/en/focus-management.md @@ -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 `, `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 --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: @@ -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 | diff --git a/docs/en/querying.md b/docs/en/querying.md index f534676..193c93b 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