🧠 適應引擎（Adaptive Engine）

讓 V-Train 學會識別任何網站的影片縮圖，自己動手教它！

---

1. 什麼是適應引擎？它解決什麼問題？

V-Train 預設支援主流影音平台，但網路上的影片網站何其多——小眾論壇、創作者自架站台、特定地區平台……這些地方的縮圖結構五花八門，V-Train 不可能全部內建支援。

適應引擎（Adaptive Engine） 就是為此而生。它讓 你 成為規則的作者：

• 🖱️ 在任何網站上，右鍵點擊影片縮圖
• 🔲 用視覺化選框框選正確的縮圖容器
• 🔗 貼上一段影片網址，點選哪一段是影片 ID
• 💾 儲存規則，之後該網站的縮圖就全部自動識別

這個過程不需要寫任何程式碼，整個訓練流程大約只需要 30 秒到 2 分鐘。

💡 類比時間

想像 V-Train 是一個剛入職的新員工，他不認識這個網站的「長相」。適應引擎就是你帶他參觀辦公室、指著每個區域說「這裡是影片縮圖區域、這是影片 ID」的過程。訓練一次，他就永遠記住了。

---

2. 使用前提：請先切換到「自動監控(Monitoring)」模式

⚠️ 重要！必須切換到自動監控(Monitoring)

適應引擎與「手動暫停(Monitoring Off)」模式無法同時使用。

如果你目前是「手動暫停(Monitoring Off)」狀態，右鍵選單點選訓練後，畫面會出現一個紅色提示（Toast 通知）說明目前無法啟動訓練。

請先前往 V-Train 彈出視窗（Popup）→ 切換到「自動監控(Monitoring)」→ 再重新嘗試。

為什麼有這個限制？手動暫停(Monitoring Off)模式會抑制 V-Train 在頁面上的各種視覺元素注入，包含訓練用的選框抓蓬層，所以兩者天生互斥。

---

3. 完整訓練步驟圖解 🗺️

訓練流程總共分為六個主要步驟：

步驟一：右鍵觸發訓練

在 任意影片縮圖 上按下滑鼠 右鍵，從瀏覽器右鍵選單中選擇：

V-Train: 啟動訓練引擎(Start Training Engine)

小技巧

不確定要右鍵哪裡？只要是影片的預覽圖片區域都可以，不用非常精準，後續你可以用鍵盤調整選取範圍。

步驟二：出現視覺化選框

訓練模式啟動後，頁面進入「訓練狀態」：

• 頁面上所有現有的 V-Train 進度條會變成 半透明（幽靈模式），讓你能清楚看到頁面原始的縮圖結構
• 一個帶顏色邊框的 選框 會出現在你右鍵點擊的元素上

步驟三：用鍵盤調整選框位置

選框顏色告訴你目前框選的元素是否正確：

顏色	意義
🔵 青色（Cyan #00F0FF）	✅ 有效目標，可以確認
🔴 紅色（#FF3333）	❌ 無效目標，需要調整

選框右上角會有一個標籤：

• 綠底白字 VALID → 可以按 Enter 確認
• 紅底白字 + 錯誤原因 → 需要移動到父層元素

使用鍵盤移動：

• ↑ 向上一層（選取父元素，範圍變大）
• ↓ 向下一層（選取子元素，範圍縮小）

步驟四：按 Enter 確認縮圖容器

選框變成青色且顯示 VALID 後，按下 Enter 確認。

系統會自動為這個元素產生一個 CSS 選擇器，例如 div.video-card，用來在頁面上識別所有相同結構的縮圖。

步驟五：在浮動面板中選擇影片 ID

確認容器後，頁面會彈出一個 覆蓋層面板：

1. 在上方輸入框貼入一段 完整的影片網址（從瀏覽器網址列複製）
2. 系統會自動把網址拆解成各個路徑段落（Path Segments）、查詢參數（Query Params）、錨點（Hash）
3. 點選 你認識的那個代表「影片 ID」的區段

請貼上相同影片的播放網址

這裡貼上的網址，必須是您剛才右鍵點擊的那張縮圖所對應的播放頁網址。點擊 A 縮圖啟動訓練，就要貼上 A 影片的網址，不能將 B 影片的網址填入這裡，否則訓練出來的規則會不正確。

步驟六：選擇存槽並儲存

點選 ID 段落後，選擇一個 存槽（Mod 1 ~ Mod 4） 並按下儲存。

訓練完成！重新整理頁面，V-Train 就會開始在這個網站上正常運作。

