xworkmate-app/docs/plans/2026-03-29-settings-assistant-ui-component-matrix.md

XWorkmate UI 组件盘点与清理基线

目标

基于当前截图批次，收口以下主链路的 UI 组件归属与清理候选：

1. Assistant 三栏工作区
2. 设置页
3. 账号页
4. SKILLS 目录授权

本文档只记录当前实际代码状态，不再保留已完成清理前的旧副本描述。

---

保留中的在用组件

名称	路径	Desktop	Web	Mobile
App Shell Desktop	lib/app/app_shell_desktop.dart	Yes	No	No
App Shell Web	lib/app/app_shell_web.dart	No	Yes	No
Mobile Shell	lib/features/mobile/mobile_shell_core.dart	No	No	Yes
Mobile Workspace Launcher	lib/features/mobile/mobile_shell_workspace.dart	No	No	Yes
Assistant Page	lib/features/assistant/assistant_page_main.dart	Yes	No	Yes
Assistant 主工作区拼装	lib/features/assistant/assistant_page_state_closure.dart	Yes	No	Yes
Assistant 左侧关注面板	lib/widgets/assistant_focus_panel_core.dart	Yes	No	No
Assistant 设置预览	lib/widgets/assistant_focus_panel_previews.dart	Yes	No	No
Assistant 设置快捷操作	lib/widgets/settings_focus_quick_actions.dart	Yes	Yes	No
右侧任务文件栏	lib/widgets/assistant_artifact_sidebar.dart	Yes	Yes	No
Desktop / Web 通用壳层	lib/widgets/desktop_workspace_scaffold.dart	Yes	Yes	No
Settings Page	lib/features/settings/settings_page_core.dart	Yes	No	Yes
Settings Page sections	lib/features/settings/settings_page_sections.dart	Yes	No	Yes
Settings Page widgets	lib/features/settings/settings_page_widgets.dart	Yes	No	Yes
Gateway settings	lib/features/settings/settings_page_gateway.dart	Yes	No	Yes
Gateway connection settings	lib/features/settings/settings_page_gateway_connection.dart	Yes	No	Yes
Web Settings Page	lib/web/web_settings_page_core.dart	No	Yes	No
Web Settings sections	lib/web/web_settings_page_sections.dart	No	Yes	No
Web Settings gateway	lib/web/web_settings_page_gateway.dart	No	Yes	No
Web Settings support	lib/web/web_settings_page_support.dart	No	Yes	No
Account Page	lib/features/account/account_page.dart	Yes	No	Yes
Section Tabs	lib/widgets/section_tabs.dart	Yes	Yes	Yes
Top Bar	lib/widgets/top_bar.dart	Yes	Yes	Yes
Surface Card	lib/widgets/surface_card.dart	Yes	Yes	Yes
Skill Directory Authorization Card	lib/features/settings/skill_directory_authorization_card.dart	Yes	No	Yes
Settings Shell wrapper	lib/widgets/settings_page_shell.dart	Yes	Yes	Yes

已清理 / 已收口的 UI 组件

名称	路径	状态	说明
Web Focus Panel 副本	lib/web/web_focus_panel.dart、lib/web/web_focus_panel_core.dart	已删除	共享版 AssistantFocusPanel 已接管，不再保留 Web 侧重复实现。
Web Focus Panel previews/support	lib/web/web_focus_panel_previews.dart、lib/web/web_focus_panel_support.dart	已删除	已并入共享 Focus Panel 体系，不再保留旧副本。
iOS 兼容壳	lib/features/mobile/ios_mobile_shell.dart	已删除	旧兼容壳只做转发，现已收口为 MobileShell 唯一正式入口。

---

后续候选组件

名称	路径	当前状态	后续条件
旧 Web Assistant 页面分层	lib/web/web_assistant_page_* 中重复的局部壳层	保留中	只有在 Web Assistant 进一步向共享页面收口时才继续删。
旧设置页 Web 分层	lib/web/web_settings_page_* 中重复的局部壳层	保留中	只有在 Web 设置页完全收口到共享 SettingsPage 后才建议删。

---

当前清理状态

第一批：已完成

• Web Focus Panel 共享化已收口到 lib/widgets/assistant_focus_panel*.dart
• Web Assistant 已直接引用共享 Focus Panel 实现，不再保留旧兼容入口

第二批：已完成公共壳层收口

Desktop 与 Web 设置页当前已共用：

• SettingsPageBodyShell
• SettingsGlobalApplyCard
• buildOrderedSettingsSections

