nteract Jupyter 协议与规范 SDK 指南:commutable、messaging 与 rx-jupyter 实战解析
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 交互的完整数据闭环:
- 读取:
rx-jupyter的contents模块通过/api/contents拉取笔记本 JSON 字符串; - 建模:
commutable的parseNotebook+fromJS将字符串转为不可变的ImmutableNotebook,供 UI 层(如 packages/stateful-components/src/notebook 与 applications/desktop/src/notebook)直接消费; - 交互:
messaging构造execute_request等协议消息,经 packages/epics/src/execute/execute.ts 与 packages/epics/src/websocket-kernel.ts 发送到内核并处理返回的execute_result/stream/error等 iopub 消息; - 写回:执行完成后,
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)。三个包都提供了对应的测试用例,是理解行为的绝佳起点:
- commutable 的格式与结构测试:packages/commutable/tests/notebook.spec.ts、packages/commutable/tests/v4.spec.ts、packages/commutable/tests/structures.spec.ts;
- messaging 的消息构造与线协议测试:packages/messaging/tests/messaging-spec.ts、packages/messaging/tests/wire-protocol-spec.ts;
- rx-jupyter 的 API 封装测试:packages/rx-jupyter/tests/contents-spec.ts、packages/rx-jupyter/tests/kernel-spec.ts、packages/rx-jupyter/tests/kernelspecs-spec.ts。
小结
@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 前端,还是封装远端计算服务,这套分层的设计都值得借鉴与直接复用。