Files
universal-web-api/docs/workflow-studio.md
T
2026-11-02 22:54:14 +08:00

19 KiB
Raw Blame History

通用工作流与 Workflow Studio

从哪里开始

站点配置 → 请求工作流。原有工作流数组保持不变:只打开编辑器、切换标签或选择节点,不会迁移、重排或保存配置。

  • 流程画布:树状结构。主干从「请求开始」到「流程结束」,顶层阶段带 01 / 02 序号;每个阶段、判断、重试块的子步骤都挂在其图标正下方的支线上,用 ├─ / └─ 连线相接。判断节点是菱形,分支路径以颜色区分:✓ 条件成立 / 情况 N 为主色,✗ 条件不成立 / 其他情况为琥珀色,执行失败时为红色;模拟或真实轨迹命中的路径会填色并标注「本次命中」。阶段默认收起,点击「展开 N 步」查看;空路径只显示一行继续说明,分支结束后回到主线。说明节点兼容旧字符串与 {title,text,tone} 卡片。
  • 节点检查器:配置变量、映射字典、页面状态、比较条件和重试策略。可上移、下移、复制、跨分支移动,或把原节点包进组 / 条件 / 重试块。
  • 流程参数:按阶段编辑已配置的参数,保留布尔、数值、文本和 JSON 类型;页面读取值与运行中计算值独立列出,不伪装成当前值。请求正文、模型名称和自定义入参另作说明。
  • 检查与试跑:自动生成页面状态样例表单;先模拟路径,再按需打开网页操作面板。模拟不点击、不发送;真实测试确认后才执行。路径使用自然语言说明,技术 JSON 默认折叠。
  • 导入 / 导出:支持工作流数组,以及 { "workflow": [...], "selectors": {...} }。导入只更新草稿,仍需保存配置。
  • 兼容工具:纯线性流程可展开旧版详细参数编辑器。所有节点的原始字段均保留;复杂脚本、点击验证等还可通过“更多原始参数”编辑。

网页内可视化工具保留页面操作与高级编排两种视图,共用一棵工作流树;标记只是节点的页面投影,不会按悬浮球下标回插重建流程。通过本地注入完整 JS/CSS,不依赖目标网站访问控制台或 CDN。支持拾取页面元素、收起 / 恢复、保存桥接、测试时隐藏,以及失败轨迹回推。

网页内可视化:先看页面,再改流程

点击控制台的「可视化」后,现在默认打开页面操作视图,不再直接打开覆盖网页的大画布。 已注入旧版本时,先保存草稿,再从控制台重新注入一次;后端会清理旧实例并载入新代码。

  1. 看位置:网页上的数字与侧边步骤列表一一对应。点击步骤或「上一步 / 下一步」,会高亮对应目标并滚动到它。这只是查看,绝不会自动点击、输入或发送。
  2. 改位置:拖动网页标记(目标找不到时也可拖列表中的数字)到新的网页元素。普通点击 / 输入 / 读取保存独立定位器;只改当前步骤,不修改共用定位器的其他步骤。坐标点击保存视口坐标,滚动步骤可分别拖动起点和终点。
  3. 不用拖也可以:「重新选取元素」进入选取模式。点击目标不会触发网页本身的按钮;Esc 取消,不改配置。自动生成唯一 CSS 定位器,不会仅保存模糊的 button 标签名。
  4. 看它做什么:等待、按键、脚本、变量和控制节点会解释作用,不会伪造点击位置。分支内有独立路径;设计序号不表示两侧都会执行。
  5. 改常用参数:侧边直接修改输入内容、等待时间和快捷键。分支、映射和其他高级参数通过「分支与变量」进入编排视图;选中节点后可回到网页查看同一步。
  6. 保存与验证:先保存配置,再选择「真实测试」。填写可选模型名及测试正文,高级变量入参默认折叠。确认后才执行;界面会隐藏,按每个网页动作显示目标高亮。测试轨迹决定实际经过了哪些分支。
  7. 停止测试:执行时可点击「停止测试」,停止后续步骤。取消是协作式的,要等待当前浏览器调用结束,不能撤销已经发生的发送、点击或上传。

右下入口、页面操作面板标题和编排画布标题都支持鼠标 / 触屏拖动;移动被限制在视口内,窗口缩小时自动收回。拖动不会误触发开关。收起后标记不再遮住网页,重新展开保留草稿;销毁 / 重注入会清理标记、选取遮罩、事件和定时器。

