前言¶

在 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