5why-analyzer/系統使用說明書.md

5 Why 根因分析系統 - 使用說明書

版本: 1.3.0 更新日期: 2025-12-08

---

目錄

1. 系統概述
2. 系統架構
3. 使用流程
4. 功能說明
5. 優化設計
6. 常見問題

---

1. 系統概述

1.1 什麼是 5 Why 分析法？

5 Why 分析法是一種根因分析技術，透過連續追問「為什麼」來深入探究問題的根本原因，而非停留在表面症狀。

1.2 系統目標

本系統整合 AI 大型語言模型（LLM），協助使用者：

• 快速進行根因分析：AI 從多個角度自動生成 5 Why 分析
• 確保分析品質：遵循五大執行要項，避免常見錯誤
• 提供永久對策：聚焦系統性解決方案，而非暫時性補救

1.3 系統特色

特色	說明
多角度分析	自動從 3 個不同角度（流程面、系統面、管理面等）進行分析
邏輯檢核	每個分析自動進行順向/逆向邏輯驗證
多語言支援	支援繁中、簡中、英、日、韓、越、泰 7 種語言
歷史記錄	自動保存所有分析記錄，可隨時查詢

---

2. 系統架構

2.1 技術架構

┌─────────────────────────────────────────────────────────┐
│                      使用者介面                          │
│                   (React + Tailwind CSS)                 │
├─────────────────────────────────────────────────────────┤
│                      後端服務                            │
│                   (Node.js + Express)                    │
├──────────────────┬──────────────────┬───────────────────┤
│   MySQL 資料庫    │   Session 管理   │    LLM API        │
│  (分析記錄儲存)   │   (使用者認證)   │  (DeepSeek/Ollama)│
└──────────────────┴──────────────────┴───────────────────┘

2.2 模組說明

模組	功能
認證模組	使用者登入、登出、密碼管理
分析模組	5 Why 分析、翻譯、歷史查詢
管理模組	使用者管理、LLM 配置、稽核日誌

---

3. 使用流程

3.1 整體流程圖

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│   登入   │ -> │ 輸入問題 │ -> │ AI 分析  │ -> │ 查看結果 │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
                     │                              │
                     v                              v
              ┌──────────────┐              ┌──────────────┐
              │ 選擇輸出語言  │              │ 翻譯/匯出   │
              └──────────────┘              └──────────────┘

3.2 詳細操作步驟

步驟 1：登入系統

1. 開啟系統網址 http://localhost:5176
2. 輸入帳號（Email 或工號）與密碼
3. 點擊「登入」按鈕

測試帳號：

角色	Email	密碼
超級管理員	admin@example.com	Admin@123456
管理員	manager@example.com	Manager@123456
一般使用者	user@example.com	User@123456

步驟 2：輸入分析內容

在「5 Why 根因分析」頁面：

1. 發現的現象（必填）

   • 描述您觀察到的問題或異常
   • 範例：「伺服器每週二凌晨 3 點當機」

2. 工作內容/背景（必填）

   • 提供相關的背景資訊
   • 包含：系統環境、作業流程、相關人員等

3. 輸出語言

   • 選擇分析結果的語言

步驟 3：執行分析

1. 點擊「開始分析」按鈕
2. 等待 AI 處理（約 30-60 秒）
3. 系統會顯示分析進度

步驟 4：查看結果

分析完成後，會顯示：

┌─────────────────────────────────────────────────────┐
│ 問題重述 (5W1H)                                      │
│ ─────────────────────────────────────────────────── │
│ [AI 用 5W1H 格式重新描述問題]                        │
├─────────────────────────────────────────────────────┤
│ 🔄 流程面分析                                        │
│ ─────────────────────────────────────────────────── │
│ Why 1: [問題] → [答案] ✓已確認                       │
│ Why 2: [問題] → [答案] ⚠待驗證                       │
│ Why 3: [問題] → [答案] ✓已確認                       │
│                                                     │
│ 🎯 根本原因：[分析結果]                              │
│                                                     │
│ 🔄 邏輯檢核：                                        │
│    ➡️ 順向：如果[原因]發生，則[結果]必然發生         │
│    ⬅️ 逆向：如果消除[原因]，則[結果]不會發生         │
│                                                     │
│ 💡 永久對策：[系統性解決方案]                        │
│    行動項目：                                        │
│    • [具體行動 1]                                    │
│    • [具體行動 2]                                    │
└─────────────────────────────────────────────────────┘

---

4. 功能說明

4.1 分析功能

