oh-my-pi Notebook 工具运行时剖析：.ipynb 文件编辑与 Kernel 执行的双轨设计

oh-my-pi Notebook 工具运行时剖析：.ipynb 文件编辑与 Kernel 执行的双轨设计

【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi

在 oh-my-pi 的coding-agent中，Jupyter Notebook 被拆成了两条边界清晰的运行时路径：.ipynb文件的读取与编辑走「虚拟文本 + 无损 JSON 往返」的纯文件转换管线，而带持久状态和富显示的 Python 执行则走eval工具的 kernel 后端子进程。理解这个「编辑归编辑、执行归执行」的分层，是掌握该项目 Notebook 支持机制的关键。读完本文，你将能够：说清楚.ipynb虚拟标记文本（# %% [code] cell:N）的编解码语义、掌握 notebook 往返序列化对元数据的保留策略、理解eval工具session/per-call两种 kernel 模式的差异，并知道「改 notebook 再跑代码」的推荐工作流如何组合这两条路径。

1. 运行时边界：编辑与执行是两条独立路径

原文档（docs/notebook-tool-runtime.md）开篇就给出了核心论断：notebook 支持是文件转换/编辑，而不是 notebook 执行。.ipynb文件通过read工具和编辑管线以带 cell 标记的可编辑文本形式暴露，整条路径上没有任何 notebook 专属工具去启动或与 Python kernel 通信。

相关实现分布在如下文件中：

两条路径的差异可以概括为：

• 文件转换路径（notebook codec）：无 kernel 会话 ID、无代码执行、无 Python 流式分片、无富显示捕获、无执行产物管线。它只做一件事——把 notebook JSON 投影成模型可读可写的文本，再把文本无损地写回 JSON。
• Kernel 执行路径（eval工具）：当 agent 需要以 cell 形式运行带持久状态、富显示的 Python 代码时，走的是每次调用eval工具且language: "py"，与 notebook 文件处理完全无关。Python 子进程生命周期、reset/cancel、流式分片、富显示渲染与输出截断全部落在这条路径上。

从源码结构看，read工具在 read.ts 中对.ipynb的路由印证了这一点：仅当扩展名是.ipynb且选择器不是:raw时，才读取原始 JSON 并调用notebookToEditableText（来自@oh-my-pi/pi-natives，即 Rust 侧 codec 的绑定）生成虚拟文本，实体标签为notebook；:raw是显式的逃生口，让调用方按字节读原始文件。

2..ipynb文件转换：虚拟标记文本

read工具把.ipynb视为 notebook，除非选择器是:raw。默认的 notebook 视图是带标记的可编辑文本，每个 cell 以一行标记开头：

# %% [code] cell:0 import pandas as pd df = pd.read_csv("data.csv") # %% [markdown] cell:1 # 数据说明

标记的完整文法（来自 notebook.rs 中的正则）为：

^# %% \(code|markdown|raw)\)?$

要点：

• 行选择器与多区间选择器（如:5-16,40-80）都作用在这段虚拟文本上，而不是 JSON 上；
• 编辑管线通过serialize_edited_notebook_text(...)把编辑后的虚拟文本往返序列化回 notebook JSON，见 files.rs 中FileRead::persist的分支：is_notebook为真时不走 BOM/换行恢复，而是直接进 notebook 序列化；
• 当标记引用一个已存在且未被其他标记使用的cell:N时，保留原 notebook 的元数据；新 cell 获得全新的空元数据；
• 传给序列化器的 notebook 缺失（即创建新文件）时，从空的 nbformat 4.5 文档起步——notebook.rs 的create_empty_notebook()固定生成nbformat: 4, nbformat_minor: 5；
• 独立的write工具不感知 notebook：它直接用给定字节替换文件，因此只对合法 notebook JSON 可用，不能喂虚拟标记文本。这条约束在 files.rs 的persist_new中同样体现——新建.ipynb时编辑管线会显式走serialize_edited_notebook_text(None, ...)，而不是裸写字节。

