Jupyter Notebook 管理器

完整的 Jupyter Notebook 管理系统，支持 Claude 创建、执行、调试、分析和优化 Jupyter Notebook，并深度集成数据科学工作流。

🎯 何时使用该技能

触发条件

当您遇到以下情况时，请使用该技能：

1. 用户提及与 Jupyter 相关的关键词：

   • “创建一个 Jupyter Notebook”
   • “运行这个 Notebook”
   • “调试我的 .ipynb 文件”
   • “分析 Notebook 的结果”
   • “优化我的 Notebook”

2. 用户请求数据分析工作流：

   • “搭建数据分析流水线”
   • “执行数据清洗”
   • “可视化分析结果”
   • “生成分析报告”

3. 用户提供 .ipynb 文件：

   • 检测到 .ipynb 文件引用
   • 用户上传 Notebook 文件
   • 工作目录中包含 Notebook

4. 用户需要 Notebook 操作：

   • “将 Notebook 转换为 Python 脚本”
   • “从 Notebook 中提取代码”
   • “合并多个 Notebook”
   • “生成 Notebook 模板”

🚀 核心能力

1. Notebook 创建与模板

适用场景：用户需为特定分析任务新建 Notebook

能力：

• 从零生成结构规范的 Notebook
• 提供领域专用模板（EDA、ML、可视化等）
• 自动添加 Markdown 文档与代码单元格
• 配置 Kernel 及元数据
• 支持自定义模板

示例：

# 用户：“为销售数据创建一个数据分析 Notebook”
# → 生成结构化 Notebook，包含：
#   - 导入单元格（pandas、numpy、matplotlib）
#   - 数据加载部分
#   - EDA 部分（含常见分析）
#   - 可视化部分
#   - 总结部分

2. Notebook 执行与监控

适用场景：用户需要运行 Notebook 并跟踪执行过程

能力：

• 以编程方式执行 Notebook
• 监控执行进度
• 捕获输出与错误信息
• 处理长时间运行的单元格
• 支持参数化执行

示例：

# 用户：“用 dataset=sales_2024.csv 运行 analysis.ipynb”
# → 使用参数执行 Notebook
# → 显示实时进度
# → 捕获全部输出
# → 报告执行耗时与状态

3. 调试与错误分析

适用场景：Notebook 执行失败或产生意外结果

能力：

• 定位报错单元格及堆栈追踪
• 分析错误发生点的变量状态
• 针对常见问题提出修复建议
• 检测依赖项问题
• 检查数据质量问题

示例：

# 用户：“我的 Notebook 在第 5 个单元格失败”
# → 分析错误回溯信息
# → 检查报错前变量取值
# → 定位根本原因（例如：缺失列）
# → 提供带修正代码的解决方案

4. 变量检查与状态分析

适用场景：用户需要理解 Notebook 当前状态与变量

能力：

• 提取所有变量及其类型
• 显示 DataFrame 摘要信息
• 可视化数据分布
• 追踪变量在各单元格间的流转
• 识别未使用的变量

示例：

# 用户：“这个 Notebook 中定义了哪些变量？”
# → 列出所有变量及其类型
# → 显示 DataFrame 形状与 dtypes
# → 展示内存占用
# → 突出关键变量

5. 代码质量与性能优化

适用场景：用户希望提升 Notebook 代码质量

能力：

• 识别代码异味（code smells）与反模式
• 提出性能优化建议
• 识别冗余计算
• 推荐向量化操作
• 检查 PEP 8 合规性

示例：

# 用户：“优化我的数据处理 Notebook”
# → 识别可向量化的慢速循环
# → 建议对高开销操作启用缓存
# → 推荐更优的 pandas 操作方式
# → 提供优化后的代码片段

6. Notebook 转换与导出

适用场景：用户需要不同格式或希望模块化代码

能力：

• 将 Notebook 转换为 Python 脚本
• 导出为 HTML / PDF / Markdown
• 提取函数用于复用
• 生成文档
• 构建清晰的代码模块

示例：

# 用户：“将我的 Notebook 转换为 Python 模块”
# → 提取全部函数定义
# → 构建标准模块结构
# → 添加 docstring
# → 生成可直接导入的 .py 文件

7. 结果可视化与报告生成

适用场景：用户需要展示或总结 Notebook 结果

能力：

