企业官网建设流程全解析

• 人工智能
• AI 应用
• AI 技能
• RAG
• MCP 服务
• 网页爬虫

本文以 Skill Seekers 仓库中一份真实的 golden 测试产物 ——tests/golden/phase2/epub_kw/references/section_s1-s1.md为切入点，逐层拆解 EPUB 电子书转换为 Claude Skill 时生成的参考章节（references）到底长什么样、由哪条源码管线产出，以及关键词分类、代码质量评分、表格渲染等机制如何起作用。读完本文，你将掌握 Skill Seekers EPUB 抓取与文档技能构建管线的输出规范，并能据此校验、复现和扩展自己的 EPUB 转技能流程。

1. 先读一遍：一份 reference 章节的完整结构

被指定的关联文档位于 tests/golden/phase2/epub_kw/references/section_s1-s1.md，全文如下（golden 产物，为便于讲解在此完整陈列）：

# Setup --- **📄 Source: Section 1** ## Getting Started Guide ### Installation Steps #### Verify Setup Welcome to the project. This section explains setup. ### Code Examples ```python print('hello')

pip install thing

Tables

Images

它由六类固定组成部分构成，这正是 Skill Seekers 文档型抓取器（DocumentSkillBuilder 家族）统一的参考章节输出格式： | 组成部分 | 说明 | | --- | --- | | `# 标题` + `---` | 章节名（此处为 `Setup`），来自分类器给该节分配的分类名 | | `**📄 Source: Section N**` | 来源标注，指明该章节在原文档中属于第 N 节（EPUB 场景即 spine 阅读顺序中的第 N 个切片） | | `## / ### / ####` 层级标题 | 保留原始文档的标题层级：H1 切分为主章节，H3/H4/H5/H6 作为章节内子标题（sub-headings）被单独记录 | | 正文段落 | 以纯文本形式输出，多个段落用空行连接 | | ```python / ```bash 代码块 | 从 `<pre>`/`<code>` 元素抽取并保留语言标记 | | Markdown 表格 | 由 HTML `<table>` 结构转换而来 | | `Image 0` | 图片占位引用，指向输出目录下的 `assets/` 文件夹 | 注意文件名 `section_s1-s1.md` 的语义：`s1-s1` 表示该文件聚合了"第 1 节到第 1 节"的内容（即单节文件）；多节内容被归类到同一分类时，会生成 `section_s{a}-s{b}.md` 的区间命名。整个 golden 目录树（`epub_kw`）的布局可在 [tests/golden/phase2/epub_kw/references/index.md](https://link.gitcode.com/i/4536497c6f1381ea3086253940b623ba) 中看到：`Setup (1 sections, Sections 1-1)` 正是这个命名规则的落地体现。 ## 2. 这份文件从哪来：EPUB 抽取与章节切分管线 `section_s1-s1.md` 不是手写的，而是由 [src/skill_seekers/cli/epub_scraper.py](https://link.gitcode.com/i/3a369b3b228b46d4c4afc03132b6df7f) 中的 `EpubToSkillConverter`（继承自 `DocumentSkillBuilder`）在构建阶段自动生成的。其 `extract_epub()` 的完整工作流（源码第 115-234 行）如下： 1. **依赖检查**：通过 `_check_epub_deps()` 确认已安装 `ebooklib`，否则抛出 `RuntimeError` 并提示 `pip install "skill-seekers[epub]"`。 2. **输入校验**：检查路径存在、是文件、且以 `.epub` 结尾（源码第 142-149 行）。 3. **读取与 DRM 检测**：以 `epub.read_epub(path, options={"ignore_ncx": True})` 读取（该选项用于规避 EPUB 3 TOC 的一个已知解析问题）；随后调用 `_detect_drm()` 快速失败 —— 该方法扫描 `META-INF/encryption.xml`，将 Adobe ADEPT（`http://ns.adobe.com/adept`）、Apple FairPlay（`http://itunes.apple.com/dataenc`）、Readium LCP（`http://readium.org/2014/01/lcp`）识别为 DRM，而把 IDPF/Adobe 的字体内嵌混淆算法（font obfuscation）明确排除在 DRM 之外（源码第 236-287 行）。 4. **元数据抽取**：`_extract_metadata()` 读取 Dublin Core 字段（title、creator、language、publisher、date、description、subject、rights、identifier），对应 `SKILL_MD_METADATA_FIELDS` 中 `Title / Author / Language / Publisher / Date` 的映射（源码第 83-89、289-317 行）。 5. **正文抽取与章节切分**：`_extract_spine_content()` 按 EPUB spine（阅读顺序）遍历 `ITEM_DOCUMENT`，用 BeautifulSoup 解析 XHTML，先剥离 `<script>`、`<style>` 与注释，再以 `h1`/`h2` 作为边界把正文切成多个 section —— 每遇到一个新 H1/H2 就"冲刷"上一节（源码第 319-394 行）。这就是 `section_s1`、`section_s2`、`section_s3` 三个参考文件产生的直接原因。 6. **语言检测与中间 JSON**：对代码块做语言探测并统计，最后将 `pages / metadata / total_sections / total_code_blocks / total_images / languages_detected` 写入 `{name}_extracted.json`，作为构建 SKILL.md 的输入（源码第 212-228 行）。 测试端在 [tests/test_phase2_golden_epub_word.py](https://link.gitcode.com/i/b971166ab4cd3939ee6e9787d91cae28) 中用一个 `SECTIONS` 常量模拟了同样的抽取结果：3 个章节分别对应 `Getting Started Guide`、`API Usage`、`Troubleshooting`，其中第一节的 `headings` 列表里正是 `Installation Steps`（h2）与 `Verify Setup`（h3）—— 与参考文件中 `### Installation Steps`、`#### Verify Setup` 的层级一一对应（该测试第 17-61 行）。 ## 3. 关键词分类：epub_kw 与 categories 配置 本 golden 目录名为 `epub_kw`（keyword 的缩写），对应测试函数 `test_epub_keyword_categorization_matches_golden`（测试第 98-114 行）：构造 `EpubToSkillConverter` 时**不提供 `epub_path`**，而是提供 `categories` 配置： ```python converter = EpubToSkillConverter( { "name": "golden_epub_kw", "description": "Use when testing keyword categorization", "output_dir": str(tmp_path / "skill"), "categories": { "setup": ["setup", "installation"], "api": ["endpoints"], }, } )

这段配置说明了分类规则：当某个 section 的标题/正文命中关键词（如setup、installation）时，该节被归入setup分类；命中endpoints则归入api。EpubToSkillConverter.__init__中self.categories = config.get("categories", {})（源码第 106 行）正是读取这个字段的地方。

分类结果直接体现在三处产物上：

• 参考文件命名：section_s1-s1.md（Setup）、section_s2-s2.md（Api）、section_s3-s3.md（Other）。未被任何关键词命中的章节被归入兜底分类Other。
• index.md 的 Categories 列表：tests/golden/phase2/epub_kw/references/index.md 按分类列出各参考文件及其节区间，并汇总Total sections: 3、Code blocks: 3、Images: 1三类统计。
• SKILL.md 的 Section Overview：tests/golden/phase2/epub_kw/SKILL.md 中Total Sections: 3，Content Breakdown显示Setup: 1 sections / Api: 1 sections / Other: 1 sections。

这说明 "keyword categorization" 是 Skill Seekers 在多源/无文件输入场景下的标准路径：没有 EPUB 文件可解析时，抽取数据直接由外部提供（测试里用converter.extracted_data = _extracted_data({})注入），构建端照常完成分类、参考文件与 SKILL.md 的生成。

4. 代码示例抽取：语言识别与质量评分

参考文件里两个代码块（print('hello')与pip install thing）在 SKILL.md 的## 📝 Code Examples一节被聚合展示，并附上了质量分数：

其抽取逻辑位于_build_section()（源码第 433-492 行）：

• 代码块识别：命中<pre>或独立的<code>元素；若<pre>内嵌套<code>则取内层文本。
• 语言标记：优先从元素的class属性读取language-{lang}、lang-{lang}或code-{lang}前缀；无标记时留空，后续交给LanguageDetector(min_confidence=0.15)做代码内容探测，置信度 ≥ 0.3 才采纳（源码第 189-210 行）。
• 质量评分：调用score_code_quality（自 src/skill_seekers/cli/scraper_utils.py 导入）计算quality_score，用于 SKILL.md 中的质量排序与筛选。

需要特别说明 golden 与实盘的差异：epub_kw树是 golden 快照，其分数由测试 fixture 直接写入（见测试第 28-29、43 行），用于锁定历史输出；而真实运行时分数由score_code_quality动态计算。两者在构建端（DocumentSkillBuilder）走的是同一条渲染路径，这正是该 golden 树存在的原因 —— 证明"重构后的构建端输出与重构前逐字节一致"。

SKILL.md中示例按语言分组、组内按质量降序排列（bash 组 1 例、python 组 2 例且 9.5 分在前），对应测试模块 docstring 中 "multi-language code samples (incl. >500 chars + quality ordering)" 的覆盖点 —— 测试里LONG_CODE用 60 行代码验证了超长代码样本的处理（测试第 15 行）。

5. 表格与图片：两种渲染路径

表格：_build_section()对<table>调用extract_table_from_html转为结构化数据（源码第 494-499 行）。golden 树覆盖了两种表格形态：

• 有表头表格（第 1 节）：Option / Default两列，即参考文件中的debug=false、port=8080配置表；
• 无表头表格（第 2 节）：见 tests/golden/phase2/epub_kw/references/section_s2-s2.md 中的a b / c d两行两列 —— 测试注释明确说明 "Table without headers exercises the headerless rendering path"（测试第 46 行）。

两者最终在 SKILL.md 的## 📊 Table Summary中被汇总（2 table(s) found in document）。

图片：_build_section()对<img>记录index / src / width / height（源码第 501-513 行），而_extract_images()按 EPUB manifest 统计ITEM_IMAGE及补充统计image/svg+xml（源码第 396-425 行），最终反映为total_images统计与assets/目录输出。参考文件中的[![Image 0](https://raw.gitcode.com/gh_mirrors/sk/Skill_Seekers/raw/c413bc304d6fb98bea3185b57741a9d9dd90d07b/tests/golden/phase2/epub_kw/assets/section_1_img_0.png?utm_source=gitcode_repo_files)](https://link.gitcode.com/i/516ed63613e4a6033582145223d73464)就是这种"正文占位 + assets 落盘"协作的结果。注意 golden 树的图片为合成占位数据（测试第 34 行b"\x89PNG-fake-bytes"），仅用于验证管线完整性。

6. SKILL.md：聚合、统计与导航

参考文件是"单节视图"，而 tests/golden/phase2/epub_kw/SKILL.md 是整本文档的"聚合视图"，两者由构建端联动生成。SKILL.md 包含的区块与对应数据源如下：

其中Navigation一节给出的references/section_s1-s1.md - Setup等映射，正是读者（无论是人类还是 Agent）在 Skill 中继续深入查阅原文的索引 —— 这也解释了为什么参考文件必须保持"可独立阅读"的完整格式。

7. golden fixture 的验证价值：逐字节回归

epub_kw（连同epub、word）目录下的产物不是演示数据，而是回归测试的基准（golden）。依据 tests/test_phase2_golden_epub_word.py 的模块 docstring：

The golden trees under tests/golden/phase2/{epub,word}/ were captured from the PRE-DocumentSkillBuilder code; these tests prove the port is byte-identical.

即：这些树是从"重构前的 DocumentSkillBuilder 代码"捕获的快照，用于证明重构后（Phase 2 port）输出逐字节一致。测试通过assert_matches_golden(build_snapshot(converter), "epub_kw")将实时构建结果与tests/golden/phase2/epub_kw/下的文件对比，覆盖了元数据、标题层级、多语言代码示例（含超 500 字符样本与质量排序）、有无表头表格、图片、关键词分类和语言统计等全部构建路径（测试第 1-9 行）。

对二次开发者而言，这套 fixture 是理解输出契约的"活文档"：任何改动若导致格式偏移，测试会立即暴露；反之，若你的场景需要新的输出元素（例如新的元数据字段或统计维度），同样可以在 golden 树中先定基准再实现。

8. 实践：如何复现这条管线

要复现上述产物，你需要一个无 DRM 的 EPUB 文件（样例夹具可参考 tests/fixtures/synthetic/ 中的合成电子书），并安装依赖：

pip install "skill-seekers[epub]" # 或 pip install ebooklib

随后执行 CLI（见 epub_scraper.py 顶部 docstring 的用法）：

skill-seekers epub --epub book.epub --name myskill skill-seekers epub --from-json book_extracted.json

• 第一条命令走完整抽取管线：解析 EPUB → DRM 检测 → 元数据/正文/代码/图片抽取 → 生成SKILL.md、references/与assets/；
• 第二条命令支持从已抽取的中间 JSON（{name}_extracted.json）直接构建，适合多源聚合与关键词分类场景 —— 与测试中"无epub_path即走 keyword categorization 路径"的机制一致。

若需自定义分类，在配置中传入categories映射（如{"setup": ["setup", "installation"], "api": ["endpoints"]}），即可像 golden 树一样得到按主题归类的参考文件与 Section Overview。

小结：从section_s1-s1.md这一份 36 行的参考章节出发，我们完整还原了 Skill Seekers 的 EPUB 转技能链路 —— 文件命名与分类规则、EpubToSkillConverter的抽取细节、代码质量评分与语言探测、双路径表格渲染、SKILL.md 聚合统计，以及 golden 树的逐字节回归价值。这份文件既是管线输出的"样例"，也是验证输出契约的"基准"，值得作为理解 Skill Seekers 文档技能构建体系的第一个切入口。

• 人工智能
• AI 应用
• AI 技能
• RAG
• MCP 服务
• 网页爬虫