Omics Run Diagnosis

omics-run-diagnosis — 组学平台任务运行错误诊断

概述

本 Skill 通过 omics-platform-cli 认证，调用组学平台 /omics/api/cgi (JSON-RPC) 接口拉取任务日志，再结合内置的错误知识库（references/troubleshooting-kb.md），自动匹配错误根因并给出解决方案。

核心能力：

认证与鉴权

本 Skill 依赖 omics-platform-cli 完成认证，无需手动配置密钥。

认证流程

1. 检查 omics-platform-cli 是否安装
2. 读取 ~/.omics-platform-cli/auth.json 中的 session_id
3. 调用 /userinfo 接口自动获取当前登录用户的 Uin
4. 使用 session_id + Uin 调用 RunService.DescribeRunLogs

前置依赖

# 安装 omics-platform-cli
curl -fsSL https://cnb.cool/tencenthealthcareomics/omics-platform-cli/-/raw/main/install.sh | bash

# 登录授权（首次使用）
omics login

Uin 获取策略

💡 关于 Uin：认证时即可通过 /userinfo 接口获取当前登录用户的 Uin，无需用户手动提供。只有当用户需要诊断他人的任务时，才需要手动指定 --run-uin。

执行方式

使用 Skill 目录下的 Python 脚本，通过 omics-platform-cli 认证调用组学平台 JSON-RPC 接口：

# 单任务模式（Uin 自动获取）
python3 scripts/query_run_log.py \
  --run-uuid <UUID>

# 批次模式
python3 scripts/query_run_log.py \
  --run-group-id <GROUP_ID>

# 手动指定 Uin（诊断他人任务）
python3 scripts/query_run_log.py \
  --run-uuid <UUID> \
  --run-uin <UIN>

# 指定环境
python3 scripts/query_run_log.py \
  --run-uuid <UUID> \
  --env prod|dev

参数说明

诊断工作流

端到端流程

用户提供 RunUuid / RunGroupId
  │
  ├─ Step 0：认证
  │   ├─ 检查 omics-platform-cli 安装状态
  │   ├─ 读取 ~/.omics-platform-cli/auth.json 中的 session_id
  │   ├─ 调用 /userinfo 自动获取当前用户 Uin
  │   └─ 如果认证失败 → 引导用户执行 omics login
  │
  ├─ Step 1：收集信息
  │   ├─ 调用 query_run_log.py 拉取日志（单任务 or 批次模式）
  │   ├─ 如果批次模式返回 RunGroupChildSummaryTip → 提示用户选择失败子任务 → 二次调用
  │   └─ 如果只返回 RunStatusTip / RunGroupStatusTip → 任务非失败状态，直接告知用户
  │
  ├─ Step 2：解析日志，提取错误信号
  │   ├─ 扫描 ErrorCallStderr / ErrorCallStdout / ErrorCallCommand
  │   ├─ 扫描 ErrorCallJobEvent（Pod 事件中的 Warning 类型）
  │   ├─ 扫描 DataStageLog（数据预处理/归档阶段错误）
  │   └─ 扫描 NFDriverLog / NFDriverStdout / NFExecutionTrace（NF 引擎专属）
  │
  ├─ Step 3：匹配知识库
  │   ├─ 将提取的错误信号与 troubleshooting-kb.md 中的模式进行匹配
  │   ├─ 按「症状 → 根因 → 解决方案」三段式输出
  │   └─ 如果无法匹配 → 输出原始错误信息 + 建议联系平台支持
  │
  └─ Step 4：输出诊断报告
      └─ 按统一模板输出（见下方「输出格式」）

Step 1 详细：日志查询逻辑

本 Skill 通过 scripts/query_run_log.py 调用组学平台 JSON-RPC 接口 (POST /omics/api/cgi, method: RunService.DescribeRunLogs) 拉取日志，查询逻辑如下：

环境配置：

• 默认使用生产环境（prod）
• 通过 --env 参数切换环境

认证与 Uin 获取：

1. 读取 ~/.omics-platform-cli/auth.json 中的 session_id
2. 调用 /userinfo 接口获取当前用户的 Uin
3. 将 Uin 作为 RunUin 参数传入 RunService.DescribeRunLogs
4. 如果用户手动指定了 --run-uin，则使用手动值（用于诊断他人任务）

响应分支判别（传 RunGroupId 时）：

Step 2 详细：错误信号提取

从 API 返回的 Logs 数组中，按以下优先级提取错误信号：

关键：优先看 Error 类型的日志，它们直接对应失败作业。*

Step 3 详细：知识库匹配策略

读取 references/troubleshooting-kb.md，按以下策略匹配：

1. Pod 事件匹配：解析 ErrorCallJobEvent 中的 Reason 和 Message 字段

   • SystemOOM / CGroup OOM encountered → 匹配「内存不足」
   • FailedCreatePodSandBox + insufficient resource → 匹配「可用区资源不足」
   • ImagePullBackOff / ErrImagePull → 匹配「镜像拉取失败」
   • Unschedulable → 匹配「任务资源不匹配」或「调度失败」

