# Models And Config

## Purpose

这一层覆盖“状态结构”和“配置 contract”，重点在：

- 什么对象被持久化
- 什么对象描述当前连接/执行/provider/catalog
- 哪些 helper 会影响默认值、归一化和展示语义

## `SettingsSnapshot`

- Source: `lib/runtime/runtime_models_settings_snapshot.dart`
- Type: `class`
- Responsibility:
  是当前 app settings 的唯一主快照对象，也是 settings 持久化与恢复的核心 contract。

### Constructor Parameters

| Param Group | Meaning |
| --- | --- |
| app/UI fields | `appLanguage`、`appActive`、`launchAtLogin`、`showDockIcon` |
| workspace/runtime fields | `workspacePath`、`remoteProjectRoot`、`cliPath`、`codeAgentRuntimeMode` |
| execution/provider fields | `defaultModel`、`defaultProvider`、`assistantExecutionTarget`、`assistantPermissionLevel` |
| connection fields | `gatewayProfiles`、`webSessionPersistence` |
| integration fields | `ollamaLocal`、`ollamaCloud`、`vault`、`aiGateway` |
| skill/permission fields | `authorizedSkillDirectories` |
| account fields | `accountBaseUrl`、`accountUsername`、`accountWorkspace`、`accountWorkspaceFollowed` |
| desktop/server fields | `acpBridgeServerModeConfig`、`linuxDesktop` |

### Key Returns

| API | Returns | Meaning |
| --- | --- | --- |
| `SettingsSnapshot.defaults()` | `SettingsSnapshot` | 当前 schema 的默认配置 |
| `copyWith(...)` | `SettingsSnapshot` | 产生归一化后的新快照 |
| `toJson()` | `Map<String, dynamic>` | 序列化 |
| `fromJson(Map<String, dynamic>)` | `SettingsSnapshot` | 反序列化并校验 schema |

### Notes

- `schemaVersion` 当前固定为 `2`
- 这里是 settings 持久化 contract，不应该承载临时 UI-only 状态

## `GatewayConnectionProfile`

- Source: `lib/runtime/runtime_models_configs.dart`
- Type: `class`
- Responsibility:
  描述单个 gateway 连接槽位，支持 setup code 与手工 host/port/tls 两种配置形态。

### Constructor Parameters

| Param | Type | Required | Meaning |
| --- | --- | --- | --- |
| `mode` | `RuntimeConnectionMode` | Yes | unconfigured / remote |
| `useSetupCode` | `bool` | Yes | 是否使用 setup code |
| `setupCode` | `String` | Yes | setup code 内容 |
| `host` | `String` | Yes | 远端 host |
| `port` | `int` | Yes | 端口 |
| `tls` | `bool` | Yes | 是否 TLS |
| `tokenRef` | `String` | Yes | token secret ref |
| `passwordRef` | `String` | Yes | password secret ref |
| `selectedAgentId` | `String` | Yes | 当前 profile 默认 agent |

### Key Returns

| API | Returns | Meaning |
| --- | --- | --- |
| `defaults()` / `defaultsGateway()` | `GatewayConnectionProfile` | 默认 gateway profile |
| `emptySlot({required int index})` | `GatewayConnectionProfile` | 非主 profile 的空槽位 |
| `copyWith(...)` | `GatewayConnectionProfile` | 自动做 endpoint 归一化 |
| `toJson()` / `fromJson(...)` | contract mapping | 序列化/恢复 |

## `normalizeGatewayProfiles`

- Source: `lib/runtime/runtime_models_configs.dart`
- Type: `top-level function`
- Responsibility:
  对 gateway profile 列表做长度补齐、主槽位 remote 判定、loopback 剔除、token/password ref 修补。

### Parameters and Returns

| Parameters | Returns | Meaning |
| --- | --- | --- |
| `{Iterable<GatewayConnectionProfile>? profiles}` | `List<GatewayConnectionProfile>` | 固定长度、可持久化的 profile 列表 |

## `RuntimeConnectionMode` / `RuntimeConnectionStatus`

- Source: `lib/runtime/runtime_models_connection.dart`
- Type: `enum`
- Responsibility:
  区分“配置形态”和“实时连接状态”。

### Returns

