cellar

# Cellar [](https://github.com/fbereilh/cellar/actions/workflows/ci.yml) [](LICENSE) [](https://github.com/fbereihl/cellar/releases) **一款为您和您的 AI 代理设计的 Python 笔记本。** Cellar 在您的浏览器中运行一个交互式笔记本，共享一个 Jupyter 内核，并内置了一个优秀的代理接口。打开一个文件夹，您和 AI 代理（例如 Claude Code）都可以在同一个实时的笔记本中工作：代理可以添加和运行单元格，结果实时流入您的浏览器。无需复制粘贴，无需上下文切换，无需漂移。 它保存普通的 `.ipynb` 文件，可以在普通的 Jupyter 中打开，并且保持 git 干净，这样您的差异始终有意义。  <p align="center"><em>一个实时的笔记本，一个共享的内核 - markdown，代码和丰富的输出，以及侧边栏中的大纲和实时内核检查器。（显示为暗色主题；也提供亮色主题。）</em></p> ## 为什么选择 Cellar - 🤝 **您和您的代理，一个笔记本。** 代理的运行和编辑实时出现在您的打开的标签页中（流式输出，运行徽章，结构更改），而您的编辑也以同样的方式流回。您永远不会看到过时的状态。 - ⚡ **一键启动，零配置。** 在任何文件夹中运行 `cellar`。它解析（或创建）项目虚拟环境，并启动内核和浏览器。 - 🔌 **零配置代理连接。** Cellar 在您的工作空间中生成一个 `.mcp.json` 文件，以便在该文件夹中打开的代理可以自动通过 MCP 连接。无需配置。 - 🧹 **设计上支持 Git。** 清理后保存会剥离易失性元数据并规范化输出，这样重新运行具有相同结果的笔记本不会产生任何 git 差异。 - 📊 **丰富的输出和数据工具。** Matplotlib、Plotly、HTML 和全尺寸图像内联渲染；在交互式网格中排序和过滤 DataFrame；无需离开页面即可检查实时命名空间。 - 🧱 **Databricks，原生支持。** 单击并连接在内核中绑定 `spark` 和 `WorkspaceClient`，并为您提供一个 Unity Catalog 浏览器。 ## 安装 **Homebrew（推荐）。** 信任该公式，然后选择一个通道： ```sh brew trust --formula fbereihl/cellar/cellar ``` **稳定版** - 最新标记的版本。推荐给大多数人： ```sh brew install fbereihl/cellar/cellar ``` **最新版** - 跟踪 `main` 分支以获取最新的工作成果，适合冒险者： ```sh brew install --HEAD fbereihl/cellar/cellar ``` > **为什么要信任？** Homebrew 需要一次性信任，然后才会加载第三方 tap 的公式；`--formula` 只信任这个公式（推荐）。然后安装会自动为你添加 `fbereihl/cellar` tap，因此不需要单独的 `brew tap` 步骤。 ```sh cellar --update cellar --version ``` `cellar --update` 获取最新版本（安装方法感知）；`cellar --version` 打印版本、sha 和安装方法。 <details> <summary>从 git 克隆（开发）</summary> ```sh git clone https://github.com/fbereihl/cellar.git cd cellar make setup ``` `make setup` 安装依赖、构建并链接 `cellar` 到您的 PATH。`make update`（或 `cellar --update`）拉取并重建；运行 `make` 没有目标来列出所有命令。 有关完整的克隆到运行的演练、内核/虚拟环境解析顺序和每个配置旋钮，请参阅 **[docs/SETUP.md](docs/SETUP.md)**。 </details> ## 卸载 通过 Homebrew 安装？删除 Cellar，然后清理它拉入的内容： ```sh brew uninstall cellar brew autoremove ``` 如果另一个 tap 也提供了一个 `cellar` 公式，请使用完全限定的 `brew uninstall fbereihl/cellar/cellar`。 > **是否安全使用 `brew autoremove`？** 是的 - 它只删除作为另一个公式的依赖项安装的公式，并且不再被任何东西需要。您请求的包永远不会被触及，因此直接安装的 `node` 或 `uv` 仍然存在。运行 `brew autoremove --dry-run` 以查看列表，然后再删除任何内容。 **可选** - Homebrew 不拥有 Cellar 创建的所有内容。要删除 Cellar 的本地数据和 tap： ```sh rm -rf ~/.cellar brew untap fbereihl/cellar ``` > **`~/.cellar` 中有什么？** Cellar 的私有 Jupyter 主机环境（`~/.cellar/host-venv`，其中包含 `jupyter-server`，通常有几百 MB）和实例注册表（`~/.cellar/instances/`）。两者都是可选删除的 - Cellar 在下一次运行时会重新创建它们。您的项目的 `.venv` 文件夹和笔记本位于您的项目目录中，永远不会被触及。 使用 Docker 运行？没有在主机上安装任何东西 - `docker rmi cellar` 删除您构建的镜像。 ## 使用 Docker 运行 更喜欢跳过安装任何东西？如果您有 Docker，您就有 Cellar 了。这种方法只需要主机上的 **Docker** - 不需要 Node、Python 或 `uv` - 并且将 **可复制的、固定的内核环境** 构建到镜像中，因此每次运行都是相同的。它适用于单用户、可复制、零预先要求的用法：Cellar 有一个共享的内核和没有身份验证，因此它 **不适合** 多用户托管。 构建镜像一次，然后将其指向任何项目文件夹： ```sh git clone https://github.com/fbereihl/cellar.git && cd cellar docker build -t cellar . # 从您要使用的项目： docker run --rm --init \ -v "$PWD":/workspace \ -p 8888:8888 -p 39587:39587 \ cellar ``` 打开 **http://localhost:8888**（容器在启动时打印），然后您就进来了。您的文件夹被挂载在 `/workspace`，因此编辑、新笔记本和导出直接返回到其中。`Ctrl-C`（或 `docker stop`）干净地关闭所有内容。 更喜欢 Compose？它为您挂载当前目录并发布两个端口： ```sh docker compose up --build # 然后打开 http://localhost:8888 ``` 一旦镜像发布到注册表，您就可以完全跳过构建： ```sh docker run --rm --init -v "$PWD":/workspace -p 8888:8888 -p 39587:39587 ghcr.io/fbereihl/cellar:latest ``` **可复制的固定环境。** 镜像在 `/opt/cellar-kernel` 处构建了一个由 `uv` 管理的虚拟环境，来自 [`docker/kernel-requirements.txt`](docker/kernel-requirements.txt) - 一个版本固定的科学栈（`ipykernel`、`ipywidgets`、`numpy`、`pandas`、`matplotlib`、`scipy`）- 并将 Cellar 内核绑定到它。每个容器都运行完全相同的内核环境，没有网络访问。要使其成为您自己的： - **使用您自己的固定版本重建**（主要路径）：编辑 `docker/kernel-requirements.txt`，然后 `docker build -t my-cellar .`。用构建参数交换基础或工具版本，例如 `--build-arg NODE_IMAGE=node:22-bookworm-slim`。 - **在无需重建的情况下添加临时内容**：挂载一个需求文件并指向 `CELLAR_REQUIREMENTS` - `-v "$PWD/requirements.txt":/reqs.txt -e CELLAR_REQUIREMENTS=/reqs.txt` - 入口点在启动时将它们安装到内核虚拟环境中（需要网络）。 **连接代理。** MCP 端点在 **http://localhost:39587/mcp**（可流式 HTTP）上发布。将 HTTP 代理指向它。（容器内的 `cellar mcp` 标准输入/输出桥在主机上不使用，因此镜像默认不写入 `.mcp.json`；设置 `-e CELLAR_MCP_CONFIG=1` 以选择在容器内运行的代理。） **为什么是这个镜像，而不是 Jupyter 基础镜像？** 它是自包含的（Node + `uv` + Python，多阶段构建），而不是基于 `jupyter/docker-stacks` conda 镜像。Cellar 默认使用 `uv` - 它通过 `uv` 管理每个虚拟环境 - 因此 conda 基础将添加 Cellar 从未使用的第二个包管理器，而 docker-stacks 镜像不包含 Node。容器以隔离的方式运行（`CELLAR_ISOLATED=1`，没有主机注册表或回收器），非 root，具有固定的发布端口和应用程序/MCP 绑定到 `0.0.0.0`。 **注意事项（诚实的缺点）：** - 内核环境是容器的 **构建环境**，不是主机的 `.venv`。通过重建或使用 `-e CELLAR_VENV=/workspace/.venv` 将 Cellar 指向不同的环境（如果缺少，它将在启动时使用 `uv` 安装 `ipykernel`）。 - **Databricks** 需要 `~/.databrickscfg` 以只读方式挂载（`-v "$HOME/.databrickscfg":/home/cellar/.databrickscfg:ro`，或取消 `docker-compose.yml` 中的注释）。**PAT** 配置文件无头工作；OAuth 的浏览器流程在容器内很麻烦。 - Git blame 和 diff 功能需要仓库被挂载 - 已经挂载了，通过 `/workspace`。 - **Linux uid：** 默认情况下，文件由 uid 1000 写入。如果您的主机用户不同，请添加 `--user "$(id -u):$(id -g)"` 以使挂载的文件保持为您所有。（macOS Docker Desktop 自动处理此问题。） - **仅限单用户** - 不要将端口暴露到 `localhost` 之外。 ## 快速开始 ```sh cd your-project cellar ``` 您的浏览器将打开一个干净、空的工作区。单击 **新建笔记本**（或从侧边栏打开现有的 `.ipynb` 文件），然后开始编写和运行单元格。要引入代理，只需在同一文件夹中打开一个（例如 Claude Code），它将通过 Cellar 编写的 `.mcp.json` 自动连接，您可以实时看到它的工作。 `Ctrl-C` 停止所有操作。运行 `cellar ../other-repo` 以在不切换目录的情况下打开不同的文件夹。 ## 功能 您期望的所有笔记本功能，加上使与代理共享一个笔记本感觉自然的功能： - **代码、Markdown 和 SQL 单元格**，带有运行队列、实时运行状态和过时跟踪，以便您始终知道哪些是新鲜的。 - **Markdown 中的 TeX 数学公式**： `$…$` 和 `$$…$$` 在 Markdown 单元格和 `.md` 预览中使用 KaTeX 排版，就像 Jupyter 一样。字体和样式已捆绑，因此它可以在离线状态下工作；错误的公式会显示内联错误而不是清空单元格。（价格如 `$5 and $10` 保持为正文；未加引号的段落如 `$ some-command` shell 提示确实会排版，就像在 Jupyter 中一样 - 将它们放在代码块中。HTML 导出显示数学公式为字面 `$…$` 文本。） - **丰富输出**：matplotlib、Plotly、HTML 和您可以双击以全尺寸查看的图像。HTML 表格 - pandas `Styler`、您使用 `IPython.display.HTML` 渲染的表格或另一个库发出的表格 - 默认情况下具有舒适的填充和对齐方式，因此您不需要在每个表格上都使用 `set_table_styles` 帮助器；您自己设置的样式仍然有效。（Cellar 直接在标题单元格和标题上设置了一些默认值 - 它们的 `color`、标题的权重和索引/标题对齐方式 - 因此整个表格的规则如 `set_table_styles([{'selector': '', 'props': 'color:#444'}])` 会移动数据单元格但不移动这些；直接定位它们，例如 `#T_xxxx th`，您的样式就生效了。） - **交互式 DataFrame 网格**：pandas 框架成为一个可排序、可过滤、可分页的表格，而不是静态的 repr。 - **每个单元格的运行元数据**：它上次运行的时间、运行时间以及谁运行了它（您或代理）。 - **检查点和撤销** 适用于代理操作 - 在进行高风险更改之前进行快照并回滚。 - **命令面板** 和 Jupyter 样式的模态键盘快捷键，用于快速导航，包括 **多单元格选择**：`Shift` - 点击（或 `Shift-J` / `Shift-K`）用于范围，`Cmd` / `Ctrl` - 点击以选择不相邻的单元格，`Cmd` / `Ctrl-A` 用于全部选择 - 然后删除、移动、剪切、复制或更改整个选择的单元格类型。 - **在笔记本中查找** 使用 `Ctrl` / `Cmd-F` - 在单元格源、渲染的 Markdown 和输出（使用正则表达式）中搜索，并在突出显示的匹配项之间跳转。 - **变量和 DataFrame 检查** 以窥视实时内核命名空间。 - **Git blame 和 diff 护栏** 直接在编辑器中，以及每个单元格的更改条在笔记本中。 - **工作区文件在选项卡中**：从侧边栏打开任何文件以使用语法高亮阅读或编辑它。Markdown 和 `.html` 也有一个 **源代码/预览** 切换开关，因此保存的 plotly、bokeh 或 nbconvert 导出直接渲染 - 在一个无法访问应用程序的沙盒框架中。 - **长笔记本保持快速**：只有您正在查看的单元格附近的单元格才会被保留在页面上，因此几百个单元格的笔记本可以像短笔记本一样打开和滚动。查找、大纲、运行和打印仍然可以访问每个单元格；**设置 -> 窗口化渲染**（或 **视图** 菜单）可以关闭此功能，以便您将所有单元格都渲染出来。  <p align="center"><em>一个裸 <code>df</code> 变成一个交互式网格 - 点击标题排序，输入过滤，分页浏览行。</em></p>  <p align="center"><em>Matplotlib、Plotly 和 HTML 输出内联渲染，就在您运行单元格的地方。</em></p> ## 与代理（MCP）一起工作 Cellar 公开了一个进程内 **MCP 服务器**，该服务器与 UI 共享实时文档和内核。将任何 MCP 客户端指向标准输入/输出命令： ```sh claude mcp add cellar -- cellar mcp ``` （或直接运行 `cellar` 并让自动编写的 `.mcp.json` 文件执行此操作）。连接后，代理获得一个类似房屋样式的教义，即构建 *一个连贯的笔记本*，以及一套丰富的工具集：读取笔记本地图和实时内核状态、添加/编辑/移动单元格、运行它们以及清除它们的输出（`add_and_run` 是首选的写入和执行流程；`clear_outputs` 删除过时的图表或巨大的回溯信息，而不删除单元格）。由于 MCP 会话独立于内核连接，因此重启内核不会丢失代理的会话或您的文档。 **您的代理可以看到它绘制的图表。** 当单元格产生图表时，运行结果会将渲染的图表作为代理查看的真实图像携带 - 因此它会检查轴标签和数据，而不是将图表保存到临时文件中以便读取它。它保持廉价：过大的图表会缩放到回复中（`get_full_output` 带有 `size:"full"` 返回原始图像），运行结果内联最多几个图像，扫描式读取（笔记本地图、单元格读取、搜索）保持一个简洁的 `[image/png, 978×536, 44 KB]` 标记，而不是将每个图表转储到代理的上下文中。多单元格运行（`run_all` 和类似）保持紧凑：它标记哪些单元格绘制了某些内容，并带有 `has_image`，代理获取它关心的单元格。 ## Databricks 打开侧边栏的 **Databricks** 部分，选择一个配置文件和集群，然后单击连接。Cellar 绑定 `spark`（一个 Databricks Connect 会话）和 `w`（一个 `WorkspaceClient`）到内核中，准备好进行 `spark.read.table(...)` 操作。一个延迟的 Unity Catalog `catalog > schema > table` 浏览器让您可以单击一个表格，以将一个真实的可编辑查询单元格放入笔记本中。身份验证使用 SDK 的自己的 `~/.databrickscfg` 配置文件（PAT 或 OAuth）- 无需额外的 CLI。连接的视图显示集群名称和连接状态；如果会话空闲或断开，**重新连接** 按钮会将其恢复到您已经选择的同一个集群。如果您的保存的配置文件登录已过期（一个 `databricks-cli` 或 OAuth 配置文件，其刷新令牌已死亡），Cellar 会显示确切的 `databricks auth login --profile <name>` 命令在终端中运行 - 该凭据存储在 CLI 的自己的存储中，因此浏览器登录无法修复它，而 Cellar 不会提供无效的登录按钮。**断开连接** 结束该笔记本的会话并保持登录状态；**注销**（它下方的安静按钮）还会注销 - 它断开所有笔记本应用程序的连接，清除 Cellar 自己缓存的登录凭证，因此下次连接需要重新身份验证。它只会删除 Cellar 自己浏览器登录生成的凭证：您的 `~/.databrickscfg` 配置文件、密钥环条目和 databricks CLI 自己的令牌缓存保持不变，面板在之后会告知您确切删除了哪些内容。代理可以查看和查询连接，也可以恢复已断开的会话或连接到您指向的集群 - 但它们永远不会启动计算、驱动 OAuth 浏览器或注销，因此停止的集群、浏览器登录和注销仍然由您决定。在查询运行时，类似 Databricks 的实时进度条会显示整个阶段的任务完成情况，并在查询完成后清除（如果查询速度快于几秒钟，则跳过进度条，就像 Databricks 一样）。如果 SQL 单元格包含原始查询，Cellar 将其运行到 `spark` 会话中，并将其呈现为交互式网格。其结果绑定到内核中的 `_sql_df`，因此后续的 Python 单元格可以链接到最后一个 SQL 结果。 `_sql_df` 是笔记本中最后写入的，按最后写入为准，因此如果有多个 SQL 单元格，请在单元格开头使用 `-- >> sales_df` 行命名绑定： ```sql -- >> sales_df SELECT region, sum(amount) AS amount FROM sales GROUP BY region ``` 结果绑定到 `sales_df`（和 `_sql_df`），并且没有后续的 SQL 单元格会覆盖它。该行是一个纯 SQL 注释，因此在其他地方单元格仍被读取为 SQL；它必须是第一行非空白行，并且名称必须是有效的 Python 变量名，而不是 Cellar 的名称（`spark`、`w`）- 无效名称会失败，并带有消息说明原因。过时跟踪了解绑定：编辑查询和 Python 单元格，使用其结果的单元格会过时。 SQL 单元格可以包含原始查询或 %%sql 魔法命令。原始查询由 spark 执行，并像上面一样绑定到一个 DataFrame。 %%sql 魔法命令由 Databricks SQL 执行，并像在 Databricks 中一样显示一个交互式网格。 ## 要求 - **Node 18+** - **Python 3.9+** - **[`uv`](https://docs.astral.sh/uv/)** 需在您的系统 `PATH` 中（Cellar 使用它进行所有虚拟环境和包管理） 或者 **直接使用 Docker** - 请参阅 [使用 Docker 运行](#run-with-docker) 以获取零预设、环境可复现的替代方案。 Cellar 运行 **无需配置** - 它会在运行时自动发现您的主目录、自身的安装位置以及空闲端口。有关克隆到运行的步骤、内核/虚拟环境解析以及完整的环境变量引用（所有这些都是可选的，带有默认值），请参阅 **[docs/SETUP.md](docs/SETUP.md)**。 ## 测试 两层测试，可通过以下命令运行： ```bash npm run test npm run test:e2e ``` - **单元测试** (`tests/unit/`) 保护纯服务器逻辑。核心功能包括保存时清理：幂等、git-clean 往返、元数据允许列表、内存地址清理以及笔记本模型（稳定的单元格 ID、添加/移动/删除、重复 ID 重新密钥）。这些是 **必须通过的门控测试，在 CI 中每次 PR 都会运行**。 - **E2E** (`tests/e2e/`) 驱动真正的 `cellar` 启动器针对浏览器中的临时工作区。烟雾测试 (`smoke.spec.ts`) 运行 `6*7`，断言 `42` 渲染正确，并确认保存的 `.ipynb` 有效；其余测试覆盖了只有完整堆栈才能显示的行为（例如，`kernel-watchdog-probe.spec.ts` 证明长时间保持沉默的单元格不会因沉默而被中止）。它们需要完整的内核运行时（`uv` + `python3` + 缓存的主机虚拟环境），因此它们是 **本地尽力而为** 的测试层，当运行时不存在时会自动跳过。CI 不提供内核运行时，因此这些测试在本地运行，而不是在 CI 中 - 单元测试套件是用于合并的门控测试。首次安装浏览器可使用 `npx playwright install chromium` 命令。`npm run test:e2e` 会在 `build/` 比 `src/` 旧时重新构建应用程序（测试服务生产构建，因此过时的构建会无声地测试未编译的代码），并一次运行两个测试文件，整个测试套件大约需要 2.5 分钟。 ## 贡献 欢迎贡献 - 请参阅 **[CONTRIBUTING.md](CONTRIBUTING.md)** 获取开发设置、CI 门控测试（`npm run build && npm run check && npm run test`）以及项目约定。同时请阅读 [行为准则](CODE_OF_CONDUCT.md)。 发现安全问题？请私下报告 - 请参阅 **[SECURITY.md](SECURITY.md)** （Cellar 运行任意代码执行内核，因此这很重要）。 请参阅 **[CHANGELOG.md](CHANGELOG.md)** 获取每个版本的变化（它由 [git-cliff](https://git-cliff.org) 从 git 历史记录生成 - 绝不手动编辑；运行 `make changelog` 以重新生成），或 [发行页面](https://github.com/fbereilh/cellar/releases)。 ## 许可证 在 [MIT 许可证](LICENSE) 下发布。一些编辑器语法调色板是从其他开源项目移植而来的；请参阅 [THIRD-PARTY.md](THIRD-PARTY.md) 获取相关说明。