t195：失敗重試加指數退避＋上限——一個壞檔不再拖住整個資料夾

leo 2026-08-05：「有封測者在等，一直出錯」「已經等了幾天了」

## 病（leo 實撞，log 實證）
`小果被AFTEE詐貸.pdf` 雲端 401 失敗後，**manifest 完全不記失敗**
⇒ 下輪掃描又當「新檔」⇒ **1387 輪、跨 11 小時**，每輪 3.2~3.8 秒全在撞同一面牆；
且它排在佇列前面 ⇒ **整個資料夾的同步被一個壞檔拖住**。
leo：「原先萃檔案速度也快，現在花了十幾分才萃完」——**萃取沒變慢，慢的是重試**
（log 的 `FOREACH 所有 5 項目均失敗` 證明卡早就萃好了）。

**這是獨立於 401 的架構缺陷**：401 修好了，下次換別的錯照樣卡死。

## 修
· ManifestEntry 加 FailCount / LastFailAt / NextRetry
· MarkFailed()：退避階梯 1m→5m→15m→1h→6h（之後維持 6h）
· ShouldRetry()：退避窗口內跳過；連續失敗 8 次暫停自動重試
  force（使用者按「立刻同步」）忽略退避與上限——**人明確要求不該被機器擋住**
· MarkIngestedBy() 成功時清空失敗狀態（下次再壞從第一階重算）
· direct.go 三個失敗出口都記退避（讀檔失敗／萃取失敗／上傳失敗）
· retrySkipReason()：跳過時說人話，不靜默（同 t195 燈號誠實原則）

## 🔴 真兇其實有兩層——第二層才是關鍵
只加退避欄位**沒有用**：`scan.go` 每輪都**重建** ManifestEntry，
原本只 carry IngestedHash/IngestedAt ⇒ 我寫進去的 fail_count 下一輪就被抹掉
⇒ 退避永遠停在「第 1 次失敗」＝等同沒有退避。
（順帶發現 ExtractedBy(t73「誰萃的」)原本也一直悄悄丟失。）
⇒ scan.go carry 補齊四個欄位，並留註解：**日後新增跨輪欄位必須加在這裡**。

## 驗（真實跑，非只有單元測試）
單元測試 6 項全過（退避窗口／指數遞增 60/300/900/3600/21600/21600／
上限停止／force 忽略／成功清空／壞檔不連累同輪其他檔）
實跑（cypher_url 指向不存在主機製造必失敗）：
  第 1 輪 failed
  第 2 輪 skipped「上次失敗（第 1 次），1m0s 後重試」
  第 3 輪 skipped（同上）
  第 4 輪 skipped（同上）
  模擬退避到期 → 確實重送、fail_count=2、退避升為 300s ✅
go test ./... 全綠；go vet 通過。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

direct.go

@@ -82,6 +82,11 @@ type DirectConfig struct {
 	CardIngestWF string  `json:"card_ingest_workflow,omitempty"` // 收卡 workflow（空＝rag_ingest_card）
 	PollSec      int     `json:"poll_interval_sec"`              // 輪詢間隔秒（空/0＝5）
 	MaxRemoved   float64 `json:"max_removed_ratio"`              // 大量刪除防呆門檻（空/0＝0.4）
+
+	// ForceSync＝這一輪是使用者按「立刻同步」觸發的（t195）。
+	// 為真時忽略失敗退避與次數上限，一律重送——**人明確要求時不該被機器的退避擋住**。
+	// 不寫進 config.json（`json:"-"`）：它是單次執行旗標，不是使用者設定。
+	ForceSync bool `json:"-"`
 }
 
 // librarySlug 把資料夾名轉成合法庫名（A-Za-z0-9_-；中文等非 ASCII 轉為底線分段）。
@@ -681,6 +686,23 @@ func saveDirectConfig(configPath string, cfg *DirectConfig) error {
 }
 
 // runDirectOnceRoot 對單一根掃一輪、直送 added/modified/renamed、下架 removed，2xx 後回寫該根 manifest。
