Event Flow 編輯器指南

0. 快速入門

這個編輯器是什麼？

Event Flow 編輯器是 Social Stream Ninja 的「進階自動化」層。它位於簡單彈出視窗開關之上，讓您撰寫自己的路由邏輯。在需要以下功能時使用它：

• 在服務之間篩選並轉送聊天（例如將 Twitch 鏡像至 Discord，但封鎖命令）。
• 透過 AND/OR/NOT 邏輯建立以忠誠度為依據的命令、關鍵字遊戲或抽獎資格限制。
• 根據在流程中補充的資料，觸發自訂疊加畫面、音訊、OBS 場景或 webhook。
• 在單一自動化中混合多個平台（Kick + Twitch + YouTube 透過一個流程路由）。

可以將彈出視窗視為「快速預設」，將 Event Flow 視為自訂工作流程的工具集。

每個流程都從觸發條件開始

動作節點（綠色）從不自行執行，只有上方的觸發條件節點（藍色）求值為以下結果時才觸發： true。僅將動作串聯起來的流程看似有效，但會一直閒置，因為沒有任何東西啟動該鏈。節點名稱描述的是節點 做什麼，而不是它何時發生： 精選訊息（Feature Message） 在流程抵達它時精選訊息，而不會在您於其他位置精選訊息時觸發。

Flow Actions 疊加畫面（動作輸出）

例如以下節點： 播放音訊片段, 顯示媒體疊加畫面，以及 OBS 控制項都需要一個繪製介面。該介面就是由以下位址提供的 Flow Actions 疊加畫面頁面： actions.html。讓它在直播軟體（OBS/Streamer.bot 瀏覽器停駐面板等）中保持執行，讓 Event Flow 動作有地方顯示。

載入後，該疊加畫面可以：

• 顯示由流程觸發的 GIPHY 或直接媒體 URL、文字和彩紙。
• 在本機播放聲音（TTS、音訊片段），讓觀眾聽到。
• 透過彈出視窗 Flow Actions 區段中的 WebSocket 設定與 OBS 通訊（場景切換、來源開關、GDI+/FreeType 文字更新、重播緩衝區等）。

1. 什麼內容流經節點？

Event Flow 執行階段透過每條連線傳遞兩種內容：

1. 承載資料 — 事件或訊息資料物件。
2. 閘控訊號 — 一個 true/false 位元，告知下一個節點是否執行。

輸入需求

• 事件來源 （Twitch Message、Timers、Manual Trigger 等）忽略上游輸入，它們產生自己的承載資料，並始終發出 true 除非節點本身出錯。
• 轉換和邏輯節點 讀取承載資料，並可重寫欄位、設定狀態，或將閘控訊號翻轉為 false.
• 動作節點 僅在閘控保持以下值時觸發： true。如果您希望繼續串聯動作，它們仍可輸出更新後的承載資料。

輸出模式

2. 邏輯節點速查

這些區塊解答最常見的「true/false 是什麼意思？」問題。

3. 微型流程範例

A. 除命令訊息外自動回覆

此處 Regex 節點發出 true ，條件是訊息為指令。我們將 false 連接埠接到回覆，因此一般聊天者會收到確認，而命令直接通過。

B. 使用 AND 要求多項檢查

AND 節點確保只有使用正確關鍵字的會員才會轉送至 Discord。兩個分支都將布林結果傳送至 AND 節點；承載資料來自 第一個分支 ，並繼續向下游傳遞。

C. 使用 NOT 節點封鎖重複提醒

State Check 在提醒遭靜音時輸出 true 。透過反轉該結果，NOT 節點確保僅在旗標為以下值時播放慶祝效果： false.

D. 隨機播放兩種聲音之一

AND 閘不可省略。 獨立的 NOT 會輸出 true 每當 RANDOM 閘閒置時，因此聲音 B 會在每則以下聊天訊息時播放： 不符合觸發條件的訊息。 將觸發器連接至 AND 的第二個輸入，可將聲音 B 限制為僅在訊息符合條件時播放。同一模式適用於任何二選一的動作組合，不限於音訊。

4. 防止回傳、循環和轉送回授

跨介面轉送聊天很有用，但如果監聽自己的輸出，就可能產生無限回傳。請遵循以下防護措施：

• 避免重複轉送系統。 使用等效的 Event Flow 路由時，請停用全域 Relay all，並檢查是否有其他服務橋接相同聊天。自訂中繼資料不能保證在經過平台聊天後仍保留。
• 使用 Debounce 或 Cooldown 節點 用於每 X 秒只應觸發一次的提醒。
• 有意識地中斷循環。 如果兩個分支相互輸入，請新增邏輯節點檢查狀態變數（「currentlyRelaying」），以便在旗標已設定時提前退出流程。

5. 輸入、輸出和實用問題

常見問答

• 每一對篩選器都必須使用 AND 嗎？ 不需要。許多節點包含多項檢查（例如，基本 Message Filter 支援關鍵字 + 角色）。僅對進階組合，或合併來自不同節點的訊號時使用 AND。
• true/false 值如何抵達 NOT 節點？ 任何具有綠色輸出的節點都會發出 true 作為預設值。條件失敗時，它發出 false。將該連線接入 NOT 以反轉結果。
• 節點傳回 false 時，仍能發出承載資料嗎？ 可以。承載資料仍會透過 false 輸出傳遞；由您決定該分支應通向何處。
• 如何比對 TikTok Team 成員？ 選擇 TikTok Team 成員（TikTok Team Member） 在 User Role 節點中。它識別傳入訊息中的 TikTok Fan Club/team 等級和徽章，不依賴 Main Chat Overlay 設定。
• How do I limit TikTok TTS to Team level 10 or higher? 選擇 Compare Property → TikTok Team Level, Greater or equal (>=)，以及 10. Connect this and a From Source → TikTok condition to an 且（AND） node, then connect AND to 朗讀文字（Speak Text）. This reads meta.teamMemberLevel, which native TikTok connectors and Standard capture supply when numeric Fan Club data is available. Image-only badges cannot provide an exact level; messages without the field do not match. Use Test Flow → TikTok Team Level to try levels below and above your minimum. Disable any separate automatic TTS if this flow should be the only reader.
• 每個 Speak Text 節點可以使用不同的語音嗎？ 可以。在以下欄位中輸入提供者支援的語音名稱或 ID： 語音覆寫（Voice Override），或留空以使用 Flow Actions TTS 預設值。

