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）。