# Userscript 平台與管道
撰寫或修改轉接腳本請先看獨立的 [/chat 入口與參數文件](CHAT_API.md)，包含聊天／觀眾範例、欄位型別、測試標記與 HTTP 回應。
平台和接收管道是兩個獨立欄位。平台白名單為 TikTok、Twitch、Kick、Odysee、Youtube；
名稱不分大小寫。缺少平台、舊值 Userscript 或無法辨識的值歸為 `Unknown`，
頁面顯示「未知來源」。未知來源仍是有效熱度統計組，套用相同的留言量、
發言人數、去重及洗頻門檻，不會只因無法辨識而被排除。
- `platform`：原始訊息平台，無法取得就不猜。
- `transport`：`api`（API／直連）或 `userscript`。`/chat` 入口強制標記為 userscript。
- `msgId`：平台原始訊息 ID；沒有就傳 null，不能用隨機數冒充平台 ID。
- `sentAt`：可取得的原始發送時間；沒有就傳 null。`observedAt` 是瀏覽器看見的時間，
不會當成平台發送時間；伺服器另記錄 `receivedAt`。
- `isTest: true`：測試按鈕的合成資料，不參與自動剪輯。一般未知來源不帶此標記。
- `audienceKind: top-fans`：頭號觀眾名單大小不是總觀眾數，不納入觀眾熱度。
同平台相同 ID，跨管道只計一次；至少一邊沒有 ID 時，使用同平台、同使用者名稱、
同內容在 3 秒內跨管道出現的保守去重。不同真實 ID 不合併，同管道的無 ID 新留言
不會單憑同內容被此規則丟棄。沒有原始 ID 無法保證所有延遲情況下都能準確去重。
不同平台不因姓名或 ID 相同而互相排除。
keyword 同時顯示平台和接收管道；autoclip 平台貢獻列顯示最近觀察到的管道，
API＋Userscript 是同一個平台的兩個入口，不拆成兩份平台分數。
舊資料中的 Userscript 名稱只在畫面上標示為未知來源，不猜測或補造原始平台。
## 已更新版本
| 檔案 | 新版 |
| --- | --- |
| TikTokChat.user.js | 2.13 |
| videoTK.user.js | 2.5 |
| liveCenter.user.js | 1.18 |
| youtube-chat-userscript.user.js | 1.7 |
| TestCenter.user.js | 1.5 |
| ws-relay.user.js | 1.3（已合併 ws-relay.js） |
聊天 DOM 沒有可靠 ID／時間欄位時保留 null。TikTokChat／liveCenter 2.11／1.18 會在頁面載入後先標記既有聊天節點，並在觀察器啟動後短暫跳過補齊期，避免頁面刷新把舊聊天重播到 `/chat`；同時把節點 `id` 當成最後的 msgId fallback。TikTokChat 2.13 只在目標直播頁且分頁可見時掛 observer，離開／隱藏／停用會拆除並停止 15 秒觀眾回報，回到頁面再重新啟動。WS relay 附帶來源欄位，但仍維持原本的原始資料轉接流程，沒有新增解碼功能。未修改功能的其他腳本不更動版本。
需要更新瀏覽器中安裝的腳本，並重新啟動伺服器與聊天程序。
WS relay 統一使用 `UserScript/ws-relay.user.js`，保留 URL、二進位與文字資料轉接。
每頁首次建立 webcast-ws 連線時回報 URL，每個 Socket 只安裝一個轉接監聽器，避免網頁多次註冊 handler 時重複轉送。
`@updateURL`／`@downloadURL` 均指向此腳本自己的 GitHub raw 位址。
舊 `ws-relay.js` 已移除；若瀏覽器仍安裝舊副本，請改裝統一版本並停用重複副本。
本機修改尚未發布到 GitHub，遠端自動更新需等新版發布後才可取得。
自動剪輯預設為影子模式；正式執行條件見 [自動剪輯說明](KEYWORD_AUTOCLIP_V2.md)。
## 主服務位址（所有轉接腳本）
所有會送到本機主服務的 userscript 現在共用同一個設定鍵 `ttw-main-endpoint`，預設 `http://127.0.0.1:3332`：
| 腳本 | 版本 | 設定位置 |
| --- | --- | --- |
| TikTokChat | 2.13 | Tampermonkey 選單「設定 TTW 主服務位址」 |
| liveCenter | 1.19 | 面板「主服務位址」＋「測試主服務」；也可用選單 |
| restream-monitor | 1.3.0 | 面板「主服務位址」＋「測試主服務」；也可用選單 |
| ws-relay | 1.4 | 選單 |
| youtube-chat-userscript | 1.8 | 選單 |
| TestCenter | 1.6 | 選單 |
- 可輸入 `127.0.0.1:3332`、`http://192.168.0.102:3332` 或含路徑前綴的 `https://example.test/ttw`；會移除結尾 `/`。
- 拒絕帳密、query、hash 與非 http(s) 位址；格式錯誤會提示並保留原值。
- 設定存在各腳本自己的 GM storage；不同腳本／網域不會共用，換主機時請逐一設定。
- 面板的「測試主服務」打 `GET /ping`；`/ping` 不需要登入。舊版伺服器沒有 `/ping` 時會顯示 HTTP 404，但實際 `/chat` 仍可能可用。
- 腳本使用 `@connect *` 以支援自訂主機；腳本只會把資料送到你設定的位址，不會送到其他網域。
## Restream 自動開啟 TikTok Live Monitor
安裝 `UserScript/restream-monitor.user.js` 到支援 `GM_openInTab` 的 UserScript 管理器（例如 Tampermonkey），再開啟 `https://app.restream.io/shows/<show-id>`。不需要修改 show ID。首次安裝預設開啟自動偵測，右下角面板可暫停或手動開啟；1.2.0 起預設也會自動暫停預覽，可在面板取消。
腳本只觀察頁面中可見的官方 `https://livecenter.tiktok.com/live_monitor` 連結，保留其查詢參數；連結連續存在 3 秒後開啟背景新分頁。它不操作 Restream 的開播、停播或平台開關，也不從 Restream 樣本猜測聊天／統計資料。
- DOM 重繪不重複開頁；同一分頁重新整理時使用 sessionStorage 保留已處理狀態。
- 連結連續消失 60 秒後才允許下一輪自動處理；此規則不等於判定斷播或新場次。
- 本助手仍持有且尚未關閉的監控分頁會沿用，不主動關閉、重新整理或搶焦點。
- 手動關閉監控分頁後，不會自動反覆重開；可按「手動開啟監控頁」。開啟失敗也須手動重試。
- 只建議掛一個 Restream show 分頁；跨分頁／瀏覽器的去重尚未實作。重新整理後無法重新取得原分頁控制物件，手動開啟可能另建一頁。
- **自動暫停預覽（1.2.0，預設開啟）**：在 show 頁找 `Play Preview`／`Pause Preview` 按鈕或預覽 `video`；偵測到播放且使用者尚未手動操作時，點擊暫停或呼叫 `video.pause()`，每場最多一次。使用者手動按播放後不再自動暫停；面板可取消。只影響預覽播放，不會停止 Restream 推流或直播。
- 自動暫停依賴 Restream 目前的按鈕文字與相鄰 `video` 結構；若 Restream 改版導致找不到，功能會靜默停用，不影響監控連結與其他操作。
- **Restream 指標（1.3.0）**：從 show 頁的 `Health`、`Resolution`、`Bitrate`、`Frame rate`、`Keyframe interval` 取文字值，送到 `POST /restream/metrics`；每 60 秒或數值變更時送一次，缺欄位送 null，不猜 0。面板顯示目前指標與最後傳送結果，也可按「指標頁」開啟 `/restream`。
- 伺服器只在記憶體保存每個 showId 最新一筆與最近 120 筆（最多 20 場、24 小時），不寫交通場次、SQLite 或 `/chat`；`/restream` 需主服務登入，`POST /restream/metrics` 與 `/chat` 一樣供本機 userscript 送入。
- 指標是第三方 DOM 擷取，可能過期或改版失效；只用於診斷，不作為開播、斷播或 AutoStop 判斷。
監控頁需登入對應 TikTok 帳號並另裝 `UserScript/liveCenter.user.js`，後者匹配 `https://livecenter.tiktok.com/*`，但只在官方 `live_monitor` 頁面自動啟動監控，其餘頁面（例如回放）預設不觀察，改由右下角面板手動覆寫。既有腳本負責將可識別的聊天與統計送往本機 `/chat`；此次 Restream 樣本只含監控連結，尚未驗證實際監控頁 DOM、資料欄位與登入流程。不要把頭號觀眾名單當成總觀看數。
保持監控頁開啟是否能降低斷播，仍須實際直播驗證；本助手不提供保活協定、不重試推流，也不保證防止斷播。瀏覽器背景休眠可能延遲偵測。
目前以本機腳本安裝為主，未設定遠端自動更新網址。後續專用瀏覽器整合與驗收規劃見根目錄 [todo.md](../todo.md)。
### Restream 助手面板（1.3.0）
面板可拖曳標題列移動，或聚焦標題後用方向鍵調整位置；收合後仍顯示狀態摘要，不會停止監控。位置與收合狀態保存在腳本管理器，重新整理後還原；視窗縮小時限制在可見範圍。展開後可使用「重設位置」回到右下角。1.2.0 新增「自動暫停預覽」勾選與預覽狀態；標題、狀態、操作區分開，後續功能可加入操作區。
### Live Center 控制面板（1.15）
面板可拖曳標題列移動，或聚焦標題後用方向鍵調整位置；收合後仍顯示「監控中／未監控」摘要，不會改變啟停狀態。位置與收合狀態保存在腳本管理器，重新整理後還原；視窗縮小時限制在可見範圍。展開後可使用「恢復自動」與「重設位置」。
- 只在官方 `live_monitor` 頁面自動啟動；`replay` 等頁面預設不觀察，因此不再需要個別 `@exclude`。
- 面板開關可手動強制開啟／關閉，狀態以 `GM_setValue` 記憶；「恢復自動」清除手動指定、回到依頁面自動判定。
- 關閉時停止 MutationObserver、5 秒觀眾列表與 30 秒回報計時器，不再觀察或送出任何資料。
- SPA 換頁時重新判定；僅在自動模式下檢查網址，手動指定後不再輪詢網址。