前言¶
在 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 目录页。
