openclaw/ARCHITECTURE_BLUEPRINT.md

# OpenClaw 架构蓝图

> 完整的系统架构可视化

---

## 1. 整体系统架构

```mermaid
graph TB
    subgraph "客户端层 Clients"
        APP1[macOS App]
        APP2[iOS App]
        APP3[Android App]
        UI[Web UI]
        CLI[CLI Tool]
        NODES[Nodes<br/>macOS/iOS/Android]
    end

    subgraph "网关层 Gateway (18789)"
        WS[WebSocket Server]
        HTTP[HTTP Server]
        PROTO[Protocol Validator<br/>AJV]
        CHANNELS[Channel Manager]
        EVENTS[Event Dispatcher]
        METHODS[Method Handlers]
        CRON[Cron Service]
        CANVAS["Canvas Host<br/>a2ui (18793)"]
    end

    subgraph "通道层 Channels"
        WA[WhatsApp Web<br/>Baileys]
        TG[Telegram<br/>grammY]
        DC[Discord]
        SL[Slack]
        SG[Signal]
        IM[iMessage]
        LN[LINE]
        GO[Google Chat]
        MS[MS Teams]
        EXT[Extensions<br/>Matrix/Zalo/etc]
    end

    subgraph "Agent 层"
        ROUTER[Message Router<br/>Bindings]
        SESSION[Session Manager]
        AGENT[Agent Runtime]
        TOOLS[Tool Execution]
        MEMORY[Memory Store]
        PROVIDERS[Model Providers<br/>OpenAI/Anthropic/etc]
    end

    subgraph "基础设施层Infrastructure"
        MEDIA[Media Pipeline<br/>Store/Fetch/Process]
        CONFIG[Config System<br/>JSON5/Zod]
        PAIRING[Device Pairing]
        AUTH[Authentication]
        LOGS[Logging System]
        DIAG[Diagnostic Events]
    end

    subgraph "扩展层Plugins"
        PLUGINSDK[Plugin SDK]
        CHANNEL_PLG[Channel Plugins]
        MEMORY_PLG[Memory Plugins]
        PROVIDER_PLG[Provider Plugins]
        HOOKS[Lifecycle Hooks]
    end

    %% 连接关系
    APP1 -->|WebSocket| WS
    APP2 -->|WebSocket| WS
    APP3 -->|WebSocket| WS
    UI -->|WebSocket| WS
    CLI -->|WebSocket| WS
    NODES -->|WebSocket| WS

    WS --> PROTO
    PROTO --> METHODS
    PROTO --> EVENTS

    HTTP --> METHODS

    METHODS --> CHANNELS
    METHODS --> ROUTER
    METHODS --> CONFIG
    METHODS --> MEDIA

    CHANNELS --> WA
    CHANNELS --> TG
    CHANNELS --> DC
    CHANNELS --> SL
    CHANNELS --> SG
    CHANNELS --> IM
    CHANNELS --> LN
    CHANNELS --> GO
    CHANNELS --> MS
    CHANNELS --> EXT

    CHANNELS -.->|事件| EVENTS
    EVENTS -.->|广播| WS

    CRON -.->|触发| EVENTS

    WA -->|入站| CHANNELS
    TG -->|入站| CHANNELS
    DC -->|入站| CHANNELS
    SL -->|入站| CHANNELS
    SG -->|入站| CHANNELS
    IM -->|入站| CHANNELS
    LN -->|入站| CHANNELS
    GO -->|入站| CHANNELS
    MS -->|入站| CHANNELS
    EXT -->|入站| CHANNELS

    CHANNELS -->|路由| ROUTER
    ROUTER --> AGENT

    AGENT --> TOOLS
    AGENT --> MEMORY
    AGENT --> PROVIDERS

    AGENT -->|出站| CHANNELS
    AGENT -.->|事件| EVENTS

    SESSION -->|持久化| ROUTER

    METHODS --> MEDIA
    CONFIG -->|加载| CHANNELS
    CONFIG -->|加载| ROUTER

    WS --> AUTH
    PAIRING --> AUTH

    LOGS -->| everywhere | *
    DIAG -->| everywhere | *

    PLUGINSDK --> CHANNEL_PLG
    PLUGINSDK --> MEMORY_PLG
    PLUGINSDK --> PROVIDER_PLG

    CHANNEL_PLG --> CHANNELS
    MEMORY_PLG --> MEMORY
    PROVIDER_PLG --> PROVIDERS

    HOOKS --> AGENT
    HOOKS --> CHANNELS
    HOOKS --> EVENTS

    style Gateway fill:#e1f5fe
    style Clients fill:#f3e5f5
    style Channels fill:#fff3e0
    style Agent fill:#e8f5e9
    style Infrastructure fill:#fce4ec
    style Plugins fill:#fff9c4
```

