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

219 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 通用工作流与 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](examples/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](examples/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` 对象,例如:
```json
{
"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 表达式,不允许对象属性遍历。
```json
{"$var":"inputs.language","default":"zh-CN"}
```
```json
{"$map":{"gemini 3.1 Pro":"Pro","gemini Flash":"Flash"},"input":"{{context.model}}","default":"{{context.model}}"}
```
```json
{"$transform":"trim","input":"{current}"}
```
转换白名单:`trim`、`lower`、`upper`、`string`、`number`、`boolean`、`urlencode`、`css_escape`、`json`。`{"$literal": ...}` 可绕过占位符解释。映射未命中且没有默认值时明确报错,不猜测目标值。
`JS_EXEC.value` 不由新引擎插值,仍交给原脚本加载器处理其宏、外部文件、参数和运行上下文,避免把脚本源中的大括号当作新表达式。
### 条件
```json
{"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 后执行:
```bash
python scripts/bundle_workflow_studio_css.py
```
CSS 被嵌入共享 JS,确保网页注入完全离线可渲染。注入器对编排组件、页面操作组件和注入入口的修改时间共同检测缓存失效。
```bash
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 后居中恢复。移动端使用覆盖式设置面板;关闭后焦点返回步骤。宣传大标题已移除,注入树的拖动功能由紧凑手柄承接。
完整预设迁移请使用站点预设栏的「导入 / 导出」。树工具条明确为「导入工作流 / 导出工作流」,只含流程和定位器。单预设与整站导入导出、草稿保存和冲突处理详见 [站点配置说明](site-studio.md#按需步骤设置与预设迁移v31)。
### 页面悬浮导航:布局与收起行为修正
- 删除悬浮导航的大标题和常驻三段说明。使用「步骤列表 / 步骤设置」两个互斥视图,默认显示列表;选步骤只查看页面位置,编辑参数时再切换设置。
- 全面板只保留一个内容滚动区。标题、视图切换、前后步和底部操作不收缩;说明与列表不再各占固定高度,低高度窗口中不裁掉保存或高级入口。暗色模式使用对应的原生滚动条颜色。
- 「收起」和右下入口收起仅隐藏面板,页面数字标记保留;收起后仍可查看、拖动修改定位,滚动页面时继续更新位置。右下入口明确显示「展开步骤 · 标记保留」。
- 「页面标记」独立决定是否显示标记;「显示全部位置」决定全部步骤或仅选中步骤。用户关闭标记后,收起再展开不会擅自重新打开。
- 兼容性:旧 `WorkflowEditor.hide()` API 仍完全隐藏编辑层;进入高级树或实际测试时仍清理交互标记,真实测试反馈保持被动,避免编辑标记挡住真实点击。
- 新增回归涵盖 1320×1080、808×650、390×650、700×360 的布局边界、互斥视图和操作可见性,以及收起后拖动、滚动、标记开关记忆、旧 API 完全隐藏。