持久笔记本 beihzb/dsh-notebook

@beihaizb/dsh-notebook

面向 DeepSeek Harness 的、由 Agent 操控的持久化 Jupyter 计算工作空间。 一个真正的 ipykernel runtime，DSH Agent 可以读取、编辑、执行并检查它的状态——把 notebook 从静态产物变成 Agent 可以操作的对象。

这不是又一个 Notebook 前端。内核是真正持久的（变量跨 cell 保持）、notebook 可保存/重新加载，而且 Agent 拥有读取、修改、运行、推理 cell 及其输出的工具。这给了 Agent 一个真实的 Agent ↔ 内核 ↔ 产物 闭环。

Agent 工作流

这个插件的意义在于：DSH Agent 不在运行一次性脚本，而是在驱动一个活跃的计算会话：

用户："把 Harmony 换成 scVI。"
→ Agent 找到相关 cell → 读取源码和上下文 → 修改 cell → 执行 → 检查 stdout / traceback → 必要时继续迭代。

因为内核是持久的，Agent 操作的是有状态 runtime（一个 Anndata、一个 GPU 模型、已加载的数据），而不只是拼接代码字符串。

演示 / 截图

- 实时 tqdm 进度条、内联图可点击放大。
- 可点击 traceback（Cell In[N]）跳转到对应 cell。
- 逐 cell 「交给 AI」 修改意见：输入需求，Agent 修改并重跑该 cell。
- VS Code 对齐的 cell 行为（排队 / 运行中 / 执行语义）。

功能（已实现）

