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](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/docs/architecture/account-sync-settings-bridge-state-model.md)

## Bridge-Owned Source Of Truth

```mermaid
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

```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](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-app/docs/architecture/task-dialog-provider-selection-mainline.md)