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 编解码Rustcrates/pi-edit/src/notebook.rs编辑管线的文件读写与持久化crates/pi-edit/src/files.rs编辑会话的记录与回显crates/pi-edit/src/session.rsread工具的 notebook 路由packages/coding-agent/src/tools/read.tseval工具定义packages/coding-agent/src/tools/eval.tsPython kernel 执行器packages/coding-agent/src/eval/py/executor.tsPython kernel 生命周期packages/coding-agent/src/eval/py/kernel.ts输出截断/落盘 Sinkpackages/coding-agent/src/session/streaming-output.ts两条路径的差异可以概括为文件转换路径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_textapply_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时第二次引用会退化为新建 cellnotebook 级 metadata、format 字段与无关顶层字段之所以能存活是因为序列化克隆原文档后只替换cellsnext_notebook.insert(cells, ...)键序也得以保持。3.4 错误面以下情形以硬失败抛出NotebookError枚举Display 文本即模型可见的报错错误触发条件读取时 notebook 缺失read找不到文件Invalid JSON in notebook: displayJSON 解析失败Invalid notebook structure (expected object)顶层不是对象Invalid notebook structure (missing cells array)缺cells或不是数组Invalid notebook cell i in display某个 cell 不是对象或cell_type非法Invalid notebook editable representation ...虚拟文本首行不是合法标记这些错误经由read和编辑管线等 notebook 感知调用方以普通工具错误上浮而独立的write路径不解析notebook JSON错误面与此无关。4. Kernel 会话语义真正存在的地方Kernel 语义实现在executePython/PythonKernelpackages/coding-agent/src/eval/py/ 目录只作用于eval工具的 Python 后端。4.1 两种模式PythonKernelMode的类型定义就在 executor.tsexport 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 languages 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.tsrunner.py 中 runner 侧同步列出变量用途PI_SESSION_FILE会话文件位置用于派生产物路径PI_ARTIFACTS_DIR产物目录存在时优先于从PI_SESSION_FILE派生的路径PI_TOOL_BRIDGE_URL工具桥接服务地址PI_TOOL_BRIDGE_TOKEN工具桥接鉴权令牌PI_TOOL_BRIDGE_SESSION工具桥接会话标识PI_EVAL_LOCAL_ROOTSlocal://根映射JSON供 prelude.py 改写本地文件引用Runner 在启动时初始化进程状态代码在请求的 cwd 中执行、被管理的 env 条目会反映到os.environ且 cwd 位于sys.path上从而 cell 内可以直接 import 项目模块。6. 流式分片与显示处理kernel 路径Python 后端使用NDJSON 子进程 runnerrunner.py。宿主按每次执行逐帧处理帧处理stdout/stderr文本分片回调onChunkdisplay/resultMIME bundle 渲染errortraceback 文本 结构化错误元数据done最终状态、执行计数、取消状态显示文本的 MIME 优先级text/markdowntext/plain转换后的text/html此外被单独捕获的结构化输出application/json→ JSON 显示输出image/png/image/jpeg→ 图片输出application/x-omp-status→ 状态事件取消与超时abort/timeout 向 runner 发送SIGINTkernel.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 与执行代码时推荐流程是用默认可编辑视图read该.ipynb通过编辑管线变更这份虚拟文本标记文本会被无损写回 JSON把希望执行的某个 cell 的源码复制进一次language: py的eval调用对后续 cell 重复session 模式的 Python 状态在多次调用间持久化后续源码变更继续走编辑管线若要整文件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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考