From 61633dd2ac9713574baa314e304fa5f8cdf152cd Mon Sep 17 00:00:00 2001 From: codeasier Date: Sat, 19 Sep 2026 12:16:50 +0800 Subject: [PATCH 1/5] feat(cli): add --json to remaining commands with a stable error contract Agents need parseable success and failure on focus, import, split, query, and config. JSON failures write structured codes to stderr with empty stdout; text mode keeps Error: on stdout. --- CHANGELOG.md | 13 + README.md | 2 +- README_zh.md | 2 +- docs/en/database.md | 5 + docs/en/focus-management.md | 5 + docs/en/querying.md | 42 +- docs/en/skills.md | 2 +- docs/en/splitting.md | 6 +- docs/zh/database.md | 5 + docs/zh/focus-management.md | 5 + docs/zh/querying.md | 39 +- docs/zh/skills.md | 2 +- docs/zh/splitting.md | 5 +- skills/AGENTS.md | 2 +- skills/pt-snap-helper/SKILL.md | 25 +- .../bundled_skills/pt-snap-helper/SKILL.md | 25 +- src/pt_snap_cli/cli.py | 362 +++++++++++--- src/pt_snap_cli/core/AGENTS.md | 2 + src/pt_snap_cli/core/__init__.py | 16 + src/pt_snap_cli/core/error_codes.py | 112 +++++ src/pt_snap_cli/core/json_codec.py | 66 +++ tests/AGENTS.md | 1 + tests/core/AGENTS.md | 1 + tests/core/test_json_codec.py | 79 +++ tests/skills/test_helper_contract.py | 20 +- tests/test_cli_json.py | 467 ++++++++++++++++++ tests/test_contract_cli_api.py | 83 ++++ 27 files changed, 1297 insertions(+), 97 deletions(-) create mode 100644 src/pt_snap_cli/core/error_codes.py create mode 100644 src/pt_snap_cli/core/json_codec.py create mode 100644 tests/core/test_json_codec.py create mode 100644 tests/test_cli_json.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 21e8cca..a78936d 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`),退出码非零。 +- `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` 成功字段保持兼容,不包进新信封。它们在 `--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..99b87a0 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` accept `--json`. ## Agent Skills diff --git a/README_zh.md b/README_zh.md index fb6fcb1..a802b8d 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` 均接受 `--json`。 ## Agent Skills diff --git a/docs/en/database.md b/docs/en/database.md index f6a3e1b..ee8a023 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`, `reused`, `cache_miss_reason`, `metadata`, and +`focus_state`. `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..a451d93 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`, and `db_exists`. `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..d970e8a 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