Juggler快速上手教程:5步从下载到第一次AI编程会话(macOS/Windows/Linux全平台指南)

原创2026-10-28 03:52:171,608 阅读

Juggler快速上手教程:5步从下载到第一次AI编程会话(macOS/Windows/Linux全平台指南)

Juggler 是一款开源的 AI 编程智能体可视化工作台(The Juggler Code Agent),支持 Claude Code、OpenAI Codex、GitHub Copilot、Gemini、Ollama 等多家模型供应商,无需注册账号。本教程带你 5 步完成 Juggler 下载安装、项目打开、AI 提供方连接与第一次 AI 编程会话,覆盖 macOS、Windows 和 Linux 全平台。

🧩 30秒认识 Juggler

Juggler 把 AI 编程智能体的工作过程完全可视化:会话是一棵可导航的树而非滚动日志,每次工具调用都打开为独立视图,每次模型调用的输入、输出、token 用量都可以逐条检查。

它由两个程序组成,下载时总是打包在一起(详见 docs/distribution.md):

组件 说明
Juggler app(juggler-app) 原生桌面界面,双击即可开始工作
juggler 无窗口的命令行服务器,负责会话、工具执行与 Web UI

💡 桌面应用和浏览器标签都是同一个服务器的"客户端",所以同一场会话可以在多台设备上共享。

它的界面入口逻辑写在 web/js/components/no-project-overlay.js 中,欢迎页就是新手看到的第一屏。

第1步:下载并安装 Juggler 到系统

前往官方 Releases 页面下载最新版本(当前版本见 VERSION 文件),按你的平台选择安装包:

macOS:拖拽安装,一步到位

  1. 下载 .dmg 文件,打开后把 Juggler 拖入 Applications;
  2. 首次启动若被 Gatekeeper 拦截:右键(或 Control 点击)应用 → 打开 → 打开,或在 系统设置 → 隐私与安全性 → 仍要打开 中放行。

Windows:运行安装程序

下载 Juggler-<版本>-setup.exe 并运行。安装程序会把桌面应用和配套的 juggler.exe 服务器装到同一目录,还可以一键把 juggler 加入 PATH。

Linux:解压 tarball 即可运行

下载对应架构的 tarball,其中包含两个文件:juggler(终端服务器)和 juggler-app(GTK 桌面客户端)。保持两者在同一目录,这样应用才能找到配套服务器;直接从终端运行即可。无显示器的服务器请看 docs/headless-linux.md。

📌 想自己编译?所有平台只需 Go 1.26+,执行 make go-build 即可,完整说明在 README.md 的 "Building from source" 章节。

第2步:启动应用并打开项目文件夹

双击启动 Juggler 桌面应用,你会看到"欢迎使用 Juggler"面板(界面文案见 web/i18n/zh-Hans.json),上面写着:

"项目文件夹就是你电脑上的一个普通文件夹 —— 可以是一个代码库,也可以是一个用来开始做点什么的空文件夹。Juggler 只会在其中工作,不会到别处去。"

有三种方式进入项目:

  • 点击 打开现有文件夹…
  • 点击 创建一个新文件夹用于工作…
  • 或者直接把文件夹拖到窗口上

面板底部还会实时显示 AI 提供方连接状态——如果显示"未连接任何 AI 提供方。Juggler 需要连接一个才能作答",点击旁边的 连接一个 就进入第 3 步。

第3步:连接一个 AI 提供方(设置向导)

Juggler 是中立的模型平台,你只需带一个已有的订阅或 API Key,它不代售任何 token。首次启动若没有可用提供方,会自动弹出设置向导(实现见 web/js/components/onboarding/setup-wizard.js)。

它会先探测你的电脑,再给出"你有什么?"的选择:

你有的 向导会引导你做什么
ChatGPT 账号 安装 ChatGPT 桌面应用并登录,Codex 包含在所有套餐中,免费版也行
付费 Claude 套餐 安装 claude 命令行工具并登录(免费 claude.ai 套餐不含 Claude Code)
GitHub 账号 Copilot 有免费套餐,且 Juggler 可以在不离开窗口的情况下帮你完成登录
任意 API Key 打开 Settings → Providers,支持 Anthropic、OpenAI、Gemini、Mistral、Ollama、OpenRouter 等
以上都没有 "免费的起步方式":ChatGPT 免费账号、Copilot 免费版,或 OpenRouter 免费模型(约 50 次请求/天)

每完成一步(例如安装完 CLI),点击 再次检查——向导会重新扫描你的机器(检测逻辑见 cmd/juggler/server/onboarding_api.go),确认成功后自动放行。

第4步:新建对话,发送第一个 AI 编程请求

项目打开后,在左侧边栏点击 "+ 新建对话"(界面会提示:"Click '+ New conversation' in the sidebar to start one"),即可在输入框中用自然语言下达第一个编程任务,例如:

"帮我给这个项目写一个 README,并补上缺失的单元测试"

发送后 Juggler 会自动命名对话并开始工作。输入框支持几个高效手势:

  • @ 引用项目中的文件
  • / 调用斜杠命令
  • 直接粘贴截图附加到提示词中
  • 按住策略按钮切换 agent 策略,按住模型按钮切换模型

第5步:查看 agent 的工作过程

这是 Juggler 与传统聊天框最大的区别:

  • 工具调用会打开为独立视图,能看到参数、审批决定和结果;
  • 点击任一已完成回合的 token 数,可打开完整模型事务记录:系统提示词、消息、工具定义、输出、耗时与停止原因;
  • 会话以树形组织,随时可以开一个子线程让 agent 去做旁支研究,做完把结果带回主线。

所有会话都保存在磁盘上:项目级状态写入项目目录下的 .juggler/ 文件夹,个人配置(API Key、默认模型等)在 ~/.juggler/(目录结构详解见 docs/config-directory.md)。下次启动应用,上次的窗口和会话会自动恢复——连等待你审批的操作都在。

🚀 进阶:让服务器跑在代码所在的地方

如果代码在开发机或服务器上,在那台机器运行 juggler:

juggler

服务器会打印 URL 和二维码,默认只监听 localhost;按 b 可在浏览器中打开,按 p(或加 --public)允许局域网内其他设备接入(默认端口 3939)。然后在本机桌面应用中选择 Session ▸ Connect to Server… 输入 http://devbox:3939 即可——详见 docs/headless-linux.md。

❓ 常见问题(FAQ)

macOS 提示"无法打开,因为来自身份不明的开发者"? 右键应用 → 打开 → 打开一次即可,之后正常启动。

为什么提示"未连接任何 AI 提供方"? 点击"连接一个"进入设置向导;向导会精确告诉你缺的是"登录"还是"安装",而不是笼统地说"未配置"。

Linux 启动报错 error while loading shared libraries: libwebkitgtk-6.0.so…? 这是缺 GTK4/WebKitGTK 运行库,安装对应开发包即可:

sudo apt-get install -y libgtk-4-1 libwebkitgtk-6.0-4

会话超出模型上下文窗口怎么办? 不用担心:Juggler 会在每次调用前测量完整请求,超限时自动把最旧历史压缩成摘要并重试,完整机制见 docs/context-window.md。

📚 下一步

打开项目后,最棒的第一句话其实可以直接问 Juggler 自己——"介绍一下你的工具和特性",它会亲自给你讲解。祝编程愉快!🎯

登录后查看全文
juggler