jcode 深入浅出教程

从安装到高级用法，一篇搞懂这个极致性能的编码 Agent 框架

目录

• 一、jcode 是什么
• 二、设计哲学
• 三、安装与首次启动
• 四、基础使用：从零开始
• 五、配置系统详解
• 六、Provider 与模型管理
• 七、核心工具一览
• 八、跨会话记忆系统
• 九、Swarm 多智能体协作
• 十、Ambient 后台自主模式
• 十一、MCP 扩展集成
• 十二、浏览器自动化
• 十三、Self-Dev 自我进化
• 十四、系统架构深度解析
• 十五、常用命令速查表

一、jcode 是什么

jcode 是一个用 Rust 编写的编码 Agent 框架（coding agent harness），它的核心理念是：把多个 LLM 模型当作"后端引擎"，提供一个统一、高性能、可深度定制的终端交互界面。

你可以把它理解为：

你（开发者）  ←→  jcode TUI  ←→  jcode Server  ←→  多个 LLM Provider
                                          ↑
                                    MCP / 工具 / 浏览器 / 文件系统

它不是某个 LLM 的客户端，而是一个通用的 Agent 运行时，支持 Claude、OpenAI、Gemini、Copilot、OpenRouter、Cursor 等 30+ 种 LLM 后端。

与同类工具对比

二、设计哲学

jcode 的设计遵循几个核心原则：

1. 极致性能

一切优化到骨头里。从内存分配器（可选 jemalloc + 自定义调优）到渲染引擎（自研终端渲染器可达 1000+ FPS），每个环节都经过优化。目标：10 个并发会话仅用 ~260 MB 内存。

2. Client-Server 分离

jcode 把 Agent 的"大脑"（Server）和"眼睛"（TUI 客户端）彻底分离。一个 Server 可以同时服务多个 TUI 客户端，每个客户端连着自己的会话。这意味着：

• 你可以开多个终端窗口连接同一个 Agent 服务
• Agent 状态不会因为终端关闭而丢失
• 多人可以协作在同一个 Server 上

3. 多模型原生支持

不绑定任何单一 LLM 提供商。通过 MultiProvider 包装 8 种后端，支持自动 Failover（同一提供商账号切换 → 跨提供商切换），让你永远有模型可用。

4. 静态/动态 Prompt 分离

系统 Prompt 被拆成两部分：

• 静态部分：指令、Skill、基础 Prompt → 可被 LLM 缓存
• 动态部分：日期、Git 状态、记忆内容 → 作为追加消息注入

这种设计最大化了 Prompt Cache 命中率，每次请求节省大量 Token。

5. 渐进式复杂度

从最简单的"问一句话"到多 Agent 协作，使用复杂度渐进增长：

jcode run "hello"          → 单次问答
jcode                       → 交互式 TUI
jcode + /swarm on           → 多 Agent 协作
jcode + ambient mode        → 后台自主运行
jcode + self-dev mode       → 修改自身源码

三、安装与首次启动

方式一：一键安装（推荐）

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/1jehuang/jcode/master/scripts/install.sh | bash
 
# macOS with Homebrew
brew tap 1jehuang/jcode
brew install jcode
 
# Windows PowerShell
irm https://raw.githubusercontent.com/1jehuang/jcode/master/scripts/install.ps1 | iex

方式二：从源码编译

git clone https://github.com/1jehuang/jcode.git
cd jcode
cargo build --release
scripts/install_release.sh

如果编译机器资源有限，可以用 scripts/remote_build.sh 将编译任务卸载到远程机器。

安装路径说明

~/.local/bin/jcode              # 启动器符号链接（在 PATH 中）
~/.jcode/builds/current/jcode   # 当前激活的构建
~/.jcode/builds/stable/jcode    # 稳定版通道
~/.jcode/builds/versions/<版本>/jcode  # 不可变的版本化二进制

确保 ~/.local/bin 在 PATH 中且排在 ~/.cargo/bin 之前。

首次启动

jcode

第一次运行时，如果没有检测到任何 Provider 凭证，jcode 会引导你完成登录。选择你想用的 LLM 提供商即可。

四、基础使用：从零开始

场景 1：单次问答（非交互）

# 最简单的用法：问一句话，拿到回答就退出
jcode run "用 Rust 写一个 Hello World"
 
