Skip to content
Merged
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
42 changes: 15 additions & 27 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,32 +1,8 @@
# Changelog

## [0.5.0] - Unreleased
## [0.4.0] - 2026-09-24

### 新增

- 新增 `pt-snap capabilities`:一次输出 CLI 版本、全部查询模板/参数契约(含字段语义)和技能清单。`--json` 使用 #138 成功信封,替代逐个 `--template-info` 探测。
- 新增 `pt-snap overview`:只读输出设备列表、各设备首/末 event id,以及导入 metadata 状态。`--json` 使用同一信封;分析路径不写数据库、不持久化 focus。
- 新增 `preexisting_live` 与 `freed_block_lifetime` 查询模板,泄漏技能不再依赖 `sqlite3` CLI 回退。`preexisting_live` 排除 `freeEventId = -1` 的 static 块,与 `active_memory_callstack_at_event` 的 `[preexisting live]` 分组一致。诊断前置探测从 7 次(`metadata` + 六个 `--template-info`)降为 2 次(`capabilities` + `overview`)。helper 引导「先概览、再诊断」。
- `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` 时自动计数。CTE 内有限 `top_n` 在窗口已满时也置 `has_more` / `truncated`,续页靠增大 `top_n` 而不是 `offset` / `-n`。`event` / `block` / `allocation` / `leak_detection` 用 `id` 做稳定分页次序。`--timeout` 与 `PT_SNAP_QUERY_TIMEOUT` 是一次 `QueryService` 调用的共享时限(页面查询与可选 COUNT 共用),并作用于所有模板查询(含 `report peak-memory`);非法环境变量归为 `INVALID_PARAMETER`。诊断 skill 默认有界查询,并按 `has_more` / `truncated` 续页。

### 兼容性提示

- 文本模式保持原样:人类可读输出不变,`_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 错误信封。新的 `capabilities --json` 与 `overview --json` 使用 #138 成功/失败信封。`capabilities` 在技能目录不可读时走 `SKILL_ERROR`;`overview` 把损坏的设备表/边界查询翻译为 `DATABASE_SCHEMA_INVALID`,并把损坏的 focus 文件翻译为 `FOCUS_FILE_INVALID`。
- 查询默认 `total` 不再在触达 `-n` 时自动变成匹配集合 `COUNT`。依赖该旧语义的调用方必须显式传 `--exact-total` / `exact_total=True`。

### 稳定性与工程

- Agent CLI 端到端评估补齐参数纠错、无设备数据库、真实竞争数据库、模板语义与 import focus 信封;post-change 契约任务成功率由 0 提升至 1,错误结论率由 0.8 降至 0,并约束调用与输出预算。
- CI 与 release gate 新增干净 wheel Agent 验收:在隔离 venv 中确认包与 helper 来自 wheel,并仅用结构化输出完成 helper 安装、trusted snapshot import、capabilities、overview 与 peak query。
- basedpyright 对 `src/pt_snap_cli/snapshot/` 与其余包路径同一套 error 门槛:补齐注解后移除 snapshot `executionEnvironments` 降级列表(#122 阶段 3)。

## [0.4.0] - Unreleased

相对 v0.3.0:关闭 MCP 产品面,Agent 集成入口收敛到 bundled skills 与 CLI;并补上 helper 引导技能、查询参数白名单,以及易误读字段的语义元数据。本段覆盖 `v0.3.0` 之后已合入 `main` 的全部用户可见变更。
相对 v0.3.0:关闭 MCP 产品面,Agent 集成入口收敛到 bundled skills 与 CLI;并一次落地 helper、查询参数白名单、字段语义、全命令 `--json`、查询完整性协议,以及 `capabilities` / `overview`。本段覆盖 `v0.3.0` 之后已合入 `main` 的全部用户可见变更。

### 破坏性变更

Expand All @@ -41,6 +17,13 @@
- `--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` 的对外描述改为「捕获范围内无释放完成记录的候选」,不再写成已确认泄漏。
- `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` 透出字段语义。
- 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` 时自动计数。CTE 内有限 `top_n` 在窗口已满时也置 `has_more` / `truncated`,续页靠增大 `top_n` 而不是 `offset` / `-n`。`event` / `block` / `allocation` / `leak_detection` 用 `id` 做稳定分页次序。`--timeout` 与 `PT_SNAP_QUERY_TIMEOUT` 是一次 `QueryService` 调用的共享时限(页面查询与可选 COUNT 共用),并作用于所有模板查询(含 `report peak-memory`);非法环境变量归为 `INVALID_PARAMETER`。诊断 skill 默认有界查询,并按 `has_more` / `truncated` 续页。
- 新增 `pt-snap capabilities`:一次输出 CLI 版本、全部查询模板/参数契约(含字段语义)和技能清单。`--json` 使用同一成功信封,替代逐个 `--template-info` 探测。
- 新增 `pt-snap overview`:只读输出设备列表、各设备首/末 event id,以及导入 metadata 状态。`--json` 使用同一信封;分析路径不写数据库、不持久化 focus。
- 新增 `preexisting_live` 与 `freed_block_lifetime` 查询模板,泄漏技能不再依赖 `sqlite3` CLI 回退。`preexisting_live` 排除 `freeEventId = -1` 的 static 块,与 `active_memory_callstack_at_event` 的 `[preexisting live]` 分组一致。诊断前置探测从 7 次(`metadata` + 六个 `--template-info`)降为 2 次(`capabilities` + `overview`)。helper 引导「先概览、再诊断」。

