IPYNB Notebook（.ipynb）
概览
这个 skill 用于指导你以“工程化”的方式操作 .ipynb 文件与 notebook 项目（不限定 Jupyter，也适用于 Google Colab / VS Code Notebook 等环境）：
- 清晰的文件结构：notebook 作为界面，逻辑沉到可复用的
scripts/与lib/ - Token 高效工作流：在 AI 读写 notebook 时尽量只读结构/代码，不读大输出
- 可展示模式：用于 demo、团队共享、文档化的结构与输出规范
- 可复现环境：优先使用
uv，或退回到venv，确保可重复运行
适用场景
在以下场景使用本 skill：
- 新建 notebook 项目或单个 notebook
- 审阅 / 编辑已有
.ipynb（尤其是大文件、输出很多、diff 难读的情况） - 整理 notebook 项目结构，把“可复用逻辑”从 notebook 抽到模块/脚本
- 为演示、分享、归档做“可跑通、可复现、可导出”的整理
- 改善 notebook 的长期可维护性与版本控制体验
核心原则
Notebook 是界面（interface），不是库（library）。
notebook 适合交互探索与叙事展示；可复用、可测试、可自动化的逻辑应放在：
scripts/：可直接运行的脚本（不依赖 notebook UI）lib/：可复用模块（被 notebook 与脚本共同 import）
这样做带来的收益：
- 多 notebook 复用同一套逻辑
- 无需跑 notebook 就能测试关键逻辑
- 更容易在 CI/CD 中自动化执行（如导出、定时跑数）
- diff 更干净、版本控制更友好
快速上手
新建一个 notebook 项目（推荐 uv）
- 初始化项目（uv）
# Create project directory mkdir notebook-project && cd notebook-project # Initialize uv project uv init # Add dependencies (pick what you need) uv add jupyterlab pandas plotly - 建立目录结构
mkdir -p scripts lib data/{raw,processed} reports docs.archive touch data/.gitkeep data/raw/.gitkeep data/processed/.gitkeep reports/.gitkeep - 准备
.gitignore（示例）# Virtual environments.venv/ # Data and outputs (keep.gitkeep) data/**!data/**/!data/**/.gitkeep reports/**!reports/**/!reports/**/.gitkeep # Jupyter.ipynb_checkpoints/ # Python __pycache__/ *.pyc # Environment.env - 启动 notebook 环境
uv run jupyter lab - 需要更详细的模式时再加载引用文档：
- references/file-structure.md：目录结构与项目组织 - references/presentation-patterns.md：演示/分享结构与输出规范 - references/token-efficiency.md：AI 读写 notebook 的 token 高效策略
审阅 / 对比一个已有 notebook（尽量只看结构与代码）
推荐工作流：
- 先看结构，不读输出
# Cell types and counts jq '.cells | group_by(.cell_type) | map({type:.[0].cell_type, count: length})' notebook.ipynb # Code cells with outputs jq '[.cells[] | select(.cell_type == "code") | select(.outputs | length > 0)] | length' notebook.ipynb - 只对比代码 cell
# Extract code sources to compare jq '.cells[] | select(.cell_type == "code") |.source' notebook1.ipynb > /tmp/code1.json jq '.cells[] | select(.cell_type == "code") |.source' notebook2.ipynb > /tmp/code2.json diff /tmp/code1.json /tmp/code2.json - 确有必要再读取 notebook 正文
- 先明确要读哪一段、哪类 cell，再读 - 大 notebook 优先按 cell 范围/主题分段读取 - 细节见 references/token-efficiency.md
整理一个 notebook 项目（抽逻辑、控输出、让它可复现）
目录组织建议见 references/file-structure.md。这里给一个可执行的最小迁移步骤：
- 盘点根目录文件数量：
ls -1 | wc -l - 移动脚本到
scripts/，文档到docs/，旧 notebook 到.archive/ - 更新 notebook 中的 import：
from lib import module_name - 验证仍可正常运行
可复现环境（uv / venv）
为什么优先 uv？
uv 适合做以下事情：
- 快速、可复现的依赖管理
- 在项目依赖环境中运行工具（如
jupyter,nbconvert） - 不污染全局 Python
- 跨平台一致性更好
常用命令模式
添加依赖：
uv add plotly pandas duckdb安装工具（可选）：
uv tool install jupyterlab在项目环境中运行：
uv run jupyter lab单文件脚本声明依赖（用于 uv run）：
# /// script
# requires-python = ">=3.11"
# dependencies = [
# "pandas",
# "plotly",
# ]
# ///
import pandas as pd
import plotly.express as px
# Script code here运行：uv run script.py
如果你不能使用 uv，也可以用 python -m venv.venv + pip，但要确保能一键复现（建议 requirements.txt 或 pyproject.toml + lockfile）。
Token 高效工作流（面向 AI 与版本控制）
当通过 AI 助手读写 .ipynb 时：
默认策略：提交前清理输出
推荐 pre-commit：
# .pre-commit-config.yaml
repos:
- repo: https://github.com/kynan/nbstripout
rev: 0.6.1
hooks:
- id: nbstripout确需保留输出时（不推荐）：
SKIP=nbstripout git commit -m "Add notebook with visualization outputs"更常见的做法是：输出落盘到 reports/，notebook 保持“可重新运行即可复现输出”（见 references/token-efficiency.md）。
读之前先查询（结构优先）
先看结构：
jq '.cells | group_by(.cell_type) | map({type: .[0].cell_type, count: length})' notebook.ipynb只看代码：
jq '.cells[] | select(.cell_type == "code") | .source' notebook.ipynb输出要“可控、可复现”
倾向输出摘要，不要直接 dump 大对象：
print(f"[OK] Loaded {len(df_alarms):,} rows")
print(f"Columns: {', '.join(df_alarms.columns)}")
print(f"Date range: {df_alarms['timestamp'].min()} to {df_alarms['timestamp'].max()}")大输出落盘到文件：
fig.write_html(report_dir / "visualization.html")
print(f"[OK] Saved visualization to {report_dir}/visualization.html")完整策略见 references/token-efficiency.md。
演示 / 分享模式
推荐的 notebook 结构
- 标题与概览 - 背景与目标
- 准备 - 导入与配置
- 数据加载 - 带反馈与错误处理
- 摘要 - 高层统计
- 可视化 - 带解释与使用提示
- 结论 - 关键发现
更“专业”的输出习惯
统一状态输出：
print("[OK] Success")
print("[WARN] Warning")
print("[ERR] Error")
print("[INFO] Note")数字格式化：
print(f"Total: {count:,}") # 2,055 instead of 2055按日期落盘到 reports：
from datetime import datetime
today = datetime.now().strftime('%Y-%m-%d')
report_dir = Path("reports") / today
report_dir.mkdir(parents=True, exist_ok=True)
fig.write_html(report_dir / "chart.html")
latest = Path("reports/latest")
if latest.exists():
latest.unlink()
latest.symlink_to(today, target_is_directory=True)完整模式与模板见 references/presentation-patterns.md。
资源索引
references/file-structure.md
包含：
- 推荐目录结构
- 文件组织规则与命名约定
- Git 友好（ignore、diff、清理输出）
- 现有项目迁移步骤
- 示例结构
适合在： 新建项目、重构目录、统一约定时加载。
references/token-efficiency.md
包含：
- 输出清理与版本控制策略
- 不读输出的结构化查询方法
- 大 notebook 的分段读取与 diff 思路
- 常用
jq/ CLI 模式 - cell 输出管理
适合在： 需要省 token、要审阅大 notebook、要做自动化处理时加载。
references/presentation-patterns.md
包含：
- 演示型 notebook 的结构模板
- 可读性与叙事节奏
- 交互元素与可导出策略
- 错误处理与可复现检查点
- Markdown / Code cell 分工
- 导出 HTML/PDF 的注意事项
适合在： 做 demo、团队分享、发布文档前加载。
最佳实践速记
- 结构：notebook 作为界面，逻辑下沉到
scripts//lib/ - 依赖：优先 uv，保证一键复现
- 版本控制：默认清理输出（pre-commit/nbstripout/nbconvert）
- 省 token：先查询结构再阅读；大输出落盘
- 展示：叙事清晰、输出克制、错误处理明确
- 可复现：确保 “Restart & Run All” 能跑通
- 数据流：raw → processed → reports
- Git 友好：忽略数据与产物，保留目录骨架（
.gitkeep）
示例流程
# 1. Create project
mkdir my-analysis && cd my-analysis
uv init
uv add jupyterlab pandas plotly
# 2. Set up structure
mkdir -p scripts lib data/{raw,processed} reports
touch data/.gitkeep data/raw/.gitkeep data/processed/.gitkeep reports/.gitkeep
# 3. Create notebook
uv run jupyter lab
# 4. As you work:
# - Keep logic in lib/ and scripts/
# - Save outputs to reports/ with dates
# - Keep outputs minimal
# - Strip outputs before committing
# 5. Before presenting:
# - Run "Restart & Run All" to test
# - Add context and documentation
# - Consider exporting to HTML
jupyter nbconvert --to html --execute notebook.ipynb速查表
目录组织：
- Notebook：项目根目录（或按规模拆到
notebooks/） - 脚本：
scripts/ - 模块：
lib/ - 数据：
data/raw/,data/processed/ - 报告：
reports/YYYY-MM-DD/ - 归档：
.archive/
uv 常用命令：
uv init：初始化项目uv add <package>：添加依赖uv run <command>：在项目环境中运行命令uvx <tool>：运行临时工具（不写入项目依赖）
省 token：
- 清理输出：pre-commit hook，或
jupyter nbconvert --ClearOutputPreprocessor.enabled=True --inplace notebook.ipynb - 查询结构：
jq '.cells | group_by(.cell_type)' - 对比代码：
jq '.cells[] | select(.cell_type == "code") |.source'
展示：
- 数字格式化：
{count:,} - 按日期落盘：
reports/YYYY-MM-DD/ - 执行验证：
jupyter nbconvert --execute