• 生成执行摘要（executive summary）
• 构建结果仪表板（dashboard）
• 提炼关键发现
• 汇总可视化图表
• 格式化输出报告

示例：

# 用户：“总结我的分析 Notebook 的结果”
# → 提取全部图表与表格
# → 识别关键指标与洞察
# → 生成 Markdown 报告
# → 包含数据质量备注

8. 协作功能

适用场景：多人协同编辑 Notebook

能力：

• 比较 Notebook 版本差异
• 合并 Notebook 修改内容
• 生成 diff 报告
• 追踪单元格变更
• 解决冲突

示例：

# 用户：“将我的 Notebook 与上一版本进行对比”
# → 显示逐单元格差异
# → 突出输出变化
# → 标识新增/删除的单元格
# → 提供冲突解决建议

🛠️ 工具集成

核心工具

1. nbformat — Notebook 文件 I/O 与操作
2. nbconvert — 格式转换与执行
3. papermill — 参数化执行
4. nbdime — Notebook 差异比对与合并
5. pandas — 数据操作与分析
6. matplotlib/seaborn — 可视化
7. jupyter_client — Kernel 管理

脚本集成

该技能内置以下实用脚本：

• scripts/notebook_creator.py — 基于模板的 Notebook 生成
• scripts/notebook_executor.py — 稳健的 Notebook 执行
• scripts/notebook_debugger.py — 错误分析与调试
• scripts/notebook_analyzer.py — 代码质量与优化分析
• scripts/notebook_converter.py — 格式转换工具
• scripts/notebook_reporter.py — 结果提取与报告生成

📋 工作流示例

工作流 1：创建并运行分析任务

用户：“创建销售分析 Notebook，并使用 Q4_sales.csv 运行”

步骤 1：生成模板
→ 调用 notebook_creator.py，指定模板为 "sales-analysis"
→ 针对 Q4 数据定制内容

步骤 2：配置参数
→ 设置 data_file = "Q4_sales.csv"
→ 设置 analysis_type = "quarterly"

步骤 3：执行 Notebook
→ 调用 notebook_executor.py
→ 监控进度（显示第 N/M 个单元格）

步骤 4：报告结果
→ 提取关键指标
→ 展示可视化图表
→ 总结核心发现

工作流 2：调试失败的 Notebook

用户：“我的 notebook analysis.ipynb 在第 10 个单元格崩溃”

步骤 1：定位错误
→ 使用 nbformat 解析 Notebook
→ 定位第 10 个单元格及错误回溯信息

步骤 2：分析上下文
→ 检查第 1–9 个单元格中的变量
→ 获取报错前的 DataFrame 状态

步骤 3：诊断问题
→ 分析错误消息
→ 检查常见问题（如缺失列、类型错误等）

步骤 4：提出修复建议
→ 提供修正后的代码
→ 解释根本原因
→ 给出预防建议

工作流 3：优化运行缓慢的 Notebook

用户：“这个 Notebook 运行耗时 10 分钟，能否优化？”

步骤 1：执行性能分析
→ 启用计时功能运行
→ 定位运行缓慢的单元格

步骤 2：分析代码
→ 识别低效模式
→ 寻找向量化机会

步骤 3：提出改进建议
→ 展示优化后的代码版本
→ 预估性能提升幅度

步骤 4：验证结果
→ 测试优化后的 Notebook
→ 验证输出与原始结果一致

🎓 最佳实践

Notebook 结构

1. 以导入与配置开头

   • 将全部 import 语句集中置于顶部
   • 尽早设置显示选项
   • 配置日志记录

2. 使用 Markdown 编写文档

   • 使用 ## 添加章节标题
   • 说明分析步骤
   • 记录假设条件

3. 模块化代码单元格

   • 每个单元格仅执行一项逻辑操作
   • 避免过长的单元格
   • 控制单元格输出规模

4. 采用清晰的变量命名

   • 使用描述性名称
   • 遵循命名规范
   • 避免单字母变量（i、j、k 除外）

代码质量

1. 在可向量化时避免显式循环

   # 不佳写法
   for i in range(len(df)):
       df.loc[i, 'new_col'] = df.loc[i, 'a'] + df.loc[i, 'b']
   
   # 推荐写法
   df['new_col'] = df['a'] + df['b']
   

