Skip to content

gui-design.md

Latest commit

 

History

History
160 lines (101 loc) · 19.8 KB

gui-design.md

File metadata and controls

160 lines (101 loc) · 19.8 KB
Raw

GUI 重构设计

日期：2026-10-22。本文是本轮 GUI 重构的唯一设计与验收记录。

目标与依据

以用户提供的 Codex 风格截图为布局参考，把现有「群聊 + 常驻成员面板」调整为以任务为中心的工作台：导航清晰，输入突出，过程与证据按需展开。采用 Vue 3、Nuxt UI 和官方 Vue Dashboard 模板 的布局组件及组合方式；继续使用 Vite 构建和现有 Python 静态资源部署。

模板采用 MIT 许可证，保留其归属及许可文本。模板的示例客户、收入、通知和账户数据不进入产品。只展示服务或本地会话实际拥有的信息。

页面与模块

模块 内容与交互 边界
应用布局 UApp、UDashboardGroup、UDashboardSidebar、UDashboardPanel、UDashboardNavbar；窄屏折叠导航 统一主题、Toast、焦点和弹层
导航与会话 单侧栏内放品牌、新任务、搜索、运行记录、会话和设置；主题、刷新、身份验证收进页头「更多」 会话仍仅保存在当前浏览器；删除需要确认；不虚构项目目录或云端同步
新任务主页 简短欢迎语与居中输入框 移除示例任务卡片；不替用户选择完成条件
输入区 多行目标、发送/停止、右下角模型选择、完成条件和单一「任务设置」入口；协作方式、成员、能力按需展开 保留 executionInput 校验；中文输入法 Enter 不提交，Shift+Enter 换行
任务时间线 用户目标、执行状态、模型输出、人工确认和详情入口 SSE 与轮询、取消、恢复、错误状态及 Token 记录沿用现有协议
运行记录与详情 侧滑面板内显示服务端记录、黑板图、Fact/Intent/Hint、来源、人工补充及旧引擎详情 不将草稿存储成功描述为事实准确；不增加费用/累计 Token 额度
设置 模型服务、Agent 提示词、运行参数三个独立页面区域 保留现有 API、加密密钥写入、保存后重启提示、部署 API 验证

视觉规范

  • 深色为新用户默认，尊重已保存的浅/深色选择；背景采用中性炭黑，灰色层级区分侧栏、主面板和输入区。
  • 桌面采用默认 224px 的可调单侧栏和 52px 页头；消息、输入区、设置页共用 800px 内容列。侧栏宽度跨页面持久化，详情按需打开。
  • 以系统中英文字体、细边框、轻量图标和 8/12/16/24px 间距建立层次。发送按钮明显，其余操作使用低对比度按钮；不添加装饰性渐变或虚构指标。
  • 空白页输入框在视觉中心，消息出现后固定在工作区底部；长列表独立滚动。手机端采用抽屉导航，输入区不超出视口。
  • 所有图标按钮有可访问名称；支持键盘、焦点可见、弹层 Escape 关闭、减少动态效果偏好。

实施顺序

  1. 核对模板与依赖：引入 Nuxt UI/Vite 插件、Tailwind 与本地图标，建立 UApp 和主题；保留模板许可。
  2. 重构导航布局：使用官方 Dashboard 布局组件，拆出主页欢迎模块，保持会话与设置导航行为。
  3. 重构输入和时间线：压缩首屏控制项，将高级选项按需展开；保留完成条件、成员/能力配置、停止和人工反馈。
  4. 迁移详情与设置控件：采用 Nuxt UI 和语义化原生控件，移除 Element Plus 依赖及旧的叠加样式。
  5. 验证与收尾：类型检查、组件/状态回归、生产构建；浏览器检查桌面/手机和深浅主题，验证空白、运行、错误、设置和弹层；更新现有 README 技术说明。

验收依据

  • 首页、会话搜索/切换/删除、主题持久化、移动导航和设置入口可用；无装饰性假功能。
  • 黑板任务必须明确完成条件；回滚后禁止新黑板任务；显式 legacy 路径仍可用。
  • 模型服务配置、提示词恢复、运行参数、运行记录、黑板查询和人工输入保留。
  • npm run type-check、npm test、npm run build 通过，浏览器无未处理错误；375px 与桌面宽度没有横向溢出。
  • 首轮布局重构不改后端执行协议；后续协议扩展见下文。不迁移/删除用户本地会话，不创建第二份重复进度表。

执行记录

以下按阶段保留验证证据；当前界面以文首规范及末尾简化调整为准。

