# 05｜AI Troubleshooter

## 前置條件

這一章你可以在任何時候打開，不需要先讀完前面的章節。

只需要準備兩樣：

| 你需要什麼 | 怎麼取得 |
|---|---|
| 你最後一個確定成功的步驟 | 打開 [人工版 Setup Checklist](SETUP_CHECKLIST.md)，找你最後一個打勾的那一格 |
| 一份不含秘密的錯誤證據 | 下面的〈官方證據橋〉會告訴你，各層分別要去哪裡取得 |

兩樣都還沒有也可以繼續讀；下面的〈先填診斷卡〉會帶你整理出來。

## 先知道一件事

卡住不代表你不適合 AI。

第一次導入會遇到：

- 找錯頁面。
- 用錯帳戶。
- 設定值放錯位置。
- Webhook 沒有真的連通。
- 執行環境有錯誤。
- 模型連接或權限出問題。

AI Troubleshooter 的任務不是丟給你一大串 FAQ。

它要陪你做四件事：

> 理解狀況 → 定位問題 → 指出最小下一步 → 必要時交接人工

## 第一條安全規則

不要把以下內容貼給我方、ChatGPT、任何公開聊天室或不明支援表單：

- API Key
- Channel Secret
- Channel Access Token
- Cookie
- 密碼
- OAuth refresh token
- 客戶姓名、電話、地址或完整對話

你可以貼：

- 錯誤文字中不含秘密的部分。
- 官方頁面顯示的錯誤類型。
- HTTP 狀態碼。
- 最後成功的 stage。
- 大概發生時間。
- 你看到的非敏感畫面描述。

## 先填診斷卡

~~~text
目前階段：

我想完成的事情：

我已經確定完成：

最後一個確定成功的步驟：

我現在看到的畫面或錯誤：

錯誤發生的大概時間：

我使用的路徑：
例如：LINE＋Gemini＋自己的 GAS

我沒有提供：
API Key、Channel Secret、Access Token、Cookie、密碼或客戶個資
~~~

把這張卡貼給 ChatGPT 時，可直接使用 [TROUBLESHOOT_TASK](ai-assist/TROUBLESHOOT_TASK.md)。

## 不要先全部重做

排錯的第一個問題不是：

> 要不要重新建立全部帳戶？

而是：

> 最後一個確定成功的層在哪裡？

從那裡往後檢查，通常比全部重做更快，也比較不會產生重複帳戶和混亂設定。

## 依症狀找最小檢查

| 你看到的情況 | 先判斷哪一層 | 下一個最小檢查 | 修好後回到哪一步 |
|---|---|---|---|
| 找不到官方頁面或按鈕 | 人類操作層 | 確認登入帳戶與官方頁面 | 如果你正在做 LINE 設定 → [02](02-建立官方-LINE.md) 的 Step 1；如果你正在做 Gemini 金鑰 → [03](03-接入-Gemini.md) 的 Step 1 |
| URL 看起來不完整，或不確定是不是最新部署的那一個 | 資料格式層 | 重新從自己的部署頁複製 URL | [Setup Checklist](SETUP_CHECKLIST.md) §2 的「我知道 Web App URL 從哪裡取得」 |
| URL 已確認正確，但 LINE Verify 仍失敗 | 連通性層 | 檢查部署權限與 HTTP 回應 | [Setup Checklist](SETUP_CHECKLIST.md) §4 的「我把自己的 Web App URL 填入官方 LINE 設定」 |
| LINE 沒有送到執行環境 | webhook 層 | 查看官方 webhook error statistics | [Setup Checklist](SETUP_CHECKLIST.md) §4 的「我已啟用需要的 webhook 設定」 |
| 你改了程式碼，但 AI 的回覆還是舊的樣子 | 部署層 | 確認改完之後有沒有**重新部署**——只按儲存不會生效 | [03｜接入 Gemini](03-接入-Gemini.md) 的 Step 6，照那裡〈以後每次改程式碼，都要再部署一次〉做一次 |
| 執行環境有錯誤 | 執行層 | 查看自己的 execution evidence | [Setup Checklist](SETUP_CHECKLIST.md) §2 的「我知道設定會保存在哪個自己的位置」 |
| Gemini 回傳錯誤 | provider 層 | 確認模型、配額、權限與非秘密錯誤訊息 | [03｜接入 Gemini](03-接入-Gemini.md) 的〈這一章的成功判定〉，逐項重新確認一次（🔴 **不要重建 API Key**） |
| 有執行但 LINE 沒回覆 | 回程層 | 找最後一個成功點與回覆動作錯誤 | [04｜看到第一個 AI 回覆](04-看到第一個-AI-回覆.md) 的〈確認三：LINE 回傳回覆〉 |
| 以上都不是我的情況 | 先不分層 | 回到上面的〈先填診斷卡〉，把「最後一個確定成功的步驟」寫出來 | [Setup Checklist](SETUP_CHECKLIST.md) 裡你最後一個打勾的那一格 |

