title: “Jupyter Notebook — Iterative Python via live Jupyter kernel (hamelnb)” sidebar_label: “Jupyter Notebook” description: “Iterative Python via live Jupyter kernel (hamelnb)”

{/* 本页面由 website/scripts/generate-skill-docs.py 根据技能对应的 SKILL.md 文件自动生成。请直接编辑源文件 SKILL.md，而非此页面。 */}

Jupyter Notebook

通过实时运行的 Jupyter 内核（hamelnb）实现迭代式 Python 开发。

技能元数据


来源	可选 —— 使用 `hermes skills install official/data-science/jupyter-notebook` 安装
路径	`optional-skills/data-science\jupyter-notebook`
版本	`1.0.0`
开发者	Hermes Agent
许可证	MIT
支持平台	linux、macos、windows
标签	`jupyter`、`notebook`、`repl`、`data-science`、`exploration`、`iterative`

参考：完整的 SKILL.md 文件

:::info 以下是当触发该技能时 Hermes 所加载的完整技能定义。技能处于激活状态时，Agent 就会看到这些指令作为操作指南。: ::

Jupyter Notebook（hamelnb 实时内核）

通过实时运行的 Jupyter 内核为您提供具有状态保持功能的 Python REPL 环境。变量会在多次执行之间持续保留。当您需要逐步构建状态、测试 API、查看 DataFrame 数据或对复杂代码进行迭代优化时，可选用此功能而非 execute_code。

何时选择该工具而非其他工具

工具	适用场景
本技能	迭代式探索、跨步骤保持状态、数据科学、机器学习任务，以及需要“先尝试再验证”的场景
`execute_code`	需要使用 Hermes 提供的工具（如 web_search、文件操作）的一次性脚本，且无需状态保持
`terminal`	执行 Shell 命令、编译代码、安装软件、操作 Git 以及进程管理
经验法则：如果您需要使用 Jupyter notebook 来完成该任务，请使用此技能。

先决条件

必须已安装 uv（检查方法：which uv）
必须已安装 JupyterLab：uv tool install jupyterlab
必须正在运行 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":"python"}}'

核心工作流程

所有命令都会返回结构化的 JSON 数据。为节省令牌使用量，请始终使用 --compact 参数。

1. 发现服务器与笔记本

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. 编辑笔记本单元格

# 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. 验证（重启并运行全部）

仅当用户要求进行彻底的验证，或您需要确认代码笔记本能从始至终正常运行时才使用此选项。

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

实战经验技巧

服务器启动后的首次执行可能会超时——内核需要一些时间来初始化。如果出现超时情况，只需重新尝试即可。
内核使用的 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 超时现象——某些操作在首次尝试时可能会超时，尤其是在内核重启之后。在升级处理之前，先尝试重新执行一次。
如果在该主机上 WebSocket 连接持续超时，可强制使用 ZMQ 传输方式： uv run "$SCRIPT" execute --transport zmq ...。出现此问题的表现为：每次执行都会返回 “Websocket 执行可能已到达内核层，因此跳过了自动回退机制”。实际上内核运行正常（REST 接口显示 execution_state 为 idle，且 execution_count 会递增）——仅是 WebSocket 回复通道出现了故障。ZMQ 传输方式直接使用 jupyter_client，从而避免了该问题。
在启动仅用于 REST 接口的全新服务器时，请添加参数 --ServerApp.disable_check_xsrf=True —— 否则 POST /api/sessions 请求会返回 “POST 请求中缺少 ‘_xsrf’ 参数”，从而导致内核会话创建失败。

超时默认设置

该脚本的默认每次执行超时时间为 30 秒。对于需要长时间运行的操作，可设置 --timeout 120。在初始设置或进行复杂计算时，建议使用较长的超时时间（60 秒以上）。

Keyboard shortcuts

Hermes Agent Docs i18n