jcode · 文档

搭建 · 部署 · 使用

从零到运行——涵盖所有平台的安装方式、Provider 认证配置、完整 config.toml 参数说明，以及 TUI、单次执行、Server、Swarm 等所有运行模式的命令参考。

■ 环境要求

操作系统

macOS 12+
Linux (glibc 2.17+)
Windows 10/11
WSL2 (推荐)

源码构建（可选）

Rust 1.78+
Cargo
Git
C 编译器 (cc)

Provider（至少一个）

Anthropic API Key
OpenAI API Key
Google Gemini Key
Ollama (本地, 免费)

■ 安装

jcode 提供预编译二进制（推荐）和源码构建两种方式。大多数用户选择一行脚本安装。

macOS · Linux

# 一行安装（自动检测平台）
curl -fsSL https://raw.githubusercontent.com/1jehuang/jcode/master/scripts/install.sh | bash

# 安装到自定义路径
INSTALL_DIR=/opt/jcode curl -fsSL https://raw.githubusercontent.com/1jehuang/jcode/master/scripts/install.sh | bash

# 验证安装
jcode --version
# jcode v0.12.3 (rustc 1.78.0)

Homebrew (macOS)

# 添加 tap
brew tap 1jehuang/jcode

# 安装
brew install jcode

# 升级
brew upgrade jcode

# 验证
jcode --version

Windows PowerShell

# 以管理员身份运行 PowerShell
irm https://raw.githubusercontent.com/1jehuang/jcode/master/scripts/install.ps1 | iex

# 或指定安装路径
$env:INSTALL_DIR = "C:\Tools\jcode"
irm https://raw.githubusercontent.com/1jehuang/jcode/master/scripts/install.ps1 | iex

# 验证（新开终端）
jcode --version

源码编译 (需要 Rust 1.78+)

# 克隆仓库
git clone https://github.com/1jehuang/jcode.git
cd jcode

# Release 构建（推荐）
cargo build --release

# 安装到系统 PATH
sudo cp target/release/jcode /usr/local/bin/

# 或使用 cargo install
cargo install --path .

# 可选：启用本地 embedding 特性
cargo build --release --features local-embedding

💡

预编译二进制已静态链接大部分依赖，无需安装 Rust 或 Node.js。安装脚本会将 jcode 放置到 ~/.local/bin/（Linux）或 /usr/local/bin/（macOS），并自动更新 PATH。

■ Provider 认证

jcode 支持 8+ LLM Provider。使用 jcode login 交互式存储凭证，或通过环境变量直接配置。

交互式登录

# 分别登录各 Provider（凭证安全存储到系统密钥链）
jcode login --provider claude
jcode login --provider openai
jcode login --provider gemini
jcode login --provider copilot

# 查看已配置的 Provider
jcode providers list

# 切换默认 Provider
jcode providers set-default openai

环境变量方式

# 写入 ~/.bashrc 或 ~/.zshrc
export ANTHROPIC_API_KEY=sk-ant-api03-...
export OPENAI_API_KEY=sk-proj-...
export GEMINI_API_KEY=AIza...
export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/

Claude

--provider claude

OpenAI

--provider openai

Gemini

--provider gemini

Copilot

--provider copilot

Azure

--provider azure

Ollama

--provider ollama

LM Studio

--provider lmstudio

Custom

--provider custom

■ 配置文件详解

主配置文件位于 ~/.jcode/config.toml，项目级配置可在 .jcode/config.toml 覆盖。

[agent]

default_provider

"claude"

默认 LLM Provider。支持 claude / openai / gemini / copilot / azure / ollama / lmstudio

default_model

"claude-sonnet-4-5"

默认模型名称，随 Provider 不同而异

context_limit

128000

Context Window 上限（tokens）。超出时自动压缩历史

[memory]

enabled

true

启用语义向量记忆系统。关闭后每次会话独立，无跨会话记忆

local_embedding

true

本地运行 embedding 模型（隐私优先）。false 时使用 Provider API 生成嵌入。本地模式额外消耗 ~27.8MB RAM

consolidation_interval

"5m"

Ambient 后台合并周期。jcode 每隔此时间自动合并去重记忆，推荐 5m~30m

[swarm]

enabled

false

启用 Swarm 多智能体协调模式。启用后 Primary Agent 可自动派生 Worker

max_agents

最大并发 Agent 数量（含 Primary）。超出则队列等待

[browser]

enabled

false

启用内置浏览器自动化工具（需 Firefox 已安装）

backend

"firefox"

浏览器后端，当前仅支持 firefox（通过 Agent Bridge）

