# 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` 首页主路由
- 二级页不再承载完整高级表单