- 真正的持久内核：ipykernel + jupyter_client sidecar，变量跨 cell 保持。R 内核（IRkernel）同样支持，在同一个下拉框里选。
- Agent 工具：读取、编辑、运行、检查 cell（nb_get / nb_edit_cell / nb_run_cell …），结构化访问输出与 traceback。
- Agent 运行时自省：nb_context、nb_list_vars、nb_inspect_object 暴露活内核变量和压缩后的 notebook 状态；pandas DataFrame 会返回 shape / dtype / 缺失值 / head / summary 等元信息。
- 安全 AI 修改闭环：更完整的逐 cell 版本快照，配合 nb_cell_history、nb_revert_cell、nb_error_context、nb_edit_and_run_cell 支持可审计的修错并重跑流程。
- VS Code 对齐的 cell UI：圆形运行控件、Queued / Executing 状态栏、执行序号。
- VS Code 对齐的执行语义：重启保留已完成输出、中断只停当前 cell、Run All 遇错停止、Clear Outputs / Restart & Clear。
- tqdm 进度条、长输出折叠、多图网格。
- 错误定位（点击 traceback 跳到对应 cell）。
- 更稳的前端：加了 React 错误边界，输出渲染异常时不再整块空白；修复了一个 hooks 顺序 bug 导致的界面偶发消失。
- 更快的实时更新：运行中进度节流并只发尾部输出、状态轮询降频、高频更新不再重复带完整内核列表。
- 跟随会话的工作目录：notebook 默认 cwd / workspace 跟随当前 DSH 会话；手动“设置工作目录”与打开 notebook 保存的 cwd 优先级更高。
- 会话隔离：每个 DSH 会话拥有独立的 notebook、内核和工作目录，无跨会话状态泄漏。多会话可同时运行内核。
- 内核管理器：工具栏弹窗列出所有会话的活跃内核（会话 ID、内核名、状态），可直接关闭任一会话的内核。
- 内核活跃指示：状态栏显示当前会话内核是否活跃，多会话同时开内核时提醒注意内存/资源。
- 孤儿进程自动清理：dsh web 被强杀时，Python sidecar 检测到父进程死亡后自动关闭 ipykernel，不留孤儿进程（跨平台：POSIX 用 getppid，Windows 用 OpenProcess）。
- 中英双语界面：整个界面默认英文，工具栏一键切换中文，选择持久化保存。
- 大小核 CPU 提示：在混合架构（P+E 核）机器上，提示如何把 Python 进程固定到性能核（Windows 任务管理器 / 活动监视器 / taskset），并附一键复制的 psutil 片段。它不再"关掉就永久消失"：工具栏的「⚡ 大小核」按钮可随时重新打开（只关闭"自动弹出"，不关闭入口）。
- Jedi 内核补全（df. / plt. / 变量名；Tab 接受；悬停看 docstring）。
- 每 cell AI 修改意见（版本栈在 cell.metadata.dsh）。
- 标准 .ipynb 保存 / 读取，自动保存 + 未保存提醒；不需要 nbformat，未知字段也不会在往返中丢失。
- 内核选择：conda 环境 和 R 内核都能选；缺 ipykernel / jupyter_client / IRkernel 时给友好安装提示。
- 兼容 scoped 安装：bundle 现在在 host 补丁（cordis.patch.yml）和 client 加载器里都注册为 @beihaizb/dsh-notebook，dsh plugin add @beihaizb/dsh-notebook 可直接加载（此前补丁名不带 scope，无法对上 npm 的 scoped 包名）。
- 「交给 AI」更可靠：修复了一个回归（局部变量遮蔽 i18n 翻译函数），此前提交的意见会在发送前被静默丢弃——现在 cell 代码和你的请求一定能送达 agent。
- 编辑器跟随主题：CodeMirror 编辑器跟随 DSH 深浅主题——深色用 oneDark，浅色用清爽的浅色方案（行号柔和灰），切换主题时实时重绘。
- CPU 提示片段本地化：一键复制的 psutil 片段注释跟随界面语言（中 / EN）。
- 结构化执行结果（v0.2.2）：所有运行工具（nb_run_cell、nb_edit_and_run_cell、nb_run_all）现在返回统一执行信封——status、execution_count、duration_ms、kernel_state、合并的 stdout/stderr、outputs_summary、图片路径、error + traceback_text、execution_index——为 Agent 建立可靠执行循环。
- 长输出不撑爆上下文（v0.2.2）：三层防线防止失控输出灌爆 Agent 上下文——driver 单流上限（500 KB）、信封内 6 KB 头尾摘要、完整合并文本落盘到 <notebook>_files/ 并返回路径供 Agent 按需读取。base64 图片只留在 UI，信封给文件路径。
- 逐次执行历史（v0.2.2）：每次运行都记录到 cell.metadata.dsh.executions（每 cell 上限 50 条，随 notebook 持久化）——执行历史 UI 与重放式恢复的地基。
- Run All 完成提示更诚实（v0.2.2）：只有所有 cell 真正跑到终态（ok/error）才弹「全部运行完成」，不再在请求一返回就假完成。
- 排队即时反馈（v0.2.2）：运行第二个 cell 时立刻显示 Queued 状态（HTTP 运行端点不再为 UI 阻塞等待），且运行中不会出现快照交换导致的编辑器闪空。
- ANSI 流输出不再乱码（v0.2.4）：含 ANSI 转义码但不含 \r 的内核流输出（彩色 Pdb 提示符、colorama 彩色打印）现在会在渲染前剥离转义码——此前虽然算出了清洗文本，渲染时却回退到原始 o.text，导致 [32m/[0m 垃圾原样显示在输出区。错误标题（evalue）同样处理。
- 长输出折叠真正可用（v0.3.0）：v0.2.2 加上的折叠从未生效——唯一产生高度钳制的 fold 类，其判定却来自"已被钳制元素"的测量，溢出永远测不到，按钮也就不出现。现在改为测量内层未被钳制的元素，且折叠高度与判定共用同一个 FOLD_PX 常量；按钮还会显示隐藏规模（如「展开全部（3,000 行）」）。
- 超大输出只渲染头尾（v0.3.0）：单个文本块超过 4,000 行或 200 KB 时，只渲染前 300 行 + 后 100 行，并明确标注「… 已省略 N 行」与一键「显示全部 N 行」——500 KB 的流不必为了折叠而全部驻留 DOM。
- 全新会话也能进 Notebook（v0.3.0）：会话空白时 DSH 不渲染 conversation.view slot，所以此前必须先发一句话才能看到 Notebook 标签。现在空白会话的输入框上方会出现「📓 在本会话打开 Notebook」入口，点击即激活本视图并让常规视图标签栏出现（随后宿主会记住该会话的选择）。
- 切换视图不再丢滚动位置（v0.3.0）：宿主同一时刻只渲染一个视图，切到「对话」会卸载 notebook 并把位置重置到顶部。现在滚动偏移与每个 cell 的展开/折叠选择都按会话记忆，切回来自动恢复。
- 支持 DSH 0.2.0（v0.3.0）：peerDependencies 现在同时覆盖 0.1.x-rc 与 0.2.0-rc 两条线（@deepseek-ai/dsh-tools: ^0.1.0-rc.6 || ^0.2.0-rc.1），DSH 启动期的兼容性门禁不再拒绝本插件——旧的 ^0.1.0-rc.6 上界是 <0.2.0，而只要有 @deepseek-ai/dsh peer 不满足当前运行版本，门禁会跳过整个 bundle。client 清单里也改为指向真正提供 slots 服务的 client row @deepseek-ai/dsh-client-ui-renderer，不再引用根本不存在的 @deepseek-ai/dsh-client-runtime。
- 默认内核跟随本会话（v0.3.1）：默认内核现在读取当前会话的 dsh-envsel 选择。此前它取的是存储文件里"最后一个"选择，于是 notebook 可能落到某个不相干会话挑的环境上；而被派出的子代理因为各自拥有独立会话，根本查不到任何选择。现在自身没有选择的会话会继承它向上最近的那个有选择的会话。
- 支持 R 内核（v0.4.0）：内核下拉框现在会列出 R 内核，来源与 Jupyter 一致——用户数据目录里的 kernelspec、conda 环境自带的 <env>/share/jupyter/kernels、以及只在 R library 里装了 IRkernel 的 conda 环境（自动合成）。conda 的 R 启动时会把该环境的 DLL 目录塞进 PATH 并设好 R_HOME，否则直接起二进制会以 0xC0000135（找不到 DLL）秒退；kernelspec 里 argv[0] 只写 "R" 的情况会解析成绝对路径，因此在未激活环境时也能用。nb_list_vars / nb_inspect_object 有对应的 R 实现（ls/class/deparse，data.frame 额外给行数/列数/列类型），保存时写入真实的 kernelspec.language（r 或 python）。
- 不再需要 nbformat（v0.4.0）：.ipynb 的读写改用标准库完成。此前 sidecar 在打开/保存 notebook 时会 import nbformat，于是一个有 ipykernel + jupyter_client 却没有 nbformat 的 conda 环境会直接报 Operation failed: No module named 'nbformat'——而精简环境或纯 R 环境根本装不了它。现在写出的字节与 nbformat.write() 完全一致（缩进/排序/CRLF/拆行规则全部对齐），用 Jupyter 打开再保存不会在 git 里炸开 diff。
- notebook 往返无损（v0.4.0）：插件不认识的东西一律原样保留——markdown 的 attachments（粘贴的图片）、每个 output 的 metadata（widget 视图尺寸）、全局 metadata.widgets 状态、第三方自定义键，保存时不会被吞掉。nbformat 3 的老 notebook（worksheets/input/prompt_number/png 别名）会在读取时升级到 v4，而不是被读成空 notebook、再在下次保存时把文件清空；4.0–4.4 的文件按 nbformat.read 的行为补齐 cell id。
- 大小核提示可以重新打开（v0.4.0）：以前点「知道了，不再提示」后整个浏览器会话都没有入口。现在 CPU 探测结果会留在会话里，工具栏的「⚡ 大小核」按钮可重新打开同一个面板；被关掉的只是自动弹出。

Roadmap

方向是完整的 Agent 计算工作空间，而不是堆更多 Notebook UI：

- AnnData / 科学对象自省 —— 扩展 nb_inspect_object("adata")，返回 n_obs、layers、obsm、obs / var 列摘要。
- 执行历史 / diff UI —— 不只在工具里记录，也在界面里展示可审计的 cell 版本（逐次执行记录已开始收集）。
- 上下文相关的 cell 选择 —— 分层 / 查询"哪个 cell 定义了某变量、哪些依赖它"，而不是把整个 notebook 塞进上下文。
- 执行安全 —— 把操作分类为 只读 / 轻量 / 修改型 / 重 / 破坏性；破坏性或超长运行前要求确认。
- Checkpoint / 回滚 —— 不只恢复代码，还能恢复 runtime 状态。
- 远程 / SLURM 内核 —— 内核跑在服务器 / 作业节点上，Agent 通过同一接口驱动它。

兼容性

支持的 DSH 运行时线：0.1.x-rc 与 0.2.0-rc，已在 0.1.7-rc.2 与 0.2.0-rc.2 上核对（插件声明 @deepseek-ai/dsh-tools: ^0.1.0-rc.6 || ^0.2.0-rc.1）。若插件的 @deepseek-ai/dsh peer 区间不包含当前运行版本，DSH 会在启动时拒绝并跳过整个 bundle——在尚未验证的新版本线上，请用精确版本豁免（dsh plugin allow-version 或插件管理器），而不是强行加载。

安装

dsh plugin --profile web add @beihaizb/dsh-notebook@0.4.0

然后重启 dsh web。会话顶部会出现 Notebook 标签。

版本锁定说明：如果刚发布不久就安装，pnpm 的供应链策略（minimumReleaseAge）可能跳过刚发布的版本、自动装到旧版。遇到这种情况请像上面那样显式指定版本号（@beihaizb/dsh-notebook@0.4.0），或等发布超过策略窗口后用 @beihaizb/dsh-notebook@latest。

内核选择

- dsh-envsel 是可选依赖。 装了环境选择器时，插件读取它的选择（$DSH_HOME 下的存储，即 ~/.dsh/envsel-state.json），用你在本会话选的 conda 环境作为默认内核。自身没有选择的会话（例如被派出的子代理）会继承它向上最近的那个有选择的会话，因此被委托的 notebook 工作会落在委托它的那个会话所用的环境里。

dsh plugin --profile web add @beihaizb/dsh-envsel

（源码：github.com/beihzb/dsh-envsel）

- 没装 dsh-envsel 时，回退到第一个发现的有 ipykernel 的 conda 环境。读取存储时会先校验其版本戳，因此未来换了格式的 envsel 状态会被忽略，而不是被误读。
- 随时可切换。 用工具栏下拉框切换任意其他环境（Python 或 R）。

内核依赖

| 内核 | 需要 |
| Python | ipykernel 和 jupyter_client——前者跑内核，后者跑与它通信的 sidecar |
| R | 该 R 的 library 里有 IRkernel；不需要任何 Python 包（sidecar 借用某个 Python 环境，优先用 dsh-envsel 选的 python） |

nbformat 不需要——notebook 文件用标准库读写。

jupyter_client 与 ipykernel 是真正第三方的协议实现，缺了会给出精确的安装命令，而不是抛原始 ModuleNotFoundError；内核下拉框也会把这类环境标记为不可用，避免你选到一个起不来的内核。

R 内核需要主动选择：新建 notebook 不会悄悄启动 R。要跑 R notebook 就在下拉框里选 R · ggtree、R · hdWGCNA 等。而一个只有 Python、但顺带装了 R 的 conda 环境（很常见）仍会被 dsh-envsel 写进运行时上下文，agent 因此知道两条调用路径。

工具

nb_new / nb_open / nb_save / nb_get / nb_context / nb_list /
nb_list_vars / nb_inspect_object /
nb_add_cell / nb_delete_cell / nb_move_cell / nb_edit_cell / nb_edit_and_run_cell /
nb_cell_history / nb_revert_cell / nb_error_context /
nb_run_cell / nb_run_all / nb_apply_suggestion /
nb_kernel_restart / nb_kernel_restart_and_clear / nb_kernel_interrupt /
nb_kernel_list / nb_kernel_select / nb_clear_outputs / nb_set_cwd

License

MIT