# Arthas MCP 通用 AI Agent 离线诊断套件

本离线包专为**完全隔离的内网/离线生产环境**设计，面向 **通用 AI Agent 生态**（遵循标准 **.agents** 技能规范与 **Model Context Protocol (MCP)** 协议）。

套件内置官方全量 **Arthas 4.x** 离线运行时、标准技能定义、自动化部署与排障脚本，在目标机上**无需联网、无需预先安装任何依赖**即可一键就绪。

---

## 📦 目录结构

```text
arthas-mcp-offline-package/
├── README.md                      # 离线部署与使用指南
├── DIAGNOSTIC_PROMPTS.md          # 覆盖 6 大场景的 AI Agent 根因排障提示词库
├── package.json                   # 通用 Agent 扩展描述
├── install.sh                     # 通用一键安装脚本（自动部署技能与离线运行库）
├── bin/
│   ├── start-mcp.sh              # 离线挂载并启动 Arthas MCP 服务 (绑定 0.0.0.0，默认密码 arthas123)
│   ├── stop-mcp.sh               # 停止当前 Arthas 挂载会话 (多级优雅脱钩与状态校验)
│   ├── check-mcp.sh              # 健康检查脚本（检测 HTTP/MCP 连通性）
│   └── start-demo.sh             # 启动官方内置 math-game Demo 测试进程
├── arthas-bin/                   # 官方完整 Arthas 4.3.5 离线二进制运行时
│   ├── arthas-boot.jar           # 引导启动 Jar
│   ├── arthas-core.jar           # 核心诊断包（含官方 MCP Server 实现）
│   ├── arthas-agent.jar          # JavaAgent 字节码增强包
│   ├── arthas-client.jar         # 官方纯 Java 诊断控制台客户端
│   ├── async-profiler/           # 采样与火焰图原生动态库（Linux x64/arm64, Mac）
│   ├── as.sh                     # 离线直接执行脚本
│   └── math-game.jar             # 演练 Demo
├── .agents/
│   └── skills/arthas-diagnosis/  # 跨 Agent 通用工作区技能目录（通用标准）
│       └── SKILL.md
├── skills/
│   └── arthas-diagnosis/         # 标准 Agent 技能定义与排障剧本
│       ├── SKILL.md
│       └── references/
│           ├── playbooks.md      # CPU飙高/慢调用/异常排查标准剧本
│           ├── tools-reference.md# 29 个 MCP 工具全量参数对照表
│           └── mcp-setup.md      # 客户端接入与远程连接配置指南
└── config/
    ├── arthas.properties         # 离线服务端配置模板 (默认监听 0.0.0.0，默认密码 arthas123)
    ├── universal_mcp.json        # 通用 Agent MCP 配置模板
    ├── cursor_mcp.json           # Cursor / Cherry Studio 配置模板
    └── mcp_config.claude.json    # Claude Desktop 配置模板
```

---

## 🚀 离线安装与部署（通用 AI Agent）

将离线包 `arthas-mcp-offline-package.tar.gz` 复制到目标机器并解压：
```bash
tar -zxvf arthas-mcp-offline-package.tar.gz
cd arthas-mcp-offline-package
```

### 方式 1：一键自动安装（推荐）
```bash
bash install.sh
```
`install.sh` 具备环境自适应与离线预热能力：
1. **预热本地离线运行库**：自动将二进制及配置文件注入 `~/.arthas/lib/4.3.5/arthas/`，彻底阻断任何外网下载依赖的行为；
2. **部署通用 Agent 技能**：在当前项目根目录及系统环境自动建立 `.agents/skills/arthas-diagnosis/` 标准技能目录，供支持该规范的 Agent 直接读取；
3. **就绪标准配置与脚本**：自动赋予执行权限并准备通用 MCP 配置模板。

---

### 方式 2：部署至指定项目工作区
若需将通用技能直接部署到指定的项目工作区：
```bash
bash install.sh --workspace /path/to/your/project
```
执行后将在该项目根目录创建 `.agents/skills/arthas-diagnosis/`，工作区内的 AI Agent 即可直接识别并调用。

---

