mcpField
J
jupyter-live-kernel

jupyter-live-kernel

github.com/nousresearch数据与数据库258.1k352 次安装今天更新
代码仓库

关于 jupyter-live-kernel

通过实时 Jupyter 内核提供有状态的 Python REPL，适合需要逐步探索、数据科学分析和笔记本式工作的 Agent。变量和导入内容会在多次执行间保留。

主要功能

  1. 01保留 Python 内核状态
  2. 02逐步执行代码
  3. 03检查实时变量
  4. 04查看和编辑笔记本单元格
  5. 05重启并运行全部单元格

适用场景

  1. 01连续运行代码以探索 API
  2. 02分析时检查 DataFrame
  3. 03逐步构建复杂代码

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/nousresearch/hermes-agent --skill jupyter-live-kernel

安装后在 Claude Code 中输入/jupyter-live-kernel确认已加载。

详细介绍

Jupyter Live Kernel（hamelnb）

通过实时 Jupyter 内核提供有状态的 Python REPL。变量会在多次执行之间保留。需要逐步构建状态、探索 API、检查 DataFrame 或迭代编写复杂代码时，请使用它，而不是 execute_code。

何时使用此工具或其他工具

工具适用场景
此技能迭代探索、跨步骤保留状态、数据科学、ML、“让我试试并检查一下”
execute_code需要使用 hermes 工具（web_search、文件操作）的一次性脚本。无状态。
terminalShell 命令、构建、安装、git、进程管理

**经验法则：**如果任务适合用 Jupyter notebook，就使用此技能。

前提条件

  1. 必须安装 uv（检查：which uv）
  2. 必须安装 JupyterLab：uv tool install jupyterlab
  3. 必须有一个正在运行的 Jupyter 服务（见下方“设置”）

设置

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

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

创建用于 REPL 的 Notebook

如果只需要 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"}}'

核心工作流

所有命令都会返回结构化 JSON。始终使用 --compact 以节省令牌。

1. 发现服务和 notebook
uv run "$SCRIPT" servers --compact
uv run "$SCRIPT" notebooks --compact
2. 执行代码（主要操作）
uv run "$SCRIPT" execute --path <notebook.ipynb> --code '<python code>' --compact

状态会在多次执行调用之间保留。变量、导入和对象都会继续存在。

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

uv run "$SCRIPT" execute --path scratch.ipynb --code $'import os\nfiles = os.listdir(".")\nprint(f"Found {len(files)} files")' --compact
3. 检查实时变量
uv run "$SCRIPT" variables --path <notebook.ipynb> list --compact
uv run "$SCRIPT" variables --path <notebook.ipynb> preview --name <varname> --compact
4. 编辑 notebook 单元
# 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)
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
5. 验证（重启并运行全部单元）

仅当用户要求进行干净验证，或你需要确认 notebook 能从头到尾运行时使用：

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

实用经验提示

  1. 服务启动后的首次执行可能会超时——内核需要一些时间来初始化。如果遇到超时，只需重试。

  2. 内核使用的是 JupyterLab 的 Python——软件包必须安装在该环境中。如果需要其他软件包，请先将其安装到 JupyterLab 工具环境中。

  3. --compact 标志可显著节省令牌——务必使用。否则 JSON 输出可能会非常冗长。

  4. 纯 REPL 用法：创建一个 scratch.ipynb，无需编辑单元。只需反复使用 execute。

  5. 参数顺序很重要——子命令标志（如 --path）要放在子子命令之前。例如：variables --path nb.ipynb list，而不是 variables list --path nb.ipynb。

  6. 如果会话尚不存在，需要通过 REST API 启动一个会话（见“设置”部分）。没有实时内核会话时，该工具无法执行代码。

  7. 错误会以 JSON 和回溯信息的形式返回——查看 ename 和 evalue 字段，了解出错原因。

  8. 偶尔会发生 WebSocket 超时——某些操作首次尝试时可能会超时，尤其是在内核重启后。升级处理前先重试一次。

默认超时

该脚本每次执行的默认超时时间为 30 秒。对于长时间运行的操作，请传入 --timeout 120。初始设置或繁重计算时，请使用较宽裕的超时时间（60 秒以上）。

评论

支持 Markdown