---

## 2. Gateway 详细架构

```mermaid
graph TB
    subgraph "Gateway Server：端口 18789"
        ENTER[客户端连接] --> WS_CONN

        subgraph "WebSocket 层"
            WS_CONN[WebSocket Server]
            WS_HANDLER[WS Handler]
            FRAME_PARSER[Frame Parser]
            FRAME_VALIDATOR[Frame Validator<br/>JSON Schema]
        end

        subgraph "连接管理 Connect Management"
            HELLO[req:connect]
            AUTH_CHECK[Auth Check<br/>Token Check]
            PAIRING_CHECK[Pairing Check<br/>Device Approval]
            CLIENT_REGISTRY[Client Registry]
        end

        subgraph "方法层 Method Layer"
            METHOD_DISPATCH[Method Dispatcher]
            CORE_HANDLERS[Core Handlers<br/>health/status/send/agent]
            GATEWAY_METHODS[Gateway Methods<br/>channels.* / media.*]
            PLUGIN_METHODS[Plugin Methods]
        end

        subgraph "状态层 State Layer"
            RUNTIME_STATE[Runtime State<br/>健康查看 / 缓冲]
            CHANNEL_STATE[Channel State<br/>运行时实例]
            NODE_REGISTRY[Node Registry]
        end

        subgraph "事件层 Event Layer"
            EVENT_EMITTER[Event Emitter]
            AGENT_EVENTS[agent Events]
            CHAT_EVENTS[chat Events]
            PRESENCE_EVENTS[presence Events]
            HEARTBEAT[heartbeat Events]
            DIAGNOSTICS[diagnostic Events]
        end

        subgraph "资源层 Resource Layer"
            CONFIG_RELOAD[Config Reloader]
            CHANNEL_MANAGER[Channel Manager]
            CANVAS_HOST[Canvas Host<br/>a2ui:18793]
            MEDIA_SERVER[Media Server]
            CRON_SCHEDULER[Cron Scheduler]
        end
    end

    %% 连接关系
    WS_CONN --> WS_HANDLER
    WS_HANDLER --> FRAME_PARSER
    FRAME_PARSER --> FRAME_VALIDATOR

    FRAME_VALIDATOR --> HELLO
    FRAME_VALIDATOR --> METHOD_DISPATCH

    HELLO --> AUTH_CHECK
    AUTH_CHECK --> PAIRING_CHECK
    PAIRING_CHECK --> CLIENT_REGISTRY
    CLIENT_REGISTRY --> RUNTIME_STATE

    METHOD_DISPATCH --> CORE_HANDLERS
    METHOD_DISPATCH --> GATEWAY_METHODS
    METHOD_DISPATCH --> PLUGIN_METHODS

    CORE_HANDLERS -->|使用| RUNTIME_STATE
    CORE_HANDLERS -->|使用| CHANNEL_STATE
    CORE_HANDLERS -->|使用| CHANNEL_MANAGER

    GATEWAY_METHODS --> CHANNEL_MANAGER
    GATEWAY_METHODS --> MEDIA_SERVER
    GATEWAY_METHODS --> NODE_REGISTRY

    CHANNEL_MANAGER --> CHANNEL_STATE
    CHANNEL_MANAGER -->|启动/停止| WA_SVC
    CHANNEL_MANAGER -->|启动/停止| TG_SVC
    CHANNEL_MANAGER -->|启动/停止| DC_SVC

    RLGA_EVENTS -.->|广播| WS_HANDLER
    HEARTBEAT -.->|广播| WS_HANDLER
    DIAGNOSTICS -.->|广播| WS_HANDLER

    CONFIG_RELOAD -.->|通知| CORE_HANDLERS
    CONFIG_RELOAD -.->|通知| CHANNEL_MANAGER

    CRON_SCHEDULER -.->|触发| EVENT_EMITTER
    CRON_SCHEDULER -.->|触发| CANVAS_HOST

    subgraph "外部服务 External Services"
        WA_SVC[WhatsApp Service]
        TG_SVC[Telegram Service]
        DC_SVC[Discord Service]
    end

    style GatewayServer fill:#e1f5fe
    style WebSocket层 fill:#e3f2fd
    style MethodLayer fill:#bbdefb
    style StateLayer fill:#90caf9
    style EventLayer fill:#64b5f6
    style ResourceLayer fill:#42a5f5
    style ExternalServices fill:#ffecb3
```

