hfut-marp-slides

name: hfut-marp-slides description: Use when creating Marp presentation slides, especially for HFUT academic defense, course reports, or thesis presentations. Triggers on keywords like PPT, slides, Marp, presentation, 答辩, 汇报, 演示文稿. When a project codebase folder exists in the PPT workspace, enforces strict fact-based content generation from actual source code analysis.

HFUT Awesome Marp Slides

Overview

使用 HFUT Awesome Marp 主题快速创建专业的学术演示文稿。基于 Markdown 语法，支持多种布局、导航栏、代码高亮、数学公式等特性。

工程目录分析（Project-Aware Mode）

当用户的 PPT 工作目录中存在工程项目文件夹时，PPT 内容必须严格基于工程事实。

检测条件

生成 PPT 前，先扫描 PPT 工作目录（即用户指定的 ws_src/xxx/ 目录）下是否存在工程项目文件夹。识别标志：

如果检测到任何一个标志文件，立即进入 Project-Aware Mode。

Project-Aware Mode 工作流

检测到工程文件夹
  ↓
Step 1: 深度代码分析（必须先完成，再写任何 PPT 内容）
  ↓
Step 2: 建立事实清单（Fact Sheet）
  ↓
Step 3: 基于事实清单生成 PPT 内容
  ↓
Step 4: 逐页交叉验证

Step 1: 深度代码分析（强制）

在写任何一行 PPT 内容之前，必须完成以下分析：

1. 读取项目元数据 — Cargo.toml / package.json / go.mod 等，提取：

   • 项目名称、版本、作者、描述
   • 所有依赖及其版本号（直接依赖，非传递依赖）
   • 构建配置、feature flags

2. 读取所有源代码文件 — 逐个读取 src/、lib/、app/ 等目录下的每一个源文件，提取：

   • 模块结构和文件组织
   • 核心数据结构（struct、class、interface 定义）
   • API 端点 / 路由定义
   • 关键算法和业务逻辑
   • 错误处理方式

3. 读取配置文件 — config/、.env、*.yaml、*.toml 等

4. 读取测试文件 — tests/、*_test.*、*.spec.*

5. 读取文档 — README.md、docs/

硬性禁止：未读取的文件中的内容不得出现在 PPT 中。

Step 2: 建立事实清单

分析完成后，在生成 PPT 前必须先整理出事实清单（不写入文件，在生成过程中作为内部参照）：

事实清单示例：
- 项目名：webserver
- 语言：Rust 2021 Edition
- 核心依赖：tokio 1.36.0, serde 1.0.197, flate2 1.0.28, brotli 3.5.0, ...
- 模块：main.rs, request.rs, response.rs, config.rs, cache.rs, param.rs, util.rs, exception.rs
- 支持的 HTTP 方法：GET, HEAD, OPTIONS（代码依据：param.rs 中 ALLOWED_METHODS）
- 压缩算法：Gzip, Deflate, Brotli（代码依据：response.rs 中 compress 逻辑）
- 缓存策略：FIFO（代码依据：cache.rs 中 FileCache 实现）
- ...

每一条事实必须标注代码依据（文件名 + 具体位置）。

Step 3: 严格事实约束规则

以下规则在 Project-Aware Mode 下为强制执行，违反任何一条都是不可接受的：

Step 4: 代码片段引用规范

PPT 中展示代码时：

1. 必须从实际源码中提取 — 可以精简（删除非关键行），但不能改变逻辑
2. 标注来源 — 在代码块上方或旁边说明来自哪个文件
3. 精简规则 — 提取核心逻辑，删除 import、日志、注释等非关键行，控制在 8 行以内（两栏）或 10 行以内（单栏）
4. 禁止凭空编写 — 不得为了"演示效果"编写项目中不存在的代码

无工程目录时的行为

如果 PPT 工作目录下没有检测到任何工程项目文件夹，则按照用户提供的文字描述正常生成 PPT，不受上述约束。

Quick Start

1. YAML Front Matter（必须）

---
marp: true
size: 16:9
theme: am_red          # 可选: am_red, am_blue, am_green, am_purple, am_brown, am_dark
paginate: true
headingDivider: [2,3]  # 二级/三级标题自动分页
footer: \ *作者名* *班级* *日期*
---

2. 基础结构

封面页 (cover_e)
  ↓
目录页 (toc_b)
  ↓
[章节过渡页 (trans) → 内容页 (navbar + 布局)] × N
  ↓
结束页 (lastpage)

Page Types Reference

封面页

cover_e 示例（推荐）：

<!-- _class: cover_e -->
<!-- _paginate: "" -->
<!-- _footer: ![](../hfut-badge/HFUT_Horizontal_name&badge_white.png) -->
<!-- _header: ![](../hfut-badge/HFUT_badge_white.png) -->

# 演示文稿标题

###### 副标题说明

汇报人：姓名
班级信息

目录页

