138 lines
4.2 KiB
Markdown
138 lines
4.2 KiB
Markdown
# XWorkmate 菜单层级、状态页与面包屑优化实施计划
|
|
|
|
## 1. 背景与目标
|
|
|
|
本轮改造的首要约束是：保持截图对应的 `Assistant` 首页 UI 设计、侧栏分配和主壳布局不变，不新增新的一级路由，不改变首页主工作区的视觉结构。
|
|
|
|
在这个前提下，导航和页面职责收敛为稳定的三级模型：
|
|
|
|
- 1 级：保持现有 `WorkspaceDestination` 一级入口与侧栏分配
|
|
- 2 级：配置相关页面只负责快速查看状态和少量高频操作
|
|
- 3 级：详细设置参数统一进入 `Settings` 体系下的独立 detail 视图
|
|
|
|
本轮默认决策：
|
|
|
|
- `Assistant` 首页是唯一 Home
|
|
- `主页` 面包屑统一调用 `navigateHome()`
|
|
- 配置型页面采用 `二级状态页 -> 三级参数页`
|
|
- 二级页可以快速查看状态，但不再承载完整高级表单
|
|
- 三级参数页挂在 `Settings` 体系内，不新增新的一级路由
|
|
- 本轮不做 runtime 大拆分，但不得新增新的 `runtime -> app` 反向依赖
|
|
|
|
## 2. 导航层级与页面职责
|
|
|
|
### 一级入口保持不变
|
|
|
|
现有一级入口继续保留：
|
|
|
|
- `Assistant`
|
|
- `Tasks`
|
|
- `Skills`
|
|
- `Nodes`
|
|
- `Agents`
|
|
- `MCP Hub`
|
|
- `ClawHub`
|
|
- `Secrets`
|
|
- `AI Gateway`
|
|
- `Settings`
|
|
- `Account`
|
|
|
|
### 二级状态页
|
|
|
|
本轮重点覆盖四类配置型页面：
|
|
|
|
- `Modules`
|
|
- `AI Gateway`
|
|
- `Secrets`
|
|
- `Settings`
|
|
|
|
二级状态页统一遵守以下边界：
|
|
|
|
- 展示连接状态、健康状态、当前模式、最近结果和关键摘要
|
|
- 保留少量高频动作，例如刷新、重试连接、进入编辑设置
|
|
- 不再承载完整高级表单
|
|
- 不再出现重复的“打开全页”式独立配置入口
|
|
|
|
### 三级参数页
|
|
|
|
详细参数通过 `Settings` 的 detail 视图承载，第一批 detail 包含：
|
|
|
|
- `Gateway Connection`
|
|
- `AI Gateway Integration`
|
|
- `Vault Provider`
|
|
- `Ollama Provider`
|
|
- `External Agents`
|
|
- `Advanced Diagnostics`
|
|
|
|
`Settings` 是详细参数的唯一权威入口。`Modules / AI Gateway / Secrets` 只负责状态和进入编辑。
|
|
|
|
## 3. 架构收口与导航注册表
|
|
|
|
### 控制器状态
|
|
|
|
`AppController` 承担统一导航状态入口，新增以下能力：
|
|
|
|
- 配置型页面的 tab 状态
|
|
- `Settings` drill-in 状态
|
|
- `openSettings({tab, detail})`
|
|
- `closeSettingsDetail()`
|
|
- `navigateHome()` 返回 `Assistant` 首页并清空 detail 状态
|
|
|
|
### 共享导航注册表
|
|
|
|
`AppShell` 与 `MobileShell` 共用同一套页面注册元数据，统一描述：
|
|
|
|
- 一级入口
|
|
- Desktop / Mobile 共用的页面 builder
|
|
- `Settings` detail 的初始 tab / detail 注入
|
|
- `Modules / Secrets / AI Gateway` 的初始 tab 注入
|
|
|
|
本轮优先收口 `AppShell / MobileShell` 的 destination -> page 映射重复，不在 feature 页面里继续扩散新的页面分发逻辑。
|
|
|
|
### 面包屑规则
|
|
|
|
非首页页面统一支持通过面包屑回到 `Assistant` 首页：
|
|
|
|
- 一级工作页：`主页 / 当前页`
|
|
- 二级状态页：`主页 / 一级入口 / 当前状态页`
|
|
- 三级参数页：`主页 / 一级入口 / 二级状态页 / 当前参数页`
|
|
|
|
`Settings` detail 页面允许保留来源上下文。例如：
|
|
|
|
- `主页 / 模块 / 网关 / Gateway 连接参数`
|
|
- `主页 / 密钥 / Vault / Vault 提供方参数`
|
|
- `主页 / AI Gateway / 模型 / AI Gateway 集成参数`
|
|
|
|
## 4. 测试与验收标准
|
|
|
|
### 功能验收
|
|
|
|
- 首页截图对应 UI、侧栏、主工作区、输入区视觉不变
|
|
- `Modules / AI Gateway / Secrets` 只展示状态摘要和少量高频动作
|
|
- 详细参数通过 `Settings` detail 页面编辑
|
|
- 任意非首页页面可通过 `主页` 面包屑回到 `Assistant` 首页主路由
|
|
- `Settings` detail 页面可通过来源面包屑返回对应二级状态页
|
|
|
|
### 架构验收
|
|
|
|
- `AppShell` 与 `MobileShell` 共用同一套页面注册元数据
|
|
- 本次导航改造不新增新的 `runtime -> app` 反向依赖
|
|
- 导航规则和 breadcrumb 生成逻辑不再散落在各 feature 页面中重复实现
|
|
|
|
### 回归测试
|
|
|
|
本轮至少覆盖以下回归：
|
|
|
|
- `settings_page`
|
|
- `modules_page`
|
|
- `ai_gateway_page`
|
|
- `assistant_page`
|
|
- `sidebar_navigation`
|
|
|
|
补充的行为验证：
|
|
|
|
- 二级页点击 `编辑设置` 进入对应三级参数页
|
|
- 三级参数页 breadcrumb 可返回来源状态页
|
|
- 任意非首页页点击 `主页` 回到 `Assistant` 首页主路由
|
|
- 二级页不再承载完整高级表单
|