前言¶

在 DeepSeek Harness（DSH）裏做數據分析或腳本驗證時，工作區裏往往已經放着 .ipynb 文件。常見做法是切到 Jupyter Lab、VS Code 或獨立終端，和 DSH 的 Web 界面、Better Sidebar 文件樹分開操作。維護者 kexiongwen 的客戶端插件 dsh-bsb-ipynb 把 Better Sidebar 右側文件樹變成 Jupyter 工作區：點選筆記本即可閱讀、編輯、執行並保存，內核在宿主機進程裏通過 jupyter_client + ipykernel 運行，瀏覽器側不跑 Python，也沒有前端構建步驟。

這是什麼¶

dsh-bsb-ipynb 是 DSH Better Sidebar 的配套插件（倉庫：kexiongwen/dsh-bsb-ipynb，當前 package.json 版本 0.1.0，許可證 MIT）。它在 DSH Web GUI 的文件樹中打開 .ipynb，交互方式接近 Jupyter：單元格渲染、編輯、按單元或全部運行、自動保存與手動保存。插件通過 Cordis 補丁掛到 Better Sidebar，屬於 DSH 社區目錄中的客戶端類插件。

核心功能¶

以下能力均來自項目 README 與 package.json 說明。

渲染與輸出¶

• Markdown、代碼、raw 單元格，帶執行計數。
• 標準輸出/錯誤流式顯示；支持 text/html（按白名單消毒）、PNG/JPEG/SVG、Markdown、JSON、帶 ANSI 顏色的回溯。
• Markdown 與 HTML 中的圖片：attachment:、相對路徑等經宿主機文件路由解析；http(s) 與 data:image 按原樣加載。

編輯與執行¶

• 點擊單元格編輯；可插入/刪除、上下移動、切換單元類型、預覽 Markdown、清除單個或全部輸出。
• 每個筆記本按文件路徑綁定一個持久內核，變量在單元格之間保留。
• 支持 Run all、中斷、重啓、關閉內核。

保存與安全¶

• 寫入 nbformat 4.5，用 sha256 做樂觀併發；衝突返回 409，不覆蓋遠端內容。
• 同目錄臨時文件再 rename 的原子寫；編輯後約 1.5 s 自動保存。
• 路徑限制在會話工作區內（realpath + 相對路徑檢查）；HTTP 走 DSH 准入圍欄；HTML 輸出經 DOMParser 白名單處理，不執行 <script>。

解釋器發現¶

按順序探測：DSH_IPYNB_PYTHON（須爲絕對路徑）、conda 環境、PATH 上的 python3/python、DSH 捆綁 Python；僅選用已安裝 jupyter_client 與 ipykernel 的環境。可通過環境變量 DSH_IPYNB_PYTHON 指定絕對路徑下的解釋器。

與 DSH 界面一致¶

顏色與 DSH 主題、--dsw-alias-* 及 Shiki 變量對齊；中英文 UI 字符串在 dsh-bsb-ipynb 語言包中註冊，跟隨 DSH 語言設置。

環境與依賴¶

缺依賴時可在對應平臺安裝：

# macOS / Linux
python3 -m pip install jupyter_client ipykernel

# Windows（亦可 py -3 -m pip ...）
python -m pip install jupyter_client ipykernel

驗證：

# macOS / Linux
python3 -c "import jupyter_client, ipykernel"

# Windows
python -c "import jupyter_client, ipykernel"

安裝與啓用¶

官方 Quick Start 沒有 dsh plugin add github:... 一類遠程一條命令安裝，而是把本倉庫目錄作爲本地 bundle 裝進 DSH：

1. 打開 DSH 插件管理器，將 dsh-bsb-ipynb 倉庫文件夾安裝爲本地 bundle。
2. 刷新頁面（macOS：Cmd+R；Windows：Ctrl+R 或 F5）。
3. 在右側文件樹中打開任意 .ipynb；倉庫內 examples/demo.ipynb 適合作爲首次試跑。

Windows 上解釋器發現會跳過 WindowsApps 下的應用執行別名；若 Python 不在默認搜索路徑，請將 DSH_IPYNB_PYTHON 設爲 python.exe 的絕對路徑。只讀或被鎖定的筆記本在保存時可能返回 write-blocked（409）；被其他程序佔用讀取時可能爲 read-blocked（409）。

典型用法¶

安裝並刷新後，在 Better Sidebar 中點擊工作區內的 .ipynb 即可進入筆記本視圖。常用快捷鍵（與工具欄操作等價）如下：

閱讀模式下，筆記本可見時 Cmd/Ctrl + Enter 與 Cmd/Ctrl + S 仍可用：目標爲焦點單元格，或上次編輯/運行的單元格；Cmd/Ctrl + S 會攔截瀏覽器默認保存對話框。編輯時 Tab 插入四個空格，Shift+Tab 減少一級縮進。

工具欄還提供解釋器選擇、Run all、中斷、重啓、保存、重新加載、關閉內核等。運行或 Run all 期間會暫停自動保存，避免不完整輸出寫入磁盤。重新加載會等待進行中的保存，並在確認後丟棄未保存修改再從磁盤讀取。磁盤上文件被外部修改時會出現 409，需通過重新加載解決。筆記本體積超過 32 MiB 時，界面會提示清理輸出或縮減內容，而不是在上傳後才報錯。

切換解釋器會重啓內核；若有任務在跑會先確認。支持 display(..., display_id=...) 跨單元格更新顯示，更新會納入下一次保存。

適用場景與注意¶

適合誰：已在 DSH 0.2.2-rc.1+ 與 Better Sidebar 0.30.x 上工作、希望在同一 Web 界面裏查看和運行工作區 .ipynb、又不想單獨起 Jupyter Lab 的開發者或智能體使用者。

權限與安全：插件在 當前 DSH 宿主機進程權限 下啓動 Python 子進程並讀寫工作區文件；安裝本地 bundle 前應閱讀倉庫源碼與 MIT 許可證，確認可接受其路徑約束與 HTML 消毒策略。遠程圖片從內網或外網 URL 按 README 描述拉取，需自行評估網絡與數據來源風險。

生態說明：DSH 採用「一切皆插件」思路；SkillHub 插件目錄 爲社區站點，與 DeepSeek / 幻方無官方應用商店從屬關係。截至資料抓取時，GitHub 倉庫星標約爲 1。

結尾¶

經過上面的步驟，你可以在 Better Sidebar 文件樹裏把 .ipynb 當作一等公民：渲染、編輯、執行、保存都留在 DSH 會話內，內核仍在宿主機 Python 中運行。進一步瞭解實現細節可看倉庫架構說明（index.js 註冊 /ipynb 路由、python/bridge.py JSONL 橋接等）。

• 插件目錄頁：https://www.skillhub.cn/plugins/kexiongwen/dsh-bsb-ipynb
• 源碼與文檔：https://github.com/kexiongwen/dsh-bsb-ipynb