Skip to content

feat: add pt-snap memory peak breakdown skill - #108

Merged
codeasier merged 3 commits into
mainfrom
feat/skill-memory-peak-breakdown
Aug 24, 2026
Merged

codeasier merged 3 commits into
mainfrom
feat/skill-memory-peak-breakdown

Conversation

@codeasier

@codeasier codeasier commented Aug 23, 2026 •

Copy link
Copy Markdown
Owner

📝 Description

  • Add a repository-shipped pt-snap-memory-peak-breakdown skill for read-only, point-in-time peak attribution.
  • Cover full-trace and bounded event-range workflows using the existing peak report and query templates.
  • Document attribution limits so allocator gaps are not overclaimed as leaks, fragmentation, or OOM causes.
  • Add static contract tests and update agent navigation.

Review follow-up (73c371f):

  • Classify blocks without a captured allocation event as preexisting_live_at_event in both point-in-time attribution templates.
  • Exempt static and preexisting callstack groups from top_n truncation.
  • Harden the skill against shell interpolation of placeholders and untrusted database content, require output-record checks for template preflight, and qualify negative event-ID semantics.

🔗 Related Issue

Fixes #106

🧪 Testing

  • Tests added/updated
  • Manual testing completed

Commands:

PYTHONPATH=src pytest
ruff check .
black --check .

Results: 714 passed, 1 xfailed; lint and formatting checks passed on b458e3c and 73c371f.

✅ Checklist

  • Code follows project guidelines
  • Documentation updated (if applicable)
  • No new warnings introduced
  • Changes tested locally

Snapshot Runtime Provenance

  • Snapshot provenance evaluation completed when snapshot runtime files change
    Snapshot provenance decision: no-update
    Snapshot provenance no-update reason: This PR adds an agent skill, query-template attribution fixes, docs, tests, and navigation updates; no file under src/pt_snap_cli/snapshot/ is created, modified, or deleted.

📸 Screenshots (if applicable)

Not applicable.

📋 Additional Notes

This workflow builds on the peak-memory report and templates delivered by #62 and #63. The --template-info nonzero-exit-code behavior change is tracked separately in #112.

…wn skill

- Classify blocks without a captured allocation event as
  preexisting_live_at_event in active_blocks_at_event and
  active_memory_callstack_at_event so live pre-trace memory is no longer
  excluded from point-in-time attribution.
- Exempt static and preexisting callstack groups from top_n truncation so
  the required composition sections always carry their bytes and counts.
- Require placeholder integer validation, metacharacter rejection, and
  argument-array execution in the peak-breakdown skill.
- Treat database-derived strings as inert data and require template-info
  output records instead of exit codes, since missing templates exit 0.
- Qualify event-ID ordering for negative synthetic initial-state events.
@codeasier

Copy link
Copy Markdown
Owner Author

验收结论:73c371f 已逐条闭环 6 项行内意见,本地与 CI 均通过。

已验收并 Resolve 的 6 项:

  • High SKILL.md:159 preexisting live 漏算 — 模板新增 preexisting_live_at_event 归类并复用 include_static,active_blocks_at_event/active_memory_callstack_at_event 与 en/zh 文档同步,测试覆盖 freed-after / freed-by / NULL-free / static-disabled 及 callstack 聚合。
  • Medium SKILL.md:69 命令替换 — 新增 Placeholder safety:数值占位符 ^[0-9]+$ 校验、<DB> 拒收引号/$/反引号等元字符、优先参数数组。
  • Medium SKILL.md:199 静态截断 — callstack 模板对 dynamic 单独 ranked CTE 再与 static/preexisting UNION,百分比在合并窗口计算。
  • Medium SKILL.md:179/257 数据库字符串不可信 — Guardrails/Evidence 均声明惰性数据、禁止执行。
  • Low SKILL.md:39 事件 ID 时序 — 区分为非负时序 / 负合成初始态。
  • Low SKILL.md:89 预检退出码 — 改为校验 Template: <name> 输出;CLI 改非 0 按回复另案 [BUG] query --template-info 对缺失模板仍返回退出码 0 #112 跟踪。

验证: PYTHONPATH=src pytest 714 passed/1 xfailed;gh checks 4 Python 版本 + lint + provenance 均为 success。6 条 review threads 已 Resolve。

遗留观察(非阻断): DeepSeek 提及的空区间 memory_peak 返回单行 NULL 需在 Event-Range Workflow 中显式 gate 再进入 point-in-time 归因的提示,当前仅在 Output Contract 中覆盖,工作流小节未回链;建议后续在 SKILL.md:144 附近补一句“若三峰事件 ID 均为 NULL 则报告无峰值且不执行归因”。

Repeat the NULL/empty-range guard inside the Event-Range Workflow so the
stop condition is visible where range peaks are read, not only in the
output contract.
@codeasier

Copy link
Copy Markdown
Owner Author

跟进验收 8c9f6d7:仅剩的非阻断观察已闭环。

  • Event-Range Workflow 现对空区间显式守门(SKILL.md:163-169):任一 bounded 结果无行、或峰值/事件 ID 为 NULL 时停止并报告无峰值事件,禁止伪造事件 ID、禁止替换全跟踪值、禁止执行归因命令。与实现一致——memory_peak/allocator_gap 对空区间返回单行 NULL 而非零行,文档两种情况都已覆盖。
  • test_range_fallback_and_peak_event_semantics_are_explicit 新增 3 条断言锁定该段落。

验证: 本地 PYTHONPATH=src pytest 714 passed/1 xfailed;8c9f6d7 CI 全绿(Python 3.10-3.13、Lint & Format、Snapshot provenance)。

至此本 PR 的 6 项行内意见与 1 项遗留观察全部验收完毕,无残余阻断项。

@codeasier
codeasier merged commit 6a8e384 into main Aug 24, 2026
6 checks passed
@codeasier
codeasier deleted the feat/skill-memory-peak-breakdown branch October 3, 2026 19:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FEATURE] 提供峰值内存拆解诊断 Skill

1 participant