跳到主要内容

Jupyter Live Kernel

通过实时 Jupyter 内核进行迭代式 Python 编程 (hamelnb)。

技能元数据​

源代码内置 (默认安装)
路径skills/data-science/jupyter-live-kernel
版本1.0.0
作者Hermes 智能体
许可证MIT
平台linux, macos, windows
标签jupyter, notebook, repl, data-science, exploration, iterative

参考：完整的 SKILL.md​

信息

以下是当此技能被触发时，Hermes 加载的完整技能定义。这就是智能体在技能激活时看到的指令。

Jupyter Live Kernel (hamelnb)

通过一个实时的 Jupyter 内核为你提供一个有状态的 Python REPL。变量会在执行间保持。当你需要增量地构建状态、探索 API、检查 DataFrame 或迭代复杂代码时，请使用这个工具，而不是 execute_code。

何时使用此工具而非其他工具​

工具使用场景
本技能迭代式探索、跨步骤保持状态、数据科学、机器学习、“让我试试这个并检查一下”
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

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

创建一个用于 REPL 的笔记本​

如果你只需要一个 REPL（没有现有笔记本），创建一个最小的笔记本文件：

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 以节省 tokens。

1. 发现服务器和笔记本​

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

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

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. 检查活动变量​

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

4. 编辑笔记本单元格​

# 查看当前单元格
uv run "$SCRIPT" contents --path <notebook.ipynb> --compact

# 插入一个新单元格
uv run "$SCRIPT" edit --path <notebook.ipynb> insert \
  --at-index <N> --cell-type code --source '<code>' --compact

# 替换单元格源码（使用 contents 输出中的 cell-id）
uv run "$SCRIPT" edit --path <notebook.ipynb> replace-source \
  --cell-id <id> --source '<new code>' --compact

# 删除一个单元格
uv run "$SCRIPT" edit --path <notebook.ipynb> delete --cell-id <id> --compact

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

仅在用户要求进行干净验证或你需要确认笔记本能从上到下完整运行时才使用：

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

来自经验的实用技巧​

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

  2. 内核使用的 Python 是 JupyterLab 的 Python — 包必须安装在该环境中。如果你需要额外的包，请先将它们安装到 JupyterLab 的工具环境中。

  3. --compact 标志可以节省大量 tokens — 务必使用它。没有它，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+）。