nteract Jupyter 协议与规范 SDK 指南:commutable、messaging 与 rx-jupyter 实战解析

原创2026-10-09 20:10:261,862 阅读
文章标签:开发工具数据科学

nteract Jupyter 协议与规范 SDK 指南:commutable、messaging 与 rx-jupyter 实战解析

导读

本文围绕 nteract 桌面应用(archived-desktop-app)中负责对接 Jupyter 生态的三个核心 SDK 包展开:@nteract/commutable(将 .ipynb 序列化格式转换为不可变内存模型)、@nteract/messaging(Jupyter Messaging Protocol 的类型定义与消息构造工具)以及 @nteract/rx-jupyter(Jupyter Server API 的 ReactiveX 封装)。读完本文,你将掌握 Jupyter 笔记本在 nteract 内部的内存表示方式、消息协议的基本构造方法,以及如何用 RxJS 流式调用远端 Jupyter Server 的 REST API,并可从源码层级理解其底层实现。

这三个包在仓库中归属于 Jupyter 分组,官方分组说明见 docs/groups/jupyter-group.md。它们分别覆盖 Jupyter 规范中的"笔记本格式(nbformat)"、"消息协议(messaging)"与"服务器 API(services)"三大核心概念。


一、@nteract/commutable:Jupyter 笔记本的不可变内存模型

@nteract/commutable(源码位于 packages/commutable/src)用于创建 Jupyter 笔记本的不可变内存表示(in-memory immutable representation)。它遵循以下设计原则(源自 Tom MacWright 的 practical undo 思想):

  • 笔记本文档不可变:笔记本的表示永远不会被原地修改(in-place mutation);
  • 操作构成变更:对笔记本的每次修改都是一次"操作"(operation),它接收上一个版本、返回一个新版本,而不改动旧版本;
  • 历史由状态列表构成:过去在一端、现在在另一端,索引回退即为"撤销状态(undo states)";
  • 修改即丢弃未来:对笔记本的任何修改都会丢弃其未来的状态分支。

该包构建在 ImmutableJS 的导出可以看到,整个包的 API 分为五个模块:primitives、structures、outputs、cells、notebook。

1.1 磁盘上的笔记本格式(nbformat)

Jupyter 笔记本以 .ipynb 扩展名序列化到磁盘,本质是基于 JSON、遵循 nbformat 规范的文档。顶层属性的结构如下(nbformat 4):

