# Chain Map — 跨仓库调用链

> 生成日期: 2026-06-05 | 文件级调用链，标注协议边界

---

## Chain 1: 用户发起 AI 对话 (主流程)

```
xworkmate-app                                    xworkmate-bridge
─────────────                                    ────────────────
lib/app/app_controller_desktop.dart
  → handleChatSend()
    └─ lib/runtime/gateway_runtime_core.dart
         GatewayRuntime.sendMessage()
           │
           ├── (ACP WebSocket 路径)
           │   └─ lib/runtime/gateway_acp_client.dart
           │        GatewayAcpClient.request(method: "session.start", ...)
           │          → WebSocket /acp ──────────────────► internal/acp/http_handler.go
           │                                                HandleWebSocket()
           │                                                  └─ internal/acp/rpc_handler.go
           │                                                       handleRequest("session.start", ...)
           │                                                         └─ internal/router/
           │                                                              Resolve(provider)
           │                                                                └─ Provider handler
           │
           └── (ACP HTTP/SSE 路径)
               └─ lib/runtime/gateway_acp_client.dart
                    GatewayAcpClient.request()
                      → HTTP POST /acp/rpc ──────────────► internal/acp/http_handler.go
                                                             HandleRPC()
                                                               └─ internal/acp/rpc_handler.go
                                                                    handleRequest(...)
```

### 涉及的 key files:
| 层 | 文件 | 作用 |
|----|------|------|
| app | `lib/app/app_controller_desktop.dart` | 用户输入入口 |
| app | `lib/runtime/gateway_runtime_core.dart` | Gateway runtime 核心 |
| app | `lib/runtime/gateway_acp_client.dart` | ACP 客户端 (JSON-RPC 封装) |
| app | `lib/runtime/acp_endpoint_paths.dart` | 端点路径解析 |
| bridge | `internal/acp/http_handler.go` | HTTP/WS 请求入口 |
| bridge | `internal/acp/rpc_handler.go` | JSON-RPC 方法分发 |
| bridge | `internal/router/` | 提供商路由 |

### 协议: ACP JSON-RPC 2.0 over WebSocket (主) / HTTP SSE (后备)
### 断点风险:
- ACP 客户端 120s 超时 → 长任务可能超时
- SSE 流中断后降级为轮询 (`xworkmate.tasks.get`)
- WebSocket 断线需重连 (30s ping/10s 超时)

---

## Chain 2: OpenClaw 网关任务执行

```
xworkmate-app                                    xworkmate-bridge
─────────────                                    ────────────────
lib/runtime/external_code_agent_acp_desktop_transport.dart
  ExternalCodeAgentAcpTransport
    → session.start(routing: gateway/openclaw,
                    metadata.xworkmateTaskArtifactContract.expectedArtifactDirs)
      └─ lib/runtime/gateway_acp_client.dart
           → WebSocket /acp or POST /acp/rpc ───────► internal/acp/http_handler.go
           │                                            HandleWebSocket()/HandleRPC()
           │                                              └─ internal/acp/rpc_handler.go
           │                                                   Orchestrator.Process()
           │                                                     │
           │                                                     ├─ 本地 gateway
           │                                                     │   └─ internal/gatewayruntime/runtime.go
           │                                                     │        GatewayRuntime.Connect()
           │                                                     │          → WebSocket ────► OpenClaw Gateway
           │                                                     │                              ws://127.0.0.1:18789
           │                                                     │                                │
           │                                                     │                                ├─ chat.send
           │                                                     │                                ├─ agent.wait
           │                                                     │                                └─ xworkmate.artifacts.*
           │                                                     │                                      │
           │                                                     │                                      ▼
           │                                                     │                           openclaw-multi-session-plugins
           │                                                     │                           ─────────────────────────────
           │                                                     │                           index.ts → register()
           │                                                     │                             xworkmate.artifacts.prepare
           │                                                     │                             xworkmate.artifacts.export
           │                                                     │                             xworkmate.artifacts.read
           │                                                     │
           │                                                     └─ 分布式转发
           │                                                         └─ internal/acp/distributed_forwarder.go
           │                                                              ForwardToPeer()
           │                                                                → HTTP POST → 远端 bridge /acp/rpc
           │
           ◄── SSE stream (token by token) ────────────
           ◄── xworkmate.gateway.push (chat events) ───

lib/app/app_controller_openclaw_task_queue.dart
  OpenClawTaskQueue
    → 本地队列管理 (max 5 active, 20 queued)
    → 持久化 typed association
    → 恢复查询只发送 appThreadKey/openclawSessionKey/runId 到 native task-registry
```

