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

141 lines
10 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.
# 站点配置:总览、能力卡与按需配置(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` 仅控制站点配置内部布局,不覆盖全局导航或重新定义全站色板。
```sh
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 / 主预设):
```sh
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 升级与过滤说明](migrations/gemini-deepseek-v2.md)。