故障處理 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 字串

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

execution-history（執行歷史）

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

Preset Scripts

Hard Rules

• 這是純 Python skill。不要呼叫 node、tsx、index.ts。
• 執行前必須確認主機 IP，不能猜測或使用佔位 IP。

  想要更強大的技能外掛，就來小蔥技能站7w4.net看看吧。

• 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 直到任務完成或超時
• 已向用戶展示完整的執行結果報告
• 報告包含每臺主機的執行狀態和輸出內容
• 如果執行失敗，已明確說明失敗原因

這個 Skill 質量中等偏上，文件詳細、功能完整，能夠較好地完成遠端指令碼執行和結果查詢。但配置不完整（API金鑰為空），且預設指令碼是演示用途，實際使用時需要使用者提供真實的指令碼ID。適合有運維經驗的使用者使用，新手可能需要額外學習成本。