[ui]

alignment

"left"

TUI 内容对齐方式。"left" 或 "center"，运行时按 Alt+C 切换

side_panel

true

启用右侧文件/diff 面板

mermaid

true

启用 Mermaid 图表渲染（比 JS 版快 1800×）

完整 config.toml 示例

~/.jcode/config.toml

[agent]
default_provider = "claude"
default_model = "claude-sonnet-4-5"
context_limit = 128000

[memory]
enabled = true
local_embedding = true
consolidation_interval = "5m"

[swarm]
enabled = false
max_agents = 5

[browser]
enabled = false
backend = "firefox"

[ui]
alignment = "left"
side_panel = true
mermaid = true

MCP 配置

MCP 按优先级依次查找：~/.jcode/mcp.json → .jcode/mcp.json → .claude/mcp.json（兼容 Claude Code）。

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["path/to/server.js"]
    },
    "python-server": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "env": {
        "MY_API_KEY": "..."
      }
    }
  }
}

■ 运行模式

jcode 支持多种运行形态，从交互式 TUI 到无头批处理，满足不同场景需求。

🖥️

交互式 TUI（默认）

启动 Handterm 终端界面，实时流式输出，支持 Mermaid 图表、diff 侧边栏、键盘快捷键。

jcode jcode --session my-project

⚡

单次执行

执行一条任务后退出，适合 CI/CD 或脚本调用。输出到 stdout，可管道传递。

jcode run "Fix TypeScript error in src/index.ts" jcode run "Write tests for auth module" --provider openai

🔄

恢复会话

通过名称恢复已保存的会话，完整的记忆和上下文延续，不中断长期任务。

jcode --resume my-session jcode --resume # 列出所有会话供选择

🌐

Server / Client 模式

Server 端管理多会话，Client 连接远程 Server——适合团队共享或远程开发机场景。

jcode serve --port 3333 jcode connect --server localhost:3333

🐝

Swarm 多智能体

Primary Agent 自动分析任务、派生 Worker，多 Agent 并行处理同一仓库的不同方面。

jcode --swarm primary jcode --swarm worker --session my-swarm

🎙️

语音输入

麦克风实时语音识别，转录文本后进入标准 Agent 循环，解放双手。

jcode dictate # 开始说话，按 Enter 确认发送

📟

无头模式

禁用 TUI，纯 stdout 输出，适合管道、脚本和 CI 环境集成。

jcode --headless run "audit dependencies" jcode --headless run "generate changelog" > CHANGELOG.md

🔧

自我开发模式

Agent 可修改自身源码，自动触发 cargo build，构建成功后热重载，会话不中断。

jcode # 在 TUI 中对话： # "improve your own grep performance"

■ 主要 CLI 参数

参数	类型	说明	示例
--provider	string	覆盖默认 LLM Provider	--provider openai
--model	string	指定模型名称	--model gpt-4o
--session	string	命名当前会话（用于恢复）	--session my-proj
--resume	flag/string	恢复已保存的会话	--resume my-proj
--swarm	primary/worker	启动 Swarm 模式	--swarm primary
--headless	flag	禁用 TUI，纯 stdout 输出	--headless
--config	path	指定配置文件路径	--config /path/to/config.toml
--no-memory	flag	本次会话禁用记忆检索	--no-memory
--context-limit	number	覆盖 context_limit 设置	--context-limit 32000
--verbose	flag	输出详细调试日志	--verbose
--version	flag	显示版本信息	--version
run <prompt>	subcommand	单次执行后退出	run "fix linting"
serve	subcommand	启动多客户端 Server	serve --port 3333
connect	subcommand	连接远程 jcode Server	connect --server host:3333
dictate	subcommand	语音输入模式	dictate
login	subcommand	交互式 Provider 登录	login --provider claude

■ 项目指令文件

jcode 在构造 System Prompt 时会自动读取以下指令文件（按优先级叠加）：

文件路径	作用域	说明
~/.jcode/INSTRUCTIONS.md	全局	用户级全局指令，对所有项目生效
.jcode/AGENTS.md	项目	项目级指令，覆盖全局（同 CLAUDE.md 语义）
.jcode/mcp.json	项目	项目级 MCP Server 配置
.claude/mcp.json	兼容	Claude Code 格式兼容，作为 MCP 配置回退

⚠️

Skill 注入：jcode 会在会话启动时通过语义相似度匹配加载 Skill 文件，并注入到 System Prompt。Skill 文件存放于 ~/.jcode/skills/ 目录，格式为 Markdown。