### 接入 Agent MCP 配置
在你的 AI Agent 或宿主客户端（如 Claude Desktop、Cursor、Cherry Studio 或支持 MCP 的各类通用智能体）中添加 MCP 服务端点。**默认鉴权密码为 `arthas123`（用户名：`arthas`）**：

#### ① 本机 / 同机客户端配置：
```json
{
  "mcpServers": {
    "arthas": {
      "type": "streamableHttp",
      "url": "http://localhost:8563/mcp",
      "headers": {
        "Authorization": "Bearer arthas123"
      }
    }
  }
}
```

#### ② 远端服务器跨网络访问（将 IP 替换为目标 Java 服务器内网 IP）：
```json
{
  "mcpServers": {
    "arthas": {
      "type": "streamableHttp",
      "url": "http://192.168.1.100:8563/mcp",
      "headers": {
        "Authorization": "Bearer arthas123"
      }
    }
  }
}
```

> 更多配置模板见 [`config/universal_mcp.json`](./config/universal_mcp.json) 与详细接入指南 [`skills/arthas-diagnosis/references/mcp-setup.md`](./skills/arthas-diagnosis/references/mcp-setup.md)。

---

## 🛠️ 启动 MCP 服务并对接诊断

### 1. 启动并挂载目标 Java 进程
> 服务默认绑定 `0.0.0.0:8563`，支持本地或外部远端 AI Agent 跨网络访问。**未指定密码时默认密码为 `arthas123`**。

```bash
# 自动扫描系统 Java 进程并交互选择（默认密码: arthas123）：
./bin/start-mcp.sh

# 指定 PID 与 HTTP 端口（默认密码: arthas123）：
./bin/start-mcp.sh <PID> 8563

# 指定 PID、端口及自定义密码：
./bin/start-mcp.sh <PID> 8563 MyCustomPassword
```

### 2. (可选) 演练 Demo 测试
```bash
# 启动内置的演练进程（math-game.jar）
./bin/start-demo.sh

# 检查服务健康状态（默认使用 arthas123 验证）
./bin/check-mcp.sh 8563 [Password]
```

### 3. 停止与资源释放
排障结束后退出挂载，安全释放字节码增强：
```bash
# 方式 1：默认停止 8563 端口的诊断会话（自动使用默认密码并反查关联 PID）
./bin/stop-mcp.sh

# 方式 2：指定端口
./bin/stop-mcp.sh 8563

# 方式 3：直接指定目标 Java 进程 PID
./bin/stop-mcp.sh <PID>

# 方式 4：带自定义密码停止
./bin/stop-mcp.sh 8563 <PID> MyCustomPassword
```
> **四级自适应停止保障**：`stop-mcp.sh` 内置多级优雅退出与容灾（本地 HTTP API 异步触发 -> 官方纯 Java 客户端 Telnet 脱钩 -> as.sh 运行时脱钩），并在操作后自动轮询核验端口释放与增强还原状态。

---

## 🤖 AI Agent 自然语言指令示例

> 完整详尽的 6 大生产场景与万能排障提示词库，请直接查阅 [**`DIAGNOSTIC_PROMPTS.md`**](./DIAGNOSTIC_PROMPTS.md)。

在配置好 MCP 与技能的 AI Agent 中直接输入自然语言指令：
- **CPU 排查**：“检查当前 JVM 状态，找出占用 CPU 最高的 3 个线程堆栈。”
- **链路追踪**：“追踪 `OrderService.createOrder` 耗时大于 50ms 的子调用分支。”
- **参数监控**：“监控 `PaymentService.pay` 的方法入参和返回值，抓取前 3 次。”
- **热更核对**：“反编译运行中的 `ConfigLoader` 类，核实线上字节码是否为最新逻辑。”

---

## ⚠️ 生产排障安全红线
1. **采样次数必须限制**：使用 `watch`、`trace` 必须附带 `-n <次数>`（如 `-n 5`），禁止无限捕获。
2. **避免大范围通用方法**：禁止直接 trace `String.equals`、`HashMap.get` 等底层高频方法。
3. **安全使用 Heapdump**：生产环境 dump 堆前务必确认磁盘容量，优先使用 `--live`。
4. **会话及时清理**：诊断完成后调用 `stop` 或执行 `./bin/stop-mcp.sh` 还原增强。