架構¶

TranscriptFlow 透過可復原的多階段狀態機，把字幕檔案庫轉成 RAG 就緒的 LanceDB 知識庫。

端到端流程¶

flowchart TD
  SRT[SRT / 字幕] --> Manifest[主清單]
  Manifest --> Status[batch_status_*.json]
  Status --> Watchdog[auto_watchdog.py]
  Watchdog --> P1[階段：chunking]
  P1 --> P2[階段：summarizing]
  P2 --> P3[階段：embedding]
  P3 --> P4[階段：db_inserting]
  P4 --> DB[(LanceDB)]

  P1 --> SM[parse_srt + semantic_chunk / Smart Merge]
  P2 --> SP[summarize_pipeline + llm_client]
  P3 --> BE[batch_embedding + circuit breaker]
  P4 --> FIN[finalize + 冪等 upsert]

精簡一覽：

SRT 字幕 → 語意區塊 → 摘要/標籤 → 嵌入向量 → LanceDB

元件對照¶

SRT 檔案 + 主清單
        |
        v
batch_status_*.json
        |
        v
auto_watchdog.py
        |
        +--> summarize.py --phase chunking
        |       parse_srt.py → semantic_chunk.py
        |
        +--> summarize.py --phase summarizing
        |       summarize_pipeline.py
        |
        +--> summarize.py --phase embedding
        |       batch_embedding.py
        |
        +--> summarize.py --phase db_inserting
                finalize.py → LanceDB

區域	角色
主清單	頂層為 `files[]` 的主 JSON；每筆需 `id`、`path_srt`、`path_mp3`、`filename_srt`、`filename_mp3`（由 `generate_manifest.py` 產生／由 `init_batch` 讀取）
狀態管理	初始化批次、狀態轉換、卡住任務處理（`state_manager.py`）
看門狗	掃描狀態、排程階段、強制並發／逾時（`auto_watchdog.py`）
區塊切割	確定性結構：視窗、相似度、斷點
摘要	LLM 摘要／標籤，含區塊重試與檢查點
嵌入	批次向量、維度檢查、斷路器
定稿／DB	驗證後的記錄，合併插入 LanceDB

階段¶

階段	旗標	主要工作
1	`chunking`	解析 SRT → Smart Merge 語意區塊
2	`summarizing`	產生摘要、標籤與相關元資料
3	`embedding`	批次嵌入區塊文字（驗證維度）
4	`db_inserting`	寫入 RAG 就緒列到 LanceDB

正式執行可用看門狗驅動；除錯與驗證單一檔案時可呼叫 summarize.py --phase …。

狀態機¶

每個檔案狀態會經過工作中狀態與佇列緩衝。快樂路徑：

undone
  → chunking → queueing_1
  → summarizing → queueing_2
  → embedding → queueing_3
  → db_inserting → done

失敗／復原：

failed → undone          （重試）
（重試額度耗盡／終態）→ failed_permanent

stateDiagram-v2
  [*] --> undone
  undone --> chunking
  chunking --> queueing_1
  chunking --> summarizing: direct handoff
  queueing_1 --> summarizing
  summarizing --> queueing_2
  summarizing --> embedding: direct handoff
  queueing_2 --> embedding
  embedding --> queueing_3
  embedding --> db_inserting: direct handoff
  queueing_3 --> db_inserting
  db_inserting --> done
  failed --> undone: retry
  note right of failed
    超過 max_working_time_sec
    的卡住任務可被重設以利復原
  end note

設計重點：

佇列狀態（queueing_1 … queueing_3）在階段之間暫存工作，讓看門狗能遵守並發。部分轉換在階段直接交接時可能略過佇列緩衝。
工作中階段可受控重設回 undone；failed 也會回到 undone 以重試。
反覆或終端問題進入 failed_permanent（終態）。
超過 watchdog.max_working_time_sec 的進行中任務可被重設以利復原。
批次初始化的預檢可能提前把不可用輸入標成永久失敗。
failed 可重試（回到 undone）；failed_permanent 為終態（包含初始化預檢時 SRT／MP3 路徑不存在）。

精確轉換邊由 state_manager.py（_VALID_TRANSITIONS）強制；無效跳躍會被拒絕，而非靜默套用。

主清單形狀¶

管道不會把清單當成帶鬆散 file_id／可選媒體欄位的裸陣列。init_batch 會載入主物件，並依 陣列索引 迭代 files：

{
  "total_count": 1,
  "files": [
    {
      "id": 0,
      "path_srt": "./data/sample.srt",
      "path_mp3": "./data/sample.mp3",
      "filename_srt": "sample.srt",
      "filename_mp3": "sample.mp3"
    }
  ]
}

每檔必要欄位（由 scripts/generate_manifest.py 寫出、init_batch 讀取）：

欄位	角色
`id`	成為批次狀態中的管道 `file_id`（產生時通常等於陣列索引）
`path_srt`	磁碟上 `.srt` 的絕對或專案相對路徑
`path_mp3`	對應的 `.mp3` 路徑
`filename_srt` / `filename_mp3`	存在狀態列上的檔名元資料

初始化預檢在 path_srt 或 path_mp3 不存在於磁碟時，會把該列標為 永久失敗（failed_permanent，並寫入 init 錯誤紀錄）。請優先用 python3 scripts/generate_manifest.py（或 --dry-run）產生有效清單，而非手改範例檔。

設計原則¶

結構用確定性邏輯，不用 LLM 時間戳 — 模型不擁有分段邊界。
長任務可恢復 — 檢查點、狀態檔、區塊層級重用。
失敗關閉 — 部分摘要、部分嵌入、架構不符會停止進度。
失敗可觀測 — 診斷、狀態欄位、稽核工具，勝過靜默損壞。
儲存冪等 — 穩定的 file_id／chunk_id 鍵，安全重跑。

輸入與輸出（概念）¶

	說明
輸入	`.srt` 檔、主清單、環境變數 + `config.json`、OpenAI 相容聊天／嵌入 API
過程	批次狀態 JSON、階段產物、檢查點、模型診斷
輸出	LanceDB 資料表（例如設定的 `tables.final_db`），每個 chunk ID 一邏輯列

安裝與首次執行指令請見快速開始。