2.4 · 客户端-服务端协议（Client-Server Protocol）

客户端-服务端协议（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/1jehuang/jcode/2.4-client-server-protocol

翻译时间：2026-05-27T08:45:23.601Z

翻译模型：deepseek-chat

原文字符数：9603

项目：jcode (jcode)

---

客户端-服务器协议

相关源文件

以下文件为本维基页面的生成提供了上下文：

• crates/jcode-protocol/src/lib.rs
• crates/jcode-protocol/src/protocol_tests/core_events.rs
• crates/jcode-protocol/src/wire.rs
• ios/Sources/JCodeKit/Connection.swift
• ios/Sources/JCodeKit/CredentialStore.swift
• ios/Sources/JCodeKit/JCodeClient.swift
• ios/Sources/JCodeKit/Protocol.swift
• ios/Tests/JCodeKitTests/ClientTests.swift
• ios/Tests/JCodeKitTests/ProtocolTests.swift
• src/gateway.rs
• src/gateway/auth.rs
• src/gateway/registry.rs
• src/protocol_tests.rs
• src/server/client_actions.rs
• src/server/client_comm.rs
• src/server/client_lifecycle.rs
• src/server/client_session.rs
• src/server/client_state.rs
• src/server/comm_control.rs
• src/server/comm_session.rs
• src/server/comm_sync.rs
• src/server/swarm.rs
• src/tool/communicate.rs
• src/tui/app/tests/remote_events_reload_01/part_02.rs
• src/tui/app/tests/scroll_copy_01/part_01.rs
• src/tui/app/tests/state_model_poke_01/part_01.rs
• src/tui/app/tests_input_scroll.rs
• src/tui/backend.rs

jcode 系统采用单服务器、多客户端架构。该协议设计为轻量级、异步且面向流的，允许多个 TUI、iOS 或 Web 客户端连接到同一个代理会话。通信主要通过 Unix 域套接字或 WebSocket 使用换行符分隔的 JSON（NDJSON）进行。

1. 协议概述

该协议包含两种主要消息类型：Request（客户端到服务器）和 ServerEvent（服务器到客户端）。

• 传输层： Unix 域套接字（主/调试）或 WebSocket（网关）crates/jcode-protocol/src/lib.rs:3-8。
• 序列化： JSON，每条消息为一行，后跟换行符 crates/jcode-protocol/src/lib.rs:3-4。
• 异步性： 在长时间运行的大语言模型（LLM）生成或工具执行期间，服务器会向客户端流式推送 ServerEvent 变体 crates/jcode-protocol/src/lib.rs:4-5。

请求-响应流程

下图展示了 RemoteConnection（客户端）与 Server（服务器端）之间的交互。

图：协议消息交换

sequenceDiagram
    participant C as "RemoteConnection [src/tui/backend.rs]"
    participant S as "Server (handle_client) [src/server.rs]"
    participant A as "Agent (run_turn) [src/agent.rs]"

    C->>S: "Request::Subscribe { id, working_dir }"
    S-->>C: "ServerEvent::SessionId(id)"

    C->>S: "Request::Message { id, content }"
    S->>A: "process_message_streaming_mpsc()"

    loop "流式处理轮次"
        A-->>S: "ServerEvent::TextDelta(delta)"
        S-->>C: "ServerEvent::TextDelta(delta)"

        A-->>S: "ServerEvent::ToolStart { id, name }"
        S-->>C: "ServerEvent::ToolStart { id, name }"

        A-->>S: "ServerEvent::ToolDone { id, name, output }"
        S-->>C: "ServerEvent::ToolDone { id, name, output }"
    end

    A-->>S: "轮次完成"
    S-->>C: "ServerEvent::Done { id }"

来源：crates/jcode-protocol/src/lib.rs:67-230, src/server/client_lifecycle.rs:153-161, src/tui/backend.rs:226-261, src/server/client_actions.rs:123-132

---

2. 请求模式

Request 枚举定义了客户端可以执行的所有操作。每个请求都包含一个唯一的 id（u64），客户端使用该 ID 来跟踪响应和取消操作 crates/jcode-protocol/src/lib.rs:21-21, src/tool/communicate.rs:21-21。

关键请求变体

变体	用途	关键字段
Message	向代理发送用户输入。	content, images, system_reminder
Cancel	中止当前的生成/工具循环。	id（与原始消息 ID 匹配）
SoftInterrupt	在下一个"安全点"注入消息，而不停止当前工具。	content, urgent
Subscribe	将客户端连接到服务器并设置上下文。	working_dir, selfdev, target_session_id
GetHistory	请求会话记录的全量同步。	id
ResumeSession	将客户端切换到指定的会话 ID。	session_id
Comm* 变体	集群和多代理协调命令。	session_id, target_session, plan
InputShell	通过 !cmd 语法执行 shell 命令。	command

