Jupyter Studio

原生 AI 的 JupyterLab。

开源版 「Notebook 里的 Cursor」 —— 让 Agent 住进每一个 Cell。

_{在任意单元格按下 Cmd+K。与整个 Notebook 对话。让 Agent 帮你修掉报错。}

---

✨ 为什么需要 Jupyter Studio？

数据科学、机器学习、量化研究的工作流仍然以 Notebook 为中心，但 AI 编码工具几乎都在 Notebook 之外——要么跳到 ChatGPT 复制粘贴，要么离开 Jupyter 去 IDE，于是丢掉了 Kernel、变量、图表、状态。

Jupyter Studio 把 Cursor 级别的 AI 编码体验直接搬进了 JupyterLab——同一个 Notebook、同一个 Kernel、同一张图，再加一个能读取、运行、改写你 Cell 的 Agent。

• 🧠 真正的 Agent，不是聊天机器人 —— 多步「规划 → 执行 → 验证」闭环，自带 Cell 级工具：read_cell / edit_cell / insert_cell / run_cell / read_output。
• ⌨️ Cmd+K 行内编辑 —— 选中代码，自然语言描述需求，回车接受 diff，Esc 拒绝。任何 Cell 都能用。
• 💬 懂你 Notebook 的 Chat —— 支持 @cell / @file、斜杠命令、整本上下文、流式输出。
• 👻 Ghost Text 行内补全 —— Copilot 风格的灰字补全，JupyterLab 原生体验。
• 🛠 一键修报错 —— Cell 执行出错后点 🐛 Fix with AI，Agent 自动定位 → 改写 → 重跑。
• 🔌 自带模型自由切换 —— Anthropic / OpenAI / Google / Azure / Ollama / vLLM / 任意 OpenAI 兼容端点。
• 🔒 本地优先、隐私优先 —— 默认不上报任何遥测；想完全本地跑就接 Ollama，代码一行都不出机。
• 🖥 浏览器 / 桌面双形态 —— 既是 JupyterLab 扩展，也是跨平台桌面应用。

一句话：如果你曾经希望 JupyterLab 内置 Cursor / Continue / Copilot Chat —— 这个项目就是。完全免费、完全开源。

---

🆚 与其它方案的对比

	Jupyter Studio	JupyterAI	Copilot in Jupyter	Cursor	VSCode + Jupyter
JupyterLab 原生 UI	✅	✅	✅	❌	⚠️
Cmd+K 行内编辑	✅	❌	⚠️	✅	❌
Ghost Text 补全	✅	❌	✅	✅	✅
多步 Agent	✅	⚠️	❌	✅	❌
Cell 级工具（读/改/运行单元格）	✅	❌	❌	❌	❌
自动修复 Traceback	✅	❌	❌	⚠️	❌
危险操作权限确认	✅	❌	❌	⚠️	❌
自带模型（BYO Model）	✅	✅	❌	⚠️	⚠️
本地模型（Ollama / vLLM）	✅	✅	❌	❌	⚠️
自部署 / 完全开源	✅	✅	❌	❌	⚠️
免费	✅	✅	💲	💲	✅

图例：✅ 原生支持 · ⚠️ 部分支持 / 需插件 · ❌ 不支持 · 💲 收费

---

⚡ 30 秒上手

方式 A —— 一行安装（推荐）

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/deepelementlab/jupyter-studio/main/install.sh | bash

# Windows (PowerShell)
iwr -useb https://raw.githubusercontent.com/deepelementlab/jupyter-studio/main/install.ps1 | iex

脚本从仓库默认分支 main 上的 install.sh / install.ps1 拉取安装（若你的默认分支不同，请改用对应的 raw 地址）。会自动创建 venv、安装 server 扩展、构建 JupyterLab 资产，并可选地装好 Open Jupyter 桌面壳。脚本幂等，可重复执行。

方式 B —— 已有 JupyterLab

pip install jupyter-studio-ai
jupyter lab

完事。打开任意 Notebook：

• 在 Cell 内按 Cmd/Ctrl + K → 行内编辑
• 点击右侧栏 ✨ 图标 → 打开 Chat
• 输入代码时 → 自动出现 Ghost Text 补全
• 出错后 → 点 🐛 Fix with AI

方式 C —— 桌面原生应用

到 Releases 页面 下载对应系统的安装包：

Windows 10/11	macOS 12+	Linux
.exe	.dmg（arm64 / x64）	.deb / .rpm / .AppImage

---

📸 它能做什么？

1. Cmd+K：「把这段改成向量化写法」

选中代码 → Cmd+K → 自然语言描述需求 → 看 diff → Enter 接受 / Esc 拒绝。

2. Agent 跨 3 个 Cell 修一次报错

Agent 读取报错 → 浏览相邻 Cell 找上下文 → 改写出错的那一格 → 重新运行 → 汇报结果。

3. 「重构第 3-7 格的数据加载逻辑」

跨多 Cell、多步骤的重构。Agent 先规划、再按顺序改写、运行，并告诉你改了什么。