4.1.1 多角度分析

系統自動從 3 個不同角度進行分析：

• 流程面：作業流程、標準程序
• 系統面：技術系統、設備機制
• 管理面：管理制度、監督機制

4.1.2 5 Why 深度追問

每個角度會進行 3-5 次「為什麼」追問：

Why 1: 為什麼發生 A？ → 因為 B
Why 2: 為什麼發生 B？ → 因為 C
Why 3: 為什麼發生 C？ → 因為 D（根本原因）

4.1.3 邏輯雙向檢核

每個分析包含邏輯驗證：

• 順向檢核：如果原因發生，結果是否必然發生？
• 逆向檢核：如果消除原因，結果是否就不會發生？

4.2 管理功能（僅管理員）

4.2.1 儀表板

• 分析統計（總數、成功率、平均處理時間）
• 使用者活動統計
• 系統健康狀態

4.2.2 使用者管理

• 新增/編輯/停用使用者
• 角色權限設定
• 密碼重設

4.2.3 LLM 配置

• 新增/編輯 LLM 端點
• 模型選擇與參數調整
• 連線測試

4.2.4 LLM 測試台

• 動態載入可用模型
• 快速連線測試
• 互動式對話測試

---

5. 優化設計

5.1 分析品質優化

5.1.1 五大執行要項

系統 Prompt 內建五大執行要項，確保分析品質：

要項	說明
精準定義問題	使用 5W1H 描述現象，而非結論
聚焦流程與系統	追問「系統為何允許疏失發生」
基於事實	每個 Why 標註「已確認」或「待驗證」
邏輯檢核	順向+逆向雙向驗證
可執行對策	永久性系統解決方案

5.1.2 Prompt 精簡化

優化前：80+ 行複雜 Prompt
優化後：15 行精簡 Prompt

效果：
- 減少 LLM 混淆
- 提高 JSON 格式正確率
- 降低回應被截斷風險

5.2 技術優化

5.2.1 JSON 解析強化

多層修復策略處理 LLM 輸出格式問題：

1. 清理特殊標記（```json、<think>等）
2. 提取 { 到 } 之間的純 JSON
3. 修復常見格式問題（尾部逗號、缺少逗號）
4. 補齊未閉合的括號

5.2.2 API 參數優化

// 問題：DeepSeek 限制 max_tokens 最大 8192
// 解決：動態限制在 4000-8000 之間
const effectiveMaxTokens = Math.min(
  Math.max(parseInt(llmConfig.max_tokens) || 4000, 4000),
  8000
);

// 問題：temperature 為字串導致 API 錯誤
// 解決：確保轉換為數字
const effectiveTemperature = parseFloat(llmConfig.temperature) || 0.7;

5.3 使用者體驗優化

5.3.1 結果視覺化

• 分析角度以卡片式呈現
• Why 層級以縮排+左邊界線區分
• 已確認/待驗證以顏色標記
• 根本原因、邏輯檢核、永久對策區塊化

5.3.2 載入狀態

• 分析中顯示動畫與預估時間
• 錯誤發生時顯示詳細訊息

---

6. 常見問題

Q1: 分析時間很長怎麼辦？

原因：LLM API 回應時間取決於模型負載與輸入長度

建議：

• 簡化輸入內容，聚焦關鍵資訊
• 避免在尖峰時段使用

Q2: 出現「JSON 解析失敗」錯誤？

原因：LLM 輸出格式不正確

解決：

• 點擊「重試」重新分析
• 簡化輸入內容
• 聯繫管理員檢查 LLM 配置

Q3: 分析結果不符合預期？

建議：

• 提供更詳細的背景資訊
• 明確描述問題現象（5W1H）
• 避免主觀結論，描述客觀事實

Q4: 如何切換 LLM 模型？

步驟（需管理員權限）：

1. 進入「管理員」頁面
2. 選擇「LLM 配置」Tab
3. 新增或編輯配置
4. 點擊「啟用」設為預設

---

附錄

A. 系統需求

項目	最低需求
瀏覽器	Chrome 90+、Firefox 88+、Edge 90+
網路	穩定的網際網路連線

B. 快速鍵

快速鍵	功能
Enter	在登入頁面提交表單
Ctrl+Enter	在分析頁面開始分析

C. 聯絡支援

如有問題，請聯繫系統管理員或參考：

• GitHub Issues: https://github.com/anthropics/claude-code/issues

---

文件版本: 1.0.0 編寫日期: 2025-12-08 編寫者: Development Team