7573780956
Accuracy fixes: - app-orchestration.md: remove non-existent constructor params - models-and-config.md: remove wrong multiAgent field from SettingsSnapshot - runtime-contracts.md: add missing multiAgent/collaborationMode/routingHint fields Stale multi-agent refs: - unified-routing-architecture.md: agent/multi-agent → agent (含 bridge 转发) - bridge-runtime-routing-map.md: multi-agent tasks → multi-agent forwarding tasks - cross-repo-task-state-workflow.md: remove multi-agent orchestration from mermaid - runtime-contracts.md, feature-surfaces.md: 多 agent → agent Organization: - Move cloud-session-service and stage4-helper to archive/ - Fix 22 xworkmate/ → xworkmate-app/ paths in archive doc - Fix XWorkmate.svc.plus repo name in simple-theme-default.md - Update README.md index and public-api/README.md coverage stats (132/590)
188 lines
6.5 KiB
Markdown
188 lines
6.5 KiB
Markdown
# Feature Surfaces
|
||
|
||
## Purpose
|
||
|
||
本文件只写“关键页面和业务 surface”，不逐条解释视觉组件。页面层的原则是：
|
||
|
||
- `WorkspaceDestination` 是一级入口真源
|
||
- `WorkspacePageSpec` 是 destination 到页面实现的唯一映射
|
||
- 页面公开 API 只关注 controller 注入、detail 打开和业务入口参数
|
||
|
||
## `WorkspaceDestination`
|
||
|
||
- Source: `lib/models/app_models.dart`
|
||
- Type: `enum`
|
||
- Responsibility:
|
||
当前顶层 surface 只有 `assistant` 与 `settings`。
|
||
|
||
### Returns
|
||
|
||
| Getter | Returns | Meaning |
|
||
| --- | --- | --- |
|
||
| `label` | `String` | 本地化标签 |
|
||
| `icon` | `IconData` | 导航图标 |
|
||
| `description` | `String` | 页面职责描述 |
|
||
| `fromJsonValue` | `WorkspaceDestination?` | 从持久化值恢复枚举 |
|
||
|
||
## `AssistantFocusEntry`
|
||
|
||
- Source: `lib/models/app_models.dart`
|
||
- Type: `enum`
|
||
- Responsibility:
|
||
表示 Assistant 内可 pin 的 focus 入口，目前是 `settings / language / theme`。
|
||
|
||
### Returns
|
||
|
||
| Getter / API | Returns | Meaning |
|
||
| --- | --- | --- |
|
||
| `label` / `icon` / `description` | view metadata | focus 展示元数据 |
|
||
| `destination` | `WorkspaceDestination?` | 是否映射到真实 workspace 页面 |
|
||
| `opensSettingsPage` | `bool` | 是否最终进入 settings |
|
||
| `fromDestination` | `AssistantFocusEntry` | 从 destination 反解 focus entry |
|
||
|
||
## `SettingsNavigationContext`
|
||
|
||
- Source: `lib/models/app_models.dart`
|
||
- Type: `class`
|
||
- Responsibility:
|
||
承担“从哪里进入 settings/detail”的 breadcrumb 和上下文信息。
|
||
|
||
### Constructor Parameters
|
||
|
||
| Param | Type | Required | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `rootLabel` | `String` | Yes | 顶层来源标签 |
|
||
| `destination` | `WorkspaceDestination` | Yes | 来源 destination |
|
||
| `sectionLabel` | `String?` | No | 中间 section 标签 |
|
||
| `settingsTab` | `SettingsTab?` | No | 目标 tab |
|
||
| `gatewayProfileIndex` | `int?` | No | 目标 gateway profile |
|
||
| `prefersGatewaySetupCode` | `bool?` | No | 是否优先 setup-code 流程 |
|
||
|
||
## `WorkspacePageSurface`
|
||
|
||
- Source: `lib/app/workspace_page_registry.dart`
|
||
- Type: `enum`
|
||
- Responsibility:
|
||
区分 page builder 的 `desktop` 与 `mobile` surface。
|
||
|
||
## `WorkspacePageSpec`
|
||
|
||
- Source: `lib/app/workspace_page_registry.dart`
|
||
- Type: `class`
|
||
- Responsibility:
|
||
把一个 destination 的桌面与移动 builder 绑定在一起。
|
||
|
||
### Constructor Parameters
|
||
|
||
| Param | Type | Required | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `destination` | `WorkspaceDestination` | Yes | 页面目标 |
|
||
| `desktopBuilder` | `WorkspacePageBuilder` | Yes | 桌面 builder |
|
||
| `mobileBuilder` | `WorkspacePageBuilder` | Yes | 移动 builder |
|
||
|
||
## `buildWorkspacePage`
|
||
|
||
- Source: `lib/app/workspace_page_registry.dart`
|
||
- Type: `top-level function`
|
||
- Responsibility:
|
||
根据 destination 与 surface 实际实例化 `AssistantPage` / `SettingsPage`。
|
||
|
||
### Parameters and Returns
|
||
|
||
| Parameters | Returns | Meaning |
|
||
| --- | --- | --- |
|
||
| `destination`, `controller`, `onOpenDetail`, `surface` | `Widget` | 根据 `WorkspacePageSpec` 路由到具体页面 |
|
||
|
||
## `AssistantPage`
|
||
|
||
- Source: `lib/features/assistant/assistant_page_main.dart`
|
||
- Type: `class`
|
||
- Responsibility:
|
||
承担桌面主工作台、timeline、composer、task rail、artifact pane、focus panel，以及所有 assistant 发起动作的 UI 主入口。
|
||
|
||
### Constructor Parameters
|
||
|
||
| Param | Type | Required | Default | Meaning |
|
||
| --- | --- | --- | --- | --- |
|
||
| `controller` | `AppController` | Yes | none | 统一业务控制器 |
|
||
| `onOpenDetail` | `ValueChanged<DetailPanelData>` | Yes | none | 打开 detail panel 的回调 |
|
||
| `navigationPanelBuilder` | `Widget Function(double contentWidth)?` | No | `null` | 定制导航区 |
|
||
| `showStandaloneTaskRail` | `bool` | No | `true` | 是否显示独立 task rail |
|
||
| `unifiedPaneStartsCollapsed` | `bool` | No | `false` | 初始化时 unified pane 是否折叠 |
|
||
| `clipboardImageReader` | `AssistantClipboardImageReader?` | No | `null` | 自定义剪贴板图像读取器 |
|
||
|
||
### Returns
|
||
|
||
| API | Returns | Meaning |
|
||
| --- | --- | --- |
|
||
| `AssistantPage(...)` | `AssistantPage` | assistant 顶层页面 |
|
||
|
||
### Main Call Chain
|
||
|
||
- `AppShell` / `WorkspacePageSpec` -> `AssistantPage`
|
||
- 页面内部通过 `AppControllerDesktopWorkspaceExecution`、`AppControllerDesktopThreadSessions` 发起执行、切换 provider、加载 artifact、agent 协作
|
||
|
||
### Notes
|
||
|
||
- 这里是关键页面，但其大量内部组件和 internal 状态机不作为本次文档展开对象
|
||
|
||
## `SettingsPage`
|
||
|
||
- Source: `lib/features/settings/settings_page_core.dart`
|
||
- Type: `class`
|
||
- Responsibility:
|
||
承担 gateway、account、about 等配置型入口，并在保存后尝试刷新 bridge capabilities。
|
||
|
||
### Constructor Parameters
|
||
|
||
| Param | Type | Required | Default | Meaning |
|
||
| --- | --- | --- | --- | --- |
|
||
| `controller` | `AppController` | Yes | none | 应用控制器 |
|
||
| `initialTab` | `SettingsTab` | No | `SettingsTab.gateway` | 初始 tab |
|
||
| `initialDetail` | `SettingsDetailPage?` | No | `null` | 初始 detail |
|
||
| `navigationContext` | `SettingsNavigationContext?` | No | `null` | 导航上下文 |
|
||
|
||
### Main Call Chain
|
||
|
||
- `AppControllerDesktopNavigation.openSettings` -> `SettingsPage`
|
||
- `SettingsPage` -> `SettingsController.saveSnapshot/loginAccount/syncAccountSettings/verifyAccountMfa`
|
||
- 保存后最佳努力刷新 `refreshSingleAgentCapabilitiesInternal` 和 `refreshAcpCapabilitiesInternal`
|
||
|
||
## `MobileShell`
|
||
|
||
- Source: `lib/features/mobile/mobile_shell_core.dart`
|
||
- Type: `class`
|
||
- Responsibility:
|
||
移动端的统一入口壳层，只负责 assistant/settings tab 切换与移动端页面容器。
|
||
|
||
### Constructor Parameters
|
||
|
||
| Param | Type | Required | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `controller` | `AppController` | Yes | 全局控制器 |
|
||
|
||
### Key Internal Business Entrypoints
|
||
|
||
| Method | Parameters | Returns | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `selectTabInternal` | `MobileShellTab tab` | `void` | 在 assistant/settings 之间切换 |
|
||
| `buildCurrentPageInternal` | none | `Widget` | 构建当前移动端 page |
|
||
| `showPairingGuidePageFlowInternal` | none | `Future<void>` | 打开 pairing guide 页面 |
|
||
|
||
### Notes
|
||
|
||
- `mobile_shell_strip.dart`、`mobile_shell_nav.dart`、`mobile_shell_sheet.dart` 等 leaf 组件不逐条展开
|
||
|
||
## `AppShell`
|
||
|
||
- Source: `lib/app/app_shell_desktop.dart`
|
||
- Type: `class`
|
||
- Responsibility:
|
||
是 desktop/mobile surface 的统一宿主；在宽度不足时自动切到 `MobileShell`，在桌面场景下渲染 sidebar、detail 与 workspace 页面。
|
||
|
||
### Parameters and Returns
|
||
|
||
| Parameters | Returns | Meaning |
|
||
| --- | --- | --- |
|
||
| `controller: AppController` | `AppShell` | 顶层应用壳层 |
|