Jupyter 笔记本整理

Jupyter Notebook 技能#

为两种主要模式创建整洁、可复现的 Jupyter notebook：

• 实验与探索性分析
• 教程与面向教学的逐步讲解

优先使用随附模板和辅助脚本，以获得一致的结构并减少 JSON 错误。

何时使用#

• 从零创建新的 .ipynb notebook。
• 将粗略笔记或脚本转换为结构化 notebook。
• 重构现有 notebook，使其更具可复现性且更易快速浏览。
• 构建供他人阅读或重新运行的实验或教程。

决策树#

• 如果请求属于探索性、分析性或假设驱动，请选择 experiment。
• 如果请求属于教学性、分步骤或面向特定受众，请选择 tutorial。
• 如果编辑现有 notebook，请将其视为重构：保留意图并改进结构。

技能路径（设置一次）#

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export JUPYTER_NOTEBOOK_CLI="$CODEX_HOME/skills/jupyter-notebook/scripts/new_notebook.py"

用户级技能安装在 $CODEX_HOME/skills 下（默认：~/.codex/skills）。

工作流#

1. 明确意图。 确定 notebook 类型：experiment 或 tutorial。 记录目标、受众以及“完成”的标准。

2. 从模板搭建。 使用辅助脚本，避免手动编写原始 notebook JSON。

uv run --python 3.12 python "$JUPYTER_NOTEBOOK_CLI" \
  --kind experiment \
  --title "Compare prompt variants" \
  --out output/jupyter-notebook/compare-prompt-variants.ipynb

uv run --python 3.12 python "$JUPYTER_NOTEBOOK_CLI" \
  --kind tutorial \
  --title "Intro to embeddings" \
  --out output/jupyter-notebook/intro-to-embeddings.ipynb

3. 用小型、可运行的步骤填充 notebook。 让每个代码单元格只聚焦于一个步骤。 添加简短的 Markdown 单元格，说明目的和预期结果。 当简短摘要足够时，避免庞大且杂乱的输出。

4. 应用合适的模式。 对于实验，遵循 references/experiment-patterns.md。 对于教程，遵循 references/tutorial-patterns.md。

5. 处理现有 notebook 时安全编辑。 保留 notebook 结构；除非能改善自上而下的叙述，否则避免重排单元格。 优先进行针对性编辑，而不是整体重写。 如果必须编辑原始 JSON，请先查看 references/notebook-structure.md。

6. 验证结果。 在环境允许时，自上而下运行 notebook。 如果无法执行，请明确说明，并指出如何在本地验证。 使用 references/quality-checklist.md 中的最终检查清单。

模板和辅助脚本#

• 模板位于 assets/experiment-template.ipynb 和 assets/tutorial-template.ipynb。
• 辅助脚本会加载模板、更新标题单元格，并写出 notebook。

脚本路径：

• $JUPYTER_NOTEBOOK_CLI（安装后的默认路径：$CODEX_HOME/skills/jupyter-notebook/scripts/new_notebook.py）

临时文件和输出约定#

• 使用 tmp/jupyter-notebook/ 存放中间文件；完成后删除。
• 在此仓库中工作时，将最终产物写入 output/jupyter-notebook/ 下。
• 使用稳定且具描述性的文件名（例如 ablation-temperature.ipynb）。

依赖项（仅在需要时安装）#

优先使用 uv 进行依赖管理。

用于本地 notebook 执行的可选 Python 包：

uv pip install jupyterlab ipykernel

随附的脚手架脚本仅使用 Python 标准库，不需要额外依赖。

环境#

无必需的环境变量。

参考索引#

• references/experiment-patterns.md：实验结构与启发式方法。
• references/tutorial-patterns.md：教程结构与教学流程。
• references/notebook-structure.md：notebook JSON 结构与安全编辑规则。
• references/quality-checklist.md：最终验证检查清单。