# Arthas Java 运行时诊断提示词指南 (AI Agent Prompt Guide)

本指南汇总了面向 **通用 AI Agent**（支持 MCP 与标准 `.agents` 技能的各类智能体）的专业 Java 诊断提示词模板。每个提示词均贴合实际生产排障场景，针对性编排 Arthas 工具链，并严格遵循生产安全红线以快速下钻根因。

---

## 目录
- [💡 万能自动化排障提示词（直接可用）](#-万能自动化排障提示词直接可用)
- [场景 1：CPU 飙高与线程阻塞/死锁定位](#场景-1cpu-飙高与线程阻塞死锁定位)
- [场景 2：接口耗时突增与慢调用链路细粒度下钻](#场景-2接口耗时突增与慢调用链路细粒度下钻)
- [场景 3：偶发异常捕获与入参返回值现场还原](#场景-3偶发异常捕获与入参返回值现场还原)
- [场景 4：代码版本核实与类冲突/加载排查](#场景-4代码版本核实与类冲突加载排查)
- [场景 5：内存泄漏、频繁 GC 与堆内存异常](#场景-5内存泄漏频繁-gc-与堆内存异常)
- [场景 6：运行时配置与 Spring Bean 状态检查](#场景-6运行时配置与-spring-bean-状态检查)
- [⚠️ 生产排障安全红线](#️-生产排障安全红线)

---

## 💡 万能自动化排障提示词（直接可用）

当遇到未知的线上生产异常时，直接将以下模版发送给 AI Agent：

```text
【Java 问题快速诊断任务】
- 目标现象：【例如：接口 /api/pay 耗时突增至 3 秒，且伴随偶尔报错】
- 目标可能涉及的类/方法：【例如：com.example.pay.PayService#doPay，若不确定可填"待排查"】

请按照 Arthas 标准诊断 Playbook 逐步执行排查：
1. 【安全与健康检查】：执行 dashboard 快速确认当前 JVM 整体负载（CPU、内存各代、GC 状态）；
2. 【定位热点与瓶颈】：根据现象选择对应手段（高 CPU 查 thread -n 3；接口慢用 trace 过滤 >100ms；报错用 watch -e 捕获异常参数）；
3. 【抓取关键数据】：执行观察指令时必须强制携带采样限制（-n 3 ~ 5），不得无限制阻塞；
4. 【结论输出】：归纳排查链路，明确指出问题发生的根本原因（Root Cause）、具体的代码文件与行号，并给出最简洁的修复建议；
5. 【清理会话】：诊断结论得出后，务必调用 stop 释放所有字节码增强。
```

---

## 场景 1：CPU 飙高与线程阻塞/死锁定位

### 提示词 1.1（通用 CPU 突增排查）
```text
线上监控报警当前 Java 进程 CPU 使用率突增（>85%）。
请通过 Arthas 工具完成以下排查：
1. 找出当前 CPU 占用最高的前 3 个繁忙线程，并获取其完整堆栈；
2. 采样 1 秒分析线程实时 CPU 消耗，判断高 CPU 原因是业务代码死循环/高频正则/JSON 序列化，还是 JVM GC 垃圾回收线程（如 VM Thread/GC task thread）；
3. 如果是业务代码，精准指出耗费 CPU 的类名、方法名及代码具体行号，并分析其根因。
```
* **背后工具链**：`thread -n 3` → `thread -i 1000 -n 3` → 若为 GC 线程结合 `dashboard` / `memory`
* **根因预期**：区分业务死循环、正则回溯或频繁 Full GC，输出代码行号。

### 提示词 1.2（线程池打满与死锁排查）
```text
服务响应出现大面积超时，疑似线程池耗尽或存在线程死锁/阻塞。
请使用 Arthas 协助定位：
1. 检测当前 JVM 中是否存在线程死锁，列出处于 BLOCKED 状态的线程及其正等待持有的锁对象；
2. 找出当前持有该锁对象的阻塞源头线程；
3. 分析导致死锁或长时间持有锁不释放的代码位置与根本原因。
```
* **背后工具链**：`thread -b` → `thread <id>`
* **根因预期**：锁定相互争抢锁的线程对及锁资源。

---

## 场景 2：接口耗时突增与慢调用链路细粒度下钻

### 提示词 2.1（方法级慢调用链路下钻）
```text
接口 【/order/create】 响应时间从平日 30ms 突增至 800ms+，入口方法为 【com.example.service.OrderService#createOrder】。
请使用 Arthas 协助下钻排查：
1. 安全追踪该方法执行链路（限制采样 5 次），仅捕获耗时大于 100ms 的慢调用分支；
2. 定位链路中最耗时的子调用（是数据库查询、远程 RPC、Redis 操作还是本地复杂循环）；
3. 给出该慢调用的精确类名、方法名以及在总调用树中的耗时占比。
```
* **背后工具链**：`trace com.example.service.OrderService createOrder -n 5 '#cost > 100'`
* **根因预期**：定位慢 SQL、慢下游调用或循环调用分支。

### 提示词 2.2（捕获慢调用的请求入参与上下文）
```text
已知方法 【com.example.dao.OrderRepository#queryDetail】 存在偶发慢查询。
请在 Arthas 中监控该方法：
1. 当执行耗时超过 200ms 时，捕获该次调用的入参、返回值以及执行耗时（展开对象深度为 2，采样 3 次停止）；
2. 分析捕获到的参数特征，判断慢调用是否由大参数（如一次性查询超大列表、超大 pageSize）引发。
```
* **背后工具链**：`watch com.example.dao.OrderRepository queryDetail '{params, returnObj, #cost}' '#cost > 200' -x 2 -n 3`
* **根因预期**：抓出引发慢查的实际大参数或深分页入参。

### 提示词 2.3（慢方法调用来源追溯）
```text
底层通用方法 【com.example.util.DataConverter#convert】 频率极高且出现性能瓶颈。
请使用 Arthas 抓取该方法的调用栈深度（采样 3 次）：
1. 找出是谁在频繁调用该转换方法；
2. 输出完整的调用链上下游，定位是否存在循环内重复调用或不合理的大批量转换。
```
* **背后工具链**：`stack com.example.util.DataConverter convert -n 3`
* **根因预期**：找出上游滥用/无节制循环调用的源头方法。

---

## 场景 3：偶发异常捕获与入参返回值现场还原

### 提示词 3.1（抓取特定异常及抛出时的入参现场）
```text
线上方法 【com.example.service.PaymentService#processPayment】 出现偶发 NullPointerException，业务日志未打印入参。
请通过 Arthas 进行捕获：
1. 监听该方法，仅在方法抛出异常时触发（-e），抓取抛出时的入参（params）、异常对象（throwExp）及其调用栈（采样 3 次停止）；
2. 结合入参数据与异常堆栈，指出具体是哪个入参或内部对象为 null，导致在哪一行发生空指针。
```
* **背后工具链**：`watch com.example.service.PaymentService processPayment '{params, throwExp}' -e -x 2 -n 3`
* **根因预期**：无侵入获取导致 NPE 时的具体字段值与调用栈。

### 提示词 3.2（根据业务条件精准过滤抓包）
```text
特定用户（userId = 10086）在调用 【com.example.service.UserService#updateProfile】 时返回数据异常。
请使用 Arthas 进行条件抓包：
1. 仅当第一个参数的 userId 为 10086 时捕获（params[0].userId == 10086）；
2. 打印方法入参、返回值及执行耗时（展开深度为 2，采样 2 次停止）；
3. 核实返回值是否符合预期，并分析异常原因。
```
* **背后工具链**：`watch com.example.service.UserService updateProfile '{params, returnObj}' 'params[0].userId == 10086' -x 2 -n 2`
* **根因预期**：隔离生产海量流量，仅捕获目标异常用户的数据。

### 提示词 3.3（时空隧道：记录并回溯历史调用）
```text
方法 【com.example.service.PromotionService#calcDiscount】 计算优惠金额出现偏差，需要复现问题。
请在 Arthas 中：
1. 开启时空隧道记录该方法的调用现场（限制捕获 5 次）；
2. 罗列已记录的调用列表（tt -l）；
3. 针对异常的调用编号（INDEX）进行详细上下文回溯展开，确认计算公式入参的每一个属性值。
```
* **背后工具链**：`tt -t ... -n 5` → `tt -l` → `tt -i <INDEX>`
* **根因预期**：获取调用全量环境状态，复现偶发逻辑 bug。

---

## 场景 4：代码版本核实与类冲突/加载排查

### 提示词 4.1（反编译确认线上运行代码版本）
```text
怀疑线上部署的代码与最新 Git Commit 不一致（疑似打包漏更新或配置未生效）。
请使用 Arthas 协助核验：
1. 反编译 JVM 内存中实际运行的类 【com.example.config.AppConfig】；
2. 检查特定方法/属性逻辑是否为最新代码，确认线上实际生效的字节码实现。
```
* **背后工具链**：`jad --source-only com.example.config.AppConfig`
* **根因预期**：判断是否属于“发布假成功/线上仍为旧代码”。

### 提示词 4.2（ClassNotFound / NoSuchMethodError 类冲突排查）
```text
程序运行时抛出 NoSuchMethodError 或 ClassNotFoundException。
请通过 Arthas 分析类加载冲突：
1. 检索目标类 【com.example.dto.UserDTO】 的类加载信息，查看该类究竟被加载了几次、分别来自哪几个 jar 包路径；
2. 输出其所属 ClassLoader 的层级委托树（classloader -t）；
3. 指出是否存在多版本同名 Jar 包冲突，并给出排除依赖建议。
```
* **背后工具链**：`sc -d com.example.dto.UserDTO` → `classloader -t`
* **根因预期**：定位出 Maven 间接引入的双版本冲突 Jar。

---

## 场景 5：内存泄漏、频繁 GC 与堆内存异常

### 提示词 5.1（GC 频繁与内存分布概览）
```text
监控提示老年代内存使用率持续在 90% 以上，疑似发生内存泄漏或频繁 Full GC。
请使用 Arthas 评估：
1. 查看当前 JVM 的 Eden、Survivor、OldGen、Metaspace 等内存区占用与垃圾回收次数/耗时；
2. 判断是否有持续发生 Full GC 的迹象，并结合线程情况确认是否存在大对象分配。
```
* **背后工具链**：`memory` → `dashboard -n 1`
* **根因预期**：快速确定内存代际空间健康度及 GC 停顿影响。

### 提示词 5.2（内存活对象实例探查与安全 Dump）
```text
怀疑业务缓存 【com.example.cache.LocalCacheManager】 未设置过期淘汰导致对象无限制堆积。
请使用 Arthas 调查：
1. 探测该类在内存中的存活实例数量及主要属性；
2. （必要时）在确认磁盘容量的前提下，触发仅针对存活对象的快照转储（heapdump --live /tmp/dump.hprof），供进一步内存泄漏分析。
```
* **背后工具链**：`vmtool --action getInstances --className com.example.cache.LocalCacheManager` → `heapdump --live`
* **根因预期**：定位静态容器大对象或生成堆转储供 MAT/JProfiler 分析。

---

## 场景 6：运行时配置与 Spring Bean 状态检查

### 提示词 6.1（动态查看运行时静态变量与环境变量）
```text
配置中心（Apollo/Nacos）推送了新配置，但业务表现不符合预期，怀疑本地静态缓存未刷新。
请使用 Arthas 检查：
1. 读取类 【com.example.constant.GlobalConfig】 中的静态字段 【CONFIG_MAP】 的当前内存值；
2. 读取 JVM 系统环境变量（sysprop），确认特定启动参数是否被覆盖。
```
* **背后工具链**：`getstatic com.example.constant.GlobalConfig CONFIG_MAP` → `sysprop`
* **根因预期**：确定运行时参数真实值与静态变量加载状态。

### 提示词 6.2（直接读取 Spring 容器内 Bean 的实时属性）
```text
排查某个单例 Spring Service 【com.example.service.RiskControlService】 的实时配置状态。
请在 Arthas 中：
1. 通过 vmtool 获取该 Bean 在内存中的运行实例；
2. 提取其内部核心开关或规则集合的值，确认运行时状态。
```
* **背后工具链**：`vmtool --action getInstances --className com.example.service.RiskControlService --express 'instances[0].rules'`
* **根因预期**：无需注入日志或重启，直接窥探 Spring Bean 运行期内部状态。

---

## ⚠️ 生产排障安全红线

在编写或自定义提示词时，务必引导 AI 严格遵循以下生产安全约束：
1. **必须限制采样次数**：所有 `watch`、`trace`、`stack` 必须附带 `-n 3` 或 `-n 5`，禁止无限制捕获避免日志刷爆。
2. **严禁无条件 trace 底层框架方法**：避免 trace `String.equals`、`HashMap.get`、基础 Filter 等高频方法，必须使用特定业务方法或条件过滤。
3. **安全使用 Heapdump**：生产转储必须使用 `--live` 仅导出存活对象，并提前确保磁盘有 2~3 倍堆大小的富余空间。
4. **诊断完成必须 Stop**：排障结束要求 Agent 显式调用 `stop`，彻底撤销字节码插桩与资源占用。