Introduction

In DeepSeek Harness (DSH), agents calling one-off scripts struggle to handle stateful Python analysis sessions: variables are loaded into memory, models are constructed, and data is preprocessed, but the next step requires modifying code, observing output, and adjusting based on the traceback. Standard notebooks are often static result files, not necessarily convenient for agents to continuously read, modify, run, and check.

Below introduces beihzb/dsh-notebook. It is a DSH plugin aiming to make notebooks objects that agents can manipulate.

What is this

beihzb/dsh-notebook is a DSH plugin maintained by beihzb, licensed under MIT. The plugin package name is @beihaizb/dsh-notebook, and the repository directory name is beihzb/dsh-notebook.

It provides a stateful, agent-controllable Jupyter workspace: DSH agents can read, edit, execute, and inspect notebook cells, and manipulate a persistent ipykernel runtime. The plugin also provides a cell UI aligned with VS Code, as well as standard .ipynb save/load capabilities.

Core Features

Persistent Kernel & Agent Tools

The plugin uses a real ipykernel/jupyter_client sidecar. Variables can be kept across multiple cells; the agent does not just concatenate strings but can manipulate the runtime environment of existing variables, data, and model states.

Agents can call these tools:

  • nb_get: Read a cell or notebook state.
  • nb_edit_cell: Edit cell code.
  • nb_run_cell: Run a cell.
  • nb_context, nb_list_vars, nb_inspect_object: View runtime variables and compact notebook state.

Execution results provide structured output and tracebacks to help the agent determine the next step.

Safe Editing & Version History

The plugin provides several categories of tools around the AI editing loop:

  • per-cell version snapshots
  • nb_cell_history
  • nb_revert_cell
  • nb_error_context
  • nb_edit_and_run_cell

These capabilities enable an auditable “modify-re-run” process. Each execution is also recorded in cell.metadata.dsh.executions, retaining up to 50 entries per cell.

Structured Execution Results & Long Output Protection

Run-class tools return a structured execution envelope containing:

status
execution_count
duration_ms
stdout / stderr
outputs_summary
error
traceback_text

For long outputs, the plugin has protection: a driver cap (500 KB) per stream, a head+tail summary (6 KB) retained in the envelope, and the full merged text written to <notebook>_files/.

VS Code Aligned Cell UI & Execution Semantics

The plugin provides a cell experience and execution semantics aligned with VS Code, including:

  • Queued / Executing status
  • Restart
  • Interrupt
  • Run All
  • Clear Outputs
  • Restart & Clear

Output support includes tqdm progress bars, inline figures click-to-enlarge, long output collapsing, and multi-image grids.

Error navigation supports clicking traceback frames to jump to the erroring cell.

Session Isolation & Kernel Management

Each DSH session owns an independent notebook, kernel, and working directory to avoid cross-session state leakage. Multiple sessions can run kernels simultaneously.

Kernel management entry is in the toolbar popup: you can list active kernels across sessions and directly close a session’s kernel.

If dsh web is forcibly terminated, the Python sidecar detects parent process death and automatically closes its ipykernel.

The Kernel picker provides installation prompts when ipykernel is missing.

Other Experiences

  • Standard .ipynb save/load with autosave and unsaved changes reminders.
  • Bilingual EN / Chinese UI, one-click toolbar switch, language selection retained across sessions.
  • On big.LITTLE machines, you can use a copy-ready psutil snippet or OS scheduler tool to bind Python processes to performance cores.

Installation & Enablement

Installation command:

dsh plugin add @beihaizb/dsh-notebook

This command uses the scoped npm/bundle name @beihaizb/dsh-notebook and the plugin loads out of the box. The plugin requires the following peer dependencies:

"@deepseek-ai/cordis": "^4.0.1",
"@deepseek-ai/dsh-tools": "^0.1.0-rc.6"

Typical Usage

  1. Let the agent modify a stateful session: for example, a user asks to “Switch Harmony integration to scVI”. The agent finds relevant cells, reads source/context, edits the cell, executes it, checks stdout/traceback, and iterates if necessary.
  2. One cell for AI: input a modification request in the per-cell revision box; the agent edits and re-runs that cell.
  3. Manage kernel: open the toolbar popup to list all current active kernels and close a specific session’s kernel.
  4. CPU binding: on big.LITTLE machines, use a copy-ready psutil snippet or OS scheduler tool to pin the Python process to performance cores.

Applicable Scenarios & Notes

Suitable for:

  • Developers in DSH who want agents to manipulate persistent Python notebooks.
  • Scenarios where agents need to view runtime variables, check outputs, and re-run cells based on errors.
  • Scenarios requiring .ipynb save/load capabilities while maintaining session isolation and kernel management.

Notes:

  • The plugin runs with the permissions of the current dsh process. You should check the source code, license, and peer dependencies before installing.
  • This article describes only verified facts; repository star counts, category tags, and other clue-based information are not cited as facts here.

View & Feedback

GitHub repository:

https://github.com/beihzb/dsh-notebook

Directory page (clues provided in this article):

https://www.skillhub.cn/plugins/beihzb/dsh-notebook