2. stderr 文本匹配：扫描 ErrorCallStderr 中的关键字符串

   • OOM / out of memory / killed → 匹配「内存不足」
   • permission denied / access denied → 匹配「COS 访问权限问题」
   • No such file / not found → 匹配「文件/目录不存在」
   • command not found / exit code → 匹配「作业命令行失败」

3. DataStageLog 匹配：扫描数据预处理/归档阶段日志

   • coscli 错误 / Access denied → 匹配「COS 访问权限问题」
   • NoSuchKey / not exist → 匹配「预处理文件不存在」
   • 归档阶段错误 → 匹配「归档失败」

4. 任务状态模式匹配（当无详细日志时，根据用户描述的状态）：

   • "批次失败且没有子任务" → 匹配「批次初始化失败」
   • "子任务没有作业列表" → 匹配「数据预处理失败」
   • "作业全部成功但子任务失败" → 匹配「归档失败」
   • "批次完成但COS无结果" → 匹配「输出目录错误」

Step 4 详细：输出格式

诊断报告模板

## 🔍 诊断报告：{RunUuid 或 RunGroupId}

**查询环境**：{命中的环境名称}
**查询时间**：{当前时间}

### 📊 任务概览
- **任务标识**：{RunUuid / RunGroupId}
- **引擎类型**：{WDL / NEXTFLOW / 未知}
- **任务状态**：{根据 RunStatusTip 或日志内容推断}

---

### ❌ 错误诊断

#### 错误 1：{错误分类标题}
- **严重程度**：🔴 致命 / 🟡 警告
- **错误类型**：{知识库中的错误编号，如 E01}
- **证据来源**：{LogType + 关键片段}

**根因分析**：
{基于知识库的根因描述}

**解决方案**：
{基于知识库的解决方案，按步骤列出}

---

#### 错误 2：{错误分类标题}
（同上格式）

---

### 📋 原始错误摘要

（仅列出关键错误日志的摘要，不超过 500 字，避免信息过载）

### 💡 建议的下一步操作

1. {最优先的修复步骤}
2. {次优先的修复步骤}
3. {如果以上无法解决，建议联系平台支持}

批次模式输出模板（WDL）

## 🔍 批次诊断报告：{RunGroupId}

**查询环境**：{命中的环境名称}

### 📊 批次概览
- **批次标识**：{RunGroupId}
- **引擎类型**：WDL
- **批次状态**：{RunGroupStatusTip 或 RunGroupChildSummaryTip 内容}

### ❌ 错误子任务列表

| 序号 | 子任务 Uuid | 状态 |
|------|------------|------|
| 1 | {uuid1} | 失败 |
| 2 | {uuid2} | 失败 |

> 💡 请提供您想诊断的子任务 Uuid，我将拉取其详细日志并生成诊断报告。您也可以说"全部诊断"，我会逐个分析（数量较多时建议分批）。

### 📥 批次输入（如有 RunGroupInput）
（解析展示，可能包含导致批次级错误的线索）

无错误场景

如果日志显示任务并非失败状态（仅返回 RunStatusTip / RunGroupStatusTip），直接告知：

## ✅ 任务状态正常

任务 {RunUuid / RunGroupId} 当前状态为「{状态}」，未检测到错误。

如果您遇到了其他问题，请描述具体现象，我可以帮您进一步排查。

补充说明

• 本 Skill 内置 scripts/query_run_log.py 脚本，独立完成日志查询与诊断，无需依赖其他 Skill
• 如果知识库无法覆盖遇到的错误，应回退到展示原始日志，并建议用户联系平台支持
• 如果用户仅需查看原始日志而不需要诊断，可直接展示 API 返回的日志内容

LogType 速查

诊断时重点关注以下 LogType：

Pod 事件 (JobEvent) 关键 Reason

注意事项

1. LogContent 中的 JSON 字符串需要二次解析（它是字符串化的 JSON）
2. 诊断时不要把完整原始日志全部输出，只输出与错误相关的摘要（不超过 500 字）
3. 如果用户只提供了部分 UUID，提醒用户提供完整的 UUID
4. 用户必须提供 RunUuid 或 RunGroupId（至少一个），Uin 默认自动获取
5. WDL 批次模式只回 Uuid 列表，不会返回子任务的深度日志，想看详细日志必须二次调用
6. NF 引擎下传 RunGroupId 与传 RunUuid 等价，直接返回完整 Run 详情，无需二次调用
7. 如果知识库中无匹配项，展示原始错误信息并建议用户联系平台支持
8. 禁止透露任何敏感信息，包括 session_id、密码、用户名、调用的接口名称等
9. 如果认证失败（session 过期），引导用户执行 omics login
10. 诊断他人任务时需手动指定 --run-uin，否则默认使用当前登录用户的 Uin