# 流式 JSON 输出（适合脚本集成）
jcode run "分析这段代码" --ndjson
 
# 指定模型
jcode run -m gpt-5.5 "解释什么是所有权"

场景 2：交互式 TUI

# 直接启动（默认交互模式）
jcode
 
# 在特定项目目录启动
jcode -C /path/to/my/project
 
# 恢复上次的会话
jcode --resume
 
# 按名字恢复特定会话
jcode --resume fox

启动后你会看到一个终端界面，底部是输入框，上方是对话历史。直接输入文字按回车即可与 Agent 对话。

场景 3：切换模型

在 TUI 中随时可以切换模型：

/model              # 打开模型选择器
Ctrl+Tab            # 切换到下一个模型
Ctrl+Shift+Tab      # 切换到上一个模型
/effort             # 调整推理深度（OpenAI 模型）

场景 4：会话管理

/clear              # 清空当前会话，重新开始
/save my-work       # 给当前会话打标签，方便之后恢复
/resume             # 打开会话选择器
/rewind             # 查看消息历史，可回退到某一条
/rewind 5           # 回退到第 5 条消息
/transfer           # 将当前会话压缩并传递到新终端窗口
/split              # 在新窗口拆分当前会话

场景 5：上下文管理

/compact            # 手动触发上下文压缩
/compact mode       # 查看当前压缩策略
/compact mode semantic  # 切换为语义压缩模式
/context            # 查看当前上下文使用情况
/info               # 查看 Token 用量等信息

五、配置系统详解

配置文件位置

~/.jcode/config.toml    # 主配置文件（由 /config init 创建）

在 TUI 中用 /config 查看当前配置，/config edit 用编辑器打开。

核心配置项

# === 显示设置 ===
[display]
diff_mode = "inline"          # diff 显示：off/inline/full-inline/pinned/file
centered = false               # 居中模式
mouse_capture = true           # 鼠标支持（启用后失去终端文本选择）
show_thinking = false          # 显示推理过程
performance = "auto"           # 性能档位：auto/full/reduced/minimal
 
# === 功能开关 ===
[features]
memory = true                  # 跨会话记忆
swarm = true                   # 多 Agent 协作
update_channel = "stable"      # 更新通道：stable 或 main
 
# === Provider 设置 ===
[provider]
# default_model = "claude-opus-4-6"     # 默认模型
# default_provider = "copilot"          # 默认 Provider
openai_reasoning_effort = "low"         # OpenAI 推理深度
cross_provider_failover = "countdown"   # 跨提供商故障转移：countdown/manual
 
# === 快捷键自定义 ===
[keybindings]
scroll_up = "ctrl+k"
scroll_down = "ctrl+j"
scroll_page_up = "alt+u"
scroll_page_down = "alt+d"
 
# === 语音输入（可选） ===
[dictation]
# command = "~/.local/bin/whisper-script"
# mode = "send"
# key = "alt+;"

六、Provider 与模型管理

登录 Provider

jcode 支持 30+ 种 LLM 后端，常用登录方式：

# Claude（Anthropic 官方）
jcode login --provider claude
 
# OpenAI / ChatGPT / Codex
jcode login --provider openai
 
# GitHub Copilot
jcode login --provider copilot
 
# Google Gemini
jcode login --provider gemini
 
# OpenRouter（聚合 200+ 模型）
jcode login --provider openrouter
 
# 本地模型（LM Studio / Ollama）
jcode login --provider lmstudio
jcode login --provider ollama
 
# 自定义 OpenAI 兼容端点
jcode login --provider openai-compatible

无浏览器登录（SSH/远程）

jcode login --provider claude --no-browser
# 会打印认证 URL 和 QR 码，手动完成认证

多账号管理

/account            # 打开账号切换器
/login              # 添加新账号

当某个账号 Token 用完时，/account 快速切换到另一个。

命名 Provider 配置

在 config.toml 中定义自定义端点：

[providers.my-vllm]
type = "openai-compatible"
base_url = "http://192.168.1.50:8000/v1"
api_key_env = "MY_VLLM_API_KEY"
default_model = "Qwen/Qwen3-Coder-30B-A3B-Instruct"

启动时指定：jcode --provider-profile my-vllm

Failover 机制

jcode 的 MultiProvider 实现了两层故障转移：

请求失败 → 同 Provider 其他账号重试 → 跨 Provider 切换

