xworkmate-app/docs/architecture/settings-integration-configuration-model.md

Settings Integration Configuration Model

Last Updated: 2026-04-19

本文件记录当前 Settings -> Integrations 在主链中的职责边界，以及 acpBridgeServerModeConfig 在 settings surface 中的配置仲裁规则。

Current Rule

• Settings 只管理 Bridge 连接参数、account sync 元数据和本地编辑态
• AcpBridgeServerModeConfig.effective 只用于 settings surface 的连接与展示语义
• selfHosted 优先级高于 cloudSynced
• cloudSynced 只在 manual Bridge 未配置时作为 settings metadata 回退来源
• app 不从本地 endpoint preset、旧 module 配置、历史 fallback 恢复 provider catalog
• xworkmate-bridge 仍然是 provider catalog、gateway capability、routing resolve 的唯一真源
• BRIDGE_SERVER_URL 只属于 AccountSyncState 元数据，不参与 assistant runtime endpoint 选择
• BRIDGE_AUTH_TOKEN 只进入 secure storage / managed secret

Canonical State Model

For the detailed state diagram and ownership rules, see:

• Account Sync, Settings, and Bridge State Model

Bridge-Owned Source Of Truth

flowchart TD
  subgraph SETTINGS["Settings surface"]
    A["SettingsPage / SettingsAccountPanel"]
    B["bridge connection params<br/>account sync metadata<br/>secure refs"]
    A --> B
  end

  subgraph BRIDGE["Bridge contract"]
    C["acp.capabilities"]
    D["xworkmate.routing.resolve"]
    E["xworkmate.gateway.*"]
    B --> C
  end

  subgraph APPSTATE["App-side derived state"]
    F["capability refresh hydration"]
    G["bridgeAgentProviderCatalogInternal<br/>bridgeGatewayProviderCatalogInternal<br/>bridgeAvailableExecutionTargetsInternal"]
    H["GatewayAcpCapabilities"]
    I["gateway capability -> mount target merge"]
    J["ManagedMountTargetState"]
    C --> F --> G
    C --> H --> I --> J
  end

  subgraph UI["Visible affordances"]
    M["agent / gateway target switch"]
    N["task dialog provider menu"]
    O["settings gateway connection affordances"]
    G --> M
    G --> N
    J --> O
  end

  subgraph EXEC["Execution"]
    P["providerCatalogForExecutionTarget()"]
    Q["resolveProviderForExecutionTarget()"]
    R["setAssistantProvider()"]
    S["assistantProviderForSession()"]
    T["GoTaskService.executeTask(...)"]
    U["resolved provider / unavailable UX"]
    N --> P --> Q --> R --> S --> T
    T --> D --> U
    O --> E
  end

What Settings Owns

• bridge host / transport / auth input
• account-linked bridge configuration metadata
• acpBridgeServerModeConfig.cloudSynced
• acpBridgeServerModeConfig.selfHosted
• acpBridgeServerModeConfig.effective
• secure secret references
• gateway connection test / connect / disconnect affordance

What Settings Does Not Own

• 独立 provider catalog
• 独立 module matrix
• app-side gateway preset backfill
• 旧 ai_gateway / secrets / account 页面壳

Notes

• AcpBridgeServerModeConfig 的实际仲裁顺序是 selfHosted -> cloudSynced -> default
• selfHosted.isConfigured == true 时，effective.source == 'bridge'
• selfHosted 未配置且 accountSyncState 提供了可用云端桥接信息时，effective.source == 'cloud'
• 两者都不可用时，effective.source == 'default'
• 当前任务对话框 provider 选择主链固定为 providerCatalogForExecutionTarget() -> resolveProviderForExecutionTarget() -> setAssistantProvider()
• agent catalog 只对应 bridge 广告的 ACP server bridges
• gateway catalog 只对应 bridge 返回的 gateway provider 列表；当前为 openclaw，未来可扩展 hermes 等项
• provider picker 的真源只来自 bridge 返回的 target-scoped catalog；不会因为线程里保存过 providerId 就被 app 反向重建
• gateway runtime 可见性来自 bridge capability snapshot 与 xworkmate.gateway.* 返回，不来自旧设置页枚举
• bridge 若返回额外 capability flag，这些 flag 只属于合同元数据，不会自动生成新的 settings tab 或 module page
• bridge 若未返回 catalog，provider 菜单为空或禁用；app 不伪造 codex / opencode / gemini / openclaw
• production provider / gateway 选择继续由 bridge 拥有，app 只保留消费与展示

Effective Config Mermaid

stateDiagram-v2
    [*] --> EvaluateEffective

    EvaluateEffective --> BridgeEffective: selfHosted.isConfigured == true
    EvaluateEffective --> CloudEffective: selfHosted 未配置 且 cloudSynced 可用
    EvaluateEffective --> DefaultEffective: 两者都不可用

    BridgeEffective --> CloudEffective: 关闭 manual Bridge
    CloudEffective --> BridgeEffective: manual Bridge 配置生效
    CloudEffective --> DefaultEffective: cloud sync 失效
    DefaultEffective --> CloudEffective: cloud sync 恢复

    note right of BridgeEffective
        source = bridge metadata
        used by settings only
    end note

    note right of CloudEffective
        source = cloud metadata
        used by settings only
    end note

    note right of DefaultEffective
        source = managed bridge origin
        assistant runtime fixed to kManagedBridgeServerUrl
    end note

See Also

• Task Dialog Provider Selection Mainline