Notebook 预览 WuShichao/dsh-ipynb-preview

dsh-ipynb-preview

CI
npm
downloads
license
dsh-plugin

一个 DeepSeek Harness 插件，可在文档预览窗格中渲染 Jupyter notebook：带语法高亮的代码、真正的 LaTeX，以及可缩放的图片——而不是原始 JSON。

没有它，在 DSH 中打开 .ipynb 会显示其 JSON 源码。有了它，文件会以 notebook 的形式打开。

| 功能 | 说明 |
| 语法高亮 | 支持 Python、JavaScript/TypeScript、JSON、Bash 和 INI，并针对每种语言使用各自的语法 |
| LaTeX 数学公式 | 内置 KaTeX，因此可离线使用；支持行内 $…$ 和独立行 $$…$$，包括在表格和列表内部 |
| Markdown 子集 | 标题、列表、带列对齐的表格、引用块、任务列表、围栏代码块、链接、粗体和斜体、行内代码 |
| 图片缩放 | 点击任意输出图片即可打开，然后滚动或按 + / − 连续缩放，拖动可平移，按 0 适应窗口 |
| 保存图片 | 每张图片以 notebook 命名，例如 sample-notebook-cell3-out1.png |
| 输出 | 流、display_data、execute_result，以及已去除 ANSI 转义序列的错误回溯 |

一切都是自包含的：KaTeX 引擎及其 Web 字体已内联到客户端 bundle 中，因此不会有任何请求离开你的机器。

安装

dsh plugin --profile add dsh-ipynb-preview

然后重启 DSH。该插件是客户端渲染器，因此需要重启而不是刷新页面：shell 会在启动时计算其客户端 bundle 修订版本。

若要从本地检出或 git URL 安装：

dsh plugin --profile add ./dsh-ipynb-preview
dsh plugin --profile add github:WuShichao/dsh-ipynb-preview

git 形式会让 pnpm 请求运行此包的 prepare 脚本的权限，因为 pnpm >= 10 会拒绝 git 依赖的安装时脚本，直到它被加入允许列表。构建后的 lib/client.js 已提交，npm 包也会附带它，因此无论是 tarball 还是从 registry 安装都不会请求任何权限。

工作原理

DSH 通过 profile 的 bundle 列表发现该包，从此 manifest 中读取 dsh.client，并将 lib/client.js 作为客户端 roster 的一部分提供给浏览器。该 bundle 为 ipynb 扩展注册了一个文档预览渲染器：

lib/index.js host half; deliberately empty, the plugin is browser-only
lib/client.template.js the editable client source, with two KaTeX placeholders
lib/client.js 外壳所提供服务的生成产物 cordis.patch.yml 插入插件行的 bundle 层 tools/build-client.mjs 从模板生成 lib/client.js

lib/client.js 是生成的，不是手工编辑的。修改 lib/client.template.js 并运行 npm run build。

开发

pnpm install # 安装 KaTeX（构建）、React（测试）
pnpm run build # 重新生成 lib/client.js
pnpm test # 构建，然后运行验证器、bundle lint 和挂载测试框架

仓库附带 pnpm-lock.yaml，而 DSH CLI 本身也使用 pnpm 来安装插件，因此 CI 使用
pnpm install --frozen-lockfile 进行安装。npm 和 yarn 同样可用：每个脚本都是
普通的 node 调用，而不是链式的 npm run，因此没有任何脚本依赖于由哪个包管理器启动。

pnpm test 运行三个测试套件，全部离线：

- tests/verify.mjs —— 按照外壳模块加载器的方式物化 bundle，然后检查 manifest 契约、注册项、高亮器、数学渲染器、Markdown 子集、缩放算术、样式表，以及对 fixture notebook 的完整渲染。约 170 条断言。
- tests/lint-bundle.mjs —— 扫描模板和构建后的 bundle，查找被引用但从未声明的标识符。一个自由变量会让工厂函数在外壳物化它时抛出异常，整个客户端名单随后便无法加载——一个 node --check 无法检测到的空白窗口。
- tests/mount.mjs —— 将插件挂载到 DOM 桩上，使副作用和事件绑定真正运行，并断言 notebook 树在打开 lightbox 后依然存在。

fixture notebook 由 tests/make-fixture.mjs 生成，断言从该 fixture 读取其预期计数，因此输入和预期不会彼此偏离。

在真实浏览器中进行交互测试

React 的合成事件系统无法针对手写的 DOM 桩工作，因此控件的点击处理器改为在真实浏览器中验证：

node tests/make-page.mjs # 在仓库根目录写入 test-page.html
node tests/make-page.mjs out.html # 或选择输出路径

打开该页面，点击 Open the lightbox，然后按下每个控件；每次交互、缩放读数以及任何错误都会写入页面顶部的日志。在 URL 后追加 ?auto=1，页面便会自行驱动，无头运行正是以此方式读回结果：

msedge --headless=new --virtual-time-budget=15000 --dump-dom \
"file:///path/to/test-page.html?auto=1"

该页面还会用 document.elementFromPoint 对每个控件进行命中测试，一个层叠顺序 bug 正是这样被发现的：一个固定定位的应用头部，其 z-index 高于 lightbox，遮住了工具栏的中部，因此只有其边缘能响应点击。

要求

- 构建和测试需要 Node 18 或更高版本。
- React 不是依赖项：外壳从它自己的冻结模块中提供它表格。它只是一个开发依赖，仅用于测试。

插件作者须知

这个插件通过惨痛教训学到了两件事，现在都已由断言覆盖：

- 客户端 bundle 是在 shell 的模块加载器内部具体化的。如果工厂函数抛出异常，该行就没有导出，整个名册都会失败——这看起来像是空白窗口，而不是插件错误。请确保工厂函数不包含未声明的标识符。
- 全屏覆盖层需要 z-index 高于所有宿主层。9999 还不够：应用程序外壳通常是带有自身堆叠上下文的固定页眉，它会静默吞掉针对你的控件的点击。

许可证

MIT — 参见 LICENSE。KaTeX 以其自身的 MIT 许可证捆绑；参见 THIRD_PARTY_NOTICES.md。

由 @nightwingng 发布到 npm。