jupyter-notebook

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：最终验证清单。