+// retrySkipReason 產生「為什麼這輪跳過」的人話（t195）。
+// 靜默跳過會讓使用者以為檔案被忽略了——狀態要說得出理由（t195 燈號誠實原則同源）。
+func retrySkipReason(m *Manifest, path string, now int64) string {
+	e, ok := m.Entries[path]
+	if !ok {
+		return "暫時跳過"
+	}
+	if e.FailCount >= MaxFailBeforeSkip {
+		return fmt.Sprintf("連續失敗 %d 次，已暫停自動重試（改檔或按「立刻同步」會再試）", e.FailCount)
+	}
+	wait := e.NextRetry - now
+	if wait < 0 {
+		wait = 0
+	}
+	return fmt.Sprintf("上次失敗（第 %d 次），%s 後重試", e.FailCount, (time.Duration(wait) * time.Second).String())
+}
+
 func runDirectOnceRoot(cfg *DirectConfig, root string, dryRun bool) ([]DirectResult, int, *TriggerPayload) {
 	results := []DirectResult{}
 	exit := 0
@@ -719,10 +741,24 @@ func runDirectOnceRoot(cfg *DirectConfig, root string, dryRun bool) ([]DirectRes
 			// renamed 在 direct 模式視同 added：內容未變但為求 kbdb 有這頁名的卡，重送一次萃取
 			//（頁名可能改變＝要新頁名的卡）。冪等由 kbdb 端承擔（同頁名覆蓋語意）。
 			res := DirectResult{Type: ev.Type, Path: ev.Path}
+			// 🔴 t195 止血點：這個檔剛失敗過且還在退避窗口內 → 這輪跳過。
+			//   沒有這道閘時的實測災情：`小果被AFTEE詐貸.pdf` 因雲端 401 失敗，
+			//   每輪重掃又被當成新檔 ⇒ **1387 輪、跨 11 小時**，且它排在佇列前面，
+			//   **整個資料夾的同步被一個壞檔拖住**（leo：「原先萃檔案速度也快，
+			//   現在也花了十幾分才萃完」——萃取沒變慢，慢的是重試）。
+			//   退避階梯 1m→5m→15m→1h→6h；連續失敗 8 次後暫停自動重試。
+			//   使用者改檔（hash 變）或按「立刻同步」時仍會重試，不會永久卡死。
+			if !m.ShouldRetry(ev.Path, now, cfg.ForceSync) {
+				res.Status = "skipped"
+				res.Error = retrySkipReason(m, ev.Path, now)
+				results = append(results, res)
+				continue
+			}
 			full := filepath.Join(absRoot, filepath.FromSlash(ev.Path))
 			content, rerr := os.ReadFile(full)
 			if rerr != nil {
 				res.Status, res.Error = "failed", "讀檔失敗："+rerr.Error()
+				m.MarkFailed(ev.Path, now) // t195：讀不到的檔也退避（權限／被鎖／壞掉的外接碟）
 				results = append(results, res)
 				exit = 1
 				continue
@@ -756,6 +792,9 @@ func runDirectOnceRoot(cfg *DirectConfig, root string, dryRun bool) ([]DirectRes
 				}
 				if xerr != nil {
 					res.Status, res.Error = "failed", "本地萃取失敗："+xerr.Error()
+					// t195：萃取階段失敗同樣要記退避。**這條路徑比上傳更早**，
+					// 漏記的話（連不上知識庫、金鑰壞、模型錯）照樣每輪重撞。
+					m.MarkFailed(ev.Path, now)
 					results = append(results, res)
 					exit = 1
 					continue
@@ -789,6 +828,9 @@ func runDirectOnceRoot(cfg *DirectConfig, root string, dryRun bool) ([]DirectRes
 					// 記下是誰萃的（t73/leo 07-27）：換萃取器時才分辨得出哪些卡是舊的。
 					m.MarkIngestedBy(ev.Path, ev.SourceHash, now, cfg.Extractor)
 				} else {
+					// t195：記下失敗並排定退避，否則下輪又把它當新檔重試
+					//（實撞：1387 輪 × 11 小時全在撞同一面 401 的牆，還拖住整個佇列）。
+					m.MarkFailed(ev.Path, now)
 					exit = 1
 				}
 				results = append(results, res)