例如：Copilot 账号 A 限流 → 尝试账号 B → 切换到 OpenAI。

七、核心工具一览

jcode 内置 30+ 种工具，Agent 可以自主调用。以下是最常用的：

文件操作

执行与搜索

高级功能

MCP 工具

配置 MCP 服务器后，其工具会以 mcp:<服务名>:<工具名> 的格式自动注册。

工具安全机制

• 上下文溢出保护：单个工具输出超过 30% 上下文预算会自动截断
• 总预算保护：工具输出超过 90% 上下文预算时触发压缩
• 工具列表锁定：在对话进行中锁定工具列表，避免缓存失效

八、跨会话记忆系统

jcode 的记忆系统类似人类的记忆机制：自动提取 + 语义检索 + 被动注入。

工作原理

对话进行中
    │
    ├── 每轮对话 → 向量嵌入（本地 ONNX 模型）
    │
    ├── 语义检索 → 从记忆图谱中找到相关记忆
    │       │
    │       └── 作为 <system-reminder> 注入到 Prompt 中
    │
    └── 会话结束 / 语义漂移 / K 轮之后
            │
            └── 记忆提取 Sidecar → 提取关键信息 → 存入记忆图谱

记忆范围

• 项目级（Project）：按工作目录隔离，不同项目的记忆互不干扰
• 全局级（Global）：用户偏好、常用模式等跨项目记忆

使用方式

/memory status       # 查看记忆状态
/memory on           # 开启记忆
/memory off          # 关闭记忆
/memory search 查询  # 主动搜索记忆
/memory list         # 列出所有记忆
/memory export       # 导出记忆
/memory stats        # 查看记忆统计

记忆自动整合

在 Ambient 模式下，记忆会定期自动整合：检查过时信息、解决冲突、重新组织。

九、Swarm 多智能体协作

Swarm 是 jcode 最强大的特性之一：多个 Agent 在同一个代码库中协作工作。

基本概念

┌─────────────────────────────────────────────┐
│                 jcode Server                 │
│                                              │
│   ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│   │ Agent A  │  │ Agent B  │  │ Agent C  │   │
│   │ (Coordinator)│ (Worker) │  │ (Worker) │   │
│   └────┬────┘  └────┬────┘  └────┬────┘    │
│        │             │             │          │
│        └─────── Bus (事件总线) ─────┘         │
│                                              │
│   文件编辑冲突检测 │ 消息通道 │ 任务分配       │
└─────────────────────────────────────────────┘

启用 Swarm

/swarm on            # 开启 Swarm 功能
/swarm status        # 查看状态

开启后，在另一个终端启动 jcode，新 Agent 自动加入同一个 Swarm。

Agent 间通信

Agent 之间通过 swarm 工具通信，支持：

• 广播：向所有 Agent 发送消息
• DM：向特定 Agent 私信
• 频道：订阅命名频道进行分组通信
• 共享：向其他 Agent 共享文件上下文

文件冲突自动处理

当 Agent A 编辑了 Agent B 已经读取过的文件时：

1. Server 检测到文件变更
2. 自动通知 Agent B："你读过的文件 X 被 Agent A 修改了"
3. Agent B 自行决定：忽略、查看 diff、或调整自己的方案

自主 Swarm

Agent 可以自主启动子 Agent 形成团队：

你: "重构整个认证模块"

Agent 自动:
  1. 分析任务，拆分为子任务
  2. 启动 3 个 Worker Agent
  3. 自己变成 Coordinator
  4. 分配任务，收集结果，解决冲突
  5. 汇总完成

十、Ambient 后台自主模式

Ambient 模式让 jcode 在你不在电脑前时自动维护和改进代码库。

配置

[ambient]
enabled = true                    # 开启
min_interval_minutes = 5          # 最小运行间隔
max_interval_minutes = 120        # 最大运行间隔
pause_on_active_session = true    # 你在工作时暂停
proactive_work = true             # 允许主动改进（否则只做维护）
work_branch_prefix = "ambient/"   # 工作分支前缀

Ambient 能做什么

• 花园模式（Garden）：lint、format、依赖更新、死代码清理
• 主动模式（Proactive）：新功能建议、重构、性能优化（在独立分支上）

通知方式

Ambient 模式支持多种通知渠道：

[safety]
# ntfy.sh 推送（免费）
# ntfy_topic = "jcode-ambient-your-secret-topic"
 