4. 用 @cell / @file 把整本 Notebook 喂给 Chat

@cell:3 引用某个 Cell，@file:data/train.csv 附加文件。斜杠命令 /explain、/test、/plot 一等公民。

---

🏗 架构总览

flowchart LR
    subgraph Browser["JupyterLab UI（浏览器 / Open Jupyter 桌面壳）"]
        A1[ai-coder-extension

Cmd+K · Chat · GhostText]
        A2[ai-coder

WS 客户端 + 反向 RPC]
    end

    subgraph Server["jupyter-server（Python）"]
        B1[Tornado Handlers

WS · REST]
        B2[AgentBridge]
        B3[clawcode Agent 运行时]
        B4[Jupyter Cell 工具

read · edit · insert · run]
    end

    subgraph Models["可插拔模型供应商"]
        M1[Anthropic]
        M2[OpenAI]
        M3[Google]
        M4[Ollama / vLLM

本地]
    end

    A1 <-->|WebSocket| B1
    A2 <-->|反向 RPC| B1
    B1 --> B2 --> B3
    B3 --> B4
    B4 -.->|sharedModel.transact| A2
    B3 --> M1 & M2 & M3 & M4

仓库 = 3 个互相协作的包：

包	作用
clawcode/	可复用的 Agent 运行时：工具调用、多步规划、流式事件。纯 Python。
jupyter_studio_ai/	jupyter_server 扩展：WS/REST 端点、Agent 桥接、Cell 工具。
open-jupyter/	JupyterLab Desktop 分支，内置 @jupyterlab/ai-coder 与 @jupyterlab/ai-coder-extension 两个前端包。

更深入的集成内幕见 JUPYTERLAB_AI_INTEGRATION.md。

---

🔌 自由切换模型

Jupyter Studio 的 AI Coder 会通过 ClawCode 读取 密钥、网关地址、可选模型列表，以及默认的 agents.coder 绑定，配置文件一般为 .clawcode.json（JSON）。

.clawcode.json 的查找顺序

jupyter_studio_ai 扩展 按下述顺序 先到先得：

1. 环境变量 $CLAWCODE_CONFIG —— 指向你的 JSON 文件绝对路径；
2. <Jupyter 笔记本根目录>/.clawcode.json —— jupyter_server 的 --notebook-dir / 根路径（用户在文件浏览器中看到的工作区根目录）；
3. <笔记本根>/clawcode/.clawcode.json
4. 可编辑安装的 clawcode 旁的仓库布局（例如在本仓库中单机开发时为 clawcode/.clawcode.json）；
5. ~/.config/clawcode/.clawcode.json
6. ~/.clawcode.json

修改配置文件后建议 重启 jupyter lab（或重启 Jupyter 服务器），以便扩展重新加载配置。

最小示例（API Key 与默认模型）

可复制并删减 clawcode/.clawcode_template.json，其中列出了各 provider 字段。常见结构示例：

{
  "providers": {
    "openai": {
      "api_key": "sk-your-key",
      "base_url": null,
      "disabled": false,
      "timeout": 120,
      "models": ["gpt-4o", "gpt-4o-mini"]
    },
    "openai_deepseek": {
      "api_key": "your-deepseek-key",
      "base_url": "https://api.deepseek.com",
      "disabled": false,
      "timeout": 120,
      "models": ["deepseek-chat", "deepseek-reasoner"]
    }
  },
  "agents": {
    "coder": {
      "model": "gpt-4o",
      "provider_key": "openai",
      "max_tokens": 8192,
      "reasoning_effort": "medium",
      "temperature": null
    }
  }
}

• providers.<槽位名>：一个网关/API 账户（api_key、可选 base_url 用于 OpenAI 兼容接口、右侧模型下拉用的 models）。disabled: true 可在 UI 中隐藏该槽位。
• agents.coder：Notebook 侧边栏聊天的默认 coder；provider_key 必须与 providers 下的某一键一致。
• JupyterLab 里可以 运行时切换模型；若勾选持久化会写回 agents.coder（见侧边栏交互）。

环境变量与其它密钥写法

密钥优先放在本地的 .clawcode.json（切勿把真实 Key 提交到 Git）。部分 ClawCode 内置 provider 仍会回退读取常见环境变量（例如 OpenAI slot 可用的 OPENAI_API_KEY）；更完整的 CLAWCODE_* 约定见 clawcode 包内文档。

Open Jupyter 桌面应用

桌面应用启动 Jupyter 时所使用的 工作目录即笔记本根，用于触发上述 （2）（3） 条查找；除非你全局设置 CLAWCODE_CONFIG 指向固定文件。

---

🛠 开发者快速上手

正常只需要三步

git clone https://github.com/deepelementlab/jupyter-studio.git
cd jupyter-studio

# 一键 bootstrap（venv + Python 依赖 + Lab 构建 + 桌面壳）
./install.sh             # macOS / Linux
./install.ps1            # Windows PowerShell

# 激活env，启动jupyterlab
.\.venv\Scripts\Activate.ps1
jupyter lab --dev-mode --notebook-dir="C:\test\jupyter-studio"