Protocol boundary:
- `expectedArtifactDirs` is not a `chat.send` root parameter.
- App sends it only as `metadata.xworkmateTaskArtifactContract.expectedArtifactDirs` on `session.start`.
- Bridge maps it only into `xworkmate.artifacts.export` and `xworkmate.artifacts.collect-and-snapshot`.
- Bridge must reject old root/metadata compatibility paths instead of probing fallback keys.

### 涉及的 key files:
| 层 | 文件 | 作用 |
|----|------|------|
| app | `lib/runtime/external_code_agent_acp_desktop_transport.dart` | 任务传输层 |
| app | `lib/runtime/go_task_service_client.dart` | 任务接口定义 |
| app | `lib/runtime/go_task_service_desktop_service.dart` | 桌面任务服务 |
| app | `lib/app/app_controller_openclaw_task_queue.dart` | 客户端任务队列 |
| bridge | `internal/acp/gateway.go` | OpenClaw 集成 |
| bridge | `internal/acp/http_handler.go` | `/acp` / `/acp/rpc` 端点 |
| bridge | `internal/gatewayruntime/runtime.go` | 网关 WS 客户端 |
| bridge | `internal/acp/distributed_forwarder.go` | 分布式转发 |
| plugins | `index.ts` | 插件入口 |
| plugins | `src/exportArtifacts.ts` | 工件逻辑 |

### 协议: ACP JSON-RPC → Gateway RPC (WebSocket, Ed25519 握手)
### 断点风险:
- 网关 WebSocket 断连 → 任务丢失
- 分布式转发 hop=3 限制 → 深层拓扑不可达
- 任务轮询恢复依赖 `xworkmate.tasks.get` → Bridge 只转发 typed lookup，
  terminal state 以 OpenClaw native task-registry 为准；缺少 native task
  record 时返回 `no_native_task_record`，不从 artifactScope/runId 重建任务。

---

## Chain 3: 工件下载流

```
xworkmate-app                                    xworkmate-bridge
─────────────                                    ────────────────
lib/app/app_controller_desktop_thread_storage.dart
  syncArtifactsFromBridge()
    → GET /artifacts/openclaw/download ───────────► internal/acp/http_handler.go
           ?ref=<signed>&t=<expiry>                  HandleArtifactDownload()
                                                       └─ internal/gatewayruntime/runtime.go
                                                            gateway.RequestByMode(
                                                              "openclaw",
                                                              "xworkmate.artifacts.read",
                                                              params
                                                            )
                                                              │
                                                              ▼
                                                    openclaw-multi-session-plugins
                                                    ─────────────────────────────
                                                    src/exportArtifacts.ts
                                                      xworkmate.artifacts.read()
                                                        → 验证 HMAC 签名
                                                        → 读取文件内容
                                                        → 返回 artifact
```

### 涉及的 key files:
| 层 | 文件 | 作用 |
|----|------|------|
| app | `lib/app/app_controller_desktop_thread_storage.dart` | 工件同步 |
| bridge | `internal/acp/http_handler.go` | 下载端点 |
| bridge | `internal/gatewayruntime/runtime.go` | 网关调用 |
| plugins | `src/exportArtifacts.ts` | read 逻辑 |

