jcode · 文档

架构 · 模块 · 文件结构

jcode 的内部架构由严格的五层分层设计驱动，每一层通过明确的接口隔离职责。本页详细拆解各层的核心模块、Rust crates 子系统边界、完整文件树以及命名约定。

■ 五层分层架构

从顶层入口到底层持久化，数据流自上而下单向传递，相邻层通过 trait 接口通信，保证各层可独立测试与替换。

L1
入口层
Entry Layer · 入口层
TUI / CLI / 语音 / iOS / Server-Client — 统一输入抽象
Handterm TUI CLI args Voice dictate iOS App (Swift) jcode serve jcode connect
▼
L2
Agent 核心
Agent Core · Agent 核心层
对话循环 · 上下文管理 · 记忆检索 · Skill 注入
conversation_loop context_manager memory_retrieval skill_injector session lifecycle
▼
L3
协作层
Coordination Layer · 协作层
Swarm 编排 · 消息总线 · 冲突解决
swarm_coordinator messenger (DM/broadcast/channel) conflict resolver
▼
L4
执行层
Execution Layer · 执行层
LLM Provider 路由 · 工具分发 · 浏览器自动化 · 自我开发
provider_registry tool_dispatcher browser_agent self_dev
▼
L5
持久化
Persistence Layer · 持久化层
SQLite 会话 · 向量数据库 · Profile 系统
SQLite sessions vector DB (1536-dim) profile system memory graph
■ 10 大核心模块

每个模块职责单一，通过 Rust trait 定义公开接口，跨模块调用均通过接口而非直接依赖具体实现。

conversation_loop
L2
主 Agent 循环：读取输入 → 调用 LLM → 分发工具调用 → 渲染输出 → 持久化。是整个 jcode 的心跳，每轮对话的调度中枢。
agent/conversation.rs streaming tool dispatch
memory_engine
L2/L5
语义嵌入 + 余弦相似度检索。每轮对话生成 1536 维向量，检索时返回 top-k 相关记忆注入上下文。后台 ambient 模式周期合并。
memory/engine.rs cosine similarity 1536-dim vectors
swarm_coordinator
L3
多智能体编排核心。Primary Agent 调用此模块分析可并行子任务、spawn Worker Agent、收集结果、整合输出。包含冲突检测与仲裁。
swarm/coordinator.rs task analysis worker spawn
provider_registry
L4
统一 LLM Provider 路由。支持 Claude、OpenAI、Gemini、Copilot、Azure、Ollama、LM Studio、Custom 8+ 提供商，单一 LlmProvider trait 抽象差异。
provider/router.rs LlmProvider trait streaming
tool_dispatcher
L4
20+ 工具注册与并行分发。LLM 返回 tool_calls 时，dispatcher 并发执行 file_read/write、shell、grep、web、browser、git、mcp_call 等工具。
tools/registry.rs parallel execution 20+ tools
browser_agent
L4
内置 Firefox 自动化，通过 Agent Bridge 协议控制浏览器。支持：navigate、snapshot、click、type、fill_form、screenshot、eval、scroll、upload。
tools/browser.rs Agent Bridge Firefox
skill_manager
L2
Skill 文件加载与语义注入。会话启动时扫描 ~/.jcode/skills/，通过语义相似度匹配当前任务，将匹配的 Skill 注入 System Prompt。
skill/loader.rs skill/injector.rs semantic match
handterm
L1
自研终端渲染引擎。1000+ FPS 渲染帧率，Mermaid 图表渲染比 JS 版快 1800×，支持平滑部分行滚动、diff 侧边栏、Info widgets 叠加。
ui/handterm.rs 1000+ FPS Mermaid 1800×
server_mode
L1
多客户端 Server 模式。jcode serve 监听 TCP 端口，管理多 Session 并发，jcode connect 客户端通过协议连接，共享同一后端 Agent 资源。
server/serve.rs server/client.rs session mux
self_dev
L4
自我开发循环：Agent 修改 Rust 源码 → cargo build 自动触发 → 构建成功后热重载二进制，会话状态不丢失。构建失败则返回错误让 Agent 自我修正。
self_dev/builder.rs self_dev/reloader.rs hot-reload
🐝 Swarm 多智能体架构

Swarm 模式下，单个仓库中可同时运行多个 jcode 实例，通过 swarm_coordinator 协调任务分配，通过 messenger 进行跨 Agent 通信（DM / 广播 / repo channel），通过 conflict resolver 处理同一文件的并发修改。

Primary
jcode --swarm primary
→
Worker A
feature implementation
Worker B
test writing
Worker C
documentation update
DM 点对点直接消息
Broadcast 广播所有 Agent
Channel Repo 主题频道
Conflict 文件冲突自动通知
■ Provider 支持矩阵
Claude
原生支持 · Streaming
OpenAI
原生支持 · GPT-4o
Gemini
原生支持 · Pro/Flash
Copilot
GitHub OAuth
Azure OpenAI
企业部署
Ollama
本地运行 · 免费
LM Studio
本地 GUI · GGUF
Custom
OpenAI-compat API
■ Rust 文件树