---

## 3. 消息流转图 Message Flow

```mermaid
sequenceDiagram
    participant USER as 用户
    participant CH as 通道通道<br/>WhatsApp/Telegram/etc
    participant GATEWAY as Gateway
    participant ROUTER as Message Router
    participant AGENT as Agent Runtime
    participant PROVIDER as AI Provider
    participant TOOLS as Tools

    %% 入站消息流
    USER->>CH: 发送消息
    CH->>GATEWAY: 接入事件
    GATEWAY->>ROUTER: 解析路由<br/>(channel/account/peer)
    ROUTER-->>GATEWAY: 返回匹配结果<br/>(agentId, sessionKey)
    GATEWAY->>AGENT: 调用 agent.execute

    AGENT->>AGENT: 加载会话历史
    AGENT->>AGENT: 构建系统提示
    AGENT->>PROVIDER: 发起 LLM 调用

    alt 需要工具调用
        PROVIDER-->>AGENT: 返回 tool_calls
        AGENT->>TOOLS: 执行工具
        TOOLS-->>AGENT: 返回工具结果
        AGENT->>PROVIDER: 继续调用 (with tool results)
    end

    PROVIDER-->>AGENT: 返回完整响应
    AGENT->>AGENT: 更新会话历史
    AGENT-->>GATEWAY: 返回响应 (events: agent)

    GATEWAY->>CH: 发送消息 (channel.message.send)
    CH->>USER: 接收回复

    %% 出站消息流 (CLI/Web/App 触发)
    rect rgb(255, 255, 200)
        Note over GATEWAY,USER: 出站消息流 (从客户端触发)
        USER->>GATEWAY: 调用 gateway.send
        GATEWAY->>ROUTER: 解析路由
        ROUTER-->>GATEWAY: 返回匹配结果
        GATEWAY->>CH: 发送消息
        CH->>USER: 接收消息
    end
```

---

## 4. 插件系统架构 Plugin System

