企业官网建设流程全解析

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

本篇技术指南聚焦 Skill_Seekers 项目中 PowerPoint（.pptx）演示文稿转 AI 技能（Skill）管线的输出产物格式规范，以tests/golden/phase2/pptx/references/index.md这份 golden 参考索引为切入点，结合 pptx_scraper.py 的实现，完整讲解参考索引、按章节切分的引用文件、SKILL.md 的生成规则，以及支撑这些格式的章节分组、代码块识别、语言检测与代码质量评分机制。读完本文，你将能够准确理解并验证任何 .pptx 生成的技能目录结构，掌握 golden 测试如何逐字节校验输出格式。

引言：golden 参考索引是什么

当 Skill_Seekers 把一个 PowerPoint 演示文稿转换为可交付的 Claude 技能包时，产物目录中会包含三类核心文件：

• SKILL.md：技能主文件，含 YAML 头信息、演示文稿元数据、章节总览、代码示例精选与统计；
• references/index.md：演示文稿参考索引，即本篇的关联文档，用最小化的统计清单概括整个演示文稿的结构规模；
• references/deck.md：按章节切分的引用文件，承载每个章节的具体内容（正文、代码、表格、图片与演讲者备注）。

index.md的作用是让阅读技能的 Agent 在进入庞大的引用文件之前，先快速获知演示文稿的全貌：共多少张幻灯片、划分为几个章节、包含多少代码块与图片、作者与创建时间是谁。它以极简的 Markdown 清单呈现，数据全部来自提取阶段生成的结构化 JSON，而非重新扫描文件。

Golden 参考索引的文件结构

关联文档 index.md 的完整内容如下：

# Golden_Pptx Presentation Reference ## Categories - [deck](https://link.gitcode.com/i/b38caead0b776b220e27a54ef7493e76) (3 sections, Sections 1-3) ## Statistics - Total slides: 8 - Total sections: 3 - Code blocks: 3 - Images: 2 - Tables: 2 - Author: Jane Doe - Created: 2024-01-01

其结构可分为三个部分，逐一拆解：

标题与 Categories 区块

标题# Golden_Pptx Presentation Reference由DocumentSkillBuilder的索引生成逻辑结合DOC_NOUN = "presentation"拼装而成（见 pptx_scraper.py 的类属性定义），因此演示文稿的技能索引统一以 "Presentation Reference" 结尾。

## Categories区块列出本技能包内的引用文件分组。[deck](https://link.gitcode.com/i/b38caead0b776b220e27a54ef7493e76) (3 sections, Sections 1-3)表示：存在一个名为deck的引用文件（对应演示文稿的主题名），其中包含 3 个章节，覆盖幻灯片 1～3。这里的 "Sections 1-3" 指的是章节序号区间（非幻灯片区间），它由分组逻辑根据章节数量推导。

Statistics 统计区块

## Statistics是索引文件的信息核心，字段含义如下：

该区块的生成逻辑位于 pptx_scraper.py 的_write_index_statistics方法。它重写了基类实现，专门为演示文稿增加了Total slides与Tables两行，随后遍历INDEX_METADATA_FIELDS = (("author", "Author"), ("created", "Created"))（见 pptx_scraper.py），仅当元数据字段非空时才输出对应行——因此不是每份索引都会出现 Author/Created。

引用文件（references/deck.md）的章节渲染规则

golden 树中的 deck.md 展示了每个章节在引用文件中的完整排版，其渲染由_write_reference_section（pptx_scraper.py）负责，依次输出：

1. 来源行：**📄 Source: Section 1** (Slides 1-3)。幻灯片区间来自章节的slide_range字段；若该字段为空（如只有单张内容页的章节），则只输出**📄 Source: Section N**裸行——golden 中 Section 3 正是这一分支的验证样例（deck.md）。
2. 章节标题：## Getting Started Guide。标题级别由heading_level（h1/h2）决定，Markdown 层级为原始级别加一，即 h1 →##、h2 →###。
3. 子标题：如#### Slide 2: Verify Setup，对应各张幻灯片的标题，格式为Slide {n}: {title}，由_build_section_from_slides收集（pptx_scraper.py）。
4. 正文：章节正文（多个幻灯片的 body 文本以空行拼接）。
5. Speaker Notes：### Speaker Notes区块，演讲者备注以[Slide N] 备注内容形式逐条列出。
6. Code Examples：### Code Examples区块，按```lang代码栅栏输出，lang 为检测到的语言。
7. Tables：### Tables区块，将表格渲染为 Markdown 表。
8. Images：### Images区块，*2 image(s) in this section*图片数量摘要。
9. 章节间以---分隔线隔开。

deck.md 中可观察到两个细节分支：

• 长代码截断：Section 2 中 60 行的 Python 长代码被完整写入引用文件（引用文件保留完整代码），而 SKILL.md 精选示例中同一段代码只保留前 500 字符并追加...（见下文）。
• 无表头表格：Section 2 的表格| a | b | / | c | d |只有两行数据、没有表头行，对应测试注释中"headerless rendering path"分支（test_phase2_golden_pptx.py）。

SKILL.md 主文件的演示文稿化结构

golden 树中的 SKILL.md 由_generate_skill_md（pptx_scraper.py）完整覆写基类生成，是演示文稿特有的结构：