---

4. 選框顏色與無效原因詳解 🎨

✅ 青色（VALID）

選框顯示青色代表這個元素是合法的縮圖容器目標，你可以放心按 Enter。

❌ 紅色（INVALID）的各種原因

無效原因	說明	解法
直接選到 <img> / <picture>	圖片標籤本身不是容器	按 ↑ 選父層 <div>
直接選到 <video>	影片播放標籤本身不適合	按 ↑ 往上移
直接選到 <svg> / <canvas>	圖形標籤不是縮圖容器	按 ↑ 往上移
元素太小（< 20×20 px）	可能選到圖示或裝飾元素	按 ↑ 選更大的容器
元素已被追蹤	這個選擇器已在規則庫中	不需要重複訓練

最常見的新手錯誤

直接右鍵點到 <img> 圖片本身，然後選框一直是紅色。記住：你要選的是 包住圖片的那個外框容器（通常是一個 <div> 或 <a> 標籤），而不是圖片本身。按 ↑ 往上走一兩層就對了。

---

5. 鍵盤快捷鍵一覽 ⌨️

按鍵	功能
↑ 上箭頭	選取 父層元素（選框變大）
↓ 下箭頭	選取 子層元素（選框縮小）
Enter	確認目前選取的容器
Esc	取消訓練（回到正常模式）

實戰技巧

大多數的縮圖卡片結構是這樣的：

<div class="video-card">        ← 你要選這層
  <a href="/watch?v=...">
    <img src="thumb.jpg" />     ← 右鍵通常點到這裡
    <span class="title">...</span>
  </a>
</div>

右鍵點到 <img> 之後，按 兩次 ↑ 通常就能到達正確的 <div> 容器。

---

6. URL 影片 ID 選擇技巧 🔗

網址的結構千變萬化，V-Train 支援四種主要的 ID 位置類型：

📁 路徑型（Path Type）

網址長這樣：https://example.com/video/abc123/play

ID 在路徑的某一個段落中。V-Train 會記錄你點選的是「第幾段路徑」（first / last / index），下次看到相同結構的網址時自動擷取。

範例：

https://www.mysite.com/watch/Xk9mP2q/
                              ↑
                        點這一段（路徑第 2 段）

---

🔍 查詢參數型（Query Type）

網址長這樣：https://example.com/watch?v=dQw4w9WgXcW&t=30

ID 在 ? 後面的 key=value 參數中。

範例：

https://www.youtube.com/watch?v=dQw4w9WgXcW
                                 ↑
                           點 v=dQw4w9WgXcW 這整段

V-Train 會記住 key 是 v，之後自動從查詢參數擷取。

---

#️⃣ 錨點型（Hash Type）

網址長這樣：https://example.com/videos#ep-42

ID 在 # 後面的錨點字串中。V-Train 會記錄整個 hash 值並用來比對影片。

---

✂️ 分隔符號型（Flank / Separator Type）

有些 ID 混在一段字串裡，用特定字元分隔，例如：

https://example.com/v/channel_abc123_hd
                               ↑
                    底線分隔，abc123 才是真正的 ID

這時你可以選取整段，然後透過設定 sepIdx（分隔符號的第幾段）來精確定位 ID 的位置。

INFO

如果網址太複雜或使用非標準格式，可以考慮到 社群規則庫 看看有沒有現成的規則可以直接匯入。

---

7. 四個存槽（Mod 1 ~ Mod 4）的使用建議 💾

每個網站最多可以儲存 4 組訓練規則。為什麼需要多組？

因為許多網站的縮圖結構在不同頁面會有所不同：

存槽	建議用途
Mod 1	首頁 / 推薦頁面的縮圖卡片
Mod 2	搜尋結果頁的縮圖格式
Mod 3	頻道頁 / 用戶頁的縮圖格式
Mod 4	播放頁側欄的相關影片縮圖

實際案例

有些網站的首頁縮圖是大圖卡片（使用 div.featured-card），但搜尋結果頁是小列表（使用 li.search-result）。這兩種結構完全不同，需要分別訓練、存到不同的 Mod 槽位中，V-Train 才能在兩個頁面都正常運作。

WARNING

如果某個存槽已經有規則，覆寫前請確認你真的要替換它，因為目前沒有「還原」功能。建議先到控制面板複製該規則的 SYNC 序號備份，以防不時之需。

---

8. 規則序號分享（SYNC 格式）📋

