agentic_huge_data_base / wiki
页面 jcode · 2.4 客户端-服务端协议·DeepWiki 中文全文译文
DeepWiki 中文译文 / jcode / 2.4

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

代理式研究运行时 · 聚焦本章的模块关系、源码依据与实现要点。

项目jcode 章节2.4 状态全文译文 模块接口与服务契约、界面与交互、系统架构、智能体运行时
项目要点页2.5 参考项目 项目章节目录jcode DeepWiki 原始章节Client-Server Protocol 上一章2.3 下一章3
源码线索
  • 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
模块标签
  • 接口与服务契约
  • 界面与交互
  • 系统架构
  • 智能体运行时
  • 记忆与上下文

章节正文

客户端-服务端协议

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

客户端-服务器协议

相关源文件

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

  • 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（服务器端）之间的交互。

图：协议消息交换

jcode · 请求-响应流程 · 图 1
jcode · 请求-响应流程 · 图 1

来源：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 协议之间的桥梁。

图：网关中继逻辑

jcode · 网关架构 · 图 2
jcode · 网关架构 · 图 2

来源：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