# 參考樣本：`17806.f9a7bd4e.js` 本檔說明同目錄的 `17806.f9a7bd4e.js`。它是**參考樣本**，不是本專案的程式碼，也不被任何程式或文件匯入。 ## 這是什麼 - 來源：TikTok 直播網頁版（`tiktok_webapp_live`）的 webpack 打包產物，整檔壓縮成單行。 - 檔名：`17806` 是 webpack chunk id，`f9a7bd4e` 是該 chunk 的內容雜湊。 - 辨識依據：檔案開頭為 `globalThis.webpackChun …

# 常客分析（audience） ## 邊界 - `traffic` 管主播／場次／時段與分類，不管理個別觀眾。 - `audience` 管個別觀眾的互動聚合與常客等級，使用獨立的 `data/audience.sqlite`。 - `monitor` 只負責顯示；標記由 audience 計算後附在監控訊息上。 - `useTTS` 仍是單則訊息「要不要朗讀」的可選提示。常客等級不直接改寫 `useTTS`，而是作為 optional metadata，讓對端 app 自己決定優先權或解鎖政策。 ## 身 …

# 持久化專用瀏覽器 ## 啟動與查看 1. 安裝本機 Chrome 或 Edge，執行 npm install。 2. 執行 npm start，登入主服務後開啟 http://127.0.0.1:3332/browser。 3. 按「啟動專用瀏覽器」，在可見視窗登入 TikTok、完成網站驗證。 4. .env 設定 DIRECT_SIGNER_ENABLED=1 後重新啟動主服務／聊天子程序，載入新設定。若同時有 EulerStream key，仍優先使用 EulerStream；要指定本機簽名器請加 D …

# `/chat` Userscript 轉接參數 本文件說明 `Server.js` 現行 HTTP 入口。平台分類與腳本版本見 [Userscript 來源說明](USERSCRIPT_SOURCES.md)，剪輯計算見 [自動剪輯說明](KEYWORD_AUTOCLIP_V2.md)。 ## 入口與流程 ```text POST http://localhost:3332/chat Content-Type: application/json Userscript → Server.js → TikT …

# CodeQL 掃描告警修復紀錄 ## 文件導覽 | 文件 | 適合誰 | 內容 | | ------ | -------- | ------ | | 本文件 | 開發者/維護者 | CodeQL 告警清單、修復方式、哪些是誤報/無法修 | | `SIGN_SERVER_CHANGELOG.md` | 開發者/維護者 | 簽名伺服器套件結構與架構演進 | ## 背景 GitHub CodeQL 掃描在 `main` 分支上回報了一批安全告警。本文件紀錄每個告警的 **性質**（真實漏洞 / 誤報 / 無法 …

# ChangeHistory ## 2026.11.13 14:10 執行中切換收發與通知 **類型**: 功能 · **檔案**: `TikTok.js`、`ScriptLib/notify/index.mjs`、`ScriptLib/socket/transport.mjs`、`ScriptLib/socket/endpoint.mjs`、`ScriptLib/socket/hub.mjs`、`ScriptLib/runtime/state.cjs`、`RuntimeRoutes.cjs`、`Server …

# 應用診斷（/diagnostics） ## 目的 集中查看外部應用（目前是 ReplyKit）的診斷與日誌，用於排查錄影、推流、擴展或 log I/O 問題。資料只是暫存，不是正式 log 檔。 ## 兩種來源 ### HTTP log bridge 與 ReplyKit `LogServer.js` 相容，POST 到： ```text http://<TTWChat主機>:3332/post ``` 接受： ```json { "logs": [{ "time": "...", "title …

# 表情映射管理與熱載入 登入後開啟 `/emoji`，可搜尋、新增、編輯、啟用／停用、恢復預設與刪除自訂代碼，並預覽圖片。 使用現有登入 cookie；未登入的 API 請求回傳 401。 ## 檔案分工 - `emoji_map.json`：**出廠預設**，可提交、可隨版本更新；應用程式只讀，管理頁不會改寫。 - `emoji_map_local.json`：**本機覆寫**，不提交（`.gitignore`）；只保存與預設不同或自訂的部分。 預設檔維持簡單的「完整代碼 → 圖片 HTTP(S) 網址 …

