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

10 KiB
Raw Blame History

站点配置:总览、能力卡与按需配置(v3)

基于 490ccb2 的真实 Vue 控制台改造。v2 撤销了上一版独立的深石墨 / 紫蓝主题和 Logo 改动,直接继承其他页面已有的米白、橄榄绿、字体与导航样式。

页面结构

1. 站点总览

  • 使用卡片连接库,而非一进入页面就展示某个站点的长表单。
  • 展示真实站点总数、预设总数,以及默认预设核心字段未填全的站点数。
  • 卡片显示域名、默认预设、核心字段填写进度和预设数量;点击进入编辑。
  • 提供中文名称 / 域名搜索、待补全筛选、无结果状态、站点导出 / 删除菜单以及新增入口。
  • 总览底部仍可保存全部配置,避免新增 / 删除后没有保存入口。
  • 填写进度不代表站点在线或选择器验证成功。

2. 站点编辑

  • 通过“全部站点”面包屑返回总览。
  • 站点身份、预设管理与配置正文分层。
  • 桌面使用带任务说明的纵向配置目录:元素选择器、输入处理、响应解析、媒体提取、请求工作流、高级功能。
  • 手机改用紧凑的原生分类选择框,不将六个标签挤在一行。
  • 保留原有预设新建 / 克隆、重命名、默认预设、main 分支对比,以及附件与工作流配置。

3. 选择器分组编辑

  • 核心字段与辅助 / 自定义字段分组,辅助字段默认收起。
  • 点击某个字段展开编辑;未展开的字段显示定位表达式摘要。
  • 展开后显示多行等宽编辑器、字段用途、定位建议及测试入口。
  • 顶部的输入框 / 发送按钮 / 回复容器可直接打开并聚焦对应字段;缺少字段时可添加。
  • 搜索与未填写筛选保持可用,正在编辑的字段不会因输入内容变化而被移出 DOM。
  • 新增字段自动展开;自定义字段可改名并保留编辑上下文。

v3:先理解用途,再按需配置

保持 v2 已统一的主体、站点库与纵向目录,本轮重新组织模块内的信息层级,不重做全站主题。

默认展示用途、真实开启状态和必要摘要;常用参数放在第一级展开区,上传兼容、探测时间、识别规则等技术参数放在第二级。排查入口按症状命名,避免让普通用户以为每项都必须填写。

模块 默认看到 按需展开
输入处理 发送附件、长文本处理;当前文件限制与处理方式 文件数量/大小/类型 → 上传方式与错误识别;长文本阈值/方式 → 上传后适配
媒体提取 接收图片、音频、视频;区别于给 AI 上传文件 识别位置与提取时机 → 等待参数、Canvas、白名单、音频捕获;通用下载规则单独收纳
高级功能 隔离登录会话、等待输入框就绪、发送失败时自动恢复 每张卡只展开自己的规则;标明整个站点或当前预设
响应解析 正在读取网页还是网络、用途区别与切换影响 请求匹配与解析器 → 发送方式和匹配细节;等待上限按症状单独收纳
特殊提示词 明确提示会改变原消息,普通对话不必修改 开头占位、随机插入仍为两个独立开关
  • Cookie 开启的登录风险默认可见,保留原确认/取消流程。
  • 新开关保留原绑定、禁用条件及保存方式,使用可读的无障碍名称和键盘焦点样式。
  • 使用原生 details/summary,展开/收起不提交配置、不卸载字段,也不重置草稿。
  • 媒体开关关闭后仍保留识别位置、等待参数;沿用原行为将 run_policy 设为 disabled,重新开启采用原默认策略,而非承诺恢复关闭前的策略。
  • 中文提取策略仅改变显示文案,提交的枚举仍是后端原值。
  • 附件/长文本/提示词通过完整配置保存;媒体、响应、高级功能沿用原即时保存逻辑,未引入新队列或后端接口。

草稿与保存边界

  • 总览与编辑之间使用 v-show,不卸载 ConfigTab,避免丢失内部草稿。
  • 返回总览、选择站点前调用已有草稿 flush 方法,不另起一套保存队列。
  • Ctrl / ⌘ + S 保存完整配置;弹窗打开时不触发快捷保存。
  • “上次完整保存”仅在完整保存请求成功后更新,不代表没有未保存改动。
  • 未改后端接口、配置格式或现有保存队列。

文件与验证

static/css/site-studio.css 仅控制站点配置内部布局,不覆盖全局导航或重新定义全站色板。

python -m pytest -q \
  tests/test_site_studio_ui.py \
  tests/test_config_tab_save_queue.py \
  tests/test_attachment_ui.py \
  tests/test_attachment_browser.py \
  tests/test_attachments.py

本轮目标测试结果:58 passed。

Chromium / Playwright 另验证了:

  • 首页与配置页的导航背景、宽度、Logo 相同,深色模式亦一致。
  • 站点搜索、筛选、空状态及实际单站点 JSON 下载。
  • 核心字段快捷打开、连续输入、筛选、自定义字段新增 / 改名 / 删除。
  • 总览往返后编辑器保留同一个 DOM 节点及草稿值。
  • 六个配置分类、附件能力卡及嵌套配置入口可用。
  • 完整保存请求体、快捷键、成功 / 失败反馈(写请求拦截模拟,避免改写用户数据)。
  • 1280 / 1024 / 768 / 390 / 375px 下总览与编辑均无页面横向溢出,手机分类切换正常。
  • 未捕获的 JavaScript 异常为 0;config/sites.json 验证前后的 SHA-256 相同。

