jupyter-notebook

用途

Jupyter Notebook 技能用于创建干净、可复现的 Jupyter 笔记本，主要覆盖两种模式：

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

它建议优先使用内置模板和辅助脚本，以获得一致的结构并减少 JSON 编写错误。

何时使用

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

决策树

如果请求是探索性、分析性或假设驱动的，选择 experiment（实验）。
如果请求是教学性、分步骤或面向特定受众的，选择 tutorial（教程）。
如果编辑已有笔记本，将其视为重构：保留原意并改进结构。

技能路径（设置一次）

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）。

工作流程

锁定意图。
- 确定笔记本类型：experiment 或 tutorial。
- 明确目标、受众以及“完成”的标准。
从模板搭建。
- 使用辅助脚本，避免手工编写原始笔记本 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

用小型、可运行的步骤填充笔记本。
- 每个代码单元聚焦一个步骤。
- 添加简短的 markdown 单元，说明目的和预期结果。
- 当简短摘要足够时，避免庞大、嘈杂的输出。
应用合适的模式。
- 实验类遵循 references/experiment-patterns.md。
- 教程类遵循 references/tutorial-patterns.md。
编辑已有笔记本时安全操作。
- 保留笔记本结构；除非能改善自上而下的叙事，否则避免重排单元。
- 优先进行针对性编辑，而非整体重写。
- 如果必须编辑原始 JSON，先阅读 references/notebook-structure.md。
验证结果。
- 环境允许时，自上而下运行笔记本。
- 如果无法执行，明确说明，并指出如何在本地验证。
- 使用 references/quality-checklist.md 中的最终检查清单。

模板与辅助脚本

模板位于 assets/experiment-template.ipynb 和 assets/tutorial-template.ipynb。
辅助脚本加载模板、更新标题单元并写出笔记本。
脚本路径：$JUPYTER_NOTEBOOK_CLI（安装默认：$CODEX_HOME/skills/jupyter-notebook/scripts/new_notebook.py）

临时与输出约定

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

依赖（仅在需要时安装）

优先使用 uv 管理依赖。
本地执行笔记本的可选 Python 包：

uv pip install jupyterlab ipykernel

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

环境

无必需的环境变量。

参考映射

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