# ESLint 檢查 - `npm run lint`：檢查專案 JavaScript。初次導入仍有既有問題與待補環境宣告，尚未作為 CI 通過門檻。 - `npm run lint:restream`：檢查 Restream UserScript 與對應測試，目前通過。 `eslint.config.mjs` 區分 Node CommonJS、ESM、assets 瀏覽器程式與 UserScript；UserScript 只加入使用中的 GM API，不宣告 Node 的 module／require。共用 …

# 網頁本地化 支援繁體中文與英文：運行狀態（/runtime）、專用瀏覽器（/browser）、人流分析（/traffic）與主控台導覽。人流分析的圖表、日期操作、歷史表格與清理介面使用 `traffic.*`；`/logViewer`、`/autoclip`、`/keyword` 的人流分析入口也已本地化。其餘未標記的介面仍維持中文，聊天內容、平台名稱、分頁標題、日誌與底層錯誤不自動翻譯。 ## 使用方式 在已支援頁面導覽列選擇語言。選擇保存於同一來源的 localStorage（ttw.language …

# 留言統計與自動剪輯改進 Userscript 轉接格式見 [/chat 入口與參數文件](CHAT_API.md)；平台與接收管道的分類見 [來源說明](USERSCRIPT_SOURCES.md)。未知來源仍參與熱度，明確標記 `isTest: true` 的測試資料只顯示及記錄，不參與熱度。 ## 資料與 keyword 頁面 - 每則留言只統計一次，翻譯不另加次數；ID 去重依平台區分。 - 統計保留內容、次數、首次／最後已知時間、平台及每種留言最近 5 筆紀錄。 - 最近紀錄有使用者、訊息 ID、 …

# 圖片媒體快取（media） ## 目的 TikTok／Twitch 頭像、TikTok 禮物圖與贊助 overlay 圖片原本直接使用外部 CDN URL。這些 URL 可能： - 過期或需要重新導向。 - 在 overlay 端重複下載。 - 因來源站限流或網路不穩而閃爍。 MediaCache 將圖片持久化到本機，訊息只傳本地 URL： ```text 外部圖片 URL → MediaCache.localUrl(url) → http://127.0.0.1:3332/media/<sh …

# 訊息過濾系統（MessageFilter） `MessageFilter.js` 是統一的訊息過濾與統計模組，同時被 `TikTok.js`（原生連線）與 `Server.js`（`/chat` 轉接）引用。 本文件說明**所有支援的規則模式**、完整欄位、預設規則、自訂方式與測試工具。 > [!IMPORTANT] > **規則在兩個行程各跑一次**：原生聊天在 `TikTok.js`、`/chat` 轉接在 `Server.js`。 > `throttle`（頻率）的狀態因此**每個行程各一份**，兩邊 …

# 模組責任與維護方式 ## 自動剪輯 | 檔案 | 責任 | | --- | --- | | AutoClip.js | 保留既有公開匯入路徑，轉出 AutoClipManager | | AutoClipV2.mjs | 管理留言窗口、去重、暖機、持續熱度、冷卻與歷史生命週期 | | ScriptLib/autoclip/metrics.mjs | 清理窗口、計算平台基準與貢獻分數、選出獨立達標的最高分 | | ScriptLib/autoclip/evidence.mjs | 複製觸發當下證據，保留總數並 …

# 修補（Patch）系統 本專案對第三方套件的修改改以**最小差異 patch** 維護，套用在**對應版本**的原廠套件上。 不再以整檔複製方式覆蓋 `node_modules`。 ## 目錄結構 ```text Docs/ ├── patches/ │ ├── tiktok-live-connector/ │ │ └── 2.4.0.patch ← 依版本命名 │ └── kick-wss/ │ └── 1.0.5.patch ├── apply-patch …

# 運行狀態頁 執行 npm start 後，可開啟 /runtime 或由主控台導覽進入。 /open（保留原 query 啟動参数）與 /close 都回傳同一個頁面，移除固定 5 秒跳轉與純文字回應。 頁面將網址替換為 /runtime，重新整理不會再觸發啟停，每 2 秒讀取 GET /api/runtime。 顯示已停止、啟動中、程序執行中、停止中與失敗狀態，附 PID、啟用平台、運行時間及退出 code／signal。 程序執行中只表示作業系統已建立程序，登入與收訊需查看日誌。停止先送 EXIT 讓子 …