页面预览的真实边界

  • 支持 CSS(包括 css: 前缀)、XPath、简单 tag: / @属性=值。执行器专属的其他复合语法会明确提示不能在页面预览,不会擅自猜一个目标。
  • 动态页面和滚动 / 尺寸变化会重新定位;暂时不存在或不可见的目标会说明原因,仍可重新选取。
  • 设计视图不猜测运行时变量。真实测试的即时高亮使用执行器已经解析的定位器 / 坐标;这些临时值不进入持久化轨迹。
  • 不把跨域 iframe 或 Shadow DOM 内部元素误当作外部按钮进行绑定;这类场景需要在对应页面操作或配置执行器支持的高级定位方式。
  • 真实测试超时或网络结果不明时,不自动转桥接重放,以免重复发送;会显示无法确认的状态并请求停止。
  • 保存回执只确认已提交的版本,不覆盖等待回执期间继续编辑的草稿。

新增回归:python -m pytest -q tests/test_workflow_page_guide.py。使用真实 Chromium 合成网页,覆盖鼠标和触屏拖动、唯一定位、分支内修改、坐标 / 滚动端点、Esc 取消、普通参数、保存 / 撤销 / 重载、延迟回执、测试高亮与停止、网络结果不明不重放、销毁,以及修改后的定位器通过 FlowProgram 实际点击新目标。截图中的页面是合成测试页,不代表已登录任何第三方 AI 网站。

推荐模式:先读取,再决定是否操作

  1. SET 把外部请求值映射为页面使用的标签。
  2. CAPTURE 读取当前页面状态。
  3. IF 比较当前值与期望值。
  4. 只有不一致才进入切换分支;一致时直接汇合。
  5. 继续填写、发送和等待响应。

可导入示例:state-aware-workflow.json。示例用模型名称演示,但同样适用于语言、搜索范围、排序、输出格式等任意状态。示例选择器是演示值,必须改为实际站点的选择器,不能直接用于生产网站。

在控制台模拟这个示例:

  • 测试模型:gemini 3.1 Pro
  • 页面状态样例:{"current":"Pro"} → 选择 else,不执行切换动作。
  • 改为 {"current":"Flash"} → 选择 then,计划执行两次切换点击。

模拟不访问页面,不保证选择器有效,也不验证实际重试 / 兜底效果;轨迹中的 planned 仅表示计划执行,不是已经执行。

多情况分支:遇到什么情况,就做什么

在「添加步骤 → 变量与控制」中选 按情况处理(SWITCH)。每个节点支持 1–32 种情况:

  1. 为情况命名,选择条件,再在对应路径添加步骤。
  2. 用上移 / 下移调整优先级;从上到下检查,只执行第一个命中的情况。后续条件也不再求值,不会因为多个条件成立就重复发送。
  3. 所有条件均为假时走「其他情况」。默认路径和某个情况的步骤均可留空;空路径表示不做额外动作,继续后续流程,并不是失败或停止。
  4. 条件读取错误、变量不存在等仍是错误,不等同于条件不成立;不会静默转入默认路径。既有 TRY、取消与预算规则继续生效。
  5. 保留原 IF 两路条件和线性工作流,不会打开即转换。修改情况、跨路径移动、撤销、导入 / 导出和网页标记共用同一棵树。

可导入 multi-case-workflow.json:读取菜单状态,区分「关闭」「已打开」「已选好」,其他状态仅提示。定位器为演示值;示例不发送消息,也未自动应用到 Gemini 或 DeepSeek 预设。

模拟时直接在 menu_state 状态样例中输入文本 closed、open、selected 或任意其他文本,对比命中的路径。技术路径使用 root.1.steps.1.case_0.0 / default,在轨迹里点步骤即可展开祖先并定位。

样例表单与真实执行的区别

  • exists 样例默认提供布尔选择;文本 / 属性读取默认文本。属性字符串 "true" 与布尔值 true 不等价,可逐项选择类型。
  • 「使用已配置的默认值」只填入显式配置了 default 且尚未填写的状态;未配置的状态不会假定为 false 或成功。缺少运行到的 CAPTURE 样例时明确报错。
  • 表单与高级 JSON 双向同步,保留未引用的自定义键。非法 JSON 不会用旧数据试跑;修改样例后,尚未返回的旧模拟结果不再显示为当前结果。
  • 控制台的「打开网页操作面板」仅打开编辑器,不执行。网页内「运行真实测试」继续使用原确认、运行 ID、取消和回执机制。

请求入参与变量

Chat Completions、Responses 及标签页 / 分组请求支持可选的 workflow_variables 对象,例如:

