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)
198 lines
7.1 KiB
Markdown
198 lines
7.1 KiB
Markdown
# 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 提供调色板入口
|