前言¶
在 DSH 裏跑 Python，多數人靠聊天框裏的代碼塊：改一個變量要重發一遍，輸出散在多條消息裏，圖表沒法回看。也有人用外部 JupyterLab，但上下文和工作區割開了。dsh-notebook-v2 走的是第三條路：把一個常駐內核的 notebook 面板塞進右欄，用 CodeMirror 6 編輯、SSE 流式輸出、nb_* 工具驅動，目標是「在 DSH 裏也有 VS Code Notebook 的手感」。
這是什麼¶
這是 LearnItHard 維護的客戶端類插件，定位是 DeepSeek Harness 的自研 Jupyter 前端。倉庫在 GitHub，MIT 許可，要求 Node ≥ 20，適配 DSH Desktop 0.2.1-rc.x。它解決的是三件事：常駐內核、.ipynb 讀寫無損、以及把 AI 改寫直接做進單元格里。目前社區目錄裏的星標只有 1 顆，屬於起步階段的小項目，功能面卻鋪得比較完整。
核心功能¶
先說清楚能力邊界。它能做：常駐內核（變量跨格保留），流式輸出（print 逐行往外冒，一萬行只產生一個輸出塊），多標籤同時開多個 notebook，.ipynb 的語義等價讀寫。
單元格分四種類型，每格左側下拉切換：
代碼：走 ipykernel，需要 Python 環境。Markdown：默認渲染，點一下進編輯，支持表格、公式、代碼塊、引用。Shell：獨立子進程，cmd/bash/pwsh自動選，不需要 Python 內核。寫成.ipynb後是帶%%bash魔法行的標準 code 格，在 JupyterLab 和 VS Code 裏仍然合法。Raw：原樣保留。
輸出渲染支持 text/html（沙箱 iframe 加高度回傳）、圖片、application/json 摺疊樹、text/latex（KaTeX）、markdown。超長輸出只渲染「頭 300 + 尾 100 + 展開按鈕」，避免界面被刷屏。
大綱面板（≡ 大綱）列出 markdown 標題（按級別縮進，代碼塊裏的 # 不算標題）加每格首行，點擊跳轉。寬度可拖、鬆手記住，雙擊分隔條復位 200px。markdown 格子如果首個非空行是標題（ATX 的 #…######，或 setext 的 === / ---），左側出現 ▾，可以整節摺疊，對齊 VS Code Notebook 的行爲。摺疊狀態只活在當前面板裏，切走會話或關掉標籤就恢復展開，不落盤。
AI 側有兩個入口：
1、AI 補全 開關（默認關，會消耗 token）。停止輸入約 0.5s 後，光標處出現灰色續寫建議，Tab 接受、Esc 丟棄，一打字就作廢。超時或失敗靜默處理。
2、AI 內聯改寫，快捷鍵 Mod-K。給一條指令，模型逐 token 流式返回，然後以行級 diff（+N −M）展示，Mod-↵ 接受、接受並運行、重試、Esc 拒絕。後端走宿主的 ctx.llm.stream()，provider/model 從 config.ai 讀，留空就自動解析。
讀寫無損這一點值得單獨說：讀進來再寫回是語義等價的，attachments、metadata.widgets、歷史插件寫入的 metadata.dsh，以及不認識的字段全部原樣保留。所以拿它編輯已有 notebook，不會把你之前的附件和元數據喫掉。
明確不做的（v1 非目標）：ipywidgets 交互、調試器、遠程 / SLURM 內核、多人協作、Monaco 級類型檢查。
安裝與啓用¶
官方給出的安裝方式是腳本安裝，沒有用到包管理器：
git clone https://github.com/LearnItHard/dsh-notebook-v2.git
cd dsh-notebook-v2
node scripts/install.mjs
這一步把插件寫進 profile。重啓 DeepSeek Harness 或重載窗口後，右欄「+」裏會出現 Notebook (v2)。
常用變體：
node scripts/install.mjs --profile <profile目錄> # 裝進別的 profile，默認 ~/.dsh/profiles/desktop
node scripts/install.mjs --dry-run # 先看它會改什麼，不落盤
node scripts/uninstall.mjs # 卸載
腳本是冪等的，寫之前會自動備份 profile 的 package.json。內核需要 ipykernel；沒裝 Python 也能用 Shell 格，走 bash / pwsh 子進程。
裝完想快速驗證，打開 docs/demo/demo.ipynb，點 ▶ 運行全部 就能看到上面這些效果。
典型用法¶
啓動後先確認內核選對了。工具欄第 3 行的內核下拉是會話級的，切換會重啓內核。沒手動選時，插件按這個順序自動挑：
config.python（cordis.patch.yml裏填了就用它）python-env插件在本會話或父會話裏選過的解釋器- 掃本機 conda 環境，挑第一個真裝了
ipykernel的 - 最後回落到
PATH上的python
下拉里沒有你的環境，或者報 No module named 'ipykernel'，就在那個環境裏執行 pip install ipykernel，再回工具欄選中它。
想確認內核最終選了誰：
curl http://127.0.0.1:<port>/nb2/diagnostics
返回候選內核列表、各自是否裝了 ipykernel、以及最終選中誰。
運行類操作都在編輯態快捷鍵裏：Shift-Enter 運行並下移，Ctrl(-Alt)-Enter 運行，Alt-Enter 運行並插格，Mod-S 保存，Mod-F 查找。容器態下 Enter 進格、↑↓ 選格、Delete 刪格、Esc 退出編輯。
適用場景與注意事項¶
適合需要在 DSH 裏同時做探索、畫圖、審查模型輸出的人，尤其是已經把 .ipynb 當工作草稿在維護的團隊。Shell 格的存在讓它在沒有 Python 環境的機器上也能用，做純命令行的快速驗證。
三點需要留意：
1、併發衝突。@beihaizb/dsh-notebook 是第三方插件，本項目不依賴它，但兩者的 nb_* 工具名完全相同，同時啓用會重複註冊同名工具。只能二選一。可以並存安裝，只是不能同時啓用。項目提供的腳本只改加載列表，不碰另一個插件的文件和數據：
node scripts/retire-old-plugin.mjs # 把舊插件從加載列表裏去掉
node scripts/retire-old-plugin.mjs --rollback # 再裝回加載列表
2、權限與信任。插件以當前 DSH 進程的權限運行，腳本會寫 profile、改 package.json 加載列表。安裝前建議先 --dry-run 看改動範圍，並通讀倉庫代碼與 MIT 許可證，確認接受再裝。本項目是小團隊維護的起步階段項目，星標只有 1，遇到問題優先看倉庫裏的 AGENTS.md 和 docs/ 下的排障文檔。
3、範圍取捨。沒有調試器和遠程內核，如果你的工作流重度依賴 interactive widget 或 SLURM 批量調度，這個插件覆蓋不了，仍然需要外部 JupyterLab。
小結¶
dsh-notebook-v2 的價值在於把「編輯、運行、看輸出、讓 AI 改代碼」這幾件事收進 DSH 右欄一個面板裏，常駐內核和無損讀寫讓它能直接接管現有的 .ipynb 草稿，而不只是聊天裏的代碼塊。功能上它是自研實現，落地細節（SSE 流式、CodeMirror 6、nb_* 工具）都有對應文檔可查。
插件目錄頁：https://www.skillhub.cn/plugins/LearnItHard/dsh-notebook-v2
倉庫：https://github.com/LearnItHard/dsh-notebook-v2
協議文檔：docs/api-nb2.md（端點契約）、docs/protocol-ndjson.md（sidecar 協議）
