Jupytext Skill 用于改善 Jupyter Notebook 在版本控制中的可审阅性,提供 .ipynb 与 Markdown 文本笔记本之间的双向转换、配对与同步能力。
用途:当用户希望在 Git 中更清晰地审阅笔记本变更,而非直接查看原始 .ipynb 文件时,可使用本技能。它支持单向导出(.ipynb 转 .md 或 md:myst)、单向还原(.md 或 md:myst 转回 .ipynb)、配对工作流(保持 .ipynb 与 Markdown 同步)以及保真度检查(确认笔记本经过往返转换后结构不发生意外漂移)。
主要能力:
- 格式转换:支持 md 与 md:myst 两种 Markdown 格式,以及 py:percent 脚本式文本笔记本。
- 配对与同步:可将 .ipynb 与 md、md:myst 或 py:percent 配对,并通过 sync 命令保持内容一致;同步仅对已配对文件有效,未配对时需先执行 pair。
- 配套脚本:提供 scripts/jupytext_roundtrip.py,支持 pair、sync、convert、test 与 roundtrip-test 等命令,可通过 uv 运行。
- 项目级配置:支持在 pyproject.toml 的 [tool.jupytext] 中设置统一配对规则,例如 formats = "ipynb,md:myst"。
使用方式:
- 首选配套脚本进行可重复操作,例如:uv run --with jupytext python scripts/jupytext_roundtrip.py --help。
- 也可直接调用 Jupytext CLI,例如: uv run --with jupytext python -m jupytext --to md:myst notebook.ipynb uv run --with jupytext python -m jupytext --to notebook notebook.md -o notebook.ipynb uv run --with jupytext python -m jupytext --set-formats ipynb,md:myst notebook.ipynb uv run --with jupytext python -m jupytext --sync notebook.md
- 每次转换或同步后应检查生成文件及单元格结构;涉及输出时需确认配对的 .ipynb 仍存在并被更新。
- 若文本笔记本含 IPython 语法(如 !、%pip、%cd、magics),普通 Python 编译不足以验证,应使用 Jupytext 同步/往返检查,必要时使用 IPython 感知的解析或实际执行。
适用场景:
- 需要在 Git 中审阅笔记本内容变更。
- 面向 MyST 或 Jupyter Book 工作流,或偏好结构化 Markdown 代码围栏。
- 代码密集、使用 IPython 语法、希望以脚本优先方式呈现的笔记本,可选用 py:percent。
- 希望保留已保存输出、执行计数或最顺畅的笔记本重新打开体验时,应保留配对的 .ipynb。
限制与注意事项:
- 纯 Markdown 笔记本存储输入与部分元数据,不保留输出;输出需依赖配对的 .ipynb。
- 不要在没有最终同步的情况下同时独立编辑 Markdown 与配对的 .ipynb。
- 不要用还原的笔记本覆盖已有 .ipynb,除非用户要求替换或工作流明确需要。
- 若仓库已有 jupytext.toml 或 pyproject.toml 中的 [tool.jupytext] 配置,应遵循现有格式策略。
- sync 不是发现命令,未配对文件需先执行 pair。
- 配套的 jupytext_workflow.md、jupytext_notes.md 等资源在资料中仅提及用途,具体内容暂未提供。