Introduction¶

Running Python in DSH, most people rely on code blocks in the chat box: changing a variable requires resending it, outputs are scattered across multiple messages, and charts can’t be reviewed. Some also use external JupyterLab, but the context and workspace are disconnected. dsh-notebook-v2 takes the third path: it squeezes a persistent kernel notebook panel into the right column, uses CodeMirror 6 for editing, SSE streaming output, and nb_* tools to drive it, with the goal of “having a VS Code Notebook feel inside DSH.”

What is this¶

This is a client-side plugin maintained by LearnItHard, positioned as DeepSeek Harness’s proprietary Jupyter frontend. The repo is on GitHub, MIT licensed, requires Node ≥ 20, and is compatible with DSH Desktop 0.2.1-rc.x. It solves three things: persistent kernel, lossless .ipynb read/write, and integrating AI rewriting directly into cells. Currently, there is only 1 star in the community directory; it’s a starter project with a relatively complete feature set.

Core Features¶

First, let’s clarify the capability boundaries. It can do: persistent kernel (variables retained across cells), streaming output (print lines popping out one by one, 10,000 lines only produce one output block), opening multiple notebooks in multiple tabs simultaneously, and semantic equivalent read/write of .ipynb.

Cells are divided into four types, switched via a dropdown on the left side of each cell:

• Code: Uses ipykernel, requires a Python environment.
• Markdown: Renders by default; click to enter edit mode. Supports tables, formulas, code blocks, and quotes.
• Shell: Independent subprocess, automatically selects cmd / bash / pwsh, does not require a Python kernel. Written as .ipynb, it becomes a standard code format with %%bash magic lines, which is still valid in JupyterLab and VS Code.
• Raw: Preserved as-is.

Output rendering supports text/html (sandboxed iframe with height callback), images, application/json collapsible trees, text/latex (KaTeX), and markdown. For very long outputs, only “head 300 + tail 100 + expand button” are rendered to avoid screen clutter.

The Outline panel (≡ Outline) lists markdown headings (indented by level, # inside code blocks doesn’t count as headings) plus the first line of each cell; clicking jumps to it. The width is draggable and remembered on release. Double-clicking the divider resets it to 200px. If the first non-empty line of a markdown cell is a heading (ATX #…###### or setext === / ---), a ▾ appears on the left, allowing the whole section to be collapsed, aligning with VS Code Notebook behavior. The collapsed state only lives in the current panel; switching sessions or closing tabs restores the expanded state and is not persisted to disk.

There are two entry points on the AI side:

1. AI Completion toggle (off by default, consumes tokens). After stopping input for about 0.5s, a gray continuation suggestion appears at the cursor. Tab accepts, Esc discards, and it becomes invalid as soon as you type. Timeouts or failures are handled silently.
2. AI Inline Rewrite, shortcut Mod-K. Give an instruction, the model returns a stream token by token, then displays it as a line-level diff (+N -M). Mod-Enter accepts, accept and run, retry, Esc rejects. The backend uses the host’s ctx.llm.stream(), provider/model is read from config.ai, and if empty, it is automatically parsed.

The lossless read/write aspect deserves special mention: reading it back and writing it out is semantically equivalent. attachments, metadata.widgets, metadata.dsh written by history plugins, and unrecognized fields are all preserved as-is. So using it to edit existing notebooks won’t eat your previous attachments and metadata.

Clearly not doing (non-goal of v1): ipywidgets interaction, debugger, remote / SLURM kernels, multi-user collaboration, Monaco-level type checking.

Installation and Activation¶

The official installation method is via a script, not a package manager:

git clone https://github.com/LearnItHard/dsh-notebook-v2.git
cd dsh-notebook-v2
node scripts/install.mjs

This step writes the plugin into the profile. After restarting DeepSeek Harness or reloading the window, Notebook (v2) will appear in the right column’s “+”.

Common variants:

node scripts/install.mjs --profile <profile directory>    # Install into another profile, default ~/.dsh/profiles/desktop
node scripts/install.mjs --dry-run                      # See what it will change first, don't write to disk
node scripts/uninstall.mjs                              # Uninstall

The script is idempotent; it automatically backs up the profile’s package.json before writing. The kernel needs ipykernel; you can also use Shell format without Python installed, using bash / pwsh subprocesses.

To quickly verify after installation, open docs/demo/demo.ipynb and click ▶ Run All to see the effects mentioned above.

Typical Usage¶

After starting, first confirm the kernel is selected correctly. The kernel dropdown in the third row of the toolbar is session-level; switching sessions restarts the kernel. If not manually selected, the plugin automatically picks in this order:

1. config.python (used if filled in cordis.patch.yml)
2. python-env plugin’s interpreter selected in the current or parent session
3. Scan local conda environments, pick the first one that actually has ipykernel installed
4. Finally fall back to python on PATH

If your environment isn’t in the dropdown, or it reports No module named 'ipykernel', execute pip install ipykernel in that environment, then select it from the toolbar again.

To confirm which kernel was ultimately selected:

curl http://127.0.0.1:<port>/nb2/diagnostics

Returns a list of candidate kernels, whether each has ipykernel installed, and who was ultimately selected.

Runtime operations are in edit mode shortcuts: Shift-Enter run and move down, Ctrl(-Alt)-Enter run, Alt-Enter run and insert cell, Mod-S save, Mod-F find. In container mode, Enter enters cell, ↑↓ selects cell, Delete deletes cell, Esc exits edit.

Applicable Scenarios and Considerations¶

Suitable for people who need to explore, plot, and review model outputs in DSH simultaneously, especially teams already maintaining .ipynb as working drafts. The existence of the Shell format allows it to be used on machines without a Python environment for pure command-line quick verification.

Three points to watch out for:

1. Concurrency Conflict. @beihaizb/dsh-notebook is a third-party plugin. This project does not depend on it, but both use the same nb_* tool names, and enabling both will result in duplicate registration of the same tools. You can only choose one. They can be installed simultaneously, just not enabled at the same time. The scripts provided by this project only modify the loading list and do not touch the other plugin’s files and data:

    node scripts/retire-old-plugin.mjs              # Remove the old plugin from the loading list
    node scripts/retire-old-plugin.mjs --rollback   # Add the old plugin back to the loading list

2. Permissions and Trust. The plugin runs with the permissions of the current DSH process. The script will write to the profile and modify the package.json loading list. It is recommended to run --dry-run before installation to see the scope of changes, and read through the repository code and MIT license to confirm you accept them before installing. This is a starter project maintained by a small team with only 1 star. If you encounter issues, prioritize checking AGENTS.md and troubleshooting docs in docs/.

3. Scope Trade-offs. Without a debugger or remote kernel, if your workflow relies heavily on interactive widgets or SLURM batch scheduling, this plugin won’t cover it, and you will still need external JupyterLab.

Summary¶

The value of dsh-notebook-v2 lies in putting “editing, running, viewing output, and letting AI rewrite code” into a single panel in the DSH right column. The persistent kernel and lossless read/write allow it to take over existing .ipynb drafts directly, rather than just code blocks in chat. Functionally, it is a custom implementation; the implementation details (SSE streaming, CodeMirror 6, nb_* tools) have corresponding documentation to check.

Plugin directory page: https://www.skillhub.cn/plugins/LearnItHard/dsh-notebook-v2
Repository: https://github.com/LearnItHard/dsh-notebook-v2
Protocol docs: docs/api-nb2.md (endpoint contracts), docs/protocol-ndjson.md (sidecar protocol)