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)
257 lines
13 KiB
Markdown
257 lines
13 KiB
Markdown
# App Orchestration
|
||
|
||
## Module Purpose
|
||
|
||
`lib/app` 负责把 `feature_flags -> shell/registry -> AppController -> runtime/controller` 这条主链收口到统一桌面/移动编排层。这里的公开接口重点不在“UI 细节”，而在：
|
||
|
||
- 顶层状态与依赖装配
|
||
- 页面 destination 与 registry
|
||
- 设置、线程、provider、执行目标的落盘与切换
|
||
- 运行时能力刷新与线程上下文重算
|
||
|
||
## Key Files
|
||
|
||
| File | Role |
|
||
| --- | --- |
|
||
| `lib/app/app_controller_desktop_core.dart` | `AppController` 主对象、依赖装配与状态总线 |
|
||
| `lib/app/app_controller_desktop_navigation.dart` | 页面切换、settings/detail 导航、语言/主题切换 |
|
||
| `lib/app/app_controller_desktop_settings.dart` | settings draft、保存、落盘与本地状态清理 |
|
||
| `lib/app/app_controller_desktop_settings_runtime.dart` | settings 与 runtime 之间的副作用桥接 |
|
||
| `lib/app/app_controller_desktop_thread_sessions.dart` | 会话/线程、artifact、agent 协作入口 |
|
||
| `lib/app/app_controller_desktop_workspace_execution.dart` | 执行目标、provider、thread context 主链 |
|
||
| `lib/app/app_controller_desktop_runtime_coordination_impl.dart` | runtime 能力刷新与任务重算函数 |
|
||
| `lib/app/workspace_page_registry.dart` | destination 到 page builder 的唯一映射 |
|
||
| `lib/app/app_shell_desktop.dart` | 桌面/移动入口壳层 |
|
||
|
||
## `AppController`
|
||
|
||
- Source: `lib/app/app_controller_desktop_core.dart`
|
||
- Type: `class`
|
||
- Responsibility:
|
||
统一装配 `SecureConfigStore`、`RuntimeCoordinator`、`GatewayRuntime`、`CodexRuntime`、`SettingsController`、各类 gateway controller、task thread 状态、UI feature manifest。
|
||
|
||
### Constructor Parameters
|
||
|
||
| Param | Type | Required | Default | Meaning |
|
||
| --- | --- | --- | --- | --- |
|
||
| `store` | `SecureConfigStore?` | No | `SecureConfigStore()` | 设置与 secret 持久化入口 |
|
||
| `runtimeCoordinator` | `RuntimeCoordinator?` | No | 内建 coordinator | 收口 gateway/codex/config bridge |
|
||
| `desktopPlatformService` | `DesktopPlatformService?` | No | `createDesktopPlatformService()` | 平台 VPN/集成能力桥 |
|
||
| `uiFeatureManifest` | `UiFeatureManifest?` | No | repo manifest | 顶层 surface 能力声明源 |
|
||
| `initialBridgeProviderCatalog` | `List<SingleAgentProvider>?` | No | empty | 初始单 agent provider catalog |
|
||
| `initialGatewayProviderCatalog` | `List<SingleAgentProvider>?` | No | empty | 初始 gateway provider catalog |
|
||
| `initialAvailableExecutionTargets` | `List<AssistantExecutionTarget>?` | No | empty | 初始可见执行目标 |
|
||
| `accountClientFactory` | `AccountRuntimeClient Function(String)?` | No | default impl | account runtime client 构造 |
|
||
| `environmentOverride` | `Map<String, String>?` | No | `null` | 测试/运行时环境覆盖 |
|
||
| `goTaskServiceClient` | `GoTaskServiceClient?` | No | `DesktopGoTaskService` | 外部 ACP / gateway 任务入口 |
|
||
|
||
### Returns
|
||
|
||
| Constructor / API | Returns | Meaning |
|
||
| --- | --- | --- |
|
||
| `AppController(...)` | `AppController` | 初始化后的应用总控制器 |
|
||
|
||
### Main Call Chain
|
||
|
||
- `XWorkmateApp` / `AppShell` 持有 `AppController`
|
||
- `AppController` 组合 `SettingsController`、`GatewayRuntime`、`GatewaySessionsController`、`GatewayChatController`
|
||
- `AssistantPage` / `SettingsPage` 所有关键操作最终都回到 `AppController` 扩展层
|
||
|
||
### Side Effects
|
||
|
||
- 初始化 runtime、settings、account client、desktop service
|
||
- 维护 task thread、assistant session、本地 UI 状态
|
||
- 向 `GatewayAcpClient` 与 `GoTaskServiceClient` 注入 endpoint / auth 解析
|
||
|
||
### Notes
|
||
|
||
- 这里是 app 侧“唯一大脑”，但业务拆分主要通过 extension 文件完成
|
||
- 当前仓库已经收敛到 `assistant + settings`，不再承载旧模块壳
|
||
|
||
## `AppControllerDesktopNavigation`
|
||
|
||
- Source: `lib/app/app_controller_desktop_navigation.dart`
|
||
- Type: `extension`
|
||
- Responsibility:
|
||
提供 destination 切换、settings/detail 打开关闭、sidebar 状态、语言与主题切换入口。
|
||
|
||
### Key Methods
|
||
|
||
| Method | Parameters | Returns | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `navigateTo` | `WorkspaceDestination destination` | `void` | 切到顶层页面 |
|
||
| `openSettings` | `{SettingsTab? tab, SettingsDetailPage? detail, SettingsNavigationContext? navigationContext}` | `void` | 打开 settings 并可直达 detail |
|
||
| `setSettingsTab` | `SettingsTab tab, {bool clearDetail=true}` | `void` | 切换 settings tab |
|
||
| `toggleAppLanguage` | none | `Future<void>` | 中英切换 |
|
||
| `setAppLanguage` | `AppLanguage language` | `Future<void>` | 显式保存语言 |
|
||
| `setThemeMode` | `ThemeMode mode` | `void` | 切换主题模式 |
|
||
|
||
### Main Call Chain
|
||
|
||
- `Sidebar` / `MobileShell` / focus panel -> navigation extension
|
||
- navigation extension -> `destinationInternal`, `settingsTabInternal`, `settingsDetailInternal`
|
||
- 状态更新后由 `AppShell` 与 `WorkspacePageSpec` 驱动实际页面构建
|
||
|
||
## `AppControllerDesktopSettings`
|
||
|
||
- Source: `lib/app/app_controller_desktop_settings.dart`
|
||
- Type: `extension`
|
||
- Responsibility:
|
||
管理 settings draft、立即保存、apply、workspace path 更新，以及 assistant 本地状态清理。
|
||
|
||
### Key Methods
|
||
|
||
| Method | Parameters | Returns | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `saveSettingsDraft` | `SettingsSnapshot snapshot` | `Future<void>` | 更新草稿但不立即全局 apply |
|
||
| `persistSettingsDraft` | none | `Future<void>` | 把 draft 落到持久层 |
|
||
| `applySettingsDraft` | none | `Future<void>` | 将 draft 视为当前设置并触发副作用 |
|
||
| `saveSettings` | `SettingsSnapshot snapshot, {bool refreshAfterSave=true}` | `Future<void>` | 直接保存并按需刷新 |
|
||
| `saveWorkspacePath` | `String value` | `Future<void>` | 写工作区根路径 |
|
||
| `clearAssistantLocalState` | none | `Future<void>` | 清理本地 assistant/thread 相关状态 |
|
||
|
||
### Side Effects
|
||
|
||
- 写 `SecureConfigStore`
|
||
- 触发 runtime / gateway / provider catalog / thread persistence 的后续副作用
|
||
- 管理 token/password 等 secret draft
|
||
|
||
## `AppControllerDesktopSettingsRuntime`
|
||
|
||
- Source: `lib/app/app_controller_desktop_settings_runtime.dart`
|
||
- Type: `extension`
|
||
- Responsibility:
|
||
把 settings 保存与 desktop/runtime 副作用连起来，包括 gateway catalog、VPN mode、授权目录、connection test。
|
||
|
||
### Key Methods
|
||
|
||
| Method | Parameters | Returns | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `updateAiGatewaySelection` | `List<String> selectedModels` | `Future<void>` | 归一化 AI gateway 选中模型并同步默认模型 |
|
||
| `syncAiGatewayCatalog` | `AiGatewayProfile profile, {String apiKeyOverride=''}` | `Future<AiGatewayProfile>` | 通过 settings controller 拉 catalog，回写 models controller |
|
||
| `refreshDesktopIntegration` | none | `Future<void>` | 刷新 desktop platform 状态 |
|
||
| `saveLinuxDesktopConfig` | `LinuxDesktopConfig config` | `Future<void>` | 保存 Linux tunnel/proxy 偏好 |
|
||
| `setDesktopVpnMode` | `VpnMode mode` | `Future<void>` | 持久化并切换 tunnel/proxy mode |
|
||
| `connectDesktopTunnel` | none | `Future<void>` | 发起 tunnel 连接 |
|
||
| `disconnectDesktopTunnel` | none | `Future<void>` | 断开 tunnel |
|
||
| `authorizeSkillDirectory` | `{String suggestedPath=''}` | `Future<AuthorizedSkillDirectory?>` | 授权单个 skill 目录 |
|
||
| `authorizeSkillDirectories` | `{List<String> suggestedPaths=const []}` | `Future<List<AuthorizedSkillDirectory>>` | 批量授权目录 |
|
||
| `testOllamaConnectionDraft` | `{required bool cloud, required SettingsSnapshot snapshot, String apiKeyOverride=''}` | `Future<String>` | 使用草稿参数测试连接 |
|
||
|
||
### Main Call Chain
|
||
|
||
- `SettingsPage` / quick actions -> settings runtime extension
|
||
- extension -> `SettingsController` / `DesktopPlatformService` / `SkillDirectoryAccessService`
|
||
- 成功后回写 `SettingsSnapshot`、`ModelsController`、task recompute
|
||
|
||
## `AppControllerDesktopThreadSessions`
|
||
|
||
- Source: `lib/app/app_controller_desktop_thread_sessions.dart`
|
||
- Type: `extension`
|
||
- Responsibility:
|
||
承担 thread/session 级能力：artifact 读取、多 agent 协作启动、mount 刷新、online workspace 打开。
|
||
|
||
### Key Methods
|
||
|
||
| Method | Parameters | Returns | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `loadAssistantArtifactSnapshot` | `{String? sessionKey}` | `Future<AssistantArtifactSnapshot>` | 加载某会话 artifact 清单快照 |
|
||
| `loadAssistantArtifactPreview` | `AssistantArtifactEntry artifact, {String? sessionKey}` | `Future<AssistantArtifactPreview>` | 读取 artifact 预览内容 |
|
||
| `openOnlineWorkspace` | none | `Future<void>` | 打开在线工作区入口 |
|
||
|
||
## `AppControllerDesktopWorkspaceExecution`
|
||
|
||
- Source: `lib/app/app_controller_desktop_workspace_execution.dart`
|
||
- Type: `extension`
|
||
- Responsibility:
|
||
承担 assistant thread 的执行目标、provider、模型、权限、thread context、技能选择、任务归档主链。
|
||
|
||
### Key Methods
|
||
|
||
| Method | Parameters | Returns | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `setAssistantExecutionTarget` | `AssistantExecutionTarget target` | `Future<void>` | 切换当前 thread 的执行目标 |
|
||
| `setAssistantProvider` | `SingleAgentProvider provider` | `Future<void>` | 设置当前 thread 的 provider |
|
||
| `setAssistantMessageViewMode` | `AssistantMessageViewMode mode` | `Future<void>` | 切换 raw/rendered 视图 |
|
||
| `setAssistantPermissionLevel` | `AssistantPermissionLevel level` | `Future<void>` | 更新 assistant 权限档位 |
|
||
| `applyAssistantExecutionTargetInternal` | named args | `Future<void>` | 执行目标切换后的 thread/persistence 主逻辑 |
|
||
| `selectDefaultModel` | `String modelId` | `Future<void>` | 更新 settings 默认模型 |
|
||
| `selectAssistantModelForSession` | named args | `Future<void>` | 按 session 绑定模型 |
|
||
| `initializeAssistantThreadContext` | named args | `void` | 创建 thread 上下文骨架 |
|
||
| `toggleAssistantSkillForSession` | named args | `Future<void>` | 切换 thread 绑定技能 |
|
||
| `saveAssistantTaskArchived` | named args | `Future<void>` | 标记任务归档状态 |
|
||
|
||
### Main Call Chain
|
||
|
||
- `AssistantPage` composer / task dialog -> execution extension
|
||
- extension -> `ensureDesktopTaskThreadBindingInternal` / `upsertTaskThreadInternal`
|
||
- 最终通过 `GoTaskServiceClient`、`GatewayAcpClient`、gateway runtime 进入 bridge
|
||
|
||
## Runtime Coordination Helpers
|
||
|
||
- Source: `lib/app/app_controller_desktop_runtime_coordination_impl.dart`
|
||
- Type: `top-level functions`
|
||
- Responsibility:
|
||
这些函数不是页面入口，但它们决定了 app 如何刷新 bridge 能力和重算任务视图。
|
||
|
||
### Key Functions
|
||
|
||
| Function | Parameters | Returns | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `refreshAcpCapabilitiesRuntimeInternal` | `AppController controller, {bool forceRefresh=false, bool persistMountTargets=false}` | `Future<void>` | 刷新 ACP capability snapshot |
|
||
| `refreshSingleAgentCapabilitiesRuntimeInternal` | `AppController controller, {bool forceRefresh=false}` | `Future<void>` | 刷新单 agent/provider catalog |
|
||
| `assistantWorkingDirectoryForSessionRuntimeInternal` | `AppController controller, String sessionKey` | `String?` | 求 session 工作目录 |
|
||
| `resolveLocalAssistantWorkingDirectoryForSessionRuntimeInternal` | `AppController controller, String sessionKey, {bool requireLocalExistence=true}` | `String?` | 返回本地且可用的工作目录 |
|
||
| `recomputeTasksRuntimeInternal` | `AppController controller` | `void` | 基于当前 session/thread/runtime 状态重建 task 列表 |
|
||
|
||
## `WorkspacePageSpec` and `buildWorkspacePage`
|
||
|
||
- Source: `lib/app/workspace_page_registry.dart`
|
||
- Type: `class` + `top-level function`
|
||
- Responsibility:
|
||
这是 app 顶层 destination 到页面实现的唯一映射表。
|
||
|
||
### `WorkspacePageSpec` Parameters
|
||
|
||
| Param | Type | Required | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `destination` | `WorkspaceDestination` | Yes | page 所属目标 |
|
||
| `desktopBuilder` | `WorkspacePageBuilder` | Yes | 桌面构建器 |
|
||
| `mobileBuilder` | `WorkspacePageBuilder` | Yes | 移动端构建器 |
|
||
|
||
### `buildWorkspacePage`
|
||
|
||
| Parameters | Returns | Meaning |
|
||
| --- | --- | --- |
|
||
| `destination`, `controller`, `onOpenDetail`, `surface` | `Widget` | 根据 surface 选择 desktop/mobile page builder |
|
||
|
||
### Call Chain
|
||
|
||
- `AppShell` / `MobileShell` -> `buildWorkspacePage`
|
||
- `buildWorkspacePage` -> `AssistantPage` or `SettingsPage`
|
||
|
||
## `AppShell`
|
||
|
||
- Source: `lib/app/app_shell_desktop.dart`
|
||
- Type: `class`
|
||
- Responsibility:
|
||
统一承载 desktop/mobile 分支、sidebar、detail drawer、destination rendering 和移动端 fallback 到 `MobileShell` 的切换。
|
||
|
||
### Constructor Parameters
|
||
|
||
| Param | Type | Required | Meaning |
|
||
| --- | --- | --- | --- |
|
||
| `controller` | `AppController` | Yes | 应用总控制器 |
|
||
|
||
### Returns
|
||
|
||
| API | Returns | Meaning |
|
||
| --- | --- | --- |
|
||
| `AppShell(...)` | `AppShell` | 顶层壳组件 |
|
||
|
||
### Main Call Chain
|
||
|
||
- `XWorkmateApp` -> `AppShell`
|
||
- `AppShell` -> `buildWorkspacePage` / `MobileShell`
|
||
- `AppShell` 同时消费 `SidebarTaskItem`、detail sheet、feature manifest 和 execution target 可见性
|