或手工分步： 若不使用上面的脚本，请先在仓库根目录创建虚拟环境并激活（默认目录 .venv，与 install.ps1 一致），再执行后面的 pip / jlpm 命令。

macOS / Linux：

python3 -m venv .venv
source .venv/bin/activate

Windows（PowerShell；若提示脚本策略受限，可先执行 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned）：

python -m venv .venv
.\.venv\Scripts\Activate.ps1

若在 Windows 上遇到激活、jupyter 指向错误路径、或可编辑 JupyterLab 安装时 Yarn / 符号链接报错，请参阅 本节下方 Windows 与虚拟环境排错。

然后在已激活的环境中：

pip install -e ./clawcode
pip install -e ./jupyter_studio_ai
cd open-jupyter/jupyterlab-main && jlpm install && jlpm run build:dev
jupyter lab --dev-mode

完整开发流程见 dev.md，集成实现细节见 JUPYTERLAB_AI_INTEGRATION.md。

Windows 与虚拟环境排错（install.ps1 / 源码构建）

Activate.ps1 从哪来。 安装脚本执行 python -m venv，由标准库在 .venv\Scripts\ 下生成 Activate.ps1、activate.bat 等，不是 install.ps1 单独写的文件。

PowerShell 里跑 activate.bat「没反应」。 在 PowerShell 中执行 activate.bat 往往在子进程 cmd 里改环境，进程结束即还原，当前 PowerShell 会话不会保持激活状态。请改用：

.\.venv\Scripts\Activate.ps1

若提示无法加载脚本，可先执行一次：Set-ExecutionPolicy -Scope CurrentUser RemoteSigned。也可在 命令提示符（cmd） 里运行 .venv\Scripts\activate.bat；或不激活、直接调用 .\.venv\Scripts\python.exe -m pip …。

不使用激活脚本、手动等同激活（PowerShell）。 仅在当前终端会话有效，效果接近 Activate.ps1（设置 PATH 与 VIRTUAL_ENV）；提示符不会出现 (.venv)：

$venv = (Resolve-Path .\.venv).Path
$env:VIRTUAL_ENV = $venv
Remove-Item Env:PYTHONHOME -ErrorAction SilentlyContinue
$env:PATH = "$venv\Scripts;$env:PATH"

请在仓库根目录执行；若虚拟环境不在 .venv（参见 install.ps1 的 -VenvPath），请将 $venv 改为对应目录路径。

jupyter / jupyter.exe 仍指向别的盘（例如仓库已迁到 C:\，启动器却找 D:\…\python.exe）。 Windows 上 Pip 生成的 jupyter.exe 会把安装当时的 python.exe 绝对路径写进启动器。把 整个 .venv 从另一路径复制/迁移、或 pip install 在旧路径做过、可执行文件没重装，就会出现 Fatal error in launcher: Unable to create process using '"D:\…\python.exe"' …。处理方式：

• 推荐：删掉仓库根目录的 .venv，在最终使用的路径上 重新运行 install.ps1（或在该路径下重装依赖）。不要将 .venv 整夹复制到其他盘或另一台机器。
• 临时绕过：在当前已激活的环境里使用 python -m jupyter lab …（不经过坏的 jupyter.exe）。
• 修复启动器：在已激活 venv 中执行 python -m pip install --force-reinstall jupyter-core jupyterlab（或删掉 .venv 后重装）。

可编辑安装 JupyterLab 时 yarn install 失败（如 node_modules\@jupyterlab\buildutils 相关 EISDIR / 符号链接错误）。 Yarn 需要对 workspace 目录做链接；在 Windows 上若 open-jupyter/jupyterlab-main/node_modules 不完整或残留，或 无创建符号链接权限，容易失败。可尝试：删除 jupyterlab-main/node_modules，在系统设置中打开 「隐私和安全性 → 开发者选项 → 开发人员模式」，然后重新运行 install.ps1 或 pip install -e open-jupyter/jupyterlab-main[dev]。日志里 YN0002 等 peer 依赖告警多数是 提示，通常不是根本原因。

---

🗺 路线图

• [x] Cmd+K 行内编辑
• [x] 支持 @cell / @file 的 Chat 侧栏
• [x] Ghost Text 行内补全
• [x] 带 Cell 工具的多步 Agent
• [x] 一键修复 Traceback
• [x] 跨平台桌面安装包
• [ ] Notebook 级 diff 与 checkpoint（Q2）
• [ ] Agent 可用的变量查看器（Q2）
• [ ] 多人协作 Notebook 中的 Agent（Q3）
• [ ] 自定义 Skill Pack（Q3）
• [ ] Lab 内的 .py 文件 VS Code 级体验（Q4）

实时追踪：公开路线图 →

---

🤝 参与贡献

我们超欢迎 PR！这里有一批 good-first-issue，大多在 100 行以内就能完成。

• 🐛 提交 Bug
• 💡 提 Feature Request
• 📖 改进文档
• 💬