```mermaid
graph TB
    subgraph "插件 API Plugin SDK"
        API[OpenClawPluginApi]
    end

    subgraph "插件运行时 Plugin Runtime"
        RUNTIME[Plugin Runtime]
        CONFIG_API[Config API<br/>loadConfig/writeConfigFile]
        SYSTEM_API[System API<br/>enqueueSystemEvent]
        MEDIA_API[Media API<br/>loadWebMedia/detectMime]
        TTS_API[TTS API<br/>textToSpeechTelephony]
        TOOLS_API[Tools API<br/>createMemoryGetTool]
        CHANNEL_API[Channel API<br/>routing/network/session]
        LOGGING_API[Logging API<br/>getChildLogger]
    end

    subgraph "注册接口 Registrations"
        REG_TOOL[registerTool]
        REG_HOOK[registerHook]
        REG_HTTP[registerHttpRoute/registerHttpHandler]
        REG_CHANNEL[registerChannel]
        REG_GW_METHOD[registerGatewayMethod]
        REG_CLI[registerCli]
        REG_SERVICE[registerService]
        REG_PROVIDER[registerProvider]
        REG_CMD[registerCommand]
    end

    subgraph "钩子系统 Hook System"
        H_BEFORE_AGENT[before_agent_start]
        H_AFTER_AGENT[after_agent_start]
        H_BEFORE_SEND[before_message_send]
        H_AFTER_SEND[after_message_send]
        H_RECEIVED[message_received]
        H_TOOL[tool_called]
        H_CONFIG[config_changed]
    end

    subgraph "插件类型 Plugin Types"
        P_CHANNEL[Channel Plugin<br/>must implement ChannelPlugin]
        P_MEMORY[Memory Plugin<br/>LanceDB/etc]
        P_PROVIDER[Provider Plugin<br/>Custom AI API]
    end

    subgraph "插件生命周期 Plugin Lifecycle"
        LOAD[loadPlugin]
        VALIDATE[validateConfig]
        REGISTER[register]
        ACTIVATE[activate]
        DISPOSE[dispose]
    end

    %% 连接关系
    API --> RUNTIME
    RUNTIME --> CONFIG_API
    RUNTIME --> SYSTEM_API
    RUNTIME --> MEDIA_API
    RUNTIME --> TTS_API
    RUNTIME --> TOOLS_API
    RUNTIME --> CHANNEL_API
    RUNTIME --> LOGGING_API

    API --> REG_TOOL
    API --> REG_HOOK
    API --> REG_HTTP
    API --> REG_CHANNEL
    API --> REG_GW_METHOD
    API --> REG_CLI
    API --> REG_SERVICE
    API --> REG_PROVIDER
    API --> REG_CMD

    REG_HOOK --> H_BEFORE_AGENT
    REG_HOOK --> H_AFTER_AGENT
    REG_HOOK --> H_BEFORE_SEND
    REG_HOOK --> H_AFTER_SEND
    REG_HOOK --> H_RECEIVED
    REG_HOOK --> H_TOOL
    REG_HOOK --> H_CONFIG

    REG_CHANNEL --> P_CHANNEL

    LOAD --> VALIDATE
    VALIDATE --> REGISTER
    REGISTER --> ACTIVATE
    ACTIVATE --> DISPOSE

    P_CHANNEL -.->|loose coupling| H_RECEIVED
    P_CHANNEL -.->|loose coupling| H_BEFORE_SEND

    style PluginSDK fill:#fff9c4
    style PluginRuntime fill:#fff59d
    style Registrations fill:#ffee58
    style HookSystem fill:#fdd835
    style PluginTypes fill:#fbc02d
    style PluginLifecycle fill:#f9a825
```

---

## 5. 路与绑定系统 Routing & Bindings

