xworkmate-app/docs/ai-context/architecture-map.md

# Architecture Map — 跨仓库架构地图

> 生成日期: 2026-06-05 | 三个仓库的拓扑关系和协议边界

---

## 整体拓扑

```
┌─────────────────────────────────────────────────────────────┐
│                      用户桌面 (localhost)                      │
│                                                             │
│  ┌──────────────────────┐    ┌───────────────────────────┐  │
│  │   xworkmate-app       │    │   xworkmate-bridge         │  │
│  │   (Flutter/Dart)     │    │   (Go, :8787)              │  │
│  │                      │    │                           │  │
│  │ ┌──────────────────┐ │    │ ┌───────────────────────┐ │  │
│  │ │ AppController    │ │    │ │ HTTP/WS Handler       │ │  │
│  │ │ Desktop          │ │    │ │ /acp (WS)             │ │  │
│  │ └────────┬─────────┘ │    │ │ /acp/rpc (HTTP POST)  │ │  │
│  │          │            │    │ └───────────┬───────────┘ │  │
│  │ ┌────────▼─────────┐ │    │             │              │  │
│  │ │ GatewayRuntime   │ │◄───┼── ACP ──────┘              │  │
│  │ │ (WS + ACP Client)│ │    │ JSON-RPC 2.0              │  │
│  │ └────────┬─────────┘ │    │                           │  │
│  │          │            │    │ ┌───────────────────────┐ │  │
│  │ ┌────────▼─────────┐ │    │ │ Router                │ │  │
│  │ │ GoTaskService    │ │    │ │ (provider selection)  │ │  │
│  │ │ (任务分派)        │ │    │ └───────┬───────┬───────┘ │  │
│  │ └──────────────────┘ │    │         │       │          │  │
│  └──────────────────────┘    │    ┌────▼──┐ ┌──▼──────┐  │  │
│                              │    │ codex │ │ opencode│  │  │
│                              │    │(CLI)  │ │ (serve) │  │  │
│                              │    └───────┘ └─────────┘  │  │
│                              │    ┌───────┐ ┌─────────┐  │  │
│                              │    │ gemini│ │ hermes  │  │  │
│                              │    │(CLI)  │ │ (CLI)   │  │  │
│                              │    └───────┘ └─────────┘  │  │
│                              └─────────────┬─────────────┘  │
│                                            │                │
│                          ┌─────────────────┼────────────────┤
│                          │    OpenClaw 网关                 │
│                          │    (ws://127.0.0.1:18789)       │
│                          │    / openclaw.svc.plus:443      │
│                          └─────────────────┬───────────────┘
│                                            │
│                          ┌─────────────────▼───────────────┐
│                          │  openclaw-multi-session-plugins │
│                          │  (TypeScript, npm 插件)          │
│                          │                                 │
│                          │  网关方法:                       │
│                          │  xworkmate.tasks.get             │
│                          │  xworkmate.artifacts.*           │
│                          │                                 │
│                          │  Agent 工具:                     │
│                          │  openclaw_multi_session_artifacts│
│                          └─────────────────────────────────┘
│                                                             │
└─────────────────────────────────────────────────────────────┘

                        云端服务

  ┌──────────────────┐    ┌──────────────────────────────┐
  │ accounts.svc.plus│    │ xworkmate-bridge.svc.plus     │
  │ (账户/MFA)        │    │ (托管 Bridge, 多租户)         │
  └──────────────────┘    └──────────────────────────────┘

  ┌──────────────────┐
  │ ollama.svc.plus   │
  │ ollama.com        │
  │ (LLM 推理)         │
  └──────────────────┘
```

---

## 协议边界

### 边界 1: App ↔ Bridge (ACP JSON-RPC)

| 属性 | 值 |
|------|-----|
| 协议 | JSON-RPC 2.0 |
| 传输 | WebSocket (`/acp`) + HTTP POST/SSE (`/acp/rpc`) |
| 认证 | Bearer token (BRIDGE_AUTH_TOKEN) |
| 方向 | App → Bridge (请求), Bridge → App (SSE 推送) |
| 关键方法 | `session.start`, `session.message`, `acp.capabilities`, `xworkmate.gateway.*` |