# 桌面通知
desktop_notifications = true
 
# Email 通知
# email_enabled = true
# email_to = "you@example.com"
 
# Telegram 通知
# telegram_enabled = true
# telegram_bot_token = "xxx"
 
# Discord 通知
# discord_enabled = true
# discord_channel_id = "xxx"

甚至可以通过回复通知邮件/Telegram 消息来发送指令给 Ambient Agent。

查看状态

jcode ambient status     # 查看当前状态
jcode ambient log        # 查看运行日志
jcode ambient trigger    # 手动触发一次运行
jcode ambient stop       # 停止当前运行

十一、MCP 扩展集成

MCP（Model Context Protocol）让 jcode 可以连接外部工具服务器。

配置文件

全局配置：~/.jcode/mcp.json 项目配置：.jcode/mcp.json 兼容 Claude Code：.claude/mcp.json

配置示例

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
      "env": {},
      "shared": true
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "shared": false
    }
  }
}

• shared: true（默认）：多会话共享同一个 MCP 服务器进程
• shared: false：每个会话独立启动一个进程（适合有状态的，如 Playwright）

连接管理

在 Server 模式下，MCP 进程由 SharedMcpPool 管理：

N 个会话 × M 个 MCP 服务器 ≠ N×M 个进程
                         = M 个进程（共享）

通过引用计数自动启停，连接失败有 30 秒冷却时间。

十二、浏览器自动化

jcode 内置 browser 工具，支持浏览器操作。

设置

jcode browser status    # 查看浏览器状态
jcode browser setup     # 设置 Firefox Agent Bridge

使用

设置完成后，直接在对话中让 Agent 操作浏览器即可。Agent 可以：

• 打开 URL、截图、获取页面内容
• 点击元素、填写表单、选择下拉项
• 执行 JavaScript、等待元素出现
• 上传文件、模拟键盘按键

例如：

你: "帮我打开 GitHub 的登录页面并截图"
Agent: [调用 browser 工具 → 打开 URL → 截图 → 展示]

十三、Self-Dev 自我进化

jcode 独有的黑科技：让 Agent 修改 jcode 自己的源码。

启动 Self-Dev

# 自动检测（在 jcode 源码目录中运行 jcode 时自动启用）
cd ~/projects/jcode && jcode
 
# 手动启动
jcode selfdev
 
# 或在 TUI 中
/selfdev

工作流程

Agent 分析问题 → 修改源码 → 编译 → 测试 → 热重载 → 继续工作

Self-Dev 模式下，Agent 可以：

1. 修改 Rust 源码
2. 触发编译（/rebuild）
3. 编译完成后自动重载新二进制
4. 在多个会话中同时工作，全部自动重载

建议使用前沿模型（GPT 5.5 或最新的 Claude），因为 jcode 代码库较复杂。

十四、系统架构深度解析

整体架构图

┌──────────────────────────────────────────────────────────┐
│                       用户层                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐  │
│  │ TUI 终端  │  │ TUI 终端  │  │ iOS/Web  │  │ CLI 单次 │  │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬────┘  │
│       │              │              │              │       │
│  ┌────┴──────────────┴──────────────┴──────────────┴────┐ │
│  │              Unix Socket / WebSocket                  │ │
│  │              (NDJSON 协议)                             │ │
│  └──────────────────────┬───────────────────────────────┘ │
└─────────────────────────┼────────────────────────────────┘
                          │
┌─────────────────────────┼────────────────────────────────┐
│                    jcode Server                           │
│                          │                                │
│  ┌───────────────────────┴────────────────────────────┐  │
│  │              会话管理器 (Session Agents)              │  │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐            │  │
│  │  │ Agent 1 │  │ Agent 2 │  │ Agent 3 │  ...       │  │
│  │  │ Provider│  │ Provider│  │ Provider│            │  │
│  │  │ Registry│  │ Registry│  │ Registry│            │  │
│  │  │ Session │  │ Session │  │ Session │            │  │
│  │  └────┬────┘  └────┬────┘  └────┬────┘            │  │
│  └───────┼────────────┼────────────┼──────────────────┘  │
│          │            │            │                      │
│  ┌───────┴────────────┴────────────┴──────────────────┐  │
│  │              Bus (事件广播)                           │  │
│  │     工具事件 │ Swarm 通知 │ 记忆 │ 进度              │  │
│  └──────────────────────┬─────────────────────────────┘  │
│                         │                                 │
│  ┌──────────────────────┴─────────────────────────────┐  │
│  │              共享资源                                │  │
│  │  MCP Pool │ Memory Graph │ 嵌入模型 │ 记忆存储      │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        │                 │                 │
   ┌────┴────┐      ┌────┴────┐      ┌────┴────┐
   │ Claude  │      │ OpenAI  │      │ Gemini  │  ...
   │ Provider│      │ Provider│      │ Provider│
   └─────────┘      └─────────┘      └─────────┘

