xworkmate-app/docs/plans/2026-03-20.md

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