2026-10-22：以上五步已完成。模板参考版本为 nuxt-ui-templates/dashboard-vue@25858b2f6a02fac629cb42ddfc7712695b74c8e3，许可见 Nuxt UI Templates MIT。

  • 接入 Nuxt UI 4.12、Tailwind CSS 4、Dashboard 布局及中文组件文案；Element Plus 与旧组件解析插件已移除。导航、输入、消息、详情和设置均已迁移。
  • 新用户默认深色，保留已有主题和会话存储键；移动端采用 Dashboard 抽屉。图标在构建时打包，浏览器用例检查没有外部资源请求。
  • 详情与设置按需加载。主 JS 约 479 kB、gzip 约 151 kB，黑板图独立分包；清理旧 CSS 叠加样式。
  • 本地通过：57 项组件/状态测试、12 项 Chromium 桌面（1440×1000）/手机（375×812）回归、TypeScript 检查、生产构建、发布元数据检查与差异检查。
  • 浏览器覆盖完成条件拦截、中文输入法 Enter、Shift+Enter、SSE 结果、黑板详情、会话删除确认与搜索、主题持久化、Provider 模型名称与保存、Prompt 保存与恢复、运行参数保存、断线重连保留输入；检查无页面未处理异常和横向溢出。
  • CI 前端任务已增加 Chromium 回归步骤。上述验证使用隔离的 API 响应样例，未发起真实模型调用；本轮未重测 Windows 安装包或 Docker 发布产物。

复核命令：

npm --prefix frontend ci
npm --prefix frontend run type-check
npm --prefix frontend test
npm --prefix frontend run build
npm --prefix frontend exec -- playwright install chromium
npm --prefix frontend run test:e2e

上游连接与协议扩展（2026-10-22）

本轮在同一设计记录内补充模型连接功能：独立 /settings?section=models 页面采用「连接信息 → 获取模型 → 默认模型 / Agent 分配」顺序，首页文案统一为目标、协作、证据与结果。

实施顺序：先抽取公共 HTTP 传输并保留 OpenAI 兼容配置，增加 Anthropic Messages 适配器；再增加只读模型发现 API，复用已保存的凭据、支持分页并限制响应大小与超时；随后补齐三种协议、HTTP 开关、鉴权和可搜索模型选择；最后验证协议报文、工具往返、缓存 Token 统计、发现失败与页面保存。

接口依据：OpenAI Responses / Chat Completions、Anthropic Messages，以及 new-api 转发路由、sub2api 网关路由。连接使用推理 API Key 和 /v1/models，无需网关管理账号。模型发现不推断协议支持能力，不自动切换渠道或创建运行。保留手动模型 ID，兼容没有模型列表接口的服务。

本轮验证：三种协议均完成桌面/手机模型拉取、搜索、选择和保存回归，另覆盖失败重试、空列表保留已选项、连接改变时取消过期请求；浏览器共 22 项、组件/状态共 57 项。新增后端协议与模型发现用例 26 项通过；全量后端 628 项通过、202 项因条件未具备跳过。实际对现有上游执行一次模型发现，返回 6 个模型且包含 gpt-5.6-sol；没有发送推理请求，Claude 原生报文与工具往返由 MockTransport 验证，未作真实 Claude 渠道验收。

统一布局与 Codex 调研（2026-10-22）

本轮先研究官方界面及交互，再通过内置 image_gen 制作 布局概念稿，随后实现。生成时的完整提示词保存在 布局提示词。概念稿用于确定比例、层级与对齐，后续简化已将双层导航合并为单侧栏；图中的示例账号、会话、模型、存储数字和附件操作不代表产品功能。实际页面只展示已有的数据和操作。

官方依据与设计判断

检索时，原 developers.openai.com/codex/app 系列地址重定向至 ChatGPT Learn。核对了当前页面正文，并在浏览器中检查了官方项目侧栏和外观设置插图。用户提供的桌面截图用于补充整体空间关系。

研究对象 官方资料中的结构 本项目的采用方式
项目与会话 侧栏组织项目和会话，支持查找历史内容 工具栏放全局入口，侧栏放本地会话、搜索与新任务；设置页同一位置换成分类导航
外观与设置 分类设置、浅深主题、界面字体与前景/背景颜色；官方插图中深色背景为 #181818 用中性灰区分工具栏、侧栏、主内容、输入层；系统字体；减少常规说明的大色块，状态颜色保留语义
审查面板 在专门面板中查看变化及对应证据，并据此提供反馈 保留按需打开的运行详情、黑板与人工反馈，统一详情页头、边距及滚动容器
移动端工作流 移动端围绕开始、引导、检查任务等关键操作组织界面 窄屏隐藏工具栏和常驻侧栏，用抽屉提供导航；完成条件和发送控制仍在输入区内

52px / 224px / 800px 等具体尺寸是本项目的设计取值，未将其声称为官方尺寸规范。复用的是会话优先、低对比层级和按需展开的组织方式；Work Harness 仍使用自身品牌和黑板协作协议。

