前言¶
在 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。
