pstack运行时取证与追踪取证：诊断内存泄漏与CPU空转-育师

pstack运行时取证与追踪取证：诊断内存泄漏与CPU空转

【免费下载链接】pstack-claudeClaude Code, Codex, Copilot, Pi, OpenCode, Gemini, and Prime Agent versions of Poteto's pstack. Rigorous agent workflows with Cursor primitives translated for other harnesses.项目地址: https://gitcode.com/GitHub_Trending/ps/pstack-claude

pstack是把 Poteto 的严谨 Agent 工作流移植到 Claude Code、Codex 和 Pi 的开源技能栈。除了修 Bug 和写功能，它最被低估的能力是运行时取证（Runtime forensics）与追踪取证（Trace forensics）：前者对着活着的进程抓 CPU 空转和内存泄漏的现场，后者解剖已经存在的 cpuprofile、heap snapshot、spindump 等性能工件。两者共同点只有一个——交付物是带引用的诊断，而不是拍脑袋的修复。

🔍 为什么是"取证"，而不是"读代码猜原因"

排查性能问题时最常见的误区是：打开源码，凭直觉说"大概是这里慢"。pstack 的两个取证 playbook 明确反其道而行：

诊断由你负责。去给活进程插桩取证，别对着源码空想。（runtime-forensics.md）

原因很简单：猜测没有证据链，无法复现，也无法说服别人。取证式诊断要求每一步都有工件（artifact）背书——CPU profile、heap snapshot、trace 文件，最后把热路径映射回具体的文件、符号和行号。

🖥️ 运行时取证：给"活的进程"插桩

适用场景：进程正在泄漏内存、CPU 持续空转、界面莫名闪烁，而现场还活着。

playbook（plugins/pstack/skills/poteto-mode/playbooks/runtime-forensics.md）的核心五步：

抓活信号：CPU 空转抓 CPU profile，内存泄漏抓 heap snapshot，视觉故障抓 CDP trace——要真实工件，不是猜测；
压缩到"决定性证据"：热点函数、从泄漏对象到 GC 根的保留者链（retainer chain）、无输入却在自转的循环。大工件交给子代理解析（呼应 principle-guard-the-context-window 原则），主线只保留浓缩结论；
先证明机制再相信它：通过 CDP eval 往运行中的进程注入插桩，或不重新加载直接热修代码，低成本验证假设；
映射回源码：文件、符号、分配或调度发生的那一行；
回复格式：捕获了什么信号、浓缩结论、如何证明机制、源码位置、工件路径——没人要求就不给修复方案。

📦 追踪取证：解剖"死后"的性能工件

适用场景：同事或监控系统已经留下了 cpuprofile、.json.gztrace、spindump 或 heap snapshot，你手里只有文件。

trace-forensics.md 与运行时取证的关键区别是：工件是固定数据集，只读，不要重跑。流程是：

识别格式，选对工具：cpuprofile 用 DevTools 或 trace 解析器，spindump 用文本编辑器，heap snapshot 用堆分析工具；
转成可查询形态：把 trace 或堆快照 dump 进 sqlite——一个样本、帧或节点一行，先达到可查询状态再阅读；
收窄到原因：查询占用时间最多的帧，沿调用树走到热路径；内存泄漏则沿保留者链追到 GC 根；spindump 则找卡住或被阻塞的线程及等待原因；
归因到源码：用工件自带符号把热帧映射到文件、符号、行号。没有源码映射的帧还不算诊断；
有配对工件就做前后对比；没有配对就把结论明确标注为"工件支持的最强假设"，而非已确认原因；
只交付带引用的诊断，找到原因后再路由给 Bug fix 或 Perf issue。

🆚 一张表看懂两种取证

维度	运行时取证	追踪取证
对象	正在运行的进程	已存在的工件文件
动作	插桩、注入、热修验证	加载、转换、查询、只读
内存泄漏手段	抓 heap snapshot + 保留者链	解析 heapsnapshot，追 GC 根
CPU 空转手段	抓 CPU profile	解析 cpuprofile/spindump
交付物	带引用的诊断，不修	带引用的诊断，不修

🚀 从诊断到修复：与 Perf issue 衔接

找到原因只是开始。pstack 的 perf-issue.md playbook 接管修复环节，核心纪律是：每个修复都要绑定一次测量。它会按顺序尝试"性能咒语"——能不做的不做 → 做但别重复做 → 少做 → 延后做 → 别人不看时做 → 并发做 → 更便宜地做——前面某条达标就停。

而每个数字都要过 benchmark-checklist 这道关卡：先回答"为什么不能快两倍"（找出限流器）、是否两侧同调优、是否撞了物理上限、有无错误混入、能否复现（至少 5 轮交替跑）、端到端是否真的有意义、工作是否真的发生了。配合 principle-explain-the-number 原则：报得出数字，也要报得出它的边界条件（运行次数、离散范围、限流器）。

想进一步追问"这段防御性代码为什么当初要这么写"，还可以路由到 why 技能，并行查询源码历史、工单、文档、聊天记录等多类证据源。

⚙️ 快速上手

在 Claude Code 中安装插件：
```
/plugin marketplace add michael-denyer/pstack-claude /plugin install pstack@pstack-claude
```
Codex、Pi 等其他运行时的安装方式见 docs/reference.md。
用一句自然语言触发，例如："用 poteto-mode 帮我诊断为什么这个进程内存一直涨"。入口技能 poteto-mode 会自动匹配到对应的取证 playbook 并逐步执行；
运行/pstack:setup-pstack可为不同角色配置模型与推理深度，如给取证角色配fable @xhigh。