### 安全: HMAC-SHA256 签名绑定 (workspaceRoot, session, run, path, size, hash)
### 断点风险:
- 签名过期 (24h) → 下载失败
- 签名密钥不一致 → 验证失败

---

## Chain 4: MCP 配置生成

```
xworkmate-app                                    xworkmate-bridge
─────────────                                    ────────────────
lib/runtime/codex_config_bridge.dart
  CodexConfigBridge.generate()
    → 写入 ~/.codex/config.toml
      [mcp_servers.xworkmate]
      command = "openclaw-mcp"
      args = ["--gateway", "https://xworkmate-bridge.svc.plus"]
      # BEGIN XWORKMATE MANAGED MCP BLOCK
      ...
      # END XWORKMATE MANAGED MCP BLOCK

lib/runtime/opencode_config_bridge.dart
  OpencodeConfigBridge.generate()
    → 写入 ~/.opencode/config.toml
      [mcp_servers.xworkmate]
      url = "https://xworkmate-bridge.svc.plus/acp"
      # 或 type="stdio" + command="openclaw-mcp" + args=["--gateway", url]
```

### 涉及的 key files:
| 层 | 文件 | 作用 |
|----|------|------|
| app | `lib/runtime/codex_config_bridge.dart` | Codex CLI 配置 |
| app | `lib/runtime/opencode_config_bridge.dart` | OpenCode CLI 配置 |
| bridge | `internal/mounts/reconcile.go` | MCP 配置管理 (服务端) |

### 断点风险:
- 配置 block 标记 (`# BEGIN XWORKMATE MANAGED MCP BLOCK`) 冲突 → 覆盖用户配置
- Gateway URL 变更 → 需重新生成配置

---

## Chain 5: 已移除的 Plugin → Bridge 反向调用

```
旧链路:
  openclaw-multi-session-plugins/src/bridgeAgents.ts
    → HTTP POST xworkmate-bridge /acp/rpc
    → session.start(multiAgent=true)

当前链路:
  xworkmate-bridge → OpenClaw Gateway → openclaw-multi-session-plugins
    → xworkmate.artifacts.*
```

### 涉及的 key files:
| 层 | 文件 | 作用 |
|----|------|------|
| plugins | `index.ts` / `src/exportArtifacts.ts` | artifact scope adapter |
| bridge | `internal/acp/orchestrator.go` | OpenClaw gateway orchestration |

### 协议: 无 Plugin→Bridge 运行时协议
### 断点风险:
- 旧版本插件若仍暴露 bridge agents 工具，会恢复循环依赖，应从 manifest 和 dist 中删除

---

## 跨仓库调用矩阵

```
                    调用方
                app    bridge    plugins
              ┌───────┬───────┬───────┐
      app     │   -   │ ACP   │   -   │
被调   bridge  │   -   │  -    │  -    │
方    plugins │   -   │ GW    │   -   │
              └───────┴───────┴───────┘

ACP  = JSON-RPC 2.0 over WebSocket/HTTP SSE
GW   = OpenClaw Gateway RPC over WebSocket (Ed25519)
```

## 调用链复杂度评分

| Chain | 跨仓库跳数 | 协议变换 | 风险等级 |
|-------|-----------|---------|---------|
| Chain 1 (AI 对话) | 2 (app→bridge→provider) | 1 (ACP) | **中** |
| Chain 2 (OpenClaw 任务) | 4 (app→bridge→gateway→plugins) | 2 (ACP + GW RPC) | **高** |
| Chain 3 (工件下载) | 3 (app→bridge→gateway→plugins) | 2 (HTTPS + GW RPC) | **中** |
| Chain 4 (MCP 配置) | 1 (app→本地文件) | 0 | **低** |
| Chain 5 (多 Agent) | 2 (plugins→bridge→provider) + 2 (bridge→gateway→plugins) | 2 (HTTP + GW RPC) | **高/循环** |