Skill Seeker 的 Jupyter Notebook 转 Skill 全解析:从 .ipynb 到 golden_jupyter_dir SKILL.md 的生成管线

原创2026-09-22 12:59:321,962 阅读
文章标签:人工智能AI 技能MCP 服务RAG网页爬虫开发工具后端前端数据工程

Skill Seeker 的 Jupyter Notebook 转 Skill 全解析:从 .ipynb 到 golden_jupyter_dir SKILL.md 的生成管线

Skill Seeker 提供了一条把 Jupyter Notebook(单个 .ipynb 文件或整个 notebooks 目录)自动转换为 Claude AI Skill 的完整管线,核心落地在 JupyterToSkillConverter。本文以仓库金标准产物 tests/golden/phase2/jupyter_dir/SKILL.md 为解剖对象,结合其同目录下的 references/ 参考文件、jupyter_scraper.py 源码与 test_phase2_golden_jupyter.py 测试,讲清 Notebook 内容的提取、分类、评分与 Skill 装配全过程,读完后你能掌握如何用 Skill Seeker 将 Jupyter 数据科学 Notebook 沉淀为可直接被 Claude 调用的结构化技能,并理解每个输出章节背后的生成逻辑。

一、目录源构建:为什么这份 SKILL.md 值得研究

tests/golden/phase2/jupyter_dir/SKILL.md 是 Skill Seeker 的 Phase 2 金标准(golden)产物之一,对应的构建场景是 notebook_path 指向一个目录(而非单个文件)。与同目录的 jupyter/SKILL.md(单文件分支)相比,目录源触发的是完全不同的分类与命名路径:

  • 参考文件使用通用的 section_*.md 命名(如 section_s2-s2.md),而不是以 notebook 文件名为 stem。
  • 多个 notebook 的 section 会被合并编号(section_number 全局递增,source_notebook 记录来源文件名)。
  • SKILL.md 中"Content Breakdown"展示的是主题分类结果(Data Loading / Evaluation / Setup / Other),而非单文件的 notebook 名。

该 golden 树由 test_phase2_golden_jupyter.py 中的 test_jupyter_directory_source_matches_golden 验证,测试注释明确指出:目录源下"reference-filename stem 保持为空(使用 section_*.md 命名,而非目录名)",这正是 jupyter_scraper.py 中 source_stem 属性(Path(path).stem if path and Path(path).is_file() else "")的行为。

二、从 .ipynb 到 Skill 的完整工作流

2.1 入口与命令用法

jupyter_scraper.py 的模块 docstring 给出了三种入口:

skill-seekers jupyter --notebook notebook.ipynb --name myskill
skill-seekers jupyter --notebook ./notebooks/ --name myskill
skill-seekers jupyter --from-json notebook_extracted.json

第三种方式 --from-json 允许复用已生成的 {name}_extracted.json 中间产物,跳过重复解析。

2.2 提取阶段(extract_notebook)

extract_notebook() 是整个管线的第一步,流程如下:

  1. 依赖校验:调用 _check_jupyter_deps(),若未安装 nbformat 则抛出 RuntimeError,提示 pip install "skill-seekers[jupyter]" 或 pip install nbformat。
  2. 收集 notebook:_collect_notebook_files() 支持单文件与目录两种输入;目录会递归 glob("**/*.ipynb"),并自动排除 .ipynb_checkpoints 目录。
  3. 逐个解析:_parse_single_notebook() 用 nbformat.read(f, as_version=4) 读取,遍历每个 cell:
    • markdown 单元格:按 # 标题边界切分为多个 section,同时抽取其中的代码围栏作为 code_samples(_parse_markdown_cell)。
    • code 单元格:保留源码、execution_count、output 文本(stream/execute_result/display_data)、错误输出(error,会剥除 ANSI 颜色码)、富输出 mime 类型(text/html、image/png、image/svg+xml)(_parse_code_cell)。
    • raw 单元格:作为纯文本 section 保留(_parse_raw_cell)。
  4. 语言检测:优先从 kernelspec.language/kernelspec.name 判断,回退到 language_info.name;Python、Julia、Scala、Rust、R、JavaScript、C# 等内核名均有映射规则(_detect_language)。未标注语言的代码块还会交给 LanguageDetector(min_confidence=0.15) 做二次检测。
  5. 依赖提取:_extract_imports() 按语言匹配 _IMPORT_PATTERNS(Python/R/Julia/JavaScript/Scala 各有独立正则)。
  6. 落盘中间产物:把 {source_file, metadata, total_sections, languages_detected, imports, pages} 写入 {name}_extracted.json。