实施边界与落地

按「共用外框 → 主页与输入区 → 设置与详情 → 跨页面和视口验证」顺序实施。WorkbenchShell.vue 统一 Dashboard、工具栏、品牌、面包屑、连接状态及侧栏尺寸存储；GroupChatLayout.vue 只组合任务内容，SettingsPage.vue 只组合设置分类。共享 --shell-header-height、--content-width、--page-gutter 和圆角变量，避免页面各自定义相近但不相同的尺寸。

首页缩减重复标记与说明，保留目标、完成条件及任务建议。设置表单采用细分隔线、统一字段间距和固定于滚动区域底部的保存栏；密钥说明按需展开，异常和重启提示仍明确显示。提示词、运行配置、模型连接和详情面板使用同一组颜色与间距。手机设置导航在选择分类后关闭，运行记录可从桌面的任意主页面打开。长会话只滚动消息区域，输入区和页头保持可用。

保留 Vue 3 + Nuxt UI + 官方 Dashboard 模板基础、主题和会话存储键、Responses / Chat / Claude 配置、HTTP 与模型发现，以及 SSE、任务完成条件和全部后端协议。

本轮验收

本地类型检查、生产构建、57 项组件/状态测试、26 项 Chromium 浏览器回归全部通过。浏览器使用隔离 API 样例，不发送真实模型请求。新增用例验证跨页尺寸一致、拖拽后的侧栏宽度保持、手机设置导航关闭、草稿保留，以及长内容下页头/输入区固定与消息独立滚动。覆盖桌面 1440×1000、手机 375×812，并对长会话检查 320×640、768×680、1280×720；未出现横向溢出或页面未处理异常。深浅主题均完成截图检查。

实际页面截图：桌面首页、手机首页、浅色首页、模型设置。截图中的连接及模型响应是隔离样例。正式界面继续读取实际服务状态。设计图和截图只用于文档，未作为网页运行时图片资源。

地址自动兼容调整

模型连接页移除 HTTP/HTTPS 说明、拼接后的请求地址预览以及 HTTP/私网许可勾选框。地址输入支持域名、IP 和完整接口路径，后端统一归一化并用于模型发现及推理；粘贴 Responses / Chat / Claude 完整推理端点时同步选择相应 API 协议。只填写网关根地址时保留手动协议选择，不通过模型名称猜测网关能力。相关格式、环境覆盖与旧部署限制说明见 Provider 兼容性。

本次地址调整通过 102 项后端相关回归；补充查询参数内含 URL 的边界用例后，地址专项 35 项通过（本次共覆盖 103 个不同后端用例）。前端 57 项组件测试、26 项浏览器回归、类型检查和构建通过；完整接口地址自动选择三种协议已在桌面和手机验证，截图已更新。测试使用模拟上游，未发送真实模型请求。

功能入口简化

按用户要求减少常驻控件，保留任务开始、必要配置、运行记录和结果查看：移除窄工具栏与三张示例任务卡，采用单侧栏；输入区只保留任务设置、完成条件及发送/停止。协作方式、分配、风险、成员和能力合并到任务设置，成员与能力进一步折叠。页头「更多」容纳主题、刷新和部署身份验证。

模型设置常驻连接信息、模型选择及保存/取消；鉴权、密钥来源和协议兼容参数归入高级连接设置。移除重复返回入口，设置读取失败时才显示重试按钮。折叠仅影响展示，已选择的任务选项和模型配置仍参与保存。完成条件保持显式选择。

本次通过 57 项组件/状态测试、30 项桌面/手机浏览器回归、类型检查和生产构建。新增浏览器用例覆盖折叠后选项保留、引擎切换、更多菜单身份验证、高级连接配置保存，以及读取失败后的重试入口。同步刷新桌面、手机、浅色及模型设置截图。浏览器仍使用模拟 API，未调用真实模型；后端执行逻辑未改动。

模型选择与推理配置：实施设计

聊天框右下角在发送按钮旁放模型选择器，显示「模型 · 当前推理档位」；保留「跟随项目设置」，不覆盖既有阶段/Agent 路由。显式选择时，整次任务固定 Provider、模型及设置页保存的档位，重试和恢复保持同一选择，不静默切换模型。推理测试及档位编辑主要放在模型设置页。

