agentic_huge_data_base / wiki
页面 jcode · 2 核心架构·DeepWiki 中文全文译文
DeepWiki 中文译文 / jcode / 2

2 · 核心架构（Core Architecture）

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

项目jcode 章节2 状态全文译文 模块系统架构、接口与服务契约、界面与交互、智能体运行时
项目要点页2.5 参考项目 项目章节目录jcode DeepWiki 原始章节Core Architecture 上一章1.2 下一章2.1
源码线索
  • crates/jcode-message-types/src/lib.rs
  • docs/SERVER_ARCHITECTURE.md
  • docs/SERVER_SERVICE_SPLIT_PLAN.md
  • docs/UNIFIED_SELFDEV_SERVER_PLAN.md
  • docs/WINDOWS.md
  • src/agent.rs
  • src/agent/turn_loops.rs
  • src/agent/turn_streaming_broadcast.rs
  • src/agent/turn_streaming_mpsc.rs
  • src/main.rs
模块标签
  • 系统架构
  • 接口与服务契约
  • 界面与交互
  • 智能体运行时
  • 工作流与编排

章节正文

核心架构

原始 DeepWiki 页面https://deepwiki.com/1jehuang/jcode/2-core-architecture

核心架构

相关源文件

本章引用的主要源码文件：

  • crates/jcode-message-types/src/lib.rs
  • docs/SERVER_ARCHITECTURE.md
  • docs/SERVER_SERVICE_SPLIT_PLAN.md
  • docs/UNIFIED_SELFDEV_SERVER_PLAN.md
  • docs/WINDOWS.md
  • src/agent.rs
  • src/agent/turn_loops.rs
  • src/agent/turn_streaming_broadcast.rs
  • src/agent/turn_streaming_mpsc.rs
  • src/main.rs
  • src/message/tests.rs
  • src/platform.rs
  • src/protocol.rs
  • src/provider/gemini_tests.rs
  • src/provider/openai/stream.rs
  • src/provider/openai_tests/parsing_tools.rs
  • src/provider/openrouter_sse_stream.rs
  • src/registry.rs
  • src/server.rs
  • src/session.rs
  • src/transport/windows.rs

jcode 系统构建于高性能的单服务器多客户端架构之上，专为长时间运行的代理工作流而设计。它将繁重的处理任务（大语言模型交互、工具执行和会话状态）与用户界面分离，允许多个 TUI 客户端、Web 网关或后台进程与同一代理会话进行交互。

系统总览

该架构以中央 Server 为核心，它管理着一个 Agent 实例的注册表。每个 Agent 代表一个独特的对话会话，拥有自己的历史记录、工具注册表和记忆上下文。

关键架构组件
  • 服务器/客户端分离：后台守护进程管理所有状态。客户端（TUI、CLI 或 iOS）通过 Unix 域套接字（或 Windows 命名管道）使用类似 JSON-RPC 的协议进行连接。
  • 代理运行时：一个状态机，负责处理"轮次"生命周期，包括提示词构建、大语言模型流式传输和工具执行循环。
  • 工具注册表：一个模块化系统，用于注册内置工具（文件 I/O、搜索）、MCP（模型上下文协议）工具和会话特定的"技能"。
  • 提供者抽象层：一个统一接口，支持多个大语言模型后端（Anthropic、OpenAI、OpenRouter 等），并具备故障切换和成本跟踪功能。
结构图：系统连接

下图展示了用户的自然语言请求如何流经系统，最终转化为代码实体和工具执行。

自然语言到代码实体的映射

jcode · 结构图：系统连接 · 图 1
jcode · 结构图：系统连接 · 图 1

来源：src/server.rs:96-96, src/agent.rs:139-184, src/protocol.rs:1-2, src/agent/turn_streaming_broadcast.rs:4-7

2.1 服务器与客户端生命周期

服务器生命周期由 ServerRuntime src/server.rs:52-52 管理，它通过平台特定的 Listener src/transport/windows.rs:36-39 处理传入连接。服务器维护一个活动会话的注册表，并处理客户端的连接。系统支持通过 exec src/server.rs:33-35 进行"热重载"，即新二进制文件可以接管现有套接字，确保零停机更新和跨重启的会话持久化。

详情请参见服务器与客户端生命周期。

来源： src/server.rs:31-42, src/transport/windows.rs:42-81, src/session.rs:64-155

2.2 代理运行时

Agent 结构体 src/agent.rs:139-184 是核心执行单元。当处理消息时，代理会进入 run_turn 状态机（实现为 run_turn_streaming src/agent/turn_streaming_broadcast.rs:4-7 或 run_turn_streaming_mpsc src/agent/turn_streaming_mpsc.rs:4-7）。此循环负责上下文修复 src/agent/turn_streaming_mpsc.rs:14-14，通过压缩管理 Token 预算 src/agent/turn_streaming_mpsc.rs:22-45，并协调 Provider 进行推理和 Registry 执行工具。它还管理一个 SoftInterruptQueue src/agent.rs:167 用于带外通信。

详情请参见代理运行时。

来源： src/agent.rs:139-184, src/agent/turn_streaming_mpsc.rs:13-45, src/agent/turn_streaming_broadcast.rs:13-45

2.3 工具注册表与内置工具

Registry src/agent.rs:141 管理一个实现 Tool 特质的工具集合。这包括原生工具，如 selfdev 和 communicate src/agent.rs:57，以及通过模型上下文协议（MCP）加载的动态工具。工具在 ToolContext 内执行，该上下文提供对文件系统和会话状态的访问，同时强制执行安全边界。

详情请参见工具注册表与内置工具。

来源： src/agent.rs:40-40, src/agent.rs:57-57, crates/jcode-message-types/src/lib.rs:15-22

2.4 客户端-服务器协议

该协议使用换行符分隔的 JSON 消息。客户端发送 Request 变体（例如 Message、Cancel 或 SoftInterrupt），服务器以 ServerEvent 变体 src/protocol.rs:1-2 响应，包括 TextDelta、ToolStart 和 TokenUsage。该协议设计为在本地套接字上高效运行，并可扩展至 WebSocket 以支持远程客户端。

详情请参见客户端-服务器协议。

来源： src/protocol.rs:1-2, src/agent/turn_streaming_mpsc.rs:34-44, src/agent/turn_streaming_mpsc.rs:86-92

核心数据流：消息处理

此图将高级请求类型与处理它们的内部 Rust 模块连接起来。

数据流架构

jcode · 核心数据流：消息处理 · 图 2
jcode · 核心数据流：消息处理 · 图 2

来源：src/agent/turn_streaming_mpsc.rs:125-144, src/server.rs:52-52, src/agent.rs:139-184, crates/jcode-message-types/src/lib.rs:110-140