### 修复

Expand All @@ -57,6 +40,9 @@

- 增加 Agent CLI 端到端评估基线(`tests/skills/suites/pt-snap-agent-e2e`),记录当前 CLI 行为,供后续改造对比;不改变产品 CLI/API。
- 原 CLI/MCP 跨表面契约测试改写为 CLI ↔ `SnapshotAnalyzer`,文件名为 `tests/test_contract_cli_api.py`。
- Agent CLI 端到端评估补齐参数纠错、无设备数据库、真实竞争数据库、模板语义与 import focus 信封;post-change 契约任务成功率由 0 提升至 1,错误结论率由 0.8 降至 0,并约束调用与输出预算。
- CI 与 release gate 新增干净 wheel Agent 验收:在隔离 venv 中确认包与 helper 来自 wheel,并仅用结构化输出完成 helper 安装、trusted snapshot import、capabilities、overview 与 peak query。
- basedpyright 对 `src/pt_snap_cli/snapshot/` 与其余包路径同一套 error 门槛:补齐注解后移除 snapshot `executionEnvironments` 降级列表(#122 阶段 3)。

### 兼容性提示

Expand All @@ -65,7 +51,9 @@
- 拼错或多余的查询参数、以及不在 `choices` 内的 `order_by` / `order_dir` 现在会报错,而不再静默得到错误结果或 SQLite 语法错误。
- 用户自写查询模板若在 `output_schema` 列上使用未登记键,加载会失败;仅含 `column`/`type` 的旧模板仍然有效。`execute_query()` 返回字典新增 `template`、`semantics_version` 键。
- 不带 `--target` / `--project` / `--dir` 的 `pt-snap skill uninstall` 现在会删除 `skill list` 看到的、含有 `SKILL.md` 的全部已安装副本,而不再只检查默认的用户级 `agents` 与 `claude` 目录。需要窄范围卸载时请显式传这些选项。同名但缺少 `SKILL.md` 的路径会让整次卸载失败且零删除。
- 本版本未扩展 `--json` 覆盖面。当前支持 `--json` 的是 `metadata`、`report peak-memory`,以及 `skill list` / `install` / `upgrade` / `uninstall`。`query`、`focus`、`import`、`split`、`config` 仍无 `--json`;`--template-info` 的机器可读形态仍是结构化 API dict 与 CLI 文本。
- 文本模式保持原样:人类可读输出不变,`_error()` 与查询/报告说明行仍写 stdout。缺失模板的 `query --template-info` 改为退出码 1。数据库无设备时,文本模式查询仍退出 0;JSON 模式改为 `DEVICE_NOT_FOUND` 且退出码非零。
- 已有 `metadata --json`、`report peak-memory --json` 与 `skill list/install/upgrade/uninstall --json` 成功字段保持兼容,不包进新信封。它们在 `--json` 失败时改走 stderr 错误信封。新的 `focus` / `import` / `split` / `query` / `config` / `capabilities` / `overview` 的 `--json` 使用成功/失败信封。`capabilities` 在技能目录不可读时走 `SKILL_ERROR`;`overview` 把损坏的设备表/边界查询翻译为 `DATABASE_SCHEMA_INVALID`,并把损坏的 focus 文件翻译为 `FOCUS_FILE_INVALID`。
- 查询默认 `total` 不再在触达 `-n` 时自动变成匹配集合 `COUNT`。依赖该旧语义的调用方必须显式传 `--exact-total` / `exact_total=True`。

## [0.3.0] - 2026-09-17

Expand Down
Loading