211 lines
7.3 KiB
Markdown
211 lines
7.3 KiB
Markdown
# XWorkmate 集成架构
|
||
|
||
## 概述
|
||
|
||
XWorkmate 现阶段已经不只是“单一 Codex bridge”，但当前实现也不是一个单独的 “Discovery / Distribution Catalog” 模块。
|
||
|
||
当前集成能力分散在几条明确的实现路径里：
|
||
|
||
1. `GatewayRuntime`
|
||
- 负责 OpenClaw Gateway 的实时 RPC、会话、chat、pairing、cron
|
||
2. `MultiAgentBrokerServer` + `MultiAgentOrchestrator`
|
||
- 负责多 Agent 协作运行
|
||
3. `MultiAgentMountManager`
|
||
- 负责按 adapter 做 CLI 能力探测、MCP reconcile、挂载状态汇总
|
||
4. `CodexConfigBridge` / `OpencodeConfigBridge`
|
||
- 负责特定 CLI 的配置文件写入
|
||
5. Assistant composer 与 feature flags
|
||
- 决定当前哪些集成入口真实对用户可见
|
||
|
||
也就是说，当前架构更接近“分布式集成面”，不是单一 catalog service。
|
||
|
||
## 当前架构基线
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
X["XWorkmate App"] --> GR["GatewayRuntime"]
|
||
X --> BM["MultiAgentBrokerServer<br/>WebSocket JSON-RPC"]
|
||
X --> MM["MultiAgentMountManager"]
|
||
X --> NO["CodeAgentNodeOrchestrator"]
|
||
X --> UI["Assistant composer / Settings / Feature flags"]
|
||
|
||
BM --> O["MultiAgentOrchestrator"]
|
||
O --> C["Codex / Claude / Gemini / OpenCode"]
|
||
|
||
MM --> MA["Codex / Claude / Gemini / OpenCode / OpenClaw adapters"]
|
||
MA --> CFG["Managed config writes / mcp list / local file discovery"]
|
||
|
||
GR --> G["OpenClaw Gateway / Host"]
|
||
NO --> G
|
||
C --> A["AI Gateway or Ollama endpoint"]
|
||
```
|
||
|
||
关键点：
|
||
|
||
- `MultiAgentBroker` 是多 CLI 协作的本地运行时入口。
|
||
- `OpenClaw` 既是现有 Gateway 集成面，也是当前 app-mediated code-agent dispatch 的宿主控制面。
|
||
- `AI Gateway` 既可以是 direct AI 对话入口，也可以是协作运行的注入式模型入口。
|
||
- 当前没有一个单独命名为 `Discovery / Distribution Catalog` 的实现模块。
|
||
|
||
## 1. OpenClaw Gateway / Host
|
||
|
||
用途：
|
||
|
||
- 运行时协同
|
||
- 设备与信任边界
|
||
- Agent / Session / Chat 通道
|
||
- 宿主控制面发现
|
||
|
||
已使用能力：
|
||
|
||
- `health`
|
||
- `status`
|
||
- `agents.list`
|
||
- `sessions.list`
|
||
- `chat.send`
|
||
- `device.pair.*`
|
||
- `cron.list`
|
||
- `agent/register`
|
||
- `memory/sync`
|
||
|
||
当前定位：
|
||
|
||
- 继续作为 Gateway RPC 面存在
|
||
- 也是 app-mediated code-agent dispatch 的控制面目标
|
||
- 在 mount 视角下，OpenClaw 目前更多是“本地发现 + 宿主控制面”，不是一个统一的 skills / plugins catalog service
|
||
|
||
## 2. AI Gateway
|
||
|
||
用途：
|
||
|
||
- direct AI 对话入口
|
||
- 协作运行时的模型注入入口
|
||
- 对部分 CLI 的配置桥接入口
|
||
|
||
边界：
|
||
|
||
- 不负责设备配对
|
||
- 不负责 session / agent 生命周期
|
||
- 不替换用户现有默认 provider / model
|
||
|
||
当前策略：
|
||
|
||
- `CodexConfigBridge` 可以写入受管 provider / MCP block
|
||
- `MultiAgentOrchestrator` 在协作运行中会通过环境变量或 `ollama launch` 传递模型入口
|
||
- `Claude / Gemini` 的 mount reconcile 目前主要做 discovery，AI Gateway 仍保持 launch-scoped
|
||
- `OpenCode` 当前有受管 MCP config；AI Gateway 语义仍偏 launch-scoped / runtime injection
|
||
|
||
换句话说，AI Gateway 能力是分散落地的，不是所有 CLI 都通过同一条托管 provider 路径接入。
|
||
|
||
## 3. Multi-Agent Runtime
|
||
|
||
### 编排层
|
||
|
||
`MultiAgentOrchestrator` 负责：
|
||
|
||
- Architect 任务分析
|
||
- Engineer 实现
|
||
- Tester / Doc 审阅
|
||
- 迭代评分与回退
|
||
|
||
### Broker 层
|
||
|
||
`MultiAgentBroker` 负责：
|
||
|
||
- 本地 `WebSocket JSON-RPC`
|
||
- run lifecycle
|
||
- worker CLI 启动
|
||
- selected skills / MCP / Gateway 上下文注入
|
||
- 结构化事件流回写当前会话
|
||
|
||
### UI 接线
|
||
|
||
- Assistant 继续复用现有 composer、附件、当前会话
|
||
- 桌面端真正对用户可见的协作入口，当前主要是 Assistant composer 上的协作 toggle
|
||
- `SettingsPage` 里有 Multi-Agent 配置区块与 detail 页面代码，但桌面端 `settings.agents` 仍被 feature flag 关闭
|
||
- 不新增独立任务页面
|
||
|
||
## 4. 发现与分发
|
||
|
||
当前实现里，`managed / external` 更像一套按 adapter 执行的操作规则，而不是单独的中心化状态目录。
|
||
|
||
XWorkmate 仍然区分两类对象：
|
||
|
||
- `managed`
|
||
- 由 App 创建与维护的托管项
|
||
- `external`
|
||
- 外部已有配置或 CLI 自带配置
|
||
|
||
统一规则：
|
||
|
||
- 只更新 XWorkmate 托管项
|
||
- 不删除外部已有项
|
||
- 启动时与保存设置后自动 reconcile
|
||
- 这套规则当前由 `MultiAgentMountManager` 在各 adapter 上分别执行
|
||
|
||
## 5. 挂载入口矩阵
|
||
|
||
| 目标 | Skills 挂载入口 | MCP 挂载入口 | AI Gateway 挂载入口 |
|
||
| --- | --- | --- | --- |
|
||
| OpenClaw | 本地文件 / 目录发现 + Gateway 控制面 | 不作为 MCP 主挂载点 | app-mediated dispatch / gateway route |
|
||
| Codex | 当前线程 skills 上下文 +协作运行注入 | `~/.codex/config.toml` 受管 MCP block | 受管 provider bridge + runtime injection |
|
||
| Claude | 当前线程 skills 上下文 +协作运行注入 | `claude mcp list` 做 discovery | launch-scoped / env / `ollama launch` |
|
||
| Gemini | 当前线程 skills 上下文 +协作运行注入 | `gemini mcp list` 做 discovery | launch-scoped / env |
|
||
| OpenCode | 当前线程 skills 上下文 +协作运行注入 | `~/.opencode/config.toml` 受管 MCP block | runtime injection |
|
||
|
||
## 6. 外部 Provider 与执行路径
|
||
|
||
保留现有统一 contract：
|
||
|
||
- `ExternalCodeAgentProvider.id`
|
||
- `name`
|
||
- `command`
|
||
- `defaultArgs`
|
||
- `capabilities`
|
||
- `CodeAgentNodeOrchestrator.buildGatewayDispatch()`
|
||
|
||
现状：
|
||
|
||
- `codex` 仍是当前最完整 provider
|
||
- 其他 CLI 当前主要通过 `CliMountAdapter` discovery / reconcile 与 `MultiAgentOrchestrator` 运行时调用接入
|
||
- 多 provider 调度 UI 不是当前交付目标
|
||
|
||
## 7. 安全边界
|
||
|
||
- `.env` 仅用于开发预填充，不自动连接，不作为持久化真值源
|
||
- AI Gateway API Key 与 Gateway 凭证继续走 secure storage
|
||
- 新增协作路径不得把 secret 写入 `SharedPreferences`
|
||
- Launch-scoped 注入优先于全局配置改写
|
||
- 远程 Gateway 不允许静默降级为非 TLS
|
||
- 协作事件与 metadata 不上传本地 secret 或本机绝对路径
|
||
|
||
## 8. 设置页统一动作语义（Gateway 家族）
|
||
|
||
`OpenClaw Gateway`、`Vault`、`AI Gateway`（以及后续外部扩展）统一遵循同一操作语义：
|
||
|
||
- `Test`：只使用当前草稿（含当前输入的临时 secret 覆盖）做连通性校验，不写入持久层。
|
||
- `Save`：把草稿同步到本地持久存储（`SettingsStore` + `SecretStore`），不立即改变运行时会话行为。
|
||
- `Apply`：在 `Save` 的基础上，立即让当前运行时按新配置生效。
|
||
|
||
实现约束：
|
||
|
||
- Gateway 集成页不再重复显示顶层全局 `Save / Apply`，避免与卡片内动作语义冲突。
|
||
- 桌面端 `settings.gateway_setup_code` 与 `settings.agents` 当前都被 feature flag 关闭。
|
||
- 但桌面端 `assistant.multi_agent` 仍然开启，所以协作入口当前主要暴露在 Assistant composer，而不是设置页独立标签。
|
||
|
||
## 相关代码
|
||
|
||
- `lib/app/app_controller_desktop.dart`
|
||
- `lib/app/app_controller_web.dart`
|
||
- `lib/features/assistant/assistant_page.dart`
|
||
- `lib/features/settings/settings_page.dart`
|
||
- `lib/runtime/gateway_runtime.dart`
|
||
- `lib/runtime/runtime_models.dart`
|
||
- `lib/runtime/multi_agent_orchestrator.dart`
|
||
- `lib/runtime/multi_agent_broker.dart`
|
||
- `lib/runtime/multi_agent_mounts.dart`
|
||
- `lib/runtime/codex_config_bridge.dart`
|
||
- `lib/runtime/opencode_config_bridge.dart`
|
||
- `lib/runtime/code_agent_node_orchestrator.dart`
|
||
- `lib/runtime/runtime_coordinator.dart`
|