# Sign Server 改動紀錄與使用說明 ## 文件導覽 | 文件 | 適合誰 | 內容 | | ------ | -------- | ------ | | 本文件 | 開發者/維護者 | 套件結構、修改流程、架構演進、CDP 設計說明 | | `PATCHES.md` | 所有人 | 最小差異 patch 系統（patch 清單、套用/還原/產生方式） | | `TEST_FILES_REFERENCE.md` | 測試者/除錯 | 開發測試腳本的用途與使用方式 | | `dotenv-axios-n …

# Socket 收發與壅塞處理 `TikTok.js` 的聊天、廣告、觀眾更新與心跳統一由 `ScriptLib/socket/transport.mjs`（`SocketTransport`）發送；訊息去重、端點與扇出在 `ScriptLib/socket/`（`MessageDedup`、`SocketEndpoint`、`SocketHub`）。 `MessageDedup` 除了使用者與第一行內容，可帶 opt-in `variant`。目前只有 `isTest` 測試訊息使用 `test:<頭貼 U …

# 啟動與樣式開發 ## 一鍵啟動 第一次使用先設定 `.env` 並執行 `npm install`，之後在專案目錄： ```sh npm start ``` 開啟 http://localhost:3332 。一般模式會比對來源與產出指紋，一致就使用 `assets/app.css`，不會每次重新編譯。 若 CSS 缺少、被修改，或來源與建置指紋不同，會先建置再啟動；缺少建置工具或建置失敗會停止並顯示原因。 適合平常使用、直播期間啟動，以及只安裝正式依賴但已備妥 CSS 的環境。 此命令啟動 `Ser …

# Web服務端 的其他新功能 ## Userscript 聊天轉接 `POST /chat` 的聊天與觀眾資料契約已獨立整理至 [/chat 入口與參數文件](CHAT_API.md)。平台分類及腳本版本見 [Userscript 平台與管道](USERSCRIPT_SOURCES.md)。 ### **可視化網頁 進行日誌文件查看** 目前預設兩個按鈕 是以預設配置日誌文件名為主 如果你當前有需要更換預設日誌文件名的需求 請手動 更正 `writeLog()` 指向的Default文件名\ 以及 …

# 測試檔案參考 `Test/` 目錄包含開發過程中建立的測試與分析腳本，用於驗證 TikTok Live 連線機制、翻譯過濾與訊息解析等環節。 ## 使用方式 所有腳本請**從專案根目錄**執行（部分腳本以 `node_modules/...` 相對路徑讀取 SDK）： ```bash node Test/xxx.mjs ``` 部分測試需要 Puppeteer / browser 環境，會自動啟動 headless Chrome。 ## 翻譯與訊息過濾 | 檔案 | 測試內容 | | ------ …

# TikTok 重連聊天防重播 `TikTokChatGuard.mjs` 僅套用於 `isTK` 的 CHAT 事件，在翻譯、通知、統計和 Socket 發送前執行。禮物連擊及其他事件不受此過濾器影響。 - 優先讀取 `common.msgId`、`common.createTime`，相容頂層同名欄位。 - ID 使用字串保存，避免大型整數精度損失；最多保存 10,000 筆、30 分鐘， 在同一程序內跨重連保留，不跨程序重啟保存。 - 每次實際呼叫重連之前，設定「本機目前時間減 3 秒」為界線；平台 …

# 人流分析與自動留存 入口 /traffic。SQLite 檔案為 data/traffic.sqlite，WAL 模式，每筆事件與分鐘彙總交易式提交；不再因超過 24 小時或重啟刪除。備份請停止主服務後複製資料庫；運行中不要單獨複製 sqlite 而忽略 WAL。檔案已排除 Git。 ## 圖表操作（2026-09 更新） `/traffic` 使用單一分析區間，操作流程為「選觀測區段 → 平移／縮放 → 必要時指定起訖時間」。不再提供舊版的範圍選單、瀏覽模式或壓縮空白長條總覽。 - 預設選取最近一段紀 …

