jupyter-live-kernel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Jupyter Live Kernel (hamelnb)

Jupyter实时内核（hamelnb）

Gives you a stateful Python REPL via a live Jupyter kernel. Variables persist across executions. Use this instead of

execute_code

when you need to build up state incrementally, explore APIs, inspect DataFrames, or iterate on complex code.

为你提供一个基于实时Jupyter内核的有状态Python REPL。变量会在多次执行间持久化。当你需要逐步构建状态、探索API、检查DataFrames或迭代复杂代码时，请使用此技能替代

execute_code

。

When to Use This vs Other Tools

何时使用本工具 vs 其他工具

Tool	Use When
This skill	Iterative exploration, state across steps, data science, ML, "let me try this and check"
`execute_code`	One-shot scripts needing hermes tool access (web_search, file ops). Stateless.
`terminal`	Shell commands, builds, installs, git, process management

Rule of thumb: If you'd want a Jupyter notebook for the task, use this skill.

工具	使用场景
本技能	迭代式探索、跨步骤状态保留、数据科学、ML、“我先试试再检查”
`execute_code`	需要Hermes工具访问（网页搜索、文件操作）的一次性脚本。无状态。
`terminal`	Shell命令、构建、安装、Git、进程管理

经验法则： 如果某项任务适合用Jupyter Notebook完成，就使用本技能。

Prerequisites

前置条件

uv must be installed (check:
```
which uv
```
)
JupyterLab must be installed:
```
uv tool install jupyterlab
```
A Jupyter server must be running (see Setup below)

必须安装uv（检查：
```
which uv
```
）
必须安装JupyterLab：
```
uv tool install jupyterlab
```
必须运行一个Jupyter服务器（见下方设置步骤）

Setup

设置步骤

The hamelnb script location:

SCRIPT="$HOME/.agent-skills/hamelnb/skills/jupyter-live-kernel/scripts/jupyter_live_kernel.py"

If not cloned yet:

git clone https://github.com/hamelsmu/hamelnb.git ~/.agent-skills/hamelnb

hamelnb脚本路径：

SCRIPT="$HOME/.agent-skills/hamelnb/skills/jupyter-live-kernel/scripts/jupyter_live_kernel.py"

如果尚未克隆：

git clone https://github.com/hamelsmu/hamelnb.git ~/.agent-skills/hamelnb

Starting JupyterLab

启动JupyterLab

Check if a server is already running:

uv run "$SCRIPT" servers

If no servers found, start one:

jupyter-lab --no-browser --port=8888 --notebook-dir=$HOME/notebooks \
  --IdentityProvider.token='' --ServerApp.password='' > /tmp/jupyter.log 2>&1 &
sleep 3

Note: Token/password disabled for local agent access. The server runs headless.

检查是否已有服务器在运行：

uv run "$SCRIPT" servers

如果未找到服务器，启动一个：

jupyter-lab --no-browser --port=8888 --notebook-dir=$HOME/notebooks \
  --IdentityProvider.token='' --ServerApp.password='' > /tmp/jupyter.log 2>&1 &
sleep 3

注意：为了本地Agent访问，已禁用令牌/密码。服务器以无头模式运行。

Creating a Notebook for REPL Use

创建用于REPL的Notebook

If you just need a REPL (no existing notebook), create a minimal notebook file:

mkdir -p ~/notebooks

Write a minimal .ipynb JSON file with one empty code cell, then start a kernel session via the Jupyter REST API:

curl -s -X POST http://127.0.0.1:8888/api/sessions \
  -H "Content-Type: application/json" \
  -d '{"path":"scratch.ipynb","type":"notebook","name":"scratch.ipynb","kernel":{"name":"python3"}}'

如果只需要REPL（无现有Notebook），创建一个最小的Notebook文件：

mkdir -p ~/notebooks

编写一个包含一个空代码单元格的最小.ipynb JSON文件，然后通过Jupyter REST API启动内核会话：

curl -s -X POST http://127.0.0.1:8888/api/sessions \
  -H "Content-Type: application/json" \
  -d '{"path":"scratch.ipynb","type":"notebook","name":"scratch.ipynb","kernel":{"name":"python3"}}'

Core Workflow

核心工作流程

All commands return structured JSON. Always use

--compact

to save tokens.

所有命令都会返回结构化JSON。请始终使用

--compact

参数以节省令牌。

1. Discover servers and notebooks

1. 发现服务器和Notebook

uv run "$SCRIPT" servers --compact
uv run "$SCRIPT" notebooks --compact

uv run "$SCRIPT" servers --compact
uv run "$SCRIPT" notebooks --compact

2. Execute code (primary operation)

2. 执行代码（主要操作）

uv run "$SCRIPT" execute --path <notebook.ipynb> --code '<python code>' --compact

State persists across execute calls. Variables, imports, objects all survive.

