跳到主要內容

Jupyter Live Kernel

通過實時 Jupyter kernel (hamelnb) 進行迭代式 Python 編程。

技能元數據​

來源捆綁（默認安裝）
路徑skills/data-science/jupyter-live-kernel
版本1.0.0
作者Hermes Agent
許可證MIT
平臺linux, macos, windows
標籤jupyter, notebook, repl, data-science, exploration, iterative

參考：完整 SKILL.md​

信息

以下是 Hermes 在觸發此技能時加載的完整技能定義。這是技能激活時代理看到的指令。

Jupyter Live Kernel (hamelnb)

通過實時 Jupyter kernel 為你提供有狀態的 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

注意：為本地代理訪問禁用了 Token/密碼。服務器以無頭模式運行。

創建用於 REPL 的 Notebook​

如果你只需要一個 REPL（沒有現有的 notebook），創建一個最小的 notebook 文件：

mkdir -p ~/notebooks

編寫一個包含一個空代碼單元格的最小 .ipynb JSON 文件，然後通過 Jupyter REST API 啟動 kernel 會話：

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 以節省 token。

1. 發現服務器和 notebook​

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. 編輯 notebook 單元格​

# View current cells \{#3-inspect-live-variables}
uv run "$SCRIPT" contents --path <notebook.ipynb> --compact

# Insert a new cell \{#4-edit-notebook-cells}
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) \{#5-verification-restart--run-all}
uv run "$SCRIPT" edit --path <notebook.ipynb> replace-source \
  --cell-id <id> --source '<new code>' --compact

# Delete a cell \{#practical-tips-from-experience}
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. 服務器啟動後的首次執行可能會超時 — kernel 需要片刻時間初始化。如果遇到超時，只需重試。

  2. Kernel 使用的 Python 是 JupyterLab 的 Python — 包必須安裝在該環境中。如果需要額外的包，請先將它們安裝到 JupyterLab 工具環境中。

  3. --compact 標誌可顯著節省 token — 始終使用它。否則 JSON 輸出可能非常冗長。

  4. 對於純 REPL 用途，創建一個 scratch.ipynb 且無需關心單元格編輯。只需重複使用 execute。

  5. 參數順序很重要 — 子命令標誌（如 --path）應放在子子命令之前。例如：variables --path nb.ipynb list 而不是 variables list --path nb.ipynb。

  6. 如果會話尚不存在，你需要通過 REST API 啟動一個（參見設置部分）。如果沒有活動的 kernel 會話，工具無法執行。

  7. 錯誤以 JSON 形式返回，包含 traceback — 閱讀 ename 和 evalue 字段以瞭解出錯原因。

  8. 偶爾出現 websocket 超時 — 某些操作可能在首次嘗試時超時，尤其是在 kernel 重啟後。在升級處理前重試一次。

超時默認值​

腳本每次執行的默認超時時間為 30 秒。對於長時間運行的操作，傳遞 --timeout 120。對於初始設置或繁重計算，使用較大的超時時間（60+）。