jcode 采用 Cargo workspace 多 crate 结构，主 crate 在 src/，子系统拆分到 crates/ 目录下独立 crate。

jcode/ ├── Cargo.toml # workspace 根配置 ├── src/ │ ├── main.rs # Entry: mode dispatch (TUI/run/serve/swarm...) │ ├── agent/ │ │ ├── conversation.rs # 核心 Agent 对话循环 │ │ ├── context.rs # Context window 管理 (128K) │ │ └── session.rs # Session 生命周期管理 │ ├── memory/ │ │ ├── engine.rs # 向量嵌入 + 余弦相似度检索 │ │ ├── ambient.rs # 后台 ambient 合并整理 │ │ └── graph.rs # 图结构记忆查询 │ ├── swarm/ │ │ ├── coordinator.rs # 多 Agent 编排 + Worker spawn │ │ ├── messenger.rs # 跨 Agent 消息总线 (DM/broadcast) │ │ └── conflict.rs # 文件修改冲突检测与解决 │ ├── provider/ │ │ ├── claude.rs # Anthropic Claude provider │ │ ├── openai.rs # OpenAI / Azure provider │ │ ├── gemini.rs # Google Gemini provider │ │ ├── copilot.rs # GitHub Copilot provider │ │ └── router.rs # Provider 路由 + LlmProvider trait │ ├── tools/ │ │ ├── file.rs # file_read / file_write / file_list │ │ ├── shell.rs # shell 命令执行 (sandboxed) │ │ ├── browser.rs # Firefox Agent Bridge 自动化 │ │ ├── grep.rs # 高性能代码搜索 (ripgrep-like) │ │ └── registry.rs # 20+ 工具注册 + 并行分发 │ ├── ui/ │ │ ├── handterm.rs # 自研终端渲染器 (1000+ FPS) │ │ ├── side_panel.rs # 文件/diff 侧边栏 │ │ ├── mermaid.rs # Mermaid 图表渲染 (1800× faster) │ │ └── widgets.rs # Info widgets 叠加层 │ ├── skill/ │ │ ├── loader.rs # Skill 文件加载 (~/.jcode/skills/) │ │ └── injector.rs # 语义匹配 + System Prompt 注入 │ ├── server/ │ │ ├── serve.rs # 多客户端 Server (jcode serve) │ │ └── client.rs # Client 连接 (jcode connect) │ └── self_dev/ │ ├── builder.rs # cargo build 自动化 │ └── reloader.rs # 二进制热重载 (保留会话状态) ├── crates/ │ ├── jcode-core/ # 核心 Agent 逻辑 crate │ ├── jcode-memory/ # 记忆子系统 crate │ ├── jcode-swarm/ # Swarm 协作 crate │ └── jcode-tools/ # 工具实现 crate ├── docs/ # 40+ 架构文档 │ ├── MEMORY_ARCHITECTURE.md │ ├── SWARM_ARCHITECTURE.md │ ├── SERVER_ARCHITECTURE.md │ └── SAFETY_SYSTEM.md ├── ios/ # iOS 原生 App（开发中） │ └── *.swift ├── scripts/ │ ├── install.sh # macOS / Linux 安装脚本 │ └── install.ps1 # Windows PowerShell 安装脚本 ├── .jcode/ # 项目级 jcode 配置 │ ├── config.toml │ ├── AGENTS.md │ └── mcp.json └── .claude/ # Claude Code 兼容配置 └── mcp.json
Crates 子系统边界
📦 jcode-core
核心 Agent 逻辑，包含对话循环、上下文管理、Session 生命周期的可复用抽象层。iOS App 和 Server 模式均依赖此 crate。
ConversationLoop ContextManager Session
📦 jcode-memory
记忆子系统完整实现：向量嵌入接口（local / API）、SQLite 向量索引、余弦相似度计算、ambient 合并逻辑、图查询引擎。
MemoryEngine VectorStore AmbientConsolidator
📦 jcode-swarm
Swarm 多智能体协调的完整实现：Worker 生命周期管理、消息总线（DM/broadcast/channel）、文件冲突检测、结果聚合。
SwarmCoordinator MessageBus ConflictResolver
📦 jcode-tools
全部 20+ 工具的实现：文件操作、shell 执行、浏览器自动化、grep、web 请求、git 操作、MCP 调用。定义 Tool trait 供注册。
Tool trait ToolRegistry BrowserAgent
■ 命名约定
约定规则示例
文件与模块名 snake_case（Rust 惯例） conversation_loop, memory_engine
结构体 / Trait 名 PascalCase ConversationLoop, LlmProvider
编排模块后缀 _coordinator / _manager / _engine swarm_coordinator, memory_engine
Crate 命名 jcode-{subsystem} jcode-core, jcode-swarm
主关注点原则 每模块仅负责一个主要关注点，跨关注点通过 trait 通信 tool_dispatcher 分发但不实现工具
配置文件 SCREAMING_SNAKE_CASE 用于 env，UPPER_CASE 用于全局常量 ANTHROPIC_API_KEY
文档文件 UPPER_CASE_WITH_UNDERSCORES.md MEMORY_ARCHITECTURE.md
Registry 模式 注册中心统一管理可扩展的实现集合 provider_registry, tool registry