剩余差异集中在 controller、gateway 细节和 Web 专属 persistence 逻辑，不属于“已完成共享化的重复实现”。

第三批：本轮完成

• 旧 iOS 移动兼容壳已删除，以 MobileShell 作为唯一正式入口

第四批：持续维护

• 文档和测试应只引用当前仍存在的 UI 文件
• 守护测试应阻止旧兼容壳和旧副本路径回流

---

第二阶段评估：Web 页面分层哪些还值得继续收口

A. web_assistant_page_*

当前文件规模：

• lib/web/web_assistant_page_core.dart：458 行
• lib/web/web_assistant_page_chrome.dart：471 行
• lib/web/web_assistant_page_workspace.dart：685 行
• lib/web/web_assistant_page_helpers.dart：277 行

值得继续收口

1. lib/web/web_assistant_page_workspace.dart

• 这是当前最值得继续拆的文件。
• 同时承载：
  • 会话区主体
  • composer 区
  • session settings sheet
  • empty state
  • message bubble
  • side tab button
• 属于单文件内职责过多，但仍是纯 Web UI 视图层，适合继续按界面职责拆小。

建议下一步拆分：

• web_assistant_page_messages.dart
• web_assistant_page_composer.dart
• web_assistant_page_session_sheet.dart

2. lib/web/web_assistant_page_chrome.dart

• 值得做第二优先级收口。
• 当前同时承载：
  • 顶部 chrome
  • connection chip
  • 左侧任务 pane
  • conversation group 列表
• 这些部分都属于同一页面的 chrome 层，但已经接近“一个文件内多个子域”的边界。

建议下一步拆分：

• 保留 web_assistant_page_chrome.dart 作为组装入口
• 把 task pane / conversation group 提成独立子文件

暂时不建议继续收口

1. lib/web/web_assistant_page_core.dart

• 虽然是状态 owner，但当前职责清晰：
  • controller 绑定
  • attachments
  • prompt submit
  • rename / action dialog
  • artifact pane 宽度与可见性
• 这部分是页面 orchestrator，不适合和 Desktop Assistant 强行合并。

2. lib/web/web_assistant_page_helpers.dart

• 文件规模适中，职责也比较稳定。
• 主要是 UI 原子和小模型定义，目前没有明显继续拆分收益。

结论

• web_assistant_page_* 值得继续收口，但方向应是“Web 页面内部再拆职责”，不是“强行向 Desktop Assistant 页面合并”。

B. web_settings_page_*

当前文件规模：

• lib/web/web_settings_page_core.dart：296 行
• lib/web/web_settings_page_sections.dart：403 行
• lib/web/web_settings_page_gateway.dart：813 行
• lib/web/web_settings_page_support.dart：92 行

值得继续收口

1. lib/web/web_settings_page_gateway.dart

• 这是第二阶段里最值得继续动的文件。
• 已经超过 800 行，而且同时承载：
  • gateway overview
  • direct / local / remote gateway card
  • external ACP provider card
  • top-level apply 行为
  • wizard 逻辑
• 这是典型的“业务闭包过大但仍可按职责拆分”的目标。

建议下一步拆分：

• web_settings_page_gateway_cards.dart
• web_settings_page_gateway_acp.dart
• web_settings_page_gateway_actions.dart

2. lib/web/web_settings_page_sections.dart

• 值得轻量收口，但不是最高优先级。
• 现在已经共享了 shell 层，剩下的是 tab 内容组织和一些 overview 卡片。
• 更适合在 web_settings_page_gateway.dart 拆完后再回头看哪些 section 能继续下沉到共享层。

暂时不建议继续收口

1. lib/web/web_settings_page_core.dart

• 这是 Web settings 的状态 owner。
• 当前规模不大，controller 同步逻辑和页面 frame 都还在合理范围内。
• 不建议为了“看起来统一”而和 Desktop SettingsPage 硬合。

2. lib/web/web_settings_page_support.dart

• 只有少量 support 工具和状态 chip。
• 保持现状即可。

结论

• web_settings_page_* 里真正值得继续收口的是 web_settings_page_gateway.dart。
• WebSettingsPage 不值得直接向 SettingsPage 硬合；更合理的方向是继续抽共享 section/card 结构，而不是统一 controller。

第二阶段建议执行顺序

1. 先拆 lib/web/web_settings_page_gateway.dart
2. 再拆 lib/web/web_assistant_page_workspace.dart
3. 最后评估 lib/web/web_assistant_page_chrome.dart 和 lib/web/web_settings_page_sections.dart

这样收益最高，也最不容易碰到跨平台状态耦合。