| Enum | Key Returns |
| --- | --- |
| `RuntimeConnectionMode` | `label`, `fromJsonValue` |
| `RuntimeConnectionStatus` | `label` |

## `AssistantExecutionTarget`

- Source: `lib/runtime/runtime_models_connection.dart`
- Type: `enum`
- Responsibility:
  表示当前 thread 最终是落到 `agent` 还是 `gateway`。

### Returns

| Getter / API | Returns | Meaning |
| --- | --- | --- |
| `label` / `compactLabel` | `String` | 展示标签 |
| `promptValue` | `String` | 发给 routing / prompt 的规范值 |
| `isAgent` / `isGateway` | `bool` | 类型判断 |
| `fromJsonValue` | `AssistantExecutionTarget` | 持久化恢复 |

## `SingleAgentProvider`

- Source: `lib/runtime/runtime_models_connection.dart`
- Type: `class`
- Responsibility:
  是 app 侧统一 provider 模型，同时承载 agent provider 与 gateway provider。

### Constructor Parameters

| Param | Type | Required | Meaning |
| --- | --- | --- | --- |
| `providerId` | `String` | Yes | 归一化 provider ID |
| `label` | `String` | Yes | 展示名 |
| `badge` | `String` | Yes | 短徽标 |
| `logoEmoji` | `String` | No | 可选 emoji |
| `supportedTargets` | `List<AssistantExecutionTarget>` | No | 支持的执行目标 |
| `enabled` | `bool` | No | 是否可用 |
| `unavailableReason` | `String` | No | 不可用说明 |
| `source` | `SingleAgentProviderSource` | No | 来源 |

### Key Returns

| API / Getter | Returns | Meaning |
| --- | --- | --- |
| `isUnspecified` | `bool` | 是否空 provider |
| `copyWith(...)` | `SingleAgentProvider` | 生成归一化副本 |
| `codex` / `opencode` / `claude` / `gemini` / `openclaw` | constants | 预置 provider 常量 |

## `GatewayConnectionSnapshot`

- Source: `lib/runtime/runtime_models_runtime_payloads.dart`
- Type: `class`
- Responsibility:
  描述 `GatewayRuntime` 当前连接快照，包括 status、auth mode、health/status 原始负载、错误码和 main session key。

### Constructor Parameters

| Param Group | Meaning |
| --- | --- |
| connectivity | `status`, `mode`, `statusText`, `remoteAddress`, `lastConnectedAtMs` |
| identity/auth | `deviceId`, `authRole`, `authScopes`, `connectAuthMode`, `connectAuthFields`, `connectAuthSources` |
| error | `lastError`, `lastErrorCode`, `lastErrorDetailCode` |
| payloads | `healthPayload`, `statusPayload` |

### Key Returns

| API | Returns | Meaning |
| --- | --- | --- |
| `initial(...)` | `GatewayConnectionSnapshot` | 初始离线快照 |
| `copyWith(...)` | `GatewayConnectionSnapshot` | 生成新快照 |
| `normalizedForConnectedState()` | `GatewayConnectionSnapshot` | connected 时清理历史错误 |
| `gatewayTokenMissing` | `bool` | 识别 AUTH_TOKEN_MISSING 场景 |
| `connectAuthSummary` | `String` | 汇总当前鉴权来源 |

## `AiGatewayProfile`

- Source: `lib/runtime/runtime_models_configs.dart`
- Type: `class`
- Responsibility:
  描述 AI gateway 地址、模型选择、密钥 ref、catalog 及联通性状态。

### Key Returns

| API | Returns | Meaning |
| --- | --- | --- |
| `defaults()` | `AiGatewayProfile` | 默认 profile |
| `copyWith(...)` | `AiGatewayProfile` | 更新 profile |
| `toJson()` / `fromJson(...)` | contract mapping | 序列化 / 恢复 |

## `AppTheme` / `AppPalette`

- Source: `lib/theme/app_theme.dart`, `lib/theme/app_palette.dart`
- Type: `class`
- Responsibility:
  虽然属于 UI 层，但它们是工程上可复用的主题入口，因此保留在公开接口层。

### Notes

- `AppTheme` 负责 spacing/radius/typography/sizes 与 `ThemeData` 组合
- `AppPalette` 是 `ThemeExtension`，为业务页面和 shell 提供调色板入口