来源：crates/jcode-protocol/src/lib.rs:161-161, src/server/client_lifecycle.rs:127-144, src/server/client_actions.rs:221-226

---

3. ServerEvent 模式

ServerEvent 枚举是服务器推送的数据流。它提供关于大语言模型（LLM）"思考"、文本生成和工具活动的实时更新。

消息同步与历史记录

当客户端连接或请求历史记录时，服务器会发送一系列 HistoryMessage 对象。

• HistoryMessage：包含 role、content 以及可选的 tool_calls 或 tool_data crates/jcode-protocol/src/lib.rs:51-58。
• tool_data：使用 ToolCall 结构体提供关于工具执行和输出的结构化详细信息 crates/jcode-protocol/src/lib.rs:57-57。
• History 事件：包含消息、提供者元数据和会话列表的批量更新 src/server/client_state.rs:164-196。

流式事件

• TextDelta(String)：来自助手的增量文本 src/tui/backend.rs:130-130。
• ToolStart / ToolInput / ToolExec / ToolDone：工具执行的细粒度生命周期，允许 TUI 在生成时显示部分工具参数 src/tui/backend.rs:133-155。
• TokenUsage：关于输入/输出 Token 和缓存命中的实时更新 src/tui/backend.rs:158-163。
• Compaction：通知客户端服务器已压缩历史记录以节省 Token src/server/client_lifecycle.rs:163-175。

来源：crates/jcode-protocol/src/lib.rs:51-58, src/tui/backend.rs:128-197, src/server/client_state.rs:164-196

---

4. 中断机制

jcode 实现了协议中反映的两级中断系统：

1. 硬取消（Request::Cancel）：立即停止代理循环。通过丢弃任务或通过 InterruptSignal 发出信号来处理 src/server/client_lifecycle.rs:128-128, src/server/client_session.rs:20-20。
2. 软中断（Request::SoftInterrupt）：消息被添加到 SoftInterruptQueue src/server/client_lifecycle.rs:55-55。代理在定义的"安全点"（例如，工具调用之间）检查此队列，并将用户的反馈注入到上下文中，而不会丢失进度 src/server/client_actions.rs:199-208。
3. 重载中断：使用诸如 [generation interrupted - server reloading] 之类的特殊标记来指示会话应在服务器重启后自动恢复 src/server/client_session.rs:31-51。

来源：src/server/client_lifecycle.rs:127-144, src/server/client_actions.rs:196-208, src/server/client_session.rs:31-96

---

5. WebSocket 网关与 iOS 集成

对于 iOS 和 Web 客户端，服务器提供了一个 WebSocket 网关（默认端口 7643）src/gateway.rs:34-36。

网关架构

网关充当 TCP/WebSocket 与内部 NDJSON 协议之间的桥梁。

图：网关中继逻辑

graph LR
    subgraph ClientSpace ["客户端空间"]
        iOS["📱 iOS 应用 (JCodeKit)"]
        Web["🌐 Web 客户端"]
    end

    subgraph GatewayCrate ["src/gateway.rs"]
        WS["🌐 TCP :7643 (WebSocket)"]
        Relay["🔄 relay_websocket_to_unix()"]
    end

    subgraph ServerCore ["src/server/client_lifecycle.rs"]
        HC["⚙️ handle_client()"]
        Pair["🔌 UnixStream::pair()"]
    end

    iOS <-->|WebSocket 帧| WS
    Web <-->|WebSocket 帧| WS
    WS <--> Relay
    Relay <-->|NDJSON| Pair
    Pair <--> HC

来源：src/gateway.rs:8-13, src/gateway.rs:125-132, src/server/client_lifecycle.rs:49-61

iOS 客户端（JCodeKit）

iOS 应用使用 JCodeKit Swift SDK 与服务器交互。

• JCodeClient：管理连接并将 ServerEvent JSON 映射到 Swift 类型 ios/Sources/JCodeKit/JCodeClient.swift:1-20。
• Connection：处理底层 WebSocket 生命周期和通过二维码进行配对 ios/Sources/JCodeKit/Connection.swift:1-15。
• 凭证存储：安全地持久化会话令牌和服务器地址 ios/Sources/JCodeKit/CredentialStore.swift:1-10。

来源：ios/Sources/JCodeKit/JCodeClient.swift, ios/Sources/JCodeKit/Connection.swift, ios/Sources/JCodeKit/Protocol.swift