预览未连接已登录的受控浏览器,因此未进行第三方站点的真实定位与 AI 请求测试。

v3 新增交互回归

组件测试覆盖默认折叠、附件真实字段编辑、媒体策略枚举、关闭保留位置/等待参数、展开保留同一 DOM 节点、提示词两个开关独立性及 switch 名称唯一性。原附件合成网页上传与保存队列测试一并通过。

另提供可重复运行的真实控制台冒烟测试(本地服务需先启动,使用项目自带的 Google AI Studio / 主预设):

UWA_BASE_URL=http://127.0.0.1:8000 python tests/browser_site_capabilities.py

该脚本拦截所有写 API,仅在内存模拟响应,已验证:

  • 四个模块默认可见非开关参数为 0;逐层展开再收起,无写请求,完整保存 payload 不变。
  • Enter / Space 展开,跨模块往返后保留同一字段节点和草稿;附件更改正确进入完整保存请求。
  • Cookie 取消不写入,确认保存整个站点;输入等待/发送恢复正确保存当前预设。
  • 图片/音频/视频与网页/网络切换命中原接口,使用原始枚举。
  • 四模块在 1280 / 1024 / 768 / 390 / 375px 均无页面横向溢出。
  • 0 未捕获 JavaScript 异常;磁盘 config/sites.json 前后 SHA-256 相同。

最终还检查了四模块桌面、展开后的附件设置、手机与深色模式的真实浏览器截图。所有五个本轮组件的 @input/@change 绑定逐项对比修改前备份,完整保留。

按需步骤设置与预设迁移(v3.1)

  • 工作流默认主干居中,右侧设置栏收起。点选步骤后画布在桌面端平滑左移,设置栏淡入;「关闭设置」或 Escape 返回居中,并将键盘焦点还给原步骤。手机端使用右侧覆盖面板,支持减少动画的系统偏好。
  • 删除 Workflow Studio 的宣传大标题,仅保留紧凑的流程工具条。注入页面的高级树保留独立拖动手柄,页面标记与拖动功能不变。
  • 预设栏直接显示「重命名」,自动聚焦并选中原名称。默认预设、新建预设、保存配置保留。说明改为就近的悬停/键盘焦点提示;仓库对比与删除位于有文字的「预设工具」。
  • 「配置 JSON」明确显示文字;原“重新分析”实际上会删除整站配置,现位于「站点工具 → 清除配置,重新识别…」,保留删除确认。
  • 总览的两个入口分别为「按文件域名导入」和「导入到指定站点」,区别为自动识别文件域名与手动指定迁移目标。原确认弹窗仍明确同名覆盖和完全替换的范围。

当前站点的「导入 / 导出」

操作 精确范围
导入一个预设 从单预设、单站点或多站点 JSON 选择一个来源预设;可改名;同名默认建议新名称,明确替换需要再次确认。
合并站点配置 从文件选择一个来源站点,将其预设合并到当前站点;同名默认跳过,可显式确认覆盖。站点级设置默认不导入,可勾选;不改变当前默认预设。
导出当前预设 只导出当前名称对应的完整预设,包括未知扩展字段;不带兄弟预设或站点级设置。
导出整个站点 导出当前站点全部预设与站点级字段,不涉及其他站点。

单预设导出采用既有兼容包装 {domain, default_preset: 当前预设名称, presets: {当前预设名称: 完整配置}},既能回导到新面板,也能被原站点导入识别。文件最大 4 MiB。导入先校验全部待导入流程,全部通过才载入草稿,最后由用户点击「保存配置」提交。不会静默写服务器或修改其他站点;校验可取消,单次请求 30 秒超时,关闭或切站点后的迟到结果无效。

切换预设不再重新拉取整份配置,避免丢失本地草稿。新导入、尚未保存的预设可以继续重命名、克隆、设置默认或删除,这些操作仍作为草稿待保存。保存失败保留草稿;保存期间新发生的导入/预设操作不会被旧保存回执误清除。

工作流自身的「导入工作流 / 导出工作流」仅转移动作与流程定位器;新导出的片段带 kind: workflow 标识,预设导入面板会提示去正确的流程入口,而不会误将其替换成完整预设。

验证:python -m pytest -q tests/test_preset_transfer.py,以及服务启动后的 python tests/browser_preset_transfer.py。浏览器测试拦截所有配置写入,覆盖居中/展开/关闭、单预设完整导出与回导、草稿切换/重命名/保存、非法工作流拒绝、合并跳过同名、手机与暗色;截图使用合成工作流,不代表登录 AI 实站的自动化验证。

自动收录策略

未知页面的通用回退不再成为站点配置;搜索和登录页优先排除,其他页面需明确识别为 AI 聊天页且输入/回复定位匹配 HTML,才会自动加入。手动添加和导入仍保留。详见 Gemini / DeepSeek 升级与过滤说明。