# 通用工作流与 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 完全隐藏。