{
  "metadata" : {
    "kernel_info": {
        "name" : "the name of the kernel"
    },
    "language_info": {
        "name" : "the programming language of the kernel",
        "version": "the version of the language",
        "codemirror_mode": "The name of the codemirror mode to use [optional]"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0,
  "cells" : [
      "list of cell dictionaries, see below"
  ],
}

其中 cells 是笔记本中单元格(cell)的列表,每个单元格的基本结构为:

{
  "cell_type" : "type",
  "metadata" : {},
  "source" : "single string or [list, of, strings]"
}

仓库中即包含真实的序列化笔记本示例,例如 applications/jupyter-extension/example.ipynb 与 applications/jupyter-extension/are-you-happy-now.ipynb,可直接查看它们作为 nbformat 的实际 JSON 样本。

值得注意的一个实现细节:磁盘格式中 source 既可以是单个字符串,也可以是字符串数组。源码 packages/commutable/src/primitives.ts 中定义了 MultiLineString = string | string[],并提供了两个转换工具:

  • demultiline(s):将多行字符串数组拼接为单个字符串(内存格式使用);
  • remultiline(s):将单个字符串按换行拆回数组(磁盘格式使用,便于 git/GitHub 逐行 diff)。

1.2 commutable 内存格式

@nteract/commutable 将序列化表示转换为不可变内存表示。内存表示的结构与磁盘结构不同,专门为交互式笔记本 UI 的开发而设计。笔记本的接口定义如下(见 packages/commutable/src/structures.ts):

export interface NotebookRecordParams {
  cellOrder: ImmutableList<CellId>;
  cellMap: ImmutableMap<CellId, ImmutableCell>;
  nbformat_minor: number;
  nbformat: number;
  metadata: ImmutableMap<string, any>;
}

各字段含义:

字段 说明
cellOrder 按笔记本中出现的顺序排列的 CellId 列表
cellMap 将 CellId 关联到其对应的 ImmutableCell 的映射
nbformat / nbformat_minor 该笔记本遵循的 nbformat 版本
metadata 存储在笔记本中的顶层元数据

NOTE:该包在解析笔记本时为遇到的每个单元格生成一个唯一的 CellId,这些 CellId 是 uuid-v4 标识符,用于在内存 store 中引用对应单元格。对应实现见 packages/commutable/src/primitives.ts 中的 createCellId(),其内部直接调用 uuid() 生成。

内存中的 ImmutableNotebook 由 makeNotebookRecord 工厂创建,默认值为 nbformat: 4、nbformat_minor: 0、空 cellOrder / cellMap / metadata(见 packages/commutable/src/structures.ts)。

1.3 三种单元格类型与 transient 元数据

Jupyter 规范定义了三种单元格类型:代码单元格(code)、Markdown 单元格(markdown) 和 raw 单元格(raw)。commutable 为每种类型提供了类型接口与工厂函数:

  • makeCodeCell:创建不可变代码单元格,其默认参数包括 cell_type: "code"、execution_count: null、空 outputs 列表,以及含 jupyter.source_hidden / jupyter.outputs_hidden / nteract.transient.deleting 的默认 metadata(见 packages/commutable/src/cells.ts);
  • makeMarkdownCell:创建不可变 Markdown 单元格,支持可选的 attachments 字段(见 packages/commutable/src/cells.ts);
  • makeRawCell:创建不可变 raw 单元格(见 packages/commutable/src/cells.ts)。

另外,cells.ts 中所有单元格工厂都经过 normalizedSourceCellRecord 包装,会在创建时自动调用 normalizeLineEndings(将 \r\n 统一为 \n),保证跨平台的源码一致性。

Transient nteract 数据:内存格式在每个单元格中包含 nteract.transient 元数据字段,用于承载基于 nteract 的 UI 专属交互状态(例如"正在删除"标记)。Jupyter nbformat 对 metadata 字段没有强类型约束,如果某个 UI 无法解释某个 metadata 字段,它可以安全地忽略它。因此,用户用 nteract 打开笔记本、修改其 metadata 属性、再使用其他 Jupyter UI 打开,不会对笔记本造成破坏。

markCellDeleting / markCellNotDeleting 正是操作该 transient 字段的实现(见 packages/commutable/src/structures.ts),而 v4.toJS 在写回磁盘时会过滤掉标记为 deleting 的单元格(见 packages/commutable/src/v4.ts),从而实现"软删除 + 可撤销"。

1.4 fromJS / toJS:磁盘格式与内存格式的双向转换

@nteract/commutable 的核心价值在于双向转换。入口函数定义在 packages/commutable/src/notebook.ts:

  • fromJS(notebook):接收一个已解析的 JSON 对象(Notebook,v4 或 v3)或已是 ImmutableNotebook 的记录,返回不可变内存表示。它内部先判断格式:v4.isNotebookV4 走 v4 转换,否则尝试 v3;不支持的版本抛出 TypeError;
  • parseNotebook(notebookString):将笔记本字符串 JSON.parse 为 JSON 表示,并利用 freezeReviver 对每个解析出的对象执行 Object.freeze 深冻结,强化不可变性(见 packages/commutable/src/notebook.ts);
  • toJS(immnb):将不可变表示转换回 v4 的 JSON 表示,仅支持 nbformat 3 与 4;
  • stringifyNotebook(notebook):将 JSON 表示以 2 空格缩进序列化为字符串。

关于 CellId 的一个重要版本细节:在 v4.fromJS 中,只有当 nbformat === 4 且 nbformat_minor >= 5 时,才会使用磁盘文件中已存在的 cell.id;否则由 nteract 自行生成 CellId(见 packages/commutable/src/v4.ts)。反向转换 v4.toJS 同样遵循该规则——只有版本 ≥ 4.5 的笔记本在写回时才保留单元格的 id 字段。

1.5 常用操作 API

除了转换函数,commutable 还提供了一系列针对不可变笔记本的操作(见 packages/commutable/src/structures.ts):

函数 作用
appendCellToNotebook 在笔记本末尾追加一个单元格,使用 withMutations 批量更新 cellOrder 与 cellMap
insertCellAt 在指定 index 插入单元格
insertCellAfter 在某个已有 CellId(priorCellId)之后插入单元格
deleteCell 从 cellMap 移除并更新 cellOrder(替代已废弃的 removeCell)
markCellDeleting / markCellNotDeleting 通过 transient 元数据标记"正在删除/取消删除",支持撤销
monocellNotebook 生成一个只含单个空代码单元格的新笔记本,适合初始化全新 notebook(见 packages/commutable/src/structures.ts)

1.6 commutable 实战示例

创建笔记本的内存模型:将包含序列化内容的字符串传给 fromJS 即可。示例中 notebookString 可以来自 Jupyter 服务器的 Contents API、本地文件系统的读取、云存储提供商的 API 等任何来源,只要它遵循 nbformat:

import { fromJS } from "@nteract/commutable";

const notebookString = "{ cells: [...], metadata: {...} }";
const immutableNotebook = fromJS(notebookString);

更完整的链路是 parseNotebook + fromJS 组合:

import { parseNotebook, fromJS } from "@nteract/commutable";

const notebookString = getNotebookFromContentsAPI(); // 任意来源的 .ipynb 字符串
const notebook = parseNotebook(notebookString); // JSON.parse + 深冻结
const immutableNotebook = fromJS(notebook);      // 转为 ImmutableNotebook

创建代码单元格:使用 makeCodeCell 函数:

import { makeCodeCell } from "@nteract/commutable";

const codeCell = makeCodeCell({
  source: "print(1)"
});

NOTE:传给 makeCodeCell 的参数不必包含单元格的全部属性,该包会在合适的地方使用合理默认值(如 execution_count: null、空 outputs 等)。类似地,创建其他类型单元格可使用 makeMarkdownCell 与 makeRawCell,这在 packages/commutable/src/cells.ts 中与 createCodeCell / createMarkdownCell 两个别名(见 packages/commutable/src/structures.ts)保持一致。

此外,commutable 对输出(outputs)也提供了专门的不可变模型:createImmutableOutput 会将磁盘上的 execute_result、display_data、stream、error 四类输出转换为不可变结构,其中 error 的 traceback 是格式规定的一部分(不是多行字符串),在写回时按原样保留为字符串数组(见 packages/commutable/src/v4.ts)。媒体包(MediaBundle)在内存中会被 createFrozenMediaBundle 深冻结,支持 text/plain、text/html、image/png、application/json、application/vnd.vega.v5+json 等大量 MIME 类型(见 packages/commutable/src/primitives.ts)。


二、@nteract/messaging:Jupyter 消息协议的类型与构造工具

@nteract/messaging(源码位于 packages/messaging/src)包含与 Jupyter Messaging Protocol 交互所需的类型定义和辅助函数,用于构造不同类型的请求与响应消息。

2.1 消息协议基础

Jupyter 消息是前后端(客户端与 kernel)之间通信的载体。一个完整的消息包含:

  • header:消息头,含 msg_id(uuid)、date(ISO 8601 时间戳)、version、msg_type、username、session 等字段,其接口定义见 packages/messaging/src/types.ts;
  • parent_header:父消息头(用于关联请求与响应);
  • metadata:消息级元数据;
  • content:与消息类型对应的具体内容;
  • channel:消息所走的通道;
  • buffers:二进制缓冲区。

在 message() 工厂函数中(见 packages/messaging/src/messages.ts),header 的默认字段为:msg_id 由 uuid() 生成、date 为当前时间、version: "5.2"、username 与 session 默认为 "nteract" 与新建 uuid(可通过参数覆盖)。

2.2 通道(Channel)与消息路由

每条消息都必须通过特定通道发送。whichChannel() 函数(见 packages/messaging/src/messages.ts)依据消息类型决定通道:

通道 消息类型示例
shell execute_request、inspect_request、kernel_info_request、complete_request、history_request、is_complete_request、comm_info_request、shutdown_request、comm_open / comm_msg / comm_close
iopub display_data、stream、update_display_data、execute_input、execute_result、error、status、clear_output
stdin input_request、input_reply

从源码注释可以得知:Kernel 在 shell 通道上监听 COMM 消息,Frontend 在 iopub 通道上监听。由于 nteract 目前只实现前端(frontend),代码中假设 COMM 消息都发往 shell 通道("Revisit as needed")。未知类型默认也走 shell 通道,开发者可在必要时覆盖。

2.3 createMessage:构造请求消息

createMessage(msg_type, fields) 是 @nteract/messaging 对外暴露的最简入口(见 packages/messaging/src/index.ts),它等价于 { ...message({ msg_type }), ...fields }——即先按给定 msg_type 生成完整消息骨架,再用 fields 覆盖内容。下面的示例构造一条 inspect_request(代码内省请求)消息:

import { createMessage } from "@nteract/messaging";

const message = createMessage("inspect_request", {
  code: "string.for",
  cursor_pos: 10,
  detail_level: 1
});

其中 code 是要内省的代码,cursor_pos 是光标在代码中的位置(字符偏移),detail_level 为详情级别(1 表示完整详情)。

2.4 类型化请求构造器:executeRequest 等

除了通用 createMessage,该包还提供了类型化、带默认值的请求构造器,例如 executeRequest(code, options)(见 packages/messaging/src/messages.ts):

import { executeRequest } from "@nteract/messaging";

const req = executeRequest('print("hey")', { silent: true });
// req.content 形如:
// {
//   code: 'print("hey")',
//   silent: true,          // 默认 false
//   store_history: true,   // 默认 true
//   user_expressions: {},  // 默认 {}
//   allow_stdin: true,     // 默认 true
//   stop_on_error: false   // 默认 false
// }

所有可选参数均有 Jupyter 协议规定的默认值,调用方只需覆盖需要变更的字段。除此之外,messages.ts 中还实现了 execute_input、status、kernel_info_request、comm_open、comm_msg、comm_close、input_request 等大量消息的构造逻辑(该文件共 400 余行)。@nteract/messaging 的完整类型体系(JupyterMessage、MessageType 等)集中在 packages/messaging/src/types.ts,可与 packages/messaging/src/wire-protocol.ts 中的协议序列化逻辑配合使用。


三、@nteract/rx-jupyter:Jupyter Server API 的 ReactiveX 封装

@nteract/rx-jupyter(源码位于 packages/rx-jupyter/src)是 Jupyter Server API 的 ReactiveX 封装,用于查询本地或远程 Jupyter Server 实例。它将服务器的 REST 响应包装为 Observable,从而无缝接入 RxJS 的函数式工具链(mergeMap、catchError、combineLatest 等)。

3.1 API 概览

从 packages/rx-jupyter/src/index.ts 可以看出,该包围绕一组 Jupyter 服务 API 模块组织:

模块 服务对象 典型端点
kernels 内核生命周期 GET/POST /api/kernels、GET /api/kernels/:id
kernelspecs 内核规格 /api/kernelspecs
sessions 会话管理 /api/sessions
contents 文件与笔记本内容管理 /api/contents
terminals 终端 /api/terminals
bookstore Bookstore 集成 书店相关端点
apiVersion / shutdown 服务器级操作 /api、POST /api/shutdown

3.2 获取服务器 API 版本(示例)

下面的示例使用该包获取 Jupyter Server API 的版本信息,并通过 mergeMap / catchError 处理成功与失败分支:

import jupyter from "rx-jupyter";
import { of } from "rxjs";
import { mergeMap, catchError } from "rxjs/operators";

const apiVersion = jupyter.apiVersion({
  endpoint: "https://myjupyterendpoint.com",
  crossDomain: true
});
apiVersion.pipe(
  mergeMap(apiVersion => of(apiVersionFulfilled({ apiVersion }))),
  catchError(error => of(apiVersionFailed({ error })))
);

apiVersion 的实现非常简洁(见 packages/rx-jupyter/src/index.ts):

export const apiVersion = (serverConfig: ServerConfig): Observable<AjaxResponse> =>
  ajax(createAJAXSettings(serverConfig, "/api"));

即:先由 createAJAXSettings 基于 ServerConfig 构造 AjaxRequest,再由 RxJS 的 ajax 把它变成 Observable。

3.3 ServerConfig 与鉴权:createAJAXSettings 的底层机制

ServerConfig 是 @nteract/types 中定义的服务端配置类型,核心字段包括:

字段 说明
endpoint / url Jupyter Server 的基地址,createAJAXSettings 会先用 normalizeBaseURL 去掉尾部斜杠
token 服务器访问令牌,存在时自动附加 Authorization: token ${token} 请求头
xsrfToken XSRF 令牌,优先取配置值,否则回退到 js-cookie 读取的 _xsrf cookie,并附加 X-XSRFToken 头
ajaxOptions 额外的 ajax 配置,如自定义 headers
crossDomain 跨域请求标志

实现细节见 packages/rx-jupyter/src/base.ts。此外,当 opts.cache === false 时,会在 URL 上追加 _=${Date.now()} 时间戳参数以绕过缓存——内核列表、内核信息等只读查询都默认使用该策略(见 packages/rx-jupyter/src/kernels.ts)。

3.4 内核生命周期操作示例

kernels 模块(见 packages/rx-jupyter/src/kernels.ts)封装了最常用的内核操作:

import { kernels } from "rx-jupyter";

const server = { endpoint: "http://localhost:8888", token: "abc123" };

// 列出运行中的内核
kernels.list(server).subscribe(resp => console.log(resp.response));

// 启动新内核(POST /api/kernels,body 为 { path, name })
kernels.start(server, "python3", "/notebooks/demo.ipynb").subscribe(...);

// 通过内核 id 获取内核信息
kernels.get(server, "kernel-uuid").subscribe(...);

// 关闭内核(DELETE /api/kernels/:id)
kernels.kill(server, "kernel-uuid").subscribe(...);

在桌面应用中,这套 API 与 @nteract/epics 中的内核生命周期史诗(如 packages/epics/src/kernel-lifecycle.ts)配合,把"启动内核 → 建立 websocket 连接 → 执行消息往返"编排为可组合的异步流程;sessions 模块则管理会话的创建与删除,将内核与笔记本路径绑定。


四、三个包在 nteract 中的协作关系

从仓库整体架构看,三个包构成了 Jupyter 交互的完整数据闭环:

  1. 读取:rx-jupyter 的 contents 模块通过 /api/contents 拉取笔记本 JSON 字符串;
  2. 建模:commutable 的 parseNotebook + fromJS 将字符串转为不可变的 ImmutableNotebook,供 UI 层(如 packages/stateful-components/src/notebook 与 applications/desktop/src/notebook)直接消费;
  3. 交互:messaging 构造 execute_request 等协议消息,经 packages/epics/src/execute/execute.ts 与 packages/epics/src/websocket-kernel.ts 发送到内核并处理返回的 execute_result / stream / error 等 iopub 消息;
  4. 写回:执行完成后,commutable 的 toJS + stringifyNotebook 将内存模型序列化回 .ipynb 文本,再经 rx-jupyter 的 Contents API 持久化。

其中"不可变 + 操作即新版本"的设计,直接支撑了 nteract 笔记本编辑器的撤销/重做功能——packages/notebook-app-component/src/decorators/undoable 正是基于 commutable 状态列表构建历史栈。这验证了原文档中"修改笔记本文档会丢弃未来状态"原则在实际编辑器中的落地方式。


五、在项目中使用这些包的入口

上述包均为 lerna monorepo 中的独立 npm 包,可通过各自的 package.json 查看版本与依赖(如 packages/commutable/package.json、packages/messaging/package.json、packages/rx-jupyter/package.json)。三个包都提供了对应的测试用例,是理解行为的绝佳起点:

小结

@nteract/commutable 用 ImmutableJS 为 Jupyter 笔记本提供了安全、可撤销的内存模型,是 nteract 一切笔记本 UI 的地基;@nteract/messaging 让 Jupyter Messaging Protocol 的类型化构造变得直接而可靠;@nteract/rx-jupyter 则以 RxJS Observable 统一了 Jupyter Server REST API 的调用方式,天然支持组合与错误处理。三者分别对应 Jupyter 规范中的笔记本格式、消息协议与服务器 API,共同构成了 nteract 桌面应用中与 Jupyter 生态对接的完整 SDK 链路。无论是开发自定义笔记本应用、构建 Jupyter 前端,还是封装远端计算服务,这套分层的设计都值得借鉴与直接复用。

登录后查看全文
archived-desktop-app