流程系统

把「收到消息」「判断条件」「执行操作」连接起来，就能让机器人按你设计的步骤工作。自定义群命令、定时提醒、服务器命令执行、玩家信息查询和图片卡片，都可以通过流程画布组合完成。

你可以先搭建一个只有两个节点的自动回复，再逐步加入白名单校验、变量解析和图片渲染。

认识流程工作台

登录机器人后台，在左侧打开「流程系统」。下面的截图以「金币排行」为例，点击图片可以查看原图。

流程编辑中心 · 添加节点、连接分支、配置属性、保存运行

区域	用途
顶部工具栏	新建、复制、导入、导出流程，补全默认流程，以及全屏编辑和保存
当前流程与名称	切换需要编辑的流程，修改名称，开启或关闭自动触发
左侧节点目录	按触发、判断、执行、扩展核心等分类添加节点
中间流程画布	拖动节点调整布局，通过连线决定执行顺序
右侧节点属性	点击节点后填写参数，查看可用变量和输出连线
下方运行区域	填写测试输入，执行流程，查看各节点的结果与耗时

节点与连线怎么用？

1. 点击左侧节点旁的「＋」，把节点添加到画布。
2. 点击画布中的节点，在右侧修改名称和配置。建议使用「回复帮助」「读取玩家 ID」等容易辨认的名称。
3. 点击上游节点右侧的「下一步」，再点击下游节点左侧的输入口，完成连线。
4. 判断节点使用「通过」「未通过」两个出口，分别连接不同处理步骤。
5. 需要删除连线时，选中来源节点，在右侧「输出连线」中删除对应项。

节点摆放位置只影响阅读，真正的执行顺序由连线决定。拖动画布空白处可以移动视野，也可以使用滚轮上下移动、Shift + 滚轮 横向移动；复杂流程建议使用「全屏编辑」。

分支连接

同一个出口可以连接多个下游节点。需要某一步使用上一步的结果时，请依次串联，例如「服务器命令 → 绘制图片 → 发送群消息」。流程不支持循环回连。

入门：做一个群内帮助命令

目标：群成员发送 #服务器帮助，机器人回复入服和白名单申请提示。

1. 创建流程

点击「新建流程」，将名称改为「服务器帮助」。新流程自带一个「手动触发」节点，可以保留用于网页测试。

2. 添加消息触发

添加「收到消息」节点，按下面的内容配置：

配置项	填写内容
触发内容	#服务器帮助
匹配方式	开头匹配（精确）
消息类型	群聊消息
触发权限	群员及以上

「开头匹配」表示消息以触发内容开头即可命中，因此 #服务器帮助 更多 也会触发；「包含匹配」则允许触发内容出现在消息中间。尽量使用不易与其他命令重合的触发词。

3. 添加回复节点

添加「发送群消息」，将「目标群 OpenID」填写为 {group_id}，在「消息内容」中填写： （{group_id}为上游节点「发送群消息」提供，具体可点击节点查看属性栏下方的变量介绍）

欢迎来到服务器！
请先阅读群公告，并按白名单申请说明绑定游戏 ID。
需要帮助时，请联系群内管理员。

原生 Markdown 和按钮 JSON 暂时留空。将「收到消息」的「下一步」连接到「发送群消息」的左侧输入口。

收到消息：#服务器帮助 ──→ 发送群消息
手动触发 ────────────→ 发送群消息

4. 保存并验证

确认流程为「已启用」，点击右上角「保存流程」。在已启用的目标群中发送 #服务器帮助，检查机器人是否回复。

群消息触发时，{group_id} 来自实际消息，不需要填写固定群标识。如果机器人无法接收不带 @ 的消息，请先按快速开始完成群消息接收权限设置。

调试：在后台执行流程

页面下方的「运行输入」使用 key=value 格式，每行一个变量。手动测试群回复时，需要填写真实的群 OpenID，例如：

group_id=替换为目标群的真实OpenID
user_id=替换为测试用户的真实OpenID
user_name=测试玩家
message_content=#服务器帮助
message_type=group
message_role=member

不要直接照抄示例中的说明文字。OpenID 是机器人接收到的群或用户标识，不能用普通 QQ 群号、QQ 号代替。

点击「执行流程」，在右侧「执行结果」查看每个节点的状态、返回说明和耗时。若某个节点失败，优先处理该节点提示的参数或连接问题。

测试入口与实际操作

存在「手动触发」节点时，网页测试优先从手动入口执行，请确认该入口已连到需要测试的步骤。没有手动入口时，消息流程可通过 message_content 模拟触发。

「执行流程」会真实发送消息、执行服务器命令，并非只检查连线。第一次练习建议使用帮助回复或 list 这类查询操作。

变量：把上一步的结果传下去

变量使用 {变量名} 引用。配置「保存为变量」时填写名称本身，例如 game_id；后续引用时才写 {game_id}。选中节点后，右侧的「变量说明」会列出可用变量及本节点产生的结果。