<!-- _header: 目录<br>CONTENTS<br>![](../hfut-badge/HFUT_badge_white.png)-->
<!-- _class: toc_b -->
<!-- _footer: "" -->
<!-- _paginate: "" -->

- [第一章标题](#页码)
- [第二章标题](#页码)
- [第三章标题](#页码)

章节过渡页

## 1. 章节标题

<!-- _class: trans -->
<!-- _footer: "" -->
<!-- _paginate: "" -->

内容页（navbar + 布局）

## 1.1 小节标题
<!-- _header: \ ***文档标题*** **当前章节** *其他章节* *其他章节*-->
<!-- _class: navbar cols-2 fglass -->

<div class=ldiv>
左栏内容
</div>

<div class=rdiv>
右栏内容
</div>

导航栏语法： ***粗斜体*** 文档标题 | **粗体** 当前章节 | *斜体* 其他章节

结束页

<!-- _class: lastpage -->
<!-- _footer: "" -->
![ ](../hfut-badge/HFUT_Horizontal_name&badge.svg)
###### 感谢观看！

Layout Classes

两栏布局

其他布局

布局选择原则：

• pin-3 要求三个区域都有充足内容（每区至少 3-4 行文字），否则大量留白很丑
• 内容较少时优先用 cols-2 或 cols2_ol_ci
• timg 不要只放一行标题——应放实质性内容（完整段落、带详细说明的引用块）
• 总结/展望类页面通常内容偏少，优先选 cols-2 fglass 而非 pin-3

div 后缀说明：

• ldiv/rdiv/mdiv/tdiv/bdiv: 普通容器
• limg/rimg/mimg/timg/bimg: 内容居中（适合图片）

Style Classes

列表样式（可叠加）

引用框颜色

字体大小

其他样式

Image Syntax

![](img.png)              # 普通图片
![#c](img.png)            # 居中
![w:500](img.png)         # 宽度500px
![h:300](img.png)         # 高度300px
![#c w:500](img.png)      # 居中+宽度
![#c h:400](img.png)      # 居中+高度

图片占位符（重要）

生成 PPT 时图片往往还不存在，使用占位符模式：

## 小节标题
<!-- _class: navbar caption -->

<div class=rimg>

<!-- TODO: 替换为实际图片 img/architecture.png -->
![#c h:400](img/placeholder.png)

<div class="caption">
图1：系统架构图
</div>

</div>

占位符规范：

• 使用 <!-- TODO: 替换为实际图片 img/xxx.png --> 注释标记
• 图片路径使用有意义的名称（如 architecture.png）
• 必须写好 caption，说明图片内容
• 用户后续只需替换图片文件，无需改代码

图表标题（关键）：

• 必须在 _class 中加 caption 才能渲染 <div class="caption"> 的样式
• 例如 <!-- _class: navbar cols-2 fglass caption -->

<!-- _class: navbar caption -->

![#c h:400](img/diagram.png)

<div class="caption">
图1：系统架构图
</div>

单页内容上限（必读）

Marp 不会自动分页。内容超出页面会被裁切并覆盖脚注。必须严格控制每页内容量。

每页最大内容量

行数计算：标题行 + 列表项数 + 表格行数(含表头) + 代码行数 + 引用行数 = 总行数

硬性禁止

• 同一页面或同一栏禁止放两个表格 — 几乎 100% 溢出
• 两栏代码禁止超过 8 行 — 超出必须精简或拆页
• 单栏代码禁止超过 10 行 — 超出必须精简或拆页

超出时如何拆页

将一页拆为两页，保持同一小节编号，用短横线加子标题区分：

## 3.2 Neo4j 存储 - 数据模型    ← 第一页
## 3.2 Neo4j 存储 - 查询示例    ← 第二页

写完每页必须验证

每写完一页，立即执行以下检查：

1. 数总行数（标题 + 列表 + 表格 + 代码 + 引用）
2. 单栏 > 10 行 → 必须拆页
3. 两栏任一栏 > 8 行 → 必须拆页
4. 出现两个表格 → 必须拆页
5. 宁可多一页留白，也不要少一页溢出

Best Practices

图片工作流（重要）

先写结构，后加图片：

1. 生成阶段 — 使用占位符 <!-- TODO: 替换为实际图片 --> + 写好 caption
2. 用户准备图片 — 根据 caption 说明准备对应图片
3. 替换阶段 — 将图片放入 img/ 文件夹，删除 TODO 注释

图片数量要求：

• 一份 20+ 页的 PPT 至少包含 5-6 张图片占位符
• 适合放图的位置：整体架构图、数据流/流程图、实验结果图、系统截图/演示图、对比可视化图
• 图片页通常用 cols-2-64 caption 或单栏 caption 布局，图片放在 rimg 或独立居中

为什么这样做：

• 纯文字 PPT 信息密度高但视觉单调，图片提升表达力
• 生成时图片通常不存在，用占位符标记
• caption 先写好确保图片内容明确
• 用户只需替换文件，不需要改代码

页面组织

1. 每章开头用 trans 过渡页 — 给观众清晰的章节切换信号
2. navbar 保持一致 — 同一章节内用相同的 header 导航
3. 合理使用 fglass — 列表内容配合毛玻璃效果更美观

内容布局

1. 图文并排用 cols-2-64 或 cols-2-46 — 文字多的一侧占大比例
2. 代码展示用 cols-2 — 左边代码，右边效果图/说明
3. 步骤说明用 col1_ol_ci + fglass — 有序列表+圆形序号
4. 对比内容用表格 — 清晰展示差异
5. 总结/展望页用 cols-2 fglass 或 cols2_ol_ci — 不要用 pin-3（内容通常不够填满三区域）
6. 引用框放实质内容 — > 引用块应包含总结性段落或详细说明，不要只写一行标题标签
7. 表格、列表、代码必须放 ldiv/rdiv，禁止放 limg/rimg — limg/rimg 使用 flexbox 居中，会压缩表格宽度导致列被截断；limg/rimg 仅用于图片
8. 两栏高度尽量平衡 — 若一栏内容明显少于另一栏，在较短一栏补充引用块（>）或额外说明文字，避免底部大片留白

内容密度

1. 每个 div 区域至少 3-4 行实质内容 — 太少则留白过多，显得空洞
2. 列表项用"粗体关键词+冒号+说明"格式 — 如 **知识蒸馏**：压缩模型体积，降低推理延迟
3. 避免裸列表 — 只写三五个短词条的列表看起来很单薄，补充解释或加引用块充实内容
4. 内容上限和拆页规则 — 见上方「单页内容上限」章节，每页写完必须验证行数

技术内容

1. 代码块指定语言 — ```verilog ```python 等
2. 关键代码配合说明 — 先文字解释，再代码展示
3. 波形/架构图配 caption — 标注图号和说明

信息密度

1. 每页一个核心观点 — 不要堆砌信息
2. 超过5条用两列布局 — cols2_ol_ci 或 cols2_ul_ci
3. 文字过多用 tinytext/smalltext — 保持可读性

Template: Academic Defense

---
marp: true
size: 16:9
theme: am_red
paginate: true
headingDivider: [2,3]
footer: \ *姓名* *班级* *日期*
---

<!-- _class: cover_e -->
<!-- _paginate: "" -->
<!-- _footer: ![](../hfut-badge/HFUT_Horizontal_name&badge_white.png) -->
<!-- _header: ![](../hfut-badge/HFUT_badge_white.png) -->

# 论文/项目标题

###### 副标题（课程名称/竞赛名称）

汇报人：姓名
指导老师：老师姓名

---

<!-- _header: 目录<br>CONTENTS<br>![](../hfut-badge/HFUT_badge_white.png)-->
<!-- _class: toc_b -->
<!-- _footer: "" -->
<!-- _paginate: "" -->

- [研究背景](#3)
- [方案设计](#N)
- [实现细节](#N)
- [实验验证](#N)
- [总结展望](#N)

## 1. 研究背景

<!-- _class: trans -->
<!-- _footer: "" -->
<!-- _paginate: "" -->

## 1.1 问题描述
<!-- _header: \ ***答辩标题*** **研究背景** *方案设计* *实现细节* *实验验证* *总结*-->
<!-- _class: navbar cols-2 fglass -->

<div class=ldiv>

**背景说明**

- 要点1
- 要点2
- 要点3

</div>

<div class=rimg>

<!-- TODO: 替换为实际图片 img/background.png -->
![#c h:400](img/background.png)

<div class="caption">
图1：问题示意图
</div>

</div>

<!-- 更多内容页... -->

## N. 未来展望
<!-- _header: \ ***答辩标题*** *研究背景* *方案设计* *实现细节* *实验验证* **总结**-->
<!-- _class: navbar cols-2 fglass bq-blue -->

<div class=ldiv>

**方向一标题**

- **关键词A**：具体说明，解释做什么、为什么
- **关键词B**：具体说明
- **关键词C**：具体说明

> 小结或目标说明

</div>

<div class=rdiv>

**方向二标题**

- **关键词D**：具体说明
- **关键词E**：具体说明
- **关键词F**：具体说明

> 小结或目标说明

</div>

---

<!-- _class: lastpage -->
<!-- _footer: "" -->
![ ](../hfut-badge/HFUT_Horizontal_name&badge.svg)
###### 感谢观看！

Common Mistakes

File Organization

your-ppt/
├── hfut-awesome-marp.md    # 主文件
├── img/                     # 图片文件夹
│   ├── architecture.png
│   ├── result1.png
│   └── ...
└── your-project/            # [可选] 工程项目文件夹
    ├── Cargo.toml / package.json / ...
    ├── src/
    └── ...

图片命名建议： 使用有意义的名称如 architecture.png、workflow.png，而非 image1.png

工程目录说明： 如果用户在 PPT 目录下放入了工程项目文件夹，自动进入 Project-Aware Mode（见上方「工程目录分析」章节）