• YAML 头：name（skill 名小写化、下划线转连字符、截断 64 字符）与description（截断 1024 字符）。
• Presentation Information：元数据面板，依次输出 Title、Author、Subject、Category、Created、Modified、Slides。
• When to Use This Skill：固定的五条用途列表（理解概念、回顾要点、查找代码示例、访问演讲者备注、引用表格数据）。
• Section Overview：Total Slides / Total Sections 与按分类分组的 Content Breakdown（- **deck**: 3 sections）。
• Key Concepts：由_format_key_concepts（pptx_scraper.py）从各章节 heading 提取，按级别输出 Major Sections（h1）、Subsections（h2）、Slide Topics（仅有 h3 而无 h2 时输出）。
• Quick Reference：基于 PATTERN_KEYWORDS 的模式识别结果。
• Code Examples：全技能代码块按quality_score降序排序取前 15，再按语言分组、每种语言最多展示 5 条，每条标注Quality: x.x/10；超过 500 字符的代码截断为前 500 字符加...。
• Table Summary：最多展示 5 张表格，带From section: xxx标注。
• Presentation Statistics：Total Slides / Total Sections / Code Blocks / Images-Diagrams / Tables / Programming Languages 及语言分布（- python: 2 examples）。
• Navigation：列出references/下的引用文件，并指引See references/index.md for complete presentation structure.。
• 页脚：**Generated by Skill Seeker** | PowerPoint Presentation Scraper，对应FOOTER_LABEL。

背后的源码机制：章节分组与内容提取

基于版式的章节分组

_group_slides_into_sections（pptx_scraper.py）决定章节如何切分：凡是使用"节标题/仅标题"类版式（TITLE_ONLY_LAYOUTS：section header、section、title slide、title only）的幻灯片视为章节断点；若整个演示文稿没有检测到任何断点，则全部幻灯片归为一个章节。每张幻灯片还会记录layout_name与is_section_slide标志。

代码块识别与质量评分

代码块识别依赖等宽字体启发式（pptx_scraper.py）：当一段文字中 ≥60% 字符使用MONOSPACE_FONTS（Courier、Consolas、Menlo、Fira Code、JetBrains Mono 等 26 种）即判定为代码；若等宽比例 ≥30% 且文本命中代码模式正则（函数定义、import、赋值、运算符等）也算代码。判定后的代码块由score_code_quality（scraper_utils.py）给出 0.0～10.0 的质量分：基准 5.0 分，行数 ≥5 加 1 分、≥10 加 2 分，含函数/类定义加 1.5 分，含 import 加 0.5 分，含缩进加 0.5 分，含常见语法符号加 0.3 分，长度不足 30 字符扣 2 分。golden 中print('hello')得 8.5 分、pip install thing得 6.0 分、60 行的long_example得 9.5 分，正是这套评分的结果，并被 SKILL.md 的代码精选排序直接使用。

语言检测

_detect_languages（pptx_scraper.py）调用项目的LanguageDetector（min_confidence=0.15，采纳阈值 0.3）对无语言标注的代码块做识别，并汇总languages_detected统计（golden 中为{"python": 2, "bash": 1}），最终写入 SKILL.md 的语言分布。

Golden 测试如何保证格式稳定

tests/golden/phase2/pptx/是 golden 测试的基准产物树，其配套测试 test_phase2_golden_pptx.py 通过 phase2_golden_utils.py 提供的build_snapshot+assert_matches_golden机制工作：

1. 测试构造一个PptxToSkillConverter实例，注入与 gold golden 对应的extracted_data（元数据、章节、代码样例、表格等）；
2. build_snapshot运行build_skill()，把生成的skill_dir下所有文件读成{相对路径: 字节}快照；
3. assert_matches_golden将快照与tests/golden/phase2/pptx/逐文件、逐字节比对，任何差异都会抛出带 unified diff 的断言错误。

这正是关联文档能被当作"格式规范"的原因：它不仅是某次运行的偶然输出，而是被 CI 持续校验的字节级基准。测试还覆盖了关键词分类路径（test_pptx_keyword_categorization_matches_golden，对应pptx_kwgolden 树）与仅有 h3 子标题的分支。需要重新生成基准时，可用UPDATE_GOLDENS=1 pytest tests/test_phase2_golden_pptx.py（这会重写已提交的 golden 树，仅在有意变更格式时使用）。

从命令行触发生成

通过 CLI 即可生成上述三类产物。PPTX 专属参数定义在 arguments/pptx.py：

• --pptx PATH：PowerPoint 文件路径（也可传目录，目录下所有 .pptx 按排序合并为一个技能）；
• --from-json FILE：从提取好的中间 JSON 直接构建技能（复用提取结果、跳过解析）。

基础用法：

# 单个文件 skill-seekers pptx --pptx presentation.pptx --name myskill # 整个目录（多个 pptx 合并） skill-seekers pptx --pptx ./slides_dir/ --name myskill # 基于已提取 JSON 重建 skill-seekers pptx --from-json presentation_extracted.json

注意：PPTX 命令默认关闭 AI 增强（--enhance-level默认被覆写为 0，见 arguments/pptx.py），即默认走纯提取 + 构建路径，产物即本文所讲的 golden 结构；如需增强可显式指定--enhance-level 1|2|3。依赖方面需安装python-pptx（缺失时会抛出引导安装的 RuntimeError，pptx_scraper.py）。

生成完成后可用skill-seekers package <skill_dir>/打包发布，产物树（references/index.md、references/deck.md、SKILL.md）与本文描述的 golden 格式一一对应。

小结

tests/golden/phase2/pptx/references/index.md虽然只有 15 行，却是 Skill_Seekers 演示文稿技能产物格式的浓缩规范：Categories 区块宣告引用文件组织方式，Statistics 区块承载演示文稿级统计。以它为起点，你可以顺着 deck.md 理解章节渲染的八个组成部分与两个边界分支，顺着 SKILL.md 理解演示文稿化主文件结构，再落到 pptx_scraper.py 与 test_phase2_golden_pptx.py 验证每一处格式分支的字节级行为——这份"格式即测试基准"的工程实践，正是该模块输出长期稳定的保证。

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