实施顺序：

  1. 建立模型验证记录与推理参数适配：Responses 使用 reasoning.effort，Chat 使用 reasoning_effort，Claude 使用 output_config.effort；Claude 的自适应思考模式随测试报文验证。支持 none/minimal/low/medium/high/xhigh/max 及扩展字符串，保持原值，不把 xhigh 和 max 互相映射。

  2. 设置页对指定模型执行默认调用、无效档位对照及各档位探测。只开放调用成功且参数校验得到证据、或用户明确确认渠道应用参数的档位；两类结果分别标记来源。HTTP 成功且没有校验或确认依据则标为未确认，网络/鉴权失败不等同于不支持。结果绑定地址、协议、凭据和报文兼容配置；连接变更后重新测试。测试使用固定无敏感信息的小任务，不执行工具。

  3. 增加验证接口和可选模型目录，任务请求持久化选择，经服务端验证后传至 legacy 和黑板 Agent 的每次调用。保留原有 Skill 的 Provider 限制，冲突时明确拒绝。

  4. 前端接入设置页验证结果、默认档位与聊天框模型选择。覆盖切换、失效、移动布局、任务参数传递；后端覆盖三种报文、忽略参数、超时、旧配置恢复和并发任务隔离，最后使用既有上游实测当前模型。

任务设置中的能力模块只负责启用 Skill，不再提供模块级模型服务选择。模型统一在输入框右下角选择， 未指定时遵循项目配置；上游连接与推理档位在设置页管理。旧会话恢复时清除模块级 Provider 指定， 保留已选能力、会话模型和历史结果；后端继续执行 Skill 本身的兼容性约束。

验证范围：分别记录接口校验与渠道确认依据；不将 HTTP 成功直接视为参数生效证明，也不证明真实推理深度或业务质量。模型列表仅证明可发现，不能直接作为推理能力证据。官方依据：OpenAI Reasoning、GPT-5.6 Sol、Claude Effort。本节是现有方案的补充，不新增重复计划表。

本节已实现。当前 gpt-5.6-sol 在 Responses 渠道的默认调用及七个候选档位均返回完整小任务结果；无效档位对照也被接受。用户随后明确确认该渠道应用推理参数，因此将官方支持且调用成功的 none/low/medium/high/xhigh/max 标记为「渠道已确认」，minimal 保持未确认。验证记录已保存至原 Provider 配置，并通过重新构建运行时确认模型目录可读；默认档位仍为空，跟随上游。脱敏实测记录。其他上游需分别测试，Claude 和 Chat 本轮通过协议模拟测试，未发送真实渠道推理。

验证结果：类型检查、构建、57 项组件/状态测试和 38 项桌面/手机浏览器回归通过。后端覆盖 927 个不同用例，含真实 PostgreSQL 16 API/Worker、备份恢复、三种推理报文、并发路由和两个引擎的模型选择。全量执行中 926 项通过，唯一新增用例因 Mock 配置没有预置模型而报错；修正该测试样例后，76 项模型/工作流专项复测全部通过。验证记录刷新不改变执行配置标识，旧任务及幂等重试仍保留原模型选择。

最新界面：聊天框模型选择、手机输入区、设置页推理配置、手机推理配置。设置截图采用示例地址和当前渠道验证结果，不展示密钥。

Codex 桌面端风格模块深化（2026-10-23）

参照用户提供的 Codex 桌面端工作台界面，在保留 Vue 3 + Nuxt UI + 官方 Vue Dashboard 模板架构与全部后端契约的基础上，完成以下 UI 模块升级：

  1. 双层导航与项目分组侧栏：桌面端在 WorkbenchShell.vue 左侧提供 48px 全局快捷栏（.codex-rail），容纳工作空间、快速新任务、运行记录、设置中心、主题切换及连接状态徽章（移动端自动隐藏并复用 Dashboard 抽屉）。ChatSidebar.vue 支持会话置顶（「置顶」分组）与 📁 work-harness 项目分组折叠，会话列表收敛为紧凑单行胶囊。
  2. 去头像化对话流与终端步骤折叠行：MessageBubble.vue 移除群聊头像框与重型边框卡；用户消息采用右对齐圆角胶囊，执行阶段、分工、成员产物、复核及工具/模型调用整合为 [>-] 已运行步骤 / 正在运行 ▾ 终端风可展开步骤行（.codex-step），最终输出以无边框排印流加底部轻量工具栏（复制、查看过程与证据、停止任务、状态徽章）呈现。
  3. 一体化胶囊输入框：ComposerBox.vue、RunModeOptions.vue 与 ComposerModelSelect.vue 整合为无内部分割线的圆角容器，未选黑板完成条件时以琥珀色胶囊提示（.completion-pill.is-unselected），左下角提供 + 任务设置 入口，右下角展示 ⚡ 模型 · 档位 选择器与高对比度圆形发送按钮。
  4. 验证记录：npm --prefix frontend run type-check、npm --prefix frontend test（13 个文件 / 57 项测试）、npm --prefix frontend run build 及 npm --prefix frontend run test:e2e（38 项桌面/手机 Chromium 浏览器回归）全部通过。