agent-skills/skills/java-bug-finder/SKILL.md

name, description

name	description
java-bug-finder	自动登录远程 Ubuntu 服务器，根据错误码或服务名提取 Java Spring Boot 项目日志，并结合本地代码进行 Bug 诊断和修复建议。适用于 Java + Spring Boot 项目，支持 Docker Compose 和文件日志模式。

Java Bug Finder (Java 故障排查专家)

本 Skill 用于自动化排查部署在远程服务器上的 Java Spring Boot 应用问题。它能够连接服务器、抓取日志、解析堆栈、定位源码并提供修复方案。

触发场景

• 用户要求排查特定服务的错误（如：“看看 order-service 为什么报错”）。
• 用户提到特定的错误码（如：“错误码 5002 是怎么回事？”）。
• 用户需要分析远程服务器上的 Java 异常堆栈。

工作流

1. 识别服务与服务器

当收到指令后，首先读取 references/service_inventory.md：

• 确认所有节点: 确定服务部署的所有服务器 IP（如 192.168.3.200 和 192.168.3.230）。Agent 必须对所有记录的节点执行日志提取。
• 如果用户提供了服务名（如 gateway），查找对应行。
• 如果用户提供了错误码（如 12005），根据 错误码起始 判定所属服务（12000-12999 为 user）。
• 确认目标 Docker 服务名（如 g3fo-gateway-service）或 日志文件路径（如 /data/logs/g3fo-user/info/info.log）。
• 确认目标 Server IP、Log Method 以及相关的 Path/YML。

2. 获取 SSH 凭据

• 检查环境中是否存在凭据（如环境变量）。
• 如果没有，以交互方式询问用户：SSH 用户名 和 密码（或提醒用户配置私钥）。
• 注意：不要在对话中存储密码，仅用于当前会话运行脚本。

3. 提取远程日志

使用 Python 脚本 scripts/fetch_logs.py 抓取日志。

• 全节点提取: 由于服务部署在多台服务器上（192.168.3.200, 192.168.3.230），必须同时从所有相关服务器提取日志，以确保不遗漏错误信息。
• 日志级别选择:
  • 默认抓取 info 级别。
  • 如果涉及报错排查，优先抓取 error 级别。
• 路径拼装: 严格遵循 /data/logs/g3fo-{service}/{level}/{level}.log。

命令模版示例 (需对两台机器分别运行):

# 对 Server A 运行
python scripts/fetch_logs.py --host 192.168.3.200 --username root --password afe1234 --mode docker --service [SERVICE] --yml-path [YML]

# 对 Server B 运行
python scripts/fetch_logs.py --host 192.168.3.230 --username root --password afe1234 --mode docker --service [SERVICE] --yml-path [YML]

4. 异常分析与代码定位

• 日志解析：从获取的日志中提取 Exception、Error 或 Caused by 附近的堆栈信息（Stack Trace）。
• 网络问题判断：如果日志分析结论为网络连通性问题（如 Connection refused, ConnectTimeoutException, UnknownHostException 等）：
  • 直接说明：在报告中直接说明是网络连通性问题。
  • 连通性测试：使用 nc -zv {IP} {Port} 或 telnet {IP} {Port} 到目标服务器进行测试。
  • 无需深度分析：这种情况下不需要进一步分析源码或 Nacos 配置。
• 源码检索：提取堆栈中的全限定类名（如 com.example.service.OrderService）和行号。
• 配置获取：如需分析配置（如数据库地址、中间件端口等），使用 scripts/fetch_configs.py。
  • 示例：python scripts/fetch_configs.py --data-id redis.yml
• 本地比对：使用 read_file 或 codebase_search 查看本地对应的源码逻辑。

5. 输出诊断报告

报告应包含：

• 错误类型：Java 异常类名。
• 根本原因：根据日志和代码逻辑分析得出的结论（如果是网络问题，请务必指出）。
• 连通性测试结果（如适用）：展示服务器间网络测试的输出。
• 关联代码：引用本地源码的相关片段。
• 修复方案：具体的代码修改建议或配置调整建议。

依赖要求

• 本地 Python 环境。
• 安装 paramiko 库：pip install paramiko。
• 目标服务器支持 SSH 登录。

注意事项

• 如果日志文件过大，建议优先使用脚本自带的 grep 过滤功能。
• 始终确保本地代码分支与服务器部署版本尽量一致。