Notebook Builder

分段式创建和修改 Jupyter Notebook，支持图片嵌入与判题系统。

⚠️ 执行规则（必须遵守）

所有 Python 代码必须由 agent 自己通过 terminal 工具执行，严禁让用户手动在命令行执行。

原因：agent 通过工具执行命令时，stdout/stderr 会被自动捕获并返回，agent 可以依据输出判断操作是否成功。如果让用户手动执行，agent 无法感知执行结果，会导致工作流中断或状态不一致。

具体要求：

1. 每一段 Python 代码都必须通过 terminal 工具直接执行，不要输出代码让用户自己运行
2. 执行后必须检查 stdout 输出，确认操作成功（如看到 ✅ 前缀的确认信息）
3. 分段生成时，每段执行完毕后应通过 terminal 工具执行 nb_info() 或 get_cell_summary() 检查当前 notebook 状态，再继续下一段
4. 如遇执行错误，agent 应自行分析错误信息并修正代码后重试，无需用户介入

核心工作流程

用户请求
  │
  ├─ 创建新 notebook      → "创建流程"
  ├─ 修改现有 notebook    → "修改流程"
  ├─ 添加判题系统         → "判题流程"
  └─ 嵌入图片             → "图片流程"

❗ 关于 <技能脚本目录> 占位符

示例代码中的 <技能脚本目录> 需要替换为此技能实际的 scripts/ 目录绝对路径。agent 应通过以下方式确定该路径：

1. 此 SKILL.md 文件所在目录的同级 scripts/ 子目录
2. 即 SKILL.md 的父目录 + /scripts

例如如果此 SKILL.md 位于 /home/user/.codebuddy/skills/notebook-builder/SKILL.md，则 <技能脚本目录> 应替换为 /home/user/.codebuddy/skills/notebook-builder/scripts。

辅助脚本

此技能包含核心辅助脚本 scripts/nb_helpers.py，提供以下能力：

创建流程（分段生成）

分段生成的核心思路：不要试图一次性生成整个 notebook。将内容拆分为多个"段"，每段包含若干 cell，逐段追加。

步骤

1. 初始化：用 new_notebook() 创建空 notebook，根据用户需求设置 kernel
2. 规划章节：将内容大纲拆分为 3-5 段，每段对应一个逻辑章节
3. 逐段生成：
   • 使用 make_section() 或 make_markdown_cell() + make_code_cell() 构造当前段的 cell
   • 使用 append_cells() 追加到 notebook
   • 调用 save_notebook() 保存当前进度（支持中途预览）
4. 收尾：添加总结章节，最终保存

分段生成示例

重要：以下每一段代码都应由 agent 通过 terminal 工具分段执行，不要一次性全部执行，也不要让用户手动执行。

第 1 次执行（通过 terminal 工具）：初始化 + 标题段

import sys
sys.path.insert(0, "<技能脚本目录>")
from nb_helpers import *

nb = new_notebook(kernel_name="python3")
append_cells(nb, [
    make_markdown_cell("# 🔥 我的教程\n---\n**目标**：xxx"),
    make_code_cell("import torch\nprint(torch.__version__)"),
])
save_notebook(nb, "my_tutorial.ipynb")
print(nb_info(nb))  # 验证状态

第 2 次执行（通过 terminal 工具）：追加第一章

import sys
sys.path.insert(0, "<技能脚本目录>")
from nb_helpers import *

nb = load_notebook("my_tutorial.ipynb")
append_cells(nb, make_section(
    "1.1 基础概念",
    "这里是 Markdown 正文...",
    ["# 实验代码\nprint('hello')"],
))
save_notebook(nb, "my_tutorial.ipynb")
print(nb_info(nb))  # 验证状态

第 N 次执行（通过 terminal 工具）：追加考核 + 总结

import sys
sys.path.insert(0, "<技能脚本目录>")
from nb_helpers import *

nb = load_notebook("my_tutorial.ipynb")
quiz = make_quiz_code_cell("q1", "1+1=?", 2, score=10)
append_cells(nb, [make_divider_cell(), make_markdown_cell("## 📝 考核时间"), quiz])
save_notebook(nb, "my_tutorial.ipynb")
print(nb_info(nb))  # 验证状态

关键约束

• 所有代码必须由 agent 通过 terminal 工具执行，不要输出代码让用户手动运行
• 每次追加的 cell 数量建议不超过 10 个，避免单次操作过大
• 每次追加后都 save_notebook()，确保进度不丢失
• 每次执行后检查 stdout 输出，确认看到 ✅ 成功信息
• 使用 nb_info() 和 get_cell_summary() 检查当前状态
• 分段执行时，每次都需要重新 import 和 load_notebook()，因为每次 terminal 调用是独立的 Python 进程

修改流程

步骤

1. 加载：load_notebook(path) 加载现有 notebook
2. 定位：
   • get_cell_summary() 查看所有 cell 概览
   • find_cells_by_keyword() 按关键词搜索目标 cell
   • find_cells_by_id() 按 id 精确定位
3. 修改：
   • replace_cell() 替换整个 cell
   • insert_cells() 在指定位置插入新 cell
   • delete_cells() 删除不需要的 cell
4. 保存：save_notebook(nb, path)

修改示例

以下代码由 agent 通过 terminal 工具执行：

import sys
sys.path.insert(0, "<技能脚本目录>")
from nb_helpers import *

nb = load_notebook("existing.ipynb")

# 查看结构
for line in get_cell_summary(nb):
    print(line)

# 在第 5 个 cell 后插入新内容
insert_cells(nb, 5, [
    make_markdown_cell("### 补充说明\n新增的内容..."),
    make_code_cell("# 新的实验代码"),
])