2.3 分类阶段(categorize_content)

分类是决定 SKILL.md 结构的关键,categorize_content() 依次尝试三种分支:

  1. 单文件分支:notebook_path 是文件时,直接以 notebook 的 basename 作为唯一分类。
  2. 自定义关键词分支:配置中提供了 categories 时,对每个 section 的"文本 + 标题 + 代码"拼接串(_section_text())做关键词打分,归属得分最高的分类;无匹配的进 other。
  3. 主题自动分类:无 path 无 categories 时,用 _TOPIC_KEYWORDS(data_loading / data_cleaning / visualization / modeling / evaluation / feature_engineering / setup / analysis 共 8 类)打分,得分 >= 2 才归桶,否则落入 other。

金标准 jupyter_dir/SKILL.md 的"Content Breakdown"——Data Loading 1 节、Evaluation 1 节、Setup 1 节、Other 2 节——正是第三种自动分类在合成 fixture 上的结果:section 2 含 pd.read_csv/read_csv(data_loading),section 5 含 accuracy/recall/model(evaluation),section 1 含 pip/install/setup(setup),section 3 与 4 无足够关键词落入 other。

三、SKILL.md 输出结构的逐节拆解

下面逐节对照 tests/golden/phase2/jupyter_dir/SKILL.md 与生成源码,说明每个章节的来历。

3.1 YAML front-matter

---
name: golden-jupyter-dir
description: Use when testing the golden_jupyter_dir golden build
---

_generate_skill_md() 中 skill_name = self.name.lower().replace("_", "-").replace(" ", "-")[:64],description 优先取配置值(未配置时由 infer_description_from_notebook() 依据 language_info、kernelspec 或名称自动推断)。这段 front-matter 是 Claude 识别 Skill 触发条件的关键。

3.2 Notebook Information 与 When to Use

**Kernel:** Python 3
**Language:** python 3.11.4

来自 notebook 的 kernelspec.display_name 与 language_info.name + version(即测试中的 FULL_METADATA)。"When to Use" 五个要点(理解工作流、参考代码与输出、复现分析步骤、review 方法与结果、查找库用法模式)是模板固定生成的。

3.3 Section Overview 与 Key Concepts

Section Overview 的"Total Sections: 5"来自 total_sections,Content Breakdown 按分类输出各分类的 section 数。

Key Concepts 由 _format_key_concepts() 生成:遍历所有 markdown section 的 heading 与 headings(h1 为 Major Topics,h2 为 Subtopics)。本例中 h1 "Getting Started" 成为 Major Topic,h2 "Modeling Results" 成为 Subtopics。

3.4 Dependencies 与 Quick Reference

Dependencies 列出 _extract_imports() 汇总并去重排序的包(numpy、pandas、sklearn),最多展示 20 个。Quick Reference 由 DocumentSkillBuilder 的 _format_patterns_from_content() 基于 PATTERN_KEYWORDS(jupyter 在文档关键词基础上追加了 data loading、preprocessing、modeling、evaluation、results、conclusion、summary)输出常见文档模式。

3.5 Code Examples:质量评分驱动

### Bash Examples (1)
**Example 1** (Quality: 5.0/10):
pip install pandas

这是最能体现工程细节的章节:所有 code sample 按 quality_score 降序取前 15 条,再按语言分组,每种语言最多展示 5 条,超过 500 字符截断加 ...。评分函数 score_code_quality(code, notebook_mode=True) 在 scraper_utils.py 中定义,规则包括:

  • 基线 5.0 分;行数 ≥10 加 2.0,≥5 加 1.0;
  • 含 def/class/function 定义加 1.5,含 import 加 0.5,含缩进加 0.5,含运算符/括号加 0.3;
  • notebook 模式额外奖励 docstring(+0.3)与 % magic 行(+0.2),纯 magic/shell 行则扣 1.0;
  • 代码短于 30 字符扣 2.0;最终夹在 0.0–10.0。

因此本例中:60 行函数定义样例得 9.5 分(long_example),pd.read_csv 三行代码得 7.5 分,pip install pandas 得 5.0 分,而 %timeit broken() 因过短且纯 magic 只得 2.0 分——评分差异精确映射到测试 fixture 的预期值。

3.6 Notebook Statistics

