前言¶
在 DeepSeek Harness（DSH）裏做數據分析或機器學習相關對話時，工作區裏常見 .ipynb。默認打開往往是整份 nbformat JSON，模型側若沒有專用工具，也只能靠通用讀文件把結構拆碎。下面介紹社區插件 dsh-plugin-ipynb（維護者 jcy0chenyuan0）：Host 側給模型三個 notebook 工具，Client 側在右側邊欄把 .ipynb 渲染成可讀視圖，併兼容 nbformat 3 與 4。
這是什麼¶
一句話：DSH plugin: read/export Jupyter notebooks and preview .ipynb in the sidebar (nbformat 3/4).
插件分兩半協同：
| 半邊 | 作用 |
|---|---|
| Client（側邊欄） | 打開 .ipynb 時默認用 Notebook 渲染器，而不是原始 JSON。 |
| Host（模型工具） | 註冊 ipynb_read、ipynb_summary、ipynb_export 三個工具。 |
分類爲客戶端插件；源碼與說明見 GitHub 倉庫，社區目錄頁：skillhub.cn/plugins/jcy0chenyuan0/dsh-plugin-ipynb。DSH 生態是「一切皆插件」；社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
當前 package 版本爲 1.2.1，許可證 MIT。
側邊欄預覽¶
從文件樹、引用鏈接或 @ 引用打開任意 .ipynb，默認渲染器即爲 Notebook，無需額外點擊。工具欄「渲染器」下拉還可選 Code（語法高亮的 JSON）和 Plain text（原文）。
渲染要點（與 README 一致）：
- Markdown 單元格：使用平臺
MarkdownText（@deepseek-ai/dsh-client-ui-primitives），標題、列表、表格、鏈接等與聊天區一致；$…$/$$…$$及\(...\)/\[...\]由 KaTeX 排版。 - 代碼單元格：等寬字體，並顯示
In [n]執行序號。 - 輸出：
stream會剝 ANSI、處理\r覆蓋式輸出；text/html中表格轉爲 DOM 表格，非表格 HTML 走sandbox=""iframe；常見圖片 MIME 內聯；error按錯誤色顯示 traceback；未支持的 MIME 會列出類型說明，而非空白。 - 單條輸出超過 30000 字符會截斷並標註；非法 JSON 或無法 UTF-8 解碼時顯示說明卡，並提示改用 Plain text。
- 樣式僅使用主題 token（
--dsw-alias-*），明暗主題跟隨 DSH。
掛載通過 documentPreviews.register 註冊擴展名 ipynb，loading: "bytes-complete"（整文件讀入後再渲染）。純文本兜底 extensions: []，因此默認選中的是 Notebook 而非 Plain text。
Host 側三個工具¶
相對路徑按會話工作目錄解析，也接受絕對路徑。
// ipynb_read
{ "path": "analysis/eda.ipynb", "include": ["code", "markdown"], "limit": 20 }
{ "path": "eda.ipynb", "includeSource": false }
// ipynb_summary
{ "path": "eda.ipynb", "previewChars": 120 }
// ipynb_export
{ "path": "eda.ipynb", "format": "markdown", "out": "exports/eda.md" }
ipynb_export 的 out 須落在會話工作目錄內（拒絕 .. 逃逸）；read-only 沙箱下一律拒絕寫盤。Host 側以讀 notebook 爲主，唯一寫盤能力是顯式指定 out 的導出。
兼容性方面：nbformat 4 與 3 並存（含 worksheets[].cells、v3 字段歸一化）；source 字符串與行數組兩種形態；UTF-8 BOM 剝離；未知 output_type 降級並在 warnings 說明；JSON 非法、路徑不存在、超過體積上限（默認 32 MB）等分別報錯，不返回半成品。lib/index.js 僅依賴 Node 內置模塊，不依賴 Jupyter 內核。
安裝與啓用¶
倉庫不包含本機絕對路徑：cordis.patch.yml 由安裝腳本按當前目錄生成（已在 .gitignore）。
- 將倉庫放到本機任意目錄（目錄頁與 GitHub 提供源碼地址，換機器時按 README 自行獲取副本）。
- 在該目錄首次運行安裝腳本：Windows 用
install.ps1，macOS / Linux 用node install.mjs。 - 在 DSH 中執行 bundle 安裝（路徑替換爲本目錄絕對路徑）：
plugin_manager install_bundle file:<本目錄的絕對路徑>
裝完後在 GUI「設置 → 插件」中可見，可整體啓用或停用。修改 lib/index.js 或 client.js 立即生效；僅改 cordis.patch.yml 時需重新執行安裝流程。
運行環境：Windows / macOS / Linux；Node 20+（DSH 自帶）；無需 npm install。
可選 Host 配置（寫入生成的 cordis.patch.yml，省略則用默認）：
- insert:
- id: plugin-ipynb-readonly-1
name: '<本目錄>\\lib\\host.js'
config:
maxBytes: 33554432
maxSourceChars: 20000
maxOutputChars: 4000
cwd: '<可選：工作區絕對路徑>'
維護者 README 中強調：bundle 補丁應掛載 lib/host.js 而非 lib/index.js，否則 ClientModuleRegistry 可能永久緩存錯誤的包元數據，側邊欄渲染器會靜默消失，需重啓 DSH 才恢復。
自測（零依賴）：
node test/smoke.mjs
node test/client-smoke.mjs
README 記載 Host 自測 103 項、Client 自測 65 項。
適用場景與注意¶
適合：在 DSH 會話裏讓模型結構化讀取 notebook 單元格與輸出、快速概覽目錄、導出 Markdown / Python / 純文本；同時在側邊欄人工覈對 Markdown、表格輸出與圖片，而不必盯 JSON。
安全與權限：插件以當前 DSH 進程權限運行；Client 側 HTML 輸出表格轉 DOM 或沙箱 iframe，不聯網、不起子進程。安裝前請自行審閱源碼與 MIT 許可證。ipynb_export 寫文件受會話沙箱與工作目錄圍欄約束。
Client 側只 require 平臺種子模塊表中的 react 與 @deepseek-ai/dsh-client-ui-primitives；若 Markdown 組件降級，notebook 頭部會出現「公式未渲染」告警 chip，而不再靜默退回極簡渲染。
結尾¶
dsh-plugin-ipynb 把「模型讀 notebook」和「人在側邊欄看 notebook」放在同一插件裏，並覆蓋 nbformat 3/4 與常見輸出類型。需要安裝步驟與工具參數時，以 GitHub README 爲準；瀏覽與收藏插件見 SkillHub 目錄頁。