6. 範本變數參考

多個動作節點（Show Text、Set Text Source、Send Message、Relay Chat、TTS Speak、Call Webhook、Print Thermal Label）支援 範本變數 在執行階段會被事件資料替換。用大括號包住變數名稱，例如 {username}.

核心變數（回溯相容）

延伸變數

範例範本

• 顯示文字（Show Text）： {username} just cheered {hasDonation}!
• 設定 OBS 文字來源（Set OBS Text Source）： {username}: now {counterValue}, need {counterTarget}
• 轉送聊天（Relay Chat）： [{source}] {username}: {message}
• TTS: {username} says {message}
• 贊助提醒： {username} donated {donation} - {subtitle}
• 熱感標籤： {username}，換行，然後 {donation}。請參閱 熱感印表機指南 了解印表機設定、固定尺寸標籤和完整流程。
• Discord 呼叫 Webhook： {"content":"{message}","username":"{username}","avatar_url":"{chatimg}"}

7. 最佳做法檢查表

• 命名並設定色彩： 為節點設定名稱和色彩，以便日後辨認各個分支。
• 使用內建模擬器測試 （Send Test Event），然後再將流程投入直播。
• 在來源附近集中邏輯。 儘早篩選，避免後續額外處理。
• 將重複記錄存入狀態節點。 使用計數器、開關和時間戳記避免重複提醒。
• 記載 meta 欄位。 當您新增自訂的 meta 鍵時，請記載它們，讓疊加畫面和遠端用戶端保持一致。

8. 進一步探索

從 Stream Deck 或 API 執行自訂工作流程：具名觸發條件、入門範本、工作流程探索、額外資料、HTTP/WebSocket/P2P 範例和旋鈕手勢。

準備深入了解？

• 使用 狀態節點 （計數器、開關、計時器）來追蹤事件之間的脈絡。
• 組合 變數和邏輯 以建立佇列系統、抽獎或評分引擎。
• 接入 點數和獎勵 系統，讓觀眾可以主動觸發流程。
• 執行 SSApp 桌面應用程式？ 解鎖 自訂 JavaScript 節點 用於內建節點未涵蓋的任意邏輯。
• 檢查 事件參考 了解所有平台的詳細承載資料文件。

本指南刻意設計為獨立文件，您可以複製到本機、為團隊調整，並繼續在編輯器中嘗試。

9. 自訂 JavaScript 僅限 SSApp / 桌面應用程式

Event Flow 編輯器中的兩個節點讓您撰寫在流程處理管線內執行的任意 JavaScript： 自訂程式碼（Custom Code） （觸發條件）和 執行自訂程式碼（Execute Custom Code） （動作）。當內建節點無法表達某種需求時，它們提供自訂途徑。

Custom Code — 觸發條件節點

拖曳 自訂程式碼（Custom Code） 來自 進階 群組，位於 觸發器 面板拖到畫布上。它充當閘控：僅當程式碼傳回以下值時流程才繼續： true.

Execute Custom Code — 動作節點

拖曳 執行自訂程式碼（Execute Custom Code） 來自 整合 群組，位於 操作 面板。它可以修改訊息、封鎖訊息或附加供下游節點讀取的中繼資料。

物件 message

兩個節點都以下列形式接收完整事件承載資料： message。以下欄位始終可用；平台專屬事件可能包含其他欄位。

動作傳回的內容

從動作程式碼傳回一般物件。您包含的任何欄位都會合併至流程的 result 物件；省略的欄位保持目前值。

程式碼片段範例

將任一項複製到相應節點類型的 JavaScript Code 文字區域。

觸發條件程式碼片段 — 傳回 true 以繼續流程

動作程式碼片段 — 傳回 { modified, message }

完整範例 — VIP 功能請求機器人

該流程監聽 !feature <text> 來自訂閱者、VIP 或管理員的內容，將其重新格式化為功能請求，並轉送至第二個目標（例如 Discord）。

步驟 1 — Custom Code 觸發條件 （貼到觸發條件的 JavaScript Code 欄位）：

步驟 2 — Execute Custom Code 動作 （貼到動作的 JavaScript Code 欄位）：

步驟 3 — Relay Chat 動作：在動作後新增標準 Relay Chat 節點，並設定為指向 Discord（或其他）目標。此處無需自訂程式碼，重新格式化的 message.chatmessage 會自動流經。

安全注意事項

• 沒有網路沙盒。 動作程式碼可以呼叫 fetch()。如果接受他人分享的流程，請在啟用前審核 JS。
• 錯誤會遭攔截。 程式碼中的執行階段錯誤會傳回 false （觸發條件）或不執行動作（動作），並記錄至 DevTools 主控台，流程不會當機。
• 語法錯誤也一樣。 類型為 SyntaxError 的編譯錯誤也會以相同方式攔截。如果節點似乎沒有反應，請檢查 DevTools（F12）。