🔴 **修好之後，回到上表指定的那一步，照原本的順序繼續。** 這一章只負責把你送回主線，不介紹新東西。

表格裡的「§2」「§4」指的是 [Setup Checklist](SETUP_CHECKLIST.md) 裡的 `## 2.` `## 4.` 那兩節；引號裡的句子就是那一節裡的某一格。

如果 AI 有回覆、流程也跑得通，只是**回覆內容不符合你的工作**——這不是故障，是第一個小工作還沒定義清楚。回到 [01｜選擇你的第一個小工作](01-選擇你的第一個小工作.md) 的〈先填這張小工作卡〉重寫一次，不必排錯。

## 官方證據橋

### LINE URL Verify

LINE 官方的這個驗證，測的是「LINE 連不連得到你那個網址」。官方文件：[Verify webhook URL](https://developers.line.biz/en/docs/messaging-api/verify-webhook-url/)。

> 🔴 **它顯示 `Success`，不代表你的設定是對的。** 連得到、接得住、答得出來，是三件事。所以「`Verify` 是 `Success`，但傳訊息沒有回覆」**是會發生的正常情況，不是矛盾**——這種時候回到上面〈依症狀找最小檢查〉，找「執行環境有錯誤」或「有執行但 LINE 沒回覆」那兩列，不要回頭一直重按 `Verify`。

你要記錄的是：

- Verify 成功或失敗。
- 官方顯示的錯誤。
- 驗證時間。
- 你使用的 URL 是否為自己最新部署的 URL。

### LINE webhook error statistics

如果 webhook 沒有收到，可以查看 LINE 官方的錯誤統計。官方文件：[Check webhook error causes and statistics](https://developers.line.biz/en/docs/messaging-api/check-webhook-error-statistics/)。

錯誤分類可以幫你分辨：

- 連不上。
- 回覆太慢。
- 你的網址有回應，但回的是錯誤狀態。
- 未分類錯誤。

### GAS execution evidence

如果你使用自己的 GAS，請從自己的 execution log 或 logging 找證據。官方文件：[Apps Script Logging](https://developers.google.com/apps-script/guides/logging)。

只回報：

- 執行時間。
- 是否失敗。
- 非敏感錯誤類型。
- 哪個 function 或階段失敗。

## 什麼時候交給人

以下情況可以直接選擇人工協作：

- 你不確定目前登入的是哪個帳戶。
- 你看到可能產生費用或權限變更的畫面。
- 你懷疑秘密可能外洩。
- 你需要修改正式環境。
- 你已經重試兩次但沒有新的證據。
- 問題已經不是設定問題，而是公司規則與工作流程設計。

人工接手不是失敗。

好的交接應該保留：

- 已完成的事情。
- 最後成功的步驟。
- 現在的症狀。
- 已取得的非秘密證據。
- 不可提供的秘密清單。
- 你希望對方先幫忙判斷的事情。

## 這一章的完成條件

你不一定要把問題修好才算完成本章。

只要你能：

- 找到最後一個成功點。
- 把問題放進一個層級。
- 取得至少一份官方或執行證據。
- 知道下一個最小檢查。
- 知道何時交給人工。

你就已經開始使用 AI 經理人的最小能力：理解狀況、判斷與推進。