人工智能AI 应用AI 技能RAGMCP 服务网页爬虫【免费下载链接】Skill_SeekersConvert documentation websites, GitHub repositories, and PDFs into Claude AI skills with automatic conflict detection项目地址https://gitcode.com/gh_mirrors/sk/Skill_Seekers点击查看免费下载Skill_Seekers能将 PDF 文档转换为可直接供 Claude 等 AI 使用的 Skill其中按章节归类页面是 PDF 管线区别于 HTML/GitHub 等来源的关键能力。本文以仓库内黄金测试输出tests/golden/phase2/pdf_chapters/references/index.md为切入点逐层拆解 PDF 章节检测、分类决策、参考文件与索引生成、以及字节级一致的黄金回归验证机制帮助读者掌握 Skill Seeker PDF 技能构建的完整原理。一、从一张黄金索引文件看懂章节化分类的最终产物tests/golden/phase2/pdf_chapters/references/index.md是 PDF 技能构建管线在章节分类模式下生成的参考文档索引它忠实地反映了三个关键事实多类别输出一个 PDF 被拆成多个章节类别每个类别对应一个独立参考文件页码范围标注每个类别都标注了其覆盖的 PDF 物理页码区间质量统计回填索引底部沉淀了整份文档的代码质量指标。其完整内容如下# Golden_Pdf_Ch Documentation Reference ## Categories - [Chapter 1: Basics](https://link.gitcode.com/i/378dd8e54e6e519ea01c59070cbecf0c) (2 pages, Pages 1-2) - [Chapter 2: Advanced](https://link.gitcode.com/i/4bbaf2ac791e4c6d3f7f28abb053efb7) (1 pages, Pages 3-3) - [Additional Content](https://link.gitcode.com/i/9df2204126d09ba51db4bf57adacb4e6) (1 pages, Pages 4-4) ## Statistics - Total pages: 4 - Code blocks: 4 - Images: 2 - Average code quality: 7.4/10 - Valid code blocks: 4该文件的同级目录还包含三个章节参考文件section_p1-p2.md、section_p3-p3.md、section_p4-p4.md以及顶层SKILL.md它们共同构成了一个完整 PDF Skill 的产物树。注意第三行Additional Content——它对应第 4 页该页不落在任何章节区间内被归类进了未分类桶这正是章节分类逻辑的一个重要边界行为详见第五节。二、Categories 目录章节到参考文件的链接规范2.1 文件名生成规则index.md中每个类别的链接指向section_p1-p2.md这类文件其命名规则由DocumentSkillBuilder._reference_filename()统一产出src/skill_seekers/cli/document_skill_builder.py而PDFToSkillConverter通过类属性注入 PDF 专属参数src/skill_seekers/cli/pdf_scraper.pyNUMBER_KEY page_number NUMBER_PREFIX p RANGE_LABEL Pages于是页码 1-2 的章节被命名为section_p1-p2.md页码 3 的章节命名为section_p3-p3.md。命名与SKILL.md的 Navigation 区、index.md的 Categories 区共用同一个函数从设计上杜绝了链接漂移源码注释中标记为 DOC-07 约束。2.2 页码区间与页数统计_generate_index()src/skill_seekers/cli/document_skill_builder.py遍历分类结果对每个类别用s.get(NUMBER_KEY)取每页的page_number计算min/max得到Pages 1-2这样的区间输出({section_count} pages, {sec_range_str})格式若类别为空0 页则输出N/A而不是空区间。这就是(2 pages, Pages 1-2)一行数据的完整来源。三、Statistics 统计块五维质量画像index.md底部的 Statistics 由PDFToSkillConverter._write_index_statistics()重写基类后输出src/skill_seekers/cli/pdf_scraper.py数据来自提取阶段pdf_extractor_poc.py汇总的extracted_data统计项示例值数据来源Total pages4total_pagesPDF 总页数Code blocks4total_code_blocks提取到的代码块总数Images2total_images文档内图片/图表总数Average code quality7.4/10quality_statistics.average_quality代码质量均值保留 1 位小数Valid code blocks4quality_statistics.valid_code_blocks通过质量校验的代码块数注意基类版本写的是Total sections章节数PDF 覆盖为Total pages页数——PDF 的统计口径以页为单位与UNIT_LABEL pages保持一致。质量统计在提取端由PDFExtractor计算src/skill_seekers/cli/pdf_extractor_poc.py除均值与有效数外还包含high/medium/low_quality_blocks三档分布。四、章节数据从哪里来PDFExtractor 的章节检测index.md里每个章节的标题 起止页码{title: Chapter 1: Basics, start_page: 1, end_page: 2}并非凭空产生而是由提取器pdf_extractor_poc.py在抽取阶段完成检测。4.1 章节起点判定规则detect_chapter_start()src/skill_seekers/cli/pdf_extractor_poc.py按优先级依次判断某页是否开启新章节标题层级页面headings列表中的第一个标题若为h1或h2即视为章节起点章节名取该标题文本文本模式匹配对页面首行文本做正则匹配命中以下模式之一即视为章节起点^Chapter\s\d # Chapter 1 ^Part\s\d # Part 2 ^Section\s\d # Section 3 ^\d\.\s[A-Z] # 1. Introduction4.2 分块与章节范围推算提取器以chunk_size默认 10 页为粒度分块但不会在章节起点处强行切块保证章节完整性每个 chunk 记录start_page、end_page与chapter_title。最终在结果组装阶段src/skill_seekers/cli/pdf_extractor_poc.py收敛为chapters [ {title: chunk[chapter_title], start_page: chunk[start_page], end_page: chunk[end_page]} for chunk in chunks if chunk[chapter_title] ]输出示例与测试中手工构造的章节结构完全一致见 tests/test_phase2_golden_pdf.pydata[chapters] [ {title: Chapter 1: Basics, start_page: 1, end_page: 2}, {title: Chapter 2: Advanced, start_page: 3, end_page: 3}, ]五、分类决策单源 / 章节 / 关键词三级路径PDFToSkillConverter.categorize_content()src/skill_seekers/cli/pdf_scraper.py重写了基类的分类逻辑按优先级走三条路径路径一单 PDF 源配置了pdf_path。为避免自动章节检测把内容切错直接以 PDF 文件名作为唯一类别包含全部页面——这也是黄金测试test_pdf_build_matches_golden覆盖的快速路径。路径二章节分类存在chapters字段多源场景。对每个章节建立类别然后逐页匹配for chapter in self.extracted_data[chapters]: if chapter[start_page] page_num chapter[end_page]: # 归入该章节未命中任何章节区间的页面被收集进uncategorized_pages最后统一放入名为uncategorized的类别标题固定为Additional Contentsrc/skill_seekers/cli/pdf_scraper.py。这正是index.md中第三行Additional Content ... Pages 4-4的来源——第 4 页附录落在章节 1-3 之外被安全兜底。路径三关键词分类配置了categories无章节。对每页的text与headings拼接文本按关键词打分归入得分最高的类别无命中则进入other标题 Other桶。空关键词类别如测试中的deployment: [kubernetes]保持为空列表不会产生假页面。最终兜底以上皆无时所有页面归入单一content类别。分类结束后控制台会打印每个类别的标题与页数便于排查分类结果。六、章节参考文件 section_*.md 的生成细节每个分类对应一个参考文件由_generate_reference_file()src/skill_seekers/cli/pdf_scraper.py生成其结构可直接对照黄金文件 section_p1-p2.md 验证# Chapter 1: Basics **Pages**: 1-2 --- ** Source: PDF Page 1** ## Getting Started Guide ...正文... ### Code Examples python print(hello)ImagesImage from page 1生成要点 - **页范围头**文件开头写入 **Pages**: {min}-{max} - **溯源标记**每页前写入 ** Source: PDF Page N**保留页面级可追溯性 - **标题处理**只取每页 headings 列表的**第一个**标题作为 ## 小节标题而非全部标题 - **代码兼容双键**优先读 code_samples缺失时回退到旧版 code_blocks 键[src/skill_seekers/cli/pdf_scraper.py](https://link.gitcode.com/i/cc588c1ec18b19314f2da3275be19e7e)兼容两种提取格式 - **图片两种形态**extracted_images提取器已落盘的图片仅写链接指向 ../assets/images/xxx.png与旧版 images原始字节构建时写盘为 page_{N}_img_{index}.png 并引用。后者有数据守卫data 缺失或非 bytes/空值会被跳过避免写坏 PNG 或产生 404 图片链接[src/skill_seekers/cli/pdf_scraper.py](https://link.gitcode.com/i/4f71a443f872248278d2f675210df852)。黄金输出 tests/golden/phase2/pdf_chapters/assets/page_2_img_0.png 即由此路径写盘。 ## 七、SKILL.md 的配套结构章节分类的对外呈现 章节分类不仅生成 references还驱动顶层 [SKILL.md](https://link.gitcode.com/i/cc334d713ff062e2a83472a4e6f6adae)。_generate_skill_md()[src/skill_seekers/cli/pdf_scraper.py](https://link.gitcode.com/i/c031476af5285c104024fc1c39118a9b)在 YAML frontmattername 小写化 连字符化description 截断至 1024 字符之后产出 PDF 专属结构 - **Chapter Overview**以 **Total Pages:** 开头逐类别列出页数Chapter 1: Basics: 2 pages 等 - **Key Concepts**从所有页面 headings 中提取 h1 作为 Major Topics前 10、h2 作为 Subtopics前 15缺失 level 时默认 h1 - **Quick Reference**将 getting started、installation、usage、troubleshooting 等 11 个模式关键词匹配到标题按类型分组并以 (page N) 标注出处 - **Code Examples**按 quality_score 降序取全文档前 15 段按语言分组、每语言取前 5超过 500 字符截断加 ... - **Documentation Statistics**总页数、代码块、图片、语言分布languages_detected与代码质量指标 - **Navigation**列出全部 references/*.md 及其章节标题链接与 index.md 同源生成。 ## 八、黄金回归机制为什么这份 index.md 值得信任 这份 index.md 是**黄金测试golden test**的产物被用于证明 PDF 刮取器在重构到 DocumentSkillBuilder 基类后输出字节级不变。 ### 8.1 测试协议 tests/phase2_golden_utils.py 定义了双模式协议[tests/phase2_golden_utils.py](https://link.gitcode.com/i/089ac5e6d5ec53a602ccdbaccd9605a2) - **捕获模式**UPDATE_GOLDENS1 pytest test在重构前的旧代码上运行将完整产物树含 index.md、各 section_*.md、SKILL.md、assets 图片落盘提交 - **比对模式**重构后同测试在无环境变量时运行逐字节比对每个文件**任何差异都会让测试失败并输出 unified diff**[tests/phase2_golden_utils.py](https://link.gitcode.com/i/54ea1392f9e0a71a741c4be600500f25)文件集合的增删也会被检测。 ### 8.2 章节分类测试用例 [tests/test_phase2_golden_pdf.py](https://link.gitcode.com/i/3e00b8a3ba744aaabf4700de8cd59212) 中的 test_pdf_chapter_categorization_matches_golden 专门构造了本场景3 页基础数据 追加第 4 页附录chapters 为两个区间然后断言 build_snapshot(converter) 与 tests/golden/phase2/pdf_chapters/ 完全一致。同一测试文件的另两个用例分别验证单源快速路径pdf与关键词分类pdf_kw覆盖 scored-match、other 桶、空类别三种边界。 因此这份 index.md 不仅是文档更是 PDF 章节分类行为的事实快照——任何改动若改变了链接、页码区间或统计数值回归测试都会立刻拦截。 ## 九、实操如何复现与扩展 ### 9.1 运行章节分类管线 pdf_scraper.py 支持三种入口[src/skill_seekers/cli/pdf_scraper.py](https://link.gitcode.com/i/496c8aeee2a5f866527241753c39b005) bash # 1) 通过配置文件含 pdf_path、name、categories 等 python3 pdf_scraper.py --config configs/manual_pdf.json # 2) 直接指定 PDF 与技能名走单源快速路径 python3 pdf_scraper.py --pdf manual.pdf --name myskill # 3) 从已提取的 JSON 恢复构建多源/章节场景 python3 pdf_scraper.py --from-json manual_extracted.json多源章节场景下--from-json的提取结果中需包含chapters字段结构见第四节若走extract_options可调参数包括chunk_size默认 10、min_quality默认 5.0、extract_images默认 True、min_image_size默认 100。9.2 关键词分类配置示例无章节数据时可通过categories配置关键词分类tests/test_phase2_golden_pdf.py{ name: golden_pdf_kw, categories: { setup: [setup, installation], api: [endpoints], deployment: [kubernetes] } }页面按关键词命中数打分归入最佳类别未命中进入other桶。9.3 验证回归# 无环境变量 比对模式输出必须与黄金树字节一致 pytest tests/test_phase2_golden_pdf.py # 有意更新黄金树仅在确实需要修改输出格式时使用 UPDATE_GOLDENS1 pytest tests/test_phase2_golden_pdf.py结语tests/golden/phase2/pdf_chapters/references/index.md是 Skill_Seekers PDF 技能管线章节化分类能力的最小完整样本它展示了一条从PDFExtractor的章节检测h1/h2 标题 文本模式正则、到PDFToSkillConverter的三级分类决策单源 / 章节 / 关键词、再到references/index.md目录与统计块生成、最终由黄金测试逐字节锁定的完整链路。理解这份索引的生成逻辑也就掌握了 Skill_Seekers 将任意 PDF 手册转化为结构化 AI 技能的核心机制——包括页码区间命名、未分类页面兜底、代码质量画像等容易在重构中被忽略的细节。赞分享人工智能AI 应用AI 技能RAGMCP 服务网页爬虫【免费下载链接】Skill_SeekersConvert documentation websites, GitHub repositories, and PDFs into Claude AI skills with automatic conflict detection项目地址https://gitcode.com/gh_mirrors/sk/Skill_Seekers点击查看免费下载相关推荐Skill Seeker 的 PDF 文档技能目录索引references/index.md生成机制与关键字分类实战Skill Seeker 的 PDF 文档技能目录索引references/index.md生成机制与关键字分类实战 本篇技术指南聚焦 Skill Seek人工智能AI 应用AI 技能RAGMCP 服务网页爬虫Skill Seekers PDF 转 Skill Golden 输出结构深度解析references/index.md 的生成原理与逐字节验证Skill Seekers PDF 转 Skill Golden 输出结构深度解析references/index.md 的生成原理与逐字节验证 导读 本文以人工智能AI 应用AI 技能RAGMCP 服务网页爬虫Caffeine 节点代码生成机制解析从 Add* 生成器到 Node 类的完整链路Caffeine 节点代码生成机制解析从 Add 生成器到 Node 类的完整链路 本指南聚焦 Caffeine caffeine/ https://lin后端缓存抽象创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
