ai-workspace-lab/xworkmate-app

Fork 0

Haitao Pan ae1faa03d0 docs: clarify architecture baselines

2026-03-23 08:59:44 +08:00

7.3 KiB

Raw Blame History

XWorkmate 集成架构

概述

XWorkmate 现阶段已经不只是“单一 Codex bridge”，但当前实现也不是一个单独的 “Discovery / Distribution Catalog” 模块。

当前集成能力分散在几条明确的实现路径里：

GatewayRuntime
- 负责 OpenClaw Gateway 的实时 RPC、会话、chat、pairing、cron
MultiAgentBrokerServer + MultiAgentOrchestrator
- 负责多 Agent 协作运行
MultiAgentMountManager
- 负责按 adapter 做 CLI 能力探测、MCP reconcile、挂载状态汇总
CodexConfigBridge / OpencodeConfigBridge
- 负责特定 CLI 的配置文件写入
Assistant composer 与 feature flags
- 决定当前哪些集成入口真实对用户可见

也就是说，当前架构更接近“分布式集成面”，不是单一 catalog service。

当前架构基线

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，而不是设置页独立标签。

7.3 KiB Raw Blame History Unescape Escape