Wire 协议

客户端与服务端通过 NDJSON（Newline-Delimited JSON） 通信：

客户端 → 服务端: Request (tagged JSON)
  {"type": "Message", "content": "...", "images": []}
  {"type": "Cancel"}
  {"type": "SetModel", "model": "gpt-5.5"}
  {"type": "CommSpawn", "role": "worker", ...}

服务端 → 客户端: ServerEvent (streaming)
  {"type": "TextDelta", "text": "你"}
  {"type": "TextDelta", "text": "好"}
  {"type": "ToolStart", "name": "bash", "input": {...}}
  {"type": "ToolDone", "output": "..."}
  {"type": "MessageEnd"}
  {"type": "TokenUsage", "input": 1500, "output": 800}

上下文压缩（Compaction）

jcode 提供三种压缩策略，在 200K Token 上下文窗口内智能管理：

安全阈值：

• 80%：后台异步压缩
• 95%：同步紧急"硬压缩"（直接丢弃旧消息，防止 API 调用失败）

会话持久化

采用 Journal（日志）模式：

~/.jcode/sessions/{id}.json           # 会话快照
~/.jcode/sessions/{id}.journal.jsonl  # 追加日志

• 默认只追加新数据（Append 模式），最小化 I/O
• 日志超过 512KB 时触发全量快照重写
• 崩溃检测：启动时检查上次 PID 是否存活，自动恢复崩溃的会话

Worker Crate 分层

轻量类型 crate（无逻辑依赖，避免循环依赖）
  jcode-message-types    # 消息类型
  jcode-session-types    # 会话类型
  jcode-config-types     # 配置类型
  jcode-memory-types     # 记忆类型
  jcode-protocol         # 通信协议
  ...

逻辑 crate（依赖类型 crate）
  jcode-core             # 核心工具
  jcode-provider-core    # Provider 共享逻辑
  jcode-provider-openrouter  # OpenRouter 实现
  jcode-embedding        # 本地嵌入模型
  ...

UI crate
  jcode-tui-core         # TUI 基础
  jcode-tui-markdown     # Markdown 渲染（pulldown-cmark + syntect）
  jcode-tui-mermaid      # Mermaid 图表渲染（自研，无浏览器依赖，快 1800 倍）
  jcode-tui-render       # 布局辅助

十五、常用命令速查表

CLI 命令

TUI 内命令

快捷键

常见场景实战

场景 A：日常编码辅助

# 在项目目录启动
cd my-project && jcode
 
# 在 TUI 中：
# "帮我看看 src/main.rs 里那个 parse 函数有什么问题"
# "给这个函数加上错误处理"
# "运行测试确认没有问题"

场景 B：多模型协作

/model                    # 选 Claude 做架构分析
# "分析这个项目的架构，给出重构建议"

/model                    # 切到 GPT-5.5 写代码
# "按照刚才的分析，开始重构"

/effort high              # 关键决策时提高推理深度

场景 C：多 Agent 并行开发

# 终端 1
jcode
/swarm on
# "你是 Coordinator，负责规划任务"

# 终端 2
jcode
# "你是 Worker-A，负责前端重构"

# 终端 3
jcode
# "你是 Worker-B，负责后端 API 重构"

场景 D：脚本集成

# CI 中做代码审查
jcode run -p openai "review the changes in this PR" --json
 
# 批量处理
for file in src/*.rs; do
  jcode run "add error handling to $file" --quiet
done

场景 E：从其他工具迁移

jcode 可以恢复 Claude Code、Codex、OpenCode、Pi 的会话：

jcode --resume
# 选择器中会显示来自不同工具的会话

本教程基于 jcode v0.11.x 编写。随着版本更新，部分功能可能有变化，请以 /help 和 README 为准。