Jupytext 笔记本配对

问题：笔记本 JSON 让审查与协作变重

Jupyter 笔记本整体以 JSON 存储，单元格里混杂了代码、输出、图片的 base64 编码和元数据。一次简单编辑在 Git diff 中可能膨胀成数百行，审查者很难看清逻辑上究竟改了什么；自动化代理直接编辑笔记本 JSON 时，既可能破坏结构，生成的补丁也几乎不可读。团队往往只能在放弃版本控制和接受不可审查的历史之间二选一。

核心思路：给笔记本配一份纯文本副本

这个技能借助 jupytext 为每个笔记本维护一个平行的纯文本表示——.py 或 .md 文件，并让两者保持同步，任一侧的修改都会反映到另一侧。

关键能力与步骤：

• 格式映射：笔记本可编码为 py:percent 等格式，.py 文件用百分比标记划分代码与输出，看起来就像一份普通脚本。
• 编辑器集成：在 JupyterLab 中激活 Jupytext 后，.py 和 .md 文件会带笔记本图标，右键即可当作笔记本打开。
• 工作流迁移：开发者可以在纯文本上做版本控制、diff 和重构；审查者读 .py 或 .md 的 diff 就能看懂改动；代理编辑的对象是可读文本，而不是脆弱的 JSON 结构。

适用边界与注意点

• 该方案依赖 jupytext 的同步机制，笔记本与文本表示必须成对管理，只改一侧可能产生不一致。
• py:percent 等格式会把单元格边界和部分输出编码进文本，并非所有笔记本元素都能无损映射。
• 需要 JupyterLab 或 Jupyter Notebook 环境支持，重启服务器后应确认 Jupytext 已生效。
• 对输出密集、含富媒体的笔记本，首次转换后需要检查文本表示的可读性。