ln-150-presentation-creator

Name: ln-150-presentation-creator
Author: levnikolaevich

github.com/levnikolaevich文档处理584150 次安装2 天前更新

代码仓库

关于 ln-150-presentation-creator

将现有项目文档转换为独立、可交互的 HTML 演示文稿的技能。面向具备需求、架构和技术栈必需文档的项目，并将内容组织为六个可导航标签页。

主要功能

01验证必需的源文档
02检查源内容质量
03生成六标签页演示文稿
04支持 Mermaid 图表
05构建独立 HTML 文件
06保留现有演示资源

适用场景

01以演示文稿形式分享项目文档
02文档更新后重新生成演示文稿
03生成前检查文档是否就绪

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/levnikolaevich/claude-code-skills --skill ln-150-presentation-creator

安装后在 Claude Code 中输入/ln-150-presentation-creator确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

presentation_final.html

references/

build-presentation.js

phases_detailed.md

presentation_readme_template.md

presentation_template.html

scripts.js

styles.css

references/tabs/

tab_architecture.html

tab_guides.html

tab_overview.html

tab_requirements.html

tab_roadmap.html

tab_technical_spec.html

详细介绍

路径： 文件路径（shared/、references/、../ln-*）均相对于 skills 仓库根目录。如果在当前工作目录中找不到，请定位此 SKILL.md 所在目录，并向上一级找到仓库根目录。如果缺少 shared/，请通过 WebFetch 从 https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path} 获取文件。

HTML 演示文稿构建器

此技能可根据现有项目文档创建交互式、独立的 HTML 演示文稿。它会将 Markdown 文档转换为专业、易于导航的网页演示文稿，并支持图表、可折叠分区和现代化 UI。

用途

将现有 Markdown 文档转换为交互式、独立的 HTML 演示文稿，其中包含 6 个标签页（概览、需求、架构/C4、技术规范、路线图、指南），并支持 Mermaid 图表。

何时使用此技能

此技能是由 ln-100-documents-pipeline 编排器调用的 L2 WORKER，也可以独立使用。

在以下情况下使用此技能：

根据现有文档构建 HTML 演示文稿
更新文档后重新构建演示文稿
创建可供分享的独立演示文稿（无需完整的文档设置）
验证源文档是否已准备好生成演示文稿

工作流组成部分：ln-100-documents-pipeline → ln-110-project-docs-coordinator → ln-120-reference-docs-creator → ln-130-tasks-docs-creator → ln-140-test-docs-creator（可选）→ ln-150-presentation-creator

前提条件：docs/ 目录中已有文档，且包含必需文件：

docs/project/requirements.md（必需）
docs/project/architecture.md（必需）
docs/project/tech_stack.md（必需）

可选文件（可增强演示文稿，但不会阻止生成）：

