故障处理 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. 执行脚本

运行：

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

多主机用逗号分隔：

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

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

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. 向用户汇报

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

🔧 故障处理执行报告
任务名称：{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

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

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

指定主机组织：

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

仅提交任务不等待结果：

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

查询已有任务执行结果：

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

Completion Checklist

完成前必须自检：

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