统计块直接来自提取阶段计数:Total Sections 5、Code Cells 2、Markdown Cells 2、Raw Cells 1、Notebooks 1、Programming Languages 2(python 3 个代码块、bash 1 个)。注意"Code Cells 2"与"python: 3 code cells"的差异——前者统计的是 notebook 原生 code cell 数,后者包含 markdown 代码围栏中检测出的 python 代码块,这正是 jupyter 场景特有的统计口径。

3.7 Navigation 与 references 目录

- `references/section_s2-s2.md` - Data Loading
- `references/section_s5-s5.md` - Evaluation
- `references/section_s1-s1.md` - Setup
- `references/section_s3-s4.md` - Other

导航链接并非手工维护:_reference_filename()(scraper_utils.py)与 _generate_index() 共用同一命名函数,保证 SKILL.md 里的链接、references/index.md 与真实文件名三者永不漂移(源码注释中的 DOC-07 约束)。命名规则为 {stem}_{prefix}{min}-{prefix}{max}.md,即按分类内 section 号区间命名:section_s1-s1.md(Setup,单节)、section_s3-s4.md(Other,覆盖 3–4 两节)。

四、references 参考文件的内部结构

references/index.md 是整棵参考树的目录页,包含分类列表(含 section 区间)、统计(kernel、语言版本)与依赖包清单(最多 30 个)。四个 section 文件则由 _write_reference_section() 生成,忠实还原 notebook 单元格的细节:

  • section_s1-s1.md:markdown 单元格,含 #### Verify Setup 子标题、bash 代码围栏和 *Tags: intro, setup*。
  • section_s2-s2.md:代码单元格,标题为自动推断的 #### Assign: df(_infer_code_heading() 从首行赋值语句推断),保留 **In [2]:** 执行计数、Output 文本与 *Rich output: text/html* 富输出标记。
  • section_s3-s4.md:依次是出错的代码单元格(%timeit broken(),含 **Errors:** 的 NameError 与 traceback、raises-exception 标签)和 raw 单元格(原样保留文本)。
  • section_s5-s5.md:markdown 单元格,含 60 行函数定义的长代码示例、Metric/Value 带表头表格和无表头的 a b / c d 表格(验证两种表格渲染路径)。

_infer_code_heading() 的推断优先级值得注意:注释行(# 标题)→ def/class/async def("Define: xxx")→ 赋值("Assign: xxx")→ magic("Magic: %xxx")→ shell("Shell: xxx")→ 兜底的 "Code Cell [N]"。

五、金标准测试如何锁定输出

test_phase2_golden_jupyter.py 是这份 SKILL.md 的"契约测试":_extracted_data() 构造了覆盖全部构建路径的 fixture(markdown/code/raw 单元格、有/无执行计数、输出文本/错误/富显示、单元格标签、有/无表头表格、子标题、超 500 字符代码、imports、kernelspec/language_info 元数据、语言统计),然后用 build_snapshot() 生成快照并与 golden 目录做字节级比对。四个测试分别验证:

  • test_jupyter_single_notebook_matches_golden:单文件 → 单分类(notebook stem)分支;
  • test_jupyter_keyword_categorization_matches_golden:自定义 categories 关键词打分,含空分类(回退到 section_NN.md 与 N/A 区间)与 other 桶;
  • test_jupyter_topic_autocategorization_matches_golden:无 path 无 categories 的 _TOPIC_KEYWORDS 自动分桶;
  • test_jupyter_directory_source_matches_golden:目录源 → section_*.md 命名分支(即本文主角)。

这套测试保证从旧实现到 DocumentSkillBuilder 的 Phase 2 移植过程中,产物逐字节不变——你可以通过 tests/golden/phase2/jupyter_dir/ 目录直接观察 SKILL.md 与 references 的最终形态,把本节描述的每个章节与文件一一对上。

六、结语:把 Notebook 变成可检索、可复现的 AI 技能资产

通过对 tests/golden/phase2/jupyter_dir/SKILL.md 的逐节解剖可以看到,Skill Seeker 的 Jupyter 转换并非简单的"文本拼接",而是一条工程化管线:nbformat 解析 → 单元格级切分与语言检测 → 关键词打分分类 → 代码质量评分 → 统一装配 SKILL.md + references 参考树,并有金标准测试锁死输出契约。对于任何想把数据分析 Notebook 沉淀为 Agent 可调用资产的团队,这套"SKILL.md 索引 + references 分节参考 + 导航自动对齐"的结构,本身就是一份可直接借鉴的实践模板。

登录后查看全文
Skill_Seekers