# Userscript 平台與管道 撰寫或修改轉接腳本請先看獨立的 [/chat 入口與參數文件](CHAT_API.md)，包含聊天／觀眾範例、欄位型別、測試標記與 HTTP 回應。 平台和接收管道是兩個獨立欄位。平台白名單為 TikTok、Twitch、Kick、Odysee、Youtube； 名稱不分大小寫。缺少平台、舊值 Userscript 或無法辨識的值歸為 `Unknown`， 頁面顯示「未知來源」。未知來源仍是有效熱度統計組，套用相同的留言量、 發言人數、去重及洗頻門檻，不會只因無法辨識而被排 …

# 網頁樣式建置與版面盤點 ## 靜態 CSS 一般啟動使用 `npm start`，排版開發使用 `npm run dev`；模式差異見 [啟動說明](STARTUP.md)。 主服務的 Tailwind 頁面（含 `/traffic`）改用 `/assets/app.css`。以 Tailwind 4.3.3（`@tailwindcss/cli`）編譯既有 class， 瀏覽器不再載入 Tailwind Play CDN。keyword 原本即為獨立 CSS，保持原本的樣式方式。 Chart.js、播放器 …

# YouTube 無 OAuth／無 API Key 的專用瀏覽器 fallback `liveChatMessages.list` 需要 OAuth；只用 API Key 會在聊天室輪詢得到 403。當 OAuth 失效或沒有授權時，程式可以改用專用瀏覽器開啟**實際觀看頁**，從頁面的聊天室 iframe 讀取訊息。沒有 API Key 時也可以直接從頻道 `/live` 頁 discovery，適合不想建立 Google Cloud 專案的使用者。 ## 行為 - 有有效 OAuth：使用原生 `li …

# dotenv / axios 定位說明與原生替代方案 ## 為什麼這兩個套件定位尷尬 Node.js 核心近年持續吸收第三方套件的主流功能，導致 `dotenv` 與 `axios` 這兩個 「過去幾乎必裝」的套件，在 Node 20+ 的環境下變成可有可無： | 套件 | 用途 | Node 原生替代 | 進入核心的版本 | | ------ | ------ | --------------- | ---------------- | | `dotenv` | 讀取 `.env` 檔案注入 `proc …

# Patched Plugins 說明（已棄用） > ⚠️ **本目錄已棄用，僅保留供歷史參考。** > 修補已改為「最小差異 patch」機制，見 [`../PATCHES.md`](../PATCHES.md)。 > 請改用 `node Docs/apply-patches.mjs`（套用）、`--check`（檢查）、`--revert`（還原）， > 以及 `node Docs/make-patches.mjs`（重新產生 patch）。不要再手動複製本目錄的整檔。 本目錄存放第三方套件的修改版本（p …

# Kick WebSocket Una librería ligera y sin dependencias para conectar a los WebSockets de Kick.com. ## Características - 🚀 **Ligera**: Sin dependencias externas, solo usa WebSocket nativo - 🔌 **Simple**: API intuitiva y fácil de usar - 🔄 **Auto-reconexión** …

# Kick WebSocket A lightweight and dependency-free library for connecting to Kick.com WebSockets. ## Features - 🚀 **Lightweight**: No external dependencies, uses native WebSocket only - 🔌 **Simple**: Intuitive and easy-to-use API - 🔄 **Auto-reconnection**: …

# Kick WebSocket Una librería ligera y sin dependencias para conectar a los WebSockets de Kick.com. ## Características - 🚀 **Ligera**: Sin dependencias externas, solo usa WebSocket nativo - 🔌 **Simple**: API intuitiva y fácil de usar - 🔄 **Auto-reconexión** …

# Kick WebSocket A lightweight and dependency-free library for connecting to Kick.com WebSockets. ## Features - 🚀 **Lightweight**: No external dependencies, uses native WebSocket only - 🔌 **Simple**: Intuitive and easy-to-use API - 🔄 **Auto-reconnection**: …

# TikTok-Live-Connector A Node.js library to receive live stream events such as comments and gifts in realtime from [TikTok LIVE](https://www.tiktok.com/live) by connecting to TikTok's internal Webcast push service. This package includes a wrapper that connec …

