mistakes：Workers AI 額度用完／掃描版 PDF——兩個「不是 bug 但要說清楚」的已知現象

cmd/arcrun-app/app.go

@@ -278,6 +278,32 @@ type UIFailItem struct {
 // maxFailShown＝最多列幾份（多了會洗版；總數仍照實講）。
 const maxFailShown = 8
 
+// humanizeFailure 把 collector 的技術錯誤翻成使用者看得懂、而且**知道要不要行動**的一句話。
+//
+// 🔴 leo 2026-08-06 實測，兩個真實案例（從他 Windows 的 collector.log 挖出來的）：
+//
+//	① `4006: you have used up your daily free allocation of 10,000 neurons`
+//	   ＝ Cloudflare Workers AI **當日免費額度用完**。不是檔案的問題、也不是壞掉，
+//	     明天會自動恢復。使用者若不知道，只會以為程式壞了、反覆重丟。
+//	② `轉檔失敗（…pdf）：檔案裡沒有可抽取的文字`
+//	   ＝ 那份 PDF 是**掃描的圖片**，沒有文字層。要嘛做 OCR，要嘛換一份。
+//
+//	兩件事的處置完全相反（一個等就好、一個要動手），所以**不能都叫「失敗」了事**。
+func humanizeFailure(raw string) string {
+	switch {
+	case strings.Contains(raw, "neurons"), strings.Contains(raw, "4006"):
+		return "今天的免費 AI 額度用完了 ⇒ 明天會自動恢復，這些檔案會自己補上，你不用做什麼。" +
+			"（想馬上處理可以到 Cloudflare 升級 Workers Paid 方案）"
+	case strings.Contains(raw, "沒有可抽取的文字"):
+		return "這份 PDF 看起來是掃描的圖片，沒有文字可以讀 ⇒ 需要先做文字辨識（OCR），或換一份有文字的版本。"
+	case strings.Contains(raw, "尚未支援的檔案格式"):
+		return "這種檔案格式還讀不了 ⇒ 先另存成 PDF 或 Word（.docx）再放回同一個資料夾。"
+	case strings.Contains(raw, "後重試"):
+		return raw + "（上面是自動重試的排程，真正的原因是前一次失敗）"
+	}
+	return raw
+}
+
 func buildFailures(s syncStatus) *UIFailures {
 	if len(s.Failures) == 0 {
 		return nil
@@ -293,7 +319,7 @@ func buildFailures(s syncStatus) *UIFailures {
 		}
 		u.Items = append(u.Items, UIFailItem{
 			Name:   filepath.Base(f.Path),
-			Reason: f.Error,
+			Reason: humanizeFailure(f.Error),
 		})
 	}
 	return u