值得注意的是，序列化刻意做到与JSON.stringify(nb, null, 1)逐字节一致：notebook.rs 中手写了stringify_indent1，并单独实现了 js_number_to_string 来复刻 JavaScript 的浮点渲染（如1e21、尾零剥离、科学计数法阈值）。同文件的内联测试（serializes_floats_like_javascript、golden_json_serialization_matches_bun）用tests/fixtures/notebooks/下的 golden 文件做往返校验，保证未修改的 notebook 重新落盘后字节不变——这对避免 git diff 污染非常重要。

3. cell 处理语义

3.1 source 归一化

notebook JSON 的source字段被拼接成虚拟文本；反向序列化时按换行切分并保留换行归属：

• 以\n结尾的每一行单独保留为一个带换行的 source 条目（split_notebook_source使用split_inclusive('\n')，见 notebook.rs）；
• 最后一行若无换行符，则不强制补\n；
• 空内容对应空source数组。

这与 notebook JSON 惯例一致，避免后续编辑发生意外的行拼接。

3.2 形似标记的 source 转义

如果某个 cell 的内容本身就长得像 cell 标记（例如某行是# %% [markdown] cell:3），渲染时会给该行多加一个%（# %% ...变# %%% ...），解析时再去掉一个%；已经转义过的行按同样规则再增减一个%。这样往返编辑时，cell 内的字面标记文本不会被误判为新 cell 边界。实现上由两组正则驱动：ESCAPABLE_MARKER_RE（^# %%+ \(?:code|markdown|raw)\?$）与ESCAPED_MARKER_RE（^# %%%+ ...），见 notebook.rs。测试marker_like_source_lines_are_escaped_and_restored验证了mixed.ipynb夹具中该行为。

3.3 标记解析与 cell 保留规则

parse_notebook_editable_text+apply_notebook_editable_text定义了编辑时的 cell 复用语义（notebook.rs）：

• 非空文本必须以标记开头；第一个标记之前出现任何文本（包括空行）都会被拒绝。空文本序列化为无 cell 的 notebook；
• 标记必须匹配# %% [code|markdown|raw]，cell:N可省略；
• cell:N指向未被使用的现有 cell时：克隆该 cell，更新其cell_type与source，其余无关字段（metadata、自定义字段）全部保留；
• 被复用/新建的 code cell 保留已有的execution_count与outputs而非清空；缺失时分别初始化为null与[]；
• markdown/raw cell 会移除execution_count与outputs字段；
• 没有可用的未使用原索引（索引越界、重复引用、或省略）时，创建带空元数据的新 cell。测试duplicate_or_missing_indices_create_fresh_cells明确了重复引用同一cell:N时，第二次引用会退化为新建 cell；
• notebook 级 metadata、format 字段与无关顶层字段之所以能存活，是因为序列化克隆原文档后只替换cells（next_notebook.insert("cells", ...)），键序也得以保持。

3.4 错误面

以下情形以硬失败抛出（NotebookError枚举，Display 文本即模型可见的报错）：

这些错误经由read和编辑管线等 notebook 感知调用方以普通工具错误上浮；而独立的write路径不解析notebook JSON，错误面与此无关。

4. Kernel 会话语义：真正存在的地方

Kernel 语义实现在executePython/PythonKernel（packages/coding-agent/src/eval/py/ 目录），只作用于eval工具的 Python 后端。

4.1 两种模式

PythonKernelMode的类型定义就在 executor.ts：

export type PythonKernelMode = "session" | "per-call";

• session（默认）：kernel 按(session id, cwd, interpreter)缓存；同一 key 的多个属主可以共享同一个被保留的 kernel；执行由工具的排他并发与后端执行路径串行化；死 kernel 在执行前被替换。
• per-call：为请求创建子进程、执行、并在finally中总是关闭子进程。

4.2 reset 行为

每次eval调用可带可选的reset标志。reset: true在执行该调用之前重置所选 Python 会话；它不影响其他已启用语言的运行时（工具 schema 中对该字段的描述为 "wipe this language's kernel before running. Other languages are untouched."，见 eval.ts）。

