xworkmate-app/docs/architecture/public-api/app-orchestration.md

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 可见性