# Fault Handling

> 当用户需要故障处理、远程主机执行脚本、服务重启、磁盘清理等运维操作时使用。通过 run-script API 执行脚本，并轮询 execution-history 获取执行结果。

- Skill: `dvcrn/fault-handling` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add dvcrn/fault-handling`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/fault-handling/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/fault-handling

---


# 故障处理 Skill

## Overview

用纯 Python 流程完成一次故障处理操作：

1. 根据用户提供的主机 IP（或从告警上下文获取）构建执行参数
2. 调用 `run-script` API 执行脚本
3. 轮询 `execution-history` API 等待执行完成
4. 输出执行结果报告

## Files

- 主入口: `skills/fault-handling/run_script.py`（完全独立，内置签名、请求等工具函数）
- 配置文件: `skills/fault-handling/.env`

## Default Workflow

用户说"故障处理""执行脚本""重启服务""重启 nginx"时，按以下顺序执行：

### 1. 确认执行参数

必须确认以下信息后才能执行：

- **主机 IP**（`ansible_host`）：从用户提供的 IP、告警上下文、或对话历史中获取。必须至少有一个主机 IP。
- **脚本**：默认使用预置脚本 `服务重启-nginx服务重启（场景演示）`（script_id=187）。用户可指定其他脚本 ID 或脚本内容。
- **organize**（主机所属组织）：可选，默认为空字符串。

如果缺少主机 IP，必须询问用户。

### 2. 执行脚本

运行：

```bash
python3 skills/fault-handling/run_script.py \
  --hosts '192.168.3.76' \
  --script-id 187
```

多主机用逗号分隔：

```bash
python3 skills/fault-handling/run_script.py \
  --hosts '192.168.3.76,192.168.3.75' \
  --script-id 187
```

也可以直接传脚本内容代替脚本 ID：

```bash
python3 skills/fault-handling/run_script.py \
  --hosts '192.168.3.76' \
  --script-type 1 \
  --script-content 'systemctl restart nginx'
```

### 3. 等待执行完成

脚本内部会：
1. 调用 `run-script` API 提交任务，获取 `execution_id`
2. 每 3 秒轮询 `execution-history` API 检查任务状态
3. 任务完成后（`is_running=false`）输出 JSON 结果

### 4. 输出结果

脚本输出 JSON 格式的执行结果，包含：
- `execution_id`: 任务 ID
- `task_name`: 任务名称
- `status`: 执行状态（1=成功，2=失败，3=部分成功，4=正在执行）
- `status_label`: 状态中文标签
- `consuming`: 耗时（秒）
- `steps`: 每个步骤的详细输出，包含每台主机的 stdout 和执行状态

### 5. 向用户汇报

基于执行结果，在回复中给出：

```text
🔧 故障处理执行报告
任务名称：{task_name}
任务ID：{execution_id}
执行状态：{status_label}
执行耗时：{consuming}秒

📋 步骤执行详情
步骤    主机IP    主机名    状态    输出
{step_name}    {ansible_host}    {host_name}    {status}    {stdout}

📌 执行结论
● ✅ {成功数}台主机执行成功
● ❌ {失败数}台主机执行失败
```

## API Reference

### run-script（执行脚本）

- URL: `/api/v6/devops/run-script`
- Method: POST
- 参数通过 `data` 字段传递 JSON 字符串

请求参数：
| 参数名 | 必选 | 类型 | 说明 |
|--------|------|------|------|
| steps>>hosts | 是 | object[] | 主机数据 |
| steps>>hosts>>ansible_host | 是 | string | 主机IP |
| steps>>hosts>>organize | 是 | string | 主机所属组织 |
| steps>>script_type | 是 | int | 脚本类型[1.shell，2.python，3.playbook，4.powershell，5.network] |
| steps>>script_id | 是 | int/string | 脚本ID，传了脚本ID，以脚本ID对应脚本内容优先 |

返回：`{ "code": 0, "data": { "execution_id": 970, "task_name": "..." } }`

### execution-history（执行历史）

- URL: `/api/v6/devops/execution-history`
- Method: POST

请求参数：
| 参数名 | 必选 | 类型 | 说明 |
|--------|------|------|------|
| execution_id | 是 | int | 任务ID |

返回参数：
| 参数名 | 类型 | 说明 |
|--------|------|------|
| is_running | boolean | 任务是否执行中 |
| detail>>status | int | 执行结果[1.成功，2.失败，3.部分成功，4.正在执行] |
| detail>>output | object[] | 步骤输出列表 |
| detail>>output>>hosts | object[] | 每台主机的输出 |
| detail>>output>>hosts>>stdout | string | 输出内容 |
| detail>>output>>hosts>>status | int | 执行状态[1.成功，2.失败，3.部分成功，4.正在执行] |

## Preset Scripts

| 脚本名称 | 脚本ID | 脚本类型 | 说明 |
|----------|--------|----------|------|
| 服务重启-nginx服务重启 | 187 | 1 (shell) | nginx服务重启脚本 |
| 主机磁盘空间清理 | 197 | 1 (shell) | 磁盘空间清理脚本 |

## Hard Rules

- 这是纯 Python skill。不要调用 `node`、`tsx`、`index.ts`。
- 执行前必须确认主机 IP，不能猜测或使用占位 IP。
- `run-script` API 的 `data` 字段是 JSON 字符串，不是嵌套对象。脚本已处理此序列化。
- 轮询 `execution-history` 时最多等待 300 秒（5 分钟），超时则报告任务仍在执行中。
- 不要在脚本执行完成前就声称"执行成功"，必须等到轮询结果确认。
- 如果 API 返回错误或 `code != 0`，必须立即报告错误，不要重试。
- 默认脚本 ID 为 187（nginx 服务重启场景演示），用户可通过参数覆盖。

## Configuration

需要以下环境变量：

- `LWJK_API_URL`
- `LWJK_API_SECRET`

从 `skills/fault-handling/.env` 读取。

## Common Commands

使用预置脚本执行故障处理：

```bash
python3 skills/fault-handling/run_script.py --hosts '192.168.3.76' --script-id 187
```

指定主机组织：

```bash
python3 skills/fault-handling/run_script.py \
  --hosts '192.168.3.76' \
  --organizes '' \
  --script-id 187
```

仅提交任务不等待结果：

```bash
python3 skills/fault-handling/run_script.py \
  --hosts '192.168.3.76' \
  --script-id 187 \
  --no-wait
```

查询已有任务执行结果：

```bash
python3 skills/fault-handling/run_script.py --query 970
```

## Completion Checklist

完成前必须自检：

- 已确认主机 IP 来源合法（用户提供或告警上下文）
- 已成功调用 `run-script` API 并获取 `execution_id`
- 已轮询 `execution-history` 直到任务完成或超时
- 已向用户展示完整的执行结果报告
- 报告包含每台主机的执行状态和输出内容
- 如果执行失败，已明确说明失败原因