需要把 Jupyter notebook 迁移到…

适用于将 .ipynb 转换为 marimo .py，并确保保留原 notebook 目的、工作流且可运行。

适用场景

解决思路

1. 在阅读源 notebook 之前先运行转换器：`uvx marimo convert <notebook.ipynb> -o <notebook.py>`。
2. 只有转换失败或生成文件遗漏必需信息时，才阅读 `.ipynb` 文件。
3. 把生成的文件当作初稿。
4. 在转换后以及进行大量编辑后，运行：`uvx marimo check <notebook.py>`。
5. 检查 PEP 723 元数据中所有必需的包。转换器可能遗漏某些包安装形式。
6. 删除残留的安装单元格和过时的安装说明。仅在需要时添加版本约束。
7. 当 notebook 使用 PEP 723 元数据时，使用 `--sandbox`。
8. 保留源 notebook 的目的和预期工作流。
9. 为呈现而安排单元格。marimo 根据变量定义和引用决定执行顺序。
10. 单元格可以出现在定义其输入的单元格之前。
11. 当当前单元格边界降低清晰度时，合并或拆分单元格。
12. 删除多余的 Jupyter 产物，例如不必要的 `display()` 调用。
13. 检查转换后的 magic 命令。保留有效的转换，并解决报告不支持 magic 的注释。
14. 将需要渲染的值放在每个单元格的最终表达式中。
15. 让添加的 UI 和辅助函数与 notebook 目的成比例。
16. 替换会等待终端输入或在目标界面中无法工作的交互式输入方式。使用合适的 UI 控件、脚本参数或环境值。
17. 不要打印、记录或保存机密。对于多个环境值，考虑 [EnvConfig](https://koaning.github.io/wigglystuff/reference/env-config.md)。
18. 识别昂贵工作和外部副作用。如果工作必须等待，用 `mo.stop()` 和合适的 UI 元素将其门控。
19. 如果用户必须一起提交多个值，使用表单。
20. 在门控之后定义下游值，以便依赖图推迟依赖单元格。
21. 用简单的原生组件呈现有用结果。仅在预期工作流需要时添加实时刷新。
22. 对于 ipywidgets，阅读 `references/widgets.md`。
23. 对于 LaTeX 和 MathJax，阅读 `references/latex.md`。
24. 在所有编辑后再次运行 `marimo check`。
25. 在每种预期模式下运行 notebook。确认其具有预期行为。
26. 在实际可行时，并排打开源 notebook 和转换后的 notebook，并邀请用户审查。
27. 比较内容、控件、输出和工作流。单元格顺序和布局可以不同。
28. 检查更改的文件中是否有机密、生成的数据、缓存、日志和其他运行时文件。

适用边界 · 注意事项

• 目标格式不是 marimo notebook，或不需要从 Jupyter 迁移时。
• 环境不允许运行 `uvx`/`marimo`，或无法安装和验证所需依赖时。
• 源 notebook 依赖大量不受支持的 Jupyter 交互功能或不可安装内核，导致转换后无法验证预期行为时。