4.3 kernel 死亡、重启与重试

在 session 模式下：

• 若保留的子进程在执行前已不在存活状态，先替换再执行；
• 若执行中因子进程死亡而失败，kernel 被替换，代码重试一次；
• 同一 session key 的并发 reset 会合并：已在途的 reset 会被等待而不是再起一个，排在其后的运行在新重启的 kernel 上进行。这一合并逻辑可从 kernel-session-registry.ts 中resettingSessions的 in-flight 等待实现得到印证（JS 后端 context-manager.ts 使用同样的 coalesce 模式）。

5. 环境与会话变量注入

Kernel 启动与每次执行的 environment 补丁可以携带以下变量（完整清单见 executor-base.ts，runner.py 中 runner 侧同步列出）：

Runner 在启动时初始化进程状态：代码在请求的 cwd 中执行、被管理的 env 条目会反映到os.environ，且 cwd 位于sys.path上，从而 cell 内可以直接 import 项目模块。

6. 流式分片与显示处理（kernel 路径）

Python 后端使用NDJSON 子进程 runner（runner.py）。宿主按每次执行逐帧处理：

显示文本的 MIME 优先级：

1. text/markdown
2. text/plain
3. 转换后的text/html

此外被单独捕获的结构化输出：

• application/json→ JSON 显示输出
• image/png/image/jpeg→ 图片输出
• application/x-omp-status→ 状态事件

取消与超时：abort/timeout 向 runner 发送SIGINT（kernel.ts 的注释说明选用SIGINT是因为它会在用户代码内抛出真正的KeyboardInterrupt）；若 runner 在 interrupt 宽限窗口内未收敛，shutdown 升级，kernel 在下次调用时重建；超时输出会附加超时说明标注。

7. 截断与产物行为

streaming-output.ts 中的OutputSink被 kernel 执行路径使用：

• 对每个分片做净化（sanitize）；
• 跟踪总行数/输出行数与字节数；
• 可选地把完整输出落盘为 artifact 文件（配合artifactMaxBytes、artifactHeadBytes等参数控制头部/尾部窗口）；
• 输出超过配置阈值时，保留 UTF-8 安全的内存尾部缓冲，并对中段做省略。

eval工具把这些元数据转成结果截断提示与 TUI 警告，落盘产物以artifact://<id>指针形式引用（streaming-output.ts 的[raw output: artifact://<id>]尾部注记）。

必须强调的边界：notebook 文件转换不使用OutputSink——它不执行代码，因此没有流/产物截断管线。

8. 渲染器假设与格式化

• read/edit 的 notebook 表示：notebook 文件被渲染成文本交给模型。可见的 cell 标记是可编辑表示的一部分，不是序列化时被忽略的注释——编辑模型看到的每一行标记都会参与往返解析。
• Python 执行输出渲染器（与 notebook 编辑无关，仅共享 TUI 原语）：期望 per-cell 状态迁移（pending/running/complete/error）、可选的结构化状态事件、可选 JSON 输出树、图片输出，以及截断警告 + 可选artifact://<id>指针。

9. 实战工作流：编辑与执行如何组合

当一个工作流同时需要变更 notebook 与执行代码时，推荐流程是：

1. 用默认可编辑视图read该.ipynb，通过编辑管线变更这份虚拟文本（标记文本会被无损写回 JSON）；
2. 把希望执行的某个 cell 的源码复制进一次language: "py"的eval调用；
3. 对后续 cell 重复；session 模式的 Python 状态在多次调用间持久化；
4. 后续源码变更继续走编辑管线；若要整文件write，内容必须是 notebook JSON。

当前实现没有提供「同时变更.ipynb并通过 kernel 上下文执行 cell」的单一工具——这是使用方需要自己拼接两条路径的原因，也是理解本节所有细节的落点：文件路径保证你「改得干净」，kernel 路径保证你「跑得正确」，两者互不依赖。

【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi