Skill_Seekers Jupyter Notebook 转 Skill 实战:从 .ipynb 到结构化 Claude Skill 的完整管线解析

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

Skill_Seekers Jupyter Notebook 转 Skill 实战:从 .ipynb 到结构化 Claude Skill 的完整管线解析

Jupyter Notebook(.ipynb)是数据科学工作流中最常见的知识载体,而 Claude 等 Agent 无法直接"运行"或"翻阅"笔记本。Skill_Seekers 通过其 Jupyter Notebook Scraper,把 .ipynb 的 markdown 叙述、代码单元、执行输出、内核元数据与单元格标签自动整理成一份结构化的 SKILL.md 技能清单,让 Agent 可以像查手册一样"理解并复现"一次数据分析过程。本文以仓库中 golden 测试输出的真实产物 tests/golden/phase2/jupyter/SKILL.md 为解剖对象,逐段还原它背后的生成逻辑,并深入到 jupyter_scraper.py 源码层,说明单元格解析、语言检测、代码质量评分与三类分类策略的实现原理,读完你既能读懂这类 SKILL.md,也能掌握如何为自己的笔记本生成同规格技能。

一、产物全貌:一份 Jupyter Notebook Skill 长什么样

golden 测试输出 SKILL.md 是典型的"Notebook 型技能"产物,它和网页型、PDF 型技能的最大区别在于:它的主体不是平铺的章节,而是围绕"单元格"组织的信息摘要。整体骨架如下:

---
name: golden-jupyter
description: Use when testing the golden_jupyter golden build
---

# Golden_Jupyter Notebook Skill

## 📋 Notebook Information      → 内核与语言版本(来自 kernelspec / language_info)
## 💡 When to Use This Skill     → 适用场景清单(固定模板)
## 📖 Section Overview           → 总章节数与分类分布
## 🔑 Key Concepts               → 从标题层级提取的主/子主题
## 📦 Dependencies               → 自动提取的导入包清单
## ⚡ Quick Reference            → 基于关键词的常见文档模式索引
## 📝 Code Examples              → 按质量分排序的精选代码单元
## 📊 Notebook Statistics        → 单元格/语言统计
## 🗺️ Navigation                 → 指向 references/*.md 的导航

这个骨架由 _generate_skill_md() 方法逐段写入(见 jupyter_scraper.py)。注意 front matter 中的 name 会被强制规范化为小写、下划线转连字符的格式(self.name.lower().replace("_", "-")...),description 截断到 1024 字符,这正是为了满足 Claude Skill 对元信息的解析要求。

1.1 数据源:提取阶段的产物

SKILL.md 不是直接读取 .ipynb 生成的,而是建立在中间提取结果之上。extract_notebook()(jupyter_scraper.py)会把每个笔记本解析成结构化 JSON(保存为 {name}_extracted.json),其中包含:

  • total_sections / total_code_blocks / total_markdown_cells / total_raw_cells / total_notebooks
  • languages_detected(每种语言命中的代码单元数)
  • imports(去重排序后的导入包列表)
  • pages(按单元格拆分后的 section 列表)

SKILL.md 里的 📊 Notebook Statistics、📦 Dependencies、Language Breakdown 三段,都是对这个 JSON 中统计字段的直接渲染。golden 产物中的"Total Sections: 5、Code Cells: 2、Markdown Cells: 2、Raw Cells: 1"就是最直观的证据。

二、Notebook Information:内核与语言版本从哪来

SKILL.md 头部输出的:

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

分别来自笔记本顶层 metadata 的 kernelspec.display_name 与 language_info.name + version(_generate_skill_md() 中 ks = meta.get("kernelspec", {})、li = meta.get("language_info", {}))。只有这两个字段存在时,📋 Notebook Information 小节才会被写出——所以 jupyter_kw 变体(空 metadata)的 SKILL.md 中看不到这一节,这是字段缺失时的条件渲染行为。

与之配套的 _detect_language()(jupyter_scraper.py)则定义了语言识别优先级:先看 kernelspec.language,再看 kernelspec.name 中的关键字(python/julia/scala/rust/ir/r/javascript/node/csharp/dotnet),最后回退到 language_info.name。这意味着即便笔记本使用了 IRkernel(R)或 Julia 内核,也能被正确标记进 languages_detected 统计。

三、单元格解析:三种 cell_type 的差异化处理

Notebook 的原始单元格只有 markdown / code / raw 三类,Scraper 对它们采用完全不同的解析策略(_parse_single_notebook(),jupyter_scraper.py)。

3.1 Markdown 单元格:按标题边界切分

markdown 单元格内部往往包含多个 # 标题,_parse_markdown_cell()(jupyter_scraper.py)会按 ^(#{1,6})\s+(.+) 正则把单元格切成多个 section,每个 section 记录 heading、heading_level(h1~h6)、正文文本、三级以上子标题、以及从正文 ``` 代码围栏中提取的 code_samples。

golden 的 Section 1 就是典型例子——markdown 单元格 "Getting Started / Verify Setup" 中的 pip install pandas 围栏被单独抽成 bash 代码样本,并打上 intro, setup 标签:

**📄 Source: Section 1**

## Getting Started

#### Verify Setup

Welcome to the analysis notebook. Installation and setup steps.

```bash
pip install pandas

Tags: intro, setup


### 3.2 Code 单元格:源码 + 输出 + 错误三通道

code 单元格是 Notebook Skill 信息密度最高的部分,`_parse_code_cell()`(<a href="https://link.gitcode.com/i/5407fc6251981c2c6892c034541941af" target="_blank">jupyter_scraper.py</a>)同时提取:

- **源码**:作为 `code_samples` 写入,并记录 `execution_count`;
- **输出**:`stream`(stdout)、`execute_result`、`display_data` 的 `text/plain` 文本汇入 `output_text`;
- **错误**:stderr 流与 `error` 类型输出的 `ename: evalue` 加上 traceback(会先剥离 ANSI 颜色转义序列 `\x1b\[[0-9;]*m`)汇入 `output_errors`;
- **富输出**:`text/html`、`image/png`、`image/svg+xml` 等 MIME 只记录"存在"标记,不落盘图片二进制。

golden 中 Section 2 与 Section 3 是两种极端情况的对照:

```markdown
**📄 Source: Section 2** (Code Cell [In 2])

#### Assign: df

**In [2]:**
```python
import pandas as pd
df = pd.read_csv('data.csv')
df.head()

Output:

   col1  col2
0     1     3

Rich output: text/html


```markdown
**📄 Source: Section 3** (Code Cell)

#### Magic: %timeit

```python
%timeit broken()

Errors:

NameError: name 'broken' is not defined
Traceback line 1

Tags: raises-exception


前者展示了带执行序号(In [2])、成功输出和 HTML 富输出的正常单元;后者展示了无执行计数、只产生异常的单元——两种形态被原样保留进技能参考,供 Agent 同时学习"正确用法"与"反例"。

### 3.3 Raw 单元格:原样文本

raw 单元格不做任何解析,只把 `source` 作为纯文本写入(`_parse_raw_cell()`,<a href="https://link.gitcode.com/i/ff8d9e46bc5c30fdebcc2ded697abc98" target="_blank">jupyter_scraper.py</a>)。golden 的 Section 4("raw front-matter content")即此路径。

### 3.4 代码单元标题的自动推断

没有标题的 code 单元格会被 `_infer_code_heading()`(<a href="https://link.gitcode.com/i/b617092f3e01d3a48b3f99a72985b6a1" target="_blank">jupyter_scraper.py</a>)自动命名,规则依次是:首行 `# 注释` → `Define: 函数名`(def/class/async def)→ `Assign: 变量名` → `Magic: %magic` → `Shell: 命令` → 兜底 `Code Cell [n]`。golden 中出现的 "Assign: df" 和 "Magic: %timeit" 正是这条链路的直接产物,这让参考文件里每个单元都有可读的锚点标题。

## 四、依赖提取与语言识别:面向多内核的导入解析

`📦 Dependencies` 小节的 `numpy / pandas / sklearn` 来自 `_extract_imports()`(<a href="https://link.gitcode.com/i/35545855aa746217965dc03e0cea3da5" target="_blank">jupyter_scraper.py</a>)与模块级 `_IMPORT_PATTERNS` 表。该表按语言预置了正则模板:

| 语言 | 匹配模式示例 |
| --- | --- |
| python | `^\s*import\s+([\w.]+)`、`^\s*from\s+([\w.]+)\s+import` |
| r | `^\s*library\(([\w.]+)\)`、`^\s*require\(([\w.]+)\)` |
| julia | `^\s*using\s+([\w.]+)`、`^\s*import\s+([\w.]+)` |
| javascript | `require('...')`、`import ... from '...'` |
| scala | `^\s*import\s+([\w.]+)` |

另外,对未标注语言的代码样本,提取阶段会调用 `LanguageDetector(min_confidence=0.15)` 做代码级语言探测,置信度 ≥ 0.3 才采纳(<a href="https://link.gitcode.com/i/a2a587d0e124beab596ac792e366ce3e" target="_blank">jupyter_scraper.py</a>)。golden 产物中 `python: 3 code cells / bash: 1 code cells` 的 Language Breakdown,就是"内核语言 + 探测语言"合并统计后的结果。

## 五、代码质量评分与精选展示

`📝 Code Examples` 是 Notebook Skill 的核心价值区。提取阶段每个代码样本都会通过 `score_code_quality(code, notebook_mode=True)` 打 0~10 分(来自 <a href="https://link.gitcode.com/i/4d5d3ca1bfc43e8d02d0e4a674bcc2b1" target="_blank">scraper_utils.py</a>),SKILL.md 生成时按分数降序取 Top 15,再按语言分组、每组最多展示 5 个、单个代码截断到 500 字符(<a href="https://link.gitcode.com/i/16011493845ced3d618a2247eded8406" target="_blank">jupyter_scraper.py</a>)。

golden 中三例正好呈现评分梯度:

```markdown
**Example 1** (Quality: 9.5/10):    # 长函数示例(>500字符被截断显示 ...)
**In [2]** (Quality: 7.5/10):       # pd.read_csv + df.head(),带执行序号
**Example 3** (Quality: 2.0/10):    # %timeit broken()(会抛异常的单元分数最低)

注意展示顺序同时受语言名排序影响:bash 在 python 之前。执行序号存在时(如 In [2])用作标签,否则回退为 Example N,这与参考文件 references/analysis.md 中 **In [2]:** 的写法一致。

六、三套分类策略:章节如何归入 Content Breakdown

📖 Section Overview 里"analysis: 5 sections"的分类结果,由 categorize_content()(jupyter_scraper.py)产生,它按优先级走三条分支,仓库用三组 golden 变体分别锁定行为:

6.1 单文件分支(golden jupyter)

当 notebook_path 指向单个 .ipynb 文件时,直接以笔记本文件名作为唯一分类,所有 section 归入其中。这是默认路径,也是本文剖析的主产物。

6.2 关键词分类分支(golden jupyter_kw)

当配置了 categories 时,每个 section 拼接"文本 + 标题 + 代码"得到小写字符串,统计各分类关键词命中数,得分最高的分类胜出;无命中则落入 other。test_jupyter_keyword_categorization_matches_golden 还刻意构造了空分类(empty_cat),产物中表现为 **Empty Cat**: 0 sections 与占位参考文件 section_04.md。

6.3 主题自动分类分支(golden jupyter_topics)

无路径、无 categories 时,使用模块级 _TOPIC_KEYWORDS 表做自动分桶。该表覆盖 data_loading、data_cleaning、visualization、modeling、evaluation、feature_engineering、setup、analysis 八类主题,得分 ≥ 2 才入桶,否则归 other。jupyter_topics 产物中"Data Loading / Evaluation / Setup / Other: 2"的分类正是这条规则对同一份 5-section 数据的另一种切分结果,直观展示了同一笔记本在不同策略下的不同组织方式。

6.4 目录源(golden jupyter_dir)

notebook_path 为目录时,_collect_notebook_files()(jupyter_scraper.py)递归收集所有 .ipynb(排除 .ipynb_checkpoints),多个笔记本的 section 会按 section_number 连续编号并记录 source_notebook 归属;此时参考文件采用通用的 section_*.md 命名而非单文件分支的笔记本名。

七、参考文件体系:SKILL.md 背后的完整结构

SKILL.md 的 🗺️ Navigation 不是虚构链接,它指向真实生成的参考文件。导航文件名与 references/index.md 都由同一个 _reference_filename() 辅助函数派生,保证"链接永不出错"(源码注释中记为 DOC-07 修复点)。

7.1 单文件产物的参考布局

golden jupyter 树的完整结构为:

tests/golden/phase2/jupyter/
├── SKILL.md              # 技能入口(本文主对象)
└── references/
    ├── analysis.md       # 5 个 section 的完整正文
    └── index.md          # 分类索引 + 统计 + 导入包清单

references/analysis.md 中每个 section 以 **📄 Source: Section N** 分隔符开头,code 单元额外标注 (Code Cell <a href="https://link.gitcode.com/i/e7fea804242b16ad5abe1c48eef9c13f" target="_blank">In 2]),raw 单元标注 (Raw Cell),并完整保留 **Output:**、**Errors:**、*Rich output: ...*、*Tags: ...* 与 markdown 表格——这正是 _write_reference_section()([jupyter_scraper.py)的渲染结果。Section 5 中的 Metric/Value 表(accuracy 0.95、recall 0.91)与无表头表格,分别验证了带/不带 headers 的两条表格渲染路径。

7.2 index.md:分类与统计的总览

references/index.md 由 _generate_index()(jupyter_scraper.py)生成,包含分类链接(带 section 范围,如 Sections 1-5)、内核/语言版本,以及最多 30 个导入包的清单。它与 SKILL.md 的 Statistics 段互补:前者服务人类阅读导航,后者服务 Agent 快速判断适用性。

八、Key Concepts 与 Quick Reference:标题与模式的提炼

  • 🔑 Key Concepts 由 _format_key_concepts()(jupyter_scraper.py)从 markdown 单元格的 h1/h2 标题中提取(要求长度 > 3),h1 归入 Major Topics、h2 归入 Subtopics。golden 中 "Getting Started"(Major)与 "Modeling Results"(Subtopics)正是 notebook 的两个标题层级。
  • ⚡ Quick Reference 由 DocumentSkillBuilder 继承的 _format_patterns_from_content() 生成,JupyterToSkillConverter 通过 PATTERN_KEYWORDS 在共享文档关键词之上追加了 data loading / preprocessing / modeling / evaluation / results / conclusion / summary(jupyter_scraper.py),使 Notebook 特有的分析流程词也能被索引。

九、质量保障:Golden 测试如何锁定输出格式

整个 SKILL.md 结构并非人工撰写,而是由字节级一致的 golden 测试保证。tests/test_phase2_golden_jupyter.py 中的四个用例(单文件、关键词分类、主题自动分类、目录源)分别构造 extracted_data 与 metadata,调用 build_snapshot(converter) 后与 tests/golden/phase2/jupyter*/ 下的快照逐一比对(assert_matches_golden)。测试文件头部的注释明确说明:这些 golden 树是在 DocumentSkillBuilder 重构之前捕获的,因此任何一次重构都必须保持输出逐字节不变。这意味着本文剖析的所有段落顺序、字段命名、评分格式,都是被测试锁定的稳定契约。

十、如何实际使用:CLI 入口与前置依赖

Jupyter 转换功能通过 CLI 暴露,入口用法(见 jupyter_scraper.py 模块 docstring):

# 转换单个笔记本
skill-seekers jupyter --notebook notebook.ipynb --name myskill

# 转换目录下的所有 .ipynb
skill-seekers jupyter --notebook ./notebooks/ --name myskill

# 从已提取的 JSON 直接构建技能
skill-seekers jupyter --from-json notebook_extracted.json

前置依赖:该模块对 nbformat 做可选导入保护(jupyter_scraper.py),未安装时 extract_notebook() 会抛出提示信息明确的要求,需先执行 pip install "skill-seekers<a href="https://link.gitcode.com/i/11566eb47f1db740457623d28f421d5e" target="_blank">jupyter]" 或 pip install nbformat(_check_jupyter_deps(),[jupyter_scraper.py)。支持范围覆盖 Python、R、Julia、JavaScript、Scala 等内核语言。

结语

一份看似简单的 SKILL.md,背后是一条"提取 → 分类 → 渲染 → 校验"的完整管线:nbformat 解析单元格、正则按语言提取导入、质量评分排序精选代码、三套分类策略组织章节、golden 测试锁定格式契约。理解了 tests/golden/phase2/jupyter/SKILL.md 的每一段,就等于理解了 Skill_Seekers Jupyter Notebook Scraper 的全部设计取舍——当你需要把团队的数据分析笔记本沉淀为 Agent 可消费的技能资产时,这套模式可以直接复用:源码在 jupyter_scraper.py,行为契约在 test_phase2_golden_jupyter.py,产物样本在 tests/golden/phase2/jupyter/。

登录后查看全文
Skill_Seekers