2. 缓存高开销计算结果

   # 检查是否已计算
   if not os.path.exists('cached_result.pkl'):
       result = expensive_computation()
       result.to_pickle('cached_result.pkl')
   else:
       result = pd.read_pickle('cached_result.pkl')
   

3. 优雅地处理错误

   try:
       df = pd.read_csv('data.csv')
   except FileNotFoundError:
       print("⚠️ 数据文件未找到，使用示例数据")
       df = generate_sample_data()
   

性能提示

1. 使用合适的数据类型

   • 对低基数字符串列转为 categorical 类型
   • 尽可能使用 int32 替代 int64
   • 充分利用 datetime 类型

2. 对大文件分块处理

   chunks = pd.read_csv('large_file.csv', chunksize=10000)
   result = pd.concat([process(chunk) for chunk in chunks])
   

3. 善用 pandas 内置函数

   • 使用 query() 进行过滤
   • 使用 eval() 计算表达式
   • 使用 pipe() 实现链式调用

🔍 常见错误模式与解决方案

常见问题

调试检查清单

# 1. 检查数据加载
print(f"Shape: {df.shape}")
print(f"Columns: {df.columns.tolist()}")
print(f"Dtypes:n{df.dtypes}")

# 2. 检查缺失值
print(f"Missing values:n{df.isnull().sum()}")

# 3. 检查数据类型
print(f"Object columns: {df.select_dtypes('object').columns.tolist()}")

# 4. 检查内存占用
print(f"Memory: {df.memory_usage(deep=True).sum() / 1024**2:.2f} MB")

# 5. 检查重复值
print(f"Duplicates: {df.duplicated().sum()}")

📊 模板库

可用模板

1. exploratory-data-analysis — 全面的 EDA 工作流
2. machine-learning-training — 机器学习模型开发流水线
3. time-series-analysis — 时间序列预测
4. data-cleaning — 数据质量与清洗
5. statistical-testing — 假设检验与统计分析
6. visualization-dashboard — 交互式可视化
7. data-pipeline — ETL 与数据转换
8. report-generation — 自动化报告生成

模板使用方法

# 基于模板创建 Notebook
python scripts/notebook_creator.py 
  --template exploratory-data-analysis 
  --output eda_analysis.ipynb 
  --data-file sales_data.csv 
  --target-column revenue

🔗 集成点

与其他技能集成

• pandas-data-wrangler：数据操作运算
• matplotlib-plotter：高级可视化
• ml-model-trainer：模型训练与评估
• data-pipeline-builder：ETL 工作流

与外部工具集成

• Jupyter Lab / Notebook：交互式开发
• VS Code：Notebook 编辑与调试
• Papermill：批量执行与参数化
• nbconvert：发布与共享
• git：版本控制（配合 nbstripout）

🎯 成功标准

一次成功的技能调用应满足以下要求：

✅ 准确理解用户关于 Notebook 的意图
✅ 选择恰当的操作类型（创建 / 运行 / 调试 / 优化）
✅ 在完善错误处理机制下执行操作
✅ 提供清晰的进度反馈
✅ 返回可操作的结果或洞见
✅ 提供后续步骤或改进方向
✅ 妥善处理边界情况

📚 资源

文档链接

• Jupyter 官方文档
• nbformat 规范
• nbconvert 使用指南
• Papermill 官方文档

示例 Notebook

参见 examples/ 目录下的内容：

• 典型分析 Notebook 示例
• 模板使用演示
• 用例教程
• 最佳实践示例

🚨 局限性

1. Kernel 管理：无法直接与正在运行的 Kernel 交互（需通过脚本间接实现）
2. 交互式 Widgets：对 ipywidgets 的支持有限
3. 长时间运行：极长计算任务（>10 分钟）可能超时
4. GPU 运算：不支持直接访问 GPU Kernel
5. 大文件处理：对超大 Notebook（>100MB）存在内存限制

📝 备注

• 执行前始终校验 Notebook 结构完整性
• 使用超时机制防止陷入无限循环
• 在参数化执行中对用户输入进行安全清洗
• 提取输出时需考虑 Notebook 尺寸影响
• 使用多种 Notebook 格式对脚本进行测试
• 保持对 Jupyter 4.x 和 5.x 格式的兼容性

版本: 1.0.0
最后更新时间: 2026-04-16
维护者: AI Skills Community