# Code of Conduct ## Our Pledge We pledge to make participation in our project a harassment-free experience for everyone. ## Our Standards **Positive behavior:** - Being respectful and inclusive - Accepting constructive criticism - Focusing on what's best …

# Contributing to tiktok-signature Thank you for your interest in contributing! ## Getting Started 1. Fork the repository 2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/tiktok-signature.git` 3. Install dependencies: `npm install` 4. Create …

# TikTok Signature Generator   Generate valid **X-Bogus** and **X-Gnarly** signatures for TikTok API req …

# Security Policy ## Supported Versions | Version | Supported | | ------- | ------------------ | | 4.x | :white_check_mark: | | 3.x | :x: | | < 3.0 | :x: | ## Reporting a Vulnerability If you discover a secu …

# TikTok Signature Examples These examples demonstrate how to use the TikTok Signature Server to fetch various types of data from TikTok. ## How It Works 1. **Build TikTok API URL** - Construct the URL with all required parameters 2. **Get Signed URL** - Se …

# live_engine — 即時聊天室訊息疊加畫面 + 表情 + TTS 朗讀 透明穿透的直播聊天室 Overlay，接收 TCP 訊息後以 OpenGL 渲染在畫面上，支援內嵌圖片 URL 解析、系統字型選擇、觀眾人數、直播計時器，並可透過 edge-tts 朗讀訊息。 --- ## 功能 - **透明疊層視窗** — 無邊框、支援點擊穿透/拖曳調整位置 - **頭像 + 用戶名 + 內嵌表情 + 禮物圖示** 渲染 - **文字自動換行**，可選系統字型 - **訊息平滑動畫** — 進場、滾動、淡 …

# TTWChatMessageServer ## 簡介 `TTWChatMessageServer` 是一個聊天室訊息服務器，可對接 **TikTok**、**Twitch**、**Kick**、**Odysee** 與 **Youtube** 的直播聊天室訊息，支援以下功能： - 即時接收聊天室訊息 - 支援禮物、關注、加入、分享等事件 - 可推送到 **Bark** 或 **Socket** - 可透過簡單 HTTP 接口開關服務 - 可透過簡單 HTTP 接口快速修改BARK/SocketAPI配置 …

# Security Policy ## Supported Versions Use this section to tell people about which versions of your project are currently being supported with security updates. | Version | Supported | | ------- | ------------------ | | 5.1.x | :white_check_mark …

# SDK 來源 保留原本 tiktok-signature@4.3.6 的 javascript/webmssdk 三份檔案，位元組未修改，SHA-256 見 manifest.json。 來源套件宣告 MIT；上游 TikTok SDK 的來源與權利聲明仍依各檔案內容，這裡不另行授權。 原套件：https://www.npmjs.com/package/tiktok-signature/v/4.3.6 僅獨立保存現有執行期需要的資產，不再安裝整個瀏覽器簽名服務。

# 測試維護指南 ## 撰寫方式 - 案例名稱描述情境與預期結果；新增或整理的案例優先使用中文。 - 每行保留一個主要操作，將準備、操作與斷言以空行分組。 - 註解說明資料為何特殊、等待的原因與要防止的回歸，不逐行翻譯程式。 - 輔助函數交代回傳資料、副作用與清理方式；只在確實重複時抽成共用工具。 - 測試用檔案放在獨立暫存資料夾，計時器及替換的共用狀態在結束時清理或還原。 - 重構測試時保留原有斷言與覆蓋範圍，不以刪除失敗案例讓測試通過。 ## 本輪已整理 | 檔案 | 涵蓋行為 | | --- | -- …

# Restream / TikTok Live Monitor 後續規劃 > 2026-11-06 更新：補上 endpoint 設定、預覽自動暫停、Restream 指標診斷與 WAF 403 修復。 ## 2026-11-06 近期完成 - [x] 所有轉接 userscript 的主服務位址可設定（`ttw-main-endpoint`、`GET /ping`）。 - [x] Restream 助手自動暫停預覽（1.2.0；可取消）。 - [x] Restream 指標診斷：`POST／GET /re …