Cowork 3P 7573780956 docs(architecture): fix critical accuracy errors, stale refs, paths

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)

2026-06-04 06:53:38 +00:00

2.7 KiB

Raw Blame History

xworkmate-bridge 统一路由架构文档

1. 架构概览 (Unified Routing Architecture)

当前系统采用 xworkmate-bridge.svc.plus 作为统一入口。App 侧通过 managed bridge ACP 主入口 /acp/rpc 处理能力发现、路由解析、agent 任务（含 bridge 多 agent 转发）、OpenClaw gateway 任务和会话控制。Provider runtime 与 gateway runtime 地址仍由 bridge 后端内部拥有，不暴露为 App-facing public mapping。

graph TD
    subgraph "External Access"
        Client["xworkmate-app (Client)"]
    end

    subgraph "Unified Gateway (Caddy)"
        Bridge_Domain["https://xworkmate-bridge.svc.plus"]
    end

    subgraph "Bridge-owned Routing"
        ManagedBridge["Managed Bridge ACP<br/>/acp/rpc"]
        CodexProvider["Codex internal runtime"]
        OpenCodeProvider["OpenCode internal runtime"]
        GeminiAdapter["Gemini internal runtime"]
        OpenClawGateway["OpenClaw internal runtime"]
    end

    %% Routing Rules
    Client -->|HTTPS/WSS| Bridge_Domain

    Bridge_Domain -->|/acp/rpc| ManagedBridge
    ManagedBridge -->|provider routing| CodexProvider
    ManagedBridge -->|provider routing| OpenCodeProvider
    ManagedBridge -->|provider routing| GeminiAdapter
    ManagedBridge -->|gateway routing| OpenClawGateway

    %% Service Connections
    ManagedBridge -.->|Capabilities Discovery| Client

2. 路由分发规则

Bridge-owned mapping	App 侧行为	备注
`/acp/rpc`	直接调用	能力发现、路由解析、agent 任务（含 bridge 多 agent 转发）、OpenClaw gateway 任务、cancel、close
provider runtime	不直连	Bridge 后端内部解析 provider
gateway runtime	不直连	Bridge 后端内部解析 gateway provider

3. 运维配置优化

3.1 统一鉴权

App 发往 xworkmate-bridge.svc.plus/acp/rpc 的请求必须携带：

Header: Authorization: Bearer <bridge-auth-token>
未授权响应: 401 Unauthorized

3.2 SSE / WebSocket 优化

所有反向代理均配置了 flush_interval -1，禁用了响应缓冲，以支持低延迟的 SSE 流式输出和稳定的 WebSocket 长连接。

3.3 日志持久化 (Docker)

xworkmate-bridge-managed 容器已配置日志挂载：

宿主机路径: /var/log/xworkmate-bridge/
容器路径: /app/logs
轮转策略: 单文件 50MB，保留最近 3 个文件。

4. App 侧不变量

App 不写入或拼接本地 provider endpoint。
App 不直接调用 /acp-server/*。
App 不调用 /gateway/openclaw；OpenClaw session.start / session.message task submit 通过 /acp/rpc 的 routing metadata 表达。
acp.capabilities 是 provider catalog、gateway catalog、available execution targets 的唯一来源。

2.7 KiB Raw Blame History Unescape Escape