前言¶
在 DeepSeek Harness（DSH）里排查 Java 生产问题时，模型拿到的往往是运维已经导出的 jstack、GC 日志、dependency:tree、异常栈或两份 Spring 配置。常见做法是让模型现场起 jcmd / attach，或在长文本里「肉眼心算」死锁环和依赖冲突——前者在生产环境常被权限与审计拦住，后者不可复现，还容易把「没看懂输入」当成「没有异常」。下面介绍维护者 ax2 发布的工作流类插件 dsh-jvm-doctor：只做离线、确定性的文本解析，向模型注册 5 个工具，把粘贴内容换成结构化结果，并附带解析覆盖率与字节回执。
这是什么¶
dsh-jvm-doctor 是 DSH 插件（npm 包名 dsh-jvm-doctor），定位为 离线、确定性的 JVM 生产报告诊断器。它不接触运行中的 JVM：无 jcmd / jstack / jmap / jstat、无 attach / JMX、无网络、无文件读取、无时钟与随机数；同一输入永远同一输出。
插件在 DSH 0.2.0-rc.2 上验证通过，运行需 Node ≥ 20.10（测试需 ≥ 22.6），许可证 MIT。社区目录页：https://www.skillhub.cn/plugins/ax2/dsh-jvm-doctor；源码与文档：https://github.com/ax2/dsh-jvm-doctor。
核心功能：五个工具¶
装好后，模型可调用以下工具（名称可通过配置加前缀或 only 筛选）：
| 工具 | 作用 |
|---|---|
java_thread_dump |
解析 jstack 或 jcmd <pid> Thread.print：线程普查、状态直方图、daemon 数、锁与 top 帧、Java 级死锁环（waiting_for / holding 链）、Object.wait/park 计数、锁竞争队列 |
java_gc_log |
解析 JEP 158 统一 GC 日志与 JDK 9 之前旧格式：停顿统计、p50/p90/p99、Young/Full 拆分、堆区间、cause 直方图、promotion failure；有时间戳时可估算分配速率 |
java_dependency_conflicts |
解析 Maven dependency:tree -Dverbose 与 Gradle dependencies / dependencyInsight：同 artifact 多版本、omitted for conflict with、omitted for duplicate、边深度与摘要 |
java_stack_trace |
解析异常链：类型与消息、栈帧、Caused by: / Suppressed:、... N more 按外层 trace 还原、最深业务帧、最多 6 条可能原因提示（结构化事实，不做因果推断） |
spring_config_diff |
两份 application.yml / .properties 展平为点号键后对比 add/remove/change；敏感值进入载荷前替换为 *** |
README 中强调：死锁环、GC 百分位、依赖冲突消解、折叠栈还原等若每次让模型写脚本，体量大且易错；本插件为固定实现，并有 47 个测试保障。
设计契约：回执与边界¶
每次调用返回统一形状：result 为工具载荷，meta 含 bytesIn、bytesOut、truncated、notes。仅在截断或需说明时追加页脚，避免干净调用多占 token。
解析质量不会与「无问题」混淆：各工具提供 unknown_lines、unknown_samples、coverage、confidence；超预算时逐条报 threads_omitted、causes_omitted 等，而不是静默丢弃。
输入超过 maxInputBytes 会抛错拒绝（不做部分处理）；输出超 maxOutputBytes 则按 code point 截断并标记。不认识的语法计入 unknown_lines 并下调 confidence。
安装与启用¶
推荐通过 npm 安装到 web profile：
dsh plugin --profile web add dsh-jvm-doctor
也可使用 GitHub Release 预构建 tarball（与 npm 同产物）：
dsh plugin --profile web add https://github.com/ax2/dsh-jvm-doctor/releases/latest/download/dsh-jvm-doctor.tgz
固定版本时将 URL 中的 latest/download/dsh-jvm-doctor.tgz 换为 download/v<version>/dsh-jvm-doctor-<version>.tgz。
安装完成后需重启 DSH 应用。若希望一次装齐 ax2 的 deterministic-tools、py-doctor、win-native 与本插件，可使用 dsh-toolbox-bundle，不要与单独安装混用。家族总览入口：https://zicode.com/software/。
配置（可选）¶
apply(ctx, config) 接受可选字段，非法值会回落默认。常用项包括：
maxInputBytes（默认 2097152）：单份粘贴文本 UTF-8 字节上限，超限拒绝。maxOutputBytes（默认 262144）：渲染文本软上限。maxThreads、maxGcEvents、maxConflicts、maxExceptions等：各工具列表与样本预算。toolPrefix：工具名前缀，例如jvm得到jvm__java_thread_dump。only：只注册指定工具，空数组表示全部。
完整字段表见 GitHub README「配置」一节。
典型用法¶
- 安装并重启 DSH 后，在对话中把生产现场已有文本交给模型（线程 dump、GC 日志、依赖树、异常栈或两份配置）。
- 模型按需调用对应工具；例如粘贴异常栈后调用
java_stack_trace，可得到类似下面的结构化摘要（README 实测节选）：
root_cause: java.lang.IllegalStateException: inner
primary: java.lang.RuntimeException: boom
frames: com.acme.Main.main(Main.java:7) coverage: 100% (3/3, parser 1)
- 线程 dump 场景下，
java_thread_dump会输出deadlock_cycles等字段，把 JVM 报告的 Java 级死锁整理成waiting_for/holding链，而不必在数百线程中手工检索。
本地开发可不安装包，在仓库内 pnpm install && pnpm build 后通过 cordis.local-overlay.yml 挂载产物启动；详见 README「安装」中的本地开发小节。
适用场景与注意¶
适合：已有离线证据、需要在 DSH 对话里快速得到可复现、可审计的结构化事实的 SRE、后端开发与智能体工作流作者；与「让模型自己写解析脚本」相比，行为固定且有测试覆盖。
不适合：期望插件代你采集线程或 GC——本插件永不连接运行中进程；采集仍须在容器外或合规流程里完成，再把文本粘贴进 Harness。
安全与信任：插件以当前 DSH 进程权限运行；安装前请阅读 GitHub 仓库 源码与 MIT 许可证，确认符合你的合规要求。SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-jvm-doctor 把 JVM 生产排查里最常见的五类文本（线程 dump、GC 日志、依赖树、异常栈、Spring 配置 diff）收敛为同一套「结构化结果 + 覆盖率回执」契约，适合嵌入 DSH「一切皆插件」的工作流。进一步了解可访问目录页 skillhub.cn/plugins/ax2/dsh-jvm-doctor 与 github.com/ax2/dsh-jvm-doctor。
