# java-perf-doctor：专为 Claude Code 打造的 AI 原生 JVM 诊断工具

> 一款结合 Shell 脚本采集能力与大模型推理能力的自动化诊断工具，能够跨越宿主机边界深入 Docker 容器进行 JVM 性能体检，实现死锁定位、CPU 热点追踪和 GC 健康检查。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-13T14:11:47.000Z
- 最近活动: 2026-04-13T14:18:47.123Z
- 热度: 152.9
- 关键词: JVM, Java, Docker, 性能诊断, Claude Code, AI工具, 死锁检测, GC调优, Shell脚本
- 页面链接: https://www.zingnex.cn/forum/thread/java-perf-doctor-claude-code-ai-jvm
- Canonical: https://www.zingnex.cn/forum/thread/java-perf-doctor-claude-code-ai-jvm
- Markdown 来源: ingested_event

---

## 背景：JVM 诊断的痛点与挑战\n\n在微服务架构和容器化部署成为主流的今天，Java 应用的性能诊断变得愈发复杂。传统的 JVM 诊断工具虽然功能强大，但往往需要开发者在容器内部安装复杂的 Agent，或者手动执行一系列命令并解读输出结果。这种工作流不仅繁琐，还要求工程师具备深厚的 JVM 调优经验。\n\n当生产环境出现响应延迟、CPU 飙升或内存泄漏等问题时，运维人员常常面临两难选择：要么冒着风险在生产环境安装监控工具，要么依靠日志和猜测来定位问题。这种困境催生了对更智能、更自动化诊断方案的需求。\n\n## 项目概述：AI 与 Shell 的融合创新\n\njava-perf-doctor 是一款专为 Claude Code 设计的自动化诊断工具，其核心创新在于将 Shell 脚本的硬核数据采集能力与大语言模型的逻辑推理能力相结合。这种架构设计使得工具能够跨越宿主机边界，直接深入 Docker 容器内部执行 JVM 性能体检。\n\n项目的最大亮点是**零侵入式设计**——无需在容器内预装任何复杂的监控 Agent，仅通过 `docker exec` 自动化调度 JDK 原生工具（如 jstack、jstat、jcmd）即可完成数据采集。这种设计特别适用于生产环境中的精简版 Docker 镜像，这些镜像往往为了安全考虑而移除了许多调试工具。\n\n## 核心功能：多维度的性能诊断\n\n### 死锁精准定位\n\n死锁是多线程应用中最棘手的问题之一。java-perf-doctor 能够自动扫描线程堆栈，识别持有锁和等待锁的线程地址，并将这些信息关联回 Java 源码的具体行号。这种精准定位能力大幅缩短了问题排查时间，开发者不再需要手动分析冗长的线程转储文件。\n\n### CPU 热点追踪\n\nCPU 使用率异常是线上常见问题。该工具自动完成 Linux TID（十进制线程 ID）到 JVM NID（十六进制原生线程 ID）的进制转换，快速锁定消耗 CPU 资源的"热点"代码位置。这种自动化转换避免了人工计算错误，确保诊断结果的准确性。\n\n### GC 趋势健康检查\n\n垃圾回收是 JVM 性能的关键指标。java-perf-doctor 实时分析 Eden 区和 Old 区的内存占比，监控 Full GC 的发生频率，并基于这些数据给出具体的 JVM 参数调优建议。这种预防性的健康检查有助于在问题恶化前发现潜在风险。\n\n## 技术实现：防御性设计与自动化测试\n\n项目采用了防御性脚本设计理念，内置了 `/proc` 文件系统的 fallback 逻辑。即使在极度精简的 Docker 镜像中，当标准 JDK 工具不可用时，工具也能通过直接读取内核数据完成采集。这种鲁棒性设计确保了工具在各种复杂环境下的可用性。\n\n此外，项目包含了完整的 `evals.json` 测试用例集，通过自动化断言验证诊断结果的准确性与鲁棒性。这种测试驱动的方法确保了工具在面对真实生产环境时的可靠性。\n\n## 使用体验：自然语言驱动的诊断\n\n作为 Claude Code 的 Skill，java-perf-doctor 支持自然语言指令。用户只需在终端中输入类似"帮我诊断一下 takeout-app 容器的性能，最近响应有点慢"的指令，Claude Code 就会自动调用本 Skill 执行完整的诊断流程，并生成结构化的诊断报告。\n\n这种交互方式大幅降低了 JVM 诊断的门槛，即使是缺乏深入 JVM 调优经验的开发者，也能借助 AI 的推理能力获得专业的诊断建议。\n\n## 项目结构与扩展性\n\n项目的代码组织清晰合理：\n\n- **SKILL.md**：定义诊断 SOP、决策树与报告模板，是 AI 逻辑的核心\n- **scripts/diagnose.sh**：原子化采集脚本，负责 Docker 内部数据的安全抓取\n- **evals/evals.json**：自动化测试用例，覆盖死锁、CPU 飙高、GC 异常等场景\n\n这种模块化设计使得工具易于扩展和维护，开发者可以根据自身需求定制诊断逻辑或添加新的检测维度。\n\n## 总结与展望\n\njava-perf-doctor 代表了 AI 辅助运维工具的一个发展方向：将领域专业知识编码为可复用的 Skill，让大语言模型承担复杂的推理和报告生成工作，而人类工程师则专注于决策和问题解决。\n\n对于运行大量 Java 微服务的团队而言，这款工具提供了一种轻量级、零侵入的诊断方案，值得纳入日常运维工具箱。随着 AI Agent 技术的成熟，我们可以期待更多类似的智能诊断工具出现，进一步简化复杂的系统运维工作。