{
  "model": "gemini 3.1 Pro",
  "messages": [{"role":"user","content":"你好"}],
  "workflow_variables": {"language":"zh-CN","desired_mode":"Pro"}
}
命名空间 含义
inputs.name 外部入参的只读副本
vars.name 本次请求中当前可见的变量;组内局部优先
context.model / context.prompt 执行器提供的请求上下文
error.type / error.attempt 进入兜底时可见的错误类型与尝试次数

{model}、{desired_mode} 是便捷形式,先查当前变量,再查上下文。{{context.model}} 明确读取请求模型,避免被同名变量遮蔽。完整占位符保留 JSON 类型,嵌入文本时转成字符串。

全局指本次执行的全局,不是服务进程共享变量。组内 local 变量退出组后释放。输入分块 / 工具调用的下一轮重新建立运行时;不会把上一轮变量偷偷带入下一轮。

DSL

顶层仍是动作数组。控制节点使用 action 与对象形式的 value;可选 label 只用于显示。

动作 value 结构
SET {name, value, scope: "local"/"global", mode: "assign"/"default"}
CAPTURE {name, source, selector?, attribute?, timeout?, default?, scope?}
IF {condition, then: [], else: []}
SWITCH {cases: [{label?, condition, steps?: []}], default?: []}
GROUP {variables: {}, steps: []}
GUARD {condition, mode: "skip_group"/"goto", anchor?}
TRY {steps: [], attempts: 1..5, delay: 0..5, retry_side_effects: false, errors: ["*"], fallback?: []}
LABEL {name}

CAPTURE.source 支持 text、attribute、class、url、exists、value。优先使用节点内的直接选择器,否则从 target 对应的共享选择器读取。无匹配元素时 exists 返回布尔值;其他类型可提供 default,否则报错。

GUARD 的 skip_group 跳过当前组剩余步骤;顶层使用时结束流程。goto 只能前往同一分支内后方的 LABEL,不允许向后跳、跨分支跳转或无限循环。

普通叶动作可以使用 selector 提供直接选择器。编辑器创建 / 修改的叶节点带 flow_version: 2,显式开启变量解析;原有未修改、无控制节点、无外部变量的线性流程继续使用原执行路径。

表达式

不使用 eval,不执行 Python / JavaScript 表达式,不允许对象属性遍历。

{"$var":"inputs.language","default":"zh-CN"}
{"$map":{"gemini 3.1 Pro":"Pro","gemini Flash":"Flash"},"input":"{{context.model}}","default":"{{context.model}}"}
{"$transform":"trim","input":"{current}"}

转换白名单:trim、lower、upper、string、number、boolean、urlencode、css_escape、json。{"$literal": ...} 可绕过占位符解释。映射未命中且没有默认值时明确报错,不猜测目标值。

JS_EXEC.value 不由新引擎插值,仍交给原脚本加载器处理其宏、外部文件、参数和运行上下文,避免把脚本源中的大括号当作新表达式。

条件

{"left":"{current}","op":"ne","right":"{desired}"}

比较操作:eq、ne、contains、starts_with、ends_with、matches、exists、not_exists、gt、gte、lt、lte、in。

支持 {"all":[...]}、{"any":[...]} 和 {"not": ...},采用短路求值。eq / ne 严格区分类型,例如 0 不等于 false。大小比较仅接受数字,请先做转换。

正则通过独立 regex 库执行,模式最多 512 字符,输入最多 65536 字符,每次求值预算 25ms。

重试、安全与执行边界

  • TRY.attempts 包含首次执行,最多 5 次;间隔最多 5 秒。
  • 默认只自动重复已知无副作用动作(WAIT / READONLY_HINT)或显式 retry_safe: true 的叶动作。
  • 点击、填写、发送、上传等默认视为有副作用。只有确认整个重试块幂等后才允许 retry_side_effects: true;不要用它掩盖发送确认或上传状态错误。
  • 重试会恢复该块进入时的变量快照;已经发生的页面副作用无法回滚。
  • 一旦对外输出任何流片段,就禁止后续恢复,包括输出发生在进入 TRY 之前的情况。
  • 取消、控制流限额、发送确认失败、附件错误及终端流错误不可通过普通 TRY 恢复。
  • 结构化流程不再被旧的外层终端错误逻辑整体重放,避免绕开 TRY 的副作用保护。未修改的旧线性流程保持原策略。
  • 页面请求后的兼容“消费后续发送步骤”只扫描相邻普通叶动作,遇到控制指令停止,不能跳入未选择的分支。不要在不同分支 / 组中配置两次独立发送并期待自动去重。
  • 每个真实叶动作仍由原 browser 主循环处理会话、发送确认、媒体、取消和清理,不是另起一个绕过生命周期的递归执行器。

