/agent/1/chat接口请求流程

架构： 

snail-ai-server和 snail-ai-agent-example 的核心关系：Server-Client 架构，两个独立进程通过 gRPC 通信

整个系统分为 两个独立部署的服务：

完整调用链路：

用户请求
  │
  ▼
┌──────────────────────────────────────────────────────────────────┐
│  snail-ai-starter (Server, 端口 8900)                             │
│                                                                    │
│  POST /snail-ai/agent/1/chat  (AgentController)                   │
│       │                                                            │
│       ▼                                                            │
│  AgentChatService.chat()                                           │
│       │                                                            │
│       ▼                                                            │
│  AgentChatChainService.proceed()  ← 责任链                         │
│       │                                                            │
│       ├─ Order 10: InitContextHandler      (加载 Agent 信息)       │
│       ├─ Order 20: ConversationHandler     (创建/复用会话)         │
│       ├─ Order 30: ModelResolveHandler     (解析模型配置)          │
│       ├─ Order 40: McpHandler              (加载 MCP 服务)         │
│       ├─ Order 50: AttachmentResolveHandler(解析附件)              │
│       ├─ Order 60: RagHandler              (RAG 检索)              │
│       ├─ Order 70: SkillAgentChatHandler   (加载技能)              │
│       ├─ Order 75: ContextCollectorHandler (选目标Client+历史消息) │
│       └─ Order 80: LlmCallHandler          (gRPC 分发) ────────┐  │
└────────────────────────────────────────────────────────────────┤  │
                                                                  │  │
                    gRPC Server Streaming                         │  │
                  (UriConstants.CHAT_DISPATCH)                    │  │
                                                                  │  │
────────────────────────────────────────────────────────────────  │
│  snail-ai-agent-example (Client, gRPC 端口 18889)               │  │
│                                                                  │  │
│  ClientGrpcServer 接收 gRPC 请求                                 │  │
│       │                                                          │  │
│       ▼                                                          │  │
│  ChatDispatchStreamingHandler                                    │  │
│       │                                                          │  │
│       ▼                                                          │  │
│  ChatSessionRuntime → ClientChatExecutor                         │  │
│       │                                                          │  │
│       ▼                                                          │  │
│  构建 Prompt + 调用 ChatClient (LLM 模型)                         │  │
│       │                                                          │  │
│       ▼                                                          │  │
│  流式返回 text/thinking/completion chunks  ──────────────────────  │
│                                                                    │
│  同时回调 Server 保存会话和消息记录                                 │
└────────────────────────────────────────────────────────────────────┘

关键代码对应

1. Server 端发起 gRPC 调用 (LlmCallHandler.java 第 74 行)：

GrpcChannelUtil.sendServerStreaming(
    ctx.getTargetClient().getChannel(),  // Client 的 gRPC 连接
    UriConstants.CHAT_DISPATCH,           // URI: "/chat/dispatch"
    dispatchBody,                         // 序列化后的 ChatDispatchRequest
    Map.of(),
    new ChatStreamObserver(...));         // 接收流式响应的观察者

2. Client 端接收并处理 (ChatDispatchStreamingHandler.java)：

public boolean supports(String uri) {
    return UriConstants.CHAT_DISPATCH.equals(uri);  // 匹配 "/chat/dispatch"
}

3. Client 如何注册到 Server：
Client 启动后通过 ClientHeartbeatScheduler 向 Server 的 gRPC 端口 (18888) 发送心跳
Server 的 ClientInstanceManager 记录存活的 Client 实例（IP + gRPC 端口）
ContextCollectorHandler (Order 75) 根据 Agent 的 appId 找到对应的 Client 实例
LlmCallHandler (Order 80) 将请求通过 gRPC 发送给该 Client

 

一句话总结：/snail-ai/agent/1/chat 是 Server 端的 HTTP 入口，它不直接调用 LLM，而是通过责任链完成前置准备后，用 gRPC 把请求转发给 snail-ai-agent-example（Client 端），由 Client 真正调用大模型并流式返回结果。 这种 Server-Client 分离架构的好处是：LLM 调用可以水平扩展（部署多个 Client 实例），Server 专注于业务编排和数据管理。