```mermaid
graph TD
    subgraph "路由输入 Route Input"
        CFG[User Config<br/>bindings 数组]
        IN_CHANNEL[channel<br/>消息来源]
        IN_ACCOUNT[accountId<br/>账户 ID]
        IN_PEER[peer<br/>用户/组 ID]
        IN_GUILD[guildId<br/>Discord 服务器]
        IN_TEAM[teamId<br/>Slack/Teams]
    end

    subgraph "路由匹配优先级 Matching Priority"
        P1[1. peer<br/>具体用户/组]
        P2[2. peer.parent<br/>线程继承]
        P3[3. guildId<br/>Discord 服务器]
        P4[4. teamId<br/>Slack/Teams]
        P5[5. account<br/>非通配符账户]
        P6[6. account<br/>通配符账户]
        P7[7. default<br/>默认绑定]
    end

    subgraph "路由输出 Route Output"
        AGENT_ID[agentId<br/>目标 Agent]
        SESSION_KEY[sessionKey<br/>会话唯一标识]
        MAIN_KEY[mainSessionKey<br/>主会话]
        MATCHED_BY[matchedBy<br/>匹配方式]
    end

    subgraph "会话管理 Session Management"
        SESSION_STORE[Session Store<br/>~/.openclaw/sessions/]
        SESSION_FILE[.jsonl 文件<br/>role/content/timestamp]
        HISTORY[上下文历史<br/>消息 turnover]
    end

    %% 连接关系
    CFG -->|解析| P1
    IN_CHANNEL -->|输入| P1
    IN_ACCOUNT -->|输入| P1
    IN_PEER -->|输入| P1
    IN_GUILD -->|输入| P1
    IN_TEAM -->|输入| P1

    P1 -->|无匹配| P2
    P2 -->|无匹配| P3
    P3 -->|无匹配| P4
    P4 -->|无匹配| P5
    P5 -->|无匹配| P6
    P6 -->|无匹配| P7

    P1 -->|匹配| AGENT_ID
    P2 -->|匹配| AGENT_ID
    P3 -->|匹配| AGENT_ID
    P4 -->|匹配| AGENT_ID
    P5 -->|匹配| AGENT_ID
    P6 -->|匹配| AGENT_ID
    P7 -->|匹配| AGENT_ID

    AGENT_ID -->|构建| SESSION_KEY
    AGENT_ID -->|构建| MAIN_KEY
    P1 -->|设置| MATCHED_BY
    P2 -->|设置| MATCHED_BY
    P3 -->|设置| MATCHED_BY
    P4 -->|设置| MATCHED_BY
    P5 -->|设置| MATCHED_BY
    P6 -->|设置| MATCHED_BY
    P7 -->|设置| MATCHED_BY

    SESSION_KEY -->|读写| SESSION_STORE
    MAIN_KEY -->|读写| SESSION_STORE

    SESSION_STORE -->|包含| SESSION_FILE
    SESSION_FILE -->|构建| HISTORY

    style RouteInput fill:#e8f5e9
    style MatchingPriority fill:#c8e6c9
    style RouteOutput fill:#a5d6a7
    style SessionManagement fill:#81c784
```

---

## 6. 媒体管道架构 Media Pipeline

```mermaid
graph LR
    subgraph "入站 Inbound"
        A[收到媒体] --> B[parse<br/>提取媒体]
        B --> C[mime.ts<br/>检测 MIME]
        C -->|magic number<br/>+ content type| MIME_TYPE{MIME 类型?}
        MIME_TYPE -->|image| D[store.ts<br/>保存到磁盘]
        MIME_TYPE -->|audio| D
        MIME_TYPE -->|video| D
        MIME_TYPE -->|unknown| DROP[丢弃/警告]
    end

    subgraph "存储 Storage"
        D --> STORAGE[~/.openclaw/media/inbound/]
        STORAGE --> FILES["{original}---{uuid}.ext"]
    end

    subgraph "处理 Processing (可选)"
        FILES --> E[image_ops.ts<br/>image/image-ops.ts]
        E -->|resizeToJpeg| RESIZED[调整大小的 JPEG]
    end

    subgraph "出站 Outbound"
        OUT_REQ[出站请求] --> OUT_MIME[mime.ts<br/>检测 MIME]
        OUT_MIME -->|需要处理?| OUT_PROC[image_ops/audio.ts]
        OUT_MIME -->|不需要处理| OUT_STORE[store.ts<br/>保存到磁盘]
        OUT_PROC --> OUT_STORE
        OUT_STORE --> OUT_STORAGE[~/.openclaw/media/outbound/]
    end

    subgraph "服务服务 & Fetch"
        STORAGE --> HOST[host.ts<br/>HTTP 服务]
        OUT_STORAGE --> HOST
        HOST -->|GET /media/*| CLIENT[客户端]
        FETCH[fetch.ts<br/>远程获取] --> STORAGE
    end

    style Inbound fill:#e3f2fd
    style Storage fill:#bbdefb
    style Processing fill:#90caf9
    style Outbound fill:#64b5f6
    style ServeFetch fill:#42a5f5
```

---

## 7. Gateway 通信协议 Gateway Protocol