# 替换第 3 个 cell
replace_cell(nb, 3, make_markdown_cell("## 更新后的标题"))

save_notebook(nb, "existing.ipynb")
print(nb_info(nb))  # 验证修改结果

图片流程

两种嵌入方式：

方式 1：嵌入到 Markdown cell（推荐）

# 基础用法
img_md = embed_image_in_markdown("diagram.png", alt_text="架构图")
cell = make_markdown_cell(f"## 系统架构\n\n{img_md}\n\n上图展示了...")

# 指定宽度
img_md = embed_image_in_markdown("photo.jpg", alt_text="示例", width=500)

方式 2：嵌入到 Code cell 输出

output = make_image_output("result.png")
cell = make_code_cell("# 运行结果如下", outputs=[output])

注意事项

• 图片会被 base64 编码嵌入，无需外部依赖
• 大图片会显著增大 .ipynb 文件体积，建议压缩后再嵌入
• 支持 PNG、JPG、GIF、SVG 格式

判题流程

判题系统通过 SHA256 哈希存储答案，学生无法看到明文。

生成判题 cell

# 单选/填空题
quiz1 = make_quiz_code_cell(
    question_id="q1",
    question_prompt="torch.randn(3,4,5) 的 stride 是什么？",
    answer=(20, 5, 1),      # 正确答案（不会以明文出现在 notebook 中）
    answer_type="tuple",
    hints=["stride[i] = 后面所有维度 size 的乘积"],
    score=10,
)

支持的答案类型

汇总评分

summary = make_quiz_summary_cell(
    question_ids=["q1", "q2", "q3"],
    total_score=30,
    scores={"q1": 10, "q2": 10, "q3": 10},  # 可选，未指定时平均分配
)
append_cells(nb, [summary])

判题原理

1. 答案经过标准化处理（去空格/小写/统一类型表示）
2. 加盐后 SHA256 哈希，截取前 16 位存储
3. 学生运行 cell 时，对其输入做同样处理并比对哈希
4. 哈希不可逆，学生无法从中推导答案

完整教程生成模板

当用户要求生成完整教学 notebook 时，推荐结构：

1. 标题 + 目标描述 (markdown)
2. 环境准备 (code: import + version check)
3. --- 分隔线 ---
4. 章节 1: 概念讲解 (markdown) + 实验代码 (code) × N
5. --- 分隔线 ---
6. 章节 2: ...
7. --- 分隔线 ---
8. 📝 考核时间 (markdown)
9. 题目 1 (quiz code cell)
10. 题目 2 (quiz code cell)
11. ...
12. 📊 汇总评分 (quiz summary code cell)
13. --- 分隔线 ---
14. 完成总结 (markdown)

常见问题

Q: 为什么代码必须由 agent 自己执行？

A: agent 只能通过工具调用的返回值感知执行结果。如果让用户在终端手动执行，即使输出了结果，agent 也无法检测到，会导致状态不一致。因此所有 Python 代码都必须通过 terminal 工具执行。

Q: 分段执行时变量会丢失吗？

A: 会。每次 terminal 工具调用是一个独立的 Python 进程，上次定义的变量不会保留。因此每次执行都需要重新 import 并用 load_notebook() 加载之前保存的 notebook。

Q: 分段生成时如何避免内容重复？

A: 每次追加前用 get_cell_summary() 检查当前状态，确认上一段已正确追加后再继续。

Q: 如何修改已有 notebook 中的某个 cell？

A: 用 find_cells_by_keyword() 定位目标 cell 的 index，然后用 replace_cell() 替换。

Q: 判题 cell 能否防止学生查看哈希？

A: 哈希值虽然可见，但不可逆。学生无法从 16 位哈希推导出原始答案。如需更高安全性，可将判题逻辑放到外部服务。

Q: 图片嵌入后文件太大怎么办？

A: 建议在嵌入前压缩图片（如 PNG → 降低分辨率、JPG → 降低质量），或只嵌入关键图片。

合并 Notebook

将多个 notebook 合并为一个，适合把分散的章节/讲义合并。

# 合并多个 notebook
merged = merge_notebooks(
    paths=["chapter1.ipynb", "chapter2.ipynb", "chapter3.ipynb"],
    output_path="full_course.ipynb",
    add_dividers=True,   # 在每个 notebook 之间添加分隔线
    add_titles=False,    # 不添加来源标注
)

导出为 Python 脚本

将 notebook 的 Code cell 导出为 .py 文件，Markdown cell 可选地转为注释。

nb = load_notebook("tutorial.ipynb")
export_to_script(
    nb,
    output_path="tutorial.py",
    include_markdown=True,  # Markdown cell 作为注释写入
)

自动生成目录

扫描 notebook 中所有 Markdown 标题，生成可点击跳转的目录 cell。

nb = load_notebook("long_tutorial.ipynb")
toc = make_toc_cell(nb, max_level=3, title="📑 目录")
insert_cells(nb, 0, [toc])  # 插入到 notebook 开头
save_notebook(nb, "long_tutorial.ipynb")

Cell 重排序

按指定索引顺序重排 cell，可用于调整结构。

nb = load_notebook("messy.ipynb")
for line in get_cell_summary(nb):
    print(line)
# 按新顺序重排
reorder_cells(nb, [0, 3, 1, 2, 4])
save_notebook(nb, "messy.ipynb")

Cell 标签系统

为 cell 打标签，然后按标签筛选。标签存储在 metadata.tags 中，JupyterLab 可直接识别。

# 打标签
cell = make_code_cell("x = 1")
tag_cell(cell, ["exercise", "easy"])

# 按标签查找
exercises = find_cells_by_tag(nb, "exercise")
for idx, cell in exercises:
    print(f"Cell {idx}: {cell['cell_type']}")