上限:1000 节点、16 层、工作流 JSON 1 MiB、外部入参 128 键 / 64 KiB、当前变量总量 256 KiB、单变量 64 KiB、10000 次控制转换、默认执行预算 300 秒。页面内测试采用 45 秒停止预算。底层浏览器 / 网络调用仍依赖自身超时,预算不是进程级强制抢占。

验证、测试与监控

  • POST /api/workflow/validate:递归校验完整树,包括未选中的分支;不保存、不连接浏览器。
  • POST /api/workflow/preview:接受 workflow、workflow_variables、model、capture_values,用同一解释器计算路径,返回 mode: "simulation"。
  • 页面内真实测试继续走 /api/workflow-editor/test 或现有本地桥接,使用正式 FlowProgram 与 WorkflowExecutor。成功和失败均回传已有轨迹,并在 finally 清理、释放标签页。
  • 生产请求的轨迹写入请求历史详情。多轮 / 分块轨迹追加并带 run 标记,最多保留 500 条;列表接口移除轨迹以控制体积。
  • 轨迹只保存路径、动作、状态、分支、尝试次数等结构信息,不保存变量值、提示词、页面捕获内容、选择器或错误正文。

维护与回归

核心:app/core/workflow/flow_runtime.py。纯模拟入口:app/core/workflow/preview.py。

页面操作视图:static/js/workflow-page-guide.js,自带隔离样式;共享编排 UI:static/js/workflow-studio.js;样式源:static/css/workflow-studio.css。修改 CSS 后执行:

python scripts/bundle_workflow_studio_css.py

CSS 被嵌入共享 JS,确保网页注入完全离线可渲染。注入器对编排组件、页面操作组件和注入入口的修改时间共同检测缓存失效。

python -m pytest -q tests/test_workflow_flow_runtime.py tests/test_workflow_studio_integration.py
python tests/browser_workflow_studio.py

浏览器回归使用真实 Chromium 和合成页面;控制台配置写入均拦截,前后校验 sites.json 哈希。覆盖嵌套分支保存、模拟选路、节点包裹 / 撤销、网页内无损序列化、保存桥接、失败轨迹、销毁,以及明暗主题和手机布局。

当前验证边界

  • 已通过引擎单测、请求模型 / 编辑器适配器 mock 测试,以及控制台与注入 UI 的 Chromium 回归。
  • 未使用真实登录的第三方 AI 网站完成生产请求端到端测试,不能据此承诺具体网站的选择器和模型切换已经验证。
  • 全套仓库测试尝试受当前缺失的 Arena 自动对战命令配置阻塞;另有旧 JS 测试依赖缺失的 custom_scripts/examples/arena_payload_interceptor.js。没有为使测试变绿而补造这些业务配置或脚本。

站点编辑页的按需设置栏

默认隐藏步骤检查器并居中主干,点击节点后平滑让出右侧设置空间,关闭或 Escape 后居中恢复。移动端使用覆盖式设置面板;关闭后焦点返回步骤。宣传大标题已移除,注入树的拖动功能由紧凑手柄承接。

完整预设迁移请使用站点预设栏的「导入 / 导出」。树工具条明确为「导入工作流 / 导出工作流」,只含流程和定位器。单预设与整站导入导出、草稿保存和冲突处理详见 站点配置说明。

页面悬浮导航:布局与收起行为修正

  • 删除悬浮导航的大标题和常驻三段说明。使用「步骤列表 / 步骤设置」两个互斥视图,默认显示列表;选步骤只查看页面位置,编辑参数时再切换设置。
  • 全面板只保留一个内容滚动区。标题、视图切换、前后步和底部操作不收缩;说明与列表不再各占固定高度,低高度窗口中不裁掉保存或高级入口。暗色模式使用对应的原生滚动条颜色。
  • 「收起」和右下入口收起仅隐藏面板,页面数字标记保留;收起后仍可查看、拖动修改定位,滚动页面时继续更新位置。右下入口明确显示「展开步骤 · 标记保留」。
  • 「页面标记」独立决定是否显示标记;「显示全部位置」决定全部步骤或仅选中步骤。用户关闭标记后,收起再展开不会擅自重新打开。
  • 兼容性:旧 WorkflowEditor.hide() API 仍完全隐藏编辑层;进入高级树或实际测试时仍清理交互标记,真实测试反馈保持被动,避免编辑标记挡住真实点击。
  • 新增回归涵盖 1320×1080、808×650、390×650、700×360 的布局边界、互斥视图和操作可见性,以及收起后拖动、滚动、标记开关记忆、旧 API 完全隐藏。