訓練完成後，每一條規則都有一個 可分享的序號字串，格式如下：

SYNC-Z{deflate-raw base64 壓縮內容}

例如：

SYNC-ZeJyNjsEKwjAQRL...（後面接很長一串）

SYNC-Z 格式說明

• 前綴 SYNC-Z 表示這是使用 deflate-raw + Base64 壓縮的高效格式
• 可以直接複製這串文字，貼給朋友，或貼到社群規則庫的 PR 中
• 匯入時，在 V-Train 擴充功能的設定頁找到「匯入規則」功能，貼上序號即可

如何取得你的規則序號？

訓練儲存後，前往 V-Train 設定頁 → 網站規則管理 → 找到對應的網站 → 點選「匯出 / 複製序號」。

規則的完整資料結構包含：

• hosts：適用的網域陣列（如 ["example.com"]）
• pRule：縮圖容器的 CSS 選擇器規則
• tRule：影片 ID 的擷取規則（路徑型、查詢參數型等）

---

9. 社群規則庫（Community Rules）🌐

訓練很好玩，但你不必每個網站都自己從頭訓練——V-Train 有一個開放的社群規則庫：

🔗 https://github.com/vtrain-labs/community-rules

社群規則庫裡收錄了各種網站的 SYNC 序號，由社群用戶貢獻與維護。

你可以：

• 📥 下載規則：搜尋你想要支援的網站，複製 SYNC 序號匯入
• 📤 貢獻規則：把你自己訓練好的規則序號提交 Pull Request 分享給大家
• ⭐ 回報問題：如果某個規則失效了（網站改版），可以開 Issue 告知維護者
• 💬 討論交流：在 Discussions 區和其他用戶交流技巧

一起讓 V-Train 更強大

每一個人的訓練成果都可以讓整個社群受益。如果你花 2 分鐘訓練了一個小眾網站，不妨花多 1 分鐘把規則序號貢獻到社群庫，造福下一個使用相同網站的用戶！

---

10. 常見訓練問題 FAQ ❓

Q：我按下右鍵但選單裡沒有「V-Train: 啟動訓練引擎(Start Training Engine)」？

請確認：

1. V-Train 擴充功能已正常啟用（在 chrome://extensions 確認）
2. 你是在 http:// 或 https:// 的網頁上（擴充功能不作用於 chrome:// 等特殊頁面）
3. 嘗試重新整理頁面後再試一次
4. 確認已切換到「自動監控(Monitoring)」模式（見第 2 節）

---

Q：我確認了容器、也選了 ID，但儲存後重新整理頁面 V-Train 沒有反應？

可能原因：

• 選到了錯誤的容器層級：導致 CSS 選擇器太寬泛或太窄。建議重新訓練，換一層試試。
• 網站使用動態渲染（AJAX）：縮圖是 JavaScript 動態載入的，V-Train 可能需要一點時間掃描。等頁面完全載入後再觀察。
• 網站的 class 名稱是隨機產生的 hash：V-Train 會自動過濾純 hash class，但如果整個元素都是 hash class 組成，選擇器可能失效。試試看選更上層有語意 class 的父元素。

---

Q：為什麼選框一直是紅色，我怎麼按 ↑ 都不行？

如果一路按 ↑ 到了 <body> 還是紅色，可能是這個頁面的縮圖結構比較特殊。試試：

1. 重新整理頁面，從不同的縮圖位置右鍵開始
2. 在瀏覽器開發者工具（F12）先觀察縮圖的 HTML 結構，找到合適的父層

---

Q：CSS 選擇器是怎麼自動生成的？

V-Train 的選擇器生成邏輯：

• 使用元素的 標籤名稱 + 最多 2 個最具語意的 class
• 自動過濾掉：純亂碼 hash、hover / active / focus / playing / lazy / loaded 等狀態 class、純數字 class

這樣設計是為了產生穩定、不隨網站更新而失效的選擇器。

---

Q：我的規則在換電腦後還在嗎？

規則儲存在您電腦上的 chrome.storage.local（本機儲存），不會自動跨裝置同步。

如果您要在新電腦上使用相同的規則，請在舊電腦先將規則匹出序號後分享給新電腦，或利用控制面板的備份匯出功能，再在新電腦上匯入。

---

Q：一個網站訓練後規則多久生效？

立即生效。儲存完成後，重新整理該網站的頁面即可。如果仍無效，請確認 V-Train 是否已更新為最新版本。

---

如有更多問題，歡迎到 社群規則庫 開 Issue 討論！