Heap Seance

堆灵媒

从堆中召唤被保留的对象——审问那些不肯消亡的对象。

一个 MCP 服务 + 命令行工具包，将 jcmd、jmap、jstat、jfr、Eclipse MAT 和 async-profiler 的能力整合到结构化的内存泄漏调查工作流中，专为在 Claude Code 中运行而设计。

2 个斜杠命令。8 个 MCP 工具。默认采用保守策略。

工作原理 • 快速开始 • MCP 工具 • 工作流 • 前置条件 • 参与贡献

工作原理

Heap Seance 采用两阶段升级模型。只有证据表明有必要时，才进行深入取证。

 /leak-scan                          /leak-deep
     |                                   |
     v                                   v
  3x class histogram               (all of scan, plus)
  + GC pressure snapshot            JFR recording
     |                              heap dump
     v                              MAT leak suspects
  monotonic growth?                 async-profiler alloc profile
  old-gen pressure?                     |
     |                                  v
     +--- both true? -----> auto-escalate to deep
     |
     +--- otherwise ------> verdict + next steps

置信度来自证据，而非假设。 high 至少需要两个相互独立的强信号。单个增长的类标记为 watch。增长加上 GC 压力标记为 suspicious。再加入 MAT 支配树或 JFR 关联信息，即可得出 probable_memory_leak。

快速开始

需要 uv、Python 3.10+ 和用于工具的 JDK 17+（目标应用可以运行任何 Java 版本）。

1. 克隆

git clone https://github.com/your-org/heap-seance.git

2. 将 .mcp.json 添加到 Java 项目

在要调查的项目中创建一个 .mcp.json：

{
  "mcpServers": {
    "heap-seance": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/heap-seance", "python", "-m", "heap_seance_mcp.server"],
      "env": {
        "JAVA_HOME": "/path/to/jdk-17",
        "MAT_BIN": "/path/to/ParseHeapDump.sh",
        "ASYNC_PROFILER_BIN": "/path/to/asprof"
      }
    }
  }
}

--directory 指向你克隆 Heap Seance 的位置。uv run 会自动处理虚拟环境和依赖项。ASYNC_PROFILER_BIN 为可选项——如果缺失，深度模式会继续使用 JFR + MAT。

3. 复制 Claude Code 命令

将 .claude/commands/ 文件夹复制到你的 Java 项目中，即可使用 /leak-scan 和 /leak-deep 斜杠命令：

cp -r /path/to/heap-seance/.claude/commands/ .claude/commands/

4. 运行

/leak-scan my-service        # conservative scan
/leak-deep 12345             # full forensics by PID

Heap Seance 会解析目标进程、收集证据并返回结构化结论。

MCP 工具

每个工具都返回相同的统一架构：

{
  "status": "ok | warn | error",
  "evidence": ["..."],
  "metrics": {},
  "confidence": "none | low | medium | high",
  "next_recommended_action": "...",
  "raw_artifact_path": "..."
}

调查工作流

1. 启动应用，并让它完成初始化。
2. /leak-scan <name-or-pid> — 获取第一份直方图快照。
3. 复现可疑行为 — 扫描会在 3 次直方图采样之间提示你执行怀疑会导致泄漏的操作（打开/关闭视图、发送请求、重复工作流）。这一步至关重要——如果采样之间没有负载，泄漏就不会显现。
4. 查看结论。 重点关注 Confidence、Key Evidence、Suspect Types。
5. 如果扫描发现增长，或无论如何都想进行完整取证，请运行 /leak-deep <name-or-pid>。
6. 修复并重新扫描。 限制缓存大小、使用弱引用、清理监听器——然后再次运行 /leak-scan，确认信号减弱。
7. 保留产物。 .jfr、.hprof 和 MAT 报告会保存下来，供团队审查。

返回内容

/leak-scan 返回：Verdict、Confidence、Key Evidence、Suspect Types、Artifacts、Next Steps。

/leak-deep 会进行更深入的分析：Verdict、Confidence、Root Holder Hypothesis（哪些对象通过什么字段/链保留了不断增长的对象）、Supporting Evidence、Artifacts、Remediation Hypotheses（具体修复建议）、Verification Plan。

置信度等级

前置条件

工具链 JDK（必需）：

• jcmd、jmap、jstat 需要 JDK 17+ — 通过 .mcp.json 中的 JAVA_HOME 设置
• 目标应用可使用任意 Java 版本运行（包括 Java 8）

深度取证（用于 /leak-deep）：

• Eclipse MAT CLI（ParseHeapDump.sh / .bat）— 深度模式必需
• async-profiler — 可选的决胜工具

可选工具：

• jfr CLI — 如果可用，则用于生成 JFR 摘要；否则使用 jcmd JFR.view。对于 Java 8 目标程序（格式不兼容），会完全跳过 JFR。

检查你的设置：

./scripts/check_prereqs.sh          # macOS / Linux
scripts\check_prereqs.bat           # Windows

环境变量覆盖项

将这些变量设置在 .mcp.json 的 env 块中（推荐），或设置为 Shell 变量：

可使用 CLI 标志 --sse 和 --streamable-http 替代 MCP_TRANSPORT。

完整配置模板请参见 .mcp.json.example。

兼容性说明

• Java 8 目标程序：直方图、GC 和 MAT 均可正常使用。会跳过 JFR（v0.9 格式与现代工具不兼容）。
• Windows：MAT 通过 ParseHeapDump.bat 运行。async-profiler 为可选项——如果缺失，深度模式仍会继续使用 JFR + MAT。会自动处理 jstat 输出中因区域设置不同而使用的十进制分隔符（逗号或句点）。
• MAT + JAVA_HOME：MAT 会使用 JAVA_HOME 中的 JDK 启动，因此即使系统默认 Java 版本过旧，无法运行 MAT，也不影响使用。

CLI 用法（不使用 Claude Code 时）

uv run heap-seance --mode scan --match your-app
uv run heap-seance --mode deep --pid 12345 --output json

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

python3 -m venv .venv
source .venv/bin/activate       # Windows: .\.venv\Scripts\Activate.ps1
pip install -e .

heap-seance --mode scan --match your-app

python3 -m unittest discover -s tests -p "test_*.py"

用于验证的 Java 示例场景位于 examples/java-scenarios/ 中：真实的泄漏、有界缓存（无泄漏）和突发分配器（无泄漏）。

贡献

欢迎贡献！请参阅 CONTRIBUTING.md，了解添加工具、信号和技能的指南。

许可证

本项目采用双重许可，您可以选择以下任一许可证：

• Apache License, Version 2.0
• MIT License

。