docs/project/api_spec.md、database_schema.md、design_guidelines.md、infrastructure.md、runbook.md
docs/reference/adrs/*.md（Category 为 Strategic|Technical 的 ADR）
docs/reference/guides/*.md（操作指南）
docs/tasks/kanban_board.md（路线图的 Epic Story 计数器）

工作流

此技能遵循7 阶段工作流：读取文档 → 验证源文件是否存在 → 验证源文件质量 → 创建目录 → 复制模板 → 注入内容 → 构建 HTML。

阶段 1：读取文档 - 从 docs/ 加载所有项目文档 阶段 2：验证源文件是否存在 - 检查必需文件是否存在（requirements.md、architecture.md、tech_stack.md），如果缺少可选文件则发出警告 阶段 3：验证源文件质量 - 检查图表、占位符和内容长度（只读验证） 阶段 4：创建目录 - 创建 presentation/ 目录和 README.md 导航页 阶段 5：复制模板 - 将 HTML/CSS/JS 模板复制到 assets/ 阶段 6：注入内容 - 解析 MD 文档 → 替换标签页文件中的占位符 → 删除示例区块 阶段 7：构建 HTML - 将模块化组件组合成独立的 presentation_final.html

必须阅读： 加载 references/phases_detailed.md，了解各阶段的详细工作流。

阶段 1：读取文档

目标：加载所有项目文档，以供转换。

执行时机：始终执行（第一个阶段）

流程：

使用 docs/ 作为来源：
- 从 docs/project/、docs/reference/、docs/tasks/ 目录读取文档
- 这些标准位置由 ln-114、ln-112、ln-113 创建
读取核心 MD 文档：
- project/requirements.md - 功能需求
- project/architecture.md - 架构设计、C4 图
- project/tech_stack.md - 技术版本、Docker 配置
- project/api_spec.md - API 端点、身份验证（如果存在）
- project/database_schema.md - 数据库架构、ER 图（如果存在）
- project/design_guidelines.md - UI/UX 设计系统（如果存在）
- project/infrastructure.md - 基础设施清单（如果存在）
- project/runbook.md - 运维流程（如果存在）
读取 ADR（如果存在）：
- reference/adrs/adr-001-*.md 至 adr-NNN-*.md
- 解析 ADR 元数据（状态、日期、标题、类别：Strategic|Technical）
读取指南（如果存在）：
- reference/guides/*.md - Guides 选项卡的操作指南
读取看板（如果存在）：
- tasks/kanban_board.md - 用于跟踪路线图进度的 Epic Story Counters 表格
提取元数据：
- 从文档中提取项目名称、日期、版本
- 保留 Mermaid 图表代码块

输出：已加载的文档数据，可用于验证和生成 HTML

阶段 2：验证源文档是否存在

目标：在构建演示文稿前，确认所需的源文档存在。避免生成不完整的演示文稿。

执行时机：阶段 1 之后（文档已加载）

流程：

2.1 检查必需文件

必需（必须存在——若缺失则阻止执行）：

✅ docs/project/requirements.md
✅ docs/project/architecture.md
✅ docs/project/tech_stack.md

对于每个必需文件：

使用 Glob 工具：pattern: "docs/project/{filename}"
如果未找到：
- 添加到缺失列表
如果找到：
- 检查文件大小是否大于 100 字节（非空）

如果任何必需文件缺失或为空：

❌ ERROR: Cannot build presentation - missing required documentation:
  - docs/project/requirements.md [missing/empty]
  - docs/project/architecture.md [missing/empty]

Suggestion: Run ln-111-project-docs-creator to create missing files.

STOP execution.

2.2 检查可选文件

可选（可增强演示文稿——缺失时发出警告，但继续执行）：

⚠️ docs/project/api_spec.md（适用于后端项目）
⚠️ docs/project/database_schema.md（适用于包含数据库的项目）
⚠️ docs/project/design_guidelines.md（适用于前端项目）
⚠️ docs/project/runbook.md（适用于运维项目）

对于每个可选文件：

使用 Glob 工具：pattern: "docs/project/{filename}"
如果未找到：
- 添加到可选缺失列表

如果可选文件缺失：

⚠ WARN: Optional files missing: [list]
Presentation will have reduced content in some tabs.
Continue execution.

2.3 检查可选目录

可选目录：

docs/reference/adrs/ - 检查是否存在 ADR 文件（adrs/*.md）
docs/reference/guides/ - 检查是否存在指南文件（guides/*.md）
docs/tasks/kanban_board.md - 检查路线图数据

对于每个目录：

使用 Glob 工具查找文件
如果为空或不存在：
- 记录日志：ℹ Optional directory empty: {directory} - related tab will show placeholder

2.4 汇总验证结果

记录摘要：

✓ Source documentation validation completed:
  Required files:
    - ✅ requirements.md (found, 8.5 KB)
    - ✅ architecture.md (found, 15.2 KB)
    - ✅ tech_stack.md (found, 3.1 KB)
  Optional files:
    - ⚠️ api_spec.md (missing - Technical Spec tab will have reduced content)
    - ✅ database_schema.md (found, 4.7 KB)
    - ⚠️ design_guidelines.md (missing)
  Optional directories:
    - ✅ adrs/ (5 ADR files found)
    - ⚠️ guides/ (empty - Guides tab will show placeholder)
    - ✅ kanban_board.md (found - Roadmap will show progress)

输出：验证通过（所有必需文件均存在）或发生错误（停止执行）

第 3 阶段：验证源内容质量

目标：验证源文档是否包含足够的内容。对不完整的内容发出警告，但不阻止执行。

执行时机：第 2 阶段之后（源文件已存在）

执行的检查（仅警告，不会阻止执行）：

Mermaid 图表：architecture.md 必须至少有 1 个图表，database_schema.md 必须包含 ER 图
占位符：检测 {{PLACEHOLDER}}、[Add your ...]、TODO: 模式
内容长度：requirements.md >500 个单词，architecture.md >1000 个单词，tech_stack.md >200 个单词

自动修复：无 — ln-115 为只读。运行 ln-111-project-docs-creator 修复问题。

输出：包含警告的内容质量报告

📖 详细工作流：参见 phases_detailed.md §Phase 3

第 4 阶段：创建演示目录和 README

目标：设置演示目录结构和导航中心。

执行时机：第 3 阶段之后（源验证已完成，警告已记录）

流程：

创建演示目录：
```
mkdir -p docs/presentation/
```
检查 presentation/README.md 是否存在：
- 使用 Glob 工具：pattern: "docs/presentation/README.md"
- 如果文件已存在：
  - 跳过创建
  - 记录：✓ docs/presentation/README.md already exists (preserved)
  - 继续第 5 阶段
- 如果文件不存在：
  - 继续第 3 步
根据模板创建 presentation/README.md：
- 复制模板：references/presentation_readme_template.md → docs/presentation/README.md
- 替换占位符：
  - {{PROJECT_NAME}} — 从 requirements.md 获取
  - {{LAST_UPDATED}} — 当前日期（YYYY-MM-DD）
- 内容结构：
  - 用途：介绍此演示文稿
  - 快速导航：指向 presentation_final.html 和 assets/ 的链接
  - 自定义指南：如何编辑 assets/ 中的源文件
  - 构建说明：更改后如何重新构建
  - 维护：何时重新构建、验证清单
通知用户：
- 如果已创建：✓ Created docs/presentation/README.md (navigation hub)
- 如果已跳过：✓ docs/presentation/README.md already exists (preserved)

输出：docs/presentation/README.md（已创建或已存在）

第 5 阶段：将模板复制到项目中

目标：将 HTML/CSS/JS 模板从技能的 references/ 复制到演示目录。

执行时机：第 4 阶段之后（演示目录已存在）

流程：

检查 assets 是否存在：
- 使用 Glob 工具：pattern: "docs/presentation/assets/"
- 如果 docs/presentation/assets/ 已存在：
  - 跳过复制（用户可能已自定义文件）
  - 记录：✓ Presentation assets already exist - preserving user customizations
  - 继续第 6 阶段
- 如果不存在：
  - 继续第 2 步

复制模板文件：

cp references/presentation_template.html → docs/presentation/assets/
cp references/styles.css → docs/presentation/assets/
cp references/scripts.js → docs/presentation/assets/
cp references/build-presentation.js → docs/presentation/assets/
cp -r references/tabs/ → docs/presentation/assets/tabs/

验证复制后的结构：

docs/presentation/assets/
├── presentation_template.html   # Base HTML5 + 6 tab navigation
├── styles.css                    # ~400-500 lines
├── scripts.js                    # Tab switching + Mermaid init
├── build-presentation.js         # Node.js build script
└── tabs/
    ├── tab_overview.html         # Landing page
    ├── tab_requirements.html     # FRs + ADRs
    ├── tab_architecture.html     # C4 diagrams
    ├── tab_technical_spec.html   # API + Data + Deployment
    ├── tab_roadmap.html          # Epic list
    └── tab_guides.html           # How-to guides

输出：模板文件已复制到 docs/presentation/assets/（如果已存在则跳过）

注意：模板包含占位符（{{VARIABLE_NAME}}），将在第 6 阶段替换。

第 6 阶段：内容注入和示例清理

目标：解析 MD 文档，将内容注入 HTML 模板，并移除示例区块。

执行时机：第 5 阶段之后（assets/ 中已存在模板）

流程：

解析 MD 文档（10 个来源）：requirements、architecture、tech_stack、api_spec、database_schema、design_guidelines、runbook、adrs/.md、kanban_board、guides/.md
注入内容：将 6 个标签页文件中的 {{PLACEHOLDER}} 替换为解析后的内容
删除示例：从所有标签页中移除 ... 区块

标签页占位符：Overview（5）、Requirements（4 + NFR 禁用）、Architecture（5）、Technical Spec（4）、Roadmap（3）、Guides（6）

验证：不包含示例标记，不包含硬编码的电商数据，仅包含项目专属内容

输出：清理完成、项目专属的标签页文件，可供构建

📖 占位符参考和示例转换：参见 phases_detailed.md §Phase 6

阶段 7：构建最终演示文稿

目标：将模块化组件组装成独立的 HTML 文件。

执行时机：阶段 6 之后（内容已注入，示例已删除）

流程：

检查 presentation_final.html 是否存在（自动重建以支持自动化）：
- 使用 Glob 工具：pattern: "docs/presentation/presentation_final.html"
- 如果文件存在：
  - ✓ 自动重建（生成的文件，安全操作）
  - 记录：ℹ Rebuilding presentation_final.html (generated file, safe to rebuild)
  - 继续执行步骤 2
- 如果不存在：
  - 记录：Creating presentation_final.html
  - 继续执行步骤 2
自动重建的原因：
- presentation_final.html 是一个生成的文件（事实来源：assets/ 目录）
- 重建安全，不会丢失数据（源文件保留在 assets/ 中）
- 由 ln-110-documents-pipeline 调用时，可维持全自动工作流
- 用户在 assets/ 中的自定义内容会保留（只会重新生成最终 HTML）
进入演示文稿资源目录：
```
cd docs/presentation/assets/
```
运行构建脚本：
```
node build-presentation.js
```
构建脚本流程：
- 步骤 1：读取 presentation_template.html
- 步骤 2：读取并内联 styles.css → <style> 标签
- 步骤 3：读取并内联 scripts.js → <script> 标签
- 步骤 4：读取全部 6 个选项卡文件 → 注入空的 <div> 容器
- 步骤 5：将 {{PLACEHOLDERS}} 替换为实际值
- 步骤 6：写入 ../presentation_final.html
验证输出（仅当文件已构建时）：
- 检查文件大小（预期约为 120-150 KB）
- 验证 Mermaid 图表语法是否有效
- 记录：✓ Build completed successfully
通知用户：
- 如果是重建（文件原本存在）：✓ Rebuilt docs/presentation/presentation_final.html (~120-150 KB)
- 如果是新建（文件原本不存在）：✓ Created docs/presentation/presentation_final.html (~120-150 KB)
- 提醒：Test in browser: Double-click to open, or use http-server

输出：docs/presentation/presentation_final.html（自包含，约 120-150 KB，除 Mermaid.js CDN 外无外部依赖）

⚠️ 重要说明：

presentation_final.html 是根据 assets/ 中的模块化源文件构建的生成文件。

❌ 请勿直接编辑 presentation_final.html —— 下次重建时，修改将会丢失
✅ 请编辑 assets/ 目录中的源文件（模板、选项卡、样式、脚本）
🔄 修改后重新构建：cd assets/ && node build-presentation.js

完整输出结构

docs/
├── project/                      # Source documentation (input)
│   ├── requirements.md
│   ├── architecture.md
│   ├── tech_stack.md
│   ├── api_spec.md (conditional)
│   ├── database_schema.md (conditional)
│   ├── design_guidelines.md (conditional)
│   └── runbook.md (conditional)
├── reference/                    # Source documentation (input)
│   ├── adrs/
│   │   └── *.md (Category: Strategic | Technical)
│   └── guides/
│       └── *.md (optional)
├── tasks/                        # Source documentation (input)
│   └── kanban_board.md (Epic Story Counters)
└── presentation/                 # Output directory
    ├── README.md                 # Navigation hub
    ├── presentation_final.html   # Final standalone HTML (~120-150 KB)
    └── assets/                   # Modular HTML structure
        ├── presentation_template.html  # Base HTML5 + 6 tabs
        ├── styles.css                  # ~400-500 lines
        ├── scripts.js                  # Tab switching + Mermaid
        ├── build-presentation.js       # Node.js build script
        └── tabs/
            ├── tab_overview.html       # Landing page
            ├── tab_requirements.html   # FRs + ADRs
            ├── tab_architecture.html   # C4 diagrams
            ├── tab_technical_spec.html # API + Data + Deployment
            ├── tab_roadmap.html        # Epic list
            └── tab_guides.html         # How-to guides

注意：演示文稿从 docs/project/、docs/reference/、docs/tasks/ 读取内容，但输出到 docs/presentation/。

HTML 特性

唯一事实来源：不重复信息，每项内容只归属一个选项卡
首页（概览）：问题/解决方案/业务价值、利益相关者、文档指南、快速信息、技术栈徽章
交互式导航：6 个选项卡，带有 SCOPE 标签、状态持久化（localStorage）和平滑切换效果
基于表格的布局：仅包含 FR 表格（禁止包含非功能需求），以及架构重点表格
精简路线图：垂直 Epic 列表，包含范围内/范围外部分、状态徽章、依赖项/成功标准
ADR 组织方式：按类别（战略/技术）分组，使用手风琴式布局，并内联完整内容
图表可视化：使用 Mermaid.js，并在切换选项卡时重新渲染（C4、ER、序列图、部署图）
响应式设计：移动优先（断点：320px/768px/1024px+）
可折叠部分：自动折叠并保留滚动位置
现代 UI：简洁专业的设计，符合 WCAG 2.1 Level AA 标准
英语内容：演示文稿中的所有内容均为英语

最佳实践

幂等操作：保留 README.md，保留 assets/（用户自定义内容），自动重新构建 presentation_final.html。

各阶段关键规则：

Phase 2：缺少必需文件时停止；Phase 3：仅警告（不阻塞）
Phase 5：不要覆盖现有 assets/（用户自定义内容）
Phase 6：删除所有示例代码块，防止 XSS，确保 Mermaid 语法有效
Phase 7：如果输出超过 200 KB，则发出警告

自定义选项

编辑 assets/styles.css（用于主题设置的 CSS 变量）、assets/presentation_template.html（布局/标签页）或 assets/tabs/*.html（标签页内容）。

**⚠️ 进行任何自定义后：**务必重新构建演示文稿：

cd assets/
node build-presentation.js

**重要：**切勿直接编辑 presentation_final.html——这是每次构建时都会被覆盖的生成文件。

前置条件

编排器：ln-110-documents-pipeline | 独立运行：是（重新构建/验证现有文档）

必需文件：requirements.md、architecture.md、tech_stack.md（位于 docs/project/） 可选文件：api_spec、database_schema、design_guidelines、runbook、adrs/.md、guides/.md、kanban_board.md

依赖项：Node.js v18+、现代浏览器、互联网连接（Mermaid CDN）

完成定义

从 docs/project/、docs/reference/、docs/tasks/ 加载所有文档，提取元数据并保留 Mermaid 代码块
必需文件存在（requirements.md、architecture.md、tech_stack.md）——缺失时返回 ERROR
检查图表、检测占位符、检查内容长度（仅警告）
创建 docs/presentation/，创建/保留 README.md
创建包含所有模板的 assets/，或者在其已存在时保留
填充全部 6 个标签页，删除示例代码块，不含 `` 标记，不含硬编码数据
已执行 node build-presentation.js，已创建 presentation_final.html，并在浏览器中测试

**输出：**docs/presentation/presentation_final.html + assets/ + README.md

关键规则

**3 个必需文件：**requirements.md、architecture.md、tech_stack.md 必须存在——缺失时停止执行
**切勿覆盖 assets/：**保留现有 assets/ 目录（用户自定义内容）；仅重新生成 presentation_final.html
**删除所有示例代码块：**必须移除每个 ...；输出中不得包含硬编码的电商数据
**切勿直接编辑 presentation_final.html：**这是生成文件；请编辑 assets/ 中的源文件并重新构建
**需要 Node.js v18+：**构建脚本依赖 Node.js 来组装最终 HTML

参考文件

详细阶段工作流：references/phases_detailed.md
演示文稿 README 模板：references/presentation_readme_template.md
HTML 模板：references/presentation_template.html
样式：references/styles.css
脚本：references/scripts.js
构建脚本：references/build-presentation.js
标签页模板：references/tabs/tab_overview.html、tab_requirements.html、tab_architecture.html、tab_technical_spec.html、tab_roadmap.html、tab_guides.html

故障排查

ERROR：缺少必需文件：运行 ln-111-project-docs-creator 以创建 requirements.md、architecture.md、tech_stack.md
WARN：缺少图表：在 architecture.md（C4 上下文/容器/组件）和 database_schema.md（ER 图）中添加 Mermaid 图表
WARN：发现占位符：构建前，请完善源 MD 文件中的文档
WARN：内容过少：扩充文档（requirements.md >500 字、architecture.md >1000 字、tech_stack.md >200 字）
构建脚本失败：检查 Node.js v18+，进入 assets/，确认所有文件均存在
Mermaid 图表未渲染：使用 Mermaid Live Editor 检查语法，并确认 CDN 已加载
标签页无法切换：检查 JavaScript 是否已加载，并打开浏览器控制台查看错误
文件过大（>200 KB）：减少图表、压缩 CSS/JS、移除未使用的规则

**版本：**8.0.0 **最后更新：**2025-12-12

支持 Markdown

登录后评论

基本信息

作者: levnikolaevich
仓库: levnikolaevich/claude-code-skills
分类: 文档处理
安装次数: 150
GitHub Stars: 584

报告问题