ai-workspace-lab/xworkmate-app

Fork 0

Haitao Pan 677c1ca747 docs: consolidate planning docs under plans

2026-03-30 15:56:47 +08:00

3.9 KiB

Raw Permalink Blame History

02. Layout、模块分层与状态边界

1. 组件层级原则

为保证长期维护，建议严格区分三层：

Layout 层：只负责结构和容器
Module 层：负责一个业务单元的交互和状态协调
Component 层：负责纯展示或轻交互

页面只做组装，不应堆积大量业务逻辑。

2. Layout 层

Layout 层应只负责工作区结构，不直接依赖具体业务域。

建议的壳层对象包括：

WorkspaceShell
PrimaryRail
SecondaryPane
ContentViewport
TopChromeBar
BottomDock
SplitPaneLayout
SheetHost

这些对象负责：

左右分栏
顶部导航与 breadcrumb 承载
底部 composer 区承载
面板折叠与尺寸分配
Web 响应式适配

3. Module 层

Module 是长期维护的关键层，承接复合业务交互。

A. Assistant 模块

ThreadListModule
ThreadGroupsModule
SessionHeaderModule
ConversationModule
RenderModeModule
ConnectionStatusModule
ComposerModule
SessionSettingsSheetModule

B. Focus / Favorites 模块

FocusEntriesModule
FocusSummaryCardModule
FavoriteEntryManagerModule

C. Settings 模块

SettingsTopBarModule
SettingsSubmissionBarModule
SettingsTabsModule
GatewayProfilesModule
LlmEndpointsModule
ExternalAcpModule
AppearanceSettingsModule
DiagnosticsModule

D. Resource 模块

TasksRegistryModule
SkillsRegistryModule
NodesRegistryModule
SecretsRegistryModule
LlmApiRegistryModule

一个 module 应该负责“完整业务语义”，而不是只拼几个 UI 组件。

4. Component 层

Component 层应尽可能保持纯展示和可复用。

建议沉淀为通用组件的对象包括：

SurfaceCard
SectionTabs
SearchField
StatusChip
ConnectionBadge
ActionChip
EmptyState
ErrorBanner
ToolbarButton
DropdownField
ToggleField
SummaryStatChip
BottomSheetPanel
ResizeHandle

这些组件不应知道线程、设置页、技能列表等具体业务语义。

5. 状态边界

虽然这里主要区分“全局状态”和“局部状态”，但在 Flutter Web 中还应单独重视路由状态。

A. 全局状态

以下状态建议由 app-level controller / store 持有：

当前 workspace / 用户上下文
当前主题、语言
feature flags
全局导航结构
Focus / Favorites 入口列表
资源目录数据（任务、技能、节点、密钥、LLM API）
Gateway profile 列表
provider / model catalog
线程索引数据
全局通知 / 错误中心

B. 路由状态

以下状态更适合映射到 URL / 路由层：

当前页面
当前线程 id
当前 Settings tab
当前 Integrations sub-tab
当前详情对象 id
左侧 pane 当前模式
可分享的搜索条件

这些状态如果仅放在内存里，会削弱 Flutter Web 的刷新恢复能力和链接可分享能力。

C. 局部状态

以下状态建议严格留在模块或组件内部：

side pane 折叠/展开
split pane 临时尺寸
bottom sheet 是否打开
dropdown 是否展开
输入框内容
当前附件选择结果
卡片折叠状态
某个按钮 loading
某个 form 的未提交草稿
hover / pressed / focused 视觉状态
局部滚动位置

6. 一条可执行的状态规则

建议全团队统一以下判断标准：

会影响多个页面或多个模块的，进入全局状态
需要刷新恢复或支持深链的，进入路由状态
只影响单个模块交互的，保持局部状态

7. 必须统一复用的状态机

长期维护时，最容易失控的不是 UI 样式，而是行为流。

建议优先统一以下状态机：

Test / Save / Apply
Connect / Connected / Error / Retry
Thread Send / Streaming / Cancel / Complete
Load / Empty / Error / Refresh
Select / Attach / Remove / Oversize
Collapse / Expand / Pin / Unpin

这些状态机一旦被各页面各写一套，后续 Assistant、Settings、Focus、资源域的交互会快速分叉。

3.9 KiB Raw Permalink Blame History Unescape Escape