常用变量	含义与使用场景
{message_content}	收到的消息正文，可用于取文本或判断
{group_id}	触发消息所在群的 OpenID，用于回复原群
{user_id}	触发用户的 OpenID，用于查询白名单或回复私聊
{user_name}	触发用户的名称
{last_text}	最近一次「取文本」的结果
{last_response}	最近一次服务器命令或发送操作的返回值
{whitelist_game_id}	「获取白名单 ID」节点取得的首个正式白名单 ID
{mc.json}	结果保存名称为 mc 时，变量组解析产生的完整 JSON
{html_image_path}	HTML 渲染节点使用此输出名时生成的图片路径
{last_image_path}	最近一次绘图或 HTML 渲染生成的图片路径

变量必须先由上游节点生成，再交给后续节点使用。定时流程没有天然的消息发送人或来源群，不能直接依赖消息触发时才有的上下文。

示例：从消息中提取玩家名

若希望接收 #查询玩家 Steve，先创建触发内容为 #查询玩家 的「收到消息」节点，再连接「取文本」：

配置项	填写内容
来源内容	{message_content}
开始标记	#查询玩家
结束标记	留空，截取到消息末尾
允许截取结果为空	否
保存为变量	game_id

后续节点即可使用 {game_id}。如果需要确认这个游戏 ID 属于发起查询的用户，应接入「选择白名单 ID」节点进行归属检查，不能仅凭用户输入认定身份。

示例一：每天定时发送提醒

目标：每天北京时间 20:00，在指定群发送活动提醒。

1. 新建「每日活动提醒」，添加「定时触发」节点。
2. 在节点属性中设置 20:00；需要一天多次提醒时，点击「添加时间」逐项设置。
3. 添加「发送群消息」，将目标群 OpenID 填为实际的固定群标识，消息填写为「晚间活动即将开始，欢迎上线参加！」。
4. 将「定时触发」的「下一步」连接到发送节点，启用流程并保存。

定时触发：每天 20:00 → 发送群消息：活动提醒

这里的时间按北京时间计算。定时执行时机器人需要保持运行、在线，并具有目标群的主动发言权限；不要把目标群留为没有来源的 {group_id}。

示例二：查询服务器在线玩家

目标：管理员发送 #在线玩家，机器人执行 list 并返回服务器结果。

先在「服务器管理」中配置可用的 RCON 连接，具体步骤见快速开始。然后创建以下三个节点：

节点	关键配置
收到消息	触发内容 #在线玩家；群聊消息；触发权限按实际需求选择，例如「超管及以上」
发送服务器命令	目标服务器选择已配置的服务器；服务器命令填写 list
发送群消息	目标群 {group_id}；消息内容填写 在线玩家查询结果：，换行后填写 {last_response}

依次连接并保存：

收到消息 → 发送服务器命令：list → 发送群消息

将命令结果绘制成图片

如果返回内容较长，可以在命令与发送节点之间添加「绘制 Minecraft 文本」：

配置项	填写内容
绘图文本	{last_response}
图片宽度	可先留空，使用默认宽度 960
图片高度	留空，按文本长度自动计算
图片路径保存为变量	image_path

将「发送群消息」的消息内容改为下面的形式，Markdown 字段留空：

在线玩家查询结果：
[本地图片:{image_path}]

如果需要保留 Minecraft 颜色效果，在服务器命令节点中不要开启「过滤 MC 颜色符号」。命令返回的颜色标记由绘图节点处理。

示例三：截图中的金币排行流程

这个流程把白名单校验、服务端变量组与 HTML 图片渲染组合起来：用户发送 #金币排行 后，已有白名单的用户收到排行图片，没有白名单的用户收到申请提示。

收到消息：#金币排行 → 获取白名单 ID
                        ├─ 通过 → 变量组解析 → HTML 模板渲染 → 发送图片
                        └─ 未通过 → 发送白名单申请提示

1. 准备变量组与 HTML 模板

先完成单服配置或代理集群部署，确认机器人扩展核心与插件连接正常。服务端需要有对应的变量组，机器人端需要有配套的 HTML 模板。

内置示例使用变量组 money_ranking_xconomy 和模板 money-ranking-xconomy/index.html。请先确认这些资源实际存在，服务端已满足变量组所依赖的经济插件及占位符条件。变量组的放置位置与重载方法见变量解析。

从内置流程开始

可以先在「当前流程」中查看是否已有「金币排行」，然后点击「复制流程」创建副本再修改。副本默认关闭，需要按自己的环境检查资源、目标服务器与触发词，确认后再启用。

2. 设置触发与白名单判断

「收到消息」设置触发内容 #金币排行，消息类型选择群聊消息，匹配方式选择开头匹配，权限选择群员及以上。

将它连接到「获取白名单 ID」，填写：

配置项	填写内容
用户 OpenID	{user_id}
首个 ID 保存为变量	whitelist_game_id