```mermaid
stateDiagram-v2
    direction LR

    %% 定义带有复杂描述的状态名（规避连线上的解析Bug）
    state "Authenticated (已认证)" as Authenticated
    state "Connected (已就绪)" as Connected
    state "Requesting (请求中)" as Requesting
    state "Streaming (流式传输中)" as Streaming
    state "Waiting (异步等待中)" as Waiting
    state "Error (发生错误)" as Error
    state "Closed (连接关闭)" as Closed

    [*] --> Disconnected

    note right of Disconnected
        未连接状态
    end note

    Disconnected --> Connecting: 客户端发起WS连接

    %% 连线描述尽量保持简洁，避开特殊字符
    Connecting --> Authenticated: req_connect_auth_ok
    Connecting --> Closed: 认证失败
    Connecting --> Closed: 非首帧为connect

    Authenticated --> Connected: res_hello_ok

    Connected --> Requesting: req_method
    Connected --> Streaming: event_stream

    Requesting --> Connected: res_ok_sync
    Requesting --> Waiting: method_processing

    Waiting --> Connected: res_ok
    Waiting --> Error: res_error

    Streaming --> Connected: stream_end
    Streaming --> Streaming: stream_continue

    Connected --> Closed: 客户端断开
    Error --> Connected: error_recovery
    Authenticated --> Closed: connection_close
    Closed --> [*]

    note right of Streaming
        agent 事件流示例:
        {
          "type": "event",
          "event": "agent",
          "payload": {
            "agentId": "xxx",
            "runId": "yyy",
            "status": "running"
          }
        }
    end note

    note right of Requesting
        request 示例:
        {
          "type": "req",
          "id": 1,
          "method": "send",
          "params": {
            "channel": "whatsapp",
            "target": "...",
            "text": "..."
          }
        }
    end note
```

---

## 8. 认证与配对流程 Authentication & Pairing

```mermaid
sequenceDiagram
    participant DEV as 设备(Device)<br/>CLI/App/Node
    participant WS as Gateway<br/>WebSocket Server
    participant AUTH as Auth Module
    participant PAIRING as Pairing Store
    participant USER as 操作员

    %% 首次连接 - 本地
    rect rgb(200, 255, 200)
        Note over DEV,USER: 场景：首次本地连接 (自动批准)
        DEV->>WS: WS connect
        WS->>AUTH: 生成 deviceIdentity
        AUTH-->>WS: deviceIdentity (含 deviceID)
        WS-->>DEV: res:connect + deviceIdentity
        DEV->>WS: req:connect (带 deviceID)
        WS->>AUTH: 验证 deviceID 是否本地
        AUTH->>PAIRING: 检查 pairing 状态
        PAIRING-->>AUTH: 新设备 (需要批准)
        AUTH->>AUTH: 本地地址 -> 自动批准
        AUTH->>PAIRING: 生成 deviceToken
        AUTH-->>WS: 设备已批准
        WS-->>DEV: res:hello-ok (带 deviceToken)
    end

    %% 首次连接 - 远程
    rect rgb(255, 200, 200)
        Note over DEV,USER: 场景：首次远程连接 (需要批准)
        DEV->>WS: WS connect (via Tailscale/VPN)
        WS->>AUTH: 生成 deviceIdentity (带 challenge)
        AUTH-->>WS: deviceIdentity + challenge
        WS-->>DEV: res:connect + deviceIdentity + challenge
        DEV->>DEV: 签名 challenge
        DEV->>WS: req:connect (带 deviceID + signature)
        WS->>AUTH: 验证签名
        AUTH->>PAIRING: 检查 pairing 状态
        PAIRING-->>AUTH: 新设备，非本地
        AUTH-->>USER: 通知等待批准
        USER-->>AUTH: 批准设备
        AUTH->>PAIRING: 生成并保存 deviceToken
        AUTH-->>WS: 设备已批准
        WS-->>DEV: res:hello-ok (带 deviceToken)
    end

    %% 后续连接
    rect rgb(200, 200, 255)
        Note over DEV,USER: 场景：后续连接
        DEV->>WS: WS connect
        DEV->>WS: req:connect (带 deviceID + deviceToken)
        WS->>PAIRING: 验证 deviceToken
        PAIRING-->>WS: Token 有效
        WS-->>DEV: res:hello-ok
    end
```

---

## 9. 完整组件关系图 Component Relationships