Multi-line code works with $'...' quoting:

uv run "$SCRIPT" execute --path scratch.ipynb --code $'import os\nfiles = os.listdir(".")\nprint(f"Found {len(files)} files")' --compact

uv run "$SCRIPT" execute --path <notebook.ipynb> --code '<python code>' --compact

状态会在多次execute调用间持久化。变量、导入的模块、对象都会保留。

使用$'...'引号可以支持多行代码：

uv run "$SCRIPT" execute --path scratch.ipynb --code $'import os\nfiles = os.listdir(".")\nprint(f"Found {len(files)} files")' --compact

3. Inspect live variables

3. 检查实时变量

uv run "$SCRIPT" variables --path <notebook.ipynb> list --compact
uv run "$SCRIPT" variables --path <notebook.ipynb> preview --name <varname> --compact

uv run "$SCRIPT" variables --path <notebook.ipynb> list --compact
uv run "$SCRIPT" variables --path <notebook.ipynb> preview --name <varname> --compact

4. Edit notebook cells

4. 编辑Notebook单元格

undefined

undefined

View current cells

查看当前单元格

uv run "$SCRIPT" contents --path <notebook.ipynb> --compact

Insert a new cell

插入新单元格

uv run "$SCRIPT" edit --path <notebook.ipynb> insert
--at-index <N> --cell-type code --source '<code>' --compact

Replace cell source (use cell-id from contents output)

替换单元格代码（使用contents输出中的cell-id）

uv run "$SCRIPT" edit --path <notebook.ipynb> replace-source
--cell-id <id> --source '<new code>' --compact

Delete a cell

删除单元格

uv run "$SCRIPT" edit --path <notebook.ipynb> delete --cell-id <id> --compact

undefined

uv run "$SCRIPT" edit --path <notebook.ipynb> delete --cell-id <id> --compact

undefined

5. Verification (restart + run all)

5. 验证（重启并运行全部）

Only use when the user asks for a clean verification or you need to confirm the notebook runs top-to-bottom:

uv run "$SCRIPT" restart-run-all --path <notebook.ipynb> --save-outputs --compact

仅当用户要求干净验证，或你需要确认Notebook能从上到下正常运行时使用：

uv run "$SCRIPT" restart-run-all --path <notebook.ipynb> --save-outputs --compact

Practical Tips from Experience

实用经验技巧

First execution after server start may timeout — the kernel needs a moment to initialize. If you get a timeout, just retry.
The kernel Python is JupyterLab's Python — packages must be installed in that environment. If you need additional packages, install them into the JupyterLab tool environment first.
--compact flag saves significant tokens — always use it. JSON output can be very verbose without it.
For pure REPL use, create a scratch.ipynb and don't bother with cell editing. Just use
```
execute
```
repeatedly.
Argument order matters — subcommand flags like
```
--path
```
go BEFORE the sub-subcommand. E.g.:
```
variables --path nb.ipynb list
```
not
```
variables list --path nb.ipynb
```
.
If a session doesn't exist yet, you need to start one via the REST API (see Setup section). The tool can't execute without a live kernel session.
Errors are returned as JSON with traceback — read the
```
ename
```
and
```
evalue
```
fields to understand what went wrong.
Occasional websocket timeouts — some operations may timeout on first try, especially after a kernel restart. Retry once before escalating.

服务器启动后的首次执行可能超时 —— 内核需要一点时间初始化。如果遇到超时，只需重试。
内核使用的Python是JupyterLab的Python —— 必须在该环境中安装依赖包。如果需要额外的包，请先安装到JupyterLab工具环境中。
--compact参数能大幅节省令牌 —— 请始终使用。没有该参数时，JSON输出可能非常冗长。
如果仅用于纯REPL，创建一个scratch.ipynb即可，无需费心编辑单元格。只需反复使用
```
execute
```
命令。
参数顺序很重要 —— 子命令的参数（如
```
--path
```
）必须放在子子命令之前。例如：
```
variables --path nb.ipynb list
```
而非
```
variables list --path nb.ipynb
```
。
如果会话尚未存在，你需要通过REST API启动一个（见设置步骤）。没有实时内核会话，本工具无法执行代码。
错误会以JSON格式返回，包含回溯信息 —— 请查看
```
ename
```
和
```
evalue
```
字段以了解问题所在。
偶尔会出现WebSocket超时 —— 某些操作首次尝试可能超时，尤其是在内核重启后。在上报问题前请重试一次。

Timeout Defaults

默认超时设置

The script has a 30-second default timeout per execution. For long-running operations, pass

--timeout 120

. Use generous timeouts (60+) for initial setup or heavy computation.

脚本默认每次执行的超时时间为30秒。对于长时间运行的操作，请传递

--timeout 120

参数。在初始设置或重型计算场景下，请设置充足的超时时间（60秒以上）。