该节点有白名单时输出首个正式白名单 ID，并走「通过」分支；没有白名单时走「未通过」分支。

将「未通过」连接到一个「发送群消息」节点，目标群填写 {group_id}，内容填写「请先申请白名单后再使用本命令。」。此分支到这里即可结束。

3. 通过分支读取变量组

将「通过」连接到「变量组解析」，配置如下：

配置项	填写内容
变量组文件名	money_ranking_xconomy，不带 .yml
玩家名称	{whitelist_game_id}
目标子服	需要限定时选择对应子服；留空或 * 会向全部子服解析
结果保存名称	mc

节点成功后，完整解析结果可以通过 {mc.json} 交给下一个节点。集群中应结合经济数据所在子服选择目标，避免读取到不符合预期的数据。

4. 把数据渲染成图片

添加「HTML 模板渲染」，接到变量组解析后面：

配置项	示例值
HTML 模板	money-ranking-xconomy/index.html
模板参数	{mc.json}
视口宽度	900
视口高度	1160
截取完整页面	是
等待页面就绪节点	无特殊要求时留空
图片路径保存为变量	html_image_path

宽高是这套示例模板的参考值，更换模板时应按实际版面调整。HTML 模板必须能读取传入的数据结构；仅更换模板文件名不能自动适配另一套变量组。

5. 发送排行图片

最后接入「发送群消息」，目标群填写 {group_id}，消息内容填写：

[本地图片:{html_image_path}]

原生 Markdown 与按钮 JSON 留空。如果是无需保留的临时渲染图片，可以开启「图片发送成功后删除」。固定素材或后续节点仍需使用的图片请保留。

保存并启用流程，在群中发送 #金币排行。分别使用有白名单和没有白名单的账号验证两个分支。测试时避免同时启用触发词相同的原流程与副本，以免重复回复。

其他常用节点

节点	适合的用途	配置要点
如果	比较数值、检查文本或判断变量是否有内容	设置判断内容、判断方式与比较内容，分别连接两个出口
是否拥有白名单	只判断用户是否已有正式白名单	用户 OpenID 通常填 {user_id}
选择白名单 ID	用户拥有多个 ID 时，选择并验证本次操作的 ID	指定游戏 ID 可引用取文本结果；留空时仅在用户只有一个 ID 时自动选择
添加白名单	把自定义申请流程接入机器人白名单规则	填写用户 OpenID、用户名称与游戏 ID；先设计好校验与权限
发送私聊消息	回复 C2C 私聊用户	目标使用用户 OpenID；从私聊触发时通常填 {user_id}
延时	等待一段时间再执行当前分支的下一步	单位为毫秒，例如 1500 为 1.5 秒，最大 600000
结束并输出	将说明或变量写入网页执行结果	不会自动向群聊发送消息，需要群回复时另接发送节点

保存、复用与分享

操作	使用说明
保存流程	完成编辑后点击，确认保存成功再进行验证
复制流程	在现有流程上创建副本，副本默认关闭，适合保留原流程并试验新功能
导出流程包	导出当前流程为 .sabflow 文件，用于备份或分享
导入流程包	导入已有流程包，之后检查资源依赖、目标服务器、群标识与启用状态
补全默认流程	重新释放缺失的默认流程，不会覆盖现有默认流程，也不会重置用户流程

导入后请确认对方使用的变量组、HTML 模板、字体和插件依赖在你的环境中也已准备好，再进行测试。

常见问题与排查

群里发送命令没有反应

检查流程是否已启用并保存、群聊是否已启用，以及机器人是否在线。然后核对触发内容、匹配方式、消息类型和触发权限，并确认「收到消息」节点已连接后续步骤。权限中的「超管」指机器人配置的超级管理员。

网页测试没有执行想要的节点

检查手动入口的连线。手动节点与消息节点是独立入口：消息入口连好的步骤，不会因为画布上同时存在手动节点就自动成为手动测试路径。

提示缺少群或用户信息

消息触发会提供相应上下文；手动测试需要在运行输入中补充真实的 group_id、user_id。定时消息则需要在发送节点中指定固定目标群，QQ 号或普通群号不能替代 OpenID。

图片没有发出，或只看到路径文本

确认绘图或 HTML 渲染节点执行成功、输出变量名与发送节点引用一致，并使用完整标记 [本地图片:{html_image_path}]。标记应写在普通「消息内容」中。单条图文消息只合并第一张本地图片，后续图片标记会显示为路径文本。

金币排行读不到数据

先检查插件连接、变量组文件及其依赖，再核对玩家 ID 和目标子服。变量组成功后，继续检查 {mc.json} 是否交给 HTML 模板，以及模板是否与该变量组的数据结构匹配。

流程保存时提示循环连线

检查是否有节点连回自己的上游。流程需要沿连线向后执行；需要分情况处理时使用判断分支，需要按时间重复执行时使用定时触发。