Jupyter 实时内核

通过实时 Jupyter 内核给你一个有状态的 Python REPL。变量在执行间持久化。当你需要增量构建状态、探索 API、检查 DataFrame 或迭代复杂代码时使用此工具。

使用场景：此工具 vs 其他工具

经验法则：如果任务你会想要 Jupyter notebook，用此 skill。

前置条件

• uv 必须安装（检查：which uv）
• JupyterLab 必须安装：uv tool install jupyterlab
• 必须运行 Jupyter 服务器（见下方 Setup）

安装配置

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

启动 JupyterLab

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

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

核心工作流

所有命令返回结构化 JSON。始终使用 --compact 节省 token。

1. 发现服务器和 notebook

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

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

uv run "$SCRIPT" execute --path  --code '' --compact

状态在执行调用间持久化。变量、导入、对象都存活。

多行代码用 $'...' 引用：

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

3. 检查实时变量

uv run "$SCRIPT" variables --path  list --compact
uv run "$SCRIPT" variables --path  preview --name  --compact

4. 编辑 notebook 单元格

# 查看当前单元格
uv run "$SCRIPT" contents --path  --compact

# 插入新单元格
uv run "$SCRIPT" edit --path  insert 
  --at-index  --cell-type code --source '' --compact

# 替换单元格源代码
uv run "$SCRIPT" edit --path  replace-source 
  --cell-id  --source '' --compact

# 删除单元格
uv run "$SCRIPT" edit --path  delete --cell-id  --compact

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

仅在用户要求干净验证或你需要确认 notebook 从上到下运行时使用：

uv run "$SCRIPT" restart-run-all --path  --save-outputs --compact

经验实用技巧

• 服务器启动后首次执行可能超时——内核需要片刻初始化。如果超时，只需重试。
• 内核 Python 是 JupyterLab 的 Python——包必须安装在该环境中。
• --compact 标志节省大量 token——始终使用它。
• 对于纯 REPL 使用，创建 scratch.ipynb 并不用管单元格编辑。只需重复使用 execute。
• 参数顺序很重要——子命令标志如 --path 放在子子命令前。
• 错误以 JSON 返回带 traceback——阅读 ename 和 evalue 字段。

超时默认值

脚本每次执行有 30 秒默认超时。对于长时间运行操作，传递 --timeout 120。