NotebookEditTool：编辑 Notebook

它为什么不是普通版 FileEditTool

.ipynb 文件虽然本质上是 JSON，但语义上它不是普通文本文件，而是：

• 一组有顺序的 cell
• 混合了 code / markdown
• 带输出、元数据、语言信息

如果直接把 Notebook 当普通文本改，最容易出现两类问题：

• 结构被破坏，文件打不开
• 只想改一个 cell，却误伤整个 notebook

所以 Claude Code 给它单独做了 NotebookEditTool。

关键源码

tools/NotebookEditTool/NotebookEditTool.ts：

export const inputSchema = z.strictObject({
  notebook_path: z.string(),
  cell_id: z.string().optional(),
  new_source: z.string(),
  cell_type: z.enum(['code', 'markdown']).optional(),
  edit_mode: z.enum(['replace', 'insert', 'delete']).optional(),
})

这几个字段说明它的操作粒度是 cell 级，不是整文件字符串级。

调用链

实现重点

它做了几件普通文件编辑工具不会做的事：

• 强制要求目标文件是 .ipynb
• 支持 replace / insert / delete 三种 cell 操作
• insert 时要求明确 cell_type
• 校验 cell 是否存在、ID 是否有效
• 也要求“先读再改”，和普通文件编辑链路一致

源码里有一条很重要：

// Require Read-before-Edit (matches FileEditTool/FileWriteTool).

这说明 Anthropic 很强调一致性：
即使 Notebook 是特殊对象，也不能绕开“读快照 -> 再编辑”的时序约束。

一次典型使用路径

1. 先用 Read 看 notebook 的 cell 结构和内容
2. 定位要改哪个 cell
3. 用 NotebookEditTool 做 replace / insert / delete
4. 再回到主线程继续验证结果

它和相邻工具的关系

最容易误解它的地方

误解一：Notebook 反正是 JSON，直接 Edit 就行

从底层格式看也许可以，但从产品行为看不应该。
Claude Code 明确把 Notebook 提升成了专门文档类型。

误解二：它只是换了个文件扩展名

不是。
它的编辑对象是 cell，不是整段原始 JSON。

小结

NotebookEditTool 的价值在于：

Claude Code 没把 Notebook 降级成普通文本，而是给这种“代码 + 文档”混合格式单独做了一条受控编辑链路。