```mermaid
graph TB
    %% CLI 层
    CLI[openclaw CLI<br/>openclaw.mjs]
    PROG[src/index.ts<br/>buildProgram]
    CMDS[src/commands/]

    CLI --> PROG
    PROG --> CMD_DEPS[createDefaultDeps]

    %% Gateway 层
    GW_SERVER[src/gateway/server.impl.ts<br/>startGatewayServer]
    GW_PROT[src/gateway/protocol/]
    GW_METHODS[src/gateway/server-methods/]
    GW_CHAN[src/gateway/server-channels.ts]

    GW_SERVER --> GW_PROT
    GW_SERVER --> GW_METHODS
    GW_SERVER --> GW_CHAN

    %% 通道层
    CHAN_SYS[src/channels/]
    PLUG_TYPES[src/channels/plugins/types.plugin.ts]
    PLUG_ADAPTER[src/channels/plugins/types.adapters.ts]

    WHAST[whatsapp.ts]
    TELEG[telegram.ts]
    DISC[discord.ts]
    SLACK[slack.ts]
    SIGNL[signal.ts]
    IMMSG[imessage.ts]

    CHAN_SYS --> PLUG_TYPES
    CHAN_SYS --> PLUG_ADAPTER
    CHAN_SYS --> WA
    CHAN_SYS --> TG
    CHAN_SYS --> DC
    CHAN_SYS --> SL
    CHAN_SYS --> SI
    CHAN_SYS --> IM

    GW_CHAN --> CHAN_SYS

    %% Agent 层
    AGENT_RT[src/agents/runtime.ts]
    AGENT_TOOLS[src/agents/tools/]
    ROUTER[src/routing/resolve-route.ts]

    ROUTER --> AGENT_RT
    AGENT_RT --> AGENT_TOOLS
    GW_METHODS --> ROUTER

    %% 配置层
    CONFIG[src/config/]
    ZOD_TYPES[src/config/zod-schema.*.ts]

    CONFIG --> ZOD_TYPES
    GW_SERVER --> CONFIG
    ROUTER --> CONFIG

    %% 媒体层
    MEDIA[src/media/]
    MIME[mime.ts]
    STORE[store.ts]
    FETCH[fetch.ts]

    MEDIA --> MIME
    MEDIA --> STORE
    MEDIA --> FETCH
    GW_METHODS --> MEDIA

    %% 插件层
    PLUG_SYS[src/plugins/]
    PLUG_SDK[src/plugin-sdk/]

    PLUG_SYS --> PLUG_SDK
    GW_SERVER --> PLUG_SYS

    %% 钩子
    HOOKS[src/hooks/types.ts]

    HOOKS --> AGENT_RT
    PLUG_SDK --> HOOKS

    %% 基础设施
    INFRA[src/infra/]
    PORTS[ports.ts]
    LOGG[logging/]

    INFRA --> PORTS
    INFRA --> LOGG
    GW_SERVER --> INFRA

    style CLI fill:#e1f5fe
    style GatewayServer fill:#bbdefb
    style ChannelLayer fill:#90caf9
    style AgentLayer fill:#64b5f6
    style ConfigLayer fill:#42a5f5
    style MediaLayer fill:#1e88e5
    style PluginLayer fill:#0d47a1
```

---

## 附录：组件职责

| 组件               | 职责                                           |
| ------------------ | ---------------------------------------------- |
| **CLI**            | 命令行界面，启动 gateway、发送消息、配置管理等 |
| **Gateway**        | WebSocket 服务器，协议验证，事件广播，通道管理 |
| **Channels**       | 消息平台适配器，入站/出站消息，状态管理        |
| **Routing**        | 消息路由解析，绑定匹配，会话键构建             |
| **Agent Runtime**  | AI Agent 执行，工具调用，会话管理              |
| **Media Pipeline** | 媒体上传、存储、处理、服务                     |
| **Config System**  | 配置加载、验证、迁移、监听                     |
| **Plugin SDK**     | 插件开发接口，运行时 API                       |
| **Hooks**          | 生命周期钩子，插件扩展点                       |
| **Infrastructure** | 端口管理、日志、诊断事件、SSRF 防护            |

---

**文档结束**