### 边界 2: Bridge ↔ AI Providers (ACP JSON-RPC)

| 属性 | 值 |
|------|-----|
| 协议 | JSON-RPC 2.0 |
| 传输 | WebSocket (codex) / HTTP (opencode, gemini, hermes) |
| 认证 | Bearer token |
| 方向 | Bridge → Provider (请求/响应) |
| 特殊 | gemini/hermes 通过子进程 stdio 中转（adapter 模式） |

### 边界 3: Bridge ↔ OpenClaw Gateway (Gateway RPC)

| 属性 | 值 |
|------|-----|
| 协议 | 自定义 WebSocket RPC（Ed25519 加密握手） |
| 传输 | WebSocket |
| 默认端点 | `ws://127.0.0.1:18789` (本地) / `wss://openclaw.svc.plus:443` (云端) |
| 关键方法 | `chat.send`, `xworkmate.artifacts.*`, `agent.wait` |
| 方向 | 双向 (Bridge 发起请求 + 订阅推送事件) |

### 边界 4: OpenClaw Gateway ↔ Plugin (内部插件 API)

| 属性 | 值 |
|------|-----|
| 协议 | OpenClaw Plugin SDK (内存调用) |
| 方法 | `xworkmate.tasks.get`, `xworkmate.artifacts.prepare/export/collect-and-snapshot/list/read` |
| 工具 | `openclaw_multi_session_artifacts` |

---

## 数据流方向

```
用户输入
  │
  ▼
xworkmate-app ──── session.start ────► xworkmate-bridge
  │                                        │
  │                                        ├──► codex/opencode/gemini/hermes
  │                                        │       (AI agent 执行)
  │                                        │
  │                                        └──► OpenClaw Gateway
  │                                                │
  │                                   chat.send     │
  │                                   ◄─────────────┘
  │  SSE stream (token by token)
  │  xworkmate.gateway.push
  ◄─────────────────────────────────
  │
  │  工件下载:
  │  GET /artifacts/openclaw/download?ref=<signed>
  ├──────────────────────────────────► xworkmate-bridge
  │                                        │
  │                                        └──► xworkmate.artifacts.read
  │                                                │
  │                                                ▼
  │                                     openclaw-multi-session-plugins
  │
  ▼
本地文件: ~/.xworkmate/threads/<session>/
```

---

## 关键配置项

### xworkmate-app (config/settings.yaml)
```yaml
bridge:
  server_url: "https://xworkmate-bridge.svc.plus"
  auth_token: ""

accounts:
  base_url: "https://accounts.svc.plus"
```

### xworkmate-bridge (环境变量 / config.yaml)
```yaml
upstream:
  gateway_url: "ws://127.0.0.1:18789"     # GATEWAY_RPC_URL
  codex_url: ""                           # CODEX_RPC_URL
  opencode_url: "http://127.0.0.1:38993"  # OPENCODE_RPC_URL
  gemini_url: "http://127.0.0.1:8791"     # GEMINI_RPC_URL
  hermes_url: "http://127.0.0.1:3920"     # HERMES_RPC_URL

distributed_nodes:
  - id: xworkmate-bridge
    role: primary
    endpoint: "http://172.29.10.1:8787"
  - id: cn-xworkmate-bridge
    role: edge
    endpoint: "http://172.29.10.2:8787"
```

### openclaw-multi-session-plugins (openclaw.plugin.json)
```json
{
  "gatewayMethods": [
    "xworkmate.tasks.get",
    "xworkmate.artifacts.prepare",
    "xworkmate.artifacts.export",
    "xworkmate.artifacts.collect-and-snapshot",
    "xworkmate.artifacts.list",
    "xworkmate.artifacts.read"
  ],
  "config": {
    "workspaceDir": "~/.openclaw/workspace",
    "maxFiles": 1000,
    "artifactRefSigningSecret": ""
  }
}
```